@deepseek-ai/dsh-tool-bash 0.1.5-rc.2 → 0.1.6-alpha.1

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-bash/README.md
-README.md: 5b38c0a0bad9e03be783ad8431cd06c2d3ba34d3
-README.zh.md: 969ca02dfa9462d884f71cde7d8b34975c4a8cff
+README.md: 43c70d7ebc8eb13f28c4e4576dfde8cb2402b775
+README.zh.md: e38e7afa6b7a534fe29d1022fc2797f5a98651b0

package/README.md

@@ -53,9 +53,10 @@ The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-a
 
 The tool executes `bash -c <command>` and returns the combined output. Commands run in a fresh shell every call, so state never persists — pass `workdir` instead of `cd`. A non-zero exit is reported as `[exit code: N]` for the agent to interpret, not surfaced as a tool error. A `description` in active voice (5–10 words) labels the call in the UI; `timeoutMs` overrides the executor's default and cap. Output beyond the executor's stream caps is truncated to its tail, with the full output saved to a spill file whose path is reported.
 
+<a id="running-long-commands-in-the-background"></a>
 ### Running long commands in the background
 
-Passing `run_in_background: true` returns a job id immediately and no timeout applies; the command keeps running while the agent works on something else. The agent reads its output with `job_output` (non-blocking unless `wait: true`), lists jobs with `job_list`, and stops it with `job_kill`; a finished job notifies the owning agent in-session. Background support needs the generic job runtime (`dsh-jobs-local`) and its control tools (`dsh-tool-jobs`) mounted.
+Passing `run_in_background: true` admits a job and returns its id immediately; confinement preparation may still be pending, and no background execution timeout applies. Output is empty until the process is available. Job cancellation aborts preparation and stops any process that arrives afterward; startup failure settles the admitted job as failed. The agent reads its output with `job_output` (non-blocking unless `wait: true`), lists jobs with `job_list`, and stops it with `job_kill`; a finished job notifies the owning agent in-session. Background support needs the generic job runtime (`dsh-jobs-local`) and its control tools (`dsh-tool-jobs`) mounted.
 
 ### Sandboxed execution and escalation
 
@@ -87,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) | Own asynchronous shell preparation and map process settlement onto job outcomes |
 | [`src/render.ts`](src/render.ts) | Model-facing result text: streams, markers, truncation notices |
 | — | No runtime invariant companion is published; the environment registry validates ownership and collected values at each mutation/read; it publishes no independent snapshot that a companion could cross-check. |
 

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-tool-bash` 让 agent 运行一次性 `bash` 命令，并接收 stdout、stderr 与退出标记。每次调用都使用全新 shell，因此 cwd、变量和函数不会保留；`run_in_background` 可启动长时间运行的工作，agent 能用 `job_output` 检查、用 `job_kill` 停止。命令会收到受管 `DSH_*` 环境；沙箱拒绝可携带更宽的 `sandbox_permissions`、一句 `justification` 与用户批准重试一次。非零退出会作为结果报告，因此由 agent 决定如何响应；请使用 `dsh-bash-local` 或 `dsh-bash-sandbox` 等执行器，并加载 `dsh-shell-env`。
+`dsh-tool-bash` 让 agent（智能体）运行一次性 `bash` 命令，并接收 stdout、stderr 与退出标记。每次调用都使用全新 shell，因此 cwd、变量和函数不会保留；`run_in_background` 可启动长时间运行的工作，agent 能用 `job_output` 检查、用 `job_kill` 停止。命令会收到受管 `DSH_*` 环境；沙箱拒绝后，可携带更宽的 `sandbox_permissions`、一句 `justification` 并经用户批准重试一次。非零退出会作为结果报告，因此由 agent 决定如何响应；请使用 `dsh-bash-local` 或 `dsh-bash-sandbox` 等执行器，并加载 `dsh-shell-env`。
 
 ## 目录
 
@@ -53,13 +53,14 @@ kind: "package-reference"
 
 工具执行 `bash -c <command>` 并返回合并后的输出。命令每次调用都运行在全新 shell 中，因此状态从不保留——请传 `workdir` 而不是 `cd`。非零退出以 `[exit code: N]` 报告给 agent 解读，而不是作为工具错误抛出。主动语态的 `description`（5–10 个词）在 UI 中标注该调用；`timeoutMs` 覆盖执行器的默认值与上限。超出执行器流上限的输出会被截断为尾部，完整输出保存到 spill 文件并报告其路径。
 
+<a id="running-long-commands-in-the-background"></a>
 ### 后台运行长时间命令
 
-传入 `run_in_background: true` 会立即返回 job id，不应用超时；命令继续运行，agent 同时处理其他事情。agent 用 `job_output` 读取输出（除非 `wait: true`，否则非阻塞）、用 `job_list` 列出任务、用 `job_kill` 停止任务；完成的任务会在会话内通知拥有它的 agent。后台支持需要挂载通用任务运行时（`dsh-jobs-local`）及其控制工具（`dsh-tool-jobs`）。
+传入 `run_in_background: true` 会准入任务并立即返回 job id；限制准备可能仍在进行，且不设后台执行超时。进程可用前输出为空。任务取消会中止准备并停止随后返回的进程；启动失败使已准入任务以失败状态结算。agent 用 `job_output` 读取输出（除非 `wait: true`，否则非阻塞）、用 `job_list` 列出任务、用 `job_kill` 停止任务；完成的任务会在会话内通知拥有它的 agent。后台支持需要挂载通用任务运行时（`dsh-jobs-local`）及其控制工具（`dsh-tool-jobs`）。
 
 ### 沙箱执行与升权
 
-当已挂载的执行器约束命令（例如 `dsh-bash-sandbox`）时，被阻止的文件操作会报告为 `[sandbox: file access denied under <mode> mode]`——这是策略拒绝，不是命令失败。模型随后可以在同一轮次中用 `sandbox_permissions`（满足需要的最窄更宽模式）与一句 `justification` 重试完全相同的命令一次；该重试引发的审批提示就是用户同意的方式。升权绝不能预先推测：没有真实拒绝依据的请求，或没有严格宽于当前模式的请求，会在不运行任何东西的情况下失败关闭，被拒绝的升权对该命令即为最终结果。
+当已挂载的执行器约束命令（例如 `dsh-bash-sandbox`）时，被阻止的文件操作会报告为 `[sandbox: file access denied under <mode> mode]`——这是策略拒绝，不是命令失败。模型随后可以在同一轮次中用 `sandbox_permissions`（满足需要的最窄更宽模式）与一句 `justification` 重试完全相同的命令一次；该重试引发的审批提示就是用户同意的方式。升权绝不能预先推测：没有真实拒绝依据的请求，或没有严格宽于当前模式的请求，都会直接失败且不执行任何操作；被拒绝的升权对该命令即为最终结果。
 
 ### 可能出什么问题
 
@@ -77,7 +78,7 @@ kind: "package-reference"
 
 ### 设计理念
 
-- **shell seam 的模型侧消费方。** 本工具是 bash 能力的 Consumer 角色：它注册 `bash` schema、渲染结果并解析每次调用的策略，进程机制归执行器 seam 所有。
+- **shell seam 的模型侧消费方。** 本工具是 bash 能力的消费方角色：它注册 `bash` schema、渲染结果并解析每次调用的策略，进程机制归执行器 seam 所有。
 - **请求只来自命名参数。** 工具从不暴露 `stdin`、`env` 或 `stdoutMaxBytes`；它只用命令／workdir／超时／信号字段加上注册表收集的 `dshEnv` 构建每个请求，因此模型提供的键无法替换受管值。
 - **非零退出只报告、不失败。** 只有基础设施故障（spawn 错误、中止）才会作为工具错误暴露；模型解读退出码与标记。
 - **后台工作归任务运行时。** 后台调用把进程句柄注册到 `ctx.jobs`；job id、所有权、完成通知与释放都是运行时的职责，本工具只把 bash 退出与沙箱事实映射为任务输出。
@@ -87,9 +88,9 @@ kind: "package-reference"
 | 文件 | 职责 |
 |---|---|
 | [`src/index.ts`](src/index.ts) | 插件入口：工具注册、提示词区段、参数校验、升权、请求组装 |
-| [`src/background.ts`](src/background.ts) | 把已结算的后台进程映射为通用任务结果词汇 |
+| [`src/background.ts`](src/background.ts) | 管理异步 shell 准备，并将进程结算映射为任务结果 |
 | [`src/render.ts`](src/render.ts) | 模型侧结果文本：流、标记、截断通知 |
-| — | 不发布运行时不变式伴生入口；执行关系归能力 seam 所有。 |
+| — | 不发布运行时不变式伴生入口；环境注册表在每次变更和读取时校验所有权及收集值，且不发布可供伴生入口交叉核对的独立快照；执行关系由能力 seam 负责。 |
 
 ### 请求解析
 
@@ -125,7 +126,7 @@ kind: "package-reference"
 
 #### 模型看到什么
 
-该插件注册 scope 中的每次请求都在 first-party 顺序 1000 处包含以下 bash 指引。策略归属方通过其缓存安全的运行时上下文贡献当前沙箱状态，而不修改本区段。按 scope 限制工具可以隐藏 schema，却不会移除这个独立注册的区段。
+以下 bash 指引会以第一方顺序值 1000 出现在该插件注册作用域内的每次请求中。策略归属方通过其缓存安全的运行时上下文贡献当前沙箱状态，而不修改本区段。按作用域实施的工具限制可以隐藏 schema，却不会移除这个独立注册的区段。
 
 ##### Bash 指引
 
@@ -139,13 +140,13 @@ Check the [exit code: N] marker on every bash result; investigate failures befor
 
 #### KV Cache 影响
 
-只要注册 scope 与提示词文本不变，前缀就保持稳定。插件激活或释放可能使从该提示词区段起的复用失效；沙箱模式切换不会。
+只要注册作用域与提示词文本不变，前缀就保持稳定。插件激活或释放可能使从该提示词区段起的复用失效；沙箱模式切换不会。
 
 ### 工具 schema
 
 #### 模型看到什么
 
-模型会看到生成的 [`bash` schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-bash)。仅当本生产方启用 `run_in_background` 时，该字段才会出现；仅当已挂载执行器声明支持沙箱时，`sandbox_permissions` 和 `justification` 才会出现。按 agent（智能体）scope 限制工具可以移除该 agent 的定义。
+模型会看到生成的 [`bash` schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-bash)。仅当本生产方启用 `run_in_background` 时，该字段才会出现；仅当已挂载执行器声明支持沙箱时，`sandbox_permissions` 和 `justification` 才会出现。按 agent 作用域限制工具可以移除该 agent 的定义。
 
 #### Token 影响
 
@@ -163,7 +164,7 @@ renderer 输出依数据而定的 stdout 尾部，再输出可选的 `[stderr]`
 
 #### Token 影响
 
-调用前的结果 token 为零。输出按流设界，而每行已发出的内容在压缩（compaction）前保留于历史。
+调用前的结果 token 为零。每条流的输出有界，每个已输出行则会保留在历史中，直至压缩（compaction）。
 
 #### KV Cache 影响
 
@@ -177,7 +178,7 @@ renderer 输出依数据而定的 stdout 尾部，再输出可选的 `[stderr]`
 
 #### Token 影响
 
-启动确认很小且会被保留；收集到的输出依数据而定，受执行器流缓冲设界。消费性读取不会重复先前输出。
+启动确认很短且会保留；收集到的输出依数据而定，并受执行器流缓冲区限制。消费式读取不会重复先前输出。
 
 #### KV Cache 影响
 

package/lib/index.js

@@ -1,8 +1,8 @@
 import z from "@deepseek-ai/schemastery";
-import { isAbsolute, resolve } from "node:path";
+import { isAbsolute, sep } from "node:path";
 import { TOOL_ABORTED, defineTool } from "@deepseek-ai/dsh-tools";
 import { HarnessError } from "@deepseek-ai/dsh-llm";
-import { ESCALATION_TARGETS, approveEscalation, canonicalPath, escalationHintMarker, sandboxDenialMarker, validateEscalationArgs } from "@deepseek-ai/dsh-sandbox";
+import { ESCALATION_TARGETS, approveEscalation, escalationHintMarker, sandboxDenialMarker, validateEscalationArgs } from "@deepseek-ai/dsh-sandbox";
 import { DSH_ENV_PREFIX, parseExitStatus } from "@deepseek-ai/dsh-shell";
 //#region lib/types/background.js
 /**
@@ -28,6 +28,40 @@ function processOutcome(proc) {
 		detail: `exit code: ${proc.exitCode ?? 0}`
 	};
 }
+/**
+* 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.
+* @returns synchronous job hooks whose completion includes preparation and process settlement.
+*/
+function processJob(start, renderOutput) {
+	const controller = new AbortController();
+	let process;
+	return {
+		cancel: (reason) => {
+			if (controller.signal.aborted) return;
+			controller.abort(reason);
+			process?.kill();
+		},
+		done: (async () => {
+			try {
+				process = await start(controller.signal);
+				try {
+					if (controller.signal.aborted) process.kill();
+				} finally {
+					await process.done;
+				}
+				return processOutcome(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
 //#region lib/types/render.js
 /**
@@ -176,9 +210,9 @@ function presentBashResult(args, result) {
 */
 function resolveWorkdir(modelWorkdir, exec, policyWorkspaceRoot) {
 	const headerCwd = exec.agent?.session.header.cwd;
-	const sessionCwd = policyWorkspaceRoot ?? (headerCwd === void 0 ? void 0 : canonicalPath(headerCwd));
+	const sessionCwd = policyWorkspaceRoot ?? headerCwd;
 	if (modelWorkdir === void 0) return sessionCwd;
-	if (sessionCwd !== void 0 && !isAbsolute(modelWorkdir)) return resolve(sessionCwd, modelWorkdir);
+	if (sessionCwd !== void 0 && !isAbsolute(modelWorkdir)) return `${sessionCwd}${sep}${modelWorkdir}`;
 	return modelWorkdir;
 }
 /** Detach the executor DTO from readonly Service Definition types into plain JSON data. */
@@ -415,14 +449,10 @@ function apply(ctx, config = {}) {
 						kind: "bash",
 						label: args.command,
 						...exec.agent ? { owner: exec.agent } : {},
-						run: () => {
-							const proc = ctx.shell.start(ctx.shell.resolve(request));
-							return {
-								cancel: () => void proc.kill(),
-								done: proc.done.then(() => processOutcome(proc)),
-								readOutput: () => renderProcessRead(proc.readOutput(), proc.sandbox, escalationModes)
-							};
-						}
+						run: () => processJob((signal) => ctx.shell.start(ctx.shell.resolve({
+							...request,
+							signal
+						})), (proc) => renderProcessRead(proc.readOutput(), proc.sandbox, escalationModes))
 					})
 				};
 			}

package/lib/types/background.d.ts

@@ -4,6 +4,7 @@
  * @module @deepseek-ai/dsh-tool-bash/background
  */
 import type { ShellProcess } from '@deepseek-ai/dsh-shell';
+import type { JobHooks } from '@deepseek-ai/dsh-jobs';
 /**
  * Map a settled background process onto the generic task-outcome vocabulary:
  * `killed` stays `killed` (detail: the signal when one is known), everything
@@ -16,4 +17,11 @@ export declare function processOutcome(proc: ShellProcess): {
     status: 'completed' | 'killed';
     detail: 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.
+ * @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;
 //# sourceMappingURL=background.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-bash",
   "description": "Model-facing bash tool with optional generic background-job and sandbox-escalation support",
-  "version": "0.1.5-rc.2",
+  "version": "0.1.6-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -27,41 +27,41 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-shell": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-shell-env": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-agent": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-sandbox": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-jobs": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-tools": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-user-approval": "^0.1.5-rc.2",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/dsh-agent": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-shell": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-shell-env": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-jobs": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-tools": "^0.1.6-alpha.1",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-user-approval": "^0.1.6-alpha.1"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-agent-loop": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-shell-env": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-shell": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-subprocess-local": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-sandbox": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-jobs": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-jobs-local": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-tool-jobs": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-tools": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-agent": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-shell": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-shell-env": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-bash-local": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-subprocess-local": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-jobs-local": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-tool-jobs": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-tools": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-user-approval": "^0.1.6-alpha.1",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-session-projection": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-user-approval": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-bash-local": "^0.1.5-rc.2"
+    "@deepseek-ai/dsh-session": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-session-projection": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-jobs": "^0.1.6-alpha.1"
   }
 }