@deepseek-ai/dsh-tool-pwsh 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/shell/tool-pwsh/README.md
-README.md: a1b8755c50862bb318f72af90f3cdbae158e7746
-README.zh.md: efcf188b31365f6897eb14fb6482c973f23f6a7b
+README.md: 26bf4e30eb03a6e1d36afa2a7c1ccd60a1673ac2
+README.zh.md: fbf9fc61ba09ba2bc88daebffe46c52a64877208

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-tool-pwsh` gives the agent a `pwsh` tool that runs PowerShell commands through the mounted shell executor — the Windows counterpart of `dsh-tool-bash`, mirroring it call-for-call. Each call runs in a fresh pwsh process, so no state survives; `run_in_background` turns long-running commands into background jobs. Commands are PowerShell-dialect: native `C:\...` paths and `$env:NAME` variables, with no dialect translation. Every call runs with the managed `DSH_*` environment, and under a sandboxing executor the tool teaches and enforces the Windows-specific language-mode and named-pipe contracts. Mount it with a PowerShell executor such as `dsh-pwsh-local` and the `dsh-shell-env` plugin.
+`dsh-tool-pwsh` lets the agent run PowerShell commands through a mounted shell executor. Each call uses a fresh process; with a job registry composed every command is a job from the moment it starts, so `run_in_background` returns the id at once and a foreground command that outlives its timeout returns the same id, with observable output. Commands use native Windows paths and `$env:NAME` variables without dialect translation. Calls receive the managed `DSH_*` environment, and sandboxed execution enforces Windows language-mode and named-pipe requirements. Mount it with a PowerShell executor such as `dsh-pwsh-local` and the `dsh-shell-env` plugin.
 
 ## Table of Contents
 
@@ -41,11 +41,12 @@ The common path is a PowerShell executor provider, the environment registry, and
 - name: '@deepseek-ai/dsh-tool-pwsh'
 ```
 
-The single config field toggles background support.
+The config fields govern the background surface.
 
 | Field | Default | Meaning |
 |---|---|---|
-| `enableRunInBackground` | `true` | Expose `run_in_background`; when `false`, forced background calls are rejected |
+| `enableRunInBackground` | `true` | Expose `run_in_background` while a job registry is composed; when `false`, forced background calls are rejected |
+| `promoteOnTimeout` | `true` | Keep a foreground command that reaches its timeout running as its background job instead of killing it |
 
 The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-tool-pwsh) is the exhaustive source for every accepted field and its JSDoc; the generated [tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-pwsh) carries the full argument schema.
 
@@ -53,6 +54,10 @@ The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-a
 
 The tool executes `pwsh -Command <command>` and returns the combined output. Commands run in a fresh pwsh process every call, so state never persists — pass `workdir` instead of `cd`. Paths use native Windows form and environment variables are read with `$env:NAME`. A non-zero exit is reported as `[exit code: N]`; on Windows a force-killed command settles as `[exit code: 1]` without a signal marker, so the agent treats a bare exit 1 after an interruption as a termination, not a command failure. Background runs, output truncation, and the `description`/`timeoutMs`/`workdir` arguments behave exactly as in [`dsh-tool-bash`](../tool-bash/README.md#running-long-commands-in-the-background), including job-owned cancellation during asynchronous shell preparation.
 
+### Foreground commands as jobs
+
+With a job registry composed, a foreground command is registered with `ctx.jobs` at its start and the call waits on that job: the command is listed, streams through `job.list` and `job.follow`, and can be stopped from the Web task list for as long as it runs. A command that finishes within the timeout returns the ordinary foreground result and its job record leaves the registry with it, so the model never sees an id. A command that outlives the timeout keeps running as the job it already was, and the call returns `[still running after <timeoutMs>ms; moved to background job <id>]` plus the job hand-off guidance, seeded with one consuming read of the output so far — `job_output` continues exactly after it. A kill from outside the call (the human stopping the job) settles the foreground result with `[stopped: <reason>]` ahead of the exit marker, so the model reads the reason instead of a command failure; cancelling the call itself kills the job. Registration is best-effort: `promoteOnTimeout: false`, a missing job registry, or a registry that refuses the job at its start (the owner's job limit, no controller) run the command under the executor's deadline kill instead, and the tool description advertises the hand-over only when it holds.
+
 ### Windows-specific sandbox behavior
 
 Under a sandboxing executor, denied commands report `[sandbox: file access denied under <mode> mode]`, and the same one-shot escalation path applies: retry the exact command once with `sandbox_permissions` plus a `justification` through user approval. The tool also teaches two Windows-restricted-token contracts in its description: read-only pwsh runs in ConstrainedLanguage (`.NET` static calls, `Add-Type`, COM, and reflection fail with "only core types" errors), and in both confined modes programs cannot open named pipes, so a command that captures another program's output through piped stdio fails with EPERM — escalate the exact command once or restructure it to avoid capturing output.
@@ -83,7 +88,7 @@ This section explains the design decisions behind the tool and points at the cod
 | File | Role |
 |---|---|
 | [`src/index.ts`](src/index.ts) | Plugin entry: tool registration, prompt section, arg validation, escalation, request assembly |
-| [`src/background.ts`](src/background.ts) | Map a settled background process onto generic job outcome vocabulary |
+| [`src/background.ts`](src/background.ts) | Map a settled process onto generic job outcome vocabulary and render a ring read as a process read |
 | [`src/render.ts`](src/render.ts) | Model-facing result text: streams, markers, truncation notices (bash twin) |
 | — | No runtime invariant companion is published; this package exposes no independent event sequence or mutable data relation beyond contracts enforced at its owning seam. |
 
@@ -152,7 +157,7 @@ Prefix-stable while visibility and the tool definition are unchanged. A restrict
 
 #### What the model sees
 
-The renderer emits the data-dependent stdout tail, then optional `[stderr]` and the stderr tail. Conditional lines are exactly `[output truncated; full output: <path-or-(unavailable)>]`, `[sandbox: file access denied under <mode> mode]` plus the escalation hint `[sandbox: escalation available — …]` (only when the composition advertises escalation), `[timed out after <timeoutMs>ms]`, `[killed by signal: <signal>]`, and `[exit code: <exitCode>]` (nonzero exits only); an empty body renders as `(no output)`.
+The renderer emits the data-dependent stdout tail, then optional `[stderr]` and the stderr tail. Conditional lines are exactly `[output truncated; full output: <path-or-(unavailable)>]`, `[sandbox: file access denied under <mode> mode]` plus the escalation hint `[sandbox: escalation available — …]` (only when the composition advertises escalation), `[timed out after <timeoutMs>ms]`, `[stopped: <reason>]`, `[killed by signal: <signal>]`, and `[exit code: <exitCode>]` (nonzero exits only); an empty body renders as `(no output)`.
 
 #### Token effect
 

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-tool-pwsh` 为 agent（智能体）提供 `pwsh` 工具，通过已挂载的 shell 执行器运行 PowerShell 命令——它是 `dsh-tool-bash` 的 Windows 对应物，逐调用镜像。每次调用都运行在全新 pwsh 进程中，因此状态不会保留；`run_in_background` 把长时间运行的命令变成后台任务。命令是 PowerShell 方言：原生 `C:\...` 路径与 `$env:NAME` 变量，不做方言翻译。每次调用都运行在受管 `DSH_*` 环境中；在沙箱执行器下，工具会向模型说明并强制执行 Windows 特有的语言模式与命名管道约定。请与 `dsh-pwsh-local` 等 PowerShell 执行器以及 `dsh-shell-env` 插件一起挂载。
+`dsh-tool-pwsh` 让 agent（智能体）通过已挂载的 shell 执行器运行 PowerShell 命令。每次调用使用全新进程；组合中有 job 注册表时，每条命令从启动那一刻起就是一个任务，因此 `run_in_background` 立即返回 id，超过超时仍在运行的前台命令返回同一个 id，输出可观测。命令使用原生 Windows 路径和 `$env:NAME` 变量，不做方言翻译。调用获得受管 `DSH_*` 环境，沙箱执行会落实 Windows 语言模式与命名管道要求。请与 `dsh-pwsh-local` 等 PowerShell 执行器及 `dsh-shell-env` 插件一起挂载。
 
 ## 目录
 
@@ -41,11 +41,12 @@ kind: "package-reference"
 - name: '@deepseek-ai/dsh-tool-pwsh'
 ```
 
-唯一的配置字段用于开关后台支持。
+配置字段决定后台能力面。
 
 | 字段 | 默认值 | 含义 |
 |---|---|---|
-| `enableRunInBackground` | `true` | 暴露 `run_in_background`；为 `false` 时拒绝强制后台调用 |
+| `enableRunInBackground` | `true` | 组合中有 job 注册表时暴露 `run_in_background`；为 `false` 时拒绝强制后台调用 |
+| `promoteOnTimeout` | `true` | 到达超时的前台命令继续作为它的后台任务运行，而不是杀掉它 |
 
 生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-tool-pwsh)是每个受支持字段及其 JSDoc 的穷尽式真源；生成的[工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-pwsh)携带完整参数 schema。
 
@@ -53,6 +54,10 @@ kind: "package-reference"
 
 工具执行 `pwsh -Command <command>` 并返回合并后的输出。命令每次调用都运行在全新 pwsh 进程中，因此状态从不保留——请传 `workdir` 而不是 `cd`。路径使用原生 Windows 形式，环境变量用 `$env:NAME` 读取。非零退出以 `[exit code: N]` 报告；在 Windows 上，强制终止的命令以 `[exit code: 1]` 结算且没有信号标记，因此 agent 把中断后的裸 exit 1 当作终止而非命令失败。后台运行、输出截断以及 `description`／`timeoutMs`／`workdir` 参数的行为与 [`dsh-tool-bash`](../tool-bash/README.zh.md#running-long-commands-in-the-background) 完全一致，包括异步 shell 准备过程中由任务负责的取消。
 
+### 前台命令即任务
+
+组合中有 job 注册表时，前台命令一启动就登记到 `ctx.jobs`，调用等待该任务：命令在运行期间始终被列出、经 `job.list` 与 `job.follow` 流式观看，并可从 Web 任务列表停止。在超时内完成的命令返回普通前台结果，其任务记录随结果一起离开注册表，模型从不看到 id。超过超时仍在运行的命令继续作为它本来就是的那个任务运行，调用返回 `[still running after <timeoutMs>ms; moved to background job <id>]` 加任务交接指引，并以一次消费式读取带上目前为止的输出——`job_output` 恰好从此处接续。来自调用之外的杀停（人在界面上停止任务）会让前台结果在退出标记之前带上 `[stopped: <reason>]`，模型读到的是原因而不是命令失败；取消调用本身则杀掉任务。登记是尽力而为的：`promoteOnTimeout: false`、缺少 job 注册表，或注册表在启动时拒绝该任务（持有者的任务上限、没有控制器）都会改为在执行器的 deadline 杀下运行命令，工具描述也只在交接语义成立时才宣传它。
+
 ### Windows 特有的沙箱行为
 
 在沙箱执行器下，被拒绝的命令会报告 `[sandbox: file access denied under <mode> mode]`，并适用相同的单次升权路径：用 `sandbox_permissions` 加一句 `justification`，经用户审批后重试完全相同的命令一次。工具还会在其描述中教授两条 Windows 受限令牌约定：只读 pwsh 运行在 ConstrainedLanguage 中（`.NET` 静态调用、`Add-Type`、COM 与反射会以 "only core types" 错误失败）；两种受限模式下程序都无法打开命名管道，因此通过管道 stdio 捕获另一程序输出的命令会以 EPERM 失败——请升权该确切命令一次，或重构命令以避免捕获输出。
@@ -83,7 +88,7 @@ kind: "package-reference"
 | 文件 | 职责 |
 |---|---|
 | [`src/index.ts`](src/index.ts) | 插件入口：工具注册、提示词区段、参数校验、升权、请求组装 |
-| [`src/background.ts`](src/background.ts) | 把已结算的后台进程映射为通用任务结果词汇 |
+| [`src/background.ts`](src/background.ts) | 把已结算的进程映射为通用任务结果词汇，并把输出环读取渲染为进程读取 |
 | [`src/render.ts`](src/render.ts) | 模型侧结果文本：流、标记、截断通知（bash 孪生） |
 | — | 不发布运行时不变式伴生入口；除所属 seam 强制执行的约定外，本包不公开独立的事件序列或可变数据关系。 |
 
@@ -152,7 +157,7 @@ Non-zero exits are reported as `[exit code: N]` markers; investigate failures be
 
 #### 模型看到什么
 
-渲染器输出依数据而定的 stdout 尾部，再输出可选的 `[stderr]` 和 stderr 尾部。条件行精确为 `[output truncated; full output: <path-or-(unavailable)>]`、`[sandbox: file access denied under <mode> mode]` 加升权提示 `[sandbox: escalation available — …]`（仅在组合声明升权时）、`[timed out after <timeoutMs>ms]`、`[killed by signal: <signal>]` 与 `[exit code: <exitCode>]`（仅非零退出）；空正文渲染为 `(no output)`。
+渲染器输出依数据而定的 stdout 尾部，再输出可选的 `[stderr]` 和 stderr 尾部。条件行精确为 `[output truncated; full output: <path-or-(unavailable)>]`、`[sandbox: file access denied under <mode> mode]` 加升权提示 `[sandbox: escalation available — …]`（仅在组合声明升权时）、`[timed out after <timeoutMs>ms]`、`[stopped: <reason>]`、`[killed by signal: <signal>]` 与 `[exit code: <exitCode>]`（仅非零退出）；空正文渲染为 `(no output)`。
 
 #### Token 影响
 

package/lib/index.js

@@ -6,36 +6,98 @@ import { ESCALATION_TARGETS, approveEscalation, escalationHintMarker, sandboxDen
 import { parseExitStatus } from "@deepseek-ai/dsh-shell";
 //#region lib/types/background.js
 /**
-* Generic-task adaptation for background pwsh process handles — the shell-agnostic
-* twin of `dsh-tool-bash`'s background adaptation.
+* Generic-job adaptation for pwsh process handles — the shell-agnostic twin
+* of `dsh-tool-bash`'s background adaptation: the terminal
+* outcome the registry records and the pull sources it pumps.
 *
 * @module @deepseek-ai/dsh-tool-pwsh/background
 */
 /**
-* Map a settled background process onto the generic task-outcome vocabulary:
+* Sandbox facts worth the terminal detail: a runner that never ran the
+* command, or a denial (with the escalation hint this composition offers).
+* @param sandbox - settled sandbox facts, when this was a confined process.
+* @param escalationModes - escalation targets advertised by this composition.
+* @returns the markers to append, oldest first.
+*/
+function sandboxNotes(sandbox, escalationModes) {
+	if (sandbox?.runnerFailed) return [`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`];
+	if (sandbox?.denied) {
+		const notes = [sandboxDenialMarker(sandbox.mode)];
+		if (escalationModes.length > 0) notes.push(escalationHintMarker("command"));
+		return notes;
+	}
+	return [];
+}
+/**
+* Map a settled background process onto the generic job-outcome vocabulary:
 * `killed` stays `killed` (detail: the signal when one is known), everything
 * else is `completed` with the exit code as detail. A nonzero command exit is
-* reported, not failed, exactly like the foreground rendering.
+* reported, not failed, exactly like the foreground rendering. Sandbox facts
+* join the detail, since a job's terminal reason is the one line every
+* reader — the model's status line, the roster row — shows.
 * @param proc - the settled process handle.
+* @param escalationModes - escalation targets advertised by this composition.
 * @returns the outcome for the `ctx.jobs` registration.
 */
-function processOutcome(proc) {
-	if (proc.status === "killed") return {
+function processOutcome(proc, escalationModes = []) {
+	const base = proc.status === "killed" ? {
 		status: "killed",
 		detail: proc.signal !== null ? `signal: ${proc.signal}` : "killed before exit"
-	};
-	return {
+	} : {
 		status: "completed",
 		detail: `exit code: ${proc.exitCode ?? 0}`
 	};
+	const notes = sandboxNotes(proc.sandbox, escalationModes);
+	return notes.length === 0 ? base : {
+		...base,
+		detail: `${base.detail}; ${notes.join(" ")}`
+	};
+}
+/**
+* The process's non-consuming stream readers as registry pull sources. They
+* bind lazily because the process is spawned inside the starter, after the
+* registry admitted the job; a read before the spawn yields nothing, and the
+* pump keeps the model's consuming cursor untouched. A rejected spawn's
+* stderr reader carries the provider's `subprocess failed before reporting an
+* outcome: …` note.
+* @param proc - the started process's observed streams, once the starter has spawned it.
+* @returns one source per stream, stdout first.
+*/
+function processSources(proc) {
+	const source = (channel) => ({
+		channel,
+		read: (fromByte) => {
+			const live = proc();
+			return live === void 0 ? {
+				text: "",
+				nextOffset: fromByte,
+				lossy: false
+			} : live.observed[channel].readFrom(fromByte);
+		}
+	});
+	return [source("stdout"), source("stderr")];
+}
+/**
+* The ring chunks of one consuming registry read as the shell tools render a
+* process read: stdout chunks in order, then every stderr chunk in one
+* `[stderr]` section, so the output a foreground call hands over when it
+* stops waiting reads exactly like the `job_output` reads that follow it.
+* @param chunks - the chunks since the model cursor, in offset order.
+* @returns the delta text, possibly empty.
+*/
+function ringDelta(chunks) {
+	const out = chunks.filter((chunk) => chunk.channel !== "stderr").map((chunk) => chunk.text).join("");
+	const err = chunks.filter((chunk) => chunk.channel === "stderr").map((chunk) => chunk.text).join("");
+	const separator = out.length > 0 && !out.endsWith("\n") ? "\n" : "";
+	return out + (err.length > 0 ? `${separator}[stderr]\n${err}` : "");
 }
 /**
 * Adapt asynchronous shell preparation after job admission without exposing a partial process.
 * @param start - starts the process with job-owned cancellation.
-* @param renderOutput - consumes output from a published process.
+* @param outcome - projects the settled process into the job outcome.
 * @returns synchronous job hooks whose completion includes preparation and process settlement.
 */
-function processJob(start, renderOutput) {
+function processJob(start, outcome) {
 	const controller = new AbortController();
 	let process;
 	return {
@@ -52,15 +114,14 @@ function processJob(start, renderOutput) {
 				} finally {
 					await process.done;
 				}
-				return processOutcome(process);
+				return outcome(process);
 			} catch (error) {
 				return {
 					status: controller.signal.aborted && process === void 0 ? "killed" : "failed",
 					detail: error instanceof Error ? error.message : String(error)
 				};
 			}
-		})(),
-		readOutput: () => process === void 0 ? "" : renderOutput(process)
+		})()
 	};
 }
 //#endregion
@@ -106,6 +167,7 @@ function renderPwshResult(result, escalationModes = []) {
 		if (escalationModes.length > 0) markers.push(escalationHintMarker("command"));
 	}
 	if (result.timedOut) markers.push(`[timed out after ${result.timeoutMs}ms]`);
+	if (result.stopped !== void 0) markers.push(`[stopped: ${result.stopped}]`);
 	if (result.signal !== null) markers.push(`[killed by signal: ${result.signal}]`);
 	else if (result.exitCode !== 0) markers.push(`[exit code: ${result.exitCode}]`);
 	if (markers.length === 0) return body;
@@ -113,27 +175,40 @@ function renderPwshResult(result, escalationModes = []) {
 	return body + markers.join("\n");
 }
 /**
-* Shape one background-process read into the `job_output` delta the model
-* sees: the incremental delta, plus the lossy-read notice (with full-stream
-* spill paths) when in-memory truncation dropped unread bytes.
-* @param read - one incremental read from the process handle.
+* Shape a foreground call that stopped waiting into the text the model sees:
+* the output captured so far (one consuming registry read taken at that
+* point, so `job_output` continues exactly after it), then the still-running
+* marker and the job hand-off guidance.
+* @param promoted - the promoted result value: the job id, the wait that
+*   expired, and the output so far.
+* @returns the model-facing text for a promoted call.
+*/
+function renderPwshPromoted(promoted) {
+	return `${promoted.output.length > 0 ? promoted.output.endsWith("\n") ? promoted.output : `${promoted.output}\n` : ""}[still running after ${promoted.timeoutMs}ms; moved to background job ${promoted.jobId}]\nThe command keeps running in the background. You will be notified when it finishes; read newer output with job_output, stop it with job_kill.`;
+}
+/**
+* Shape the one consuming registry read a foreground call embeds in its
+* result when it stops waiting: the output produced so far, plus the
+* dropped-output notice (naming the job's spill files) when the model cursor
+* fell behind the ring, and the sandbox notices. Later `job_output` reads
+* render the same ring through the job tools.
+* @param delta - the read's chunks as rendered text.
+* @param lossy - whether bytes before the delta were evicted unread.
+* @param spillPaths - the complete-stream files the job currently advertises.
 * @param sandbox - settled sandbox facts, when this was a confined process.
 * @param escalationModes - escalation targets advertised by this composition.
 * @returns the delta text with any loss or sandbox notice appended.
 */
-function renderPwshProcessRead(read, sandbox, escalationModes = []) {
+function renderPwshJobRead(delta, lossy, spillPaths, sandbox, escalationModes = []) {
 	const notices = [];
-	if (read.lossy) {
-		const paths = [read.stdoutSpillPath, read.stderrSpillPath].filter((path) => path !== void 0);
-		notices.push(`[some output was dropped from memory; full output: ${paths.length > 0 ? paths.join(", ") : "(unavailable)"}]`);
-	}
+	if (lossy) notices.push(`[some output was dropped from memory; full output: ${spillPaths.length > 0 ? spillPaths.join(", ") : "(unavailable)"}]`);
 	if (sandbox?.runnerFailed) notices.push(`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`);
 	else if (sandbox?.denied) {
 		notices.push(sandboxDenialMarker(sandbox.mode));
 		if (escalationModes.length > 0) notices.push(escalationHintMarker("command"));
 	}
-	if (notices.length === 0) return read.delta;
-	return `${read.delta}${read.delta.length > 0 && !read.delta.endsWith("\n") ? "\n" : ""}${notices.join("\n")}`;
+	if (notices.length === 0) return delta;
+	return `${delta}${delta.length > 0 && !delta.endsWith("\n") ? "\n" : ""}${notices.join("\n")}`;
 }
 //#endregion
 //#region lib/types/index.js
@@ -144,8 +219,9 @@ function renderPwshProcessRead(read, sandbox, escalationModes = []) {
 * PowerShell-dialect: native `C:\...` paths and `$env:NAME` variables.
 *
 * Behavior mirrors `dsh-tool-bash` call-for-call: foreground and
-* `run_in_background` execution (background handles register with the
-* generic `ctx.jobs` runtime), the managed `DSH_*` environment through the
+* `run_in_background` execution (with a job registry composed, every call
+* registers its process with `ctx.jobs` as it starts, and a foreground call
+* waits on its job until the timeout passes), the managed `DSH_*` environment through the
 * shared `shell-env` registry, the per-call sandbox policy resolution (the
 * calling session's mode and cwd travel to the confining executor), the
 * sandbox-denial rendering with the same-turn escalation surface
@@ -165,15 +241,18 @@ const inject = [
 	"shellEnv"
 ];
 /** Runtime configuration schema for the pwsh tool plugin. */
-const Config = z.object({ enableRunInBackground: z.boolean().default(true) });
+const Config = z.object({
+	enableRunInBackground: z.boolean().default(true),
+	promoteOnTimeout: z.boolean().default(true)
+});
 function validatePwshArgs(args) {
 	if (args.command.trim().length === 0) throw new Error("invalid command: expected a non-empty string");
 	if (args.description.trim().length === 0) throw new Error("invalid description: expected a non-empty string");
 	if (args.timeoutMs !== void 0 && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) throw new Error(`invalid timeoutMs: expected a positive number, got ${JSON.stringify(args.timeoutMs)}`);
 	validateEscalationArgs(args.sandbox_permissions, args.justification);
 }
-function pwshDescription(backgroundEnabled, escalationModes) {
-	const base = "Execute a PowerShell command (`pwsh -Command`) and return its stdout/stderr. Each call runs in a fresh pwsh process: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Paths use native Windows form (`C:\\...`); read environment variables with `$env:NAME`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$env:DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. On Windows a force-killed command settles as `[exit code: 1]` without a signal marker — treat it as an interruption, not a command failure. " + (backgroundEnabled ? "Set `run_in_background: true` for long-running commands: the call returns a job id immediately; read its output with `job_output` and stop it with `job_kill`." : "Background execution is not available; long-running commands must finish within the timeout.");
+function pwshDescription(backgroundEnabled, escalationModes, promoteOnTimeout) {
+	const base = "Execute a PowerShell command (`pwsh -Command`) and return its stdout/stderr. Each call runs in a fresh pwsh process: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Paths use native Windows form (`C:\\...`); read environment variables with `$env:NAME`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$env:DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. On Windows a force-killed command settles as `[exit code: 1]` without a signal marker — treat it as an interruption, not a command failure. " + (backgroundEnabled ? "Set `run_in_background: true` for long-running commands: the call returns a job id immediately; read its output with `job_output` and stop it with `job_kill`." + (promoteOnTimeout ? " A foreground command that reaches its timeout is not killed: it moves to the background the same way, returning its job id and the output so far." : "") : "Background execution is not available; long-running commands must finish within the timeout.");
 	if (escalationModes.length === 0) return base;
 	return base + " Under the Windows sandbox, read-only pwsh runs in PowerShell ConstrainedLanguage mode, while workspace-write stays in FullLanguage unless host policy says otherwise. In read-only, prefer cmdlets and core types (`[string]`, `[datetime]`, `[regex]`, `[guid]`); .NET static calls (`[System.IO.*]::`, `[math]::`), `Add-Type`, COM objects, and reflection fail with \"only core types\" errors. `-f` formatting, property access, and core cmdlets work. In both confined modes, programs cannot open named pipes, so a command that captures another program's output through piped stdio (Node.js `child_process.spawn`/`exec` with the default `stdio: 'pipe'`) fails with EPERM, while `stdio: 'inherit'` and `stdio: 'ignore'` spawns work and PowerShell's own pipelines are unaffected. That EPERM is the documented boundary: do not retry the command another way — escalate the exact command once or restructure it to avoid capturing output. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.";
 }
@@ -211,6 +290,12 @@ function canonicalPwshResult(result) {
 		} } : {}
 	};
 }
+/** The structured abort the foreground paths throw when the caller cancels the call. */
+function toolAborted() {
+	const error = new HarnessError("tool call aborted", TOOL_ABORTED);
+	error.name = "AbortError";
+	return error;
+}
 /** Canonical background-handle properties shared by the pwsh output union. */
 const BACKGROUND_OUTPUT_PROPERTIES = {
 	kind: {
@@ -225,6 +310,7 @@ const BACKGROUND_OUTPUT_PROPERTIES = {
 };
 function apply(ctx, config = {}) {
 	const backgroundEnabled = config.enableRunInBackground ?? true;
+	const promoteOnTimeout = (config.promoteOnTimeout ?? true) && backgroundEnabled;
 	const defaultMode = ctx.shell.sandboxMode;
 	const escalationModes = defaultMode === void 0 ? [] : ESCALATION_TARGETS;
 	const sandboxPolicy = defaultMode === void 0 ? void 0 : ctx.get("sandboxPolicy");
@@ -264,219 +350,366 @@ function apply(ctx, config = {}) {
 		order: ctx.systemPrompt.getSectionOrder("TOOL_PWSH"),
 		text: "Non-zero exits are reported as `[exit code: N]` markers; investigate failures before moving on. On Windows a killed process settles as `[exit code: 1]` without a signal marker; treat a bare exit 1 after an interruption as a termination, not a command failure."
 	});
-	ctx.tools.register(defineTool({
-		name: "pwsh",
-		description: pwshDescription(backgroundEnabled, escalationModes),
-		parameters: {
-			command: {
-				type: "string",
-				required: true,
-				description: "The PowerShell command to execute."
-			},
-			description: {
-				type: "string",
-				required: true,
-				description: "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"Get-Process\" → \"List running processes\"."
-			},
-			timeoutMs: {
-				type: "number",
-				description: "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."
-			},
-			workdir: {
-				type: "string",
-				description: "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."
-			},
-			...backgroundEnabled ? { run_in_background: {
-				type: "boolean",
-				description: "Run in the background and return a job id immediately (collect with job_output, stop with job_kill). No timeout applies."
-			} } : {},
-			...escalationModes.length > 0 ? {
-				sandbox_permissions: {
+	/**
+	* One registration of the `pwsh` tool. With a registry, every call
+	* registers its process as a job at its start; without one the tool is
+	* foreground-only and the executor's deadline kills the command.
+	*/
+	const pwshTool = (jobs) => {
+		const background = jobs !== void 0;
+		const promote = background && promoteOnTimeout;
+		/** Register the command as a job; the process spawns inside the starter, after admission. */
+		const startJob = (registry, args, exec, spec) => {
+			let proc;
+			let stopped;
+			return {
+				id: registry.start({
+					kind: "pwsh",
+					label: args.command,
+					...exec.agent ? { owner: exec.agent.id } : {},
+					output: processSources(() => proc),
+					run: () => {
+						const hooks = processJob(async (signal) => {
+							proc = await ctx.shell.execute({
+								...spec,
+								signal
+							});
+							return proc;
+						}, (started) => processOutcome(started, escalationModes));
+						return {
+							done: hooks.done,
+							cancel: (reason) => {
+								stopped = reason;
+								hooks.cancel(reason);
+							}
+						};
+					}
+				}),
+				process: () => proc,
+				stopped: () => stopped
+			};
+		};
+		/** Wait on a registered foreground command until it settles or the timeout passes. */
+		const waitOnJob = async (registry, attached, exec, spec) => {
+			const owner = exec.agent?.id;
+			const timeoutMs = spec.timeoutMs;
+			/**
+			* Stop the job on this call's own account and stay on it until it
+			* settles, so the settlement is `awaited` and no completion notice
+			* follows a result this call already carries; the record then leaves
+			* with the call, as the model never saw the id.
+			*/
+			const stop = async (reason) => {
+				registry.kill(attached.id, owner, reason);
+				const settled = await registry.wait(attached.id, timeoutMs, owner);
+				if (settled.status !== "running" && settled.status !== "stopping") registry.remove(attached.id, owner);
+				return settled;
+			};
+			let view;
+			try {
+				view = await registry.wait(attached.id, timeoutMs, owner, exec.signal);
+			} catch {
+				await stop("tool call aborted");
+				throw toolAborted();
+			}
+			if ((view.status === "running" || view.status === "stopping") && attached.process() === void 0) {
+				await stop("timed out during preparation");
+				return {
+					kind: "foreground",
+					exitCode: null,
+					signal: null,
+					timedOut: true,
+					aborted: false,
+					timeoutMs,
+					stdout: {
+						text: "",
+						truncated: false
+					},
+					stderr: {
+						text: "",
+						truncated: false
+					},
+					...spec.sandboxPolicy !== void 0 ? { sandbox: {
+						mode: spec.sandboxPolicy.mode,
+						denied: false
+					} } : {}
+				};
+			}
+			if (view.status === "running" || view.status === "stopping") {
+				const read = registry.read(attached.id, owner);
+				return {
+					kind: "promoted",
+					jobId: attached.id,
+					timeoutMs,
+					output: renderPwshJobRead(ringDelta(read.chunks), read.lossy, read.job.output.spillPaths ?? [], attached.process()?.sandbox, escalationModes)
+				};
+			}
+			registry.remove(attached.id, owner);
+			const process = attached.process();
+			if (process === void 0) throw new Error(view.detail);
+			const result = await process.result();
+			const stopped = attached.stopped();
+			return {
+				...canonicalPwshResult(result),
+				...stopped !== void 0 ? { stopped } : {}
+			};
+		};
+		return defineTool({
+			name: "pwsh",
+			description: pwshDescription(background, escalationModes, promote),
+			parameters: {
+				command: {
 					type: "string",
-					enum: [...escalationModes],
-					description: "The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval."
+					required: true,
+					description: "The PowerShell command to execute."
 				},
-				justification: {
+				description: {
 					type: "string",
-					description: "Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access."
-				}
-			} : {}
-		},
-		output: {
-			schema: { oneOf: [{
-				type: "object",
-				additionalProperties: false,
-				properties: BACKGROUND_OUTPUT_PROPERTIES
-			}, {
-				type: "object",
-				additionalProperties: false,
-				properties: {
-					kind: {
+					required: true,
+					description: "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"Get-Process\" → \"List running processes\"."
+				},
+				timeoutMs: {
+					type: "number",
+					description: promote ? "Timeout in milliseconds. The executor applies its configured default and cap; on expiry the command moves to the background as a job instead of being killed." : "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."
+				},
+				workdir: {
+					type: "string",
+					description: "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."
+				},
+				...background ? { run_in_background: {
+					type: "boolean",
+					description: "Run in the background and return a job id immediately (collect with job_output, stop with job_kill). No timeout applies."
+				} } : {},
+				...escalationModes.length > 0 ? {
+					sandbox_permissions: {
 						type: "string",
-						required: true,
-						const: "foreground"
-					},
-					exitCode: {
-						required: true,
-						oneOf: [{ type: "integer" }, { type: "null" }]
-					},
-					signal: {
-						required: true,
-						oneOf: [{ type: "string" }, { type: "null" }]
-					},
-					timedOut: {
-						type: "boolean",
-						required: true
+						enum: [...escalationModes],
+						description: "The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval."
 					},
-					aborted: {
-						type: "boolean",
-						required: true
-					},
-					timeoutMs: {
-						type: "number",
-						required: true
+					justification: {
+						type: "string",
+						description: "Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access."
+					}
+				} : {}
+			},
+			output: {
+				schema: { oneOf: [
+					{
+						type: "object",
+						additionalProperties: false,
+						properties: BACKGROUND_OUTPUT_PROPERTIES
 					},
-					stdout: {
+					{
 						type: "object",
 						additionalProperties: false,
-						required: true,
 						properties: {
-							text: {
+							kind: {
+								type: "string",
+								required: true,
+								const: "promoted"
+							},
+							jobId: {
 								type: "string",
 								required: true
 							},
-							truncated: {
-								type: "boolean",
+							timeoutMs: {
+								type: "number",
 								required: true
 							},
-							spillPath: { type: "string" }
+							output: {
+								type: "string",
+								required: true
+							}
 						}
 					},
-					stderr: {
+					{
 						type: "object",
 						additionalProperties: false,
-						required: true,
 						properties: {
-							text: {
+							kind: {
 								type: "string",
-								required: true
+								required: true,
+								const: "foreground"
+							},
+							exitCode: {
+								required: true,
+								oneOf: [{ type: "integer" }, { type: "null" }]
 							},
-							truncated: {
+							signal: {
+								required: true,
+								oneOf: [{ type: "string" }, { type: "null" }]
+							},
+							timedOut: {
 								type: "boolean",
 								required: true
 							},
-							spillPath: { type: "string" }
-						}
-					},
-					sandbox: {
-						type: "object",
-						additionalProperties: false,
-						properties: {
-							mode: {
-								type: "string",
+							aborted: {
+								type: "boolean",
 								required: true
 							},
-							denied: {
-								type: "boolean",
+							stopped: { type: "string" },
+							timeoutMs: {
+								type: "number",
 								required: true
 							},
-							enforcement: { type: "string" },
-							runnerFailed: { type: "boolean" }
+							stdout: {
+								type: "object",
+								additionalProperties: false,
+								required: true,
+								properties: {
+									text: {
+										type: "string",
+										required: true
+									},
+									truncated: {
+										type: "boolean",
+										required: true
+									},
+									spillPath: { type: "string" }
+								}
+							},
+							stderr: {
+								type: "object",
+								additionalProperties: false,
+								required: true,
+								properties: {
+									text: {
+										type: "string",
+										required: true
+									},
+									truncated: {
+										type: "boolean",
+										required: true
+									},
+									spillPath: { type: "string" }
+								}
+							},
+							sandbox: {
+								type: "object",
+								additionalProperties: false,
+								properties: {
+									mode: {
+										type: "string",
+										required: true
+									},
+									denied: {
+										type: "boolean",
+										required: true
+									},
+									enforcement: { type: "string" },
+									runnerFailed: { type: "boolean" }
+								}
+							}
 						}
 					}
+				] },
+				render: (_args, value) => [{
+					type: "text",
+					text: value.kind === "background" ? `started background job ${value.jobId}` : value.kind === "promoted" ? renderPwshPromoted(value) : renderPwshResult(value, escalationModes)
+				}]
+			},
+			async execute(args, exec) {
+				validatePwshArgs(args);
+				const standingPolicy = resolveSandboxPolicy(exec);
+				const approvedMode = args.sandbox_permissions !== void 0 && args.justification !== void 0 ? await approvePwshEscalation(args.sandbox_permissions, args.justification, exec, standingPolicy) : void 0;
+				const policy = approvedMode === void 0 ? standingPolicy : {
+					...standingPolicy,
+					mode: approvedMode
+				};
+				const workdir = resolveWorkdir(args.workdir, exec);
+				const request = {
+					command: args.command,
+					...workdir !== void 0 ? { workdir } : {},
+					...args.timeoutMs !== void 0 ? { timeoutMs: args.timeoutMs } : {},
+					dshEnv: ctx.shellEnv.collect(exec),
+					...policy !== void 0 ? { sandboxPolicy: policy } : {}
+				};
+				if (args.run_in_background === true) {
+					if (!backgroundEnabled) throw new Error("run_in_background is disabled for this deployment (enableRunInBackground: false)");
+					if (jobs === void 0) throw new Error("background jobs unavailable: load @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs");
+					if (exec.signal.aborted) throw toolAborted();
+					return {
+						kind: "background",
+						jobId: startJob(jobs, args, exec, ctx.shell.resolve({
+							...request,
+							onExpiry: "none"
+						})).id
+					};
 				}
-			}] },
-			render: (_args, value) => [{
-				type: "text",
-				text: value.kind === "background" ? `started background job ${value.jobId}` : renderPwshResult(value, escalationModes)
-			}]
-		},
-		async execute(args, exec) {
-			validatePwshArgs(args);
-			const standingPolicy = resolveSandboxPolicy(exec);
-			const approvedMode = args.sandbox_permissions !== void 0 && args.justification !== void 0 ? await approvePwshEscalation(args.sandbox_permissions, args.justification, exec, standingPolicy) : void 0;
-			const policy = approvedMode === void 0 ? standingPolicy : {
-				...standingPolicy,
-				mode: approvedMode
-			};
-			const workdir = resolveWorkdir(args.workdir, exec);
-			const request = {
-				command: args.command,
-				...workdir !== void 0 ? { workdir } : {},
-				...args.timeoutMs !== void 0 ? { timeoutMs: args.timeoutMs } : {},
-				dshEnv: ctx.shellEnv.collect(exec),
-				...policy !== void 0 ? { sandboxPolicy: policy } : {}
-			};
-			if (args.run_in_background === true) {
-				if (!backgroundEnabled) throw new Error("run_in_background is disabled for this deployment (enableRunInBackground: false)");
-				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");
-				if (exec.signal.aborted) {
-					const error = new HarnessError("tool call aborted", TOOL_ABORTED);
-					error.name = "AbortError";
-					throw error;
+				if (jobs !== void 0 && promote) {
+					const spec = ctx.shell.resolve({
+						...request,
+						onExpiry: "none"
+					});
+					let attached;
+					try {
+						attached = startJob(jobs, args, exec, spec);
+					} catch (error) {
+						ctx.logger.warn(`pwsh: job registration refused, running in the foreground with the timeout kill instead: ${String(error)}`);
+					}
+					if (attached !== void 0) return waitOnJob(jobs, attached, exec, spec);
 				}
+				const result = await (await ctx.shell.execute(ctx.shell.resolve({
+					...request,
+					signal: exec.signal
+				}))).result();
+				if (result.aborted) throw toolAborted();
+				return canonicalPwshResult(result);
+			},
+			presentCall: (args) => {
+				if (args.run_in_background === true) return {
+					card: "generic",
+					title: args.command,
+					kind: "execute",
+					rawInput: args.command,
+					content: [{
+						type: "text",
+						text: args.description
+					}]
+				};
 				return {
-					kind: "background",
-					jobId: jobs.start({
-						kind: "pwsh",
-						label: args.command,
-						...exec.agent ? { owner: exec.agent } : {},
-						run: () => processJob((signal) => ctx.shell.start(ctx.shell.resolve({
-							...request,
-							signal
-						})), (proc) => renderPwshProcessRead(proc.readOutput(), proc.sandbox, escalationModes))
-					})
+					card: "terminal",
+					title: args.command,
+					description: args.description,
+					...args.workdir !== void 0 ? { cwd: args.workdir } : {}
+				};
+			},
+			presentResult: (args, result) => {
+				const block = result.content.length === 1 ? result.content[0] : void 0;
+				if (block === void 0 || block.type !== "text") return void 0;
+				const raw = block.text;
+				const isBackground = typeof args === "object" && args !== null && args.run_in_background === true;
+				const isPromoted = result.value?.kind === "promoted";
+				if (isBackground || isPromoted || result.isError) return {
+					card: "generic",
+					content: [{
+						type: "text",
+						text: `\`\`\`console\n${raw.replace(/\n+$/, "")}\n\`\`\``
+					}]
+				};
+				const { body, ...exit } = parseExitStatus(raw);
+				return {
+					card: "terminal",
+					output: body,
+					...exit
 				};
 			}
-			const result = await ctx.shell.run(ctx.shell.resolve({
-				...request,
-				signal: exec.signal
-			}));
-			if (result.aborted) {
-				const error = new HarnessError("tool call aborted", TOOL_ABORTED);
-				error.name = "AbortError";
-				throw error;
-			}
-			return canonicalPwshResult(result);
-		},
-		presentCall: (args) => {
-			if (args.run_in_background === true) return {
-				card: "generic",
-				title: args.command,
-				kind: "execute",
-				rawInput: args.command,
-				content: [{
-					type: "text",
-					text: args.description
-				}]
-			};
-			return {
-				card: "terminal",
-				title: args.command,
-				description: args.description,
-				...args.workdir !== void 0 ? { cwd: args.workdir } : {}
-			};
-		},
-		presentResult: (args, result) => {
-			const block = result.content.length === 1 ? result.content[0] : void 0;
-			if (block === void 0 || block.type !== "text") return void 0;
-			const raw = block.text;
-			if (typeof args === "object" && args !== null && args.run_in_background === true || result.isError) return {
-				card: "generic",
-				content: [{
-					type: "text",
-					text: `\`\`\`console\n${raw.replace(/\n+$/, "")}\n\`\`\``
-				}]
-			};
-			const { body, ...exit } = parseExitStatus(raw);
-			return {
-				card: "terminal",
-				output: body,
-				...exit
-			};
-		}
-	}));
+		});
+	};
+	if (!backgroundEnabled) {
+		ctx.tools.register(pwshTool(void 0));
+		return;
+	}
+	let foregroundOnly = ctx.get("jobs") === void 0 ? ctx.tools.register(pwshTool(void 0)) : void 0;
+	ctx.inject(["jobs"], (jobCtx) => {
+		foregroundOnly?.();
+		foregroundOnly = void 0;
+		const unregister = ctx.tools.register(pwshTool(jobCtx.jobs));
+		jobCtx.effect(() => () => {
+			unregister();
+			if (ctx.fiber.state === 2) foregroundOnly = ctx.tools.register(pwshTool(void 0));
+		});
+	});
 }
 //#endregion
 export { Config, apply, inject, name };

package/lib/types/background.d.ts

@@ -1,28 +1,50 @@
 /**
- * Generic-task adaptation for background pwsh process handles — the shell-agnostic
- * twin of `dsh-tool-bash`'s background adaptation.
+ * Generic-job adaptation for pwsh process handles — the shell-agnostic twin
+ * of `dsh-tool-bash`'s background adaptation: the terminal
+ * outcome the registry records and the pull sources it pumps.
  *
  * @module @deepseek-ai/dsh-tool-pwsh/background
  */
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox';
 import type { ShellProcess } from '@deepseek-ai/dsh-shell';
-import type { JobHooks } from '@deepseek-ai/dsh-jobs';
+import type { JobChunk, JobHooks, JobOutcome, JobOutputSource } from '@deepseek-ai/dsh-jobs';
 /**
- * Map a settled background process onto the generic task-outcome vocabulary:
+ * Map a settled background process onto the generic job-outcome vocabulary:
  * `killed` stays `killed` (detail: the signal when one is known), everything
  * else is `completed` with the exit code as detail. A nonzero command exit is
- * reported, not failed, exactly like the foreground rendering.
+ * reported, not failed, exactly like the foreground rendering. Sandbox facts
+ * join the detail, since a job's terminal reason is the one line every
+ * reader — the model's status line, the roster row — shows.
  * @param proc - the settled process handle.
+ * @param escalationModes - escalation targets advertised by this composition.
  * @returns the outcome for the `ctx.jobs` registration.
  */
-export declare function processOutcome(proc: ShellProcess): {
-    status: 'completed' | 'killed';
-    detail: string;
-};
+export declare function processOutcome(proc: ShellProcess, escalationModes?: readonly SandboxMode[]): JobOutcome;
+/**
+ * The process's non-consuming stream readers as registry pull sources. They
+ * bind lazily because the process is spawned inside the starter, after the
+ * registry admitted the job; a read before the spawn yields nothing, and the
+ * pump keeps the model's consuming cursor untouched. A rejected spawn's
+ * stderr reader carries the provider's `subprocess failed before reporting an
+ * outcome: …` note.
+ * @param proc - the started process's observed streams, once the starter has spawned it.
+ * @returns one source per stream, stdout first.
+ */
+export declare function processSources(proc: () => Pick<ShellProcess, 'observed'> | undefined): JobOutputSource[];
+/**
+ * The ring chunks of one consuming registry read as the shell tools render a
+ * process read: stdout chunks in order, then every stderr chunk in one
+ * `[stderr]` section, so the output a foreground call hands over when it
+ * stops waiting reads exactly like the `job_output` reads that follow it.
+ * @param chunks - the chunks since the model cursor, in offset order.
+ * @returns the delta text, possibly empty.
+ */
+export declare function ringDelta(chunks: readonly JobChunk[]): string;
 /**
  * Adapt asynchronous shell preparation after job admission without exposing a partial process.
  * @param start - starts the process with job-owned cancellation.
- * @param renderOutput - consumes output from a published process.
+ * @param outcome - projects the settled process into the job outcome.
  * @returns synchronous job hooks whose completion includes preparation and process settlement.
  */
-export declare function processJob(start: (signal: AbortSignal) => Promise<ShellProcess>, renderOutput: (process: ShellProcess) => string): JobHooks;
+export declare function processJob(start: (signal: AbortSignal) => Promise<ShellProcess>, outcome: (process: ShellProcess) => JobOutcome): JobHooks;
 //# sourceMappingURL=background.d.ts.map

package/lib/types/index.d.ts

@@ -5,8 +5,9 @@
  * PowerShell-dialect: native `C:\...` paths and `$env:NAME` variables.
  *
  * Behavior mirrors `dsh-tool-bash` call-for-call: foreground and
- * `run_in_background` execution (background handles register with the
- * generic `ctx.jobs` runtime), the managed `DSH_*` environment through the
+ * `run_in_background` execution (with a job registry composed, every call
+ * registers its process with `ctx.jobs` as it starts, and a foreground call
+ * waits on its job until the timeout passes), the managed `DSH_*` environment through the
  * shared `shell-env` registry, the per-call sandbox policy resolution (the
  * calling session's mode and cwd travel to the confining executor), the
  * sandbox-denial rendering with the same-turn escalation surface
@@ -29,8 +30,21 @@ export declare const name = "tool-pwsh";
 export declare const inject: string[];
 /** Configuration for the pwsh tool. */
 export interface Config {
-    /** Expose `run_in_background` (default true); disabled calls are also rejected. */
+    /**
+     * Expose `run_in_background` while a job registry is composed (default
+     * true); disabled calls are also rejected. Without a registry the tool is
+     * foreground-only regardless.
+     */
     enableRunInBackground?: boolean;
+    /**
+     * Keep a foreground command that reaches its timeout running as a
+     * background job instead of killing it (default true). Applies only while
+     * background execution is available: with `enableRunInBackground` false or
+     * no job registry, the executor's deadline kills the command. A foreground
+     * command the registry refuses at its start (admission or a missing
+     * controller) also runs under the deadline kill.
+     */
+    promoteOnTimeout?: boolean;
 }
 /** Runtime configuration schema for the pwsh tool plugin. */
 export declare const Config: z<Config>;

package/lib/types/render.d.ts

@@ -9,13 +9,15 @@
  *
  * @module @deepseek-ai/dsh-tool-pwsh/render
  */
-import type { ShellProcessRead, ShellSandboxInfo, CollectedOutput } from '@deepseek-ai/dsh-shell';
+import type { ShellSandboxInfo, CollectedOutput } from '@deepseek-ai/dsh-shell';
 import type { SandboxMode } from '@deepseek-ai/dsh-sandbox';
 /** The renderable foreground result shape (the schema-derived value, no `kind`). */
 export interface RenderablePwshResult {
     exitCode: number | null;
     signal: string | null;
     timedOut: boolean;
+    /** The reason the command was stopped from outside the call, when a job kill ended it. */
+    stopped?: string;
     timeoutMs: number;
     stdout: CollectedOutput;
     stderr: CollectedOutput;
@@ -33,13 +35,31 @@ export interface RenderablePwshResult {
  */
 export declare function renderPwshResult(result: RenderablePwshResult, escalationModes?: readonly SandboxMode[]): string;
 /**
- * Shape one background-process read into the `job_output` delta the model
- * sees: the incremental delta, plus the lossy-read notice (with full-stream
- * spill paths) when in-memory truncation dropped unread bytes.
- * @param read - one incremental read from the process handle.
+ * Shape a foreground call that stopped waiting into the text the model sees:
+ * the output captured so far (one consuming registry read taken at that
+ * point, so `job_output` continues exactly after it), then the still-running
+ * marker and the job hand-off guidance.
+ * @param promoted - the promoted result value: the job id, the wait that
+ *   expired, and the output so far.
+ * @returns the model-facing text for a promoted call.
+ */
+export declare function renderPwshPromoted(promoted: {
+    jobId: string;
+    timeoutMs: number;
+    output: string;
+}): string;
+/**
+ * Shape the one consuming registry read a foreground call embeds in its
+ * result when it stops waiting: the output produced so far, plus the
+ * dropped-output notice (naming the job's spill files) when the model cursor
+ * fell behind the ring, and the sandbox notices. Later `job_output` reads
+ * render the same ring through the job tools.
+ * @param delta - the read's chunks as rendered text.
+ * @param lossy - whether bytes before the delta were evicted unread.
+ * @param spillPaths - the complete-stream files the job currently advertises.
  * @param sandbox - settled sandbox facts, when this was a confined process.
  * @param escalationModes - escalation targets advertised by this composition.
  * @returns the delta text with any loss or sandbox notice appended.
  */
-export declare function renderPwshProcessRead(read: ShellProcessRead, sandbox?: ShellSandboxInfo, escalationModes?: readonly SandboxMode[]): string;
+export declare function renderPwshJobRead(delta: string, lossy: boolean, spillPaths: readonly string[], sandbox?: ShellSandboxInfo, escalationModes?: readonly SandboxMode[]): string;
 //# sourceMappingURL=render.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-pwsh",
   "description": "Model-facing pwsh tool over the bash executor seam",
-  "version": "0.1.6-alpha.2",
+  "version": "0.1.7-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -27,40 +27,41 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-jobs": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-tools": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-user-approval": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-shell-env": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-shell": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.6-alpha.2"
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-agent": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-jobs": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-llm": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-sandbox": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-sandbox-policy": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-shell": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-shell-env": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-tools": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-user-approval": "0.1.7-alpha.2"
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.2"
+    "@deepseek-ai/schemastery": "~3.18.4"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-app-boot": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-agent-loop": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-jobs": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-jobs-local": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-loader-smoke": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-pwsh-local": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session-projection": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-shell": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-shell-env": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-subprocess-local": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-tool-jobs": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-user-approval": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-tools": "^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": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-app-boot": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-agent-loop-testkit": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-jobs-local": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-loader-smoke": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-llm": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-jobs": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-pwsh-local": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-sandbox": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-sandbox-policy": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-shell": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-shell-env": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-subprocess-local": "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-user-approval": "0.1.7-alpha.2"
   }
 }