deepseek-harness/website/zh-CN/api/harness/tasks.md

<!-- Generated by scripts/gen-website-api.ts — do not edit by hand. Run `pnpm run gen-website-api` to regenerate. -->

# 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
/**
 * 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.

[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-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.

[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
/**
 * 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.

[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 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.

[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
/**
 * 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`.

[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
/**
 * 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.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/tasks/tasks/src/index.ts#L226)

### ctx.tasks.onTaskDone(listener)

```ts website-api
/**
 * 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.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/tasks/tasks/src/index.ts#L283)

### ctx.tasks.attachSurface(name)

```ts website-api
/**
 * 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.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/tasks/tasks/src/index.ts#L297)