mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
2cde2a9032
Conflict resolution notes: - package.json/run-gates: both sides' new doc-sync gates kept (master's scoped-events/readme gates + this branch's website-api/website-yaml); js-yaml devDeps deduped (master added them independently). - pnpm-workspace/knip: website AND python/sdk-runtime entries kept. - doc-typecheck/verify-type-equiv: master's condensed headers kept, website glob retained in both scan scopes. - vendor/cordis/src/fiber.ts: master's lifecycle-hardening code taken; this branch's richer FiberState JSDoc reapplied on top. vendor/README.md logs both local modifications (hardening = 6, JSDoc enrichment = 7). - pnpm-lock: regenerated from master's side (pnpm install). Post-merge sync the gates forced (the system working as designed): - verify-website-yaml caught 4 stale plugin names from master's package reorg (dsh-stdio-agent -> dsh-stdio-demo, dsh-acp-agent -> dsh-acp-demo); 8 references fixed across guide/ and develop/. - gen-website-api picked up master's 6 new services automatically (ctx.approval/permission/sandbox/sessionQuery/skills/tasks -> 6 new pages + sidebar); api/index.md hub updated to list them. - AGENTS.md budget ceiling 1370 -> 1400: the website rows (layout line + two command lines) and master's own growth collided with the old ceiling; all three website rows are load-bearing (new top-level dir, new CI command).
129 lines
4.7 KiB
Markdown
129 lines
4.7 KiB
Markdown
<!-- 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
|
|
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?: 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<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
|
|
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)
|