tasks.md 4.7 KB
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)
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?: 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?)
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(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?)
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?)
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)
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)
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.