@deepseek-ai/dsh-tool-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/tool-jobs/README.md
+README.md: 8d6a00651f69258d764904ac99d000c2055982dc
+README.zh.md: 15903b6f263fe9d225c48bf567c46f587d23cb00

package/README.md

@@ -0,0 +1,96 @@
+# @deepseek-ai/dsh-tool-jobs
+
+English | [中文](README.zh.md)
+
+The model-facing controller for `ctx.jobs`: three kind-independent tools, completion notices, and one background-work prompt section. Loading the plugin attaches the controller required by `ctx.jobs.start()`.
+
+## Tools
+
+- `job_output(job_id, wait?, timeout_ms?)` reads without blocking by default. Stream jobs return only the next delta; final-output jobs return their result after settlement. Every response ends with `[status: ...]`. `wait: true` waits up to the configured cap and leaves a still-running job alive on timeout.
+- `job_list()` returns caller-visible jobs as `<id> [<kind>] <status> — <label>`.
+- `job_kill(job_id, reason?)` requests cancellation immediately and forwards the logged reason. Terminal jobs return a non-consuming snapshot.
+
+All three use generic UI cards: `read` for output and list, `execute` for kill.
+
+Their canonical values are `{ text, job }`, `PublicJobSnapshot[]`, and `{ outcome: 'cancellation-requested' | 'already-finished', job }`. A public snapshot carries id, kind, label, status/detail, and start/finish times; it deliberately omits `ownerSession` and the internal `reported` notice bit. Native renderers preserve the status and acknowledgement text above.
+
+When a producer supplies `outputLimitBytes`, `job_output`, terminal `job_kill`, and completion notices cap the complete Native UTF-8 result after adding status or notice text. Reads retain the output tail and control suffix when they fit; a bounded completion notice instead reserves `background job <id>` and the `job_output` collection instruction before spending remaining bytes on its variable kind, label, status, detail, and truncation marker. A prepended pre-execute listener captures the caller-visible job before policy, and each job-control definition's final-content callback applies its producer cap to single-text denials, short-circuits, normalized tool or pipeline failures, replacements, and blocks; structured multi-block policy results retain their shape. An existing producer truncation marker is reused rather than duplicated. Producers that omit the field retain the existing unbounded controller behavior.
+
+## Completion notices
+
+An unreported completion delivers `background job <id> (<kind>: <label>) finished [status: ...]. Read its output with job_output.` to the exact owner. When bounded, the stable id prefix and collection command outrank variable label/detail so the notice remains actionable at PTY's supported 64-byte minimum. A kill or terminal read/wait marks delivery reported and suppresses the redundant notice, as does the teardown cancel that drains an owner or the service.
+
+Which lane carries it depends on what the owner is doing. A busy owner is injected: the notice joins the next-step inbox, and the turn cannot close while that inbox holds it, so several jobs settling together cost one step rather than one turn each. An idle owner is instead woken with a follow-up turn, because a pending notice nothing claims is a completion the model never learns about. `completionDelivery: quiet` keeps the injection lane for idle owners too, which is what a deterministic transcript needs.
+
+Waking is bounded. Each owner may open `maxConsecutiveWakes` turns this way before further notices degrade to injection, and claiming any user-authored message restores the budget. The bound exists because the chain is self-exciting: a woken turn may start the background job whose completion wakes it again. Notices this plugin queued never refill the budget they spent.
+
+One host registry may carry several mounts of this plugin — one per agent preset. The registry routes each settlement to the listeners the owner's scope chain reaches, so a mount under one preset never sees another preset's agents and an agent reads exactly one notice per completion however many presets are mounted. The same routing decides which agents this mount's controller serves: an agent whose composition loads no `tool-jobs` cannot start background work at all.
+
+## Config
+
+| key | default | meaning |
+|---|---|---|
+| `waitTimeoutMs` | `30000` | wait used when `wait: true` omits `timeout_ms` |
+| `maxWaitTimeoutMs` | `600000` | cap for model-supplied waits |
+| `completionDelivery` | `wakeup` | `wakeup` opens a turn on an idle owner; `quiet` leaves the notice pending |
+| `maxConsecutiveWakes` | `3` | turns one owner may open by wake before notices degrade to injection |
+
+A default above the cap fails at load.
+
+## Model Experience
+
+### System prompt
+
+#### What the model sees
+
+Every request in this plugin's registration scope contains this guidance. Agent-scoped tool filtering may hide the tools without removing the independently registered prompt section.
+
+##### Background-job guidance
+
+```markdown
+Track every background job id you start. You are notified in-session when a job finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running job's work. Before giving a final answer, collect every still-relevant job with job_output (set wait: true only when you are genuinely blocked on it), and job_kill jobs that stopped mattering.
+```
+
+#### Token effect
+
+Small fixed input cost per request while active.
+
+#### KV Cache effect
+
+Prefix-stable while the plugin scope and guidance text are unchanged. Activation or disposal may invalidate reuse from this prompt section.
+
+### Tool schemas
+
+#### What the model sees
+
+The generated [`job_output`, `job_list`, and `job_kill` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-jobs) while this tool set is visible.
+
+#### Token effect
+
+Fixed schema cost on each request where the tools are visible.
+
+#### KV Cache effect
+
+Prefix-stable while tool definitions and visibility are unchanged. Registration lifecycle or scoped restrictions may invalidate reuse from the first changed schema token.
+
+### Results and notices
+
+#### What the model sees
+
+Reads return output or `(no new output)` followed by `[status: <status>]` and optional detail. An empty list returns `(no background jobs)`. Kill returns `requested cancellation of job <id>` or the existing terminal status. Unreported owned completion uses the notice above.
+
+#### Token effect
+
+Results and notices remain in parent history until compaction. Stream reads do not repeat consumed output; a producer-supplied `outputLimitBytes` bounds each complete read or notice. Under `wakeup`, a notice reaching an idle owner also buys a model request the user did not ask for, capped per owner by `maxConsecutiveWakes`; a notice reaching a busy owner adds a step to the turn it is already paying for.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+- **A settlement inside the driver's retirement window still strands its notice** — between the turn loop's last inbox check and the driver committing its idle phase the owner still reads as busy, so the notice is injected and nothing wakes. Steering has the same hole; closing it belongs to `agent-loop`.
+- **A spent wake budget is not restored by time** — only user-authored input refills it, so an unattended agent whose budget ran out collects its remaining notices on the next turn something else opens.
+- **A notice pending on an idle owner does not survive that owner's disposal** — the disposal cancel clears the unclaimed inbox, and the log keeps the insert/cancel pair as the record.
+- **Stream reads are single-consumer** — independent observers need another runtime API.
+- **Unowned jobs have no session fence** — external callers must supply policy or avoid them.

package/README.zh.md

@@ -0,0 +1,96 @@
+# @deepseek-ai/dsh-tool-jobs
+
+[English](README.md) | 中文
+
+`ctx.jobs` 的面向模型控制器：三个与 kind 无关的工具、完成通知和一个后台工作提示词区段。加载该插件会附加 `ctx.jobs.start()` 所要求的控制器。
+
+## 工具
+
+- `job_output(job_id, wait?, timeout_ms?)` 默认以非阻塞方式读取。流任务只返回下一个增量；最终输出任务在终止后返回结果。每个响应都以 `[status: ...]` 结尾。`wait: true` 最多等待到配置上限，超时时仍让运行中的任务保持存活。
+- `job_list()` 以 `<id> [<kind>] <status> — <label>` 返回调用方可见的任务。
+- `job_kill(job_id, reason?)` 立即请求取消并转发已记录的原因。终止任务返回非消费式快照。
+
+三个工具都使用通用 UI 卡片：output 和 list 使用 `read`，kill 使用 `execute`。
+
+它们的规范值依次为 `{ text, job }`、`PublicJobSnapshot[]` 和 `{ outcome: 'cancellation-requested' | 'already-finished', job }`。公共快照携带 id、kind、label、status/detail 及开始／结束时间；它有意省略 `ownerSession` 和内部 `reported` 通知位。原生 renderer 保留上述状态与确认文本。
+
+当生产方提供 `outputLimitBytes` 时，`job_output`、针对已终止任务的 `job_kill` 和完成通知会在添加状态或通知文本后，对完整的原生 UTF-8 结果施加上限。只要能够容纳，读取就会保留输出尾部与控制后缀；有界完成通知则先为 `background job <id>` 和 `job_output` 收集指令预留空间，再把剩余字节用于可变的 kind、label、status、detail 与截断标记。一个前置 pre-execute 监听器会在策略运行前捕获调用方可见任务；每个任务控制定义的 final-content 回调会把其生产方上限应用到单文本拒绝、短路、规范化工具或流水线失败、替换和阻止；结构化多块策略结果保持自身形状。已有的生产方截断标记会复用，不会重复添加。省略该字段的生产方保留现有的无界控制器行为。
+
+## 完成通知
+
+一项尚未报告的完成会把 `background job <id> (<kind>: <label>) finished [status: ...]. Read its output with job_output.` 交付给确切所有者。应用上限时，即使采用 PTY 支持的 64 字节下限，稳定 id 前缀和收集命令的优先级也高于可变 label/detail，因此通知仍可操作。kill 或针对已终止任务的 read/wait 会把交付标为已报告并抑制重复通知；排空 owner 或服务的 teardown 取消同样如此。
+
+由哪条通道承载取决于所有者当时在做什么。繁忙的所有者走注入：通知进入 next-step inbox，而该 inbox 尚有内容时 turn 无法结束，因此同时结算的多个任务只花掉一步，而不是各占一轮。空闲的所有者则被 follow-up 唤醒，因为无人领取的待发通知等于模型永远不会知道的完成。`completionDelivery: quiet` 让空闲所有者也留在注入通道上，确定性 transcript 需要的正是这一点。
+
+唤醒是有界的。每个所有者最多可通过唤醒开启 `maxConsecutiveWakes` 轮，此后的通知降级为注入；领取任何用户撰写的消息都会恢复该预算。设界是因为这条链会自激：被唤醒的一轮可能启动某个后台任务，而它的完成又会唤醒同一个所有者。本插件自己排队的通知永远不会补充它刚花掉的预算。
+
+一个宿主注册表可能承载本插件的多份挂载——每个 agent preset 一份。注册表会把每次结算路由给所有者 scope 链所能抵达的监听器，因此某个 preset 下的挂载永远看不到另一个 preset 的 agent，无论挂载了多少 preset，一个 agent 每次完成都只读到一条通知。同一套路由也决定本挂载的控制器服务哪些 agent：组合中未加载 `tool-jobs` 的 agent 根本无法启动后台工作。
+
+## 配置
+
+| key | 默认值 | 含义 |
+|---|---|---|
+| `waitTimeoutMs` | `30000` | `wait: true` 省略 `timeout_ms` 时使用的等待时间 |
+| `maxWaitTimeoutMs` | `600000` | 模型所给等待时间的上限 |
+| `completionDelivery` | `wakeup` | `wakeup` 为空闲所有者开启一轮；`quiet` 让通知继续待领 |
+| `maxConsecutiveWakes` | `3` | 一个所有者可由唤醒开启的轮数，超出后通知降级为注入 |
+
+默认值高于上限时，插件会在加载时失败。
+
+## 模型体验
+
+### 系统提示词
+
+#### 模型看到的内容
+
+该插件注册 scope 中的每次请求都包含以下指引。按 agent（智能体）scope 过滤工具时，可能会隐藏工具，却不会移除独立注册的提示词区段。
+
+##### 后台任务指引
+
+```markdown
+Track every background job id you start. You are notified in-session when a job finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running job's work. Before giving a final answer, collect every still-relevant job with job_output (set wait: true only when you are genuinely blocked on it), and job_kill jobs that stopped mattering.
+```
+
+#### Token 影响
+
+激活期间，每次请求都会产生少量固定的输入 token 开销。
+
+#### KV Cache 影响
+
+只要插件 scope 与指引文本不变，前缀就保持稳定。激活或释放可能使从该提示词区段起的复用失效。
+
+### 工具 schema
+
+#### 模型看到的内容
+
+该工具集可见时，会看到生成的 [`job_output`、`job_list` 和 `job_kill` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-jobs)。
+
+#### Token 影响
+
+工具可见时，每次请求都会产生固定的 schema token 开销。
+
+#### KV Cache 影响
+
+只要工具定义与可见性不变，前缀就保持稳定。注册生命周期或 scope 限制可能使从第一个发生变化的 schema token 起的复用失效。
+
+### 结果与通知
+
+#### 模型看到的内容
+
+读取会返回输出或 `(no new output)`，随后是 `[status: <status>]` 和可选 detail。空列表返回 `(no background jobs)`。kill 返回 `requested cancellation of job <id>` 或现有终止状态。尚未报告且有 owner 的任务完成时使用上述通知。
+
+#### Token 影响
+
+结果与通知在压缩（compaction）前保留于父级历史。流读取不会重复已消费的输出；生产方提供的 `outputLimitBytes` 会限制每次完整读取或通知。在 `wakeup` 下，抵达空闲所有者的通知还会额外买下一次用户并未要求的模型请求，其数量按所有者由 `maxConsecutiveWakes` 封顶；抵达繁忙所有者的通知则只是给它已经在支付的那一轮加一步。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
+
+## 已知限制与暂缓事项
+
+- **落在 driver 退休窗口内的结算仍会让通知搁浅**：在轮次循环最后一次检查 inbox 与 driver 提交 idle 相位之间，所有者读起来仍是繁忙，因此通知走注入且无人唤醒。steer 有同样的洞；堵上它属于 `agent-loop`。
+- **已花掉的唤醒预算不会随时间恢复**：只有用户撰写的输入才能补充，因此预算耗尽的无人值守 agent 要等到其他原因开启下一轮时才收走剩余通知。
+- **待领于空闲所有者的通知无法在该所有者释放后存活**：释放时的取消会清空未领取的 inbox，日志保留插入/取消这一对作为记录。
+- **流读取只有单一消费方**：独立观察者需要另一套运行时 API。
+- **无 owner 的任务没有会话隔离**：外部调用方必须提供策略或避开这些任务。

package/lib/index.js

@@ -0,0 +1,353 @@
+import z from "@deepseek-ai/schemastery";
+import { boundContextSummary, createUserMessage } from "@deepseek-ai/dsh-llm";
+import { TextRetainer } from "@deepseek-ai/dsh-output-retention";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { JobId } from "@deepseek-ai/dsh-jobs";
+//#region lib/types/index.js
+/**
+* Model-facing `job_output`, `job_list`, and `job_kill` tools over
+* `ctx.jobs`. Loading the plugin attaches the controller required by
+* producers. It also delivers unreported completions to the owning agent:
+* injected into a busy owner's next step, or opening a turn on an idle one
+* under the default `wakeup` delivery, bounded per owner.
+* @module @deepseek-ai/dsh-tool-jobs
+*/
+const name = "tool-jobs";
+const inject = [
+	"tools",
+	"jobs",
+	"systemPrompt"
+];
+const Config = z.object({
+	waitTimeoutMs: z.number().min(1).default(3e4),
+	maxWaitTimeoutMs: z.number().min(1).default(6e5),
+	completionDelivery: z.union(["quiet", "wakeup"]).default("wakeup"),
+	maxConsecutiveWakes: z.number().min(1).default(3)
+});
+/** Shared schema for job-control outputs. */
+const PUBLIC_TASK_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		id: {
+			type: "string",
+			required: true
+		},
+		kind: {
+			type: "string",
+			required: true
+		},
+		label: {
+			type: "string",
+			required: true
+		},
+		status: {
+			type: "string",
+			required: true,
+			enum: [
+				"running",
+				"stopping",
+				"completed",
+				"killed",
+				"failed"
+			]
+		},
+		detail: { type: "string" },
+		startedAt: {
+			type: "integer",
+			required: true
+		},
+		finishedAt: { type: "integer" }
+	}
+};
+/** Remove job ownership and notification bookkeeping from a registry snapshot. */
+function publicJob(snapshot) {
+	return {
+		id: snapshot.id,
+		kind: snapshot.kind,
+		label: snapshot.label,
+		status: snapshot.status,
+		...snapshot.detail !== void 0 ? { detail: snapshot.detail } : {},
+		startedAt: snapshot.startedAt,
+		...snapshot.finishedAt !== void 0 ? { finishedAt: snapshot.finishedAt } : {}
+	};
+}
+/**
+* Render generic status with optional producer detail.
+* @param snapshot - job state to render.
+* @returns a bracketed status line.
+*/
+function statusLine(snapshot) {
+	return snapshot.detail !== void 0 ? `[status: ${snapshot.status}, ${snapshot.detail}]` : `[status: ${snapshot.status}]`;
+}
+const encoder = new TextEncoder();
+function retainTail(text, maxBytes) {
+	const retainer = new TextRetainer({
+		kind: "tail",
+		maxBytes
+	});
+	retainer.push(text);
+	return retainer.finish().text;
+}
+function retainHead(text, maxBytes) {
+	const retainer = new TextRetainer({
+		kind: "head",
+		maxBytes
+	});
+	retainer.push(text);
+	return retainer.finish().text;
+}
+function fitWithSuffix(content, suffix, maxBytes, omitted) {
+	const complete = `${content}${suffix}`;
+	if (maxBytes === void 0 || encoder.encode(complete).byteLength <= maxBytes) return complete;
+	const fixed = `${content.endsWith(omitted.trimStart()) ? "" : omitted}${suffix}`;
+	const fixedBytes = encoder.encode(fixed).byteLength;
+	if (fixedBytes >= maxBytes) return retainTail(fixed, maxBytes);
+	return `${retainTail(content, maxBytes - fixedBytes)}${fixed}`;
+}
+/**
+* One-line account of a settled job for the `notice` form's collapsed row.
+* @param snapshot - the settled job.
+* @returns its kind, label, and status, bounded like every notice summary.
+*/
+function completionSummary(snapshot) {
+	return boundContextSummary(`${snapshot.kind} ${snapshot.label} ${statusLine(snapshot)}`);
+}
+function fitCompletionNotice(snapshot) {
+	const prefix = `background job ${snapshot.id}`;
+	const detail = ` (${snapshot.kind}: ${snapshot.label}) finished ${statusLine(snapshot)}`;
+	const action = "\nDone; job_output.";
+	const complete = `${prefix}${detail}. Read its output with job_output.`;
+	const maxBytes = snapshot.outputLimitBytes;
+	if (maxBytes === void 0 || encoder.encode(complete).byteLength <= maxBytes) return complete;
+	const omitted = "\n[notice truncated]";
+	const fixed = `${prefix}${omitted}${action}`;
+	const fixedBytes = encoder.encode(fixed).byteLength;
+	if (fixedBytes <= maxBytes) return fixedBytes === maxBytes ? fixed : `${prefix}${retainHead(detail, maxBytes - fixedBytes)}${omitted}${action}`;
+	const compact = `${prefix}${action}`;
+	if (encoder.encode(compact).byteLength <= maxBytes) return compact;
+	const actionBytes = encoder.encode(action).byteLength;
+	if (actionBytes >= maxBytes) return retainTail(action, maxBytes);
+	return `${retainHead(prefix, maxBytes - actionBytes)}${action}`;
+}
+function rawSingleText(content) {
+	if (content.length !== 1) return void 0;
+	const block = content[0];
+	if (block?.type !== "text") return void 0;
+	return block.text;
+}
+function boundSingleText(content, maxBytes) {
+	const text = rawSingleText(content);
+	if (text === void 0) return void 0;
+	return [{
+		type: "text",
+		text: fitWithSuffix(text, "", maxBytes, "\n[result truncated]")
+	}];
+}
+function visibleOutputLimit(ctx, exec) {
+	if (exec.name !== "job_output" && exec.name !== "job_kill") return void 0;
+	const jobId = exec.arguments?.job_id;
+	if (typeof jobId !== "string" || jobId.length === 0) return void 0;
+	return ctx.jobs.list(exec.agent).find((snapshot) => snapshot.id === jobId)?.outputLimitBytes;
+}
+/** Validate the non-empty constraint that ParameterSchemaSpec cannot express. */
+function validateJobId(value) {
+	if (value.length === 0) throw new Error(`invalid job_id: expected a non-empty string, got ${JSON.stringify(value)}`);
+	return JobId(value);
+}
+/** Pending presentation shared by the three generic job controls. */
+function presentTaskCall(title, kind, rawInput) {
+	return {
+		card: "generic",
+		title,
+		kind,
+		...rawInput !== void 0 ? { rawInput } : {}
+	};
+}
+function apply(ctx, config) {
+	const waitDefault = config.waitTimeoutMs ?? 3e4;
+	const waitCap = config.maxWaitTimeoutMs ?? 6e5;
+	const delivery = config.completionDelivery ?? "wakeup";
+	const wakeBudget = config.maxConsecutiveWakes ?? 3;
+	const spentWakes = /* @__PURE__ */ new WeakMap();
+	if (waitDefault > waitCap) throw new Error(`tool-jobs: waitTimeoutMs (${waitDefault}) exceeds maxWaitTimeoutMs (${waitCap})`);
+	if (!Number.isSafeInteger(wakeBudget)) throw new Error(`tool-jobs: maxConsecutiveWakes (${wakeBudget}) must be a whole number of turns`);
+	if (delivery === "wakeup") ctx.on("agent/inbox/claimed", ({ agent, message }) => {
+		if (message.source.kind === "user") spentWakes.delete(agent);
+	});
+	const outputLimits = /* @__PURE__ */ new WeakMap();
+	ctx.on("tools/pre-execute", (exec, next) => {
+		const maxBytes = visibleOutputLimit(ctx, exec);
+		if (maxBytes !== void 0) outputLimits.set(exec, maxBytes);
+		return next();
+	}, { prepend: true });
+	const finalizeTaskContent = (exec, result) => {
+		const maxBytes = outputLimits.get(exec) ?? visibleOutputLimit(ctx, exec);
+		outputLimits.delete(exec);
+		if (maxBytes === void 0) return void 0;
+		if (exec.name === "job_output" && !result.isError) {
+			const value = result.value;
+			const body = value.text.length > 0 ? value.text : "(no new output)";
+			const content = body.endsWith("\n") ? body.slice(0, -1) : body;
+			const suffix = `\n${statusLine(value.job)}`;
+			if (rawSingleText(result.content) === `${content}${suffix}`) return [{
+				type: "text",
+				text: fitWithSuffix(content, suffix, maxBytes, "\n[output truncated]")
+			}];
+		}
+		return boundSingleText(result.content, maxBytes);
+	};
+	ctx.jobs.attachController("tool-jobs");
+	ctx.systemPrompt.section({
+		name: "tool:jobs",
+		order: 106,
+		text: "Track every background job id you start. You are notified in-session when a job finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running job's work. Before giving a final answer, collect every still-relevant job with job_output (set wait: true only when you are genuinely blocked on it), and job_kill jobs that stopped mattering."
+	});
+	ctx.jobs.onJobDone((snapshot, owner) => {
+		if (snapshot.reported || owner === void 0) return;
+		const message = createUserMessage({
+			content: [{
+				type: "text",
+				text: fitCompletionNotice(snapshot)
+			}],
+			source: {
+				kind: "plugin",
+				plugin: "tool-jobs",
+				form: "notice",
+				summary: completionSummary(snapshot)
+			}
+		});
+		const spent = spentWakes.get(owner) ?? 0;
+		if (delivery === "wakeup" && owner.status === "idle" && spent < wakeBudget) {
+			spentWakes.set(owner, spent + 1);
+			owner.followup(message);
+			return;
+		}
+		owner.inject(message);
+	});
+	ctx.tools.register(defineTool({
+		name: "job_output",
+		description: "Read a background job. Stream jobs return only output since the previous read; final-output jobs return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.",
+		parameters: {
+			job_id: {
+				type: "string",
+				required: true,
+				description: "Job id returned by the tool that started the background work."
+			},
+			wait: {
+				type: "boolean",
+				description: "Block until the job reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the job alive."
+			},
+			timeout_ms: {
+				type: "number",
+				description: "Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."
+			}
+		},
+		finalizeContent: finalizeTaskContent,
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					text: {
+						type: "string",
+						required: true
+					},
+					job: {
+						...PUBLIC_TASK_SCHEMA,
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => {
+				const body = value.text.length > 0 ? value.text : "(no new output)";
+				return [{
+					type: "text",
+					text: `${body}${body.endsWith("\n") ? "" : "\n"}${statusLine(value.job)}`
+				}];
+			}
+		},
+		async execute(args, exec) {
+			const id = validateJobId(args.job_id);
+			if (args.wait === true) {
+				const timeout = Math.min(args.timeout_ms ?? waitDefault, waitCap);
+				await ctx.jobs.wait(id, timeout, exec.agent, exec.signal);
+			}
+			const read = ctx.jobs.read(id, exec.agent);
+			return {
+				text: read.text,
+				job: publicJob(read.snapshot)
+			};
+		},
+		presentCall: (args) => presentTaskCall(`Read output from background job ${args.job_id}`, "read", args.job_id)
+	}));
+	ctx.tools.register(defineTool({
+		name: "job_list",
+		description: "List your background jobs (running and finished) with their ids, kinds, and statuses.",
+		parameters: {},
+		output: {
+			schema: {
+				type: "array",
+				items: PUBLIC_TASK_SCHEMA
+			},
+			render: (_args, jobs) => [{
+				type: "text",
+				text: jobs.length === 0 ? "(no background jobs)" : jobs.map((t) => `${t.id} [${t.kind}] ${t.status} — ${t.label}`).join("\n")
+			}]
+		},
+		execute(_args, exec) {
+			const jobs = ctx.jobs.list(exec.agent);
+			return Promise.resolve(jobs.map(publicJob));
+		},
+		presentCall: () => presentTaskCall("List background jobs", "read")
+	}));
+	ctx.tools.register(defineTool({
+		name: "job_kill",
+		description: "Request cancellation of a running background job by job id. Returns immediately; the job settles as killed once its work actually stops.",
+		parameters: {
+			job_id: {
+				type: "string",
+				required: true,
+				description: "Job id returned by the tool that started the background work."
+			},
+			reason: {
+				type: "string",
+				description: "Optional short reason, recorded in the log and forwarded to the job."
+			}
+		},
+		finalizeContent: finalizeTaskContent,
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					outcome: {
+						type: "string",
+						required: true,
+						enum: ["cancellation-requested", "already-finished"]
+					},
+					job: {
+						...PUBLIC_TASK_SCHEMA,
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.outcome === "already-finished" ? `job ${value.job.id} had already finished ${statusLine(value.job)}` : `requested cancellation of job ${value.job.id}`
+			}]
+		},
+		execute(args, exec) {
+			const id = validateJobId(args.job_id);
+			const result = ctx.jobs.kill(id, exec.agent, args.reason);
+			const snapshot = publicJob(ctx.jobs.get(id, exec.agent));
+			return Promise.resolve({
+				outcome: result === "already-finished" ? "already-finished" : "cancellation-requested",
+				job: snapshot
+			});
+		},
+		presentCall: (args) => presentTaskCall(`Kill background job ${args.job_id}`, "execute", args.job_id)
+	}));
+}
+//#endregion
+export { Config, apply, inject, name, statusLine };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-tool-jobs`.
+* @module @deepseek-ai/dsh-tool-jobs/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-tool-jobs";
+/** Cordis companion plugin name. */
+const name = "tool-jobs-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this model-facing adapter has no independent lifecycle stream; execution
+* relations are owned by the capability seam it calls.
+*/
+const install = () => {};
+/**
+* Register this package's 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/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Model-facing `job_output`, `job_list`, and `job_kill` tools over
+ * `ctx.jobs`. Loading the plugin attaches the controller required by
+ * producers. It also delivers unreported completions to the owning agent:
+ * injected into a busy owner's next step, or opening a turn on an idle one
+ * under the default `wakeup` delivery, bounded per owner.
+ * @module @deepseek-ai/dsh-tool-jobs
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { JobSnapshot } from '@deepseek-ai/dsh-jobs';
+export declare const name = "tool-jobs";
+export declare const inject: string[];
+/**
+ * How an unreported completion reaches an owner that is already idle: `wakeup`
+ * opens a turn for it, `quiet` leaves it pending until something else wakes the
+ * owner. A busy owner is injected either way.
+ */
+export type CompletionDelivery = 'quiet' | 'wakeup';
+/** Configures bounded `job_output` waits and completion-notice delivery. */
+export interface Config {
+    /** Wait duration applied when `job_output` sets `wait` without `timeout_ms` (default 30s). */
+    waitTimeoutMs?: number;
+    /** Hard cap on any single wait; a larger model-supplied `timeout_ms` is clamped down to it (default 10min). */
+    maxWaitTimeoutMs?: number;
+    /** Whether a completion opens a turn on an idle owner (default `wakeup`). */
+    completionDelivery?: CompletionDelivery;
+    /**
+     * Turns one owner may have opened by completion wakes before the next
+     * notice degrades to injection, reset by any user-authored input (default 3).
+     * Bounds the self-exciting chain where a woken turn starts the job whose
+     * completion wakes it again.
+     */
+    maxConsecutiveWakes?: number;
+}
+export declare const Config: z<Config>;
+/** Task state safe for model-authored programs; ownership/bookkeeping fields are omitted. */
+export interface PublicJobSnapshot {
+    id: string;
+    kind: string;
+    label: string;
+    status: JobSnapshot['status'];
+    detail?: string;
+    startedAt: number;
+    finishedAt?: number;
+}
+/**
+ * Render generic status with optional producer detail.
+ * @param snapshot - job state to render.
+ * @returns a bracketed status line.
+ */
+export declare function statusLine(snapshot: Pick<JobSnapshot, 'status' | 'detail'>): string;
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tool-jobs`.
+ * @module @deepseek-ai/dsh-tool-jobs/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-jobs-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's 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/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@deepseek-ai/dsh-tool-jobs",
+  "description": "Model-facing background job control tools (job_output, job_list, job_kill) over the ctx.jobs registry",
+  "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/tool-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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-output-retention": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-jobs": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-system-prompt": "^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-invariants": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-output-retention": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-jobs": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-jobs-local": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.3",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}