@deepseek-ai/dsh-tool-workflow 0.1.6-alpha.2 → 0.1.7-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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/workflow/tool-workflow/README.md
-README.md: 4cf16a233637da3fb2384ba80cdba8adb0298e5a
-README.zh.md: cfbbdd74f14c1c6f8c8c97b2bb84366ff61bb4d1
+README.md: ce2804d2db83e410edb248332c517200dd6963dc
+README.zh.md: 2ef39745a74eb6ab899108613c8cc8ac396f1352

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-tool-workflow` lets a model run a JavaScript orchestration script that delegates work to many subagents and returns the script's final JSON value. Use it only when the user explicitly requests a workflow or large multi-agent orchestration; use plain subagent calls for one or two delegations. The parent turn waits until every delegated task settles, and cancellation or abnormal completion returns an error rather than partial success. Deployments can rename the tool and cap rendered result text through `toolName` and `maxResultChars`.
+`dsh-tool-workflow` lets a model run JavaScript orchestration that delegates to many subagents and returns a final JSON value. Use it only when the user explicitly requests a workflow or large multi-agent orchestration; prefer plain subagent calls for one or two delegations. Foreground execution waits for all work; cancellation or abnormal completion returns an error rather than partial success. `run_in_background: true` returns an owned job id immediately and exposes live output. Deployments can rename the tool with `toolName` and cap rendered results with `maxResultChars`.
 
 ## Table of Contents
 
@@ -29,20 +29,25 @@ The `workflow` tool runs a model-authored orchestration script that fans work ou
 
 ### Calling the tool
 
-The model submits three parameters: `meta` (required identity data: `name`, `description`, and optional `whenToUse` and `phases`), `script` (required plain JavaScript body — no `export const meta` statement; the tool description carries the complete authoring contract), and `args` (optional JSON object exposed to the script as the `args` global; wrap a bare list in a field so the wire schema stays honest).
+The model submits three parameters plus one flag: `meta` (required identity data: `name`, `description`, and optional `whenToUse` and `phases`), `script` (required plain JavaScript body — no `export const meta` statement; the tool description carries the complete authoring contract), `args` (optional JSON object exposed to the script as the `args` global; wrap a bare list in a field so the wire schema stays honest), and `run_in_background` (optional; present only while `enableRunInBackground` holds).
 
-Success returns the canonical envelope `{ runId, agentsStarted, result }`, rendered to the model as `workflow "<name>" completed (<count> agent<optional-s>).` followed by `Return value:` and the pretty-printed JSON. A workflow that cannot start — a script parse or meta validation failure — returns an error the model can correct from. Cancellation and execution failures return `Error: workflow run was cancelled` or `Error: workflow run failed: <error>`; partial output is never reported as success.
+A foreground success returns the envelope `{ kind: 'foreground', runId, agentsStarted, result }`, rendered to the model as `workflow "<name>" completed (<count> agent<optional-s>).` followed by `Return value:` and the pretty-printed JSON. A workflow that cannot start — a script parse or meta validation failure — returns an error the model can correct from. Cancellation and execution failures return `Error: workflow run was cancelled` or `Error: workflow run failed: <error>`; partial output is never reported as success.
 
 ### What to expect during a run
 
 While the script runs, the parent turn waits: the tool starts the run, awaits its result, and always disposes it, so the script and its children reach quiescence on every path — including cancellation, which is bridged from the parent step's abort signal. The model sees one final outcome, never intermediate child messages; the children's own work stays out of the parent conversation.
 
+### Background runs
+
+`run_in_background: true` returns `{ kind: 'background', jobId, runId }` immediately: the run is registered on `ctx.jobs` as an owned `workflow` job, so the session-header job list streams its `phase()`, `log()`, and member lifecycle lines live from the job's output ring, and the row's progress line tracks the current phase. No tool-step signal reaches the run — `job_kill`, the list's stop control, and owner teardown are what cancel it. Settlement is the job's settlement: a completed run carries the same rendered return value as the job's result (the completion notice announces it, the model's first `job_output` after settlement carries it once), a cancelled run settles `killed` with the kill reason, and a failed run settles `failed` with the script's failure message. Without a live job registry and a controller serving the caller the call fails, naming the missing composition pieces.
+
 ### Config
 
 | Field | Default | Meaning |
 |---|---|---|
 | `toolName` | `workflow` | The model-facing tool name to register. |
 | `maxResultChars` | `50000` | Rendered-result ceiling; longer JSON is truncated with a notice. |
+| `enableRunInBackground` | `true` | Expose `run_in_background`; disabled calls are also rejected. |
 
 The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-tool-workflow) is the exhaustive source for every accepted field.
 
@@ -62,12 +67,18 @@ The consumer owns the model-facing schema, the `tool:<toolName>` system-prompt g
 
 ### Run lifecycle
 
-`execute` starts the run and awaits `run.result` inside a `try/finally` that always disposes the run. `exec.signal` is bridged to `run.cancel()`, including the already-aborted-before-start case. A non-`completed` stop reason maps to an `isError` result reporting the reason; completion renders `{ runId, agentsStarted, result }`, with the Native renderer truncating only that projection at `maxResultChars`.
+`execute` starts the run and awaits `run.result` inside a `try/finally` that always disposes the run. `exec.signal` is bridged to `run.cancel()`, including the already-aborted-before-start case. A non-`completed` stop reason maps to an `isError` result reporting the reason; completion renders `{ kind, runId, agentsStarted, result }`, with the Native renderer truncating only that projection at `maxResultChars`.
+
+### Background lifecycle
+
+A background call registers the run through `jobs.start` inside the job starter, so a synchronous engine rejection registers nothing and admission preflight runs before the engine spawns. The job's `done` chains from `run.result`: dispose (a disposal failure is warned, never rejected into the registry), stop the mirrors, then map the stop reason onto the job outcome. The ring mirror (`src/record.ts`) subscribes `workflow/phase`, `workflow/log`, and member events once per plugin and routes them into the tracked runs' `JobHandle` faces (`append` for lines, `updateProgress` for the phase); a straggling event after settlement finds no tracked run, and an append against a settled job drops inside the registry.
 
 ### Durable session records
 
 For a root transport execution (`exec.parent` absent), the tool projects the run into the calling Agent's Session with four log-only events: run-start after `start()` returns, member starts and endings filtered by `run.id`, then run-end only after the result is available and disposal reaches quiescence. Nested transport calls execute normally but write no record. The first failed Session append disables later recording for that run with one warning, leaving either no record or a legal continuous prefix without changing the tool result or cleanup. The package invariant rejects duplicate starts, unpaired members, terminal events with open members, and updates after run-end on both cold load and live append, while accepting missing terminal suffixes.
 
+The engine's `workflow/phase` and `workflow/log` events have no per-line durable surface from this tool: the session log deliberately records run and member lifecycle only, and the Web transcript derives from those records. A background run's lines reach a human through the job observation record instead, which is transient by design.
+
 ### Render intent
 
 Decided up front per the [render-intent Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md): a `generic` card titled `workflow: <meta.name>`, read directly from `args.meta.name` — presentation is a pure function of args — with the script text carried as `rawInput`. The result keeps the generic card.
@@ -76,7 +87,8 @@ Decided up front per the [render-intent Agent Note](../../../.agents/notes/imple
 
 | File | Role |
 |---|---|
-| [`src/index.ts`](src/index.ts) | Plugin entry: tool registration, run lifecycle, recorder wiring |
+| [`src/index.ts`](src/index.ts) | Plugin entry: tool registration, run lifecycle, background job registration, recorder wiring |
+| [`src/record.ts`](src/record.ts) | Background runs' live-progress mirror into the job's output ring |
 | [`src/types.ts`](src/types.ts) | The four log-only record event payloads and their `SessionEventMap` declaration |
 | [`src/invariant.ts`](src/invariant.ts) | Invariant companion: durable workflow-record protocol validation |
 
@@ -139,7 +151,7 @@ Prefix-stable while `toolName`, definition, and visibility are unchanged. Renami
 
 #### What the model sees
 
-The full model-written script, metadata, and args remain in the assistant tool call. Success is exactly `workflow "<name>" completed (<count> agent<optional-s>).`, newline, `Return value:`, newline, and pretty-printed data-dependent JSON; a cap adds `… [truncated: <omitted> more characters]` on a new line. Failures are exactly `Error: workflow run was cancelled`, optionally suffixed ` (<error>)`, `Error: workflow run failed: <error-or-unknown error>`, or defensively `Error: workflow run ended abnormally (<reason>)`; a call without an owning agent becomes `Error: workflow tool requires a calling agent (exec.agent was undefined)`. Intermediate child messages are omitted.
+The full model-written script, metadata, and args remain in the assistant tool call. A foreground success is exactly `workflow "<name>" completed (<count> agent<optional-s>).`, newline, `Return value:`, newline, and pretty-printed data-dependent JSON; a cap adds `… [truncated: <omitted> more characters]` on a new line. A background acceptance is exactly `workflow "<name>" started in the background as job <jobId>. Its return value arrives with the completion notice; check on it with job_output, stop it with job_kill.`, and the same rendered value later reaches the model through the job's completion notice and `job_output`. Failures are exactly `Error: workflow run was cancelled`, optionally suffixed ` (<error>)`, `Error: workflow run failed: <error-or-unknown error>`, or defensively `Error: workflow run ended abnormally (<reason>)`; a call without an owning agent becomes `Error: workflow tool requires a calling agent (exec.agent was undefined)`. Intermediate child messages are omitted.
 
 #### Token effect
 
@@ -156,10 +168,11 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 These limits define what the tool does not yet support. They are current constraints, not a task backlog.
 
-- **The parent turn blocks until the whole workflow settles** — there is no background start/poll API, and cancellation discards partial output as an error.
+- **A background run reports no intermediate value to the model** — `job_output` before settlement returns status only; the return value arrives whole at completion, and cancellation still discards partial output.
 - **`args` must be an object and Native result text is bounded** — callers wrap top-level arrays and scalars in a field; the canonical workflow result stays complete, while JSON beyond `maxResultChars` is truncated in the model-facing projection rather than stored behind a retrieval handle.
 - **Workflow policy is fixed per tool registration** — provider selection, caps, and tool name are deployment config, not model-call arguments.
 - **Durable records are top-level and observational** — nested PTC mode dispatches are not recorded, and a recording failure intentionally degrades to an incomplete prefix rather than changing execution.
+- **No recorded-session scenario replays a background run yet** — unit and real-engine composition suites cover the path; the snapshot tree pins only the schema and prompt text.
 
 <a id="dev-note"></a>
 ### Dev Note
@@ -169,6 +182,6 @@ These limits define what the tool does not yet support. They are current constra
 
 This Dev Note is working context for maintainers: open directions that are not decided. It is explicitly non-authoritative — shipped behavior, limits, and accepted rationale live in the sections above, the package code, and the linked Agent Notes.
 
-Open directions: a background start/poll route so the parent turn does not block; storing truncated JSON behind a retrieval handle instead of clipping the projection; recording nested dispatches beyond the top level.
+Open directions: storing truncated JSON behind a retrieval handle instead of clipping the projection; recording nested dispatches beyond the top level; a recorded-session scenario for the background path.
 
 </details>

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-tool-workflow` 让模型运行 JavaScript 编排脚本，把工作委派给多个 subagent，并返回脚本的最终 JSON 值。仅当用户明确要求工作流或大型多 agent（智能体）编排时使用；一两项委派应使用普通 subagent 调用。父级轮次会等待所有委派任务结束；取消或异常完成会返回错误，而不是部分成功。部署方可以通过 `toolName` 重命名工具，并通过 `maxResultChars` 限制渲染结果文本。
+`dsh-tool-workflow` 让模型运行 JavaScript 编排，将工作委派给多个 subagent，并返回最终 JSON 值。仅当用户明确要求工作流或大型多 agent（智能体）编排时使用；一两项委派应优先使用普通 subagent 调用。前台执行等待所有工作结束；取消或异常完成返回错误，而不是部分成功。`run_in_background: true` 立即返回自有任务 id，并提供实时输出。部署方可以用 `toolName` 重命名工具，用 `maxResultChars` 限制渲染结果。
 
 ## 目录
 
@@ -29,20 +29,25 @@ kind: "package-reference"
 
 ### 调用工具
 
-模型提交三个参数：`meta`（必需的身份数据：`name`、`description`，以及可选的 `whenToUse` 与 `phases`）、`script`（必需的纯 JavaScript 脚本体——不含 `export const meta` 语句；工具描述携带完整的编写约定）与 `args`（可选 JSON 对象，作为全局变量 `args` 向脚本公开；裸列表应包装到字段中，使协议 schema 如实表达形态）。
+模型提交三个参数外加一个开关：`meta`（必需的身份数据：`name`、`description`，以及可选的 `whenToUse` 与 `phases`）、`script`（必需的纯 JavaScript 脚本体——不含 `export const meta` 语句；工具描述携带完整的编写约定）、`args`（可选 JSON 对象，作为全局变量 `args` 向脚本公开；裸列表应包装到字段中，使协议 schema 如实表达形态），以及 `run_in_background`（可选；仅在 `enableRunInBackground` 生效时存在）。
 
-成功返回规范包络 `{ runId, agentsStarted, result }`，向模型渲染为 `workflow "<name>" completed (<count> agent<optional-s>).`，后接 `Return value:` 与美化打印的 JSON。无法启动的工作流——脚本解析或 meta 校验失败——返回模型可以修正的错误。取消与执行失败返回 `Error: workflow run was cancelled` 或 `Error: workflow run failed: <error>`；部分输出绝不会被报告为成功。
+前台成功返回包络 `{ kind: 'foreground', runId, agentsStarted, result }`，向模型渲染为 `workflow "<name>" completed (<count> agent<optional-s>).`，后接 `Return value:` 与美化打印的 JSON。无法启动的工作流——脚本解析或 meta 校验失败——返回模型可以修正的错误。取消与执行失败返回 `Error: workflow run was cancelled` 或 `Error: workflow run failed: <error>`；部分输出绝不会被报告为成功。
 
 ### 运行期间的预期
 
 脚本运行期间，父级轮次会等待：工具启动运行、等待其结果，并始终对该运行执行 dispose（资源释放），因此脚本及其子 agent 在每条路径上完全停稳——包括从父级步骤中止信号桥接而来的取消。模型只看到最终结果，永远不会看到中间子 agent 消息；子 agent 自己的工作不会进入父级对话。
 
+### 后台运行
+
+`run_in_background: true` 会立刻返回 `{ kind: 'background', jobId, runId }`：运行以自有 `workflow` 任务身份注册到 `ctx.jobs`，会话头部任务列表因此从该任务的输出环实时流式显示它的 `phase()`、`log()` 与成员生命周期行，行的进度行跟随当前阶段。没有任何工具步骤信号到达该运行——`job_kill`、列表里的停止控件与 owner 拆除才是取消它的途径。结算即任务的结算：完成的运行把同一份渲染后的返回值作为任务的 result 交出（完成通知宣布它，模型结算后的第一次 `job_output` 携带它一次），被取消的运行以 kill 原因结算为 `killed`，失败的运行以脚本的失败信息结算为 `failed`。没有活体任务注册表与服务于调用方的控制器时调用失败，并点名缺失的组合部件。
+
 ### 配置
 
 | 字段 | 默认值 | 含义 |
 |---|---|---|
 | `toolName` | `workflow` | 要注册的面向模型工具名称。 |
 | `maxResultChars` | `50000` | 渲染结果上限；更长的 JSON 会被截断并附上提示。 |
+| `enableRunInBackground` | `true` | 公开 `run_in_background`；关闭后调用同样会被拒绝。 |
 
 生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-tool-workflow)是每个受支持字段的穷尽式真源。
 
@@ -62,12 +67,18 @@ kind: "package-reference"
 
 ### 运行生命周期
 
-`execute` 启动运行，并在 `try/finally` 内等待 `run.result`；该结构总会对运行执行 dispose。`exec.signal` 会桥接到 `run.cancel()`，包括启动前已经中止的情况。非 `completed` 结束原因会映射为报告原因的 `isError` 结果；完成时渲染 `{ runId, agentsStarted, result }`，Native 渲染器只会在 `maxResultChars` 处截断该投影。
+`execute` 启动运行，并在 `try/finally` 内等待 `run.result`；该结构总会对运行执行 dispose。`exec.signal` 会桥接到 `run.cancel()`，包括启动前已经中止的情况。非 `completed` 结束原因会映射为报告原因的 `isError` 结果；完成时渲染 `{ kind, runId, agentsStarted, result }`，Native 渲染器只会在 `maxResultChars` 处截断该投影。
+
+### 后台生命周期
+
+后台调用在任务 starter 内经 `jobs.start` 注册运行，因此引擎的同步拒绝什么都不会注册，准入预检也先于引擎生成执行。任务的 `done` 链接自 `run.result`：先 dispose（释放失败只告警，绝不 reject 进注册表），再停止镜像，然后把停止原因映射到任务结果。环镜像（`src/record.ts`）按插件订阅一次 `workflow/phase`、`workflow/log` 与成员事件，并把它们路由进被跟踪运行的 `JobHandle` 面（`append` 写行，`updateProgress` 写阶段）；结算后的零星事件找不到被跟踪的运行，对已结算任务的 append 则在注册表内丢弃。
 
 ### 持久会话记录
 
 对于根 transport 执行（`exec.parent` 缺省），工具会用四个 log-only 事件把运行投影到调用方 agent 的会话：`start()` 返回后写 run-start，只记录 `run.id` 匹配的成员开始与结束，并且只在结果可用且 dispose 完全停稳后写 run-end。嵌套 transport 调用照常执行，但不写任何记录。会话追加操作首次失败后，本运行会停止后续记录并只告警一次，留下空记录或合法连续前缀，同时不改变工具结果和清理。包 invariant 会在冷加载与实时追加时拒绝重复 start、未配对成员、仍有开放成员的终点与 run-end 后更新，同时允许缺失终态后缀的连续前缀。
 
+引擎的 `workflow/phase` 与 `workflow/log` 事件在本工具没有逐行的持久面：会话日志刻意只记录 run 与成员生命周期，Web transcript 由这些记录派生。后台运行的这些行改经任务观察 record 抵达人类，而 record 的瞬态是设计使然。
+
 ### 渲染意图
 
 按[渲染意图 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.zh.md)预先确定：使用 `generic` 卡片，标题为 `workflow: <meta.name>`，直接从 `args.meta.name` 读取——呈现是参数的纯函数——脚本文本作为 `rawInput` 携带。结果继续使用 generic 卡片。
@@ -76,7 +87,8 @@ kind: "package-reference"
 
 | 文件 | 职责 |
 |---|---|
-| [`src/index.ts`](src/index.ts) | 插件入口：工具注册、运行生命周期、记录器接线 |
+| [`src/index.ts`](src/index.ts) | 插件入口：工具注册、运行生命周期、后台任务注册、记录器接线 |
+| [`src/record.ts`](src/record.ts) | 后台运行进任务输出环的实时进度镜像 |
 | [`src/types.ts`](src/types.ts) | 四个 log-only 记录事件 payload 及其 `SessionEventMap` 声明 |
 | [`src/invariant.ts`](src/invariant.ts) | 不变式配套入口：持久工作流记录协议校验 |
 
@@ -139,7 +151,7 @@ Use the <toolName> tool ONLY when the user explicitly asks for a workflow or for
 
 #### 模型看到什么
 
-由模型编写的完整脚本、元数据与 args 会保留在 assistant 工具调用中。成功结果精确为 `workflow "<name>" completed (<count> agent<optional-s>).`、换行、`Return value:`、换行，以及美化打印且依赖数据的 JSON；达到上限时，会在新行添加 `… [truncated: <omitted> more characters]`。失败结果精确为 `Error: workflow run was cancelled`（可以追加后缀 ` (<error>)`）、`Error: workflow run failed: <error-or-unknown error>` 或防御性的 `Error: workflow run ended abnormally (<reason>)`；没有所属 agent 的调用变为 `Error: workflow tool requires a calling agent (exec.agent was undefined)`。中间子 agent 消息会被省略。
+由模型编写的完整脚本、元数据与 args 会保留在 assistant 工具调用中。前台成功结果精确为 `workflow "<name>" completed (<count> agent<optional-s>).`、换行、`Return value:`、换行，以及美化打印且依赖数据的 JSON；达到上限时，会在新行添加 `… [truncated: <omitted> more characters]`。后台受理结果精确为 `workflow "<name>" started in the background as job <jobId>. Its return value arrives with the completion notice; check on it with job_output, stop it with job_kill.`，同样渲染的值稍后经任务完成播报与 `job_output` 抵达模型。失败结果精确为 `Error: workflow run was cancelled`（可以追加后缀 ` (<error>)`）、`Error: workflow run failed: <error-or-unknown error>` 或防御性的 `Error: workflow run ended abnormally (<reason>)`；没有所属 agent 的调用变为 `Error: workflow tool requires a calling agent (exec.agent was undefined)`。中间子 agent 消息会被省略。
 
 #### Token 影响
 
@@ -156,10 +168,11 @@ Use the <toolName> tool ONLY when the user explicitly asks for a workflow or for
 
 这些限制说明该工具尚未支持什么。它们是当前约束，不是任务积压。
 
-- **父级轮次会阻塞到整个工作流结算**——没有后台启动／轮询接口，取消会丢弃局部输出并返回错误。
+- **后台运行不向模型报告中间值**——结算前的 `job_output` 只返回状态；返回值在完成时整体送达，取消仍会丢弃局部输出。
 - **`args` 必须是对象，Native 结果文本有界**——调用方把顶层数组／标量包装到字段中；规范工作流结果保持完整，超过 `maxResultChars` 的 JSON 会在面向模型的投影中截断，而不是存储在检索句柄背后。
 - **每次工具注册的工作流策略固定**——提供方选择、上限与工具名称属于部署配置，不是模型调用参数。
 - **持久记录只覆盖顶层且只供观察**——嵌套 PTC mode dispatch 不记录；记录故障会刻意退化为不完整前缀，而不改变执行。
+- **尚无回放后台运行的 recorded-session 场景**——单元与真实引擎组合套件覆盖该路径；快照树只钉住 schema 与提示词文本。
 
 <a id="dev-note"></a>
 ### 开发备注
@@ -169,6 +182,6 @@ Use the <toolName> tool ONLY when the user explicitly asks for a workflow or for
 
 本开发备注是维护者的工作上下文：尚未决定的开放方向。它明确不具权威性——已交付的行为、限制与既定理由以上文、包代码与相关 Agent Note 为准。
 
-开放方向：让父级轮次不再阻塞的后台启动／轮询路径；把截断的 JSON 存储在检索句柄背后，而不是剪裁投影；记录超出顶层的嵌套 dispatch。
+开放方向：把截断的 JSON 存储在检索句柄背后，而不是剪裁投影；记录超出顶层的嵌套 dispatch；为后台路径补一个 recorded-session 场景。
 
 </details>

package/lib/index.js

@@ -1,13 +1,58 @@
 import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region lib/types/record.js
+/**
+* Live-progress mirror for background workflow runs: streams the engine's
+* `workflow/phase`, `workflow/log`, and member lifecycle events into the
+* owning job's output ring as `log` chunks — observer-only narration the
+* model's `job_output` never renders — and keeps the job's live progress
+* line on the current phase. Appends against a settled job log and drop
+* inside the registry, so a straggling event after settlement is harmless.
+* @module @deepseek-ai/dsh-tool-workflow/record
+*/
+/**
+* Create the run-to-ring mirror and subscribe the engine's live progress
+* events for the runs it tracks.
+* @param ctx - plugin context whose event bus carries the `workflow/*` events.
+* @returns the mirror taps the tool wires around each background run.
+*/
+function createWorkflowRecordMirror(ctx) {
+	const active = /* @__PURE__ */ new Map();
+	ctx.on("workflow/phase", (info, title) => {
+		const job = active.get(info.id);
+		if (job === void 0) return;
+		job.updateProgress(title);
+		job.append(`▸ ${title}\n`, { channel: "log" });
+	});
+	ctx.on("workflow/log", (info, message) => {
+		active.get(info.id)?.append(`${message}\n`, { channel: "log" });
+	});
+	ctx.on("workflow/agent-start", (info, agent) => {
+		active.get(info.id)?.append(`agent #${agent.seq} ${agent.label} started\n`, { channel: "log" });
+	});
+	ctx.on("workflow/agent-end", (info, agent) => {
+		active.get(info.id)?.append(`agent #${agent.seq} ${agent.outcome}\n`, { channel: "log" });
+	});
+	return {
+		start(runId, job) {
+			active.set(runId, job);
+		},
+		stop(runId) {
+			active.delete(runId);
+		}
+	};
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * The model-facing `workflow` tool: run a JavaScript orchestration script that fans out
 * subagents, and return the script's final value. It owns the model-facing schema and run lifecycle; script
 * parsing, execution, caps, and cancellation live behind `ctx.workflowEngine`
 * (`@deepseek-ai/dsh-workflow`), so a hardened engine swaps in without touching what the model
-* sees. Execution awaits `run.result` and always disposes the run; non-completed reasons become tool
-* errors, and background collection remains deferred. Presentation is an args-only generic card
+* sees. Foreground execution awaits `run.result` and always disposes the run; non-completed reasons
+* become tool errors. `run_in_background: true` instead registers the run as an owned `ctx.jobs` job
+* and returns its id immediately — the job's output ring streams live progress, and the run's value
+* arrives with the job's completion notice. Presentation is an args-only generic card
 * titled from `meta.name`. Explicit-ask usage guidance is registered as the tool's own prompt
 * section rather than deployment persona prose.
 * @module @deepseek-ai/dsh-tool-workflow
@@ -20,7 +65,8 @@ const inject = [
 ];
 const Config = z.object({
 	toolName: z.string().default("workflow"),
-	maxResultChars: z.natural().min(1).default(5e4)
+	maxResultChars: z.natural().min(1).default(5e4),
+	enableRunInBackground: z.boolean().default(true)
 });
 /** Render a contained recording failure without trusting the thrown value. */
 function renderRecordingError(error) {
@@ -89,7 +135,8 @@ function createWorkflowRecorder(ctx) {
 /**
 * The script-authoring contract, embedded in the tool description. This IS the
 * model-facing spec: the meta block, the hooks and their exact semantics, and
-* the supported schema subset.
+* the supported schema subset. The closing execution sentence follows the
+* composition: only a background-enabled tool describes `run_in_background`.
 */
 const DESCRIPTION = `Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.
 
@@ -103,7 +150,9 @@ Script-body hooks:
 
 Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item \`null\`.
 
-Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.`;
+Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them.`;
+const FOREGROUND_ONLY_CLOSING = " The run executes in the foreground: this call returns when the whole script finishes.";
+const BACKGROUND_CLOSING = " The run executes in the foreground by default: this call returns when the whole script finishes. Set `run_in_background: true` for a long run: the call returns a job id immediately, the run keeps orchestrating in the background, and its return value arrives with the job's completion notice (check on it with `job_output`, stop it with `job_kill`).";
 /** The pending-state card: a generic card titled by the workflow's meta name. */
 function presentWorkflowCall(args) {
 	return {
@@ -126,15 +175,98 @@ function stopReasonError(result) {
 		default: return `workflow run ended abnormally (${String(result.stopReason)})`;
 	}
 }
+/**
+* Map a settled background run onto the job outcome vocabulary. A completed
+* run carries the rendered return value as the job's result; a
+* cancelled run leaves the detail to the registry's kill-reason merge (the
+* cancel reason it forwarded is the same string); an errored run fails with
+* the script's failure message.
+*/
+function jobOutcomeOf(result, name, maxChars) {
+	switch (result.stopReason) {
+		case "completed": return {
+			status: "completed",
+			detail: `${result.agentsStarted} agent${result.agentsStarted === 1 ? "" : "s"}`,
+			result: renderResult(name, result.agentsStarted, result.value, maxChars)
+		};
+		case "cancelled": return { status: "killed" };
+		case "error": return {
+			status: "failed",
+			detail: result.error ?? "unknown error"
+		};
+		/* v8 ignore start -- defensive: WorkflowStopReason is a closed union, exhaustive by construction; a future variant fails here loudly */
+		default: return {
+			status: "failed",
+			detail: `workflow run ended abnormally (${String(result.stopReason)})`
+		};
+	}
+}
 /** Render the run's outcome text: the meta name, agent count, and the JSON value (capped). */
 function renderResult(name, agentsStarted, value, maxChars) {
 	const rendered = JSON.stringify(value, null, 2);
 	const clipped = rendered.length > maxChars ? `${rendered.slice(0, maxChars)}\n… [truncated: ${rendered.length - maxChars} more characters]` : rendered;
 	return `workflow "${name}" completed (${agentsStarted} agent${agentsStarted === 1 ? "" : "s"}).\nReturn value:\n${clipped}`;
 }
+/**
+* Register a background run as an owned job. The engine run is started
+* inside the job starter with no tool-step signal — the run belongs to the
+* job, so a registry kill or owner teardown is what cancels it — and its
+* settlement is the job's settlement: dispose, stop the mirrors, then map the
+* stop reason onto the job outcome (a completed run's rendered return value
+* rides `result` to the model's first read after settlement).
+* @param ctx - plugin context (engine, optional jobs registry, logger).
+* @param args - the validated tool call.
+* @param parent - the calling agent; owns the job.
+* @param recordsRun - whether this top-level call records durable run events.
+* @param deps - the tool's recorder/mirror taps and the render cap.
+* @returns the background result for the tool's output schema.
+*/
+function startBackgroundRun(ctx, args, parent, recordsRun, deps) {
+	const jobs = ctx.get("jobs");
+	if (jobs === void 0) throw new Error("background jobs unavailable: load @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs");
+	let run;
+	return {
+		kind: "background",
+		jobId: jobs.start({
+			kind: "workflow",
+			label: args.meta.name,
+			owner: parent.id,
+			run: (job) => {
+				run = ctx.workflowEngine.start({
+					script: args.script,
+					meta: args.meta,
+					...args.args !== void 0 ? { args: args.args } : {},
+					parent
+				});
+				deps.mirror.start(run.id, job);
+				if (recordsRun) deps.recorder.start(parent.session, run);
+				return {
+					cancel: (reason) => {
+						run.cancel(reason ?? "background workflow job killed");
+					},
+					done: run.result.then(async (result) => {
+						try {
+							await run.dispose();
+						} catch (error) {
+							ctx.logger.warn(`background workflow run ${run.id} dispose failed: ${String(error)}`);
+						}
+						deps.mirror.stop(run.id);
+						if (recordsRun) {
+							deps.recorder.finish(run.id, result.stopReason);
+							deps.recorder.abandon(run.id);
+						}
+						return jobOutcomeOf(result, args.meta.name, deps.maxResultChars);
+					})
+				};
+			}
+		}),
+		runId: run.id
+	};
+}
 function apply(ctx, config) {
-	const { toolName, maxResultChars } = config;
+	const { toolName, maxResultChars, enableRunInBackground } = config;
 	const recorder = createWorkflowRecorder(ctx);
+	const mirror = createWorkflowRecordMirror(ctx);
 	ctx.systemPrompt.section({
 		name: `tool:${toolName}`,
 		order: ctx.systemPrompt.getSectionOrder("TOOL_WORKFLOW"),
@@ -142,7 +274,7 @@ function apply(ctx, config) {
 	});
 	ctx.tools.register(defineTool({
 		name: toolName,
-		description: DESCRIPTION,
+		description: DESCRIPTION + (enableRunInBackground ? BACKGROUND_CLOSING : FOREGROUND_ONLY_CLOSING),
 		parameters: {
 			script: {
 				type: "string",
@@ -202,13 +334,40 @@ function apply(ctx, config) {
 				type: "object",
 				additionalProperties: true,
 				description: "Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]})."
-			}
+			},
+			...enableRunInBackground ? { run_in_background: {
+				type: "boolean",
+				description: "Run as a background job: return a job id immediately instead of waiting; the return value arrives with the completion notice."
+			} } : {}
 		},
 		output: {
-			schema: {
+			schema: { oneOf: [{
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					kind: {
+						type: "string",
+						required: true,
+						const: "background"
+					},
+					jobId: {
+						type: "string",
+						required: true
+					},
+					runId: {
+						type: "string",
+						required: true
+					}
+				}
+			}, {
 				type: "object",
 				additionalProperties: false,
 				properties: {
+					kind: {
+						type: "string",
+						required: true,
+						const: "foreground"
+					},
 					runId: {
 						type: "string",
 						required: true
@@ -222,15 +381,23 @@ function apply(ctx, config) {
 						required: true
 					}
 				}
-			},
+			}] },
 			render: (args, value) => [{
 				type: "text",
-				text: renderResult(args.meta.name, value.agentsStarted, value.result, maxResultChars)
+				text: value.kind === "background" ? `workflow "${args.meta.name}" started in the background as job ${value.jobId}. Its return value arrives with the completion notice; check on it with job_output, stop it with job_kill.` : renderResult(args.meta.name, value.agentsStarted, value.result, maxResultChars)
 			}]
 		},
 		async execute(args, exec) {
 			const parent = exec.agent;
 			if (!parent) throw new Error("workflow tool requires a calling agent (exec.agent was undefined)");
+			if (args.run_in_background === true) {
+				if (!enableRunInBackground) throw new Error("run_in_background is disabled for this tool");
+				return startBackgroundRun(ctx, args, parent, exec.parent === void 0, {
+					recorder,
+					mirror,
+					maxResultChars
+				});
+			}
 			const run = ctx.workflowEngine.start({
 				script: args.script,
 				meta: args.meta,
@@ -250,6 +417,7 @@ function apply(ctx, config) {
 				const error = stopReasonError(result);
 				if (error !== void 0) throw new Error(error);
 				return {
+					kind: "foreground",
 					runId: run.id,
 					agentsStarted: result.agentsStarted,
 					result: result.value

package/lib/types/index.d.ts

@@ -3,14 +3,21 @@
  * subagents, and return the script's final value. It owns the model-facing schema and run lifecycle; script
  * parsing, execution, caps, and cancellation live behind `ctx.workflowEngine`
  * (`@deepseek-ai/dsh-workflow`), so a hardened engine swaps in without touching what the model
- * sees. Execution awaits `run.result` and always disposes the run; non-completed reasons become tool
- * errors, and background collection remains deferred. Presentation is an args-only generic card
+ * sees. Foreground execution awaits `run.result` and always disposes the run; non-completed reasons
+ * become tool errors. `run_in_background: true` instead registers the run as an owned `ctx.jobs` job
+ * and returns its id immediately — the job's output ring streams live progress, and the run's value
+ * arrives with the job's completion notice. Presentation is an args-only generic card
  * titled from `meta.name`. Explicit-ask usage guidance is registered as the tool's own prompt
  * section rather than deployment persona prose.
  * @module @deepseek-ai/dsh-tool-workflow
  */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
+declare module '@deepseek-ai/dsh-jobs' {
+    interface JobKindMap {
+        workflow: 'workflow';
+    }
+}
 export declare const name = "tool-workflow";
 export declare const inject: string[];
 /** Config: the model-facing tool name plus result rendering caps. */
@@ -19,6 +26,14 @@ export interface Config {
     toolName?: string;
     /** Rendered-result ceiling, in characters: a longer JSON value is truncated with a notice (default 50000). */
     maxResultChars?: number;
+    /**
+     * Expose `run_in_background` (default true); disabled calls are also
+     * rejected. A background run needs a live `ctx.jobs` registry with a
+     * controller serving the caller (`dsh-jobs-local` plus `dsh-tool-jobs` in
+     * the shipped composition); without one the call fails with the missing
+     * piece named.
+     */
+    enableRunInBackground?: boolean;
 }
 export declare const Config: z<Config>;
 export declare function apply(ctx: Context, config: Config): void;

package/lib/types/index.js

@@ -3,19 +3,23 @@
  * subagents, and return the script's final value. It owns the model-facing schema and run lifecycle; script
  * parsing, execution, caps, and cancellation live behind `ctx.workflowEngine`
  * (`@deepseek-ai/dsh-workflow`), so a hardened engine swaps in without touching what the model
- * sees. Execution awaits `run.result` and always disposes the run; non-completed reasons become tool
- * errors, and background collection remains deferred. Presentation is an args-only generic card
+ * sees. Foreground execution awaits `run.result` and always disposes the run; non-completed reasons
+ * become tool errors. `run_in_background: true` instead registers the run as an owned `ctx.jobs` job
+ * and returns its id immediately — the job's output ring streams live progress, and the run's value
+ * arrives with the job's completion notice. Presentation is an args-only generic card
  * titled from `meta.name`. Explicit-ask usage guidance is registered as the tool's own prompt
  * section rather than deployment persona prose.
  * @module @deepseek-ai/dsh-tool-workflow
  */
 import z from '@deepseek-ai/schemastery';
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import { createWorkflowRecordMirror } from "./record.js";
 export const name = 'tool-workflow';
 export const inject = ['tools', 'workflowEngine', 'systemPrompt'];
 export const Config = z.object({
     toolName: z.string().default('workflow'),
     maxResultChars: z.natural().min(1).default(50_000),
+    enableRunInBackground: z.boolean().default(true),
 });
 /** Render a contained recording failure without trusting the thrown value. */
 function renderRecordingError(error) {
@@ -89,7 +93,8 @@ function createWorkflowRecorder(ctx) {
 /**
  * The script-authoring contract, embedded in the tool description. This IS the
  * model-facing spec: the meta block, the hooks and their exact semantics, and
- * the supported schema subset.
+ * the supported schema subset. The closing execution sentence follows the
+ * composition: only a background-enabled tool describes `run_in_background`.
  */
 const DESCRIPTION = `Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.
 
@@ -103,7 +108,9 @@ Script-body hooks:
 
 Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item \`null\`.
 
-Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.`;
+Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them.`;
+const FOREGROUND_ONLY_CLOSING = ' The run executes in the foreground: this call returns when the whole script finishes.';
+const BACKGROUND_CLOSING = ' The run executes in the foreground by default: this call returns when the whole script finishes. Set `run_in_background: true` for a long run: the call returns a job id immediately, the run keeps orchestrating in the background, and its return value arrives with the job\'s completion notice (check on it with `job_output`, stop it with `job_kill`).';
 /** The pending-state card: a generic card titled by the workflow's meta name. */
 function presentWorkflowCall(args) {
     return {
@@ -133,6 +140,31 @@ function stopReasonError(result) {
         /* v8 ignore stop */
     }
 }
+/**
+ * Map a settled background run onto the job outcome vocabulary. A completed
+ * run carries the rendered return value as the job's result; a
+ * cancelled run leaves the detail to the registry's kill-reason merge (the
+ * cancel reason it forwarded is the same string); an errored run fails with
+ * the script's failure message.
+ */
+function jobOutcomeOf(result, name, maxChars) {
+    switch (result.stopReason) {
+        case 'completed':
+            return {
+                status: 'completed',
+                detail: `${result.agentsStarted} agent${result.agentsStarted === 1 ? '' : 's'}`,
+                result: renderResult(name, result.agentsStarted, result.value, maxChars),
+            };
+        case 'cancelled':
+            return { status: 'killed' };
+        case 'error':
+            return { status: 'failed', detail: result.error ?? 'unknown error' };
+        /* v8 ignore start -- defensive: WorkflowStopReason is a closed union, exhaustive by construction; a future variant fails here loudly */
+        default:
+            return { status: 'failed', detail: `workflow run ended abnormally (${String(result.stopReason)})` };
+        /* v8 ignore stop */
+    }
+}
 /** Render the run's outcome text: the meta name, agent count, and the JSON value (capped). */
 function renderResult(name, agentsStarted, value, maxChars) {
     // The engine returns JSON data (null for a valueless script), so stringify never yields undefined.
@@ -142,11 +174,74 @@ function renderResult(name, agentsStarted, value, maxChars) {
         : rendered;
     return `workflow "${name}" completed (${agentsStarted} agent${agentsStarted === 1 ? '' : 's'}).\nReturn value:\n${clipped}`;
 }
+/**
+ * Register a background run as an owned job. The engine run is started
+ * inside the job starter with no tool-step signal — the run belongs to the
+ * job, so a registry kill or owner teardown is what cancels it — and its
+ * settlement is the job's settlement: dispose, stop the mirrors, then map the
+ * stop reason onto the job outcome (a completed run's rendered return value
+ * rides `result` to the model's first read after settlement).
+ * @param ctx - plugin context (engine, optional jobs registry, logger).
+ * @param args - the validated tool call.
+ * @param parent - the calling agent; owns the job.
+ * @param recordsRun - whether this top-level call records durable run events.
+ * @param deps - the tool's recorder/mirror taps and the render cap.
+ * @returns the background result for the tool's output schema.
+ */
+function startBackgroundRun(ctx, args, parent, recordsRun, deps) {
+    const jobs = ctx.get('jobs');
+    if (jobs === undefined) {
+        throw new Error('background jobs unavailable: load @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs');
+    }
+    let run;
+    const jobId = jobs.start({
+        kind: 'workflow',
+        label: args.meta.name,
+        owner: parent.id,
+        run: (job) => {
+            // A synchronous engine rejection (META_INVALID/SCRIPT_PARSE) propagates
+            // out of the starter, so the registry registers nothing and the model
+            // sees the violation list as an ordinary tool error.
+            run = ctx.workflowEngine.start({
+                script: args.script,
+                meta: args.meta,
+                ...args.args !== undefined ? { args: args.args } : {},
+                parent,
+            });
+            deps.mirror.start(run.id, job);
+            if (recordsRun)
+                deps.recorder.start(parent.session, run);
+            const done = run.result.then(async (result) => {
+                try {
+                    // Keep member listeners alive through disposal: an engine may
+                    // synthesize cancelled member endings while reaching quiescence.
+                    await run.dispose();
+                }
+                catch (error) {
+                    // done must not reject; a failed disposal still has a settled result to report.
+                    ctx.logger.warn(`background workflow run ${run.id} dispose failed: ${String(error)}`);
+                }
+                deps.mirror.stop(run.id);
+                if (recordsRun) {
+                    deps.recorder.finish(run.id, result.stopReason);
+                    deps.recorder.abandon(run.id);
+                }
+                return jobOutcomeOf(result, args.meta.name, deps.maxResultChars);
+            });
+            return {
+                cancel: (reason) => { run.cancel(reason ?? 'background workflow job killed'); },
+                done,
+            };
+        },
+    });
+    return { kind: 'background', jobId, runId: run.id };
+}
 export function apply(ctx, config) {
     // schemastery (the exported Config schema) has already filled the defaulted
     // fields; the assertion records that resolution, not a hidden fallback.
-    const { toolName, maxResultChars } = config;
+    const { toolName, maxResultChars, enableRunInBackground } = config;
     const recorder = createWorkflowRecorder(ctx);
+    const mirror = createWorkflowRecordMirror(ctx);
     // Usage policy ships with the tool (the master convention: tool guidance
     // lives in tool plugins as prompt sections, not in the deployment persona).
     ctx.systemPrompt.section({
@@ -156,7 +251,7 @@ export function apply(ctx, config) {
     });
     ctx.tools.register(defineTool({
         name: toolName,
-        description: DESCRIPTION,
+        description: DESCRIPTION + (enableRunInBackground ? BACKGROUND_CLOSING : FOREGROUND_ONLY_CLOSING),
         parameters: {
             script: {
                 type: 'string',
@@ -193,20 +288,42 @@ export function apply(ctx, config) {
                 additionalProperties: true,
                 description: 'Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {"files": [...]}).',
             },
+            ...enableRunInBackground ? {
+                run_in_background: {
+                    type: 'boolean',
+                    description: 'Run as a background job: return a job id immediately instead of waiting; the return value arrives with the completion notice.',
+                },
+            } : {},
         },
         output: {
             schema: {
-                type: 'object',
-                additionalProperties: false,
-                properties: {
-                    runId: { type: 'string', required: true },
-                    agentsStarted: { type: 'integer', required: true },
-                    result: { type: 'json', required: true },
-                },
+                oneOf: [
+                    {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            kind: { type: 'string', required: true, const: 'background' },
+                            jobId: { type: 'string', required: true },
+                            runId: { type: 'string', required: true },
+                        },
+                    },
+                    {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            kind: { type: 'string', required: true, const: 'foreground' },
+                            runId: { type: 'string', required: true },
+                            agentsStarted: { type: 'integer', required: true },
+                            result: { type: 'json', required: true },
+                        },
+                    },
+                ],
             },
             render: (args, value) => [{
                     type: 'text',
-                    text: renderResult(args.meta.name, value.agentsStarted, value.result, maxResultChars),
+                    text: value.kind === 'background'
+                        ? `workflow "${args.meta.name}" started in the background as job ${value.jobId}. Its return value arrives with the completion notice; check on it with job_output, stop it with job_kill.`
+                        : renderResult(args.meta.name, value.agentsStarted, value.result, maxResultChars),
                 }],
         },
         async execute(args, exec) {
@@ -217,6 +334,21 @@ export function apply(ctx, config) {
                 // parent to attribute the children to. Fail loud rather than guess.
                 throw new Error('workflow tool requires a calling agent (exec.agent was undefined)');
             }
+            if (args.run_in_background === true) {
+                if (!enableRunInBackground) {
+                    throw new Error('run_in_background is disabled for this tool');
+                }
+                // No pre-abort check here, unlike bash/pwsh: ToolRuntime re-reads the
+                // caller signal right before execute(), and this branch reaches
+                // jobs.start synchronously from there. The shell tools await a
+                // sandbox escalation approval before registering, which is the window
+                // their check covers.
+                return startBackgroundRun(ctx, args, parent, exec.parent === undefined, {
+                    recorder,
+                    mirror,
+                    maxResultChars,
+                });
+            }
             // Meta/body validation failures (META_INVALID/SCRIPT_PARSE) throw
             // synchronously here and become isError results via the registry — the
             // model sees the violation list and can correct the call.
@@ -246,6 +378,7 @@ export function apply(ctx, config) {
                     throw new Error(error);
                 }
                 return {
+                    kind: 'foreground',
                     runId: run.id,
                     agentsStarted: result.agentsStarted,
                     result: result.value,

package/lib/types/record.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Live-progress mirror for background workflow runs: streams the engine's
+ * `workflow/phase`, `workflow/log`, and member lifecycle events into the
+ * owning job's output ring as `log` chunks — observer-only narration the
+ * model's `job_output` never renders — and keeps the job's live progress
+ * line on the current phase. Appends against a settled job log and drop
+ * inside the registry, so a straggling event after settlement is harmless.
+ * @module @deepseek-ai/dsh-tool-workflow/record
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { JobHandle } from '@deepseek-ai/dsh-jobs';
+import type { WorkflowRunId } from '@deepseek-ai/dsh-workflow';
+/** Job-ring taps for the background runs the tool tracks. */
+export interface WorkflowRecordMirror {
+    /**
+     * Route a run's progress events into a job's ring. Call once per background
+     * run, from the job starter, before the worker publishes its first event.
+     * @param runId - the started run.
+     * @param job - the owning job's producer face.
+     */
+    start(runId: WorkflowRunId, job: JobHandle): void;
+    /**
+     * Stop routing a settled or abandoned run. Idempotent.
+     * @param runId - the run to drop.
+     */
+    stop(runId: WorkflowRunId): void;
+}
+/**
+ * Create the run-to-ring mirror and subscribe the engine's live progress
+ * events for the runs it tracks.
+ * @param ctx - plugin context whose event bus carries the `workflow/*` events.
+ * @returns the mirror taps the tool wires around each background run.
+ */
+export declare function createWorkflowRecordMirror(ctx: Context): WorkflowRecordMirror;
+//# sourceMappingURL=record.d.ts.map

package/lib/types/record.js

@@ -0,0 +1,43 @@
+/**
+ * Live-progress mirror for background workflow runs: streams the engine's
+ * `workflow/phase`, `workflow/log`, and member lifecycle events into the
+ * owning job's output ring as `log` chunks — observer-only narration the
+ * model's `job_output` never renders — and keeps the job's live progress
+ * line on the current phase. Appends against a settled job log and drop
+ * inside the registry, so a straggling event after settlement is harmless.
+ * @module @deepseek-ai/dsh-tool-workflow/record
+ */
+/**
+ * Create the run-to-ring mirror and subscribe the engine's live progress
+ * events for the runs it tracks.
+ * @param ctx - plugin context whose event bus carries the `workflow/*` events.
+ * @returns the mirror taps the tool wires around each background run.
+ */
+export function createWorkflowRecordMirror(ctx) {
+    const active = new Map();
+    ctx.on('workflow/phase', (info, title) => {
+        const job = active.get(info.id);
+        if (job === undefined)
+            return;
+        job.updateProgress(title);
+        job.append(`▸ ${title}\n`, { channel: 'log' });
+    });
+    ctx.on('workflow/log', (info, message) => {
+        active.get(info.id)?.append(`${message}\n`, { channel: 'log' });
+    });
+    ctx.on('workflow/agent-start', (info, agent) => {
+        active.get(info.id)?.append(`agent #${agent.seq} ${agent.label} started\n`, { channel: 'log' });
+    });
+    ctx.on('workflow/agent-end', (info, agent) => {
+        active.get(info.id)?.append(`agent #${agent.seq} ${agent.outcome}\n`, { channel: 'log' });
+    });
+    return {
+        start(runId, job) {
+            active.set(runId, job);
+        },
+        stop(runId) {
+            active.delete(runId);
+        },
+    };
+}
+//# sourceMappingURL=record.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-workflow",
   "description": "Model-facing workflow tool: run a JavaScript orchestration script over ctx.workflowEngine",
-  "version": "0.1.6-alpha.2",
+  "version": "0.1.7-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -37,29 +37,34 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-tools": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-workflow": "^0.1.6-alpha.2",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/dsh-jobs": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-llm": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-session": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-invariants": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "0.1.7-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-tools": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-workflow": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-agent": "0.1.7-alpha.2"
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.2"
+    "@deepseek-ai/schemastery": "~3.18.4"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-subagent": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-tools": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-workflow-ptc": "^0.1.6-alpha.2",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-session-projection": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-workflow": "^0.1.6-alpha.2"
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-agent": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-agent-loop-testkit": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-invariants": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-jobs": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-jobs-local": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-llm": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-session": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-subagent": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-tool-jobs": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-tools": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-workflow-ptc": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-workflow": "0.1.7-alpha.2"
   }
 }