@shuind/dsh-codex-harness 0.1.20 → 0.1.22

package/README.md

@@ -5,9 +5,11 @@
 ## 功能
 
 - **精简 Codex coding-agent 提示词**：使用精简版系统提示词；身份、模型和工作目录由 `dsh-persona` 提供，避免重复的 Harness 身份说明，同时保留必要的工具契约和编码工作流。
-- **Codex 工具**：`exec_command`、`write_stdin`、`apply_patch`、`update_plan`。
+- **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 包。
 - **远程搜索与压缩**：OpenAI Responses 请求默认优先使用 hosted `web_search` 和 `/responses/compact`；失败时回退到 DSH 的本地实现。
 - **上下文容量**：在 Web 中设置 `1K`–`1000K` tokens，设置值作用于下一次请求。
 - **活动状态**：Codex 等待模型响应或进行上下文压缩时，在输入框上方显示对应状态和耗时，让长时间 Deep Diving 不再像卡住。
@@ -15,7 +17,7 @@
 ## 安装
 
 ```sh
-dsh plugin --profile web add @shuind/dsh-codex-harness@0.1.20
+dsh plugin --profile web add @shuind/dsh-codex-harness@0.1.22
 ```
 
 重启 Web，创建新会话，在模式菜单中选择 **Codex 模式**。
@@ -82,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 中显示更清晰的名称：
@@ -92,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/client.js

@@ -28,6 +28,11 @@ window.__ModuleLoader__.load({
 		/** Browser controls for the Codex request settings mounted by the Host plugin. */
 		const NS = "codex";
 		const SETTINGS_NAMESPACE = "codex";
+		const MODEL_SETTINGS_SLOT = "conversation.input.model.settings";
+		const CONTEXT_SETTINGS_SLOT = "conversation.input.context.settings";
+		const FAST_FALLBACK_SLOT = "conversation.input.right";
+		const CONTEXT_FALLBACK_SLOT = "conversation.input.dock";
+		const DEFAULT_CONTEXT_WINDOW = 262144;
 		const en = {
 			fast: "Fast mode",
 			fastOn: "Fast mode on (priority tier)",
@@ -95,6 +100,50 @@ window.__ModuleLoader__.load({
 				})]
 			});
 		}
+		/** The legacy composer seat is a compact inline row, not a menu panel. */
+		function FastModeFallback(props) {
+			const { sessionId, useSessions, useSettings, setSetting, t } = props;
+			const agentPreset = useSessions((state) => state.byId[sessionId]?.agentPreset);
+			const snapshot = useSettings((state) => state);
+			const fast = snapshot.value?.fast ?? false;
+			if (agentPreset !== "codex") return null;
+			return (0, react_jsx_runtime.jsxs)("button", {
+				type: "button",
+				role: "switch",
+				disabled: snapshot.writable === false,
+				"aria-checked": fast,
+				"aria-label": fast ? t("fastOn") : t("fastOff"),
+				title: fast ? t("fastOn") : t("fastOff"),
+				onClick: () => {
+					setSetting("fast", !fast);
+				},
+				style: {
+					boxSizing: "border-box",
+					display: "inline-flex",
+					alignItems: "center",
+					gap: 5,
+					height: 28,
+					border: "1px solid var(--dsw-alias-border-primary)",
+					borderRadius: 7,
+					padding: "0 8px",
+					color: fast ? "var(--dsw-static-blue-500)" : "var(--dsw-alias-label-secondary)",
+					background: fast ? "var(--dsw-alias-interactive-bg-selected)" : "transparent",
+					cursor: snapshot.writable === false ? "default" : "pointer",
+					font: "inherit",
+					fontSize: 12,
+					lineHeight: "20px",
+					fontWeight: fast ? 600 : 400,
+					whiteSpace: "nowrap"
+				},
+				children: [(0, react_jsx_runtime.jsx)("span", { children: t("fast") }), (0, react_jsx_runtime.jsx)("span", {
+					style: {
+						color: "var(--dsw-alias-label-tertiary)",
+						fontSize: 11
+					},
+					children: fast ? t("fastStateOn") : t("fastStateOff")
+				})]
+			});
+		}
 		function ContextSizeControl({ contextWindow, useSettings, setSetting, unsetSetting, t }) {
 			const snapshot = useSettings((state) => state);
 			const configured = snapshot.value?.contextWindow;
@@ -211,6 +260,16 @@ window.__ModuleLoader__.load({
 				]
 			});
 		}
+		function contextWindowFromProjection(useProjection) {
+			const pressure = useProjection("contextPressure");
+			return pressure?.contextWindow !== void 0 && pressure.contextWindow > 0 ? pressure.contextWindow : DEFAULT_CONTEXT_WINDOW;
+		}
+		function LegacyContextSizeControl({ useProjection, ...props }) {
+			return (0, react_jsx_runtime.jsx)(ContextSizeControl, {
+				...props,
+				contextWindow: contextWindowFromProjection(useProjection)
+			});
+		}
 		function elapsedSeconds(startedAt, now) {
 			return Math.max(0, Math.floor((now - startedAt) / 1e3));
 		}
@@ -275,7 +334,15 @@ window.__ModuleLoader__.load({
 			"locale",
 			"settingsScope"
 		];
-		/** Mount Fast inside the model selector and context size inside the meter panel. */
+		/** Select a preferred slot when the host declares it, otherwise use a stable legacy composer seat. */
+		function chooseDeclaredSlot(preferred, fallback, isDeclared) {
+			return isDeclared(preferred) ? preferred : fallback;
+		}
+		function slotIsDeclared(ctx, slot) {
+			const registry = ctx.slots;
+			return typeof registry.spec === "function" && registry.spec.call(ctx.slots, slot) !== void 0;
+		}
+		/** Mount Codex controls in the newest named seats, with legacy composer fallbacks. */
 		function apply(ctx) {
 			ctx.effect(() => ctx.locale.register(NS, {
 				en,
@@ -287,20 +354,34 @@ window.__ModuleLoader__.load({
 				setSetting: (field, value) => settings.set(field, value),
 				unsetSetting: (field) => settings.unset(field)
 			});
-			ctx.slots.inject("conversation.input.model.settings", () => ctx.slots.register({
-				name: "conversation.input.model.settings",
+			if (chooseDeclaredSlot(MODEL_SETTINGS_SLOT, FAST_FALLBACK_SLOT, (slot) => slotIsDeclared(ctx, slot)) === MODEL_SETTINGS_SLOT) ctx.slots.inject(MODEL_SETTINGS_SLOT, () => ctx.slots.register({
+				name: MODEL_SETTINGS_SLOT,
 				id: "codex-fast",
 				order: 0,
 				locale: NS,
 				inject: injected
 			}, FastModeButton));
-			ctx.slots.inject("conversation.input.context.settings", () => ctx.slots.register({
-				name: "conversation.input.context.settings",
+			else ctx.slots.inject(FAST_FALLBACK_SLOT, () => ctx.slots.register({
+				name: FAST_FALLBACK_SLOT,
+				id: "codex-fast-fallback",
+				order: 0,
+				locale: NS,
+				inject: injected
+			}, FastModeFallback));
+			if (chooseDeclaredSlot(CONTEXT_SETTINGS_SLOT, CONTEXT_FALLBACK_SLOT, (slot) => slotIsDeclared(ctx, slot)) === CONTEXT_SETTINGS_SLOT) ctx.slots.inject(CONTEXT_SETTINGS_SLOT, () => ctx.slots.register({
+				name: CONTEXT_SETTINGS_SLOT,
 				id: "codex-context-size",
 				order: 0,
 				locale: NS,
 				inject: injected
 			}, ContextSizeControl));
+			else ctx.slots.inject(CONTEXT_FALLBACK_SLOT, () => ctx.slots.register({
+				name: CONTEXT_FALLBACK_SLOT,
+				id: "codex-context-size-fallback",
+				order: 0,
+				locale: NS,
+				inject: injected
+			}, LegacyContextSizeControl));
 			ctx.slots.inject("conversation.composer.dock", () => ctx.slots.register({
 				name: "conversation.composer.dock",
 				id: "codex-activity",
@@ -315,6 +396,7 @@ window.__ModuleLoader__.load({
 		//#endregion
 		exports.ActivityLine = ActivityLine;
 		exports.apply = apply;
+		exports.chooseDeclaredSlot = chooseDeclaredSlot;
 		exports.default = client_default;
 		exports.inject = inject;
 		return module.exports;

package/lib/index.js

@@ -177,17 +177,30 @@ function findSequence(lines, expected, from, endOfFile) {
 	}
 	return -1;
 }
+function displayPatchLine(line) {
+	if (line.length === 0) return "<empty>";
+	return line.replaceAll(" ", "[space]").replaceAll("	", "[tab]");
+}
+function formatPatchExcerpt(lines, start, count) {
+	if (lines.length === 0) return "  <empty file>";
+	const first = Math.max(0, Math.min(start, lines.length - 1));
+	return lines.slice(first, first + count).map((line, offset) => `  ${first + offset + 1}: ${displayPatchLine(line)}`).join("\n");
+}
+function mismatchMessage(label, hunkIndex, expected, actual, from, endOfFile) {
+	const expectedPreview = expected.slice(0, 12).map((line, index) => `  ${index + 1}: ${displayPatchLine(line)}`).join("\n");
+	const expectedSuffix = expected.length > 12 ? "\n  ..." : "";
+	const excerptStart = endOfFile ? Math.max(0, actual.length - 6) : Math.max(0, from - 2);
+	const markerHint = expected.some((wanted) => wanted.length > 0 && actual.includes(`-${wanted}`)) ? "\nHint: if a source line starts with a patch marker, repeat that marker after the operation marker; for example, `-- item` deletes the source line `- item`." : "";
+	return `could not find expected lines in ${label} hunk ${hunkIndex + 1} (search starts at line ${from + 1})\nExpected:\n${expectedPreview}${expectedSuffix}\nFile excerpt:\n${formatPatchExcerpt(actual, excerptStart, 10)}${markerHint}`;
+}
 /** Apply parsed update hunks and return LF-normalized text. */
-function applyPatchHunks(original, hunks) {
+function applyPatchHunks(original, hunks, label = "file") {
 	const value = splitText(original.replaceAll("\r\n", "\n"));
 	let cursor = 0;
-	for (const hunk of hunks) {
+	for (const [hunkIndex, hunk] of hunks.entries()) {
 		const expected = hunk.lines.filter((line) => line.kind !== "add").map((line) => line.text);
 		const start = findSequence(value.lines, expected, cursor, hunk.endOfFile);
-		if (start < 0) {
-			const detail = expected.join("\n");
-			invalid(`could not find expected lines${detail.length === 0 ? "" : `:\n${detail}`}`);
-		}
+		if (start < 0) invalid(mismatchMessage(label, hunkIndex, expected, value.lines, cursor, hunk.endOfFile));
 		const replacement = hunk.lines.filter((line) => line.kind !== "delete").map((line) => line.text);
 		value.lines.splice(start, expected.length, ...replacement);
 		cursor = start + replacement.length;
@@ -248,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");
@@ -268,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;
@@ -321,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");
@@ -364,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);
@@ -1004,9 +1061,9 @@ 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 a patch.";
+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.";
 const PLAN_STATUSES = [
 	"pending",
@@ -1064,7 +1121,7 @@ async function applyOnePatch(ctx, file, exec, policy) {
 	}
 	const sourceInfo = await observedTarget(ctx, target, exec);
 	const original = await ctx.fs.readText(target, exec.signal);
-	const updated = file.kind === "delete" ? void 0 : applyPatchHunks(original, file.hunks);
+	const updated = file.kind === "delete" ? void 0 : applyPatchHunks(original, file.hunks, file.path);
 	if (file.kind === "delete") {
 		await deletePatchedFile(ctx, target, sourceInfo.version, exec, policy);
 		return {
@@ -1152,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."
@@ -1181,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/client/index.d.ts

@@ -35,7 +35,9 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 type ActivityProps = PropsRuntime<'conversation.composer.dock'> & PropsLocale<'codex'>;
 export declare function ActivityLine({ sessionId, useSession, useSessions, useProjection, t }: ActivityProps): import("react").JSX.Element | null;
 export declare const inject: string[];
-/** Mount Fast inside the model selector and context size inside the meter panel. */
+/** Select a preferred slot when the host declares it, otherwise use a stable legacy composer seat. */
+export declare function chooseDeclaredSlot(preferred: string, fallback: string, isDeclared: (slot: string) => boolean): string;
+/** Mount Codex controls in the newest named seats, with legacy composer fallbacks. */
 export declare function apply(ctx: Context): void;
 declare const _default: {
     inject: string[];

package/lib/types/client/index.js

@@ -5,6 +5,11 @@ import { CODEX_CONTEXT_MAX, CODEX_CONTEXT_UNIT, CODEX_PRESET_ID } from "../conte
 import { awaitingModelStartedAt } from "./activity.js";
 const NS = 'codex';
 const SETTINGS_NAMESPACE = 'codex';
+const MODEL_SETTINGS_SLOT = 'conversation.input.model.settings';
+const CONTEXT_SETTINGS_SLOT = 'conversation.input.context.settings';
+const FAST_FALLBACK_SLOT = 'conversation.input.right';
+const CONTEXT_FALLBACK_SLOT = 'conversation.input.dock';
+const DEFAULT_CONTEXT_WINDOW = 262_144;
 const en = {
     fast: 'Fast mode',
     fastOn: 'Fast mode on (priority tier)',
@@ -55,6 +60,33 @@ function FastModeButton({ sessionId, useSessions, useSettings, setSetting, t })
             textAlign: 'left',
         }, children: [_jsx("span", { children: t('fast') }), _jsx("span", { style: { color: 'var(--dsw-alias-label-tertiary)', fontSize: 12 }, children: fast ? t('fastStateOn') : t('fastStateOff') })] }));
 }
+/** The legacy composer seat is a compact inline row, not a menu panel. */
+function FastModeFallback(props) {
+    const { sessionId, useSessions, useSettings, setSetting, t } = props;
+    const agentPreset = useSessions(state => state.byId[sessionId]?.agentPreset);
+    const snapshot = useSettings(state => state);
+    const fast = snapshot.value?.fast ?? false;
+    if (agentPreset !== CODEX_PRESET_ID)
+        return null;
+    return (_jsxs("button", { type: "button", role: "switch", disabled: snapshot.writable === false, "aria-checked": fast, "aria-label": fast ? t('fastOn') : t('fastOff'), title: fast ? t('fastOn') : t('fastOff'), onClick: () => { void setSetting('fast', !fast); }, style: {
+            boxSizing: 'border-box',
+            display: 'inline-flex',
+            alignItems: 'center',
+            gap: 5,
+            height: 28,
+            border: '1px solid var(--dsw-alias-border-primary)',
+            borderRadius: 7,
+            padding: '0 8px',
+            color: fast ? 'var(--dsw-static-blue-500)' : 'var(--dsw-alias-label-secondary)',
+            background: fast ? 'var(--dsw-alias-interactive-bg-selected)' : 'transparent',
+            cursor: snapshot.writable === false ? 'default' : 'pointer',
+            font: 'inherit',
+            fontSize: 12,
+            lineHeight: '20px',
+            fontWeight: fast ? 600 : 400,
+            whiteSpace: 'nowrap',
+        }, children: [_jsx("span", { children: t('fast') }), _jsx("span", { style: { color: 'var(--dsw-alias-label-tertiary)', fontSize: 11 }, children: fast ? t('fastStateOn') : t('fastStateOff') })] }));
+}
 function ContextSizeControl({ contextWindow, useSettings, setSetting, unsetSetting, t }) {
     const snapshot = useSettings(state => state);
     const configured = snapshot.value?.contextWindow;
@@ -90,6 +122,15 @@ function ContextSizeControl({ contextWindow, useSettings, setSetting, unsetSetti
                     fontSize: 11,
                 }, children: t('contextRestore') }))] }));
 }
+function contextWindowFromProjection(useProjection) {
+    const pressure = useProjection('contextPressure');
+    return pressure?.contextWindow !== undefined && pressure.contextWindow > 0
+        ? pressure.contextWindow
+        : DEFAULT_CONTEXT_WINDOW;
+}
+function LegacyContextSizeControl({ useProjection, ...props }) {
+    return _jsx(ContextSizeControl, { ...props, contextWindow: contextWindowFromProjection(useProjection) });
+}
 function elapsedSeconds(startedAt, now) {
     return Math.max(0, Math.floor((now - startedAt) / 1_000));
 }
@@ -138,7 +179,15 @@ export function ActivityLine({ sessionId, useSession, useSessions, useProjection
                 } }), _jsx("span", { children: label }), _jsxs("span", { style: { color: 'var(--dsw-alias-label-tertiary)' }, children: ["\u00B7 ", elapsedSeconds(activity.startedAt, now), "s"] })] }));
 }
 export const inject = ['slots', 'locale', 'settingsScope'];
-/** Mount Fast inside the model selector and context size inside the meter panel. */
+/** Select a preferred slot when the host declares it, otherwise use a stable legacy composer seat. */
+export function chooseDeclaredSlot(preferred, fallback, isDeclared) {
+    return isDeclared(preferred) ? preferred : fallback;
+}
+function slotIsDeclared(ctx, slot) {
+    const registry = ctx.slots;
+    return typeof registry.spec === 'function' && registry.spec.call(ctx.slots, slot) !== undefined;
+}
+/** Mount Codex controls in the newest named seats, with legacy composer fallbacks. */
 export function apply(ctx) {
     ctx.effect(() => ctx.locale.register(NS, { en, zh }), 'codex client: dictionaries');
     const settings = ctx.settingsScope.bind({ namespace: SETTINGS_NAMESPACE });
@@ -147,20 +196,44 @@ export function apply(ctx) {
         setSetting: (field, value) => settings.set(field, value),
         unsetSetting: (field) => settings.unset(field),
     });
-    ctx.slots.inject('conversation.input.model.settings', () => ctx.slots.register({
-        name: 'conversation.input.model.settings',
-        id: 'codex-fast',
-        order: 0,
-        locale: NS,
-        inject: injected,
-    }, FastModeButton));
-    ctx.slots.inject('conversation.input.context.settings', () => ctx.slots.register({
-        name: 'conversation.input.context.settings',
-        id: 'codex-context-size',
-        order: 0,
-        locale: NS,
-        inject: injected,
-    }, ContextSizeControl));
+    const fastSlot = chooseDeclaredSlot(MODEL_SETTINGS_SLOT, FAST_FALLBACK_SLOT, slot => slotIsDeclared(ctx, slot));
+    if (fastSlot === MODEL_SETTINGS_SLOT) {
+        ctx.slots.inject(MODEL_SETTINGS_SLOT, () => ctx.slots.register({
+            name: MODEL_SETTINGS_SLOT,
+            id: 'codex-fast',
+            order: 0,
+            locale: NS,
+            inject: injected,
+        }, FastModeButton));
+    }
+    else {
+        ctx.slots.inject(FAST_FALLBACK_SLOT, () => ctx.slots.register({
+            name: FAST_FALLBACK_SLOT,
+            id: 'codex-fast-fallback',
+            order: 0,
+            locale: NS,
+            inject: injected,
+        }, FastModeFallback));
+    }
+    const contextSlot = chooseDeclaredSlot(CONTEXT_SETTINGS_SLOT, CONTEXT_FALLBACK_SLOT, slot => slotIsDeclared(ctx, slot));
+    if (contextSlot === CONTEXT_SETTINGS_SLOT) {
+        ctx.slots.inject(CONTEXT_SETTINGS_SLOT, () => ctx.slots.register({
+            name: CONTEXT_SETTINGS_SLOT,
+            id: 'codex-context-size',
+            order: 0,
+            locale: NS,
+            inject: injected,
+        }, ContextSizeControl));
+    }
+    else {
+        ctx.slots.inject(CONTEXT_FALLBACK_SLOT, () => ctx.slots.register({
+            name: CONTEXT_FALLBACK_SLOT,
+            id: 'codex-context-size-fallback',
+            order: 0,
+            locale: NS,
+            inject: injected,
+        }, LegacyContextSizeControl));
+    }
     ctx.slots.inject('conversation.composer.dock', () => ctx.slots.register({
         name: 'conversation.composer.dock',
         id: 'codex-activity',

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,9 +194,9 @@ 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 a patch.';
+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.';
 const PLAN_STATUSES = ['pending', 'in_progress', 'completed'];
 function sessionCwd(exec) {
@@ -245,7 +245,7 @@ async function applyOnePatch(ctx, file, exec, policy) {
     }
     const sourceInfo = await observedTarget(ctx, target, exec);
     const original = await ctx.fs.readText(target, exec.signal);
-    const updated = file.kind === 'delete' ? undefined : applyPatchHunks(original, file.hunks);
+    const updated = file.kind === 'delete' ? undefined : applyPatchHunks(original, file.hunks, file.path);
     if (file.kind === 'delete') {
         await deletePatchedFile(ctx, target, sourceInfo.version, exec, policy);
         return { path: file.path, operation: 'deleted' };
@@ -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/lib/types/patch.d.ts

@@ -32,5 +32,5 @@ export type PatchFile = {
 /** Parse one complete Codex patch after normalizing CRLF input to LF. */
 export declare function parsePatch(input: string): PatchFile[];
 /** Apply parsed update hunks and return LF-normalized text. */
-export declare function applyPatchHunks(original: string, hunks: readonly PatchHunk[]): string;
+export declare function applyPatchHunks(original: string, hunks: readonly PatchHunk[], label?: string): string;
 //# sourceMappingURL=patch.d.ts.map

package/lib/types/patch.js

@@ -188,16 +188,39 @@ function findSequence(lines, expected, from, endOfFile) {
     }
     return -1;
 }
+function displayPatchLine(line) {
+    if (line.length === 0)
+        return '<empty>';
+    return line.replaceAll(' ', '[space]').replaceAll('\t', '[tab]');
+}
+function formatPatchExcerpt(lines, start, count) {
+    if (lines.length === 0)
+        return '  <empty file>';
+    const first = Math.max(0, Math.min(start, lines.length - 1));
+    return lines.slice(first, first + count)
+        .map((line, offset) => `  ${first + offset + 1}: ${displayPatchLine(line)}`)
+        .join('\n');
+}
+function mismatchMessage(label, hunkIndex, expected, actual, from, endOfFile) {
+    const expectedPreview = expected.slice(0, 12)
+        .map((line, index) => `  ${index + 1}: ${displayPatchLine(line)}`)
+        .join('\n');
+    const expectedSuffix = expected.length > 12 ? '\n  ...' : '';
+    const excerptStart = endOfFile ? Math.max(0, actual.length - 6) : Math.max(0, from - 2);
+    const markerHint = expected.some(wanted => wanted.length > 0 && actual.includes(`-${wanted}`))
+        ? '\nHint: if a source line starts with a patch marker, repeat that marker after the operation marker; for example, `-- item` deletes the source line `- item`.'
+        : '';
+    return `could not find expected lines in ${label} hunk ${hunkIndex + 1} (search starts at line ${from + 1})\nExpected:\n${expectedPreview}${expectedSuffix}\nFile excerpt:\n${formatPatchExcerpt(actual, excerptStart, 10)}${markerHint}`;
+}
 /** Apply parsed update hunks and return LF-normalized text. */
-export function applyPatchHunks(original, hunks) {
+export function applyPatchHunks(original, hunks, label = 'file') {
     const value = splitText(original.replaceAll('\r\n', '\n'));
     let cursor = 0;
-    for (const hunk of hunks) {
+    for (const [hunkIndex, hunk] of hunks.entries()) {
         const expected = hunk.lines.filter(line => line.kind !== 'add').map(line => line.text);
         const start = findSequence(value.lines, expected, cursor, hunk.endOfFile);
         if (start < 0) {
-            const detail = expected.join('\n');
-            invalid(`could not find expected lines${detail.length === 0 ? '' : `:\n${detail}`}`);
+            invalid(mismatchMessage(label, hunkIndex, expected, value.lines, cursor, hunk.endOfFile));
         }
         const replacement = hunk.lines.filter(line => line.kind !== 'delete').map(line => line.text);
         value.lines.splice(start, expected.length, ...replacement);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shuind/dsh-codex-harness",
-  "version": "0.1.20",
+  "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",
@@ -69,8 +69,7 @@
         "@deepseek-ai/dsh-client-locale",
         "@deepseek-ai/dsh-client-runtime",
         "@deepseek-ai/dsh-client-ui-conversation",
-        "@deepseek-ai/dsh-client-ui-settings",
-        "@deepseek-ai/dsh-client-ui-slots"
+        "@deepseek-ai/dsh-client-ui-settings"
       ],
       "platform": "web"
     }
@@ -90,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",
@@ -100,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": {
@@ -133,6 +134,9 @@
     "@deepseek-ai/dsh-invariants": {
       "optional": true
     },
+    "@deepseek-ai/dsh-jobs": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-llm": {
       "optional": true
     },
@@ -163,6 +167,9 @@
     "@deepseek-ai/dsh-terminal": {
       "optional": true
     },
+    "@deepseek-ai/dsh-tool-jobs": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-tools": {
       "optional": true
     }
@@ -178,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",
@@ -188,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