# 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. [Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/tasks/tasks/src/index.ts#L76) ### ctx.tasks.start(spec) ```ts website-api 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 `-N` id. [Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/tasks/tasks/src/index.ts#L101) ### ctx.tasks.list(caller?) ```ts website-api 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. [Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/tasks/tasks/src/index.ts#L153) ### ctx.tasks.get(id, caller?) ```ts website-api 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. [Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/tasks/tasks/src/index.ts#L167) ### ctx.tasks.read(id, caller?) ```ts website-api 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. [Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/tasks/tasks/src/index.ts#L181) ### ctx.tasks.kill(id, caller?, reason?) ```ts website-api 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`. [Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/tasks/tasks/src/index.ts#L200) ### ctx.tasks.wait(id, timeoutMs, caller?, signal?) ```ts website-api async wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise ``` 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. [Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/tasks/tasks/src/index.ts#L226) ### ctx.tasks.onTaskDone(listener) ```ts website-api 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. [Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/tasks/tasks/src/index.ts#L283) ### ctx.tasks.attachSurface(name) ```ts website-api 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. [Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/tasks/tasks/src/index.ts#L297)