7.4 KiB
ctx.tasks
TaskService — provided by @deepseek-ai/dsh-tasks.
The tasks service: the runtime-global background task registry. See the module doc for the ownership, isolation, and lifecycle contracts.
ctx.tasks.start(spec)
/**
* Preflight access, validation, and owner cleanup before starting and
* atomically registering work. A throwing starter leaves nothing registered;
* after it returns, registration cannot fail. Settlement records the outcome,
* notifies listeners, and releases waiters.
* @param spec - task identity, owner, and synchronous starter.
* @returns the registry-issued `<kind>-N` id.
*/
start(spec: TaskStart): TaskId
Preflight access, validation, and owner cleanup before starting and atomically registering work. A throwing starter leaves nothing registered; after it returns, registration cannot fail. Settlement records the outcome, notifies listeners, and releases waiters.
spec— task identity, owner, and synchronous starter.
Returns the registry-issued <kind>-N id.
ctx.tasks.list(caller?)
/**
* List caller-owned and unowned tasks in registration order without exposing
* another session's labels.
* @param caller - reading agent; a non-agent caller sees only unowned tasks.
* @returns fresh snapshots.
*/
list(caller?: Agent): TaskSnapshot[]
List caller-owned and unowned tasks in registration order without exposing another session's labels.
caller— reading agent; a non-agent caller sees only unowned tasks.
Returns fresh snapshots.
ctx.tasks.get(id, caller?)
/**
* Return a non-consuming snapshot without changing its read cursor or notice
* state. Throws for an unknown or foreign task.
* @param id - task to look up.
* @param caller - reading agent checked against the owner.
* @returns a fresh snapshot.
*/
get(id: TaskId, caller?: Agent): TaskSnapshot
Return a non-consuming snapshot without changing its read cursor or notice state. Throws for an unknown or foreign task.
id— task to look up.caller— reading agent checked against the owner.
Returns a fresh snapshot.
ctx.tasks.read(id, caller?)
/**
* Read the next stream delta, or the idempotent final output after settlement.
* A terminal read marks the task reported. Throws for an unknown or foreign
* task.
* @param id - task to read.
* @param caller - reading agent checked against the owner.
* @returns output text and the post-read snapshot.
*/
read(id: TaskId, caller?: Agent): TaskRead
Read the next stream delta, or the idempotent final output after settlement. A terminal read marks the task reported. Throws for an unknown or foreign task.
id— task to read.caller— reading agent checked against the owner.
Returns output text and the post-read snapshot.
ctx.tasks.kill(id, caller?, reason?)
/**
* Request cancellation, then mark the task stopping and reported. A producer
* throw propagates without changing task state. Throws for an unknown or
* foreign task.
* @param id - task to cancel.
* @param caller - killing agent checked against the owner.
* @param reason - logged reason forwarded to the producer.
* @returns `requested` for live work, otherwise `already-finished`.
*/
kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-finished'
Request cancellation, then mark the task stopping and reported. A producer throw propagates without changing task state. Throws for an unknown or foreign task.
id— task to cancel.caller— killing agent checked against the owner.reason— logged reason forwarded to the producer.
Returns requested for live work, otherwise already-finished.
ctx.tasks.wait(id, timeoutMs, caller?, signal?)
/**
* Wait for settlement or timeout without cancelling the task. Caller abort
* rejects only while the task is live; after settlement it returns the
* terminal snapshot so a notice suppressed for this waiter is still delivered.
* Timed-out and aborted waits detach their resolvers. Throws for invalid,
* unknown, or foreign input.
* @param id - task to wait for.
* @param timeoutMs - positive finite wait bound in milliseconds.
* @param caller - waiting agent checked against the owner.
* @param signal - optional cancellation of the wait itself.
* @returns snapshot at settlement or timeout.
*/
async wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>
Wait for settlement or timeout without cancelling the task. Caller abort rejects only while the task is live; after settlement it returns the terminal snapshot so a notice suppressed for this waiter is still delivered. Timed-out and aborted waits detach their resolvers. Throws for invalid, unknown, or foreign input.
id— task to wait for.timeoutMs— positive finite wait bound in milliseconds.caller— waiting agent checked against the owner.signal— optional cancellation of the wait itself.
Returns snapshot at settlement or timeout.
ctx.tasks.onTaskDone(listener)
/**
* Register an effect-scoped completion listener. Each listener is contained;
* returned promises are observed but not awaited. No listener runs after
* service disposal.
* @param listener - receives each terminal snapshot and its exact owner.
* @returns disposer that unregisters the listener.
*/
onTaskDone(listener: TaskDoneListener): () => void
Register an effect-scoped completion listener. Each listener is contained; returned promises are observed but not awaited. No listener runs after service disposal.
listener— receives each terminal snapshot and its exact owner.
Returns disposer that unregisters the listener.
ctx.tasks.attachSurface(name)
/**
* Attach an effect-scoped surface that can read and stop tasks. {@link start}
* refuses work while none is attached.
* @param name - diagnostic label; duplicate names remain independent.
* @returns disposer that detaches this surface.
*/
attachSurface(name: string): () => void
Attach an effect-scoped surface that can read and stop tasks. start refuses work while none is attached.
name— diagnostic label; duplicate names remain independent.
Returns disposer that detaches this surface.