@deepseek-ai/dsh-subagent-codex 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/subagent/subagent-codex/README.md
+README.md: 3d59ca1eaf3db9dd9d9d2cd451692ebd2a956ef4
+README.zh.md: b60cb1bba9b2d7b3f61c544c1600862a0ad6ce5b

package/README.md

@@ -0,0 +1,91 @@
+# @deepseek-ai/dsh-subagent-codex
+
+English | [中文](README.zh.md)
+
+This package registers the fixed `codex` subagent provider. Each accepted run starts the official `codex app-server --stdio` command in the delegating Session's workspace, creates one ephemeral Codex thread, submits one self-contained text task, and returns only the final answer through the shared [`dsh-subagent`](../subagent/README.md) result contract.
+
+## Start and ownership
+
+`start(request)` accepts only a non-empty sequence of text blocks and derives the child cwd from the parent Session. It then spawns the fixed command through [`dsh-subprocess`](../../subprocess/subprocess/README.md), performs `initialize` → `initialized` → `thread/start { cwd, ephemeral: true }`, and publishes the run only after Codex returns a valid ephemeral thread. A failure or cancellation before publication closes the wire, terminates the managed process tree, waits for it to exit, and rejects `start()`.
+
+The published `run.result` starts exactly one turn. It accepts only notifications for that run's thread and turn, then waits for the authoritative `turn/completed` terminal notification. The latest `agentMessage` with `phase: "final_answer"` wins; when Codex emits no explicit final phase, the latest message with `phase: null` is the compatibility fallback. Commentary never replaces either answer, and a successful turn with no nonblank answer settles as an error.
+
+For command and file approvals, the unattended provider selects a non-approval decision offered by the request, preferring `cancel`; the stable 0.147.0 request shape without an offered-decision list falls back to `decline`. It answers permission requests with an empty turn-scoped permission set, answers user-input requests with no answers, and declines MCP elicitation. A request with no legal unattended response, or any unknown server request, fails the run.
+
+Local cancellation wins the result race and maps to `aborted`. A failed turn whose `codexErrorInfo` is `contextWindowExceeded` maps to `max-tokens`; every other remote interrupted or failed turn maps to `error`, and the provider produces no `refusal`. `dispose()` is idempotent: it requests a best-effort `turn/interrupt` with both current ids when they are known, closes the JSON-RPC wire, ends stdin, invokes the shared process-tree termination escalation, and waits for whole-tree exit. Result failure and independent teardown failure remain separate.
+
+## Capabilities and context
+
+The provider advertises no optional start-time capabilities and reports `inheritsParentContext: false`. Codex receives the standalone text task and the parent Session cwd, but not the parent conversation, persona, tool filter, depth policy, or structured-output contract. The ephemeral Codex thread id and turn id stay private to this run and are never persisted in the parent Session.
+
+## Configuration
+
+| Key | Default | Meaning |
+|---|---|---|
+| `env` | `{}` | Explicit child environment layered over the subprocess seam's credential-scrubbed parent environment. |
+| `disposeGraceMs` | `3000` | Positive finite grace in milliseconds, no greater than [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md), between the shared process-tree owner's termination tiers; disposal then waits for whole-tree exit. |
+
+Production resolves `codex` from `PATH` and uses the host's native Codex configuration and authentication. The plugin does not install Codex, select a model, create `CODEX_HOME`, log in, or probe a version. Credential-shaped ambient variables are removed by the subprocess seam, so an API key intended for the child must be supplied explicitly in `env`; ordinary ambient values such as `PATH` and `HOME` remain available unless overridden.
+
+Shipped profiles load this provider once on the host and start no Codex process until a tool call. Full Agent Presets carry the tool row below with `disabled: true`; copy a preset and remove that field to expose `subagent_codex` only to agents composed from the copy. A custom host composition can still use both rows directly.
+
+```yaml
+- id: subagent-codex
+  name: '@deepseek-ai/dsh-subagent-codex'
+  config:
+    env:
+      OPENAI_API_KEY: !!js process.env.OPENAI_API_KEY
+
+- id: tool-subagent-codex
+  name: '@deepseek-ai/dsh-tool-subagent'
+  disabled: true
+  config:
+    provider: codex
+    toolName: subagent_codex
+    enableRunInBackground: false
+    maxDepth: provider-managed
+```
+
+## Product compatibility and evidence
+
+The production wire intentionally implements only the app-server methods required by this one-shot contract. Development evidence is pinned to `@openai/codex@0.147.0` / `codex-cli 0.147.0`; the npm package is a test-only dependency, and deployments still supply `codex` on `PATH`.
+
+## Model Experience
+
+### Child request
+
+#### What the model sees
+
+The Codex child receives the standalone text blocks as one turn in a fresh ephemeral thread. Its workspace is the parent Session cwd, and its model, system instructions, tools, sandbox, and authentication come from the native Codex installation and configuration.
+
+#### Token effect
+
+The child pays for an independent Codex context and turn. Child tokens do not enter the parent's context.
+
+#### KV Cache effect
+
+Independent of the parent request cache. Reuse depends only on Codex's own provider, model, instructions, tools, and ephemeral-thread request.
+
+### Parent tool result, indirectly
+
+#### What the model sees
+
+Through `dsh-tool-subagent`, the parent sees only the selected final Codex answer or the consumer's exact error for a non-completed result. Codex commentary, reasoning, tool activity, stderr, workspace diffs, and product ids are not copied into the parent Session.
+
+#### Token effect
+
+Parent input grows only by the final answer or error retained in the tool result. This provider adds no parent tool schema by itself.
+
+#### KV Cache effect
+
+Append-only: the new tool result follows the reusable parent request prefix.
+
+## Known Limitations and Deferred Work
+
+- **One fresh process, thread, and turn per run** — there is no continuation, resume, pooling, progress stream, or product-session persistence.
+- **Host-managed product installation and account state** — a missing or incompatible `codex`, configuration error, or authentication failure is surfaced as a startup or run error; the plugin provides no installer, login flow, or runtime version gate.
+- **Compatibility is pinned by development evidence** — upgrading from the verified 0.147.0 protocol baseline requires regenerating upstream schema evidence and rerunning handshake, answer-selection, approval, cancellation, keyless real-product, and credentialed DeepSeek nonce tests.
+- **No human approval path** — known unattended approval requests are denied and unknown server requests fail closed; deployments cannot configure an allow policy through this package.
+- **Final text only** — reasoning, commentary, intermediate messages, tool traffic, usage, stderr, and workspace diffs remain product-local.
+- **No optional shared capabilities** — output schemas, child personas, tool filtering, and harness depth enforcement are rejected by the shared service for this provider.
+- **No wall-clock timeout or side-effect rollback** — the caller cancels long work, and files or external systems changed before cancellation are not restored.

package/README.zh.md

@@ -0,0 +1,91 @@
+# @deepseek-ai/dsh-subagent-codex
+
+[English](README.md) | 中文
+
+本包（package）注册固定的 `codex` subagent 提供方。每次接受运行请求后，它都会在发起委托的会话工作区中启动官方 `codex app-server --stdio` 命令，创建一个临时 Codex 线程，提交一个自包含的文本任务，并通过共享的 [`dsh-subagent`](../subagent/README.md) 结果约定仅返回最终答案。
+
+## 启动与所有权
+
+`start(request)` 只接受非空的文本块序列，并根据父会话确定子级 cwd。随后，它通过 [`dsh-subprocess`](../../subprocess/subprocess/README.md) spawn 固定命令，依次执行 `initialize` → `initialized` → `thread/start { cwd, ephemeral: true }`，且仅在 Codex 返回有效的临时线程后才发布此次运行。若在发布前发生失败或取消，它会关闭通信链路、终止受管进程树并等待其退出，然后拒绝 `start()` 调用。
+
+已发布的 `run.result` 恰好启动一个轮次。它只接受与此次运行的线程和轮次匹配的通知，随后等待权威的终止通知 `turn/completed`。以最后一条 `phase: "final_answer"` 的 `agentMessage` 为准；若 Codex 没有发出明确的最终阶段，则以最后一条 `phase: null` 的消息作为兼容性回退。过程说明绝不会取代上述任一答案；成功完成的轮次若没有非空白答案，结果也会判为错误。
+
+对于命令与文件审批，无人值守的提供方会从请求给出的决策选项中选择一项不予批准的决策，并优先选择 `cancel`；稳定的 0.147.0 请求形态没有决策选项列表，因此回退到 `decline`。它对权限请求返回作用域限于当前轮次的空权限集，不向用户输入请求提供任何答案，并拒绝 MCP elicitation。若请求在无人值守模式下没有合法响应，或是未知服务器请求，此次运行就会失败。
+
+本地取消会在结果竞态中胜出并映射为 `aborted`。失败轮次的 `codexErrorInfo` 若为 `contextWindowExceeded`，则映射为 `max-tokens`；其他任何远端中断或失败轮次都映射为 `error`，且该提供方不会产生 `refusal`。`dispose()` 具有幂等性：如果当前的两个标识符均已知，它会尽力请求 `turn/interrupt`，关闭 JSON-RPC 通信链路，结束标准输入，调用共享的进程树逐级终止机制，并等待整棵进程树退出。结果失败与独立的清理失败仍彼此分离。
+
+## 能力与上下文
+
+本提供方不声明任何可选的启动时能力，并报告 `inheritsParentContext: false`。Codex 会接收独立文本任务和父会话 cwd，但不会接收父会话的对话、角色设定、工具筛选器、深度策略或结构化输出约定。临时 Codex 线程 ID 与轮次 ID 仅在此次运行内部可见，绝不会持久化到父会话。
+
+## 配置
+
+| 配置键 | 默认值 | 含义 |
+|---|---|---|
+| `env` | `{}` | 显式指定的子进程环境，叠加在由子进程 seam 清除凭证后的父环境之上。 |
+| `disposeGraceMs` | `3000` | 共享进程树责任方各终止层级之间的宽限期，单位为毫秒且须为正有限值，并不得大于仓库共享的 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md)；随后资源释放会等待整棵进程树退出。 |
+
+生产环境会从 `PATH` 中解析 `codex`，并使用宿主机原生的 Codex 配置与身份验证。本插件不安装 Codex、不选择模型、不创建 `CODEX_HOME`、不执行登录，也不探测版本。子进程 seam 会移除具有凭证特征的环境变量，因此供子进程使用的 API 密钥必须在 `env` 中显式提供；除非被覆盖，`PATH` 和 `HOME` 等普通环境变量值仍然可用。
+
+随附 profile 会在宿主上加载一次该提供方，而且在工具被调用前不会启动 Codex 进程。完整 Agent Preset 携带下列工具行并设置 `disabled: true`；复制一个 preset 后删除该字段，即可只向由该副本组装的 agent 暴露 `subagent_codex`。自定义宿主组装仍可直接使用两条配置行。
+
+```yaml
+- id: subagent-codex
+  name: '@deepseek-ai/dsh-subagent-codex'
+  config:
+    env:
+      OPENAI_API_KEY: !!js process.env.OPENAI_API_KEY
+
+- id: tool-subagent-codex
+  name: '@deepseek-ai/dsh-tool-subagent'
+  disabled: true
+  config:
+    provider: codex
+    toolName: subagent_codex
+    enableRunInBackground: false
+    maxDepth: provider-managed
+```
+
+## 产品兼容性与证据
+
+生产环境的协议层有意只实现这一单次执行约定所需的 app-server 方法。开发证据锁定在 `@openai/codex@0.147.0` / `codex-cli 0.147.0`；该 NPM 包仅作为测试依赖，部署环境仍需通过 `PATH` 提供 `codex`。
+
+## 模型体验
+
+### 子任务请求
+
+#### 模型看到的内容
+
+Codex 子任务会在一个全新的临时线程中，以单个轮次接收这些独立文本块。它的工作区是父会话 cwd；其模型、系统指令、工具、沙箱和身份验证来自原生 Codex 安装与配置。
+
+#### 对 token 的影响
+
+子任务需为独立的 Codex 上下文和轮次承担 token 开销。子任务 token 不会进入父级上下文。
+
+#### 对 KV Cache 的影响
+
+这与父请求缓存相互独立。能否复用只取决于 Codex 自身的提供方、模型、指令、工具和临时线程请求。
+
+### 父级工具结果（间接）
+
+#### 模型看到的内容
+
+通过 `dsh-tool-subagent`，父级模型只会看到选定的 Codex 最终答案，或者在结果未完成时看到消费方给出的原样错误。Codex 的过程说明、推理（reasoning）、工具活动、stderr、工作区差异和产品标识符均不会复制到父会话。
+
+#### 对 token 的影响
+
+父级输入只会增加工具结果中保留的最终答案或错误内容。本提供方自身不添加父级工具 schema。
+
+#### 对 KV Cache 的影响
+
+仅追加：新的工具结果接在可复用的父请求前缀之后。
+
+## 已知限制与后续工作
+
+- **每次运行均新建一个进程、一个线程和一个轮次**：不支持续接、恢复、池化、进度流或产品会话持久化。
+- **产品安装和账户状态由宿主管理**：`codex` 缺失或不兼容、配置错误或身份验证失败，都会呈现为启动错误或运行错误；本插件不提供安装程序、登录流程或运行时版本门禁。
+- **兼容性由开发证据锁定**：若要从已验证的 0.147.0 协议基线升级，必须重新生成上游 schema 证据，并重新运行握手、答案选择、审批、取消、无密钥真实产品以及带密钥的 DeepSeek 随机数测试。
+- **没有人工审批路径**：已知的无人值守审批请求会被拒绝，未知服务器请求会以默认拒绝方式使运行失败；部署方无法通过本包配置允许策略。
+- **仅返回最终文本**：推理、过程说明、中间消息、工具通信、用量信息、stderr 和工作区差异仍只保留在产品内部。
+- **没有可选的共享能力**：对于本提供方，共享服务会拒绝输出 schema、子任务角色设定、工具筛选和 harness 深度强制约束。
+- **没有按实际经过时间触发的超时或副作用回滚**：长时间运行的工作由调用方取消，且取消前已更改的文件或外部系统不会恢复原状。

package/lib/index.js

@@ -0,0 +1,513 @@
+import z from "@deepseek-ai/schemastery";
+import { MAX_TIMER_DELAY_MS } from "@deepseek-ai/dsh-timeout";
+import { NO_START_CAPABILITIES, assertPositiveFinite, resolveChildCwd, settleRunResult, subprocessRunHandle } from "@deepseek-ai/dsh-subagent";
+import { randomUUID } from "node:crypto";
+import { SessionId } from "@deepseek-ai/dsh-session";
+import { JsonRpcLineTransport } from "@deepseek-ai/dsh-sdk-protocol";
+//#region lib/types/wire.js
+/**
+* Minimal Codex app-server 0.147.0 protocol adapter. The shared JSON-RPC
+* transport owns framing and request correlation; this module owns only the
+* product methods, current thread/turn association, unattended approval
+* responses, and terminal-answer selection.
+*
+* @module @deepseek-ai/dsh-subagent-codex/wire
+*/
+function object(value, label) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`subagent-codex: app-server returned invalid ${label}`);
+	return value;
+}
+function string(value, label) {
+	if (typeof value !== "string" || value.length === 0) throw new Error(`subagent-codex: app-server returned invalid ${label}`);
+	return value;
+}
+function unattendedDecision(params) {
+	const available = params.availableDecisions;
+	if (available === void 0 || available === null) return "decline";
+	if (Array.isArray(available)) {
+		if (available.includes("cancel")) return "cancel";
+		if (available.includes("decline")) return "decline";
+	}
+	throw new Error("subagent-codex: app-server offered no unattended approval decision");
+}
+function isContextWindowExceeded(turn) {
+	if (turn.status !== "failed") return false;
+	const error = turn.error;
+	return error !== null && typeof error === "object" && !Array.isArray(error) && error.codexErrorInfo === "contextWindowExceeded";
+}
+function thrown$1(value) {
+	/* v8 ignore next -- typed protocol and stream failures reject with Error. */
+	return value instanceof Error ? value : new Error(String(value));
+}
+function abortError(signal) {
+	return signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error(`subagent-codex: app-server request aborted: ${String(signal.reason)}`);
+}
+async function raceAbort(pending, signal) {
+	if (signal.aborted) {
+		pending.catch(() => {});
+		throw abortError(signal);
+	}
+	let rejectAbort;
+	const aborted = new Promise((_resolve, reject) => {
+		rejectAbort = reject;
+	});
+	const onAbort = () => {
+		rejectAbort(abortError(signal));
+	};
+	signal.addEventListener("abort", onAbort, { once: true });
+	try {
+		return await Promise.race([pending, aborted]);
+	} finally {
+		signal.removeEventListener("abort", onAbort);
+	}
+}
+/**
+* One app-server connection and its single ephemeral thread/turn.
+*
+* The class deliberately exposes no generic request surface. Supporting
+* another product method must first become part of the provider contract.
+*/
+var CodexAppServerWire = class {
+	input;
+	transport;
+	fatal = Promise.withResolvers();
+	threadId;
+	turnId;
+	pendingTurnId;
+	turnCompleted;
+	earlyTurnNotifications = [];
+	lastFinalAnswer;
+	lastUnphasedAnswer;
+	closed = false;
+	constructor(input, output) {
+		this.input = input;
+		this.transport = new JsonRpcLineTransport(input, output);
+		this.fatal.promise.catch(() => {});
+		this.transport.onRequest((method, params) => this.handleServerRequest(method, params));
+		this.transport.onNotification((method, params) => {
+			try {
+				this.handleNotification(method, params);
+			} catch (error) {
+				this.fail(thrown$1(error));
+			}
+		});
+		this.input.on("error", this.onInputError);
+		this.input.on("end", this.onInputEnd);
+		output.on("error", this.onOutputError);
+	}
+	/** Start reading app-server frames. */
+	start() {
+		this.transport.start();
+	}
+	/**
+	* Perform the required app-server initialize/initialized handshake.
+	* @param signal - unpublished-start cancellation.
+	*/
+	async initialize(signal) {
+		object(await this.guarded(this.transport.request("initialize", {
+			clientInfo: {
+				name: "deepseek-harness",
+				title: "DeepSeek Harness",
+				version: "0.0.1"
+			},
+			capabilities: {
+				experimentalApi: false,
+				requestAttestation: false
+			}
+		}, signal), signal), "initialize response");
+		this.transport.notify("initialized");
+		await this.guarded(this.transport.flush(), signal);
+	}
+	/**
+	* Create the run's private ephemeral thread and retain its identity.
+	* @param cwd - parent Session workspace.
+	* @param signal - unpublished-start cancellation.
+	*/
+	async startThread(cwd, signal) {
+		const thread = object(object(await this.guarded(this.transport.request("thread/start", {
+			cwd,
+			ephemeral: true
+		}, signal), signal), "thread/start response").thread, "thread/start thread");
+		const id = string(thread.id, "thread/start thread id");
+		if (thread.ephemeral !== true) throw new Error("subagent-codex: app-server did not create an ephemeral thread");
+		this.threadId = id;
+	}
+	/**
+	* Submit the one text-only task and wait for this thread/turn's authoritative
+	* terminal notification.
+	* @param texts - already validated task text blocks.
+	* @param signal - local cancellation for the published run.
+	* @returns the shared subagent result.
+	*/
+	async runTurn(texts, signal) {
+		const completion = Promise.withResolvers();
+		this.turnCompleted = completion;
+		const threadId = this.threadId;
+		const turn = object(object(await this.guarded(this.transport.request("turn/start", {
+			threadId,
+			input: texts.map((text) => ({
+				type: "text",
+				text,
+				text_elements: []
+			}))
+		}, signal), signal), "turn/start response").turn, "turn/start turn");
+		this.commitTurnId(string(turn.id, "turn/start turn id"));
+		const terminal = object((await this.guarded(completion.promise, signal)).turn, "turn/completed turn");
+		const status = terminal.status;
+		if (isContextWindowExceeded(terminal)) return {
+			output: this.collectOutput(),
+			stopReason: "max-tokens"
+		};
+		if (status !== "completed") {
+			const detail = status === "failed" ? `: ${JSON.stringify(terminal.error)}` : "";
+			throw new Error(`subagent-codex: Codex turn ended with status ${String(status)}${detail}`);
+		}
+		const output = this.collectOutput();
+		if (output.length === 0) throw new Error("subagent-codex: Codex completed without a final answer");
+		return {
+			output,
+			stopReason: "completed"
+		};
+	}
+	/**
+	* Best-effort remote cancellation. Local settlement and process teardown
+	* remain authoritative when the child no longer accepts protocol requests.
+	*/
+	interrupt() {
+		if (this.threadId === void 0 || this.turnId === void 0 || this.closed) return;
+		this.transport.request("turn/interrupt", {
+			threadId: this.threadId,
+			turnId: this.turnId
+		}).catch(() => {});
+	}
+	/**
+	* The best non-commentary answer observed so far, preserving exact bytes.
+	* @returns the selected final or nullable-phase text block, if any.
+	*/
+	collectOutput() {
+		const selected = this.lastFinalAnswer ?? this.lastUnphasedAnswer;
+		return selected !== void 0 && selected.trim().length > 0 ? [{
+			type: "text",
+			text: selected
+		}] : [];
+	}
+	/** Detach JSON-RPC listeners and reject outstanding requests. Idempotent. */
+	close() {
+		if (this.closed) return;
+		this.closed = true;
+		this.input.off("end", this.onInputEnd);
+		this.transport.close();
+	}
+	async guarded(pending, signal) {
+		return raceAbort(Promise.race([this.fatal.promise, pending]), signal);
+	}
+	fail(error) {
+		this.fatal.reject(error);
+	}
+	onInputError = (error) => {
+		this.fail(error);
+	};
+	onOutputError = (error) => {
+		this.fail(error);
+	};
+	onInputEnd = () => {
+		this.fail(/* @__PURE__ */ new Error("subagent-codex: app-server protocol stream closed"));
+	};
+	observePendingTurnId(id) {
+		if (this.turnCompleted === void 0) throw new Error("subagent-codex: app-server referenced a turn before turn/start");
+		if (this.pendingTurnId !== void 0 && this.pendingTurnId !== id) throw new Error("subagent-codex: app-server referenced conflicting turns");
+		this.pendingTurnId = id;
+	}
+	commitTurnId(id) {
+		if (this.pendingTurnId !== void 0 && this.pendingTurnId !== id) throw new Error("subagent-codex: turn/start response did not match the active turn");
+		this.turnId = id;
+		const notifications = this.earlyTurnNotifications.splice(0);
+		for (const notification of notifications) this.handleNotification(notification.method, notification.params);
+	}
+	validateRunIds(params, nullableTurn = false) {
+		if (params.threadId !== this.threadId) throw new Error("subagent-codex: app-server request referenced another thread");
+		if (nullableTurn && params.turnId === null) return;
+		const id = string(params.turnId, "server request turn id");
+		if (this.turnId === void 0) {
+			this.observePendingTurnId(id);
+			return;
+		}
+		if (id !== this.turnId) throw new Error("subagent-codex: app-server request referenced another turn");
+	}
+	handleServerRequest(method, params) {
+		try {
+			switch (method) {
+				case "item/commandExecution/requestApproval":
+				case "item/fileChange/requestApproval":
+					this.validateRunIds(params);
+					return Promise.resolve({ decision: unattendedDecision(params) });
+				case "item/permissions/requestApproval":
+					this.validateRunIds(params);
+					return Promise.resolve({
+						permissions: {},
+						scope: "turn"
+					});
+				case "item/tool/requestUserInput":
+					this.validateRunIds(params);
+					return Promise.resolve({ answers: {} });
+				case "mcpServer/elicitation/request":
+					this.validateRunIds(params, true);
+					return Promise.resolve({
+						action: "decline",
+						content: null,
+						_meta: null
+					});
+				default: throw new Error(`subagent-codex: unsupported app-server request ${JSON.stringify(method)}`);
+			}
+		} catch (error) {
+			const normalized = thrown$1(error);
+			this.fail(normalized);
+			return Promise.reject(normalized);
+		}
+	}
+	handleNotification(method, params) {
+		if (method === "turn/started") {
+			if (string(params.threadId, "turn/started thread id") !== this.threadId) return;
+			const turn = object(params.turn, "turn/started turn");
+			if (this.turnCompleted !== void 0 && this.turnId === void 0) this.observePendingTurnId(string(turn.id, "turn/started turn id"));
+			return;
+		}
+		if (method === "item/completed") {
+			if (string(params.threadId, "item/completed thread id") !== this.threadId) return;
+			const id = string(params.turnId, "item/completed turn id");
+			if (this.turnId === void 0) {
+				if (this.turnCompleted !== void 0) {
+					this.observePendingTurnId(id);
+					this.earlyTurnNotifications.push({
+						method,
+						params
+					});
+				}
+				return;
+			}
+			if (id !== this.turnId) return;
+			const item = object(params.item, "item/completed item");
+			if (item.type !== "agentMessage") return;
+			const text = typeof item.text === "string" ? item.text : (() => {
+				throw new Error("subagent-codex: app-server returned an invalid agent message");
+			})();
+			if (item.phase === "final_answer") this.lastFinalAnswer = text;
+			else if (item.phase === null) this.lastUnphasedAnswer = text;
+			else if (item.phase !== "commentary") throw new Error(`subagent-codex: app-server returned an unknown agent message phase ${JSON.stringify(item.phase)}`);
+			return;
+		}
+		if (method !== "turn/completed") return;
+		if (string(params.threadId, "turn/completed thread id") !== this.threadId) return;
+		const turn = object(params.turn, "turn/completed turn");
+		const id = string(turn.id, "turn/completed turn id");
+		const turnCompleted = this.turnCompleted;
+		if (turnCompleted === void 0) return;
+		if (this.turnId === void 0) {
+			this.observePendingTurnId(id);
+			this.earlyTurnNotifications.push({
+				method,
+				params
+			});
+			return;
+		}
+		if (id !== this.turnId) return;
+		if (![
+			"completed",
+			"interrupted",
+			"failed"
+		].includes(String(turn.status))) throw new Error(`subagent-codex: app-server returned invalid terminal turn status ${String(turn.status)}`);
+		turnCompleted.resolve(params);
+	}
+};
+//#endregion
+//#region lib/types/run.js
+/**
+* One-shot Codex child lifecycle: spawn the real app-server through the
+* subprocess seam, publish only after initialization and ephemeral thread
+* creation, flatten post-publication failures, and dispose to whole-tree
+* quiescence.
+*
+* @module @deepseek-ai/dsh-subagent-codex/run
+*/
+/** Default POSIX grace between subprocess termination tiers. */
+const DEFAULT_DISPOSE_GRACE_MS = 3e3;
+/**
+* Resolve the fixed app-server command for a platform.
+*
+* Windows npm and pnpm installs expose `codex.cmd`, which requires `cmd.exe`;
+* the argv is constant so no task or configuration text enters the
+* shell boundary.
+* @param platform - host platform used to select the executable boundary.
+* @returns argv for the fixed Codex app-server command.
+*/
+function codexAppServerArgv(platform = process.platform) {
+	return platform === "win32" ? [
+		"cmd.exe",
+		"/d",
+		"/s",
+		"/c",
+		"codex",
+		"app-server",
+		"--stdio"
+	] : [
+		"codex",
+		"app-server",
+		"--stdio"
+	];
+}
+function thrown(value) {
+	/* v8 ignore next -- typed subprocess/wire failures reject with Error. */
+	return value instanceof Error ? value : new Error(String(value));
+}
+/**
+* Validate and preserve the one-shot task before crossing the process boundary.
+* @param prompt - task content accepted from the shared subagent service.
+* @returns the exact non-empty text block sequence.
+*/
+function textTask(prompt) {
+	if (prompt.length === 0) throw new Error("subagent-codex: the one-shot task must contain only text blocks");
+	const texts = [];
+	for (const block of prompt) {
+		if (block.type !== "text") throw new Error("subagent-codex: the one-shot task must contain only text blocks");
+		texts.push(block.text);
+	}
+	if (texts.every((text) => text.trim().length === 0)) throw new Error("subagent-codex: the one-shot task must not be empty");
+	return texts;
+}
+/**
+* Close the private wire, terminate the managed process tree, and wait for the
+* subprocess owner to prove it is gone.
+* @param wire - private app-server protocol connection.
+* @param child - shared-service handle that owns the process tree.
+*/
+async function disposeCodexChild(wire, child) {
+	wire.close();
+	if (child.pid <= 0) {
+		await child.done.catch(() => {});
+		return;
+	}
+	try {
+		child.stdin?.end();
+	} catch {}
+	child.terminate();
+	await child.waitForExit();
+	await child.done;
+}
+/**
+* Start the real `codex app-server --stdio` child and publish its one-shot run.
+* @param request - resolved shared subagent request.
+* @param spec - Workspace, environment, process service, and diagnostic policy.
+* @returns the published run after initialization and ephemeral thread creation.
+*/
+async function startCodexRun(request, spec) {
+	const texts = textTask(request.prompt);
+	if (request.signal.aborted) throw new Error("subagent-codex: request was aborted before app-server startup");
+	const child = spec.spawn({
+		argv: codexAppServerArgv(),
+		cwd: spec.cwd,
+		stdio: {
+			stdin: "pipe",
+			stdout: "pipe",
+			stderr: "inherit"
+		},
+		graceMs: spec.disposeGraceMs,
+		env: spec.env
+	});
+	const wire = new CodexAppServerWire(child.stdout, child.stdin);
+	const disposeProcess = () => disposeCodexChild(wire, child);
+	const processFailure = child.done.then((outcome) => Promise.reject(/* @__PURE__ */ new Error(`subagent-codex: app-server exited before the run settled (code ${String(outcome.exitCode)}, signal ${String(outcome.signal)})`)), (error) => Promise.reject(thrown(error)));
+	processFailure.catch(() => {});
+	const runAbort = new AbortController();
+	const requestCancel = () => {
+		if (runAbort.signal.aborted) return;
+		runAbort.abort(/* @__PURE__ */ new Error("subagent-codex: run cancelled locally"));
+		wire.interrupt();
+	};
+	const onAbort = () => {
+		requestCancel();
+	};
+	request.signal.addEventListener("abort", onAbort, { once: true });
+	try {
+		wire.start();
+		await Promise.race([wire.initialize(request.signal), processFailure]);
+		await Promise.race([wire.startThread(spec.cwd, request.signal), processFailure]);
+	} catch (error) {
+		request.signal.removeEventListener("abort", onAbort);
+		try {
+			await disposeProcess();
+		} catch (disposeError) {
+			throw new AggregateError([thrown(error), thrown(disposeError)], "subagent-codex: startup failed and app-server cleanup also failed");
+		}
+		if (runAbort.signal.aborted) throw new Error("subagent-codex: request was aborted before run publication");
+		throw thrown(error);
+	}
+	const collectOutput = () => wire.collectOutput();
+	const result = settleRunResult({
+		attempt: () => Promise.race([wire.runTurn(texts, runAbort.signal), processFailure]),
+		collectOutput,
+		cancelled: () => runAbort.signal.aborted,
+		onError: spec.onError,
+		signal: request.signal,
+		onAbort
+	});
+	return subprocessRunHandle({
+		id: SessionId(randomUUID()),
+		result,
+		signal: request.signal,
+		onAbort,
+		requestCancel,
+		teardown: disposeProcess
+	});
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Fixed Codex one-shot subagent provider. Every accepted run starts a fresh
+* official `codex app-server --stdio` process in the delegating Session's
+* workspace and publishes only after an ephemeral thread exists.
+*
+* @module @deepseek-ai/dsh-subagent-codex
+*/
+const name = "subagent-codex";
+const inject = ["subagents", "subprocess"];
+const Config = z.object({
+	env: z.dict(z.string()).default({}),
+	disposeGraceMs: z.number().default(DEFAULT_DISPOSE_GRACE_MS)
+});
+var CodexProvider = class {
+	ctx;
+	config;
+	name = "codex";
+	capabilities = NO_START_CAPABILITIES;
+	inheritsParentContext = false;
+	constructor(ctx, config) {
+		this.ctx = ctx;
+		this.config = config;
+	}
+	start(request) {
+		const parentCwd = request.parent.session.header.cwd;
+		if (parentCwd === void 0) throw new Error("subagent-codex: no working directory for the child — delegate from a parent session that has one");
+		return startCodexRun(request, {
+			cwd: resolveChildCwd("subagent-codex", void 0, parentCwd),
+			env: this.config.env,
+			disposeGraceMs: this.config.disposeGraceMs,
+			spawn: (spawnSpec) => this.ctx.subprocess.spawn(spawnSpec),
+			onError: (error, stopReason) => {
+				this.ctx.logger.warn(`subagent-codex: child run failed (${stopReason}): ${error.message}`);
+			}
+		});
+	}
+};
+/**
+* Register the fixed `codex` provider.
+* @param ctx - context carrying shared subagent and subprocess services.
+* @param config - explicit child environment and disposal grace.
+*/
+function apply(ctx, config) {
+	const resolved = config;
+	assertPositiveFinite("subagent-codex", "disposeGraceMs", resolved.disposeGraceMs);
+	if (resolved.disposeGraceMs > MAX_TIMER_DELAY_MS) throw new Error(`subagent-codex: disposeGraceMs must be no greater than ${MAX_TIMER_DELAY_MS}`);
+	ctx.subagents.registerProvider(new CodexProvider(ctx, resolved));
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-subagent-codex`.
+* @module @deepseek-ai/dsh-subagent-codex/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-subagent-codex";
+/** Cordis companion plugin name. */
+const name = "subagent-codex-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: lifecycle pairing belongs to the shared subagent
+* service and process-tree ownership belongs to the subprocess service.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - plugin context carrying the invariant registry.
+* @returns the installed registration's disposer.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Fixed Codex one-shot subagent provider. Every accepted run starts a fresh
+ * official `codex app-server --stdio` process in the delegating Session's
+ * workspace and publishes only after an ephemeral thread exists.
+ *
+ * @module @deepseek-ai/dsh-subagent-codex
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "subagent-codex";
+export declare const inject: string[];
+/** Deployment-owned environment and process-release bound. */
+export interface Config {
+    /**
+     * Explicit environment entries layered over the subprocess seam's
+     * credential-scrubbed parent environment.
+     */
+    env?: Record<string, string>;
+    /** Grace in milliseconds for app-server process-tree termination. */
+    disposeGraceMs?: number;
+}
+export declare const Config: z<Config>;
+/**
+ * Register the fixed `codex` provider.
+ * @param ctx - context carrying shared subagent and subprocess services.
+ * @param config - explicit child environment and disposal grace.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-subagent-codex`.
+ * @module @deepseek-ai/dsh-subagent-codex/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "subagent-codex-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - plugin context carrying the invariant registry.
+ * @returns the installed registration's disposer.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/run.d.ts

@@ -0,0 +1,58 @@
+/**
+ * One-shot Codex child lifecycle: spawn the real app-server through the
+ * subprocess seam, publish only after initialization and ephemeral thread
+ * creation, flatten post-publication failures, and dispose to whole-tree
+ * quiescence.
+ *
+ * @module @deepseek-ai/dsh-subagent-codex/run
+ */
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import { type SubagentRun, type SubagentStartRequest, type SubagentStopReason } from '@deepseek-ai/dsh-subagent';
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+import { CodexAppServerWire } from './wire.ts';
+/** Default POSIX grace between subprocess termination tiers. */
+export declare const DEFAULT_DISPOSE_GRACE_MS = 3000;
+/**
+ * Resolve the fixed app-server command for a platform.
+ *
+ * Windows npm and pnpm installs expose `codex.cmd`, which requires `cmd.exe`;
+ * the argv is constant so no task or configuration text enters the
+ * shell boundary.
+ * @param platform - host platform used to select the executable boundary.
+ * @returns argv for the fixed Codex app-server command.
+ */
+export declare function codexAppServerArgv(platform?: NodeJS.Platform): string[];
+/** Fully resolved inputs for one Codex app-server run. */
+export interface CodexRunSpec {
+    /** Parent Session workspace, also supplied to `thread/start`. */
+    readonly cwd: string;
+    /** Explicit deployment/test environment layered after the shared scrub. */
+    readonly env: Record<string, string>;
+    /** Subprocess termination grace passed to the shared process-tree owner. */
+    readonly disposeGraceMs: number;
+    /** Shared subprocess service spawn operation. */
+    readonly spawn: (spec: SubprocessSpawnSpec) => SubprocessHandle;
+    /** Diagnostic sink for a post-publication error flattened into a result. */
+    readonly onError?: (error: Error, stopReason: SubagentStopReason) => void;
+}
+/**
+ * Validate and preserve the one-shot task before crossing the process boundary.
+ * @param prompt - task content accepted from the shared subagent service.
+ * @returns the exact non-empty text block sequence.
+ */
+export declare function textTask(prompt: readonly ContentBlock[]): string[];
+/**
+ * Close the private wire, terminate the managed process tree, and wait for the
+ * subprocess owner to prove it is gone.
+ * @param wire - private app-server protocol connection.
+ * @param child - shared-service handle that owns the process tree.
+ */
+export declare function disposeCodexChild(wire: CodexAppServerWire, child: SubprocessHandle): Promise<void>;
+/**
+ * Start the real `codex app-server --stdio` child and publish its one-shot run.
+ * @param request - resolved shared subagent request.
+ * @param spec - Workspace, environment, process service, and diagnostic policy.
+ * @returns the published run after initialization and ephemeral thread creation.
+ */
+export declare function startCodexRun(request: SubagentStartRequest, spec: CodexRunSpec): Promise<SubagentRun>;
+//# sourceMappingURL=run.d.ts.map

package/lib/types/wire.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Minimal Codex app-server 0.147.0 protocol adapter. The shared JSON-RPC
+ * transport owns framing and request correlation; this module owns only the
+ * product methods, current thread/turn association, unattended approval
+ * responses, and terminal-answer selection.
+ *
+ * @module @deepseek-ai/dsh-subagent-codex/wire
+ */
+import type { Readable, Writable } from 'node:stream';
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { SubagentResult } from '@deepseek-ai/dsh-subagent';
+/**
+ * One app-server connection and its single ephemeral thread/turn.
+ *
+ * The class deliberately exposes no generic request surface. Supporting
+ * another product method must first become part of the provider contract.
+ */
+export declare class CodexAppServerWire {
+    private readonly input;
+    private readonly transport;
+    private readonly fatal;
+    private threadId;
+    private turnId;
+    private pendingTurnId;
+    private turnCompleted;
+    private readonly earlyTurnNotifications;
+    private lastFinalAnswer;
+    private lastUnphasedAnswer;
+    private closed;
+    constructor(input: Readable, output: Writable);
+    /** Start reading app-server frames. */
+    start(): void;
+    /**
+     * Perform the required app-server initialize/initialized handshake.
+     * @param signal - unpublished-start cancellation.
+     */
+    initialize(signal: AbortSignal): Promise<void>;
+    /**
+     * Create the run's private ephemeral thread and retain its identity.
+     * @param cwd - parent Session workspace.
+     * @param signal - unpublished-start cancellation.
+     */
+    startThread(cwd: string, signal: AbortSignal): Promise<void>;
+    /**
+     * Submit the one text-only task and wait for this thread/turn's authoritative
+     * terminal notification.
+     * @param texts - already validated task text blocks.
+     * @param signal - local cancellation for the published run.
+     * @returns the shared subagent result.
+     */
+    runTurn(texts: readonly string[], signal: AbortSignal): Promise<SubagentResult>;
+    /**
+     * Best-effort remote cancellation. Local settlement and process teardown
+     * remain authoritative when the child no longer accepts protocol requests.
+     */
+    interrupt(): void;
+    /**
+     * The best non-commentary answer observed so far, preserving exact bytes.
+     * @returns the selected final or nullable-phase text block, if any.
+     */
+    collectOutput(): ContentBlock[];
+    /** Detach JSON-RPC listeners and reject outstanding requests. Idempotent. */
+    close(): void;
+    private guarded;
+    private fail;
+    private readonly onInputError;
+    private readonly onOutputError;
+    private readonly onInputEnd;
+    private observePendingTurnId;
+    private commitTurnId;
+    private validateRunIds;
+    private handleServerRequest;
+    private handleNotification;
+}
+//# sourceMappingURL=wire.d.ts.map

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@deepseek-ai/dsh-subagent-codex",
+  "description": "One-shot Codex subagent provider over the official app-server protocol",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/subagent/subagent-codex"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-sdk-protocol": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subagent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@openai/codex": "0.147.0",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-loader-smoke": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-sdk-protocol": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subagent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess-local": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}