@shuind/dsh-codex-harness 0.1.21 → 0.1.22

package/README.md

@@ -6,6 +6,7 @@
 
 - **精简 Codex coding-agent 提示词**：使用精简版系统提示词；身份、模型和工作目录由 `dsh-persona` 提供，避免重复的 Harness 身份说明，同时保留必要的工具契约和编码工作流。
 - **Codex 工具**：`exec_command`、`write_stdin`、`apply_patch`、`update_plan`；`apply_patch` 匹配失败时会显示文件、hunk、行号、可见空白和附近文件内容，便于修正上下文。
+- **后台任务**：`exec_command` 支持 `run_in_background: true`，立即返回 DSH `job_id`；使用 `job_output` 读取输出、`job_kill` 停止任务。任务完成时，忙碌中的 agent 会在下一步收到 inbox 注入；空闲 agent 默认保持安静，等下一次唤醒时再处理完成消息。
 - **GPT 能力补全**：为 GPT 系列模型补充图片输入和思考强度选项；不会覆盖用户已有的显式配置。
 - **Fast**：仅在 Codex preset 的模型选择菜单中显示，开启后向 Responses 请求发送 `service_tier: "priority"`。
 - **旧版 Web 兼容**：在未提供新版模型设置/上下文设置 slot 的 DSH Web 中，Fast 和上下文容量会自动回退到旧版 composer slot；client 注入不依赖纯类型 slot 包。
@@ -16,7 +17,7 @@
 ## 安装
 
 ```sh
-dsh plugin --profile web add @shuind/dsh-codex-harness@0.1.21
+dsh plugin --profile web add @shuind/dsh-codex-harness@0.1.22
 ```
 
 重启 Web，创建新会话，在模式菜单中选择 **Codex 模式**。
@@ -83,6 +84,11 @@ Codex 等待模型首个输出时，Web 输入框上方会显示 `正在等待
   name: '@shuind/dsh-codex-harness'
   config:
     collaborationPrompt: true
+
+- id: codex-jobs
+  name: '@deepseek-ai/dsh-tool-jobs'
+  config:
+    completionDelivery: quiet
 ```
 
 再写入 `preset.yml`，让 Web 中显示更清晰的名称：
@@ -93,7 +99,7 @@ description: 使用 Codex 工具并开启可选协作提示词。
 order: 10
 ```
 
-然后在 Web 的 **Agent 预设** 中选择 `My Codex`，再新建会话。这个 preset 会加载 Codex 工具，并开启协作提示词；网页搜索、远程压缩和 Skills 等其他功能需要在同一个 `agent.cordis.yml` 中按需添加。
+然后在 Web 的 **Agent 预设** 中选择 `My Codex`，再新建会话。这个 preset 会加载 Codex 工具，并开启协作提示词；网页搜索、远程压缩、后台任务控制和 Skills 等其他功能需要在同一个 `agent.cordis.yml` 中按需添加。
 
 ### 可选协作提示词（私货）
 

package/lib/index.js

@@ -261,6 +261,7 @@ function renderExecResult(result) {
 	sections.push(`Wall time: ${result.wall_time_seconds.toFixed(4)} seconds`);
 	if (result.exit_code !== void 0) sections.push(`Process exited with code ${result.exit_code}`);
 	if (result.session_id !== void 0) sections.push(`Process running with session ID ${result.session_id}`);
+	if (result.job_id !== void 0) sections.push(`Background job ID: ${result.job_id}`);
 	if (result.original_token_count !== void 0) sections.push(`Original token count: ${result.original_token_count}`);
 	sections.push("Output:", result.output);
 	return sections.join("\n");
@@ -281,6 +282,17 @@ function terminalResult(result, maxBytes, startedAt) {
 		...result.sessionStatus.kind === "exited" ? { ...result.sessionStatus.exitCode === null ? {} : { exit_code: result.sessionStatus.exitCode } } : {}
 	});
 }
+/** Map a detached shell process onto the generic DSH job outcome contract. */
+function backgroundOutcome(process) {
+	if (process.status === "killed") return {
+		status: "killed",
+		detail: process.signal !== null ? `signal: ${process.signal}` : "killed before exit"
+	};
+	return {
+		status: "completed",
+		detail: `exit code: ${process.exitCode ?? 0}`
+	};
+}
 function sleep(ms, signal) {
 	return new Promise((resolve) => {
 		let timer;
@@ -334,6 +346,7 @@ async function runExecCommand(ctx, args, exec, config) {
 	const maxBytes = outputLimit(config.maxOutputBytes, args.max_output_tokens);
 	const workdir = sessionCwd$1(exec, args.workdir);
 	const startedAt = performance.now();
+	if (args.run_in_background === true && args.tty === true) throw new Error("run_in_background is only supported for pipe-backed commands; omit tty");
 	if (args.tty === true) {
 		const agent = exec.agent;
 		const terminals = ctx.get("terminals");
@@ -377,11 +390,42 @@ async function runExecCommand(ctx, args, exec, config) {
 		login: args.login ?? true,
 		...workdir === void 0 ? {} : { workdir },
 		stdoutMaxBytes: maxBytes,
-		signal: exec.signal,
 		...dshEnv === void 0 ? {} : { dshEnv },
 		...policy === void 0 ? {} : { sandboxPolicy: policy }
 	};
-	const process = ctx.shell.start(ctx.shell.resolve(shellRequest));
+	if (args.run_in_background === true) {
+		const owner = exec.agent;
+		if (owner === void 0) throw new Error("run_in_background requires an owning agent session");
+		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) {
+			exec.signal.throwIfAborted();
+			throw new Error("tool call aborted");
+		}
+		const id = jobs.start({
+			kind: "bash",
+			label: args.cmd,
+			owner,
+			outputLimitBytes: maxBytes,
+			run: () => {
+				const process = ctx.shell.start(ctx.shell.resolve(shellRequest));
+				return {
+					cancel: () => void process.kill(),
+					done: process.done.then(() => backgroundOutcome(process)),
+					readOutput: () => readShellOutput(process.readOutput(), maxBytes)
+				};
+			}
+		});
+		return withChunkId({
+			wall_time_seconds: (performance.now() - startedAt) / 1e3,
+			job_id: id,
+			output: `Started background job ${id}. Use job_output with job_id "${id}" to read output.`
+		});
+	}
+	const process = ctx.shell.start(ctx.shell.resolve({
+		...shellRequest,
+		signal: exec.signal
+	}));
 	try {
 		await waitForShell(process, normalizeWaitMs(args.yield_time_ms, config.defaultYieldTimeMs), exec.signal);
 		const output = readShellOutput(process.readOutput(), maxBytes);
@@ -1017,7 +1061,7 @@ function normalizeCodexPromptAssembly(assembly) {
 function buildCodexSystemPrompt(config = {}) {
 	return config.collaborationPrompt === true ? `${CODEX_BASE_PROMPT}\n\n${CODEX_COLLABORATION_PROMPT}` : CODEX_BASE_PROMPT;
 }
-const EXEC_COMMAND_DESCRIPTION = "Runs a command in a PTY, returning output or a session ID for ongoing interaction.";
+const EXEC_COMMAND_DESCRIPTION = "Runs a command in a PTY, returning output, a session ID for ongoing interaction, or a background job ID when requested.";
 const WRITE_STDIN_DESCRIPTION = "Writes characters to an existing unified exec session and returns recent output.";
 const APPLY_PATCH_DESCRIPTION = "Edits files using Codex patch syntax with Begin/End Patch markers and file update directives. In hunk lines, the first character is the operation marker; repeat a source-leading marker when the source line itself starts with one.";
 const UPDATE_PLAN_DESCRIPTION = "Updates the task plan.\nProvide an optional explanation and a list of plan items, each with a step and status.\nAt most one step can be in_progress at a time.";
@@ -1165,6 +1209,10 @@ function registerExecTools(ctx, config) {
 				type: "boolean",
 				description: "True allocates a PTY for the command; false or omitted uses plain pipes."
 			},
+			run_in_background: {
+				type: "boolean",
+				description: "Run as a DSH background job and return its job id immediately; collect output with job_output and stop it with job_kill. Only supported for pipe-backed commands."
+			},
 			yield_time_ms: {
 				type: "number",
 				description: "Wait before yielding output. Defaults to 10000 ms; effective range is 250-30000 ms."
@@ -1194,6 +1242,7 @@ function registerExecTools(ctx, config) {
 					},
 					exit_code: { type: "number" },
 					session_id: { type: "number" },
+					job_id: { type: "string" },
 					original_token_count: { type: "number" },
 					output: {
 						type: "string",

package/lib/types/exec.d.ts

@@ -6,6 +6,7 @@ export interface ExecCommandArgs {
     cmd: string;
     workdir?: string;
     tty?: boolean;
+    run_in_background?: boolean;
     yield_time_ms?: number;
     max_output_tokens?: number;
     shell?: string;
@@ -24,6 +25,7 @@ export interface ExecResult {
     wall_time_seconds: number;
     output: string;
     session_id?: number;
+    job_id?: string;
     exit_code?: number;
     original_token_count?: number;
 }

package/lib/types/exec.js

@@ -56,6 +56,8 @@ export function renderExecResult(result) {
         sections.push(`Process exited with code ${result.exit_code}`);
     if (result.session_id !== undefined)
         sections.push(`Process running with session ID ${result.session_id}`);
+    if (result.job_id !== undefined)
+        sections.push(`Background job ID: ${result.job_id}`);
     if (result.original_token_count !== undefined)
         sections.push(`Original token count: ${result.original_token_count}`);
     sections.push('Output:', result.output);
@@ -80,6 +82,16 @@ function terminalResult(result, maxBytes, startedAt) {
         } : {},
     });
 }
+/** Map a detached shell process onto the generic DSH job outcome contract. */
+function backgroundOutcome(process) {
+    if (process.status === 'killed') {
+        return {
+            status: 'killed',
+            detail: process.signal !== null ? `signal: ${process.signal}` : 'killed before exit',
+        };
+    }
+    return { status: 'completed', detail: `exit code: ${process.exitCode ?? 0}` };
+}
 function sleep(ms, signal) {
     return new Promise(resolve => {
         let timer;
@@ -144,6 +156,9 @@ export async function runExecCommand(ctx, args, exec, config) {
     const maxBytes = outputLimit(config.maxOutputBytes, args.max_output_tokens);
     const workdir = sessionCwd(exec, args.workdir);
     const startedAt = performance.now();
+    if (args.run_in_background === true && args.tty === true) {
+        throw new Error('run_in_background is only supported for pipe-backed commands; omit tty');
+    }
     if (args.tty === true) {
         const agent = exec.agent;
         const terminals = ctx.get('terminals');
@@ -187,17 +202,53 @@ export async function runExecCommand(ctx, args, exec, config) {
     }
     const policy = ctx.get('sandboxPolicy')?.resolve(exec.agent === undefined ? {} : { session: exec.agent.session });
     const dshEnv = ctx.get('shellEnv')?.collect(exec);
+    // Background jobs intentionally omit the tool-call signal. Once this call
+    // returns, the job lifetime belongs to the jobs registry, not the request.
     const shellRequest = {
         command: commandFor(args),
         ...args.shell === undefined ? {} : { shell: args.shell },
         login: args.login ?? true,
         ...workdir === undefined ? {} : { workdir },
         stdoutMaxBytes: maxBytes,
-        signal: exec.signal,
         ...dshEnv === undefined ? {} : { dshEnv },
         ...policy === undefined ? {} : { sandboxPolicy: policy },
     };
-    const process = ctx.shell.start(ctx.shell.resolve(shellRequest));
+    if (args.run_in_background === true) {
+        const owner = exec.agent;
+        if (owner === undefined)
+            throw new Error('run_in_background requires an owning agent session');
+        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');
+        }
+        if (exec.signal.aborted) {
+            exec.signal.throwIfAborted();
+            throw new Error('tool call aborted');
+        }
+        const id = jobs.start({
+            kind: 'bash',
+            label: args.cmd,
+            owner,
+            outputLimitBytes: maxBytes,
+            run: () => {
+                const process = ctx.shell.start(ctx.shell.resolve(shellRequest));
+                return {
+                    cancel: () => void process.kill(),
+                    done: process.done.then(() => backgroundOutcome(process)),
+                    readOutput: () => readShellOutput(process.readOutput(), maxBytes),
+                };
+            },
+        });
+        return withChunkId({
+            wall_time_seconds: (performance.now() - startedAt) / 1000,
+            job_id: id,
+            output: `Started background job ${id}. Use job_output with job_id "${id}" to read output.`,
+        });
+    }
+    const process = ctx.shell.start(ctx.shell.resolve({
+        ...shellRequest,
+        signal: exec.signal,
+    }));
     try {
         await waitForShell(process, normalizeWaitMs(args.yield_time_ms, config.defaultYieldTimeMs), exec.signal);
         const output = readShellOutput(process.readOutput(), maxBytes);

package/lib/types/index.js

@@ -194,7 +194,7 @@ export function buildCodexSystemPrompt(config = {}) {
         ? `${CODEX_BASE_PROMPT}\n\n${CODEX_COLLABORATION_PROMPT}`
         : CODEX_BASE_PROMPT;
 }
-const EXEC_COMMAND_DESCRIPTION = 'Runs a command in a PTY, returning output or a session ID for ongoing interaction.';
+const EXEC_COMMAND_DESCRIPTION = 'Runs a command in a PTY, returning output, a session ID for ongoing interaction, or a background job ID when requested.';
 const WRITE_STDIN_DESCRIPTION = 'Writes characters to an existing unified exec session and returns recent output.';
 const APPLY_PATCH_DESCRIPTION = 'Edits files using Codex patch syntax with Begin/End Patch markers and file update directives. In hunk lines, the first character is the operation marker; repeat a source-leading marker when the source line itself starts with one.';
 const UPDATE_PLAN_DESCRIPTION = 'Updates the task plan.\nProvide an optional explanation and a list of plan items, each with a step and status.\nAt most one step can be in_progress at a time.';
@@ -306,6 +306,7 @@ function registerExecTools(ctx, config) {
             cmd: { type: 'string', required: true, description: 'Shell command to execute.' },
             workdir: { type: 'string', description: 'Working directory for the command. Defaults to the turn cwd.' },
             tty: { type: 'boolean', description: 'True allocates a PTY for the command; false or omitted uses plain pipes.' },
+            run_in_background: { type: 'boolean', description: 'Run as a DSH background job and return its job id immediately; collect output with job_output and stop it with job_kill. Only supported for pipe-backed commands.' },
             yield_time_ms: { type: 'number', description: 'Wait before yielding output. Defaults to 10000 ms; effective range is 250-30000 ms.' },
             max_output_tokens: { type: 'number', description: 'Output token budget. Defaults to 10000 tokens; larger requests may be capped by policy.' },
             shell: { type: 'string', description: "Shell binary to launch. Defaults to the user's default shell." },
@@ -320,6 +321,7 @@ function registerExecTools(ctx, config) {
                     wall_time_seconds: { type: 'number', required: true },
                     exit_code: { type: 'number' },
                     session_id: { type: 'number' },
+                    job_id: { type: 'string' },
                     original_token_count: { type: 'number' },
                     output: { type: 'string', required: true },
                 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shuind/dsh-codex-harness",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "A Codex harness with a streamlined system prompt for GPT models that do not fit DSH's native interface, while remaining compatible with the DSH plugin ecosystem.",
   "type": "module",
   "main": "lib/index.js",
@@ -89,6 +89,7 @@
     "@deepseek-ai/dsh-credentials": ">=0.1.0-rc.8",
     "@deepseek-ai/dsh-fs": ">=0.0.1-rc.1",
     "@deepseek-ai/dsh-invariants": ">=0.0.1-rc.1",
+    "@deepseek-ai/dsh-jobs": ">=0.1.0-rc.8",
     "@deepseek-ai/dsh-llm": ">=0.1.0-rc.8",
     "@deepseek-ai/dsh-settings": ">=0.1.0-rc.8",
     "@deepseek-ai/dsh-sandbox": ">=0.0.1-rc.1",
@@ -99,6 +100,7 @@
     "@deepseek-ai/dsh-tool-web": ">=0.1.0-rc.8",
     "@deepseek-ai/dsh-tool-todo": ">=0.0.1-rc.1",
     "@deepseek-ai/dsh-terminal": ">=0.0.1-rc.3",
+    "@deepseek-ai/dsh-tool-jobs": ">=0.1.0-rc.8",
     "@deepseek-ai/dsh-tools": ">=0.0.1-rc.1"
   },
   "peerDependenciesMeta": {
@@ -132,6 +134,9 @@
     "@deepseek-ai/dsh-invariants": {
       "optional": true
     },
+    "@deepseek-ai/dsh-jobs": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-llm": {
       "optional": true
     },
@@ -162,6 +167,9 @@
     "@deepseek-ai/dsh-terminal": {
       "optional": true
     },
+    "@deepseek-ai/dsh-tool-jobs": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-tools": {
       "optional": true
     }
@@ -177,6 +185,7 @@
     "@deepseek-ai/dsh-credentials": "0.1.0-rc.8",
     "@deepseek-ai/dsh-fs": "0.1.0-rc.6",
     "@deepseek-ai/dsh-invariants": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-jobs": "0.1.0-rc.8",
     "@deepseek-ai/dsh-llm": "0.1.0-rc.8",
     "@deepseek-ai/dsh-settings": "0.1.0-rc.8",
     "@deepseek-ai/dsh-sandbox": "0.1.0-rc.6",
@@ -187,6 +196,7 @@
     "@deepseek-ai/dsh-tool-web": "0.1.0-rc.8",
     "@deepseek-ai/dsh-tool-todo": "0.1.0-rc.6",
     "@deepseek-ai/dsh-terminal": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tool-jobs": "0.1.0-rc.8",
     "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
     "@types/node": "^22.20.0",
     "@types/react": "~18.3.1",

package/presets/codex/agent.cordis.yml

@@ -21,6 +21,14 @@
   config:
     collaborationPrompt: false
 
+# Background jobs use the host-plane registry. A busy agent receives a
+# completion in its next step; an idle agent keeps it pending until the next
+# user/tool wake, so finishing work never opens an unsolicited model turn.
+- id: codex-jobs
+  name: '@deepseek-ai/dsh-tool-jobs'
+  config:
+    completionDelivery: quiet
+
 # The generic DSH pi-ai adapter still owns the user's configured provider,
 # endpoint, API key, and model. Codex's remote-first transport wrapper is
 # installed only in this Codex scope and falls back to the generic DSH path.

package/presets/codex/preset.yml

@@ -1,3 +1,3 @@
 name: Codex 模式
-description: 使用精简版 Codex 提示词、exec_command、write_stdin、apply_patch 和 update_plan，并保留 dsh 的 Skills 与可插拔运行时。
+description: 使用精简版 Codex 提示词、统一执行工具、后台任务控制和 dsh Skills。
 order: 5