@deepseek-ai/dsh-jobs 0.0.1-rc.3

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/jobs/jobs/README.md
+README.md: f4469286603f687be5789bd016ab462dba26e664
+README.zh.md: 720c8b550b52716ef66d182da0acf81eae4490ca

package/README.md

@@ -0,0 +1,40 @@
+# @deepseek-ai/dsh-jobs
+
+English | [中文](README.zh.md)
+
+The background job registry contract (`ctx.jobs`). The abstract `JobRegistry` 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-jobs-local`](../jobs-local/README.md). Producer plugins extend `JobKindMap` with their opaque id namespace.
+
+## Service contract
+
+- `start(spec): JobId` validates the attached controller, spec, exact live owner, optional positive `outputLimitBytes`, and any provider-owned admission policy before calling the producer's `run()` once. A preflight rejection or starter throw leaves no job id or registered work; successful return commits without another failable step.
+- `get(id, caller?)` and `list(caller?)` return non-consuming snapshots. Listing includes only caller-owned and unowned jobs.
+- `read(id, caller?)` consumes the single cursor for stream jobs and reads terminal output idempotently for final-output jobs.
+- `kill(id, caller?, reason?)` invokes producer cancellation before changing status. A cancellation throw leaves the job running; success changes it to `stopping` and marks terminal delivery reported.
+- `wait(id, timeoutMs, caller?, signal?)` returns a terminal snapshot or the live snapshot at timeout. Aborting stops only the wait; settlement wins once it has committed terminal delivery to that waiter.
+- `onJobDone(listener)` observes each terminal record with the exact owner. Listener throws and rejections are contained; listener work is not awaited.
+- `onJobsChanged(listener)` observes visible-set changes — registration, every stopping transition (teardown's included, before it awaits a slow producer), settlement, owner-disposal removal, and the emptying service disposal commits — carrying only the owner whose set moved, or `undefined` when an unowned job changed and every caller's set moved with it. It is owner-granular because removal is a change no per-job record can express, and it is not a superset of `onJobDone`: it carries no delivery meaning and marks nothing reported. The registration binds to the calling fiber, so an observer mounted outside the registry still sees the disposal emptying.
+- `attachController(name)` declares a job controller for its effect lifetime. `start()` fails before producer execution when no attached controller serves the spec's owner.
+
+All three registrations are owner-relative, because one registry serves every composition in the process. A controller or listener registered from an unscoped context serves every owner; one registered under an agent composition's scope serves exactly the agents composed under it. So a composition that loads no controller cannot start background work on the strength of another composition's controls, and one settlement notifies only the listeners its owner's composition registered.
+
+Owned access compares the job's `SessionId` with the caller's. Ids such as `bash-1` are predictable, so this fence is the boundary. Unowned jobs are open to callers and last until service disposal.
+
+`outputLimitBytes` is producer-owned model-presentation policy carried unchanged into snapshots. A controller applies it after adding status or notice metadata; the registry does not rewrite producer output or invent a default for producers that omit it.
+
+Implementations also owe the lifecycle semantics of the contract: registrations outlive producer and controller 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.
+
+See the [job type catalog](../../../docs/subsystems/jobs.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-job-registry-seam.md).
+
+## Model Experience
+
+Indirectly, through producer plugins and [`dsh-tool-jobs`](../tool-jobs/README.md), which render job 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
+
+- **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.
+- **The contract is in-process** — `JobStart.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.

package/README.zh.md

@@ -0,0 +1,40 @@
+# @deepseek-ai/dsh-jobs
+
+[English](README.md) | 中文
+
+后台任务注册表约定（`ctx.jobs`）。抽象的 `JobRegistry` 及其词汇类型在同一份约定下为长时间运行的生产方提供共享 id、owner 隔离、读取、取消、等待、通知和清理；进程局部注册表位于 [`dsh-jobs-local`](../jobs-local/README.md)。生产方插件使用其不透明 id namespace 扩展 `JobKindMap`。
+
+## 服务约定
+
+- `start(spec): JobId` 验证已附加的任务控制器、spec、确切且仍存活的 owner、可选的正数 `outputLimitBytes`，以及 Service provider 所拥有的准入策略，然后只调用生产方的 `run()` 一次。预检拒绝或启动方抛出异常时都不会生成 job id 或注册工作；成功返回会直接提交，不再执行其他可能失败的步骤。
+- `get(id, caller?)` 和 `list(caller?)` 返回非消费式快照。列表只包含调用方拥有及无 owner 的任务。
+- `read(id, caller?)` 消费流任务的唯一游标；对于最终输出任务，则以幂等方式读取终止输出。
+- `kill(id, caller?, reason?)` 在更改状态前调用生产方取消。取消抛出异常时任务保持运行；成功则把状态改为 `stopping`，并将终止交付标记为已报告。
+- `wait(id, timeoutMs, caller?, signal?)` 返回终止快照，或在超时时返回存活快照。中止只会停止等待；一旦终止交付已向该等待方提交，终止结果优先。
+- `onJobDone(listener)` 观察每条终止记录及其精确 owner。监听器抛出的异常和产生的拒绝都会被隔离；系统不会等待监听器工作。
+- `onJobsChanged(listener)` 观察可见集合的变化——注册、每一次转入 stopping（包括 teardown 在等待缓慢生产者之前的那一次）、结算、owner 销毁时的移除，以及服务销毁提交的清空——只携带集合发生变化的那个 owner，或在无主任务变化、因而每个调用方的集合都随之变化时携带 `undefined`。它按 owner 分粒度，因为移除是任何逐任务记录都无法表达的变化；它也不是 `onJobDone` 的超集：它不含任何投递含义，也不把任何东西标为已上报。注册绑定的是调用方 fiber，因此挂在注册表之外的观察者仍能收到销毁时的清空。
+- `attachController(name)` 在其 effect 生命周期内声明任务控制器。当没有任何已附加的控制器服务于 spec 的所有者时，`start()` 会在生产方执行前失败。
+
+这三类注册都是相对于所有者的，因为一个注册表要服务进程内的每一套组合。从不带 scope 的上下文注册的控制器或监听器服务于每个所有者；在某套 agent 组合的 scope 下注册的，则恰好服务于在该组合下组合出的 agent。因此，未加载任何控制器的组合无法借另一套组合的控制工具启动后台工作，而一次结算也只会通知其所有者所属组合注册的监听器。
+
+有 owner 的访问会比较任务的 `SessionId` 与调用方。`bash-1` 等 id 可预测，因此这道隔离是安全边界。无 owner 的任务向调用方开放，并持续到服务 dispose（资源释放）为止。
+
+`outputLimitBytes` 是生产方拥有的模型呈现策略，会原样携带到快照中。控制器在添加状态或通知元数据后应用它；注册表不会重写生产方输出，也不会为省略此字段的生产方虚构默认值。
+
+实现还必须兑现约定的生命周期语义：注册的存续期长于生产方 fiber 与控制器 fiber，owner 释放和服务释放会取消仍在运行的工作并等待守约的生产方，结算遵循首次结果优先（一条终止记录、一轮异常受到隔离的监听器通知，然后释放等待方）。
+
+参见[任务类型目录](../../../docs/subsystems/jobs.md)、[运行时 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)和 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-job-registry-seam.md)。
+
+## 模型体验
+
+通过生产方插件和 [`dsh-tool-jobs`](../tool-jobs/README.md) 间接影响；它们会渲染 job id、输出、状态、取消和完成通知。
+
+#### KV Cache 影响
+
+不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
+
+## 已知限制与暂缓事项
+
+- **流输出只有一个消费游标**：独立观察者需要游标或快照 API。
+- **前台工作无法转为后台**：生产方在启动前选择前台或后台。
+- **约定是进程内的**：`JobStart.run()` 传入回调和确切的 `Agent` 对象；持久化或跨进程后端必须先重塑身份、重启、所有权与观察语义，才能实现此 seam。

package/lib/index.js

@@ -0,0 +1,65 @@
+import { Service } from "@deepseek-ai/cordis";
+//#region lib/types/brand.js
+/**
+* dsh-jobs' owned branded id, carried across the registry, the model-facing
+* control surface, and the client wire.
+*
+* It lives in its own leaf because the package root and `./types` both reach
+* `dsh-agent` through the owner and listener signatures, which a Client program
+* cannot resolve even as a type. A browser-safe consumer imports the id here;
+* `Branded<B>` itself comes from the zero-dependency `@deepseek-ai/dsh-brand`.
+*
+* @module @deepseek-ai/dsh-jobs/brand
+*/
+/**
+* Brand a string as a {@link JobId}.
+* @param id - the raw job-id string (the registry generates `<kind>-N`).
+* @returns the same string, branded; no validation is performed.
+*/
+function JobId(id) {
+	return id;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* The background-job Service Definition (`ctx.jobs`). It owns the contract for
+* job 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-jobs-local`.
+* @module @deepseek-ai/dsh-jobs
+*/
+/**
+* Abstract background job registry. Subclass, implement the abstract methods,
+* and load the subclass as a plugin — it registers as `ctx.jobs` (one
+* implementation per context; loading a second throws, which is cordis'
+* standard duplicate-service behavior).
+*
+* Implementations must honor these semantics:
+* - Registrations outlive producer and controller fibers. Owner and
+*   service disposal cancel live work and await compliant producers; a
+*   throwing teardown cancel force-fails only the record. Teardown
+*   cancellation also marks the record reported, because a record its owner
+*   is being destroyed for has no reader left.
+* - Owned-job 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, released waiters, and one
+*   round of contained listener notification, even against a late producer
+*   outcome. Completion is announced last, after the record is committed and
+*   every other observer of the settlement has seen it, because a reporter
+*   may open a model turn synchronously.
+* - {@link start} refuses work while no attached job controller serves the
+*   spec's owner, so a producer cannot start work that owner cannot collect
+*   or stop. One registry serves every composition in the process, so this
+*   question — and completion-listener delivery — is owner-relative rather
+*   than process-wide: registrations made from an unscoped context serve
+*   every owner, and registrations made under an agent composition's scope
+*   serve exactly the agents composed under it.
+*/
+var JobRegistry = class JobRegistry extends Service {
+	constructor(ctx) {
+		if (new.target === JobRegistry) throw new Error("@deepseek-ai/dsh-jobs is the abstract job registry seam; load an implementation such as @deepseek-ai/dsh-jobs-local instead");
+		super(ctx, "jobs");
+	}
+};
+//#endregion
+export { JobId, JobRegistry, JobRegistry as default };

package/lib/invariant.js

@@ -0,0 +1,40 @@
+//#region lib/types/invariant.js
+/** Package-owned background-job snapshot invariants. @module @deepseek-ai/dsh-jobs/invariant */
+const PACKAGE_NAME = "@deepseek-ai/dsh-jobs";
+const TERMINAL_STATUSES = new Set([
+	"completed",
+	"killed",
+	"failed"
+]);
+/** Cordis companion plugin name. */
+const name = "jobs-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/** Validate the cross-field relationships in one registry snapshot. */
+function validateSnapshot(snapshot, owner, fail) {
+	const id = String(snapshot.id);
+	const prefix = `${snapshot.kind}-`;
+	const ordinal = Number(id.slice(prefix.length));
+	if (snapshot.kind.length === 0 || !id.startsWith(prefix) || !Number.isSafeInteger(ordinal) || ordinal < 1) fail(`job snapshot id ${JSON.stringify(id)} must be ${JSON.stringify(prefix)} followed by a positive ordinal`);
+	if (snapshot.label.length === 0) fail(`job ${JSON.stringify(id)} label must be non-empty`);
+	if (!Number.isSafeInteger(snapshot.startedAt) || snapshot.startedAt < 0) fail(`job ${JSON.stringify(id)} startedAt must be a non-negative epoch integer`);
+	if (TERMINAL_STATUSES.has(snapshot.status) !== (snapshot.finishedAt !== void 0)) fail(`job ${JSON.stringify(id)} finishedAt must be present exactly for a terminal status`);
+	if (snapshot.finishedAt !== void 0 && (!Number.isSafeInteger(snapshot.finishedAt) || snapshot.finishedAt < snapshot.startedAt)) fail(`job ${JSON.stringify(id)} finishedAt must be an epoch integer no earlier than startedAt`);
+	const expectedOwner = owner?.id;
+	if (snapshot.ownerSession !== expectedOwner) fail(`job ${JSON.stringify(id)} ownerSession does not match its completion owner`);
+}
+/** Install checks over current unowned records and every terminal snapshot. */
+const install = Object.assign((ctx, fail) => {
+	for (const snapshot of ctx.jobs.list()) validateSnapshot(snapshot, void 0, fail);
+	ctx.jobs.onJobDone((snapshot, owner) => {
+		validateSnapshot(snapshot, owner, fail);
+	});
+}, { inject: ["jobs"] });
+/**
+* Register the job-registry invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/brand.d.ts

@@ -0,0 +1,24 @@
+/**
+ * dsh-jobs' owned branded id, carried across the registry, the model-facing
+ * control surface, and the client wire.
+ *
+ * It lives in its own leaf because the package root and `./types` both reach
+ * `dsh-agent` through the owner and listener signatures, which a Client program
+ * cannot resolve even as a type. A browser-safe consumer imports the id here;
+ * `Branded<B>` itself comes from the zero-dependency `@deepseek-ai/dsh-brand`.
+ *
+ * @module @deepseek-ai/dsh-jobs/brand
+ */
+import type { Branded } from '@deepseek-ai/dsh-brand';
+/**
+ * Identifies a background job. The registry generates `<kind>-N`; predictable
+ * ids rely on owner authorization rather than secrecy.
+ */
+export type JobId = Branded<'JobId'>;
+/**
+ * Brand a string as a {@link JobId}.
+ * @param id - the raw job-id string (the registry generates `<kind>-N`).
+ * @returns the same string, branded; no validation is performed.
+ */
+export declare function JobId(id: string): JobId;
+//# sourceMappingURL=brand.d.ts.map

package/lib/types/brand.js

@@ -0,0 +1,20 @@
+/**
+ * dsh-jobs' owned branded id, carried across the registry, the model-facing
+ * control surface, and the client wire.
+ *
+ * It lives in its own leaf because the package root and `./types` both reach
+ * `dsh-agent` through the owner and listener signatures, which a Client program
+ * cannot resolve even as a type. A browser-safe consumer imports the id here;
+ * `Branded<B>` itself comes from the zero-dependency `@deepseek-ai/dsh-brand`.
+ *
+ * @module @deepseek-ai/dsh-jobs/brand
+ */
+/**
+ * Brand a string as a {@link JobId}.
+ * @param id - the raw job-id string (the registry generates `<kind>-N`).
+ * @returns the same string, branded; no validation is performed.
+ */
+export function JobId(id) {
+    return id;
+}
+//# sourceMappingURL=brand.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,145 @@
+/**
+ * The background-job Service Definition (`ctx.jobs`). It owns the contract for
+ * job 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-jobs-local`.
+ * @module @deepseek-ai/dsh-jobs
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { JobDoneListener, JobId, JobRead, JobSnapshot, JobStart, JobsChangedListener } from './types.ts';
+export { JobId } from './types.ts';
+export type { JobDoneListener, JobHooks, JobKind, JobKindMap, JobOutcome, JobRead, JobSnapshot, JobStart, JobStatus, JobsChangedListener, } from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        jobs: JobRegistry;
+    }
+}
+/**
+ * Abstract background job registry. Subclass, implement the abstract methods,
+ * and load the subclass as a plugin — it registers as `ctx.jobs` (one
+ * implementation per context; loading a second throws, which is cordis'
+ * standard duplicate-service behavior).
+ *
+ * Implementations must honor these semantics:
+ * - Registrations outlive producer and controller fibers. Owner and
+ *   service disposal cancel live work and await compliant producers; a
+ *   throwing teardown cancel force-fails only the record. Teardown
+ *   cancellation also marks the record reported, because a record its owner
+ *   is being destroyed for has no reader left.
+ * - Owned-job 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, released waiters, and one
+ *   round of contained listener notification, even against a late producer
+ *   outcome. Completion is announced last, after the record is committed and
+ *   every other observer of the settlement has seen it, because a reporter
+ *   may open a model turn synchronously.
+ * - {@link start} refuses work while no attached job controller serves the
+ *   spec's owner, so a producer cannot start work that owner cannot collect
+ *   or stop. One registry serves every composition in the process, so this
+ *   question — and completion-listener delivery — is owner-relative rather
+ *   than process-wide: registrations made from an unscoped context serve
+ *   every owner, and registrations made under an agent composition's scope
+ *   serve exactly the agents composed under it.
+ */
+export declare abstract class JobRegistry extends Service {
+    constructor(ctx: Context);
+    /**
+     * Preflight access, validation, owner cleanup, and implementation-owned
+     * admission before starting and atomically registering work. Any preflight
+     * rejection leaves no job id or execution resource. A throwing starter
+     * leaves nothing registered; after it returns, registration cannot fail.
+     * Settlement records the outcome, notifies listeners, and releases waiters.
+     * @param spec - job identity, owner, and synchronous starter.
+     * @returns the registry-issued `<kind>-N` id.
+     */
+    abstract start(spec: JobStart): JobId;
+    /**
+     * List caller-owned and unowned jobs in registration order without exposing
+     * another session's labels.
+     * @param caller - reading agent; a non-agent caller sees only unowned jobs.
+     * @returns fresh snapshots.
+     */
+    abstract list(caller?: Agent): JobSnapshot[];
+    /**
+     * Return a non-consuming snapshot without changing its read cursor or notice
+     * state. Throws for an unknown or foreign job.
+     * @param id - job to look up.
+     * @param caller - reading agent checked against the owner.
+     * @returns a fresh snapshot.
+     */
+    abstract get(id: JobId, caller?: Agent): JobSnapshot;
+    /**
+     * Read the next stream delta, or the idempotent final output after settlement.
+     * A terminal read marks the job reported. Throws for an unknown or foreign
+     * job.
+     * @param id - job to read.
+     * @param caller - reading agent checked against the owner.
+     * @returns output text and the post-read snapshot.
+     */
+    abstract read(id: JobId, caller?: Agent): JobRead;
+    /**
+     * Request cancellation, then mark the job stopping and reported. A producer
+     * throw propagates without changing job state. Throws for an unknown or
+     * foreign job.
+     * @param id - job to cancel.
+     * @param caller - killing agent checked against the owner.
+     * @param reason - logged reason forwarded to the producer.
+     * @returns `requested` for live work, otherwise `already-finished`.
+     */
+    abstract kill(id: JobId, caller?: Agent, reason?: string): 'requested' | 'already-finished';
+    /**
+     * Wait for settlement or timeout without cancelling the job. Caller abort
+     * rejects only while the job 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 - job 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.
+     */
+    abstract wait(id: JobId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<JobSnapshot>;
+    /**
+     * Register an effect-scoped completion listener. It receives the settlements
+     * of the owners its registering context's scope covers; each listener is
+     * contained; returned promises are observed but not awaited. No listener runs
+     * after service disposal.
+     * @param listener - receives each terminal snapshot and its exact owner.
+     * @returns disposer that unregisters the listener.
+     */
+    abstract onJobDone(listener: JobDoneListener): () => void;
+    /**
+    /**
+     * Register an effect-scoped observer of visible-set changes. It fires after
+     * every commit that changes what {@link list} returns for that owner —
+     * registration, every stopping transition (including the one teardown
+     * performs before it awaits a slow producer), settlement, owner-disposal
+     * removal, and the emptying that service disposal commits — so an observer
+     * re-reads rather than accumulating deltas.
+     *
+     * Delivery is owner-relative on the same terms as {@link onJobDone}: an
+     * observer registered from an unscoped context — a host composition's own
+     * carrier — sees every owner, while one registered under an agent
+     * composition's scope sees exactly the agents composed under it.
+     *
+     * This is not a superset of {@link onJobDone}: that one delivers the terminal
+     * record under first-wins semantics a job controller couples to notice
+     * delivery, while this one carries no delivery meaning and marks nothing
+     * reported. Listeners are contained and never awaited.
+     * @param listener - receives the owner whose visible set changed, or
+     *   `undefined` when an unowned job changed and every caller's set did.
+     * @returns disposer that unregisters the listener.
+     */
+    abstract onJobsChanged(listener: JobsChangedListener): () => void;
+    /**
+     * Attach an effect-scoped controller that can read and stop jobs. It serves the
+     * owners its registering context's scope covers, and {@link start} refuses an
+     * owner no attached controller serves.
+     * @param name - diagnostic label; duplicate names remain independent.
+     * @returns disposer that detaches this controller.
+     */
+    abstract attachController(name: string): () => void;
+}
+export default JobRegistry;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,49 @@
+/**
+ * The background-job Service Definition (`ctx.jobs`). It owns the contract for
+ * job 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-jobs-local`.
+ * @module @deepseek-ai/dsh-jobs
+ */
+import { Service } from '@deepseek-ai/cordis';
+export { JobId } from "./types.js";
+/**
+ * Abstract background job registry. Subclass, implement the abstract methods,
+ * and load the subclass as a plugin — it registers as `ctx.jobs` (one
+ * implementation per context; loading a second throws, which is cordis'
+ * standard duplicate-service behavior).
+ *
+ * Implementations must honor these semantics:
+ * - Registrations outlive producer and controller fibers. Owner and
+ *   service disposal cancel live work and await compliant producers; a
+ *   throwing teardown cancel force-fails only the record. Teardown
+ *   cancellation also marks the record reported, because a record its owner
+ *   is being destroyed for has no reader left.
+ * - Owned-job 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, released waiters, and one
+ *   round of contained listener notification, even against a late producer
+ *   outcome. Completion is announced last, after the record is committed and
+ *   every other observer of the settlement has seen it, because a reporter
+ *   may open a model turn synchronously.
+ * - {@link start} refuses work while no attached job controller serves the
+ *   spec's owner, so a producer cannot start work that owner cannot collect
+ *   or stop. One registry serves every composition in the process, so this
+ *   question — and completion-listener delivery — is owner-relative rather
+ *   than process-wide: registrations made from an unscoped context serve
+ *   every owner, and registrations made under an agent composition's scope
+ *   serve exactly the agents composed under it.
+ */
+export class JobRegistry extends Service {
+    constructor(ctx) {
+        // `abstract` erases at runtime, so a composition row naming this package
+        // would register a ctx.jobs with no method implementations and fail far
+        // from the misconfiguration. Fail loud at load instead.
+        if (new.target === JobRegistry) {
+            throw new Error('@deepseek-ai/dsh-jobs is the abstract job registry seam; load an implementation such as @deepseek-ai/dsh-jobs-local instead');
+        }
+        super(ctx, 'jobs');
+    }
+}
+export default JobRegistry;
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Package-owned background-job snapshot invariants. @module @deepseek-ai/dsh-jobs/invariant */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "jobs-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register the job-registry invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,47 @@
+/** Package-owned background-job snapshot invariants. @module @deepseek-ai/dsh-jobs/invariant */
+const PACKAGE_NAME = '@deepseek-ai/dsh-jobs';
+const TERMINAL_STATUSES = new Set(['completed', 'killed', 'failed']);
+/** Cordis companion plugin name. */
+export const name = 'jobs-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/** Validate the cross-field relationships in one registry snapshot. */
+function validateSnapshot(snapshot, owner, fail) {
+    const id = String(snapshot.id);
+    const prefix = `${snapshot.kind}-`;
+    const ordinal = Number(id.slice(prefix.length));
+    if (snapshot.kind.length === 0 || !id.startsWith(prefix)
+        || !Number.isSafeInteger(ordinal) || ordinal < 1) {
+        fail(`job snapshot id ${JSON.stringify(id)} must be ${JSON.stringify(prefix)} followed by a positive ordinal`);
+    }
+    if (snapshot.label.length === 0)
+        fail(`job ${JSON.stringify(id)} label must be non-empty`);
+    if (!Number.isSafeInteger(snapshot.startedAt) || snapshot.startedAt < 0) {
+        fail(`job ${JSON.stringify(id)} startedAt must be a non-negative epoch integer`);
+    }
+    const terminal = TERMINAL_STATUSES.has(snapshot.status);
+    if (terminal !== (snapshot.finishedAt !== undefined)) {
+        fail(`job ${JSON.stringify(id)} finishedAt must be present exactly for a terminal status`);
+    }
+    if (snapshot.finishedAt !== undefined
+        && (!Number.isSafeInteger(snapshot.finishedAt) || snapshot.finishedAt < snapshot.startedAt)) {
+        fail(`job ${JSON.stringify(id)} finishedAt must be an epoch integer no earlier than startedAt`);
+    }
+    const expectedOwner = owner?.id;
+    if (snapshot.ownerSession !== expectedOwner) {
+        fail(`job ${JSON.stringify(id)} ownerSession does not match its completion owner`);
+    }
+}
+/** Install checks over current unowned records and every terminal snapshot. */
+const install = Object.assign((ctx, fail) => {
+    for (const snapshot of ctx.jobs.list())
+        validateSnapshot(snapshot, undefined, fail);
+    ctx.jobs.onJobDone((snapshot, owner) => { validateSnapshot(snapshot, owner, fail); });
+}, { inject: ['jobs'] });
+/**
+ * Register the job-registry invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//# sourceMappingURL=invariant.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Types shared by job producers, the registry, and controllers. The
+ * service implementation lives in `./index.ts`.
+ * @module @deepseek-ai/dsh-jobs/types
+ */
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { JobId } from './brand.ts';
+export { JobId } from './brand.ts';
+/**
+ * Task lifecycle: `running`, optionally `stopping`, then exactly one terminal
+ * status. Producer-specific facts belong in {@link JobSnapshot.detail}.
+ */
+export type JobStatus = 'running' | 'stopping' | 'completed' | 'killed' | 'failed';
+/**
+ * Producer-defined job kinds. Plugins extend this map by declaration merging;
+ * the registry treats every value as an opaque id namespace.
+ */
+export interface JobKindMap {
+    bash: 'bash';
+    subagent: 'subagent';
+}
+/** The merge-extensible union of registered producer kind names. */
+export type JobKind = JobKindMap[keyof JobKindMap];
+/** Terminal result supplied by a producer through {@link JobHooks.done}. */
+export interface JobOutcome {
+    /** How the job ended: finished (`completed`), cancelled (`killed`), or broke (`failed`). */
+    status: 'completed' | 'killed' | 'failed';
+    /** Kind-specific detail rendered into status lines ('exit code: 3', 'max-tokens'). */
+    detail?: string;
+    /** Final output for jobs without `readOutput`; stream jobs leave it unset. */
+    output?: string;
+}
+/**
+ * Producer declaration passed to {@link JobRegistry.start}. The runtime
+ * preflights access and cleanup before invoking {@link run}; the producer owns
+ * execution resources while the runtime owns identity and lifecycle state.
+ */
+export interface JobStart {
+    /** Producer kind — also the id prefix (`bash`, `subagent`, …). */
+    kind: JobKind;
+    /** One-line model-facing label (the command; the delegation description). */
+    label: string;
+    /**
+     * Optional UTF-8 byte cap for each complete model-facing completion notice or
+     * output read, including controller status metadata.
+     */
+    outputLimitBytes?: number;
+    /**
+     * Owning live agent. Access is fenced by its session id, and agent disposal
+     * cancels and awaits the job. The instance must be the one currently
+     * registered under its agent id. Omitting the owner creates an unowned job,
+     * open to any caller until service disposal.
+     */
+    owner?: Agent;
+    /**
+     * Start the work after preflight and synchronously return its hooks. Called
+     * once; a throw leaves nothing registered, and the producer must clean up any
+     * partially started resources.
+     */
+    run(): JobHooks;
+}
+/** Hooks through which the runtime controls and observes producer work. */
+export interface JobHooks {
+    /**
+     * Request termination. Must be synchronous, idempotent, and eventually settle
+     * {@link done}; throws propagate. The optional reason is forwarded verbatim.
+     */
+    cancel(reason?: string): void;
+    /**
+     * Resolves after the producer releases its resources, not merely when work
+     * finishes. Must not reject; the runtime converts a rejection to `failed`.
+     * If teardown cancellation throws, the runtime may force-fail only the
+     * registry record without claiming that the work stopped.
+     */
+    done: Promise<JobOutcome>;
+    /**
+     * Consume output produced since the previous call. The producer formats
+     * truncation and spill notices. Absence marks a final-output-only job; each
+     * job has one consuming cursor.
+     */
+    readOutput?(): string;
+}
+/**
+ * A read-only projection of one job, safe to hand to listeners and tools —
+ * a fresh object per call, never live registry state.
+ */
+export interface JobSnapshot {
+    /** The registry-issued id (`<kind>-N`). */
+    id: JobId;
+    /** The producer kind the job was registered with. */
+    kind: JobKind;
+    /** The producer-supplied one-line label. */
+    label: string;
+    /** Producer-owned cap for complete model-facing notices and output reads. */
+    outputLimitBytes?: number;
+    /**
+     * Owner session id used for authorization and correlation; absent for
+     * unowned jobs. Completion listeners receive the exact {@link Agent}
+     * separately through {@link JobDoneListener}.
+     */
+    ownerSession?: SessionId;
+    /** Current lifecycle state. */
+    status: JobStatus;
+    /** Kind-specific status detail, present once the producer supplied one (usually terminal). */
+    detail?: string;
+    /** Epoch ms when the job was registered. */
+    startedAt: number;
+    /** Epoch ms when the job settled; absent while `running`/`stopping`. */
+    finishedAt?: number;
+    /**
+     * True when a kill, read, wait, or teardown cancel has reported or committed
+     * to report the terminal state. Completion reporters suppress redundant
+     * notices when set. Teardown claims it because the owner or service being
+     * destroyed leaves no reader: a reporter that opens a turn on notice would
+     * otherwise spend a model request per teardown layer.
+     */
+    reported: boolean;
+}
+/** Output and post-read state returned by {@link JobRegistry.read}. */
+export interface JobRead {
+    /**
+     * Stream kinds: the consuming delta since the previous read. Final-output
+     * kinds: empty while live, the terminal {@link JobOutcome.output} (or
+     * empty) once settled — idempotent, never consumed.
+     */
+    text: string;
+    /** The job's state at read time. */
+    snapshot: JobSnapshot;
+}
+/**
+ * Completion callback with the exact owner supplied at start, or `undefined`
+ * for an unowned job. Returned promises are observed but not awaited.
+ */
+export type JobDoneListener = (snapshot: JobSnapshot, owner: Agent | undefined) => void | PromiseLike<void>;
+/**
+ * Observation callback for a change to what one owner's {@link JobRegistry.list}
+ * would return. It is owner-granular rather than job-granular because the
+ * change may be a removal, which no per-job record can express, and because
+ * its consumers re-read the whole visible set anyway.
+ *
+ * An `undefined` owner means an unowned job changed, so every caller's visible
+ * set changed with it.
+ */
+export type JobsChangedListener = (owner: Agent | undefined) => void;
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,7 @@
+/**
+ * Types shared by job producers, the registry, and controllers. The
+ * service implementation lives in `./index.ts`.
+ * @module @deepseek-ai/dsh-jobs/types
+ */
+export { JobId } from "./brand.js";
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@deepseek-ai/dsh-jobs",
+  "description": "Background job registry (ctx.jobs) for the DeepSeek Harness — shared ids, owner isolation, polling, cancellation, and completion listeners for long-running tool work",
+  "version": "0.0.1-rc.3",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/jobs/jobs"
+  },
+  "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"
+    },
+    "./brand": {
+      "types": "./lib/types/brand.d.ts",
+      "default": "./lib/types/brand.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.3",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.3",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.3"
+  }
+}