@shuind/dsh-codex-harness 0.1.15 → 0.1.16

package/README.md

@@ -10,28 +10,8 @@
 - **Fast**：仅在 Codex preset 的模型选择菜单中显示，开启后向 Responses 请求发送 `service_tier: "priority"`。
 - **远程搜索与压缩**：OpenAI Responses 请求默认优先使用 hosted `web_search` 和 `/responses/compact`；失败时回退到 DSH 的本地实现。
 - **上下文容量**：在 Web 中设置 `1K`–`1000K` tokens，设置值作用于下一次请求。
+- **活动状态**：Codex 等待模型响应或进行上下文压缩时，在输入框上方显示对应状态和耗时，让长时间 Deep Diving 不再像卡住。
 
-## 可选协作提示词（私货）
-
-这段提示词默认关闭，不会注入系统提示词。需要时，在自定义 `agent.cordis.yml` 中开启：
-
-```yaml
-- id: codex-tools
-  name: '@shuind/dsh-codex-harness'
-  config:
-    collaborationPrompt: true
-```
-
-开启后，Codex preset 会在系统提示词中注入以下协作要求：
-
-```text
-Ask, align, and clarify whenever uncertainty, assumptions, tradeoffs, or decisions could materially affect the outcome.
-Understand the user's full picture, align it with your own, and leave no hidden assumptions or gaps.
-Keep only the essential logic and core actions. There's no need to explain or test what was removed or why something wasn't done.
-Convey enough valuable information with as few words as possible. Stay focused on the end goal.
-Solve problems by thinking from first principles and at a higher level.
-Make things as effortless as possible for the user.
-```
 ## 安装
 
 ```sh
@@ -72,16 +52,68 @@ Fast 设置保存在 `codex` 命名空间，只对 Codex preset 生效。
 
 上下文容量使用整数 K tokens，范围为 `1K` 到 `1000K`。实际可用上限仍取决于模型和中转站支持情况。
 
+### 活动状态
+
+Codex 等待模型首个输出时，Web 输入框上方会显示 `正在等待模型响应... · Ns`；开始上下文压缩后会切换为 `正在压缩上下文... · Ns`。收到模型输出、压缩结束或下一轮开始后自动隐藏。该状态由 Host 的 `sessionProjections` 投影驱动，因此本地压缩和远程 `/responses/compact` 都会显示同一种状态。
+
+如果当前 DSH 组合没有加载 projection 服务，插件会跳过注册，客户端也会自动隐藏这行，不影响普通会话。
+
+## 随包提供的 Codex preset
+
+安装插件后，首次启动对应的 DSH profile 时，插件会把完整 preset 从随包提供的 `presets/codex` 安装到 `${DSH_HOME:-$HOME/.dsh}/.agent-presets/codex/`；如果你已经创建了同名 preset，插件会保留你的文件。普通用户不需要自己创建 preset。
+
+在 Web 的 **Agent 预设** 中选择 **Codex**，再新建会话即可使用随包提供的 Codex 工具、网页搜索、远程压缩和 Skills 组合。Fast、思考强度、GPT 图片输入和上下文容量可以在对应的设置位置配置。
+
 ## 自定义 preset
 
-在自定义 `agent.cordis.yml` 中挂载 Codex 工具层：
+只有在想自己组合工具、提示词，或修改插件配置时才需要自定义 preset。自定义 preset 放在 `${DSH_HOME:-$HOME/.dsh}/.agent-presets/<id>/` 目录中。
+
+### 示例：创建一个带协作提示词的 Codex preset
+
+例如创建目录 `${DSH_HOME:-$HOME/.dsh}/.agent-presets/my-codex/`，并写入 `agent.cordis.yml`：
+
+```yaml
+- id: persona
+  name: '@deepseek-ai/dsh-persona'
+  config:
+    text: 你是一个使用 DSH 工具工作的 Codex 编程助手。
+
+- id: codex-tools
+  name: '@shuind/dsh-codex-harness'
+  config:
+    collaborationPrompt: true
+```
+
+再写入 `preset.yml`，让 Web 中显示更清晰的名称：
+
+```yaml
+name: My Codex
+description: 使用 Codex 工具并开启可选协作提示词。
+order: 10
+```
+
+然后在 Web 的 **Agent 预设** 中选择 `My Codex`，再新建会话。这个 preset 会加载 Codex 工具，并开启协作提示词；网页搜索、远程压缩和 Skills 等其他功能需要在同一个 `agent.cordis.yml` 中按需添加。
+
+### 可选协作提示词（私货）
+
+这段提示词默认关闭，不会注入系统提示词。需要时，在自定义 `agent.cordis.yml` 中开启：
 
 ```yaml
 - id: codex-tools
   name: '@shuind/dsh-codex-harness'
+  config:
+    collaborationPrompt: true
 ```
 
-如果需要保留 Codex preset 的完整工具、搜索、压缩和 Skills 组合，建议直接使用随包提供的 `presets/codex`。
+开启后，Codex preset 会在系统提示词中注入以下协作要求：
+
+```text
+Ask, align, and clarify first. Try your best to understand the user's full picture.
+Keep only the essential logic and core actions. There's no need to explain or test what was removed or why something wasn't done.
+Convey enough valuable information with as few words as possible. Stay focused on the end goal.
+Solve problems by thinking from first principles and at a higher level.
+Make things as effortless as possible for the user.
+```
 
 ## 注意事项
 

package/lib/client.js

@@ -398,15 +398,20 @@ window.__ModuleLoader__.load({
 			exports.jsxs = q;
 		}));
 		//#endregion
-		//#region lib/types/context.js
-		var import_jsx_runtime = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
+		//#region node_modules/.pnpm/react@18.3.1/node_modules/react/jsx-runtime.js
+		var require_jsx_runtime = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 			module.exports = require_react_jsx_runtime_production_min();
-		})))();
+		}));
+		//#endregion
+		//#region lib/types/context.js
+		var import_react = require_react();
+		var import_jsx_runtime = require_jsx_runtime();
 		/** User-selectable Codex context controls use whole K-token units. */
 		const CODEX_CONTEXT_UNIT = 1e3;
 		const CODEX_CONTEXT_MAX = 1e6;
 		//#endregion
 		//#region lib/types/client/index.js
+		/** Browser controls for the Codex request settings mounted by the Host plugin. */
 		const NS = "codex";
 		const SETTINGS_NAMESPACE = "codex";
 		const en = {
@@ -417,7 +422,9 @@ window.__ModuleLoader__.load({
 			fastStateOff: "Off",
 			contextSize: "Context size",
 			contextSizeDescription: "Next request capacity in K tokens. The meter above is current.",
-			contextRestore: "Restore model default"
+			contextRestore: "Restore model default",
+			activityCompacting: "Compacting context...",
+			activityAwaitingModel: "Waiting for model response..."
 		};
 		const zh = {
 			fast: "Fast",
@@ -427,7 +434,9 @@ window.__ModuleLoader__.load({
 			fastStateOff: "关",
 			contextSize: "上下文大小",
 			contextSizeDescription: "设置下次请求的上下文容量，单位为 K tokens；上方是当前请求。",
-			contextRestore: "恢复模型默认值"
+			contextRestore: "恢复模型默认值",
+			activityCompacting: "正在压缩上下文...",
+			activityAwaitingModel: "正在等待模型响应..."
 		};
 		function FastModeButton({ sessionId, useSessions, useSettings, setSetting, t }) {
 			const agentPreset = useSessions((state) => state.byId[sessionId]?.agentPreset);
@@ -588,6 +597,60 @@ window.__ModuleLoader__.load({
 				]
 			});
 		}
+		function elapsedSeconds(startedAt, now) {
+			return Math.max(0, Math.floor((now - startedAt) / 1e3));
+		}
+		function ActivityLine({ sessionId, useSessions, useProjection, t }) {
+			const agentPreset = useSessions((state) => state.byId[sessionId]?.agentPreset);
+			const activity = useProjection("codexActivity");
+			const [now, setNow] = (0, import_react.useState)(() => Date.now());
+			(0, import_react.useEffect)(() => {
+				if (agentPreset !== "codex" || activity === void 0 || activity === null) return void 0;
+				setNow(Date.now());
+				const timer = setInterval(() => {
+					setNow(Date.now());
+				}, 1e3);
+				return () => clearInterval(timer);
+			}, [agentPreset, activity?.startedAt]);
+			if (agentPreset !== "codex" || activity === void 0 || activity === null) return null;
+			const label = activity.activity === "awaiting-model" ? t("activityAwaitingModel") : t("activityCompacting");
+			return (0, import_jsx_runtime.jsxs)("div", {
+				id: "codex-activity",
+				role: "status",
+				"aria-live": "polite",
+				style: {
+					display: "flex",
+					alignItems: "center",
+					gap: 7,
+					minHeight: 28,
+					padding: "4px 10px",
+					color: "var(--dsw-alias-label-secondary)",
+					fontSize: 12,
+					lineHeight: "20px"
+				},
+				children: [
+					(0, import_jsx_runtime.jsx)("span", {
+						"aria-hidden": "true",
+						style: {
+							width: 7,
+							height: 7,
+							flex: "0 0 auto",
+							borderRadius: "50%",
+							background: "var(--dsw-static-blue-500)"
+						}
+					}),
+					(0, import_jsx_runtime.jsx)("span", { children: label }),
+					(0, import_jsx_runtime.jsxs)("span", {
+						style: { color: "var(--dsw-alias-label-tertiary)" },
+						children: [
+							"· ",
+							elapsedSeconds(activity.startedAt, now),
+							"s"
+						]
+					})
+				]
+			});
+		}
 		const inject = [
 			"slots",
 			"locale",
@@ -619,12 +682,19 @@ window.__ModuleLoader__.load({
 				locale: NS,
 				inject: injected
 			}, ContextSizeControl));
+			ctx.slots.inject("conversation.input.dock", () => ctx.slots.register({
+				name: "conversation.input.dock",
+				id: "codex-activity",
+				order: 5,
+				locale: NS
+			}, ActivityLine));
 		}
 		var client_default = {
 			inject,
 			apply
 		};
 		//#endregion
+		exports.ActivityLine = ActivityLine;
 		exports.apply = apply;
 		exports.default = client_default;
 		exports.inject = inject;

package/lib/index.js

@@ -5,10 +5,12 @@ import { randomBytes } from "node:crypto";
 import { resolve } from "node:path";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { z as z$1 } from "zod";
 //#region lib/types/context.js
 const CODEX_CONTEXT_MAX = 1e6;
-String.raw`start: begin_patch hunk+ end_patch
+String.raw`start: begin_patch environment_id? hunk+ end_patch
 begin_patch: "*** Begin Patch" LF
+environment_id: "*** Environment ID: " filename LF
 end_patch: "*** End Patch" LF?
 hunk: add_hunk | delete_hunk | update_hunk
 add_hunk: "*** Add File: " filename LF add_line+
@@ -30,6 +32,15 @@ function isFileHeader(line) {
 	const trimmed = line.trim();
 	return trimmed.startsWith("*** Add File: ") || trimmed.startsWith("*** Delete File: ") || trimmed.startsWith("*** Update File: ");
 }
+const ENVIRONMENT_ID_MARKER = "*** Environment ID:";
+function unwrapHeredoc(input) {
+	const normalized = input.replaceAll("\r\n", "\n").trim();
+	const lines = normalized.split("\n");
+	const first = lines[0]?.trim();
+	const last = lines.at(-1)?.trim();
+	if (lines.length >= 4 && (first === "<<EOF" || first === "<<'EOF'" || first === "<<\"EOF\"") && last === "EOF") return lines.slice(1, -1).join("\n").trim();
+	return normalized;
+}
 function pathFrom(line, prefix) {
 	const path = line.slice(prefix.length).trim();
 	if (path.length === 0) invalid(`${prefix.trim()} requires a file path`);
@@ -44,12 +55,17 @@ function isPotentialChangeMarker(line) {
 }
 /** Parse one complete Codex patch after normalizing CRLF input to LF. */
 function parsePatch(input) {
-	const lines = input.replaceAll("\r\n", "\n").trim().split("\n");
+	const lines = unwrapHeredoc(input).split("\n");
 	if (lines[0]?.trim() !== "*** Begin Patch") invalid("input must start with \"*** Begin Patch\"");
 	if (lines.at(-1)?.trim() !== "*** End Patch") invalid("input must end with \"*** End Patch\"");
 	const files = [];
 	let index = 1;
 	const end = lines.length - 1;
+	if (lines[index]?.trim().startsWith(ENVIRONMENT_ID_MARKER) === true) {
+		if (lines[index].trim().slice(19).trim().length === 0) invalid("environment id cannot be empty");
+		index++;
+		if (lines[index]?.trim().startsWith(ENVIRONMENT_ID_MARKER) === true) invalid("environment id cannot be specified more than once");
+	}
 	while (index < end) {
 		const header = lines[index++]?.trim();
 		if (header === void 0) invalid("unexpected end of input");
@@ -183,6 +199,12 @@ function applyPatchHunks(original, hunks) {
 //#region lib/types/exec.js
 /** Codex `exec_command` and `write_stdin` execution over dsh capability seams. */
 const STATES = /* @__PURE__ */ new WeakMap();
+const MIN_YIELD_TIME_MS = 250;
+const MIN_EMPTY_YIELD_TIME_MS = 5e3;
+const MAX_YIELD_TIME_MS = 3e4;
+const MAX_EMPTY_YIELD_TIME_MS = 3e5;
+const DEFAULT_OUTPUT_TOKENS = 1e4;
+const APPROX_BYTES_PER_TOKEN = 4;
 function stateFor(agent) {
 	const current = STATES.get(agent);
 	if (current !== void 0) return current;
@@ -196,13 +218,13 @@ function stateFor(agent) {
 function positiveFinite(name, value) {
 	if (value !== void 0 && (!Number.isFinite(value) || value < 0)) throw new Error(`${name} must be a non-negative finite number`);
 }
-function waitMs(value, fallback) {
-	return Math.max(0, Math.min(3e4, Math.trunc(value ?? fallback)));
+function normalizeWaitMs(value, fallback, empty = false) {
+	return Math.max(empty ? MIN_EMPTY_YIELD_TIME_MS : MIN_YIELD_TIME_MS, Math.min(empty ? MAX_EMPTY_YIELD_TIME_MS : MAX_YIELD_TIME_MS, Math.trunc(value ?? fallback)));
 }
 function outputLimit(maxOutputBytes, maxOutputTokens) {
-	if (maxOutputTokens === void 0) return maxOutputBytes;
-	positiveFinite("max_output_tokens", maxOutputTokens);
-	return Math.max(1, Math.min(maxOutputBytes, Math.trunc(maxOutputTokens * 4)));
+	const tokens = maxOutputTokens ?? DEFAULT_OUTPUT_TOKENS;
+	if (maxOutputTokens !== void 0) positiveFinite("max_output_tokens", maxOutputTokens);
+	return Math.max(1, Math.min(maxOutputBytes, Math.trunc(tokens * APPROX_BYTES_PER_TOKEN)));
 }
 function limitOutput(text, maxBytes) {
 	if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
@@ -269,6 +291,12 @@ async function waitForShell(process, ms, signal) {
 	if (signal.aborted) signal.throwIfAborted();
 	return completed === true || process.status !== "running";
 }
+/** Stop a pipe-backed session when the current Codex tool is cancelled. */
+async function stopShellOnAbort(process, signal) {
+	if (!signal.aborted || process.status !== "running") return;
+	process.kill();
+	await process.done;
+}
 function allocateSession(agent, session) {
 	const state = stateFor(agent);
 	const id = ++state.nextId;
@@ -304,21 +332,29 @@ async function runExecCommand(ctx, args, exec, config) {
 			...workdir === void 0 ? {} : { cwd: workdir }
 		};
 		const spawned = await terminals.spawn(agent, spawnRequest, exec.signal);
-		const sendRequest = {
-			text: commandFor(args),
-			submit: true,
-			waitMs: waitMs(args.yield_time_ms, config.defaultYieldTimeMs),
-			signal: exec.signal
-		};
-		const result = await terminals.startSend(agent, spawned.sessionId, sendRequest).done;
-		const output = terminalResult(result, maxBytes, startedAt);
-		if (result.sessionStatus.kind === "running") output.session_id = allocateSession(agent, {
-			kind: "terminal",
-			owner: agent,
-			id: spawned.sessionId
-		});
-		else await terminals.kill(agent, spawned.sessionId, "Codex command exited");
-		return output;
+		let retained = false;
+		let closeReason = "Codex command failed";
+		try {
+			const sendRequest = {
+				text: commandFor(args),
+				submit: true,
+				waitMs: normalizeWaitMs(args.yield_time_ms, config.defaultYieldTimeMs),
+				signal: exec.signal
+			};
+			const result = await terminals.startSend(agent, spawned.sessionId, sendRequest).done;
+			const output = terminalResult(result, maxBytes, startedAt);
+			if (result.sessionStatus.kind === "running") {
+				output.session_id = allocateSession(agent, {
+					kind: "terminal",
+					owner: agent,
+					id: spawned.sessionId
+				});
+				retained = true;
+			} else closeReason = "Codex command exited";
+			return output;
+		} finally {
+			if (!retained) await terminals.kill(agent, spawned.sessionId, closeReason);
+		}
 	}
 	const policy = ctx.get("sandboxPolicy")?.resolve(exec.agent === void 0 ? {} : { session: exec.agent.session });
 	const dshEnv = ctx.get("shellEnv")?.collect(exec);
@@ -328,35 +364,40 @@ 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));
-	const completed = await waitForShell(process, waitMs(args.yield_time_ms, config.defaultYieldTimeMs), exec.signal);
-	const output = readShellOutput(process.readOutput(), maxBytes);
-	if (!completed || process.status === "running") {
-		if (exec.agent === void 0) {
-			process.kill();
-			await process.done;
+	try {
+		await waitForShell(process, normalizeWaitMs(args.yield_time_ms, config.defaultYieldTimeMs), exec.signal);
+		const output = readShellOutput(process.readOutput(), maxBytes);
+		if (process.status === "running") {
+			if (exec.agent === void 0) {
+				process.kill();
+				await process.done;
+				return withChunkId({
+					wall_time_seconds: (performance.now() - startedAt) / 1e3,
+					output: readShellOutput(process.readOutput(), maxBytes)
+				});
+			}
 			return withChunkId({
 				wall_time_seconds: (performance.now() - startedAt) / 1e3,
-				output: readShellOutput(process.readOutput(), maxBytes)
+				output,
+				session_id: allocateSession(exec.agent, {
+					kind: "shell",
+					process
+				})
 			});
 		}
 		return withChunkId({
 			wall_time_seconds: (performance.now() - startedAt) / 1e3,
 			output,
-			session_id: allocateSession(exec.agent, {
-				kind: "shell",
-				process
-			})
+			...process.exitCode === null ? {} : { exit_code: process.exitCode }
 		});
+	} finally {
+		await stopShellOnAbort(process, exec.signal);
 	}
-	return withChunkId({
-		wall_time_seconds: (performance.now() - startedAt) / 1e3,
-		output,
-		...process.exitCode === null ? {} : { exit_code: process.exitCode }
-	});
 }
 /** Poll or write to one session returned by {@link runExecCommand}. */
 async function runWriteStdin(ctx, args, exec, config) {
@@ -370,38 +411,57 @@ async function runWriteStdin(ctx, args, exec, config) {
 	const chars = args.chars ?? "";
 	if (session.kind === "shell") {
 		if (chars.length > 0) throw new Error("this unified exec session uses pipes and does not accept stdin; rerun exec_command with tty=true");
-		const completed = await waitForShell(session.process, waitMs(args.yield_time_ms, config.pollYieldTimeMs), exec.signal);
-		const output = readShellOutput(session.process.readOutput(), maxBytes);
-		if (completed && session.process.status !== "running") {
-			forgetSession(agent, args.session_id);
+		try {
+			await waitForShell(session.process, normalizeWaitMs(args.yield_time_ms, config.pollYieldTimeMs, true), exec.signal);
+			const output = readShellOutput(session.process.readOutput(), maxBytes);
+			if (session.process.status !== "running") {
+				forgetSession(agent, args.session_id);
+				return withChunkId({
+					wall_time_seconds: (performance.now() - startedAt) / 1e3,
+					output,
+					...session.process.exitCode === null ? {} : { exit_code: session.process.exitCode }
+				});
+			}
 			return withChunkId({
 				wall_time_seconds: (performance.now() - startedAt) / 1e3,
 				output,
-				...session.process.exitCode === null ? {} : { exit_code: session.process.exitCode }
+				session_id: args.session_id
 			});
+		} finally {
+			if (exec.signal.aborted) try {
+				await stopShellOnAbort(session.process, exec.signal);
+			} finally {
+				forgetSession(agent, args.session_id);
+			}
 		}
-		return withChunkId({
-			wall_time_seconds: (performance.now() - startedAt) / 1e3,
-			output,
-			session_id: args.session_id
-		});
 	}
 	const terminals = ctx.get("terminals");
 	if (terminals === void 0) throw new Error("the dsh terminal capability is no longer available");
 	const sendRequest = {
 		text: chars,
 		submit: false,
-		waitMs: waitMs(args.yield_time_ms, chars.length > 0 ? config.writeYieldTimeMs : config.pollYieldTimeMs),
+		waitMs: normalizeWaitMs(args.yield_time_ms, chars.length > 0 ? config.writeYieldTimeMs : config.pollYieldTimeMs, chars.length === 0),
 		signal: exec.signal
 	};
-	const result = await terminals.startSend(agent, session.id, sendRequest).done;
-	const output = terminalResult(result, maxBytes, startedAt);
-	if (result.sessionStatus.kind === "running") output.session_id = args.session_id;
-	else {
-		forgetSession(agent, args.session_id);
-		await terminals.kill(agent, session.id, "Codex command exited");
+	let retained = false;
+	let closeReason = "Codex command failed";
+	try {
+		const result = await terminals.startSend(agent, session.id, sendRequest).done;
+		const output = terminalResult(result, maxBytes, startedAt);
+		if (result.sessionStatus.kind === "running") {
+			output.session_id = args.session_id;
+			retained = true;
+		} else {
+			closeReason = "Codex command exited";
+			forgetSession(agent, args.session_id);
+		}
+		return output;
+	} finally {
+		if (!retained) {
+			forgetSession(agent, args.session_id);
+			await terminals.kill(agent, session.id, closeReason);
+		}
 	}
-	return output;
 }
 //#endregion
 //#region lib/types/remote.js
@@ -707,6 +767,54 @@ function remoteCompactStream(ctx, options, next) {
 	})();
 }
 //#endregion
+//#region lib/types/activity.js
+/** Host-side activity projection for the Codex compaction status line. */
+/** Persisted and wire shape of the Codex activity value. */
+const codexActivitySchema = z$1.union([
+	z$1.object({
+		activity: z$1.literal("compaction"),
+		startedAt: z$1.number().int().nonnegative()
+	}),
+	z$1.object({
+		activity: z$1.literal("awaiting-model"),
+		startedAt: z$1.number().int().nonnegative()
+	}),
+	z$1.null()
+]);
+/** Pure event fold, exported so its reset and reference-stability rules can be tested directly. */
+function applyCodexActivity(state, event) {
+	if (event.type === "compaction/start") return {
+		activity: "compaction",
+		startedAt: event.time
+	};
+	if (event.type === "step/start" || event.type === "llm/retry-started") return {
+		activity: "awaiting-model",
+		startedAt: event.time
+	};
+	if (event.type === "turn/start" || event.type === "turn/end" || event.type === "compaction/end") return null;
+	if (state?.activity === "awaiting-model" && (event.type === "llm/retry" || event.type === "assistant/chunk" || event.type === "assistant/message" || event.type === "step/end")) return null;
+	return state;
+}
+const codexActivityProjection = {
+	key: "codexActivity",
+	stateSchema: codexActivitySchema,
+	init: () => null,
+	apply: applyCodexActivity,
+	wire: {
+		viewSchema: codexActivitySchema,
+		view: (state) => state
+	},
+	schema: codexActivitySchema,
+	view: (state) => state,
+	stateVersion: 1
+};
+/** Register the optional activity unit without requiring the projection seam in every assembly. */
+function registerCodexActivityProjection(ctx) {
+	ctx.inject(["sessionProjections"], (projectionCtx) => {
+		projectionCtx.sessionProjections.register(codexActivityProjection);
+	});
+}
+//#endregion
 //#region lib/types/index.js
 /** Codex-compatible prompt overlay and core tools for a dsh agent preset. */
 const name = "codex";
@@ -882,8 +990,7 @@ const CODEX_BASE_PROMPT = String.raw`You are Codex, based on {{model}}. You are
 `;
 const CODEX_COLLABORATION_PROMPT = String.raw`## Collaboration
 
-- Ask, align, and clarify whenever uncertainty, assumptions, tradeoffs, or decisions could materially affect the outcome.
-- Understand the user's full picture, align it with your own, and leave no hidden assumptions or gaps.
+- Ask, align, and clarify first. Try your best to understand the user's full picture.
 - Keep only the essential logic and core actions. There's no need to explain or test what was removed or why something wasn't done.
 - Convey enough valuable information with as few words as possible. Stay focused on the end goal.
 - Solve problems by thinking from first principles and at a higher level.
@@ -1267,6 +1374,7 @@ function apply(ctx, config = {}) {
 	};
 	if (ctx.fs.sandboxMode !== void 0 && ctx.get("sandboxPolicy") === void 0) throw new Error("codex: a sandboxing filesystem requires ctx.sandboxPolicy");
 	watchConfiguredGptModels(ctx);
+	registerCodexActivityProjection(ctx);
 	const codexSettings = installCodexSettings(ctx);
 	ctx.on("agent/request", async (_payload, next) => {
 		return applyCodexRequestSettings(await next(), codexSettings.current());

package/lib/types/activity-types.d.ts

@@ -0,0 +1,6 @@
+/** Pure client/host-shared type for the Codex activity projection value. */
+export type CodexActivity = {
+    activity: 'compaction' | 'awaiting-model';
+    startedAt: number;
+};
+//# sourceMappingURL=activity-types.d.ts.map

package/lib/types/activity-types.js

@@ -0,0 +1,3 @@
+/** Pure client/host-shared type for the Codex activity projection value. */
+export {};
+//# sourceMappingURL=activity-types.js.map

package/lib/types/activity.d.ts

@@ -0,0 +1,32 @@
+/** Host-side activity projection for the Codex compaction status line. */
+import type { Context } from '@deepseek-ai/cordis';
+import { z, type ZodType } from 'zod';
+import type { CodexActivity } from './activity-types.ts';
+export type { CodexActivity } from './activity-types.ts';
+/** The only long-running Codex activity currently surfaced to the client. */
+export type CodexActivityState = CodexActivity | null;
+/** Minimal event shape needed by this projection; no compaction package import is required. */
+export interface CodexActivityEvent {
+    type: string;
+    time: number;
+}
+/** Persisted and wire shape of the Codex activity value. */
+export declare const codexActivitySchema: ZodType<CodexActivityState>;
+/** Pure event fold, exported so its reset and reference-stability rules can be tested directly. */
+export declare function applyCodexActivity(state: CodexActivityState, event: CodexActivityEvent): CodexActivityState;
+export declare const codexActivityProjection: {
+    readonly key: "codexActivity";
+    readonly stateSchema: z.ZodType<CodexActivityState, unknown, z.core.$ZodTypeInternals<CodexActivityState, unknown>>;
+    readonly init: () => CodexActivityState;
+    readonly apply: typeof applyCodexActivity;
+    readonly wire: {
+        readonly viewSchema: z.ZodType<CodexActivityState, unknown, z.core.$ZodTypeInternals<CodexActivityState, unknown>>;
+        readonly view: (state: CodexActivityState) => CodexActivityState;
+    };
+    readonly schema: z.ZodType<CodexActivityState, unknown, z.core.$ZodTypeInternals<CodexActivityState, unknown>>;
+    readonly view: (state: CodexActivityState) => CodexActivityState;
+    readonly stateVersion: 1;
+};
+/** Register the optional activity unit without requiring the projection seam in every assembly. */
+export declare function registerCodexActivityProjection(ctx: Context): void;
+//# sourceMappingURL=activity.d.ts.map

package/lib/types/activity.js

@@ -0,0 +1,53 @@
+/** Host-side activity projection for the Codex compaction status line. */
+import { z } from 'zod';
+/** Persisted and wire shape of the Codex activity value. */
+export const codexActivitySchema = z.union([
+    z.object({
+        activity: z.literal('compaction'),
+        startedAt: z.number().int().nonnegative(),
+    }),
+    z.object({
+        activity: z.literal('awaiting-model'),
+        startedAt: z.number().int().nonnegative(),
+    }),
+    z.null(),
+]);
+/** Pure event fold, exported so its reset and reference-stability rules can be tested directly. */
+export function applyCodexActivity(state, event) {
+    if (event.type === 'compaction/start')
+        return { activity: 'compaction', startedAt: event.time };
+    if (event.type === 'step/start' || event.type === 'llm/retry-started') {
+        return { activity: 'awaiting-model', startedAt: event.time };
+    }
+    if (event.type === 'turn/start' || event.type === 'turn/end' || event.type === 'compaction/end')
+        return null;
+    if (state?.activity === 'awaiting-model'
+        && (event.type === 'llm/retry'
+            || event.type === 'assistant/chunk'
+            || event.type === 'assistant/message'
+            || event.type === 'step/end'))
+        return null;
+    return state;
+}
+export const codexActivityProjection = {
+    key: 'codexActivity',
+    stateSchema: codexActivitySchema,
+    init: () => null,
+    apply: applyCodexActivity,
+    wire: {
+        viewSchema: codexActivitySchema,
+        view: (state) => state,
+    },
+    // Keep the old projection contract working for DSH bundles that predate
+    // the `stateSchema`/`wire` split.
+    schema: codexActivitySchema,
+    view: (state) => state,
+    stateVersion: 1,
+};
+/** Register the optional activity unit without requiring the projection seam in every assembly. */
+export function registerCodexActivityProjection(ctx) {
+    ctx.inject(['sessionProjections'], (projectionCtx) => {
+        projectionCtx.sessionProjections.register(codexActivityProjection);
+    });
+}
+//# sourceMappingURL=activity.js.map

package/lib/types/client/index.d.ts

@@ -1,4 +1,5 @@
 /** Browser controls for the Codex request settings mounted by the Host plugin. */
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
 import type { Context } from '@deepseek-ai/cordis';
 declare const en: {
     readonly fast: "Fast mode";
@@ -9,6 +10,8 @@ declare const en: {
     readonly contextSize: "Context size";
     readonly contextSizeDescription: "Next request capacity in K tokens. The meter above is current.";
     readonly contextRestore: "Restore model default";
+    readonly activityCompacting: "Compacting context...";
+    readonly activityAwaitingModel: "Waiting for model response...";
 };
 type CodexKey = keyof typeof en;
 declare module '@deepseek-ai/dsh-client-ui-slots' {
@@ -29,6 +32,8 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
         };
     }
 }
+type ActivityProps = PropsRuntime<'conversation.input.dock'> & PropsLocale<'codex'>;
+export declare function ActivityLine({ sessionId, 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. */
 export declare function apply(ctx: Context): void;

package/lib/types/client/index.js

@@ -1,4 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** Browser controls for the Codex request settings mounted by the Host plugin. */
+import { useEffect, useState } from 'react';
 import { CODEX_CONTEXT_MAX, CODEX_CONTEXT_UNIT, CODEX_PRESET_ID } from "../context.js";
 const NS = 'codex';
 const SETTINGS_NAMESPACE = 'codex';
@@ -11,6 +13,8 @@ const en = {
     contextSize: 'Context size',
     contextSizeDescription: 'Next request capacity in K tokens. The meter above is current.',
     contextRestore: 'Restore model default',
+    activityCompacting: 'Compacting context...',
+    activityAwaitingModel: 'Waiting for model response...',
 };
 const zh = {
     fast: 'Fast',
@@ -21,6 +25,8 @@ const zh = {
     contextSize: '上下文大小',
     contextSizeDescription: '设置下次请求的上下文容量，单位为 K tokens；上方是当前请求。',
     contextRestore: '恢复模型默认值',
+    activityCompacting: '正在压缩上下文...',
+    activityAwaitingModel: '正在等待模型响应...',
 };
 function FastModeButton({ sessionId, useSessions, useSettings, setSetting, t }) {
     const agentPreset = useSessions(state => state.byId[sessionId]?.agentPreset);
@@ -83,6 +89,44 @@ function ContextSizeControl({ contextWindow, useSettings, setSetting, unsetSetti
                     fontSize: 11,
                 }, children: t('contextRestore') }))] }));
 }
+function elapsedSeconds(startedAt, now) {
+    return Math.max(0, Math.floor((now - startedAt) / 1_000));
+}
+export function ActivityLine({ sessionId, useSessions, useProjection, t }) {
+    const agentPreset = useSessions(state => state.byId[sessionId]?.agentPreset);
+    // Keep the projection seam optional: this package must still load when the
+    // host has no session-projection registry or has not carried this key.
+    const activity = useProjection('codexActivity');
+    const [now, setNow] = useState(() => Date.now());
+    useEffect(() => {
+        if (agentPreset !== CODEX_PRESET_ID || activity === undefined || activity === null)
+            return undefined;
+        setNow(Date.now());
+        const timer = setInterval(() => { setNow(Date.now()); }, 1_000);
+        return () => clearInterval(timer);
+    }, [agentPreset, activity?.startedAt]);
+    if (agentPreset !== CODEX_PRESET_ID || activity === undefined || activity === null)
+        return null;
+    const label = activity.activity === 'awaiting-model'
+        ? t('activityAwaitingModel')
+        : t('activityCompacting');
+    return (_jsxs("div", { id: "codex-activity", role: "status", "aria-live": "polite", style: {
+            display: 'flex',
+            alignItems: 'center',
+            gap: 7,
+            minHeight: 28,
+            padding: '4px 10px',
+            color: 'var(--dsw-alias-label-secondary)',
+            fontSize: 12,
+            lineHeight: '20px',
+        }, children: [_jsx("span", { "aria-hidden": "true", style: {
+                    width: 7,
+                    height: 7,
+                    flex: '0 0 auto',
+                    borderRadius: '50%',
+                    background: 'var(--dsw-static-blue-500)',
+                } }), _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. */
 export function apply(ctx) {
@@ -107,6 +151,12 @@ export function apply(ctx) {
         locale: NS,
         inject: injected,
     }, ContextSizeControl));
+    ctx.slots.inject('conversation.input.dock', () => ctx.slots.register({
+        name: 'conversation.input.dock',
+        id: 'codex-activity',
+        order: 5,
+        locale: NS,
+    }, ActivityLine));
 }
 export default { inject, apply };
 //# sourceMappingURL=index.js.map

package/lib/types/exec.d.ts

@@ -27,6 +27,7 @@ export interface ExecResult {
     exit_code?: number;
     original_token_count?: number;
 }
+export declare function normalizeWaitMs(value: number | undefined, fallback: number, empty?: boolean): number;
 /** Render the ordinary Responses tool result text used by Codex's unified exec tools. */
 export declare function renderExecResult(result: ExecResult): string;
 /** Execute one Codex command through the configured pipe or PTY capability. */

package/lib/types/exec.js

@@ -2,6 +2,12 @@
 import { randomBytes } from 'node:crypto';
 import { resolve as resolvePath } from 'node:path';
 const STATES = new WeakMap();
+const MIN_YIELD_TIME_MS = 250;
+const MIN_EMPTY_YIELD_TIME_MS = 5_000;
+const MAX_YIELD_TIME_MS = 30_000;
+const MAX_EMPTY_YIELD_TIME_MS = 300_000;
+const DEFAULT_OUTPUT_TOKENS = 10_000;
+const APPROX_BYTES_PER_TOKEN = 4;
 function stateFor(agent) {
     const current = STATES.get(agent);
     if (current !== undefined)
@@ -15,14 +21,16 @@ function positiveFinite(name, value) {
         throw new Error(`${name} must be a non-negative finite number`);
     }
 }
-function waitMs(value, fallback) {
-    return Math.max(0, Math.min(30_000, Math.trunc(value ?? fallback)));
+export function normalizeWaitMs(value, fallback, empty = false) {
+    const lower = empty ? MIN_EMPTY_YIELD_TIME_MS : MIN_YIELD_TIME_MS;
+    const upper = empty ? MAX_EMPTY_YIELD_TIME_MS : MAX_YIELD_TIME_MS;
+    return Math.max(lower, Math.min(upper, Math.trunc(value ?? fallback)));
 }
 function outputLimit(maxOutputBytes, maxOutputTokens) {
-    if (maxOutputTokens === undefined)
-        return maxOutputBytes;
-    positiveFinite('max_output_tokens', maxOutputTokens);
-    return Math.max(1, Math.min(maxOutputBytes, Math.trunc(maxOutputTokens * 4)));
+    const tokens = maxOutputTokens ?? DEFAULT_OUTPUT_TOKENS;
+    if (maxOutputTokens !== undefined)
+        positiveFinite('max_output_tokens', maxOutputTokens);
+    return Math.max(1, Math.min(maxOutputBytes, Math.trunc(tokens * APPROX_BYTES_PER_TOKEN)));
 }
 function limitOutput(text, maxBytes) {
     if (Buffer.byteLength(text, 'utf8') <= maxBytes)
@@ -100,6 +108,13 @@ async function waitForShell(process, ms, signal) {
         signal.throwIfAborted();
     return completed === true || process.status !== 'running';
 }
+/** Stop a pipe-backed session when the current Codex tool is cancelled. */
+async function stopShellOnAbort(process, signal) {
+    if (!signal.aborted || process.status !== 'running')
+        return;
+    process.kill();
+    await process.done;
+}
 function allocateSession(agent, session) {
     const state = stateFor(agent);
     const id = ++state.nextId;
@@ -142,22 +157,33 @@ export async function runExecCommand(ctx, args, exec, config) {
             ...workdir === undefined ? {} : { cwd: workdir },
         };
         const spawned = await terminals.spawn(agent, spawnRequest, exec.signal);
-        const sendRequest = {
-            text: commandFor(args),
-            submit: true,
-            waitMs: waitMs(args.yield_time_ms, config.defaultYieldTimeMs),
-            signal: exec.signal,
-        };
-        const operation = terminals.startSend(agent, spawned.sessionId, sendRequest);
-        const result = await operation.done;
-        const output = terminalResult(result, maxBytes, startedAt);
-        if (result.sessionStatus.kind === 'running') {
-            output.session_id = allocateSession(agent, { kind: 'terminal', owner: agent, id: spawned.sessionId });
+        let retained = false;
+        let closeReason = 'Codex command failed';
+        try {
+            const sendRequest = {
+                text: commandFor(args),
+                submit: true,
+                waitMs: normalizeWaitMs(args.yield_time_ms, config.defaultYieldTimeMs),
+                signal: exec.signal,
+            };
+            const operation = terminals.startSend(agent, spawned.sessionId, sendRequest);
+            const result = await operation.done;
+            const output = terminalResult(result, maxBytes, startedAt);
+            if (result.sessionStatus.kind === 'running') {
+                output.session_id = allocateSession(agent, { kind: 'terminal', owner: agent, id: spawned.sessionId });
+                retained = true;
+            }
+            else {
+                closeReason = 'Codex command exited';
+            }
+            return output;
         }
-        else {
-            await terminals.kill(agent, spawned.sessionId, 'Codex command exited');
+        finally {
+            // A PTY is published by spawn before the first send starts. Do not leave
+            // that session behind when send setup or its foreground operation fails.
+            if (!retained)
+                await terminals.kill(agent, spawned.sessionId, closeReason);
         }
-        return output;
     }
     const policy = ctx.get('sandboxPolicy')?.resolve(exec.agent === undefined ? {} : { session: exec.agent.session });
     const dshEnv = ctx.get('shellEnv')?.collect(exec);
@@ -167,32 +193,38 @@ export async function runExecCommand(ctx, args, exec, config) {
         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));
-    const completed = await waitForShell(process, waitMs(args.yield_time_ms, config.defaultYieldTimeMs), exec.signal);
-    const output = readShellOutput(process.readOutput(), maxBytes);
-    if (!completed || process.status === 'running') {
-        if (exec.agent === undefined) {
-            process.kill();
-            await process.done;
+    try {
+        await waitForShell(process, normalizeWaitMs(args.yield_time_ms, config.defaultYieldTimeMs), exec.signal);
+        const output = readShellOutput(process.readOutput(), maxBytes);
+        if (process.status === 'running') {
+            if (exec.agent === undefined) {
+                process.kill();
+                await process.done;
+                return withChunkId({
+                    wall_time_seconds: (performance.now() - startedAt) / 1000,
+                    output: readShellOutput(process.readOutput(), maxBytes),
+                });
+            }
             return withChunkId({
                 wall_time_seconds: (performance.now() - startedAt) / 1000,
-                output: readShellOutput(process.readOutput(), maxBytes),
+                output,
+                session_id: allocateSession(exec.agent, { kind: 'shell', process }),
             });
         }
         return withChunkId({
             wall_time_seconds: (performance.now() - startedAt) / 1000,
             output,
-            session_id: allocateSession(exec.agent, { kind: 'shell', process }),
+            ...process.exitCode === null ? {} : { exit_code: process.exitCode },
         });
     }
-    return withChunkId({
-        wall_time_seconds: (performance.now() - startedAt) / 1000,
-        output,
-        ...process.exitCode === null ? {} : { exit_code: process.exitCode },
-    });
+    finally {
+        await stopShellOnAbort(process, exec.signal);
+    }
 }
 /** Poll or write to one session returned by {@link runExecCommand}. */
 export async function runWriteStdin(ctx, args, exec, config) {
@@ -211,21 +243,33 @@ export async function runWriteStdin(ctx, args, exec, config) {
         if (chars.length > 0) {
             throw new Error('this unified exec session uses pipes and does not accept stdin; rerun exec_command with tty=true');
         }
-        const completed = await waitForShell(session.process, waitMs(args.yield_time_ms, config.pollYieldTimeMs), exec.signal);
-        const output = readShellOutput(session.process.readOutput(), maxBytes);
-        if (completed && session.process.status !== 'running') {
-            forgetSession(agent, args.session_id);
+        try {
+            await waitForShell(session.process, normalizeWaitMs(args.yield_time_ms, config.pollYieldTimeMs, true), exec.signal);
+            const output = readShellOutput(session.process.readOutput(), maxBytes);
+            if (session.process.status !== 'running') {
+                forgetSession(agent, args.session_id);
+                return withChunkId({
+                    wall_time_seconds: (performance.now() - startedAt) / 1000,
+                    output,
+                    ...session.process.exitCode === null ? {} : { exit_code: session.process.exitCode },
+                });
+            }
             return withChunkId({
                 wall_time_seconds: (performance.now() - startedAt) / 1000,
                 output,
-                ...session.process.exitCode === null ? {} : { exit_code: session.process.exitCode },
+                session_id: args.session_id,
             });
         }
-        return withChunkId({
-            wall_time_seconds: (performance.now() - startedAt) / 1000,
-            output,
-            session_id: args.session_id,
-        });
+        finally {
+            if (exec.signal.aborted) {
+                try {
+                    await stopShellOnAbort(session.process, exec.signal);
+                }
+                finally {
+                    forgetSession(agent, args.session_id);
+                }
+            }
+        }
     }
     const terminals = ctx.get('terminals');
     if (terminals === undefined)
@@ -233,19 +277,33 @@ export async function runWriteStdin(ctx, args, exec, config) {
     const sendRequest = {
         text: chars,
         submit: false,
-        waitMs: waitMs(args.yield_time_ms, chars.length > 0 ? config.writeYieldTimeMs : config.pollYieldTimeMs),
+        waitMs: normalizeWaitMs(args.yield_time_ms, chars.length > 0 ? config.writeYieldTimeMs : config.pollYieldTimeMs, chars.length === 0),
         signal: exec.signal,
     };
-    const operation = terminals.startSend(agent, session.id, sendRequest);
-    const result = await operation.done;
-    const output = terminalResult(result, maxBytes, startedAt);
-    if (result.sessionStatus.kind === 'running') {
-        output.session_id = args.session_id;
+    let retained = false;
+    let closeReason = 'Codex command failed';
+    try {
+        const operation = terminals.startSend(agent, session.id, sendRequest);
+        const result = await operation.done;
+        const output = terminalResult(result, maxBytes, startedAt);
+        if (result.sessionStatus.kind === 'running') {
+            output.session_id = args.session_id;
+            retained = true;
+        }
+        else {
+            closeReason = 'Codex command exited';
+            forgetSession(agent, args.session_id);
+        }
+        return output;
     }
-    else {
-        forgetSession(agent, args.session_id);
-        await terminals.kill(agent, session.id, 'Codex command exited');
+    finally {
+        // A failed send must not strand either side of the two-level session
+        // registry: the local numeric id and the underlying PTY must be retired
+        // together. A successful running result is the only retained case.
+        if (!retained) {
+            forgetSession(agent, args.session_id);
+            await terminals.kill(agent, session.id, closeReason);
+        }
     }
-    return output;
 }
 //# sourceMappingURL=exec.js.map

package/lib/types/index.js

@@ -6,6 +6,7 @@ import { CODEX_CONTEXT_MAX } from "./context.js";
 import { applyPatchHunks, parsePatch } from "./patch.js";
 import { renderExecResult, runExecCommand, runWriteStdin } from "./exec.js";
 import { hostedWebSearchStream, installHostedWebSearch, remoteCompactStream } from "./remote.js";
+import { registerCodexActivityProjection } from "./activity.js";
 export const name = 'codex';
 export const inject = ['tools', 'systemPrompt', 'shell', 'fs', 'llm', 'credentials', 'settings'];
 /** Runtime configuration schema for the Codex tool bridge. */
@@ -178,8 +179,7 @@ const CODEX_BASE_PROMPT = String.raw `You are Codex, based on {{model}}. You are
 `;
 const CODEX_COLLABORATION_PROMPT = String.raw `## Collaboration
 
-- Ask, align, and clarify whenever uncertainty, assumptions, tradeoffs, or decisions could materially affect the outcome.
-- Understand the user's full picture, align it with your own, and leave no hidden assumptions or gaps.
+- Ask, align, and clarify first. Try your best to understand the user's full picture.
 - Keep only the essential logic and core actions. There's no need to explain or test what was removed or why something wasn't done.
 - Convey enough valuable information with as few words as possible. Stay focused on the end goal.
 - Solve problems by thinking from first principles and at a higher level.
@@ -459,6 +459,7 @@ export function apply(ctx, config = {}) {
     // provider routes. Codex adds only scoped transport behavior and capability
     // metadata; failed remote operations continue through the generic path.
     watchConfiguredGptModels(ctx);
+    registerCodexActivityProjection(ctx);
     const codexSettings = installCodexSettings(ctx);
     // Keep these controls in the request config rather than mutating provider
     // settings. That makes a change apply to the next step without rebuilding

package/lib/types/patch.js

@@ -1,20 +1,21 @@
 /** Parser and line-oriented applicator for Codex's `apply_patch` language. */
 /** The grammar sent to providers that support OpenAI custom grammar tools. */
-export const APPLY_PATCH_GRAMMAR = String.raw `start: begin_patch hunk+ end_patch
-begin_patch: "*** Begin Patch" LF
-end_patch: "*** End Patch" LF?
-hunk: add_hunk | delete_hunk | update_hunk
-add_hunk: "*** Add File: " filename LF add_line+
-delete_hunk: "*** Delete File: " filename LF
-update_hunk: "*** Update File: " filename LF change_move? change?
-filename: /(.+)/
-add_line: "+" /(.*)/ LF -> line
-change_move: "*** Move to: " filename LF
-change: (change_context | change_line)+ eof_line?
-change_context: ("@@" | "@@ " /(.+)/) LF
-change_line: ("+" | "-" | " ") /(.*)/ LF
-eof_line: "*** End of File" LF
-%import common.LF
+export const APPLY_PATCH_GRAMMAR = String.raw `start: begin_patch environment_id? hunk+ end_patch
+begin_patch: "*** Begin Patch" LF
+environment_id: "*** Environment ID: " filename LF
+end_patch: "*** End Patch" LF?
+hunk: add_hunk | delete_hunk | update_hunk
+add_hunk: "*** Add File: " filename LF add_line+
+delete_hunk: "*** Delete File: " filename LF
+update_hunk: "*** Update File: " filename LF change_move? change?
+filename: /(.+)/
+add_line: "+" /(.*)/ LF -> line
+change_move: "*** Move to: " filename LF
+change: (change_context | change_line)+ eof_line?
+change_context: ("@@" | "@@ " /(.+)/) LF
+change_line: ("+" | "-" | " ") /(.*)/ LF
+eof_line: "*** End of File" LF
+%import common.LF
 `;
 function invalid(message) {
     throw new Error(`apply_patch: ${message}`);
@@ -25,6 +26,19 @@ function isFileHeader(line) {
         || trimmed.startsWith('*** Delete File: ')
         || trimmed.startsWith('*** Update File: ');
 }
+const ENVIRONMENT_ID_MARKER = '*** Environment ID:';
+function unwrapHeredoc(input) {
+    const normalized = input.replaceAll('\r\n', '\n').trim();
+    const lines = normalized.split('\n');
+    const first = lines[0]?.trim();
+    const last = lines.at(-1)?.trim();
+    if (lines.length >= 4
+        && (first === '<<EOF' || first === "<<'EOF'" || first === '<<"EOF"')
+        && last === 'EOF') {
+        return lines.slice(1, -1).join('\n').trim();
+    }
+    return normalized;
+}
 function pathFrom(line, prefix) {
     const path = line.slice(prefix.length).trim();
     if (path.length === 0)
@@ -40,7 +54,7 @@ function isPotentialChangeMarker(line) {
 }
 /** Parse one complete Codex patch after normalizing CRLF input to LF. */
 export function parsePatch(input) {
-    const lines = input.replaceAll('\r\n', '\n').trim().split('\n');
+    const lines = unwrapHeredoc(input).split('\n');
     if (lines[0]?.trim() !== '*** Begin Patch')
         invalid('input must start with "*** Begin Patch"');
     if (lines.at(-1)?.trim() !== '*** End Patch')
@@ -48,6 +62,15 @@ export function parsePatch(input) {
     const files = [];
     let index = 1;
     const end = lines.length - 1;
+    if (lines[index]?.trim().startsWith(ENVIRONMENT_ID_MARKER) === true) {
+        const environmentId = lines[index].trim().slice(ENVIRONMENT_ID_MARKER.length).trim();
+        if (environmentId.length === 0)
+            invalid('environment id cannot be empty');
+        index++;
+        if (lines[index]?.trim().startsWith(ENVIRONMENT_ID_MARKER) === true) {
+            invalid('environment id cannot be specified more than once');
+        }
+    }
     while (index < end) {
         const header = lines[index++]?.trim();
         if (header === undefined)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shuind/dsh-codex-harness",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "A minimal Codex harness 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",