diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
index 0b901fcf92..313d687b49 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
@@ -19,7 +19,7 @@ The `tasks/` package group owns background-task semantics:
Long-running tools are producers. `dsh-tool-bash` adapts a `BashProcess` into incremental output and process cancellation; `dsh-tool-subagent` adapts a child run into final output and child disposal. The execution seams remain independent of sessions and the task registry.
-`TaskService` is a concrete, process-local service. TODO(task-service-backend): separate its public contract from the implementation when a second backend defines the required lifecycle; a systemd-backed runtime is one plausible driver, but this PR does not speculate about its durability, reconnect, ownership, or observation semantics.
+`TaskService` is the abstract seam in `@deepseek-ai/dsh-tasks`; the process-local registry is `LocalTaskService` in `@deepseek-ai/dsh-tasks-local` (the [task-registry seam Agent Note](2026-07-26-task-registry-seam.md) records that split).
## Runtime contract
@@ -103,7 +103,7 @@ Separate bash and subagent output/stop tools duplicate ids, isolation, cleanup,
### An immediate abstract task-runtime backend
-The current `TaskStart.run()` contract passes in-process callbacks and exact `Agent` objects. A durable backend changes identity, restart, ownership, and observation semantics, so extracting an interface before a second implementation exists would freeze the wrong boundary.
+The current `TaskStart.run()` contract passes in-process callbacks and exact `Agent` objects. A durable backend changes identity, restart, ownership, and observation semantics, so at introduction time the registry stayed one concrete service rather than freezing the wrong boundary. The [task-registry seam Agent Note](2026-07-26-task-registry-seam.md) later separated the contract from the process-local implementation without changing these in-process semantics.
### Consumer-owned authorization or cleanup events
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
index e2860e3a91..39900e24ba 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
@@ -19,7 +19,7 @@ Status: implemented
长时间运行工具是生产方。`dsh-tool-bash` 将 `BashProcess` 适配为增量输出与进程取消；`dsh-tool-subagent` 将子运行适配为最终输出与子运行释放。执行 seam 保持独立，不依赖会话或任务注册表。
-`TaskService` 是一个具体的进程内服务。TODO(task-service-backend)：当第二个后端明确所需生命周期后，将其公共契约与实现分离；systemd 驱动的运行时是一种可能方案，但本 PR（Pull Request）不臆测其持久性、重连、所有权或观察语义。
+`TaskService` 是 `@deepseek-ai/dsh-tasks` 中的抽象 seam；进程内注册表是 `@deepseek-ai/dsh-tasks-local` 中的 `LocalTaskService`（该拆分记录在[任务注册表 seam Agent Note](2026-07-26-task-registry-seam.zh.md)中）。
## 运行时契约
@@ -103,7 +103,7 @@ bash seam 暴露 `resolve`、`run` 和 `start`。`start(spec)` 返回一个 `Bas
### 立即抽象任务运行时后端
-当前 `TaskStart.run()` 契约传入进程内回调与确切的 `Agent` 对象。持久化后端会改变身份、重启、所有权与观察语义，因此在第二种实现出现前抽取接口，会固化错误的边界。
+当前 `TaskStart.run()` 契约传入进程内回调与确切的 `Agent` 对象。持久化后端会改变身份、重启、所有权与观察语义，因此在引入之时注册表保持为单一具体服务，而非固化错误的边界。[任务注册表 seam Agent Note](2026-07-26-task-registry-seam.zh.md)后来在不改变这些进程内语义的前提下，将契约与进程内实现分离。
### 由消费方负责授权或清理事件
diff --git a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md
new file mode 100644
index 0000000000..b785eb75a6
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md
@@ -0,0 +1,35 @@
+# Agent Note: The task registry is a capability seam (`dsh-tasks` / `dsh-tasks-local`)
+
+Status: implemented
+
+English | [中文](2026-07-26-task-registry-seam.zh.md)
+
+## Problem
+
+The [background-task runtime](2026-06-20-generic-long-running-tool-runtime.md) shipped `TaskService` as one concrete package: `@deepseek-ai/dsh-tasks` owned both the `ctx.tasks` contract every producer and control surface programs against and the process-local implementation (the in-memory store, settlement bookkeeping, owner-cleanup effects, teardown). That bundling recouples the two rates of change the repository's [capability-seam rule](2026-06-13-capability-seams.md) separates: swapping the registry's storage or lifecycle backend would churn the same package whose types and `ctx.tasks` surface producers (`dsh-tool-bash`, `dsh-tool-pty`, `dsh-tool-subagent`), the control surface (`dsh-tool-tasks`), and `TaskKindMap` extenders import. Every other swappable capability in the harness — bash, pty, fs, skill, subagent, web, session persistence — already carries the interface / implementation / consumer split; the task registry was the remaining `core`-mode exception, guarded only by a `TODO(task-service-backend)` comment.
+
+## Decision
+
+`tasks/` is now a three-package capability family in the bash-trio shape:
+
+- **`@deepseek-ai/dsh-tasks` (interface)** — the abstract `TaskService extends Service` owning `ctx.tasks`, the eight-method contract (`start`, `list`, `get`, `read`, `kill`, `wait`, `onTaskDone`, `attachSurface`), all vocabulary types (`TaskId`, `TaskKindMap`, `TaskStart`, `TaskHooks`, `TaskOutcome`, `TaskSnapshot`, `TaskRead`, `TaskDoneListener`), and the snapshot invariant companion. The class-level JSDoc states the semantics every implementation owes: registrations outlive producer and surface fibers, owned access is session-fenced, settlement is first-wins with contained listeners, and `start` refuses work while no control surface is attached.
+- **`@deepseek-ai/dsh-tasks-local` (implementation)** — `LocalTaskService`, the process-local registry moved verbatim: the in-memory store, per-kind counters, waiter bookkeeping, `TASK_WAIT_TIMEOUT` deadline code, owner-cleanup effects, and force-fail teardown. The `dsh-timeout` dependency moves here with it; the seam has no implementation dependencies.
+- **`@deepseek-ai/dsh-tool-tasks` (consumer)** — unchanged; it injects `'tasks'` and never imports implementation types.
+
+Compositions load `dsh-tasks-local` where they previously loaded `dsh-tasks` (the CLI cordis.yml row, `agent-spine-demo`, test harnesses, the tool-catalog generator boot). Producer misconfiguration diagnostics ("background tasks unavailable: load …") name `dsh-tasks-local` because a deployment fixes them by loading the implementation, not the interface. Producers, `TaskKindMap` declaration merges, and the control surface keep importing `@deepseek-ai/dsh-tasks` only.
+
+The seam keeps the in-process contract semantics unchanged: `TaskStart.run()` still passes callbacks and exact `Agent` objects, so a durable or cross-process backend still has design work to do before it can implement this interface (identity, restart, ownership, observation). The split moves that future work out of every consumer's dependency graph; it does not pre-design the backend.
+
+## Alternatives considered
+
+**Keep the concrete service until a second backend exists (status quo).** This was the original runtime note's position: extracting an interface before a second implementation risks freezing the wrong boundary. It lost because the boundary is no longer speculative — the eight service methods and their semantics have been stable across every producer integration since introduction, they are exactly the surface `dsh-tool-tasks` and the producers already program against, and the repository convention treats swappable capabilities as three packages by default. The residual risk (a durable backend needing contract changes) is unchanged by the split: those changes would land in the seam package either way, and today they would also churn every consumer's implementation dependency.
+
+**Interface-only extraction inside one package (export an abstract class beside the concrete one).** Rejected because it separates nothing operationally: consumers still depend on the package that carries the implementation and its dependencies, and a replacement backend still cannot ship without the local one in its graph. The package boundary is the unit of independent evolution here.
+
+**Splitting `types.ts` out but leaving the service concrete.** Rejected for the same reason — the types are not the seam; `ctx.tasks` and its method contract are. Producers need the service key and semantics, not just the shapes.
+
+## Consequences
+
+Bought: the task registry now matches the repository-wide seam shape; a durable, remote, or instrumented registry is a sibling package implementing eight abstract methods, and no producer, control surface, or `TaskKindMap` extender changes when one lands. The seam README states the contract; the implementation README owns the lifecycle bookkeeping facts. The registry behavior suite (owner cleanup, settlement, waits, teardown) lives with `dsh-tasks-local`; the seam keeps a stub-subclass test pinning registration under `ctx.tasks` and single-service duplication behavior, plus the probe-based invariant suite.
+
+Cost: one more package (manifest, tsconfig, README, invariant companion), and compositions must name the implementation package — a boot that loads only `@deepseek-ai/dsh-tasks` gets a pending `ctx.tasks` and producers fail with the standard missing-service behavior rather than a bespoke message. The misconfiguration diagnostics naming `dsh-tasks-local` accept staleness if a different backend becomes the recommended default.
diff --git a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md
new file mode 100644
index 0000000000..aa4df43b82
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md
@@ -0,0 +1,35 @@
+# Agent Note: 任务注册表是一个能力 seam（`dsh-tasks` / `dsh-tasks-local`）
+
+Status: implemented
+
+[English](2026-07-26-task-registry-seam.md) | 中文
+
+## 问题
+
+[后台任务运行时](2026-06-20-generic-long-running-tool-runtime.md)交付时把 `TaskService` 做成了单个具体包（package）：`@deepseek-ai/dsh-tasks` 既拥有所有生产方和控制接口面向编程的 `ctx.tasks` 契约，也拥有进程内实现（内存存储、结算簿记、所有者清理 effect、拆除逻辑）。这种捆绑重新耦合了仓库[能力 seam 规则](2026-06-13-capability-seams.md)本要分离的两种变化速率：一旦替换注册表的存储或生命周期后端，被搅动的就是同一个包，而生产方（`dsh-tool-bash`、`dsh-tool-pty`、`dsh-tool-subagent`）、控制接口（`dsh-tool-tasks`）和 `TaskKindMap` 扩展方正是从这个包导入类型与 `ctx.tasks` 接口。harness 中其余每项可替换能力（bash、pty、fs、skill、subagent、web、会话持久化）都已具备接口／实现／消费方三分；任务注册表曾是仅剩的 `core` 模式例外，仅由一条 `TODO(task-service-backend)` 注释把守。
+
+## 决策
+
+`tasks/` 如今是一个 bash 三件套形态的三包能力家族：
+
+- **`@deepseek-ai/dsh-tasks`（接口）**——抽象的 `TaskService extends Service`，拥有 `ctx.tasks`、八个方法的契约（`start`、`list`、`get`、`read`、`kill`、`wait`、`onTaskDone`、`attachSurface`）、全部词汇类型（`TaskId`、`TaskKindMap`、`TaskStart`、`TaskHooks`、`TaskOutcome`、`TaskSnapshot`、`TaskRead`、`TaskDoneListener`），以及快照不变式配套插件。类级 JSDoc 陈述了每个实现都必须兑现的语义：注册的存续期长于生产方与控制接口的 fiber，有所有者的访问以会话为界，结算遵循首次结果优先且监听器错误被隔离，并且在没有附加任何控制接口时 `start` 拒绝启动工作。
+- **`@deepseek-ai/dsh-tasks-local`（实现）**——`LocalTaskService`，即原样迁移的进程内注册表：内存存储、按 kind 划分的计数器、等待方簿记、`TASK_WAIT_TIMEOUT` deadline 代码、所有者清理 effect，以及强制失败的拆除逻辑。`dsh-timeout` 依赖随之迁入此包；seam 包不含任何实现依赖。
+- **`@deepseek-ai/dsh-tool-tasks`（消费方）**——保持不变；它注入 `'tasks'`，从不导入实现类型。
+
+各组合配置在原先加载 `dsh-tasks` 的位置改为加载 `dsh-tasks-local`（CLI 的 cordis.yml 配置项、`agent-spine-demo`、各测试 harness、工具目录生成器的启动流程）。生产方的配置错误诊断信息（"background tasks unavailable: load …"）点名 `dsh-tasks-local`，因为部署方修复该问题的办法是加载实现包，而非接口包。生产方、`TaskKindMap` 声明合并和控制接口仍然只导入 `@deepseek-ai/dsh-tasks`。
+
+该 seam 保持进程内契约语义不变：`TaskStart.run()` 仍然传入回调和确切的 `Agent` 对象，因此持久化或跨进程后端在能实现此接口之前仍有设计工作要做（身份、重启、所有权、观察）。这次拆分把该项未来工作移出了每个消费方的依赖图；它并不预先设计后端。
+
+## 曾考虑的替代方案
+
+**在第二个后端出现之前保持具体服务（维持现状）。**这正是当初运行时 Agent Note 的立场：在第二种实现出现前抽取接口，可能固化错误的边界。该方案落选，因为这条边界已不再是臆测：八个服务方法及其语义自引入以来在每一次生产方集成中都保持稳定，它们正是 `dsh-tool-tasks` 与各生产方已经在面向编程的那套接口，而且仓库约定默认将可替换能力拆成三个包。剩余风险（持久化后端可能需要变更契约）不因这次拆分而改变：无论拆分与否，这类变更都会落在 seam 包里，而若维持合并包的现状，它们还会连带搅动每个消费方的实现依赖。
+
+**在单个包内仅抽取接口（在具体类旁导出一个抽象类）。**否决：它在运作层面并未分离任何东西。消费方依然依赖携带实现及其依赖项的那个包，而替换后端若不把本地实现纳入依赖图，就仍然无法发布。在这里，包边界才是独立演进的单位。
+
+**拆出 `types.ts` 但让服务保持具体。**基于同样的理由否决：类型并不是 seam，`ctx.tasks` 及其方法契约才是。生产方需要的是服务键和语义，而不只是类型形状。
+
+## 后果
+
+换来的是：任务注册表如今与全仓库统一的 seam 形态一致；持久化、远程或带插桩的注册表将是一个实现八个抽象方法的兄弟包，这样的后端落地时，任何生产方、控制接口或 `TaskKindMap` 扩展方都无需改动。seam 包的 README 陈述契约；实现包的 README 拥有生命周期簿记的相关事实。注册表行为测试套件（所有者清理、结算、等待、拆除）随 `dsh-tasks-local` 存放；seam 包保留一个基于桩子类的测试，固定 `ctx.tasks` 下的注册行为与单一服务的重复注册行为，外加基于探针的不变式测试套件。
+
+代价是：多出一个包，即多一份 manifest（元数据清单）、tsconfig、README 与不变式配套插件；同时各组合配置必须点名实现包。若某次启动只加载 `@deepseek-ai/dsh-tasks`，得到的将是挂起的 `ctx.tasks`，生产方将按标准的服务缺失行为失败，而不会得到一条专门定制的消息。若推荐的默认后端日后换成其他实现，点名 `dsh-tasks-local` 的配置错误诊断信息会随之陈旧；这一代价已被接受。
diff --git a/apps/cli/cordis.yml b/apps/cli/cordis.yml
index b89df77c46..1d5c37cff5 100644
--- a/apps/cli/cordis.yml
+++ b/apps/cli/cordis.yml
@@ -52,7 +52,7 @@
name: '@deepseek-ai/dsh-agent'
- id: tasks
- name: '@deepseek-ai/dsh-tasks'
+ name: '@deepseek-ai/dsh-tasks-local'
- id: agent-loop
name: '@deepseek-ai/dsh-agent-loop'
diff --git a/apps/cli/package.json b/apps/cli/package.json
index 8799669e8d..4f3bb5be35 100644
--- a/apps/cli/package.json
+++ b/apps/cli/package.json
@@ -57,7 +57,7 @@
"@deepseek-ai/dsh-subagent-fork": "workspace:^",
"@deepseek-ai/dsh-subagent-spawn": "workspace:^",
"@deepseek-ai/dsh-system-prompt": "workspace:^",
- "@deepseek-ai/dsh-tasks": "workspace:^",
+ "@deepseek-ai/dsh-tasks-local": "workspace:^",
"@deepseek-ai/dsh-timeout-policy": "workspace:^",
"@deepseek-ai/dsh-token-meter": "workspace:^",
"@deepseek-ai/dsh-tool-bash": "workspace:^",
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index 0f2dfd1610..2da9652c59 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -117,6 +117,7 @@ flowchart LR
pkg_tool_ralph["tool-ralph"]
pkg_tasks["tasks"]
svc_tasks["ctx.tasks
Background task registry"]
+ pkg_tasks_local["tasks-local"]
pkg_tool_tasks["tool-tasks"]
pkg_web["web"]
svc_web["ctx.web
Web access provider registry"]
@@ -192,6 +193,7 @@ flowchart LR
pkg_subagent_spawn --> svc_subagents
pkg_system_prompt --> svc_systemPrompt
pkg_tasks --> svc_tasks
+ pkg_tasks_local --> svc_tasks
pkg_token_meter --> svc_tokenMeter
pkg_tool_bash --> svc_bashEnv
pkg_tools --> svc_tools
@@ -326,7 +328,7 @@ flowchart LR
| `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-policy contributes observed-state checks through the fs/* event gate. |
| `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend consumes post-step pressure and request-error recovery events; a model-facing compact tool remains deferred. |
| `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-ralph`](../packages/workflow/tool-ralph) | - | Providers implement transports; tool-subagent exposes configured delegation while tool-ralph requires one fresh structured-output route. |
-| `ctx.tasks` | `core` | [`tasks`](../packages/tasks/tasks) | - | [`tool-bash`](../packages/bash/tool-bash), [`tool-pty`](../packages/pty/tool-pty), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-tasks`](../packages/tasks/tool-tasks) | - | Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it. |
+| `ctx.tasks` | `seam` | [`tasks`](../packages/tasks/tasks) | [`tasks-local`](../packages/tasks/tasks-local) | [`tool-bash`](../packages/bash/tool-bash), [`tool-pty`](../packages/pty/tool-pty), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-tasks`](../packages/tasks/tool-tasks) | - | Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it; tasks-local is the process-local registry. |
| `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-local`](../packages/web/web-fetch-local) | [`tool-web`](../packages/web/tool-web) | - | Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names. |
| `ctx.spillStore` | `seam` | [`spill`](../packages/spill/spill) | [`spill-local`](../packages/spill/spill-local) | [`spill-policy`](../packages/spill/spill-policy) | - | The backend saves oversized tool text and returns a model-facing locator plus retrieval hint; spill-policy is the tools/post-execute consumer that decides when to spill. |
| `ctx.httpServer` | `core` | `webserver` | - | `connection`, `modules`, `hmr` | - | Plain node:http carrier: named-route registry, index transform taps, and the static dist fallback; web-transport plugins register their own routes. |
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 86331cf22a..d794425e10 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -2058,7 +2058,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
- `@deepseek-ai/dsh-session-checkpoint-policy` — requires `llm` · `sessionPersistence` · `sessions` · `tools` ([`packages/session-persistence/session-checkpoint-policy/src/index.ts`](../packages/session-persistence/session-checkpoint-policy/src/index.ts))
- `@deepseek-ai/dsh-storage` ([`packages/storage/storage/src/index.ts`](../packages/storage/storage/src/index.ts))
- `@deepseek-ai/dsh-subagent` ([`packages/subagent/subagent/src/index.ts`](../packages/subagent/subagent/src/index.ts))
-- `@deepseek-ai/dsh-tasks` ([`packages/tasks/tasks/src/index.ts`](../packages/tasks/tasks/src/index.ts))
+- `@deepseek-ai/dsh-tasks-local` ([`packages/tasks/tasks-local/src/index.ts`](../packages/tasks/tasks-local/src/index.ts))
- `@deepseek-ai/dsh-timeout-policy` — requires `tools` ([`packages/timeout/timeout-policy/src/index.ts`](../packages/timeout/timeout-policy/src/index.ts))
- `@deepseek-ai/dsh-tool-ask-user` — requires `tools` · `userInteraction` ([`packages/ui/tool-ask-user/src/index.ts`](../packages/ui/tool-ask-user/src/index.ts))
- `@deepseek-ai/dsh-tool-todo` — requires `tools` ([`packages/todo/tool-todo/src/index.ts`](../packages/todo/tool-todo/src/index.ts))
@@ -2077,6 +2077,7 @@ Abstract service classes — a deployment loads a concrete implementation packag
- `@deepseek-ai/dsh-session-persistence` — abstract `SessionPersistence` ([`packages/session-persistence/session-persistence/src/index.ts`](../packages/session-persistence/session-persistence/src/index.ts))
- `@deepseek-ai/dsh-session-query` — abstract `SessionQueryService` ([`packages/session-query/session-query/src/index.ts`](../packages/session-query/session-query/src/index.ts))
- `@deepseek-ai/dsh-spill` — abstract `SpillStore` ([`packages/spill/spill/src/index.ts`](../packages/spill/spill/src/index.ts))
+- `@deepseek-ai/dsh-tasks` — abstract `TaskService` ([`packages/tasks/tasks/src/index.ts`](../packages/tasks/tasks/src/index.ts))
- `@deepseek-ai/dsh-workflow` — abstract `WorkflowService` ([`packages/workflow/workflow/src/index.ts`](../packages/workflow/workflow/src/index.ts))
## Library packages (no plugin entry)
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 4d310a6690..e14d28564a 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -1607,9 +1607,16 @@ Types: [AssembleContext](../core-data-structures/system-prompt.md) · [PromptSec
Source: [`packages/core/system-prompt/src/index.ts:246`](../../packages/core/system-prompt/src/index.ts)
-## `ctx.tasks` — `TaskService`
+## `ctx.tasks` — `TaskService` (abstract seam)
-The `tasks` service: the runtime-global background task registry. See the module doc for the ownership, isolation, and lifecycle contracts.
+Abstract background task registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.tasks` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+
+Implementations must honor these semantics:
+
+- Registrations outlive producer and control-surface fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record.
+- Owned-task access is fenced by the owner's session id. Ids are predictable, so authorization — not secrecy — is the boundary.
+- Settlement is first-wins: one terminal record, one round of contained listener notification, and released waiters, even against a late producer outcome.
+- start refuses work while no control surface is attached, so a producer cannot start work that callers cannot collect or stop.
```ts cordis-catalog
/**
@@ -1620,7 +1627,7 @@ The `tasks` service: the runtime-global background task registry. See the module
* @param spec - task identity, owner, and synchronous starter.
* @returns the registry-issued `-N` id.
*/
-start(spec: TaskStart): TaskId
+abstract start(spec: TaskStart): TaskId
/**
* List caller-owned and unowned tasks in registration order without exposing
@@ -1628,7 +1635,7 @@ start(spec: TaskStart): TaskId
* @param caller - reading agent; a non-agent caller sees only unowned tasks.
* @returns fresh snapshots.
*/
-list(caller?: Agent): TaskSnapshot[]
+abstract list(caller?: Agent): TaskSnapshot[]
/**
* Return a non-consuming snapshot without changing its read cursor or notice
@@ -1637,7 +1644,7 @@ list(caller?: Agent): TaskSnapshot[]
* @param caller - reading agent checked against the owner.
* @returns a fresh snapshot.
*/
-get(id: TaskId, caller?: Agent): TaskSnapshot
+abstract get(id: TaskId, caller?: Agent): TaskSnapshot
/**
* Read the next stream delta, or the idempotent final output after settlement.
@@ -1647,7 +1654,7 @@ get(id: TaskId, caller?: Agent): TaskSnapshot
* @param caller - reading agent checked against the owner.
* @returns output text and the post-read snapshot.
*/
-read(id: TaskId, caller?: Agent): TaskRead
+abstract read(id: TaskId, caller?: Agent): TaskRead
/**
* Request cancellation, then mark the task stopping and reported. A producer
@@ -1658,21 +1665,20 @@ read(id: TaskId, caller?: Agent): TaskRead
* @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'
+abstract kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-finished'
/**
* 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.
+ * rejects only while the task is live; after settlement the terminal
+ * snapshot wins so a notice suppressed for this waiter is still delivered.
+ * 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
+abstract wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise
/**
* Register an effect-scoped completion listener. Each listener is contained;
@@ -1681,7 +1687,7 @@ async wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal):
* @param listener - receives each terminal snapshot and its exact owner.
* @returns disposer that unregisters the listener.
*/
-onTaskDone(listener: TaskDoneListener): () => void
+abstract onTaskDone(listener: TaskDoneListener): () => void
/**
* Attach an effect-scoped surface that can read and stop tasks. {@link start}
@@ -1689,12 +1695,12 @@ onTaskDone(listener: TaskDoneListener): () => void
* @param name - diagnostic label; duplicate names remain independent.
* @returns disposer that detaches this surface.
*/
-attachSurface(name: string): () => void
+abstract attachSurface(name: string): () => void
```
Types: [Agent](../core-data-structures/core.md) · [TaskDoneListener](../core-data-structures/tasks.md) · [TaskId](../core-data-structures/tasks.md) · [TaskRead](../core-data-structures/tasks.md) · [TaskSnapshot](../core-data-structures/tasks.md) · [TaskStart](../core-data-structures/tasks.md)
-Source: [`packages/tasks/tasks/src/index.ts:77`](../../packages/tasks/tasks/src/index.ts)
+Source: [`packages/tasks/tasks/src/index.ts:50`](../../packages/tasks/tasks/src/index.ts)
## `ctx.tokenMeter` — `TokenMeterService`
diff --git a/docs/core-data-structures/tasks.md b/docs/core-data-structures/tasks.md
index 2c7555b84d..8d7050be1b 100644
--- a/docs/core-data-structures/tasks.md
+++ b/docs/core-data-structures/tasks.md
@@ -149,4 +149,4 @@ interface TaskRead {
## Service behavior
-[`TaskService`](../../packages/tasks/tasks/src/index.ts) provides atomic `start`, caller-scoped `get` and `list`, `read`, `kill`, bounded `wait`, contained `onTaskDone` listeners, and the `attachSurface` availability fence. Authorization compares owner sessions; owner cleanup selects the exact registered `Agent` instance. See [`dsh-tasks`](../../packages/tasks/tasks/README.md) for the package contract and [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md) for the model-facing surface.
+The abstract [`TaskService`](../../packages/tasks/tasks/src/index.ts) seam defines atomic `start`, caller-scoped `get` and `list`, `read`, `kill`, bounded `wait`, contained `onTaskDone` listeners, and the `attachSurface` availability fence; [`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) is the process-local implementation. Authorization compares owner sessions; owner cleanup selects the exact registered `Agent` instance. See [`dsh-tasks`](../../packages/tasks/tasks/README.md) for the seam contract, [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md) for the registry lifecycle, and [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md) for the model-facing surface.
diff --git a/docs/module-graph.md b/docs/module-graph.md
index abadead03f..87e0f7c0d5 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -207,6 +207,7 @@ flowchart TD
end
subgraph group_tasks["packages/tasks"]
pkg_tasks["tasks"]
+ pkg_tasks_local["tasks-local"]
pkg_tool_tasks["tool-tasks"]
end
subgraph group_workflow["packages/workflow"]
@@ -433,7 +434,6 @@ flowchart TD
pkg_tasks --> pkg_brand
pkg_tasks --> pkg_invariants
pkg_tasks --> pkg_session
- pkg_tasks --> pkg_timeout
pkg_workflow --> pkg_agent
pkg_workflow --> pkg_brand
pkg_workflow --> pkg_invariants
@@ -508,6 +508,10 @@ flowchart TD
pkg_pty_local --> pkg_sandbox
pkg_pty_local --> pkg_sandbox_policy
pkg_pty_local --> pkg_session
+ pkg_tasks_local --> pkg_agent
+ pkg_tasks_local --> pkg_invariants
+ pkg_tasks_local --> pkg_tasks
+ pkg_tasks_local --> pkg_timeout
pkg_agent_loop --> pkg_agent
pkg_agent_loop --> pkg_invariants
pkg_agent_loop --> pkg_llm
@@ -727,7 +731,7 @@ flowchart TD
pkg_agent_spine_demo --> pkg_skill
pkg_agent_spine_demo --> pkg_skill_local
pkg_agent_spine_demo --> pkg_system_prompt
- pkg_agent_spine_demo --> pkg_tasks
+ pkg_agent_spine_demo --> pkg_tasks_local
pkg_agent_spine_demo --> pkg_tool_bash
pkg_agent_spine_demo --> pkg_tool_goal
pkg_agent_spine_demo --> pkg_tool_skill
@@ -882,7 +886,7 @@ flowchart TD
| [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
| [`pty`](../packages/pty/pty) | `pty` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
| [`scripts`](../packages/sdk/scripts) | `sdk` | [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants) |
-| [`tasks`](../packages/tasks/tasks) | `tasks` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
+| [`tasks`](../packages/tasks/tasks) | `tasks` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
| [`workflow`](../packages/workflow/workflow) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`workspace`](../packages/workspace/workspace) | `workspace` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`storage`](../packages/storage/storage), [`storage-domain`](../packages/storage/storage-domain) |
| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/ui/user-approval) |
@@ -897,6 +901,7 @@ flowchart TD
| [`permission`](../packages/ui/permission) | `ui` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`user-approval`](../packages/ui/user-approval) |
| [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) |
| [`pty-local`](../packages/pty/pty-local) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session) |
+| [`tasks-local`](../packages/tasks/tasks-local) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tasks`](../packages/tasks/tasks), [`timeout`](../packages/util/timeout) |
| [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
| [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
| [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
@@ -928,7 +933,7 @@ flowchart TD
| [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
| [`jsonrpc`](../packages/ui/jsonrpc) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
| [`tui`](../packages/ui/tui) | `ui` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`commands`](../packages/ui/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-reference`](../packages/context/session-reference), [`session-title`](../packages/session-title/session-title), [`skill`](../packages/skill/skill), [`system-prompt`](../packages/core/system-prompt), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
-| [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`paths`](../packages/util/paths), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
+| [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`paths`](../packages/util/paths), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks-local`](../packages/tasks/tasks-local), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
| [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
| [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
| [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
diff --git a/examples/headless-agent/tests/code-mode.e2e.ts b/examples/headless-agent/tests/code-mode.e2e.ts
index 86c1559b83..bb8fdfe260 100644
--- a/examples/headless-agent/tests/code-mode.e2e.ts
+++ b/examples/headless-agent/tests/code-mode.e2e.ts
@@ -19,7 +19,7 @@ import { WorkerCodeRuntime } from '@deepseek-ai/dsh-code-runtime-worker'
import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
import * as WorkspaceContext from '@deepseek-ai/dsh-workspace-context'
-import TaskService from '@deepseek-ai/dsh-tasks'
+import LocalTaskService from '@deepseek-ai/dsh-tasks-local'
import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis'
@@ -112,7 +112,7 @@ async function typedCodeModeHarness(): Promise {
/** Keyless real-worker harness with the task-owned bash lifecycle. */
async function backgroundCodeModeHarness(cwd: string): Promise {
const harness = await typedCodeModeHarness()
- await harness.plugin(TaskService)
+ await harness.plugin(LocalTaskService)
await harness.plugin(ToolTasks, {})
await harness.plugin(LocalBashExecutor, { cwd, timeoutMs: 30_000 })
await harness.plugin(ToolBash)
diff --git a/examples/package.json b/examples/package.json
index 395c135a2d..8a81d399b8 100644
--- a/examples/package.json
+++ b/examples/package.json
@@ -49,6 +49,7 @@
"@deepseek-ai/dsh-subagent-acp": "workspace:*",
"@deepseek-ai/dsh-subagent-fork": "workspace:*",
"@deepseek-ai/dsh-subagent-spawn": "workspace:*",
+ "@deepseek-ai/dsh-tasks-local": "workspace:*",
"@deepseek-ai/dsh-time-context": "workspace:*",
"@deepseek-ai/dsh-timeout-policy": "workspace:*",
"@deepseek-ai/dsh-token-meter": "workspace:*",
diff --git a/packages/bash/tool-bash/README.md b/packages/bash/tool-bash/README.md
index e58145ee67..0f957e7d89 100644
--- a/packages/bash/tool-bash/README.md
+++ b/packages/bash/tool-bash/README.md
@@ -139,7 +139,7 @@ Append-only; newly visible content follows the reusable request prefix and does
#### What the model sees
-Validation and policy failures are normalized as `Error: `. This package's stable messages are `invalid command: expected a non-empty string`, `invalid description: expected a non-empty string`, `invalid timeoutMs: expected a positive number, got `, `invalid escalation: sandbox_permissions requires a justification`, `invalid escalation: justification is only valid together with sandbox_permissions`, `invalid justification: expected a non-empty sentence`, `background execution is disabled for this bash tool`, `background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks`, `sandbox_permissions is not available in this composition (no sandboxing executor to escalate)`, `sandbox escalation to "" is not strictly wider than this call's current "" mode`, the approval-availability/rejection/cancellation variants, and `command aborted`.
+Validation and policy failures are normalized as `Error: `. This package's stable messages are `invalid command: expected a non-empty string`, `invalid description: expected a non-empty string`, `invalid timeoutMs: expected a positive number, got `, `invalid escalation: sandbox_permissions requires a justification`, `invalid escalation: justification is only valid together with sandbox_permissions`, `invalid justification: expected a non-empty sentence`, `background execution is disabled for this bash tool`, `background tasks unavailable: load @deepseek-ai/dsh-tasks-local and @deepseek-ai/dsh-tool-tasks`, `sandbox_permissions is not available in this composition (no sandboxing executor to escalate)`, `sandbox escalation to "" is not strictly wider than this call's current "" mode`, the approval-availability/rejection/cancellation variants, and `command aborted`.
#### Token effect
diff --git a/packages/bash/tool-bash/package.json b/packages/bash/tool-bash/package.json
index 6fe653fe6f..a89e147e0e 100644
--- a/packages/bash/tool-bash/package.json
+++ b/packages/bash/tool-bash/package.json
@@ -60,6 +60,7 @@
"@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
"@deepseek-ai/dsh-system-prompt": "workspace:^",
"@deepseek-ai/dsh-tasks": "workspace:^",
+ "@deepseek-ai/dsh-tasks-local": "workspace:^",
"@deepseek-ai/dsh-tool-tasks": "workspace:^",
"@deepseek-ai/dsh-tools": "workspace:^",
"@deepseek-ai/dsh-user-approval": "workspace:^",
diff --git a/packages/bash/tool-bash/src/index.ts b/packages/bash/tool-bash/src/index.ts
index 81770b1595..b805c7fade 100644
--- a/packages/bash/tool-bash/src/index.ts
+++ b/packages/bash/tool-bash/src/index.ts
@@ -533,9 +533,9 @@ export function apply(ctx: Context, config: Config = {}): void {
}
const tasks = ctx.get('tasks')
if (tasks === undefined) {
- throw new Error('background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks')
+ throw new Error('background tasks unavailable: load @deepseek-ai/dsh-tasks-local and @deepseek-ai/dsh-tool-tasks')
}
- // The caller owns cancellation until TaskService commits detached ownership.
+ // The caller owns cancellation until ctx.tasks commits detached ownership.
if (exec.signal.aborted) {
const error = new HarnessError('tool call aborted', TOOL_ABORTED)
error.name = 'AbortError'
diff --git a/packages/bash/tool-bash/tests/integration.spec.ts b/packages/bash/tool-bash/tests/integration.spec.ts
index 8adf2165e0..e1315c232a 100644
--- a/packages/bash/tool-bash/tests/integration.spec.ts
+++ b/packages/bash/tool-bash/tests/integration.spec.ts
@@ -8,7 +8,7 @@ import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
import type { Agent } from '@deepseek-ai/dsh-agent'
import AgentLoop from '@deepseek-ai/dsh-agent-loop'
import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
-import TaskService from '@deepseek-ai/dsh-tasks'
+import LocalTaskService from '@deepseek-ai/dsh-tasks-local'
import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
@@ -27,7 +27,7 @@ async function harness(adapter: MockAdapter, sessionRoot?: string, dshHome?: str
await ctx.plugin(SessionPersistenceJsonl, { root: sessionRoot, compression: 'none' })
}
await ctx.plugin(AgentLoop, { agents: [] })
- await ctx.plugin(TaskService)
+ await ctx.plugin(LocalTaskService)
await ctx.plugin(ToolTasks)
await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000 })
await ctx.plugin(ToolBash, dshHome === undefined ? {} : { dshHome })
@@ -169,7 +169,7 @@ describe('bash tool through the agent loop', () => {
})
it('background: start ack → completion notice as user/message → task_output collects it', async () => {
- // The task id is deterministic (a fresh TaskService counts per kind from 1),
+ // The task id is deterministic (a fresh LocalTaskService counts per kind from 1),
// so the script can name `bash-1` without threading a generated id.
const adapter = new MockAdapter([
toolCallResponse('call-1', 'bash', { command: 'echo bg-ok', description: 'test command', run_in_background: true }),
diff --git a/packages/bash/tool-bash/tests/tools.spec.ts b/packages/bash/tool-bash/tests/tools.spec.ts
index 8811da6ca0..c2b0c3d31b 100644
--- a/packages/bash/tool-bash/tests/tools.spec.ts
+++ b/packages/bash/tool-bash/tests/tools.spec.ts
@@ -12,7 +12,7 @@ import AgentRegistry from '@deepseek-ai/dsh-agent'
import type { Agent } from '@deepseek-ai/dsh-agent'
import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
-import TaskService from '@deepseek-ai/dsh-tasks'
+import LocalTaskService from '@deepseek-ai/dsh-tasks-local'
import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
import ApprovalService from '@deepseek-ai/dsh-user-approval'
import type { ApprovalOutcome } from '@deepseek-ai/dsh-user-approval'
@@ -44,7 +44,7 @@ async function setupWithTasks() {
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
await ctx.plugin(AgentRegistry)
- await ctx.plugin(TaskService)
+ await ctx.plugin(LocalTaskService)
await ctx.plugin(ToolTasks)
await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, graceMs: 200 })
;(ctx.bash as LocalBashExecutor).internals = { spillDir }
@@ -180,7 +180,7 @@ async function setupSandboxed(withApproval = false) {
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
await ctx.plugin(AgentRegistry)
- await ctx.plugin(TaskService)
+ await ctx.plugin(LocalTaskService)
await ctx.plugin(ToolTasks)
await ctx.plugin(SandboxPolicyService, {})
await ctx.plugin(RecordingSandboxExecutor)
@@ -472,10 +472,10 @@ describe('background execution through the task runtime', () => {
})
it('fails loud when the task runtime is not loaded', async () => {
- const ctx = await setup() // no TaskService / ToolTasks
+ const ctx = await setup() // no LocalTaskService / ToolTasks
const result = await call(ctx, 'bash', { command: 'sleep 60', description: 'test command', run_in_background: true })
expect(result.isError).toBe(true)
- expect(text(result)).toContain('background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks')
+ expect(text(result)).toContain('background tasks unavailable: load @deepseek-ai/dsh-tasks-local and @deepseek-ai/dsh-tool-tasks')
})
it('a pre-aborted call is skipped before the process starts', async () => {
@@ -483,7 +483,7 @@ describe('background execution through the task runtime', () => {
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
await ctx.plugin(AgentRegistry)
- await ctx.plugin(TaskService)
+ await ctx.plugin(LocalTaskService)
await ctx.plugin(ToolTasks)
await ctx.plugin(CountingStartExecutor)
await ctx.plugin(ToolBash)
@@ -511,7 +511,7 @@ describe('background execution through the task runtime', () => {
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
await ctx.plugin(AgentRegistry)
- await ctx.plugin(TaskService)
+ await ctx.plugin(LocalTaskService)
await ctx.plugin(CountingStartExecutor)
await ctx.plugin(ToolBash)
@@ -1073,7 +1073,7 @@ describe('the model-facing bash tool builds its request from named args only (no
await ctx.plugin(SessionStore)
await ctx.plugin(SessionPersistenceJsonl, { root: join(spillDir, 'jsonl') })
}
- await ctx.plugin(TaskService)
+ await ctx.plugin(LocalTaskService)
await ctx.plugin(ToolTasks)
await ctx.plugin(RecordingBashExecutor)
await ctx.plugin(ToolBash, { dshHome: recordingDshHome })
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index d834d3ee21..3681efa015 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -768,38 +768,38 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
},
{
key: 'tasks',
- summary: 'The `tasks` service: the runtime-global background task registry.',
+ summary: 'Abstract background task registry.',
methods: [
{
- signature: 'start(spec: TaskStart): TaskId',
+ signature: 'abstract start(spec: TaskStart): TaskId',
jsDoc: '/**\n * Preflight access, validation, and owner cleanup before starting and\n * atomically registering work. A throwing starter leaves nothing registered;\n * after it returns, registration cannot fail. Settlement records the outcome,\n * notifies listeners, and releases waiters.\n * @param spec - task identity, owner, and synchronous starter.\n * @returns the registry-issued `-N` id.\n */',
},
{
- signature: 'list(caller?: Agent): TaskSnapshot[]',
+ signature: 'abstract list(caller?: Agent): TaskSnapshot[]',
jsDoc: '/**\n * List caller-owned and unowned tasks in registration order without exposing\n * another session\'s labels.\n * @param caller - reading agent; a non-agent caller sees only unowned tasks.\n * @returns fresh snapshots.\n */',
},
{
- signature: 'get(id: TaskId, caller?: Agent): TaskSnapshot',
+ signature: 'abstract get(id: TaskId, caller?: Agent): TaskSnapshot',
jsDoc: '/**\n * Return a non-consuming snapshot without changing its read cursor or notice\n * state. Throws for an unknown or foreign task.\n * @param id - task to look up.\n * @param caller - reading agent checked against the owner.\n * @returns a fresh snapshot.\n */',
},
{
- signature: 'read(id: TaskId, caller?: Agent): TaskRead',
+ signature: 'abstract read(id: TaskId, caller?: Agent): TaskRead',
jsDoc: '/**\n * Read the next stream delta, or the idempotent final output after settlement.\n * A terminal read marks the task reported. Throws for an unknown or foreign\n * task.\n * @param id - task to read.\n * @param caller - reading agent checked against the owner.\n * @returns output text and the post-read snapshot.\n */',
},
{
- signature: 'kill(id: TaskId, caller?: Agent, reason?: string): \'requested\' | \'already-finished\'',
+ signature: 'abstract kill(id: TaskId, caller?: Agent, reason?: string): \'requested\' | \'already-finished\'',
jsDoc: '/**\n * Request cancellation, then mark the task stopping and reported. A producer\n * throw propagates without changing task state. Throws for an unknown or\n * foreign task.\n * @param id - task to cancel.\n * @param caller - killing agent checked against the owner.\n * @param reason - logged reason forwarded to the producer.\n * @returns `requested` for live work, otherwise `already-finished`.\n */',
},
{
- signature: 'async wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise',
- jsDoc: '/**\n * Wait for settlement or timeout without cancelling the task. Caller abort\n * rejects only while the task is live; after settlement it returns the\n * terminal snapshot so a notice suppressed for this waiter is still delivered.\n * Timed-out and aborted waits detach their resolvers. Throws for invalid,\n * unknown, or foreign input.\n * @param id - task to wait for.\n * @param timeoutMs - positive finite wait bound in milliseconds.\n * @param caller - waiting agent checked against the owner.\n * @param signal - optional cancellation of the wait itself.\n * @returns snapshot at settlement or timeout.\n */',
+ signature: 'abstract wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise',
+ jsDoc: '/**\n * Wait for settlement or timeout without cancelling the task. Caller abort\n * rejects only while the task is live; after settlement the terminal\n * snapshot wins so a notice suppressed for this waiter is still delivered.\n * Throws for invalid, unknown, or foreign input.\n * @param id - task to wait for.\n * @param timeoutMs - positive finite wait bound in milliseconds.\n * @param caller - waiting agent checked against the owner.\n * @param signal - optional cancellation of the wait itself.\n * @returns snapshot at settlement or timeout.\n */',
},
{
- signature: 'onTaskDone(listener: TaskDoneListener): () => void',
+ signature: 'abstract onTaskDone(listener: TaskDoneListener): () => void',
jsDoc: '/**\n * Register an effect-scoped completion listener. Each listener is contained;\n * returned promises are observed but not awaited. No listener runs after\n * service disposal.\n * @param listener - receives each terminal snapshot and its exact owner.\n * @returns disposer that unregisters the listener.\n */',
},
{
- signature: 'attachSurface(name: string): () => void',
+ signature: 'abstract attachSurface(name: string): () => void',
jsDoc: '/**\n * Attach an effect-scoped surface that can read and stop tasks. {@link start}\n * refuses work while none is attached.\n * @param name - diagnostic label; duplicate names remain independent.\n * @returns disposer that detaches this surface.\n */',
},
],
diff --git a/packages/examples/agent-spine-demo/README.md b/packages/examples/agent-spine-demo/README.md
index 05ea5c75e2..bfcfef446d 100644
--- a/packages/examples/agent-spine-demo/README.md
+++ b/packages/examples/agent-spine-demo/README.md
@@ -22,7 +22,7 @@ Read this package for the whole plugin tree and its composition order.
@deepseek-ai/dsh-tool-goal optional model-facing goal controls
@deepseek-ai/dsh-goal-session optional same-session goal-round driver
@deepseek-ai/dsh-llm-retry bounded transient request retry policy
-@deepseek-ai/dsh-tasks generic background-task registry
+@deepseek-ai/dsh-tasks-local generic background-task registry
@deepseek-ai/dsh-invariants configurable invariant registry service
@deepseek-ai/dsh-session/invariant
@deepseek-ai/dsh-agent/invariant
diff --git a/packages/examples/agent-spine-demo/package.json b/packages/examples/agent-spine-demo/package.json
index bf69e27787..923a9aace6 100644
--- a/packages/examples/agent-spine-demo/package.json
+++ b/packages/examples/agent-spine-demo/package.json
@@ -42,7 +42,7 @@
"@deepseek-ai/dsh-skill": "^0.0.1",
"@deepseek-ai/dsh-skill-local": "^0.0.1",
"@deepseek-ai/dsh-system-prompt": "^0.0.1",
- "@deepseek-ai/dsh-tasks": "^0.0.1",
+ "@deepseek-ai/dsh-tasks-local": "^0.0.1",
"@deepseek-ai/dsh-tool-bash": "^0.0.1",
"@deepseek-ai/dsh-tool-goal": "^0.0.1",
"@deepseek-ai/dsh-tool-skill": "^0.0.1",
@@ -74,6 +74,7 @@
"@deepseek-ai/dsh-skill-local": "workspace:^",
"@deepseek-ai/dsh-system-prompt": "workspace:^",
"@deepseek-ai/dsh-tasks": "workspace:^",
+ "@deepseek-ai/dsh-tasks-local": "workspace:^",
"@deepseek-ai/dsh-tool-bash": "workspace:^",
"@deepseek-ai/dsh-tool-fs": "workspace:^",
"@deepseek-ai/dsh-tool-goal": "workspace:^",
diff --git a/packages/examples/agent-spine-demo/src/index.ts b/packages/examples/agent-spine-demo/src/index.ts
index c43ee2ab8d..0ac96aaa85 100644
--- a/packages/examples/agent-spine-demo/src/index.ts
+++ b/packages/examples/agent-spine-demo/src/index.ts
@@ -22,7 +22,7 @@ import AgentRegistry from '@deepseek-ai/dsh-agent'
import GoalService, { type Config as GoalDomainConfig } from '@deepseek-ai/dsh-goal'
import * as goalSession from '@deepseek-ai/dsh-goal-session'
import * as toolGoal from '@deepseek-ai/dsh-tool-goal'
-import TaskService from '@deepseek-ai/dsh-tasks'
+import LocalTaskService from '@deepseek-ai/dsh-tasks-local'
import InvariantService, { type Config as InvariantConfig } from '@deepseek-ai/dsh-invariants'
import * as sessionInvariant from '@deepseek-ai/dsh-session/invariant'
import * as agentInvariant from '@deepseek-ai/dsh-agent/invariant'
@@ -223,7 +223,7 @@ export function apply(ctx: Context, config: Config): void {
ctx.plugin(toolGoal, config.goals.tool ?? {})
ctx.plugin(goalSession)
}
- ctx.plugin(TaskService)
+ ctx.plugin(LocalTaskService)
ctx.plugin(InvariantService, config.invariants ?? {})
ctx.plugin(sessionInvariant)
ctx.plugin(agentInvariant)
diff --git a/packages/examples/agent-spine-demo/tsconfig.json b/packages/examples/agent-spine-demo/tsconfig.json
index 0888da5d24..670cd9a629 100644
--- a/packages/examples/agent-spine-demo/tsconfig.json
+++ b/packages/examples/agent-spine-demo/tsconfig.json
@@ -74,6 +74,9 @@
{
"path": "../../tasks/tasks"
},
+ {
+ "path": "../../tasks/tasks-local"
+ },
{
"path": "../../tasks/tool-tasks"
}
diff --git a/packages/pty/tool-pty/package.json b/packages/pty/tool-pty/package.json
index 2d36fb5c9b..d8b2564736 100644
--- a/packages/pty/tool-pty/package.json
+++ b/packages/pty/tool-pty/package.json
@@ -54,6 +54,7 @@
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-system-prompt": "workspace:^",
"@deepseek-ai/dsh-tasks": "workspace:^",
+ "@deepseek-ai/dsh-tasks-local": "workspace:^",
"@deepseek-ai/dsh-tool-tasks": "workspace:^",
"@deepseek-ai/dsh-tools": "workspace:^",
"cordis": "^4.0.0-rc.7"
diff --git a/packages/pty/tool-pty/src/index.ts b/packages/pty/tool-pty/src/index.ts
index fc66d2646e..abd0664893 100644
--- a/packages/pty/tool-pty/src/index.ts
+++ b/packages/pty/tool-pty/src/index.ts
@@ -250,7 +250,7 @@ export function apply(ctx: Context, config: Config = {}): void {
if (args.run_in_background === true) {
if (!enableRunInBackground) throw new Error('background terminal sends are disabled by tool-pty configuration')
const tasks = ctx.get('tasks')
- if (tasks === undefined) throw new Error('background terminal sends require @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks')
+ if (tasks === undefined) throw new Error('background terminal sends require @deepseek-ai/dsh-tasks-local and @deepseek-ai/dsh-tool-tasks')
let cancelRequested = false
const taskId = tasks.start({
kind: 'pty-send',
diff --git a/packages/pty/tool-pty/tests/tools.spec.ts b/packages/pty/tool-pty/tests/tools.spec.ts
index e0b854ee43..dbc05605c6 100644
--- a/packages/pty/tool-pty/tests/tools.spec.ts
+++ b/packages/pty/tool-pty/tests/tools.spec.ts
@@ -9,7 +9,7 @@ import ToolRegistry, { renderToolsSdk } from '@deepseek-ai/dsh-tools'
import type { ToolSdkSchema } from '@deepseek-ai/dsh-tools/src/ts-types.ts'
import PtyService, { PtySessionId } from '@deepseek-ai/dsh-pty'
import type { PtyBackend, PtyBackendSession, PtySendOperation, PtySendRequest, PtySessionStatus, PtySignal } from '@deepseek-ai/dsh-pty'
-import TaskService from '@deepseek-ai/dsh-tasks'
+import LocalTaskService from '@deepseek-ai/dsh-tasks-local'
import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
import * as ToolPty from '@deepseek-ai/dsh-tool-pty'
@@ -106,7 +106,7 @@ async function setupBase(tasks: boolean) {
const stub = stubBackend()
ctx.pty.registerBackend(stub.backend)
if (tasks) {
- await ctx.plugin(TaskService)
+ await ctx.plugin(LocalTaskService)
await ctx.plugin(ToolTasks)
}
return { ctx, stub, agent: fakeAgent(ctx, tasks ? 'with-tasks' : 'foreground') }
diff --git a/packages/subagent/tool-subagent/package.json b/packages/subagent/tool-subagent/package.json
index 6ed447dd56..b5c7b5d94f 100644
--- a/packages/subagent/tool-subagent/package.json
+++ b/packages/subagent/tool-subagent/package.json
@@ -46,6 +46,7 @@
"@deepseek-ai/dsh-subagent": "workspace:^",
"@deepseek-ai/dsh-system-prompt": "workspace:^",
"@deepseek-ai/dsh-tasks": "workspace:^",
+ "@deepseek-ai/dsh-tasks-local": "workspace:^",
"@deepseek-ai/dsh-tool-tasks": "workspace:^",
"@deepseek-ai/dsh-tools": "workspace:^",
"cordis": "^4.0.0-rc.7"
diff --git a/packages/subagent/tool-subagent/src/index.ts b/packages/subagent/tool-subagent/src/index.ts
index 4eb29d0c6e..cd2eb590ae 100644
--- a/packages/subagent/tool-subagent/src/index.ts
+++ b/packages/subagent/tool-subagent/src/index.ts
@@ -323,7 +323,7 @@ export function apply(ctx: Context, config: Config): void {
}
const tasks = ctx.get('tasks')
if (tasks === undefined) {
- throw new Error('background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks')
+ throw new Error('background tasks unavailable: load @deepseek-ai/dsh-tasks-local and @deepseek-ai/dsh-tool-tasks')
}
// Task preflight finishes before the starter can spawn a child.
const id = tasks.start({
diff --git a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
index 8468216d49..d3409e4604 100644
--- a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
+++ b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
@@ -8,7 +8,7 @@ import { type Agent } from '@deepseek-ai/dsh-agent'
import AgentRegistry from '@deepseek-ai/dsh-agent'
import SubagentService from '@deepseek-ai/dsh-subagent'
import type { SubagentStartRequest } from '@deepseek-ai/dsh-subagent'
-import TaskService from '@deepseek-ai/dsh-tasks'
+import LocalTaskService from '@deepseek-ai/dsh-tasks-local'
import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
import * as mock from './scripted-provider.ts'
import * as tool from '../src/index.ts'
@@ -641,7 +641,7 @@ describe('dsh-tool-subagent background mode', () => {
async function backgroundSetup(toolConfig: tool.Config, mockConfig: Partial = {}) {
const ctx = await setup(toolConfig, mockConfig)
await ctx.plugin(AgentRegistry)
- await ctx.plugin(TaskService)
+ await ctx.plugin(LocalTaskService)
await ctx.plugin(ToolTasks, {})
return ctx
}
@@ -680,7 +680,7 @@ describe('dsh-tool-subagent background mode', () => {
const ctx = await setup({ provider: 'mock' })
const result = await callSubagent(ctx, { description: 'd', prompt: 'p', run_in_background: true })
expect(result.isError).toBe(true)
- expect(text(result)).toContain('background tasks unavailable: load @deepseek-ai/dsh-tasks')
+ expect(text(result)).toContain('background tasks unavailable: load @deepseek-ai/dsh-tasks-local')
})
it('skips background startup when the tool signal is already aborted', async () => {
@@ -868,7 +868,7 @@ describe('background preflight failure (no orphaned child, by construction)', ()
// With no control surface, task preflight fails before the provider can spawn.
const ctx = await setup({ provider: 'mock' })
await ctx.plugin(AgentRegistry)
- await ctx.plugin(TaskService)
+ await ctx.plugin(LocalTaskService)
const scopeFiber = ctx.plugin(() => {})
const id = SessionId('sess-p')
const parent = {
diff --git a/packages/tasks/README.md b/packages/tasks/README.md
index 71c68ea250..693a25d38d 100644
--- a/packages/tasks/README.md
+++ b/packages/tasks/README.md
@@ -1,10 +1,11 @@
# tasks/ — background task capability family
-The shared home for background-task ids, owner isolation, reads, cancellation, waiting, and completion notices. Bash, subagents, and future long-running tools use one model-facing protocol. See the [background-task runtime Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md).
+The shared home for background-task ids, owner isolation, reads, cancellation, waiting, and completion notices. Bash, subagents, and future long-running tools use one model-facing protocol. See the [background-task runtime Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and the [task-registry seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md).
| Package | ctx key | Role |
|---|---|---|
-| [`tasks`](tasks/README.md) (`@deepseek-ai/dsh-tasks`) | `ctx.tasks` | The registry service: branded `-N` ids, owner-fenced read/kill/wait/list, settlement bookkeeping, the awaited owner-cleanup path, and the `attachSurface` misconfiguration fence |
+| [`tasks`](tasks/README.md) (`@deepseek-ai/dsh-tasks`) | `ctx.tasks` | The registry seam: branded `-N` ids, the owner-fenced read/kill/wait/list contract, snapshot vocabulary, the `attachSurface` misconfiguration fence, and the snapshot invariant companion |
+| [`tasks-local`](tasks-local/README.md) (`@deepseek-ai/dsh-tasks-local`) | — | The process-local registry implementation: in-memory records, first-wins settlement bookkeeping, and the awaited owner-cleanup and teardown paths |
| [`tool-tasks`](tool-tasks/README.md) (`@deepseek-ai/dsh-tool-tasks`) | — | The model-facing control surface: `task_output`, `task_list`, `task_kill`, the completion-notice injection, and the background-habit prompt section |
The registry owns state across producer or surface reloads; the tool package owns presentation. Producers register execution hooks through `ctx.tasks.start` and own whether their config exposes `run_in_background`.
diff --git a/packages/tasks/tasks-local/README.md b/packages/tasks/tasks-local/README.md
new file mode 100644
index 0000000000..5f57d3409d
--- /dev/null
+++ b/packages/tasks/tasks-local/README.md
@@ -0,0 +1,24 @@
+# @deepseek-ai/dsh-tasks-local
+
+Process-local implementation of the [`@deepseek-ai/dsh-tasks`](../tasks/README.md) registry seam: `LocalTaskService` keeps every record in memory, issues per-kind `-N` ids, and hands out fresh snapshots, never live state. It has no config; load it as a plugin and it registers as `ctx.tasks`.
+
+## Lifecycle
+
+Tasks belong to their owner and backend, not the producer tool fiber, so producer and surface reloads do not stop them. The first task for an owner attaches one awaited effect to the exact `Agent` scope. Owner disposal cancels that object's tasks, awaits producer quiescence, and removes their snapshots; reused agent or session ids cannot redirect an old cleanup.
+
+Service disposal closes listeners, cancels all live tasks, awaits their records, and detaches effects from surviving owner scopes. If teardown cancellation throws, the service force-fails the record and warns that work may be orphaned instead of deadlocking. A cancellation that returns but never settles `done` remains indistinguishable from a slow stop and can stall teardown.
+
+Settlement is first-wins: the earliest terminal outcome — producer settlement, a rejected `done` contained as `failed`, or a teardown force-failure — records once, notifies listeners once with per-listener containment, and releases waiters. Pending waits mark the task reported before listeners run so completion surfaces do not duplicate notices.
+
+## Model Experience
+
+Indirectly, through producer plugins and [`dsh-tool-tasks`](../tool-tasks/README.md), which render task ids, output, status, cancellation, and completion notices.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **Tasks are process-local** — records die with the harness process; durable or cross-restart execution needs a separate backend implementing the seam.
+- **A silently ineffective cancel can stall teardown** — only an explicit throw can be force-failed safely.
diff --git a/packages/tasks/tasks-local/package.json b/packages/tasks/tasks-local/package.json
new file mode 100644
index 0000000000..cdcc823826
--- /dev/null
+++ b/packages/tasks/tasks-local/package.json
@@ -0,0 +1,45 @@
+{
+ "name": "@deepseek-ai/dsh-tasks-local",
+ "description": "Process-local implementation of the DeepSeek Harness background task registry seam",
+ "version": "0.0.1",
+ "private": true,
+ "type": "module",
+ "main": "lib/index.js",
+ "types": "lib/types/index.d.ts",
+ "exports": {
+ ".": {
+ "types": "./lib/types/index.d.ts",
+ "default": "./lib/index.js"
+ },
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
+ "./src/*": "./src/*",
+ "./package.json": "./package.json"
+ },
+ "files": [
+ "lib/index.js",
+ "lib/invariant.js",
+ "lib/types/**/*.d.ts",
+ "lib/types/**/*.d.ts.map",
+ "src"
+ ],
+ "license": "BSD-3-Clause",
+ "peerDependencies": {
+ "@deepseek-ai/dsh-agent": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
+ "@deepseek-ai/dsh-tasks": "^0.0.1",
+ "@deepseek-ai/dsh-timeout": "^0.0.1",
+ "cordis": "^4.0.0-rc.7"
+ },
+ "devDependencies": {
+ "@deepseek-ai/dsh-agent": "workspace:^",
+ "@deepseek-ai/dsh-brand": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
+ "@deepseek-ai/dsh-session": "workspace:^",
+ "@deepseek-ai/dsh-tasks": "workspace:^",
+ "@deepseek-ai/dsh-timeout": "workspace:^",
+ "cordis": "^4.0.0-rc.7"
+ }
+}
diff --git a/packages/tasks/tasks-local/src/index.ts b/packages/tasks/tasks-local/src/index.ts
new file mode 100644
index 0000000000..f108022b17
--- /dev/null
+++ b/packages/tasks/tasks-local/src/index.ts
@@ -0,0 +1,365 @@
+/**
+ * Process-local implementation of the background task registry seam
+ * (`ctx.tasks`). It keeps every record in memory and hands out fresh
+ * snapshots, never live state.
+ *
+ * Registrations outlive producer and control-surface fibers. Agent or service
+ * disposal cancels live work and awaits compliant producers; a throwing
+ * teardown cancel force-fails only the record and reports a possible orphan.
+ * @module @deepseek-ai/dsh-tasks-local
+ */
+
+import { Context } from 'cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
+import { TaskService, TaskId } from '@deepseek-ai/dsh-tasks'
+import type { TaskDoneListener, TaskKind, TaskOutcome, TaskRead, TaskSnapshot, TaskStart, TaskStatus } from '@deepseek-ai/dsh-tasks'
+
+/** Timeout code that distinguishes a bounded wait from caller cancellation. */
+export const TASK_WAIT_TIMEOUT = 'TASK_WAIT_TIMEOUT'
+
+/** The registry's mutable per-task record (never handed out — see {@link LocalTaskService.snapshot}). */
+interface TrackedTask {
+ id: TaskId
+ kind: TaskKind
+ label: string
+ outputLimitBytes: number | undefined
+ /** Exact lifecycle owner; session-id authorization is derived from it. */
+ owner: Agent | undefined
+ cancel: (reason?: string) => void
+ readOutput: (() => string) | undefined
+ status: TaskStatus
+ detail: string | undefined
+ output: string | undefined
+ startedAt: number
+ finishedAt: number | undefined
+ reported: boolean
+ /** Resolves once the terminal snapshot is recorded and listeners notified. */
+ settled: Promise
+ /** Resolver for {@link settled}, called by the first effective settlement. */
+ markSettled: () => void
+ /** Live waits; settlement with a waiter marks the task reported. */
+ waiters: number
+ /** Removable resolvers for live waits; timeout/abort unregister before the task settles. */
+ waitResolvers: Set<() => void>
+}
+
+/** True for the three terminal {@link TaskStatus} values. */
+function isTerminal(status: TaskStatus): boolean {
+ return status === 'completed' || status === 'killed' || status === 'failed'
+}
+
+/**
+ * The in-memory `tasks` registry. See the seam contract in
+ * `@deepseek-ai/dsh-tasks` for the ownership, isolation, and lifecycle
+ * semantics this implementation honors.
+ */
+export class LocalTaskService extends TaskService {
+ private store = new Map()
+ private counters = new Map()
+ private surfaces = new Set()
+ private listeners = new Set()
+ private listenersClosed = false
+ /** Owner agents with attached scope cleanup, mapped to the exact disposer. */
+ private ownerCleanups = new Map Promise | void>()
+ /** Service context used by detached settlement continuations and teardown. */
+ private readonly selfCtx: Context
+
+ constructor(ctx: Context) {
+ super(ctx)
+ this.selfCtx = ctx
+ ctx.effect(() => () => this.disposeAll(), 'tasks teardown')
+ }
+
+ start(spec: TaskStart): TaskId {
+ if (this.surfaces.size === 0) {
+ throw new Error('background tasks unavailable: no control surface is attached (load @deepseek-ai/dsh-tool-tasks)')
+ }
+ if (spec.kind.length === 0) throw new Error('invalid task kind: expected a non-empty string')
+ if (spec.label.length === 0) throw new Error('invalid task label: expected a non-empty string')
+ if (spec.outputLimitBytes !== undefined
+ && (!Number.isSafeInteger(spec.outputLimitBytes) || spec.outputLimitBytes <= 0)) {
+ throw new Error(`invalid outputLimitBytes: expected a positive safe integer, got ${JSON.stringify(spec.outputLimitBytes)}`)
+ }
+ if (spec.owner !== undefined) this.ensureOwnerCleanup(spec.owner)
+
+ const hooks = spec.run()
+ const count = (this.counters.get(spec.kind) ?? 0) + 1
+ this.counters.set(spec.kind, count)
+ const id = TaskId(`${spec.kind}-${count}`)
+
+ let markSettled!: () => void
+ const settled = new Promise((resolve) => { markSettled = resolve })
+ const task: TrackedTask = {
+ id,
+ kind: spec.kind,
+ label: spec.label,
+ outputLimitBytes: spec.outputLimitBytes,
+ owner: spec.owner,
+ cancel: hooks.cancel.bind(hooks),
+ readOutput: hooks.readOutput?.bind(hooks),
+ status: 'running',
+ detail: undefined,
+ output: undefined,
+ startedAt: Date.now(),
+ finishedAt: undefined,
+ reported: false,
+ settled,
+ markSettled,
+ waiters: 0,
+ waitResolvers: new Set(),
+ }
+ this.store.set(id, task)
+
+ void hooks.done.then(
+ (outcome) => { this.settle(task, outcome) },
+ (error: unknown) => {
+ // Contain a producer contract violation so cleanup and waiters cannot hang.
+ this.selfCtx.logger.warn(`tasks: task ${task.id} 'done' rejected (producer contract violation): ${String(error)}`)
+ this.settle(task, { status: 'failed', detail: String(error) })
+ },
+ )
+ return id
+ }
+
+ list(caller?: Agent): TaskSnapshot[] {
+ const session = caller?.id
+ return [...this.store.values()]
+ .filter(task => task.owner === undefined || task.owner.id === session)
+ .map(task => this.snapshot(task))
+ }
+
+ get(id: TaskId, caller?: Agent): TaskSnapshot {
+ const task = this.expect(id)
+ this.assertAccess(task, caller)
+ return this.snapshot(task)
+ }
+
+ read(id: TaskId, caller?: Agent): TaskRead {
+ const task = this.expect(id)
+ this.assertAccess(task, caller)
+ const text = task.readOutput !== undefined
+ ? task.readOutput()
+ : isTerminal(task.status) ? task.output ?? '' : ''
+ if (isTerminal(task.status)) task.reported = true
+ return { text, snapshot: this.snapshot(task) }
+ }
+
+ kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-finished' {
+ const task = this.expect(id)
+ this.assertAccess(task, caller)
+ if (isTerminal(task.status)) {
+ task.reported = true
+ return 'already-finished'
+ }
+ // Cancel first so a throw leaves both lifecycle and notice state unchanged.
+ task.cancel(reason)
+ task.status = 'stopping'
+ task.reported = true
+ return 'requested'
+ }
+
+ async wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise {
+ const task = this.expect(id)
+ this.assertAccess(task, caller)
+ if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+ throw new Error(`invalid wait timeout: expected a positive number of milliseconds, got ${JSON.stringify(timeoutMs)}`)
+ }
+ if (!isTerminal(task.status)) {
+ if (signal?.aborted) throw new Error('wait aborted')
+ // Abort removes the waiter synchronously so same-tick settlement cannot
+ // suppress a notice for a wait that will reject.
+ task.waiters += 1
+ let counted = true
+ const uncount = (): void => {
+ if (!counted) return
+ counted = false
+ task.waiters -= 1
+ }
+ try {
+ // The scoped deadline distinguishes a successful wait timeout from
+ // caller cancellation and clears its timer on every exit.
+ using d = deadline(signal, timeoutMs, TASK_WAIT_TIMEOUT)
+ await new Promise((resolve, reject) => {
+ const onSettled = (): void => {
+ task.waitResolvers.delete(onSettled)
+ d.signal.removeEventListener('abort', onAbort)
+ resolve()
+ }
+ const onAbort = (): void => {
+ task.waitResolvers.delete(onSettled)
+ if (timeoutOf(d.signal, TASK_WAIT_TIMEOUT) !== undefined) {
+ resolve()
+ } else if (isTerminal(task.status)) {
+ // Settlement suppressed the notice for this waiter; deliver it.
+ resolve()
+ } else {
+ uncount()
+ reject(new Error('wait aborted'))
+ }
+ }
+ task.waitResolvers.add(onSettled)
+ d.signal.addEventListener('abort', onAbort, { once: true })
+ })
+ } finally {
+ uncount()
+ }
+ }
+ if (isTerminal(task.status)) task.reported = true
+ return this.snapshot(task)
+ }
+
+ onTaskDone(listener: TaskDoneListener): () => void {
+ const dispose = this.ctx.effect(() => {
+ this.listeners.add(listener)
+ return () => this.listeners.delete(listener)
+ }, 'tasks.onTaskDone()')
+ return () => void dispose()
+ }
+
+ attachSurface(name: string): () => void {
+ // One token per call keeps duplicate labels independently disposable.
+ const token = Symbol(name)
+ const dispose = this.ctx.effect(() => {
+ this.surfaces.add(token)
+ return () => this.surfaces.delete(token)
+ }, 'tasks.attachSurface()')
+ return () => void dispose()
+ }
+
+ /** Look up a task or fail loud. */
+ private expect(id: TaskId): TrackedTask {
+ const task = this.store.get(id)
+ if (task === undefined) throw new Error(`unknown task ${id}`)
+ return task
+ }
+
+ /**
+ * The isolation fence: a task with an owner is reachable only by callers
+ * whose session id matches (`!== undefined` semantics — an unowned task is
+ * open, and a no-agent caller can never match an owned one).
+ */
+ private assertAccess(task: TrackedTask, caller?: Agent): void {
+ if (task.owner !== undefined && task.owner.id !== caller?.id) {
+ throw new Error(`task ${task.id} belongs to another session`)
+ }
+ }
+
+ /** Project a fresh read-only snapshot from the mutable record. */
+ private snapshot(task: TrackedTask): TaskSnapshot {
+ const ownerSession = task.owner?.id
+ return {
+ id: task.id,
+ kind: task.kind,
+ label: task.label,
+ ...task.outputLimitBytes !== undefined ? { outputLimitBytes: task.outputLimitBytes } : {},
+ ...ownerSession !== undefined ? { ownerSession } : {},
+ status: task.status,
+ ...task.detail !== undefined ? { detail: task.detail } : {},
+ startedAt: task.startedAt,
+ ...task.finishedAt !== undefined ? { finishedAt: task.finishedAt } : {},
+ reported: task.reported,
+ }
+ }
+
+ /**
+ * Record the first terminal outcome, notify contained listeners, and release
+ * waiters. First-wins preserves a teardown force-failure against late producer
+ * settlement. Pending waits mark the task reported before listeners run.
+ */
+ private settle(task: TrackedTask, outcome: TaskOutcome): void {
+ if (isTerminal(task.status)) return
+ task.status = outcome.status
+ task.detail = outcome.detail
+ task.output = outcome.output
+ task.finishedAt = Date.now()
+ if (task.waiters > 0) task.reported = true
+ if (!this.listenersClosed) {
+ const snapshot = this.snapshot(task)
+ for (const listener of this.listeners) {
+ try {
+ const returned = listener(snapshot, task.owner)
+ void Promise.resolve(returned).catch((error: unknown) => {
+ this.selfCtx.logger.warn(`tasks: onTaskDone listener rejected for ${task.id}: ${String(error)}`)
+ })
+ } catch (error: unknown) {
+ this.selfCtx.logger.warn(`tasks: onTaskDone listener threw for ${task.id}: ${String(error)}`)
+ }
+ }
+ }
+ const waitResolvers = [...task.waitResolvers]
+ task.waitResolvers.clear()
+ for (const resolveWait of waitResolvers) resolveWait()
+ task.markSettled()
+ }
+
+ /**
+ * Attach one awaited cleanup through the exact owner's scope. This survives
+ * producer reloads and joins agent quiescence; the retained disposer lets
+ * service teardown detach the cross-fiber effect. Fails when the registry is
+ * absent or the owner is not its currently registered instance.
+ */
+ private ensureOwnerCleanup(owner: Agent): void {
+ const ownerId = owner.id
+ const agents = this.selfCtx.get('agents')
+ if (agents === undefined) {
+ throw new Error('background task ownership requires the agent registry (load @deepseek-ai/dsh-agent)')
+ }
+ if (agents.get(ownerId) !== owner) {
+ throw new Error(`agent "${ownerId}" is not the registered agent instance (background task owner must be live)`)
+ }
+ if (this.ownerCleanups.has(owner)) return
+ // Record only after attach succeeds; a disposing scope rejects new effects.
+ const detach = owner.ctx.effect(() => async () => {
+ this.ownerCleanups.delete(owner)
+ await this.disposeOwned(owner)
+ }, 'tasks.ownerCleanup()')
+ this.ownerCleanups.set(owner, detach)
+ }
+
+ /** Cancel, await terminal records, and drop every task owned by one exact agent lifecycle. */
+ private async disposeOwned(owner: Agent): Promise {
+ const owned = [...this.store.values()].filter(task => task.owner === owner)
+ this.cancelForTeardown(owned, 'owner disposed')
+ await Promise.all(owned.map(task => task.settled))
+ for (const task of owned) this.store.delete(task.id)
+ }
+
+ /**
+ * Close listeners, cancel live tasks, await settlement, and detach owner
+ * effects. Throwing cancels are force-failed to avoid teardown deadlock.
+ */
+ private async disposeAll(): Promise {
+ this.listenersClosed = true
+ this.listeners.clear()
+ const all = [...this.store.values()]
+ this.cancelForTeardown(all, 'tasks service disposed')
+ await Promise.all(all.map(task => task.settled))
+ this.store.clear()
+ // Detach cross-fiber owner effects after the shared store is quiescent.
+ const ownerCleanups = [...this.ownerCleanups.values()]
+ this.ownerCleanups.clear()
+ await Promise.all(ownerCleanups.map(cleanup => Promise.resolve(cleanup())))
+ }
+
+ /**
+ * Cancel tasks during teardown with per-task containment. A throwing cancel
+ * force-fails the record and reports a possible orphan; a cancel that returns
+ * without settling remains indistinguishable from a slow stop and may stall.
+ */
+ private cancelForTeardown(tasks: TrackedTask[], reason: string): void {
+ for (const task of tasks) {
+ if (isTerminal(task.status)) continue
+ try {
+ task.cancel(reason)
+ task.status = 'stopping'
+ } catch (error: unknown) {
+ const detail = `cancel threw during teardown; work may be orphaned: ${String(error)}`
+ this.selfCtx.logger.warn(`tasks: cancel of ${task.id} threw during teardown; task record forced failed and work may be orphaned: ${String(error)}`)
+ this.settle(task, { status: 'failed', detail })
+ }
+ }
+ }
+}
+
+export default LocalTaskService
diff --git a/packages/tasks/tasks-local/src/invariant.ts b/packages/tasks/tasks-local/src/invariant.ts
new file mode 100644
index 0000000000..3447287c08
--- /dev/null
+++ b/packages/tasks/tasks-local/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tasks-local`.
+ * @module @deepseek-ai/dsh-tasks-local/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-tasks-local'
+
+/** Cordis companion plugin name. */
+export const name = 'tasks-local-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: the seam companion in `@deepseek-ai/dsh-tasks` already
+ * validates every registry snapshot this implementation publishes.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/tasks/tasks/tests/tasks.spec.ts b/packages/tasks/tasks-local/tests/tasks.spec.ts
similarity index 97%
rename from packages/tasks/tasks/tests/tasks.spec.ts
rename to packages/tasks/tasks-local/tests/tasks.spec.ts
index 015f1c4f2b..d237dbe094 100644
--- a/packages/tasks/tasks/tests/tasks.spec.ts
+++ b/packages/tasks/tasks-local/tests/tasks.spec.ts
@@ -3,8 +3,9 @@ import { Context } from 'cordis'
import { Session, SessionId } from '@deepseek-ai/dsh-session'
import AgentRegistry, { AgentMessageId } from '@deepseek-ai/dsh-agent'
import type { Agent } from '@deepseek-ai/dsh-agent'
-import TaskService, { TaskId } from '@deepseek-ai/dsh-tasks'
+import { TaskId } from '@deepseek-ai/dsh-tasks'
import type { TaskHooks, TaskKind, TaskOutcome, TaskSnapshot, TaskStart } from '@deepseek-ai/dsh-tasks'
+import LocalTaskService from '@deepseek-ai/dsh-tasks-local'
declare module '@deepseek-ai/dsh-tasks' {
interface TaskKindMap {
@@ -65,7 +66,7 @@ function producer(overrides: Partial & TaskHooks> = {}) {
async function harness() {
const ctx = new Context()
await ctx.plugin(AgentRegistry)
- await ctx.plugin(TaskService)
+ await ctx.plugin(LocalTaskService)
ctx.tasks.attachSurface('test-surface')
return ctx
}
@@ -81,14 +82,14 @@ function waitResolverCount(ctx: Context, id: TaskId): number {
return task.waitResolvers.size
}
-describe('TaskService.start', () => {
+describe('LocalTaskService.start', () => {
it('preserves the SessionId brand on public owner snapshots', () => {
expectTypeOf().toEqualTypeOf()
})
it('refuses to register while no control surface is attached', async () => {
const ctx = new Context()
- await ctx.plugin(TaskService)
+ await ctx.plugin(LocalTaskService)
expect(() => ctx.tasks.start(producer().spec))
.toThrow('background tasks unavailable: no control surface is attached (load @deepseek-ai/dsh-tool-tasks)')
})
@@ -109,7 +110,7 @@ describe('TaskService.start', () => {
})
})
-describe('TaskService reads and settlement', () => {
+describe('LocalTaskService reads and settlement', () => {
it('stream kinds read a consuming delta; terminal reads mark reported', async () => {
const ctx = await harness()
const chunks = ['first', '', 'rest']
@@ -229,7 +230,7 @@ describe('TaskService reads and settlement', () => {
})
})
-describe('TaskService.kill', () => {
+describe('LocalTaskService.kill', () => {
it('cancels a live task with the forwarded reason and suppresses the notice', async () => {
const ctx = await harness()
const seen: TaskSnapshot[] = []
@@ -284,7 +285,7 @@ describe('TaskService.kill', () => {
})
})
-describe('TaskService.wait', () => {
+describe('LocalTaskService.wait', () => {
it('resolves with the terminal snapshot when the task settles, marked reported', async () => {
const ctx = await harness()
const seen: TaskSnapshot[] = []
@@ -394,7 +395,7 @@ describe('TaskService.wait', () => {
})
})
-describe('TaskService owner isolation', () => {
+describe('LocalTaskService owner isolation', () => {
it('fences read/kill/wait to the owning session and keeps unowned tasks open', async () => {
const ctx = await harness()
const owner = stubAgent(ctx, 'owner')
@@ -433,7 +434,7 @@ describe('TaskService owner isolation', () => {
it('rejects an owned registration when no agent registry is mounted', async () => {
const ctx = new Context()
- await ctx.plugin(TaskService)
+ await ctx.plugin(LocalTaskService)
ctx.tasks.attachSurface('test-surface')
expect(() => ctx.tasks.start(producer({ owner: stubAgent(ctx, 'a') }).spec))
.toThrow('background task ownership requires the agent registry')
@@ -498,7 +499,7 @@ describe('TaskService owner isolation', () => {
})
})
-describe('TaskService owner cleanup', () => {
+describe('LocalTaskService owner cleanup', () => {
it('drains the owner: cancels live tasks, awaits settlement, drops snapshots', async () => {
const ctx = await harness()
const owner = stubAgent(ctx, 'owner')
@@ -580,7 +581,7 @@ describe('TaskService owner cleanup', () => {
it('registers owner cleanup on the agent scope rather than the tasks fiber', async () => {
const ctx = new Context()
await ctx.plugin(AgentRegistry)
- const tasksFiber = await ctx.plugin(TaskService)
+ const tasksFiber = await ctx.plugin(LocalTaskService)
ctx.tasks.attachSurface('test-surface')
const owner = stubAgent(ctx, 'owner')
ctx.agents.register(owner)
@@ -646,11 +647,11 @@ describe('TaskService owner cleanup', () => {
})
})
-describe('TaskService disposal', () => {
+describe('LocalTaskService disposal', () => {
it('cancels live tasks, awaits settlement, and silences listeners', async () => {
const ctx = new Context()
await ctx.plugin(AgentRegistry)
- const fiber = await ctx.plugin(TaskService)
+ const fiber = await ctx.plugin(LocalTaskService)
const surface = await ctx.plugin(Object.assign((inner: Context) => {
inner.tasks.attachSurface('test-surface')
}, { inject: ['tasks'] }))
@@ -678,7 +679,7 @@ describe('TaskService disposal', () => {
it('force-fails a throwing cancel so service disposal does not await producer done', async () => {
const ctx = new Context()
await ctx.plugin(AgentRegistry)
- const fiber = await ctx.plugin(TaskService)
+ const fiber = await ctx.plugin(LocalTaskService)
ctx.tasks.attachSurface('test-surface')
const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
const seen: TaskSnapshot[] = []
@@ -716,7 +717,7 @@ describe('TaskService disposal', () => {
it('detaches owner effects from still-live agent scopes when the service unloads', async () => {
const ctx = new Context()
await ctx.plugin(AgentRegistry)
- const tasksFiber = await ctx.plugin(TaskService)
+ const tasksFiber = await ctx.plugin(LocalTaskService)
ctx.tasks.attachSurface('test-surface')
const owner = stubAgent(ctx, 'owner')
ctx.agents.register(owner)
@@ -741,7 +742,7 @@ describe('TaskService disposal', () => {
it('detaching the last surface re-arms the register fence', async () => {
const ctx = new Context()
- await ctx.plugin(TaskService)
+ await ctx.plugin(LocalTaskService)
const detachA1 = ctx.tasks.attachSurface('a')
const detachA2 = ctx.tasks.attachSurface('a') // duplicate name counts independently
const fiber = await ctx.plugin(Object.assign((inner: Context) => {
diff --git a/packages/tasks/tasks-local/tsconfig.json b/packages/tasks/tasks-local/tsconfig.json
new file mode 100644
index 0000000000..147e3915bc
--- /dev/null
+++ b/packages/tasks/tasks-local/tsconfig.json
@@ -0,0 +1,30 @@
+{
+ "extends": "../../../tsconfig.base.json",
+ "compilerOptions": {
+ "rootDir": "src",
+ "outDir": "lib/types"
+ },
+ "include": [
+ "src"
+ ],
+ "references": [
+ {
+ "path": "../../../vendor/cosmokit"
+ },
+ {
+ "path": "../../../vendor/cordis"
+ },
+ {
+ "path": "../../core/agent"
+ },
+ {
+ "path": "../../util/timeout"
+ },
+ {
+ "path": "../tasks"
+ },
+ {
+ "path": "../../support/invariants"
+ }
+ ]
+}
diff --git a/packages/tasks/tasks/README.md b/packages/tasks/tasks/README.md
index 1d9ce2b249..f8808f6486 100644
--- a/packages/tasks/tasks/README.md
+++ b/packages/tasks/tasks/README.md
@@ -1,8 +1,8 @@
# @deepseek-ai/dsh-tasks
-The process-local background task registry (`ctx.tasks`). It gives long-running producers shared ids, owner isolation, reads, cancellation, waiting, notices, and cleanup. Producer plugins extend `TaskKindMap` with their opaque id namespace.
+The background task registry seam (`ctx.tasks`). The abstract `TaskService` and its vocabulary types give long-running producers shared ids, owner isolation, reads, cancellation, waiting, notices, and cleanup under one contract; the process-local registry lives in [`dsh-tasks-local`](../tasks-local/README.md). Producer plugins extend `TaskKindMap` with their opaque id namespace.
-## Service API
+## Service contract
- `start(spec): TaskId` validates the control surface, spec, exact live owner, and optional positive `outputLimitBytes` before calling the producer's `run()` once. A starter throw leaves nothing registered; successful return commits without another failable step.
- `get(id, caller?)` and `list(caller?)` return non-consuming snapshots. Listing includes only caller-owned and unowned tasks.
@@ -16,13 +16,9 @@ Owned access compares the task's `SessionId` with the caller's. Ids such as `bas
`outputLimitBytes` is producer-owned model-presentation policy carried unchanged into snapshots. A control surface applies it after adding status or notice metadata; the registry does not rewrite producer output or invent a default for producers that omit it.
-## Lifecycle
+Implementations also owe the lifecycle semantics of the contract: registrations outlive producer and control-surface fibers, owner and service disposal cancel live work and await compliant producers, and settlement is first-wins — one terminal record, one round of contained listener notification, released waiters.
-Tasks belong to their owner and backend, not the producer tool fiber, so producer and surface reloads do not stop them. The first task for an owner attaches one awaited effect to the exact `Agent` scope. Owner disposal cancels that object's tasks, awaits producer quiescence, and removes their snapshots; reused agent or session ids cannot redirect an old cleanup.
-
-Service disposal closes listeners, cancels all live tasks, awaits their records, and detaches effects from surviving owner scopes. If teardown cancellation throws, the service force-fails the record and warns that work may be orphaned instead of deadlocking. A cancellation that returns but never settles `done` remains indistinguishable from a slow stop and can stall teardown.
-
-See the [task type catalog](../../../docs/core-data-structures/tasks.md) and [runtime Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md).
+See the [task type catalog](../../../docs/core-data-structures/tasks.md), the [runtime Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md), and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md).
## Model Experience
@@ -34,8 +30,6 @@ No direct invalidation; the named consumer owns any request-prefix changes.
## Known Limitations and Deferred Work
-- **Tasks are process-local** — durable or cross-restart execution needs a separate lifecycle.
-- **The service and implementation are not split** — a second backend must define the lifecycle that shapes that boundary.
- **Stream output has one consuming cursor** — independent observers need a cursor or snapshot API.
- **Foreground work cannot be promoted** — producers choose foreground or background before starting.
-- **A silently ineffective cancel can stall teardown** — only an explicit throw can be force-failed safely.
+- **The contract is in-process** — `TaskStart.run()` passes callbacks and exact `Agent` objects; a durable or cross-process backend must reshape identity, restart, ownership, and observation semantics before it can implement this seam.
diff --git a/packages/tasks/tasks/package.json b/packages/tasks/tasks/package.json
index 128a8d2c4e..9bc02879cf 100644
--- a/packages/tasks/tasks/package.json
+++ b/packages/tasks/tasks/package.json
@@ -31,7 +31,6 @@
"@deepseek-ai/dsh-brand": "^0.0.1",
"@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
- "@deepseek-ai/dsh-timeout": "^0.0.1",
"cordis": "^4.0.0-rc.6"
},
"devDependencies": {
@@ -39,7 +38,6 @@
"@deepseek-ai/dsh-brand": "workspace:^",
"@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
- "@deepseek-ai/dsh-timeout": "workspace:^",
"cordis": "^4.0.0-rc.6"
}
}
diff --git a/packages/tasks/tasks/src/index.ts b/packages/tasks/tasks/src/index.ts
index 16f0807656..17e617e8a7 100644
--- a/packages/tasks/tasks/src/index.ts
+++ b/packages/tasks/tasks/src/index.ts
@@ -1,19 +1,14 @@
/**
- * The in-process background task registry (`ctx.tasks`). It owns task ids,
- * session-scoped access, lifecycle state, completion listeners, and owner
- * cleanup while producers retain their execution resources.
- *
- * Registrations outlive producer and control-surface fibers. Agent or service
- * disposal cancels live work and awaits compliant producers; a throwing
- * teardown cancel force-fails only the record and reports a possible orphan.
+ * The background task registry seam (`ctx.tasks`). It owns the contract for
+ * task ids, session-scoped access, lifecycle state, completion listeners, and
+ * owner cleanup while producers retain their execution resources. The
+ * process-local registry lives in `@deepseek-ai/dsh-tasks-local`.
* @module @deepseek-ai/dsh-tasks
*/
import { Context, Service } from 'cordis'
import type { Agent } from '@deepseek-ai/dsh-agent'
-import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
-import { TaskId } from './types.ts'
-import type { TaskDoneListener, TaskKind, TaskOutcome, TaskRead, TaskSnapshot, TaskStart, TaskStatus } from './types.ts'
+import type { TaskDoneListener, TaskId, TaskRead, TaskSnapshot, TaskStart } from './types.ts'
export { TaskId } from './types.ts'
export type {
@@ -34,61 +29,27 @@ declare module 'cordis' {
}
}
-/** Timeout code that distinguishes a bounded wait from caller cancellation. */
-export const TASK_WAIT_TIMEOUT = 'TASK_WAIT_TIMEOUT'
-
-/** The registry's mutable per-task record (never handed out — see {@link TaskService.snapshot}). */
-interface TrackedTask {
- id: TaskId
- kind: TaskKind
- label: string
- outputLimitBytes: number | undefined
- /** Exact lifecycle owner; session-id authorization is derived from it. */
- owner: Agent | undefined
- cancel: (reason?: string) => void
- readOutput: (() => string) | undefined
- status: TaskStatus
- detail: string | undefined
- output: string | undefined
- startedAt: number
- finishedAt: number | undefined
- reported: boolean
- /** Resolves once the terminal snapshot is recorded and listeners notified. */
- settled: Promise
- /** Resolver for {@link settled}, called by the first effective settlement. */
- markSettled: () => void
- /** Live waits; settlement with a waiter marks the task reported. */
- waiters: number
- /** Removable resolvers for live waits; timeout/abort unregister before the task settles. */
- waitResolvers: Set<() => void>
-}
-
-/** True for the three terminal {@link TaskStatus} values. */
-function isTerminal(status: TaskStatus): boolean {
- return status === 'completed' || status === 'killed' || status === 'failed'
-}
-
/**
- * The `tasks` service: the runtime-global background task registry. See the
- * module doc for the ownership, isolation, and lifecycle contracts.
+ * Abstract background task registry. Subclass, implement the abstract methods,
+ * and load the subclass as a plugin — it registers as `ctx.tasks` (one
+ * implementation per context; loading a second throws, which is cordis'
+ * standard duplicate-service behavior).
+ *
+ * Implementations must honor these semantics:
+ * - Registrations outlive producer and control-surface fibers. Owner and
+ * service disposal cancel live work and await compliant producers; a
+ * throwing teardown cancel force-fails only the record.
+ * - Owned-task access is fenced by the owner's session id. Ids are
+ * predictable, so authorization — not secrecy — is the boundary.
+ * - Settlement is first-wins: one terminal record, one round of contained
+ * listener notification, and released waiters, even against a late
+ * producer outcome.
+ * - {@link start} refuses work while no control surface is attached, so a
+ * producer cannot start work that callers cannot collect or stop.
*/
-// TODO(task-service-backend): Separate the service contract from this
-// process-local implementation when a second backend defines its lifecycle.
-export class TaskService extends Service {
- private store = new Map()
- private counters = new Map()
- private surfaces = new Set()
- private listeners = new Set()
- private listenersClosed = false
- /** Owner agents with attached scope cleanup, mapped to the exact disposer. */
- private ownerCleanups = new Map Promise | void>()
- /** Service context used by detached settlement continuations and teardown. */
- private readonly selfCtx: Context
-
+export abstract class TaskService extends Service {
constructor(ctx: Context) {
super(ctx, 'tasks')
- this.selfCtx = ctx
- ctx.effect(() => () => this.disposeAll(), 'tasks teardown')
}
/**
@@ -99,56 +60,7 @@ export class TaskService extends Service {
* @param spec - task identity, owner, and synchronous starter.
* @returns the registry-issued `-N` id.
*/
- start(spec: TaskStart): TaskId {
- if (this.surfaces.size === 0) {
- throw new Error('background tasks unavailable: no control surface is attached (load @deepseek-ai/dsh-tool-tasks)')
- }
- if (spec.kind.length === 0) throw new Error('invalid task kind: expected a non-empty string')
- if (spec.label.length === 0) throw new Error('invalid task label: expected a non-empty string')
- if (spec.outputLimitBytes !== undefined
- && (!Number.isSafeInteger(spec.outputLimitBytes) || spec.outputLimitBytes <= 0)) {
- throw new Error(`invalid outputLimitBytes: expected a positive safe integer, got ${JSON.stringify(spec.outputLimitBytes)}`)
- }
- if (spec.owner !== undefined) this.ensureOwnerCleanup(spec.owner)
-
- const hooks = spec.run()
- const count = (this.counters.get(spec.kind) ?? 0) + 1
- this.counters.set(spec.kind, count)
- const id = TaskId(`${spec.kind}-${count}`)
-
- let markSettled!: () => void
- const settled = new Promise((resolve) => { markSettled = resolve })
- const task: TrackedTask = {
- id,
- kind: spec.kind,
- label: spec.label,
- outputLimitBytes: spec.outputLimitBytes,
- owner: spec.owner,
- cancel: hooks.cancel.bind(hooks),
- readOutput: hooks.readOutput?.bind(hooks),
- status: 'running',
- detail: undefined,
- output: undefined,
- startedAt: Date.now(),
- finishedAt: undefined,
- reported: false,
- settled,
- markSettled,
- waiters: 0,
- waitResolvers: new Set(),
- }
- this.store.set(id, task)
-
- void hooks.done.then(
- (outcome) => { this.settle(task, outcome) },
- (error: unknown) => {
- // Contain a producer contract violation so cleanup and waiters cannot hang.
- this.selfCtx.logger.warn(`tasks: task ${task.id} 'done' rejected (producer contract violation): ${String(error)}`)
- this.settle(task, { status: 'failed', detail: String(error) })
- },
- )
- return id
- }
+ abstract start(spec: TaskStart): TaskId
/**
* List caller-owned and unowned tasks in registration order without exposing
@@ -156,12 +68,7 @@ export class TaskService extends Service {
* @param caller - reading agent; a non-agent caller sees only unowned tasks.
* @returns fresh snapshots.
*/
- list(caller?: Agent): TaskSnapshot[] {
- const session = caller?.id
- return [...this.store.values()]
- .filter(task => task.owner === undefined || task.owner.id === session)
- .map(task => this.snapshot(task))
- }
+ abstract list(caller?: Agent): TaskSnapshot[]
/**
* Return a non-consuming snapshot without changing its read cursor or notice
@@ -170,11 +77,7 @@ export class TaskService extends Service {
* @param caller - reading agent checked against the owner.
* @returns a fresh snapshot.
*/
- get(id: TaskId, caller?: Agent): TaskSnapshot {
- const task = this.expect(id)
- this.assertAccess(task, caller)
- return this.snapshot(task)
- }
+ abstract get(id: TaskId, caller?: Agent): TaskSnapshot
/**
* Read the next stream delta, or the idempotent final output after settlement.
@@ -184,15 +87,7 @@ export class TaskService extends Service {
* @param caller - reading agent checked against the owner.
* @returns output text and the post-read snapshot.
*/
- read(id: TaskId, caller?: Agent): TaskRead {
- const task = this.expect(id)
- this.assertAccess(task, caller)
- const text = task.readOutput !== undefined
- ? task.readOutput()
- : isTerminal(task.status) ? task.output ?? '' : ''
- if (isTerminal(task.status)) task.reported = true
- return { text, snapshot: this.snapshot(task) }
- }
+ abstract read(id: TaskId, caller?: Agent): TaskRead
/**
* Request cancellation, then mark the task stopping and reported. A producer
@@ -203,81 +98,20 @@ export class TaskService extends Service {
* @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' {
- const task = this.expect(id)
- this.assertAccess(task, caller)
- if (isTerminal(task.status)) {
- task.reported = true
- return 'already-finished'
- }
- // Cancel first so a throw leaves both lifecycle and notice state unchanged.
- task.cancel(reason)
- task.status = 'stopping'
- task.reported = true
- return 'requested'
- }
+ abstract kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-finished'
/**
* 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.
+ * rejects only while the task is live; after settlement the terminal
+ * snapshot wins so a notice suppressed for this waiter is still delivered.
+ * 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 {
- const task = this.expect(id)
- this.assertAccess(task, caller)
- if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
- throw new Error(`invalid wait timeout: expected a positive number of milliseconds, got ${JSON.stringify(timeoutMs)}`)
- }
- if (!isTerminal(task.status)) {
- if (signal?.aborted) throw new Error('wait aborted')
- // Abort removes the waiter synchronously so same-tick settlement cannot
- // suppress a notice for a wait that will reject.
- task.waiters += 1
- let counted = true
- const uncount = (): void => {
- if (!counted) return
- counted = false
- task.waiters -= 1
- }
- try {
- // The scoped deadline distinguishes a successful wait timeout from
- // caller cancellation and clears its timer on every exit.
- using d = deadline(signal, timeoutMs, TASK_WAIT_TIMEOUT)
- await new Promise((resolve, reject) => {
- const onSettled = (): void => {
- task.waitResolvers.delete(onSettled)
- d.signal.removeEventListener('abort', onAbort)
- resolve()
- }
- const onAbort = (): void => {
- task.waitResolvers.delete(onSettled)
- if (timeoutOf(d.signal, TASK_WAIT_TIMEOUT) !== undefined) {
- resolve()
- } else if (isTerminal(task.status)) {
- // Settlement suppressed the notice for this waiter; deliver it.
- resolve()
- } else {
- uncount()
- reject(new Error('wait aborted'))
- }
- }
- task.waitResolvers.add(onSettled)
- d.signal.addEventListener('abort', onAbort, { once: true })
- })
- } finally {
- uncount()
- }
- }
- if (isTerminal(task.status)) task.reported = true
- return this.snapshot(task)
- }
+ abstract wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise
/**
* Register an effect-scoped completion listener. Each listener is contained;
@@ -286,13 +120,7 @@ export class TaskService extends Service {
* @param listener - receives each terminal snapshot and its exact owner.
* @returns disposer that unregisters the listener.
*/
- onTaskDone(listener: TaskDoneListener): () => void {
- const dispose = this.ctx.effect(() => {
- this.listeners.add(listener)
- return () => this.listeners.delete(listener)
- }, 'tasks.onTaskDone()')
- return () => void dispose()
- }
+ abstract onTaskDone(listener: TaskDoneListener): () => void
/**
* Attach an effect-scoped surface that can read and stop tasks. {@link start}
@@ -300,149 +128,7 @@ export class TaskService extends Service {
* @param name - diagnostic label; duplicate names remain independent.
* @returns disposer that detaches this surface.
*/
- attachSurface(name: string): () => void {
- // One token per call keeps duplicate labels independently disposable.
- const token = Symbol(name)
- const dispose = this.ctx.effect(() => {
- this.surfaces.add(token)
- return () => this.surfaces.delete(token)
- }, 'tasks.attachSurface()')
- return () => void dispose()
- }
-
- /** Look up a task or fail loud. */
- private expect(id: TaskId): TrackedTask {
- const task = this.store.get(id)
- if (task === undefined) throw new Error(`unknown task ${id}`)
- return task
- }
-
- /**
- * The isolation fence: a task with an owner is reachable only by callers
- * whose session id matches (`!== undefined` semantics — an unowned task is
- * open, and a no-agent caller can never match an owned one).
- */
- private assertAccess(task: TrackedTask, caller?: Agent): void {
- if (task.owner !== undefined && task.owner.id !== caller?.id) {
- throw new Error(`task ${task.id} belongs to another session`)
- }
- }
-
- /** Project a fresh read-only snapshot from the mutable record. */
- private snapshot(task: TrackedTask): TaskSnapshot {
- const ownerSession = task.owner?.id
- return {
- id: task.id,
- kind: task.kind,
- label: task.label,
- ...task.outputLimitBytes !== undefined ? { outputLimitBytes: task.outputLimitBytes } : {},
- ...ownerSession !== undefined ? { ownerSession } : {},
- status: task.status,
- ...task.detail !== undefined ? { detail: task.detail } : {},
- startedAt: task.startedAt,
- ...task.finishedAt !== undefined ? { finishedAt: task.finishedAt } : {},
- reported: task.reported,
- }
- }
-
- /**
- * Record the first terminal outcome, notify contained listeners, and release
- * waiters. First-wins preserves a teardown force-failure against late producer
- * settlement. Pending waits mark the task reported before listeners run.
- */
- private settle(task: TrackedTask, outcome: TaskOutcome): void {
- if (isTerminal(task.status)) return
- task.status = outcome.status
- task.detail = outcome.detail
- task.output = outcome.output
- task.finishedAt = Date.now()
- if (task.waiters > 0) task.reported = true
- if (!this.listenersClosed) {
- const snapshot = this.snapshot(task)
- for (const listener of this.listeners) {
- try {
- const returned = listener(snapshot, task.owner)
- void Promise.resolve(returned).catch((error: unknown) => {
- this.selfCtx.logger.warn(`tasks: onTaskDone listener rejected for ${task.id}: ${String(error)}`)
- })
- } catch (error: unknown) {
- this.selfCtx.logger.warn(`tasks: onTaskDone listener threw for ${task.id}: ${String(error)}`)
- }
- }
- }
- const waitResolvers = [...task.waitResolvers]
- task.waitResolvers.clear()
- for (const resolveWait of waitResolvers) resolveWait()
- task.markSettled()
- }
-
- /**
- * Attach one awaited cleanup through the exact owner's scope. This survives
- * producer reloads and joins agent quiescence; the retained disposer lets
- * service teardown detach the cross-fiber effect. Fails when the registry is
- * absent or the owner is not its currently registered instance.
- */
- private ensureOwnerCleanup(owner: Agent): void {
- const ownerId = owner.id
- const agents = this.selfCtx.get('agents')
- if (agents === undefined) {
- throw new Error('background task ownership requires the agent registry (load @deepseek-ai/dsh-agent)')
- }
- if (agents.get(ownerId) !== owner) {
- throw new Error(`agent "${ownerId}" is not the registered agent instance (background task owner must be live)`)
- }
- if (this.ownerCleanups.has(owner)) return
- // Record only after attach succeeds; a disposing scope rejects new effects.
- const detach = owner.ctx.effect(() => async () => {
- this.ownerCleanups.delete(owner)
- await this.disposeOwned(owner)
- }, 'tasks.ownerCleanup()')
- this.ownerCleanups.set(owner, detach)
- }
-
- /** Cancel, await terminal records, and drop every task owned by one exact agent lifecycle. */
- private async disposeOwned(owner: Agent): Promise {
- const owned = [...this.store.values()].filter(task => task.owner === owner)
- this.cancelForTeardown(owned, 'owner disposed')
- await Promise.all(owned.map(task => task.settled))
- for (const task of owned) this.store.delete(task.id)
- }
-
- /**
- * Close listeners, cancel live tasks, await settlement, and detach owner
- * effects. Throwing cancels are force-failed to avoid teardown deadlock.
- */
- private async disposeAll(): Promise {
- this.listenersClosed = true
- this.listeners.clear()
- const all = [...this.store.values()]
- this.cancelForTeardown(all, 'tasks service disposed')
- await Promise.all(all.map(task => task.settled))
- this.store.clear()
- // Detach cross-fiber owner effects after the shared store is quiescent.
- const ownerCleanups = [...this.ownerCleanups.values()]
- this.ownerCleanups.clear()
- await Promise.all(ownerCleanups.map(cleanup => Promise.resolve(cleanup())))
- }
-
- /**
- * Cancel tasks during teardown with per-task containment. A throwing cancel
- * force-fails the record and reports a possible orphan; a cancel that returns
- * without settling remains indistinguishable from a slow stop and may stall.
- */
- private cancelForTeardown(tasks: TrackedTask[], reason: string): void {
- for (const task of tasks) {
- if (isTerminal(task.status)) continue
- try {
- task.cancel(reason)
- task.status = 'stopping'
- } catch (error: unknown) {
- const detail = `cancel threw during teardown; work may be orphaned: ${String(error)}`
- this.selfCtx.logger.warn(`tasks: cancel of ${task.id} threw during teardown; task record forced failed and work may be orphaned: ${String(error)}`)
- this.settle(task, { status: 'failed', detail })
- }
- }
- }
+ abstract attachSurface(name: string): () => void
}
export default TaskService
diff --git a/packages/tasks/tasks/tests/service.spec.ts b/packages/tasks/tasks/tests/service.spec.ts
new file mode 100644
index 0000000000..d8d582e410
--- /dev/null
+++ b/packages/tasks/tasks/tests/service.spec.ts
@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { TaskId, TaskService } from '@deepseek-ai/dsh-tasks'
+import type { TaskDoneListener, TaskRead, TaskSnapshot, TaskStart } from '@deepseek-ai/dsh-tasks'
+
+/**
+ * Minimal concrete registry: one canned record. The seam owns the contract
+ * only (ids, snapshots, authorization-shaped signatures); the registry
+ * behavior suite lives with `@deepseek-ai/dsh-tasks-local`.
+ */
+class StubTaskService extends TaskService {
+ snapshotOf(id: TaskId): TaskSnapshot {
+ return {
+ id,
+ kind: 'bash',
+ label: 'sleep 60',
+ status: 'running',
+ startedAt: 0,
+ reported: false,
+ }
+ }
+
+ start(spec: TaskStart): TaskId {
+ spec.run()
+ return TaskId(`${spec.kind}-1`)
+ }
+
+ list(): TaskSnapshot[] {
+ return [this.snapshotOf(TaskId('bash-1'))]
+ }
+
+ get(id: TaskId): TaskSnapshot {
+ return this.snapshotOf(id)
+ }
+
+ read(id: TaskId): TaskRead {
+ return { text: '', snapshot: this.snapshotOf(id) }
+ }
+
+ kill(): 'requested' | 'already-finished' {
+ return 'requested'
+ }
+
+ wait(id: TaskId, _timeoutMs: number, _caller?: Agent, _signal?: AbortSignal): Promise {
+ return Promise.resolve(this.snapshotOf(id))
+ }
+
+ onTaskDone(_listener: TaskDoneListener): () => void {
+ return () => {}
+ }
+
+ attachSurface(_name: string): () => void {
+ return () => {}
+ }
+}
+
+describe('TaskService seam', () => {
+ it('a concrete subclass registers as ctx.tasks and serves the abstract API', async () => {
+ const ctx = new Context()
+ await ctx.plugin(StubTaskService)
+
+ const detachSurface = ctx.tasks.attachSurface('seam-test')
+ const id = ctx.tasks.start({ kind: 'bash', label: 'sleep 60', run: () => ({ cancel() {}, done: new Promise(() => {}) }) })
+ expect(id).toBe('bash-1')
+ expect(ctx.tasks.list()).toHaveLength(1)
+ expect(ctx.tasks.get(id).status).toBe('running')
+ expect(ctx.tasks.read(id).text).toBe('')
+ expect(ctx.tasks.kill(id)).toBe('requested')
+ await expect(ctx.tasks.wait(id, 5)).resolves.toMatchObject({ id })
+ const detachListener = ctx.tasks.onTaskDone(() => {})
+ detachListener()
+ detachSurface()
+ })
+
+ it('loading a second implementation throws (one tasks service per context — cordis standard)', async () => {
+ const ctx = new Context()
+ await ctx.plugin(StubTaskService)
+ class SecondTaskService extends StubTaskService {}
+ await expect(ctx.plugin(SecondTaskService)).rejects.toThrow(/service "tasks" has been registered/)
+ })
+})
diff --git a/packages/tasks/tasks/tsconfig.json b/packages/tasks/tasks/tsconfig.json
index e29262ca74..75ade66b8c 100644
--- a/packages/tasks/tasks/tsconfig.json
+++ b/packages/tasks/tasks/tsconfig.json
@@ -23,9 +23,6 @@
{
"path": "../../core/session"
},
- {
- "path": "../../util/timeout"
- },
{
"path": "../../support/invariants"
}
diff --git a/packages/tasks/tool-tasks/package.json b/packages/tasks/tool-tasks/package.json
index 2e03fb26a2..2fd0b464a4 100644
--- a/packages/tasks/tool-tasks/package.json
+++ b/packages/tasks/tool-tasks/package.json
@@ -46,6 +46,7 @@
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-system-prompt": "workspace:^",
"@deepseek-ai/dsh-tasks": "workspace:^",
+ "@deepseek-ai/dsh-tasks-local": "workspace:^",
"@deepseek-ai/dsh-tools": "workspace:^",
"cordis": "^4.0.0-rc.6"
}
diff --git a/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts b/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
index c41f498472..8494ff7f81 100644
--- a/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
+++ b/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
@@ -6,7 +6,8 @@ import ToolRegistry from '@deepseek-ai/dsh-tools'
import AgentRegistry from '@deepseek-ai/dsh-agent'
import type { Agent } from '@deepseek-ai/dsh-agent'
import { SessionId } from '@deepseek-ai/dsh-session'
-import TaskService, { TaskId } from '@deepseek-ai/dsh-tasks'
+import { TaskId } from '@deepseek-ai/dsh-tasks'
+import LocalTaskService from '@deepseek-ai/dsh-tasks-local'
import type { TaskHooks, TaskOutcome, TaskSnapshot, TaskStart } from '@deepseek-ai/dsh-tasks'
import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
import { statusLine } from '@deepseek-ai/dsh-tool-tasks'
@@ -20,7 +21,7 @@ async function setup(config: ToolTasks.Config = {}) {
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
const agentsFiber = await ctx.plugin(AgentRegistry)
- await ctx.plugin(TaskService)
+ await ctx.plugin(LocalTaskService)
const toolsFiber = await ctx.plugin(ToolTasks, config)
return { ctx, agentsFiber, toolsFiber }
}
@@ -91,7 +92,7 @@ describe('tool-tasks setup', () => {
const ctx = new Context()
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
- await ctx.plugin(TaskService)
+ await ctx.plugin(LocalTaskService)
await expect(ctx.plugin(ToolTasks, { waitTimeoutMs: 100, maxWaitTimeoutMs: 50 }))
.rejects.toThrow('waitTimeoutMs (100) exceeds maxWaitTimeoutMs (50)')
})
@@ -108,7 +109,7 @@ describe('tool-tasks setup', () => {
const ctx = new Context()
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
- await ctx.plugin(TaskService)
+ await ctx.plugin(LocalTaskService)
ToolTasks.apply(ctx, {})
expect(ctx.tools.get('task_output')).toBeDefined()
expect(() => ctx.tasks.start(producer().spec)).not.toThrow()
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 7894b009ad..5ed728d64d 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -227,9 +227,9 @@ importers:
'@deepseek-ai/dsh-system-prompt':
specifier: workspace:^
version: link:../../packages/core/system-prompt
- '@deepseek-ai/dsh-tasks':
+ '@deepseek-ai/dsh-tasks-local':
specifier: workspace:^
- version: link:../../packages/tasks/tasks
+ version: link:../../packages/tasks/tasks-local
'@deepseek-ai/dsh-timeout-policy':
specifier: workspace:^
version: link:../../packages/timeout/timeout-policy
@@ -472,6 +472,9 @@ importers:
'@deepseek-ai/dsh-subagent-spawn':
specifier: workspace:*
version: link:../packages/subagent/subagent-spawn
+ '@deepseek-ai/dsh-tasks-local':
+ specifier: workspace:*
+ version: link:../packages/tasks/tasks-local
'@deepseek-ai/dsh-time-context':
specifier: workspace:*
version: link:../packages/context/time-context
@@ -686,6 +689,9 @@ importers:
'@deepseek-ai/dsh-tasks':
specifier: workspace:^
version: link:../../tasks/tasks
+ '@deepseek-ai/dsh-tasks-local':
+ specifier: workspace:^
+ version: link:../../tasks/tasks-local
'@deepseek-ai/dsh-tool-tasks':
specifier: workspace:^
version: link:../../tasks/tool-tasks
@@ -1658,6 +1664,9 @@ importers:
'@deepseek-ai/dsh-tasks':
specifier: workspace:^
version: link:../../tasks/tasks
+ '@deepseek-ai/dsh-tasks-local':
+ specifier: workspace:^
+ version: link:../../tasks/tasks-local
'@deepseek-ai/dsh-tool-bash':
specifier: workspace:^
version: link:../../bash/tool-bash
@@ -2698,6 +2707,9 @@ importers:
'@deepseek-ai/dsh-tasks':
specifier: workspace:^
version: link:../../tasks/tasks
+ '@deepseek-ai/dsh-tasks-local':
+ specifier: workspace:^
+ version: link:../../tasks/tasks-local
'@deepseek-ai/dsh-tool-tasks':
specifier: workspace:^
version: link:../../tasks/tool-tasks
@@ -3612,6 +3624,9 @@ importers:
'@deepseek-ai/dsh-tasks':
specifier: workspace:^
version: link:../../tasks/tasks
+ '@deepseek-ai/dsh-tasks-local':
+ specifier: workspace:^
+ version: link:../../tasks/tasks-local
'@deepseek-ai/dsh-tool-tasks':
specifier: workspace:^
version: link:../../tasks/tool-tasks
@@ -3729,11 +3744,32 @@ importers:
'@deepseek-ai/dsh-session':
specifier: workspace:^
version: link:../../core/session
+ cordis:
+ specifier: ^4.0.0-rc.6
+ version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+
+ packages/tasks/tasks-local:
+ devDependencies:
+ '@deepseek-ai/dsh-agent':
+ specifier: workspace:^
+ version: link:../../core/agent
+ '@deepseek-ai/dsh-brand':
+ specifier: workspace:^
+ version: link:../../util/brand
+ '@deepseek-ai/dsh-invariants':
+ specifier: workspace:^
+ version: link:../../support/invariants
+ '@deepseek-ai/dsh-session':
+ specifier: workspace:^
+ version: link:../../core/session
+ '@deepseek-ai/dsh-tasks':
+ specifier: workspace:^
+ version: link:../tasks
'@deepseek-ai/dsh-timeout':
specifier: workspace:^
version: link:../../util/timeout
cordis:
- specifier: ^4.0.0-rc.6
+ specifier: ^4.0.0-rc.7
version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
packages/tasks/tool-tasks:
@@ -3763,6 +3799,9 @@ importers:
'@deepseek-ai/dsh-tasks':
specifier: workspace:^
version: link:../tasks
+ '@deepseek-ai/dsh-tasks-local':
+ specifier: workspace:^
+ version: link:../tasks-local
'@deepseek-ai/dsh-tools':
specifier: workspace:^
version: link:../../core/tools
@@ -4615,6 +4654,9 @@ importers:
'@deepseek-ai/dsh-tasks':
specifier: workspace:^
version: link:../../packages/tasks/tasks
+ '@deepseek-ai/dsh-tasks-local':
+ specifier: workspace:^
+ version: link:../../packages/tasks/tasks-local
'@deepseek-ai/dsh-timeout':
specifier: workspace:^
version: link:../../packages/util/timeout
diff --git a/python/sdk-runtime/package.json b/python/sdk-runtime/package.json
index 8a8d31c815..abf943793d 100644
--- a/python/sdk-runtime/package.json
+++ b/python/sdk-runtime/package.json
@@ -66,6 +66,7 @@
"@deepseek-ai/dsh-subagent-subprocess": "workspace:^",
"@deepseek-ai/dsh-system-prompt": "workspace:^",
"@deepseek-ai/dsh-tasks": "workspace:^",
+ "@deepseek-ai/dsh-tasks-local": "workspace:^",
"@deepseek-ai/dsh-timeout": "workspace:^",
"@deepseek-ai/dsh-timeout-policy": "workspace:^",
"@deepseek-ai/dsh-tool-ask-user": "workspace:^",
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 4c8817f318..2551f95df9 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -365,9 +365,10 @@ const SERVICE_ROLES: ServiceRole[] = [
key: 'tasks',
pkg: 'tasks',
title: 'Background task registry',
- mode: 'core',
+ mode: 'seam',
+ implementations: ['tasks-local'],
consumers: ['tool-bash', 'tool-pty', 'tool-subagent', 'tool-tasks'],
- note: 'Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it.',
+ note: 'Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it; tasks-local is the process-local registry.',
},
{
key: 'web',
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index 3bbfd5b1ea..45aa58d74e 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -29,7 +29,7 @@ import SubagentService from '@deepseek-ai/dsh-subagent'
import type { SubagentProvider } from '@deepseek-ai/dsh-subagent'
import SkillService from '@deepseek-ai/dsh-skill'
import * as SkillLocal from '@deepseek-ai/dsh-skill-local'
-import TaskService from '@deepseek-ai/dsh-tasks'
+import LocalTaskService from '@deepseek-ai/dsh-tasks-local'
import * as ToolAskUser from '@deepseek-ai/dsh-tool-ask-user'
import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis'
@@ -355,7 +355,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
requires: ['ctx.tools', 'ctx.tasks', 'ctx.systemPrompt'],
writes: ['tool/call', 'tool/result', 'user/message via agent.inject() for background completion notices'],
async mount(ctx) {
- await ctx.plugin(TaskService)
+ await ctx.plugin(LocalTaskService)
await ctx.plugin(ToolTasks)
},
note:
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index d68df7adcd..16803b157f 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -93,6 +93,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly> = {
'packages/support/llm-mock-server': { kind: 'none', reason: 'The test server substitutes provider wire behavior without invoking a real model.' },
'packages/support/llm-replay': { kind: 'none', reason: 'The keyless adapter invokes no provider model.' },
'packages/tasks/tasks': { kind: 'indirect', reason: 'Producer and control-surface plugins own all model rendering over the task registry.' },
+ 'packages/tasks/tasks-local': { kind: 'indirect', reason: 'The registry backend delegates model rendering to producer plugins and dsh-tool-tasks.' },
'packages/examples/acp-demo': { kind: 'indirect', reason: 'The app bundle delegates request composition to dsh-agent-spine-demo and dsh-acp.' },
'packages/ui/app-boot': { kind: 'indirect', reason: 'Only the loaded plugin tree contributes model context.' },
'packages/examples/jsonrpc-demo': { kind: 'indirect', reason: 'Only the externally configured plugin tree contributes model context.' },
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 3a5441120b..1aab67964a 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -135,6 +135,7 @@
{ "path": "./packages/subagent/subagent-fork" },
{ "path": "./packages/subagent/subagent-acp" },
{ "path": "./packages/tasks/tasks" },
+ { "path": "./packages/tasks/tasks-local" },
{ "path": "./packages/tasks/tool-tasks" },
{ "path": "./packages/workflow/workflow" },
{ "path": "./packages/workflow/workflow-workerthread" },