@x1a0f3n9/dsh-tool-jobs 0.1.5-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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: 8f3de4276d766f931f9461d25d15bf33aec26856
+README.zh.md: 83f8fca0cd7e74f4c4687351752bd8c36b002647

package/README.md

@@ -0,0 +1,187 @@
+---
+description: "The model-facing background-job controls for users and maintainers choosing, configuring, or debugging job_output, job_list, job_kill, and completion notices."
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-tool-jobs
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use `dsh-tool-jobs` to inspect and control background commands, PTY work, and subagents through `job_output`, `job_list`, and `job_kill`. Reads can wait within a configured timeout, list results identify each job's kind and status, and cancellation settles only after the work stops. When owned work finishes, the agent receives an in-session notice: busy agents receive it in their next step, while idle agents may be woken by a bounded follow-up turn. Configuration controls wait limits, completion delivery, and consecutive wakeups. Stream output is consumed by one reader, and pending notices do not survive owner disposal.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Load this plugin in any composition where the agent should start, observe, and stop background jobs: it registers the three tools, attaches the controller producers need, and delivers completion notices. It requires the `ctx.tools`, `ctx.jobs`, and `ctx.systemPrompt` services from the composed harness.
+
+### The three tools
+
+- `job_output(job_id, wait?, timeout_ms?)` — Read a job's output. Stream jobs return only the 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 and leaves a still-running job alive on timeout.
+- `job_list()` — List your background jobs with their ids, kinds, and statuses, one per line: `<id> [<kind>] <status> — <label>`.
+- `job_kill(job_id, reason?)` — Request cancellation of a running job immediately; the job settles as `killed` once its work actually stops. A terminal job returns its current snapshot, and the optional reason is recorded and forwarded to the job.
+
+The three tools return `{ text, job }`, `PublicJobSnapshot[]`, and `{ outcome: 'cancellation-requested' | 'already-finished', job }` respectively. A public snapshot carries id, kind, label, status/detail, and start/finish times and omits ownership and notification bookkeeping. All three render through generic UI cards: `read` for output and list, `execute` for kill.
+
+### Completion notices
+
+When a job finishes, the owning agent receives `background job <id> (<kind>: <label>) finished [status: ...]. Read its output with job_output.` as an in-session message. A busy agent has the notice injected into its next step — the turn cannot close while the inbox holds it, so several jobs settling together cost one step rather than one turn each. An idle agent is instead woken with a follow-up turn, because an unclaimed notice is a completion the model never learns about. A kill or a terminal read/wait marks the completion reported and suppresses the redundant notice, as does the teardown cancel that drains an owner or the service.
+
+Waking is bounded: each owner may be woken `maxConsecutiveWakes` times 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. `completionDelivery: quiet` keeps even idle owners on the injection lane, which deterministic transcripts need.
+
+### Minimal configuration
+
+Loading the plugin with no config is the common path; a `waitTimeoutMs` above `maxWaitTimeoutMs` fails at load.
+
+```yaml
+- name: '@x1a0f3n9/dsh-tool-jobs'
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `waitTimeoutMs` | `30,000` | Wait used when `wait: true` omits `timeout_ms` |
+| `maxWaitTimeoutMs` | `600,000` | Cap for model-supplied waits; larger values clamp down to it |
+| `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 |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-tool-jobs) is the exhaustive source for every accepted field and its JSDoc.
+
+### What can go wrong
+
+An agent whose composition loads no `tool-jobs` cannot start background work: this plugin's controller is what arms producers' `ctx.jobs.start()`. A model-supplied wait longer than `maxWaitTimeoutMs` is clamped down to the cap, and a timed-out wait returns `[status: running]` and leaves the job alive rather than failing. A completion notice pending on an idle owner does not survive that owner's disposal.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design decisions behind the tools and points at the code that realizes them; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design philosophy
+
+- **Kind-independent controls.** The same three tools read, list, and cancel jobs of every producer kind — bash, subagent, PTY — because all of them register through the generic `ctx.jobs` runtime.
+- **Delivery is owned here; recipients are the registry's.** The plugin decides how an unreported completion reaches the owner — injected into a busy step, or a woken turn on an idle owner — while the registry routes each settlement to the listeners its 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.
+- **Producer-owned output bounds.** When a producer supplies `outputLimitBytes`, the complete model-facing result — output read, terminal kill snapshot, or completion notice — is capped after status and notice metadata are added; producers that omit it keep unbounded behavior.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: tool registrations, completion listener, prompt section, output capping |
+| — | No runtime invariant companion is published; this model-facing adapter has no independent lifecycle stream; execution relations are owned by the capability seam it calls. |
+
+### Output capping
+
+`job_output` and `job_kill` capture the caller-visible job in a prepended pre-execute listener before policy runs, so the producer's cap applies to the complete rendered result. `job_output` preserves its output/status split when policy left the default rendering intact, bounding the output tail and the `[status: ...]` suffix; other single-text results — denials, short-circuits, normalized tool or pipeline failures, replacements, and blocks — are bounded as one text, while structured multi-block policy results keep their shape. A bounded completion notice reserves the stable `background job <id>` prefix and the `job_output` collection instruction before spending remaining bytes on variable kind, label, status, detail, and truncation marker, so the notice stays actionable at the PTY's supported 64-byte minimum; an existing producer truncation marker is reused rather than duplicated.
+
+### Notice delivery lanes
+
+`onJobDone` skips jobs already reported or unowned. A `wakeup` delivery opens a turn on an idle owner while the budget lasts, tracked per exact `Agent` in a `WeakMap`; claiming a user-authored message (`agent/inbox/claimed`) resets that owner's budget. A busy owner — or any notice past the budget, or `quiet` delivery — is injected into the next-step inbox instead. Teardown settlements arrive already `reported`, so disposal never spends a model request announcing a notice nobody can read.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the job types to the registry contract and the generated schemas.
+
+- [Background task runtime subsystem](../../../docs/subsystems/jobs.md) — the job types, snapshot fields, and `ctx.jobs` Cordis surface.
+- [jobs group map](../README.md) — the sibling group page and its package table.
+- [Registry contract](../jobs/README.md) — the abstract `ctx.jobs` service behind the tools.
+- [Process-local registry](../jobs-local/README.md) — where jobs run in this process.
+- [Generated tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-jobs) — the exact `job_output`, `job_list`, and `job_kill` schemas.
+- [Generated configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-tool-jobs) — every accepted config field and its source declaration.
+- [job-registry seam Agent Note](../../../.agents/notes/archived/architecture/2026-07-26-job-registry-seam.md) — the owner-fenced registry contract and its rationale.
+
+-----
+
+<a id="model-experience"></a>
+## 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. An 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 id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the tools are a poor fit. They are current package constraints, not a task backlog.
+
+- **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.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,187 @@
+---
+description: "面向模型的后台任务控制，供选择、配置或排查 job_output、job_list、job_kill 与完成通知的用户与维护者阅读。"
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-tool-jobs
+
+[English](README.md) | 中文
+
+## 概述
+
+使用 `dsh-tool-jobs`，可通过 `job_output`、`job_list` 与 `job_kill` 检查和控制后台命令、PTY 工作与 subagent。读取可在配置的超时内等待，列表结果标识各任务的 kind 与状态，而取消只有在工作停止后才结算。归属明确的工作完成时，agent（智能体）会收到会话内通知：繁忙的 agent 在下一步收到通知，空闲的 agent 则可能由有界的 follow-up 轮次唤醒。配置控制等待上限、完成投递与连续唤醒次数。流输出仅供单一读取方消费，待领通知无法在所有者释放后存活。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+在 agent 需要启动、观察和停止后台任务的任何组合中加载本插件：它注册三个工具、附加生产方所需的控制器，并投递完成通知。它需要组合中已提供的 `ctx.tools`、`ctx.jobs` 与 `ctx.systemPrompt` 服务。
+
+### 三个工具
+
+- `job_output(job_id, wait?, timeout_ms?)`——读取任务输出。流任务只返回自上次读取以来的输出；最终输出任务在结算后返回其结果。每个响应都以 `[status: ...]` 结尾。除非 `wait: true`，否则读取是非阻塞的；`wait: true` 最多等待到配置上限，超时时仍让运行中的任务保持存活。
+- `job_list()`——列出你的后台任务及其 id、kind 与状态，每行一个：`<id> [<kind>] <status> — <label>`。
+- `job_kill(job_id, reason?)`——立即请求取消运行中的任务；任务在其工作真正停止后以 `killed` 结算。终止任务返回其当前快照，可选的原因会被记录并转发给任务。
+
+三个工具依次返回 `{ text, job }`、`PublicJobSnapshot[]` 与 `{ outcome: 'cancellation-requested' | 'already-finished', job }`。公共快照携带 id、kind、label、status/detail 及开始／结束时间，并省略归属与通知簿记字段。三个工具都通过通用 UI 卡片渲染：output 和 list 用 `read`，kill 用 `execute`。
+
+### 完成通知
+
+任务完成时，拥有它的 agent 会收到会话内消息 `background job <id> (<kind>: <label>) finished [status: ...]. Read its output with job_output.`。繁忙的 agent 会在下一步收到注入的通知——inbox 尚有内容时轮次无法结束，因此同时结算的多个任务只花掉一步，而不是各占一轮。空闲的 agent 则被一个 follow-up 轮次唤醒，因为无人领取的通知等于模型永远不会知道的完成。kill 或针对终止任务的 read/wait 会把完成标为已报告并抑制重复通知；排空 owner 或服务的 teardown 取消同样如此。
+
+唤醒是有界的：每个所有者最多可被唤醒 `maxConsecutiveWakes` 次，此后的通知降级为注入；领取任何用户撰写的消息都会恢复预算。设界是因为这条链会自激——被唤醒的一轮可能启动某个后台任务，而它的完成又会唤醒同一个所有者。`completionDelivery: quiet` 让空闲所有者也在注入通道上，确定性 transcript（文本记录）需要的正是这一点。
+
+### 最小配置
+
+不带配置加载插件是常用路径；`waitTimeoutMs` 高于 `maxWaitTimeoutMs` 时会在加载时失败。
+
+```yaml
+- name: '@x1a0f3n9/dsh-tool-jobs'
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `waitTimeoutMs` | `30,000` | `wait: true` 省略 `timeout_ms` 时使用的等待时间 |
+| `maxWaitTimeoutMs` | `600,000` | 模型所给等待时间的上限；更大的值向下收敛到它 |
+| `completionDelivery` | `wakeup` | `wakeup` 为空闲所有者开启一轮；`quiet` 让通知继续待领 |
+| `maxConsecutiveWakes` | `3` | 一个所有者可由唤醒开启的轮数，超出后通知降级为注入 |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-tool-jobs)是每个受支持字段及其 JSDoc 的穷尽式真源。
+
+### 可能出什么问题
+
+组合中未加载 `tool-jobs` 的 agent 无法启动后台工作：本插件的控制器正是生产方 `ctx.jobs.start()` 得以启用所依赖的。模型给出的等待时间超过 `maxWaitTimeoutMs` 时会向下收敛到上限，超时的等待返回 `[status: running]` 并让任务保持存活，而不是失败。待领于空闲所有者的完成通知无法在该所有者释放后存活。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释工具背后的设计决策，并指出实现它们的代码位置；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+- **与 kind 无关的控制。** 同一套三个工具读取、列出和取消每种生产方 kind 的任务——bash、subagent、PTY——因为它们都通过通用的 `ctx.jobs` 运行时注册。
+- **投递归本插件，收件人归注册表。** 插件决定未报告的完成如何到达所有者——注入繁忙的一步，或唤醒空闲所有者的一轮——而注册表把每次结算路由给其所有者 scope 链所能抵达的监听器，因此某个 preset 下的挂载永远看不到另一个 preset 的 agent，无论挂载了多少 preset，一个 agent 每次完成都只读到一条通知。
+- **生产方自有的输出上限。** 生产方提供 `outputLimitBytes` 时，完整的模型侧结果——输出读取、终止 kill 快照或完成通知——会在添加状态与通知元数据之后被施加上限；省略该字段的生产方保持无界行为。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：工具注册、完成监听器、提示词区段、输出上限 |
+| — | 不发布运行时不变式伴生入口；这个面向模型的适配器没有独立的生命周期流；执行关系归其调用的能力 seam 所有。 |
+
+### 输出上限
+
+`job_output` 与 `job_kill` 会在策略运行前于前置的 pre-execute 监听器中捕获调用方可见任务，因此生产方上限适用于完整渲染结果。`job_output` 在策略保留默认渲染时保持其输出／状态拆分，对输出尾部与 `[status: ...]` 后缀设界；其他单文本结果——拒绝、短路、规范化工具或流水线失败、替换与阻止——按单个文本设界，而结构化多块策略结果保持自身形状。有界完成通知先为稳定的 `background job <id>` 前缀与 `job_output` 收集指令预留空间，再把剩余字节用于可变的 kind、label、status、detail 与截断标记，因此在 PTY 支持的 64 字节下限下通知仍可操作；已有的生产方截断标记会被复用，不会重复添加。
+
+### 通知投递通道
+
+`onJobDone` 跳过已报告或无所有者的任务。`wakeup` 投递在预算内为空闲所有者开启一轮，按确切 `Agent` 记录在 `WeakMap` 中；领取用户撰写的消息（`agent/inbox/claimed`）会重置该所有者的预算。繁忙的所有者——或超出预算的任何通知，以及 `quiet` 投递——改为注入 next-step inbox。teardown 结算抵达时已标记为 `reported`，因此释放永远不会花一次模型请求来宣布无人能读的通知。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。它们从任务类型逐步进入注册表约定与生成 schema。
+
+- [后台任务运行时子系统](../../../docs/subsystems/jobs.zh.md)——任务类型、快照字段与 `ctx.jobs` 的 Cordis 接口面。
+- [jobs 组映射](../README.zh.md)——同级组页面及其包表格。
+- [注册表约定](../jobs/README.zh.md)——工具背后的抽象 `ctx.jobs` 服务。
+- [进程本地注册表](../jobs-local/README.zh.md)——任务在本进程中的运行位置。
+- [生成的工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-jobs)——`job_output`、`job_list` 与 `job_kill` 的确切 schema。
+- [生成的配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-tool-jobs)——每个受支持配置字段及其源声明。
+- [任务注册表 seam Agent Note](../../../.agents/notes/archived/architecture/2026-07-26-job-registry-seam.md)——按所有者隔离的注册表约定及其理由。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 系统提示词
+
+#### 模型看到什么
+
+该插件注册 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.zh.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>` 或现有终止状态。尚未报告且有所有者归属的完成使用上述通知。
+
+#### Token 影响
+
+结果与通知在压缩（compaction）前保留于父级历史。流读取不会重复已消费的输出；生产方提供的 `outputLimitBytes` 会限制每次完整读取或通知。在 `wakeup` 下，抵达空闲所有者的通知还会额外买下一次用户并未要求的模型请求，其数量按所有者由 `maxConsecutiveWakes` 封顶；抵达繁忙所有者的通知则只是给它已经在支付的那一轮加一步。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明工具何时不合适。它们是当前包约束，不是任务积压。
+
+- **落在 driver 退休窗口内的结算仍会让通知搁浅**——在轮次循环最后一次检查 inbox 与 driver 提交 idle 相位之间，所有者读起来仍是繁忙，因此通知走注入且无人唤醒。steering（中途引导）存在同样的问题；修复它属于 `agent-loop`。
+- **已花掉的唤醒预算不会随时间恢复**——只有用户撰写的输入才能补充，因此预算耗尽的无人值守 agent 要等到其他原因开启下一轮时才收走剩余通知。
+- **待领于空闲所有者的通知无法在该所有者释放后存活**——释放时的取消会清空未领取的 inbox，日志保留插入/取消这一对作为记录。
+- **流读取只有单一消费方**——独立观察者需要另一套运行时 API。
+- **无 owner 的任务没有会话隔离**——外部调用方必须提供策略或避开这些任务。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,353 @@
+import z from "@deepseek-ai/schemastery";
+import { boundContextSummary, createUserMessage } from "@x1a0f3n9/dsh-llm";
+import { TextRetainer } from "@x1a0f3n9/dsh-output-retention";
+import { defineTool } from "@x1a0f3n9/dsh-tools";
+import { JobId } from "@x1a0f3n9/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 @x1a0f3n9/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: ctx.systemPrompt.getSectionOrder("TOOL_JOBS"),
+		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/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 @x1a0f3n9/dsh-tool-jobs
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { JobSnapshot } from '@x1a0f3n9/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/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@x1a0f3n9/dsh-tool-jobs",
+  "description": "Model-facing background job control tools (job_output, job_list, job_kill) over the ctx.jobs registry",
+  "version": "0.1.5-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "peerDependencies": {
+    "@x1a0f3n9/dsh-agent": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-llm": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-jobs": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-system-prompt": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-tools": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-output-retention": "^0.1.5-rc.2",
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@x1a0f3n9/dsh-agent": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-llm": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-session": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-jobs-local": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-output-retention": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-jobs": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-tools": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-system-prompt": "^0.1.5-rc.2",
+    "@deepseek-ai/cordis": "^4.0.2"
+  }
+}