dsh-codex-connect 0.1.0-alpha.4.7 → 0.1.0-alpha.4.8

package/INSTALL.md

@@ -12,6 +12,8 @@ Install `dsh-codex-connect` into one requested DeepSeek Harness profile without
 
 ## Install and validate
 
+The only verified combination is DSH plugin API packages `0.1.0-rc.6`, `@earendil-works/pi-ai` `0.82.1`, and Node.js `^22.19.0 || >=24.0.0`. Upgrade the DSH API packages and pi-ai together, then rerun `dsh-codex-connect doctor --json` and `pnpm --silent run check:compatibility`; the contract does not make claims about future versions.
+
 1. Check `dsh --version` or `dsh --help`. From a Harness checkout use `pnpm dsh`.
 2. Install the package:
 
@@ -19,7 +21,7 @@ Install `dsh-codex-connect` into one requested DeepSeek Harness profile without
    dsh plugin --profile web add dsh-codex-connect@alpha
    ```
 
-   After `0.1.0-alpha.4.7` is published, pin it exactly with `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.7`. If npm is unavailable after its matching GitHub prerelease is created, use `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.7'`.
+   After `0.1.0-alpha.4.8` is published, pin it exactly with `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.8`. If npm is unavailable after its matching GitHub prerelease is created, use `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.8'`.
 
 3. Run `dsh --profile web --dump-config` and require exactly one `llm-openai-codex` row loading `dsh-codex-connect`.
 4. Confirm the effective `agent-default-model` and `web.searchProvider` values are unchanged from before installation.
@@ -31,6 +33,17 @@ Install `dsh-codex-connect` into one requested DeepSeek Harness profile without
 
 6. If the user explicitly requests login, open **Settings → Plugins → Plugin configuration → Codex Connect**, or check `status` and then use `login` or `login --device-code`. OAuth approval belongs to the user.
 
+### Remote browser access
+
+The default Web OAuth boundary is loopback-only. When DSH runs on one device and you open it from another device on a trusted network through an IP address or domain, run the following on the device that runs DSH with the exact origin from the browser address bar:
+
+```sh
+dsh plugin --profile web exec dsh-codex-connect trust-origin http://192.168.1.20:3080
+dsh plugin --profile web exec dsh-codex-connect trusted-origins
+```
+
+The value is a full `http://` or `https://` origin including its port, not a bare device IP and not a path/query/fragment. Use `untrust-origin <origin>` to remove it. Restrict this to a trusted network and never expose the route publicly; use an SSH tunnel when that is safer. The Web client does not edit this list.
+
 ## Optional configuration
 
 Use **Settings → Plugins → Plugin configuration → Codex Connect** for live, staged Save/Discard edits. The package row accepts the same `enableSearch` and `enableImageTool` fields as its composition base, both defaulting to `false`. Enabling search registers a provider but does not select it; selecting `web.searchProvider: openai-codex` is a second explicit profile change. Setting `agent-default-model` to `openai-codex` is also a separate explicit change.

package/README.md

@@ -28,7 +28,7 @@ dsh plugin --profile web add dsh-codex-connect@alpha
 
 Expected result: the package is added to that profile. This does not change the profile's default model or global search route.
 
-To reproduce this release exactly, use `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.7`. If npm is unavailable after the matching GitHub prerelease exists, use `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.7'`. A local checkout can be installed as `link:/absolute/path/to/dsh-codex-connect`.
+To reproduce this release exactly, use `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.8`. If npm is unavailable after the matching GitHub prerelease exists, use `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.8'`. A local checkout can be installed as `link:/absolute/path/to/dsh-codex-connect`.
 
 ### 2. Start Harness
 
@@ -149,12 +149,22 @@ Selecting Codex as the profile's global search route is another explicit change:
 - `doctor` reads process and filesystem metadata only. `doctor --json` emits exactly one secret-free JSON document with schema version 1, package/version/Node metadata, credential-file state and safe mode, capabilities, conflict status, and hints. It omits the absolute credential path and OAuth, account, and expiry data.
 - `status --json` emits only signed-in or signed-out state with package metadata. `status --json` reads the credential only to determine sign-in state, but never prints credential contents or starts OAuth.
 - OAuth is stored separately at `$DSH_HOME/.openai-codex-auth.json` (`~/.dsh` by default). `~/.codex/auth.json` is never copied or modified. The parent directory and file use owner-only permissions where supported, writes are atomic, and refresh writes use a cross-process file lock.
+- By default, the OAuth routes accept loopback browser requests only. When DSH runs on one device and you open it from another device on a trusted network, approve the browser address-bar origin explicitly on the device that runs DSH:
+
+  ```sh
+  dsh plugin --profile web exec dsh-codex-connect trust-origin http://192.168.1.20:3080
+  dsh plugin --profile web exec dsh-codex-connect trusted-origins
+  dsh plugin --profile web exec dsh-codex-connect untrust-origin http://192.168.1.20:3080
+  ```
+
+  Replace the example with the exact origin from the browser address bar, including scheme and port; do not enter the accessing device's IP, a bare host, a path, a query, or a fragment. Trust only a network you control, never expose this route to the public Internet, and use an SSH tunnel as the fallback when explicit network trust is not appropriate. The browser page only displays and copies this command; it never changes the allowlist itself.
 - If startup reports an `openai-codex` collision, an old `dsh-codex` bundle or manual provider row may already own the adapter. Inspect the effective configuration and remove only the confirmed conflicting owner. Do not delete auth files or unrelated providers.
 - Removing the package does not delete OAuth state. Run `logout` only when credential removal is intended.
 
 ## Compatibility and security boundary
 
-- Alpha compatibility targets the current Harness `0.1.0-rc.5` main-line composition and compatible `0.1.0-rc.6` plugin APIs, Node.js `^22.19.0 || >=24.0.0`, and the pinned `@earendil-works/pi-ai` Codex provider.
+- The only verified compatibility combination is DSH plugin API packages `0.1.0-rc.6`, `@earendil-works/pi-ai` `0.82.1`, and Node.js `^22.19.0 || >=24.0.0`; see [compatibility.json](compatibility.json).
+- Upgrade the DSH plugin API packages and `@earendil-works/pi-ai` as one group, then run `dsh-codex-connect doctor --json` and the compatibility check again. This contract does not make claims about future versions.
 - ChatGPT plan eligibility, model access, quotas, and backend behavior are controlled by OpenAI and may change.
 - The Codex endpoint does not enforce the ordinary Responses `max_output_tokens` field. Harness compaction still works, but that summary cap cannot be imposed server-side on this route.
 - Shell, filesystem, skills, MCP, subagents, approvals, permissions, attachments, session persistence, compaction, and recovery continue to come from the active Harness profile.
@@ -170,6 +180,10 @@ pnpm install --frozen-lockfile
 pnpm run check
 ```
 
+## Releases
+
+Maintainers publish alpha versions through the [manual OIDC release workflow](.github/workflows/release.yml); see the [alpha release runbook](RELEASING.md) for the separate, short-lived `latest` promotion step.
+
 ## Legal / Acknowledgements
 
 Copyright 2026 Frank Song for the modifications and additional work in Codex Connect. This project includes software derived from [Yan-Zero/dsh-codex](https://github.com/Yan-Zero/dsh-codex); Copyright 2026 Yan-Zero is retained for the upstream material. Both are distributed under Apache-2.0, with details in [NOTICE](NOTICE). This project is not affiliated with or endorsed by OpenAI, ChatGPT, Codex, DeepSeek, or DeepSeek Harness.

package/compatibility.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": 1,
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "dshPluginApi": {
+    "version": "0.1.0-rc.6",
+    "packages": [
+      "@deepseek-ai/dsh-agent",
+      "@deepseek-ai/dsh-atomic-write",
+      "@deepseek-ai/dsh-attachment",
+      "@deepseek-ai/dsh-home-paths",
+      "@deepseek-ai/dsh-host-webserver",
+      "@deepseek-ai/dsh-invariants",
+      "@deepseek-ai/dsh-llm",
+      "@deepseek-ai/dsh-llm-pi-ai",
+      "@deepseek-ai/dsh-fs",
+      "@deepseek-ai/dsh-session",
+      "@deepseek-ai/dsh-settings",
+      "@deepseek-ai/dsh-tools",
+      "@deepseek-ai/dsh-web"
+    ]
+  },
+  "piAi": {
+    "package": "@earendil-works/pi-ai",
+    "version": "0.82.1"
+  }
+}

package/docs/README.zh.md

@@ -28,7 +28,7 @@ dsh plugin --profile web add dsh-codex-connect@alpha
 
 预期结果：包被加入该 profile。这个动作不会更改 profile 的默认模型或全局搜索路由。
 
-如需精确复现这个版本，使用 `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.7`。对应 GitHub prerelease 已创建但 npm 不可用时，可使用 `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.7'`。本地 checkout 可安装为 `link:/absolute/path/to/dsh-codex-connect`。
+如需精确复现这个版本，使用 `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.8`。对应 GitHub prerelease 已创建但 npm 不可用时，可使用 `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.8'`。本地 checkout 可安装为 `link:/absolute/path/to/dsh-codex-connect`。
 
 ### 2. 启动 Harness
 
@@ -149,12 +149,22 @@ dsh plugin --profile web exec dsh-codex-connect doctor --json
 - `doctor` 只读取进程与文件系统元数据。`doctor --json` 只输出一条可解析的非敏感 JSON，包含 schema version 1、包/版本/Node 信息、认证文件状态与安全 mode、能力、冲突状态和提示；它省略认证文件绝对路径以及 OAuth、账户和过期时间信息。
 - `status --json` 只输出 signed-in 或 signed-out 状态及包元数据。它只为判断登录态读取认证文件，但不会输出认证文件内容或启动 OAuth。
 - OAuth 单独存储于 `$DSH_HOME/.openai-codex-auth.json`（默认 `~/.dsh`）。`~/.codex/auth.json` 不会被复制或修改。支持的平台上，父目录与文件使用仅所有者可访问权限；写入采用原子替换，刷新写入使用跨进程文件锁。
+- 默认情况下，OAuth 路由只接受 loopback 浏览器请求。当 DSH 在一台设备运行，而你从可信网络中的另一台设备打开 DSH 时，请在运行 DSH 的设备上显式批准浏览器地址栏中的 origin：
+
+  ```sh
+  dsh plugin --profile web exec dsh-codex-connect trust-origin http://192.168.1.20:3080
+  dsh plugin --profile web exec dsh-codex-connect trusted-origins
+  dsh plugin --profile web exec dsh-codex-connect untrust-origin http://192.168.1.20:3080
+  ```
+
+  将示例替换为浏览器地址栏中的精确 origin，包括协议和端口；不要填写当前访问设备的 IP、裸主机、路径、query 或 fragment。只在你信任的网络中使用，不要把该路由暴露到公网；不适合显式信任网络时，请使用 SSH tunnel。浏览器页面只会显示并复制这条命令，不会自行修改授权列表。
 - 启动报告 `openai-codex` 冲突时，旧 `dsh-codex` bundle 或手动 provider 配置可能已占用该 adapter。先检查有效配置，只移除已确认的冲突所有者。不要删除认证文件或无关 provider。
 - 移除包不会删除 OAuth 状态；只有确实需要删除凭据时才运行 `logout`。
 
 ## 兼容性与安全边界
 
-- Alpha 面向当前 Harness `0.1.0-rc.5` 主线组合与兼容的 `0.1.0-rc.6` 插件 API、Node.js `^22.19.0 || >=24.0.0` 和固定版本的 `@earendil-works/pi-ai` Codex provider。
+- 当前唯一已验证的兼容组合是 DSH 插件 API packages `0.1.0-rc.6`、`@earendil-works/pi-ai` `0.82.1` 和 Node.js `^22.19.0 || >=24.0.0`；详见 [compatibility.json](../compatibility.json)。
+- 升级时请将 DSH 插件 API packages 与 `@earendil-works/pi-ai` 作为一组升级，再运行 `dsh-codex-connect doctor --json` 和兼容性检查。本契约不对未来版本作判断。
 - ChatGPT 套餐资格、模型权限、额度和后端行为由 OpenAI 控制，可能变化。
 - Codex 端点不会强制普通 Responses 的 `max_output_tokens` 字段。Harness 压缩仍可工作，但这个摘要上限不能由服务端在该路由上强制。
 - shell、文件系统、skills、MCP、subagents、审批、权限、附件、会话持久化、压缩与恢复继续由当前 Harness profile 提供。
@@ -170,6 +180,10 @@ pnpm install --frozen-lockfile
 pnpm run check
 ```
 
+## 发布
+
+维护者通过[手动 OIDC 发布 workflow](../.github/workflows/release.yml)发布 Alpha；`latest` 的独立短期提升步骤见 [Alpha 发布清单](../RELEASING.md)。
+
 ## 法律与致谢
 
 Codex Connect 的修改与新增工作 Copyright 2026 Frank Song。本项目包含派生自 [Yan-Zero/dsh-codex](https://github.com/Yan-Zero/dsh-codex) 的软件；上游内容继续保留 Copyright 2026 Yan-Zero。两部分均按 Apache-2.0 发布，详情见 [NOTICE](../NOTICE)。本项目与 OpenAI、ChatGPT、Codex、DeepSeek 或 DeepSeek Harness 不存在隶属关系，也未获得其背书。

package/docs/design.md

@@ -10,9 +10,9 @@ The Host registers `llm-openai-codex` as the plugin-owned settings namespace and
 
 ## OAuth persistence
 
-The plugin uses `$DSH_HOME/.openai-codex-auth.json`, separate from Codex CLI/Desktop state. The file format is strict and versioned. POSIX reads reject group/world-accessible files. Parent directories and files are created with owner-only modes, writes are atomic, and refresh mutations use the Harness cross-process file lock. Callers receive cloned credentials.
+The plugin uses `$DSH_HOME/.openai-codex-auth.json`, separate from Codex CLI/Desktop state. The file format is strict and versioned. POSIX reads reject group/world-accessible files. Parent directories and files are created with owner-only modes, writes are atomic, and refresh mutations use the Harness cross-process file lock. Callers receive cloned credentials. Browser-origin trust is a separate `$DSH_HOME/.openai-codex-trusted-origins.json` sidecar with `version: 1`, `mode: "allowlist"`, and exact normalized HTTP(S) origins; it never contains OAuth material and is changed only by the standalone CLI.
 
-The settings routes and CLI reuse the existing OAuth path and route names for migration compatibility. Only an explicit login operation emits an authorization URL or code. Browser requests must come from a loopback peer with a loopback Host and, when supplied, an exact loopback HTTP(S) Origin. A login challenge accepts only credential-free HTTPS URLs and fails closed after 30 seconds or when the provider finishes without a URL; logout and disposal cancel pending waiters. Status responses are redacted. Doctor uses `lstat` metadata and never opens the document.
+The settings routes and CLI reuse the existing OAuth path and route names for migration compatibility. Only an explicit login operation emits an authorization URL or code. Browser requests are accepted by default only from loopback; a remote request must use an exact effective HTTP(S) origin in the current sidecar, must not carry cross-site Fetch Metadata, and must match any supplied Origin exactly. The sidecar is re-read for every request, and unknown fields or modes fail closed. A login challenge accepts only credential-free HTTPS URLs and fails closed after 30 seconds or when the provider finishes without a URL; logout and disposal cancel pending waiters. Status responses are redacted. Doctor uses `lstat` metadata and never opens the document.
 
 ## Search and images
 

package/docs/design.zh.md

@@ -10,9 +10,9 @@ Host 将 `llm-openai-codex` 注册为插件自有 settings namespace，并在 LL
 
 ## OAuth 持久化
 
-插件使用 `$DSH_HOME/.openai-codex-auth.json`，与 Codex CLI/Desktop 状态分离。文件格式严格且有版本号；POSIX 上会拒绝组/其他用户可读文件。父目录和文件按仅所有者权限创建，写入采用原子替换，刷新修改使用 Harness 跨进程文件锁，返回给调用方的是凭据副本。
+插件使用 `$DSH_HOME/.openai-codex-auth.json`，与 Codex CLI/Desktop 状态分离。文件格式严格且有版本号；POSIX 上会拒绝组/其他用户可读文件。父目录和文件按仅所有者权限创建，写入采用原子替换，刷新修改使用 Harness 跨进程文件锁，返回给调用方的是凭据副本。浏览器 origin 授权单独存放于 `$DSH_HOME/.openai-codex-trusted-origins.json`，格式为 `version: 1`、`mode: "allowlist"` 和规范化的精确 HTTP(S) origin；其中不含 OAuth 内容，且只能通过独立 CLI 修改。
 
-为兼容迁移，设置页路由、OAuth 路径和 provider id 不改名。浏览器请求必须来自 loopback 对端，并带有 loopback Host；若带 Origin，则必须与该本地 HTTP(S) 源精确匹配。登录挑战只接受不含凭据的 HTTPS 地址；30 秒内未得到地址、provider 已结束但没有地址、退出登录或插件卸载时，所有 waiter 都会被清理。只有显式登录会输出授权 URL 或代码；状态输出会脱敏。doctor 只用 `lstat` 检查元数据，不打开文件。
+为兼容迁移，设置页路由、OAuth 路径和 provider id 不改名。浏览器请求默认只允许 loopback；远程请求必须使用当前 sidecar 中的精确有效 HTTP(S) origin，不能带 cross-site Fetch Metadata，若带 Origin 还必须精确匹配。每次请求都会重新读取 sidecar；未知字段或错误 mode 会快速失败。登录挑战只接受不含凭据的 HTTPS 地址；30 秒内未得到地址、provider 已结束但没有地址、退出登录或插件卸载时，所有 waiter 都会被清理。只有显式登录会输出授权 URL 或代码；状态输出会脱敏。doctor 只用 `lstat` 检查元数据，不打开文件。
 
 ## 搜索与图片
 

package/lib/bin.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { A as loginOpenAICodex, E as CODEX_CONNECT_VERSION, I as openAICodexAuthPath, M as openAICodexAuthStatus, j as logoutOpenAICodex, w as diagnoseOpenAICodex } from "./src-Bk1Nq6B4.js";
+import { E as CODEX_CONNECT_VERSION, G as openAICodexAuthStatus, R as OpenAICodexTrustedOriginsStore, U as loginOpenAICodex, W as logoutOpenAICodex, Y as openAICodexAuthPath, w as diagnoseOpenAICodex, z as normalizeTrustedOrigin } from "./src-DztMY1zT.js";
+import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { realpathSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
-import { fileURLToPath } from "node:url";
 //#region src/bin.ts
 /** Standalone credential CLI for the optional OpenAI Codex bundle. */
 const JSON_SCHEMA_VERSION = 1;
@@ -65,22 +65,30 @@ async function answerPrompt(prompt, deviceCode, question) {
 function printHelp() {
 	process.stdout.write([
 		"Usage: dsh-codex-connect <doctor|login|logout|status> [--device-code|--json]",
+		"       dsh-codex-connect trust-origin <origin>",
+		"       dsh-codex-connect trusted-origins [--json]",
+		"       dsh-codex-connect untrust-origin <origin>",
 		"",
 		"  doctor         inspect secret-free runtime and OAuth file metadata",
 		"  login          sign in with a separate ChatGPT OAuth session",
 		"  logout         remove the dsh credential without changing ~/.codex",
 		"  status         report non-secret dsh credential state",
+		"  trust-origin   allow one exact browser origin to reach Web OAuth routes",
+		"  trusted-origins list the currently allowed browser origins",
+		"  untrust-origin remove one exact browser origin from the allowlist",
 		"  --device-code  use headless device-code login (login only)",
-		"  --json         emit one secret-free JSON document (doctor/status only)",
+		"  --json         emit one secret-free JSON document (doctor/status/trusted-origins only)",
 		""
 	].join("\n"));
 }
 function doctorExitCode(report) {
-	return report.credentialFile.state === "permissions-too-broad" || report.credentialFile.state === "not-a-regular-file" || report.credentialFile.state === "unreadable-metadata" ? 1 : 0;
+	const credentialFailure = report.credentialFile.state === "permissions-too-broad" || report.credentialFile.state === "not-a-regular-file" || report.credentialFile.state === "unreadable-metadata";
+	const compatibilityFailure = report.compatibility !== void 0 && report.compatibility.status !== "compatible";
+	return credentialFailure || compatibilityFailure ? 1 : 0;
 }
 /** Project the diagnostic report without its absolute credential pathname. */
 function doctorJson(report) {
-	return {
+	const result = {
 		schemaVersion: JSON_SCHEMA_VERSION,
 		package: report.package,
 		version: report.version,
@@ -93,6 +101,8 @@ function doctorJson(report) {
 		providerConflict: report.providerConflict,
 		hints: report.hints
 	};
+	if (report.compatibility !== void 0) result.compatibility = report.compatibility;
+	return result;
 }
 function printJson(value) {
 	process.stdout.write(`${JSON.stringify(value)}\n`);
@@ -104,14 +114,24 @@ async function run(argv) {
 		return 0;
 	}
 	const [rawAction, ...flags] = argv;
-	if (rawAction !== "doctor" && rawAction !== "login" && rawAction !== "logout" && rawAction !== "status") {
-		process.stderr.write(`dsh-codex-connect: expected doctor, login, logout, or status; got ${JSON.stringify(rawAction)}\n`);
+	if (![
+		"doctor",
+		"login",
+		"logout",
+		"status",
+		"trust-origin",
+		"trusted-origins",
+		"untrust-origin"
+	].includes(rawAction)) {
+		process.stderr.write(`dsh-codex-connect: expected doctor, login, logout, status, trust-origin, trusted-origins, or untrust-origin; got ${JSON.stringify(rawAction)}\n`);
 		return 1;
 	}
 	const action = rawAction;
-	const deviceCode = flags.includes("--device-code");
-	const jsonOutput = flags.includes("--json");
-	if (flags.filter((flag) => flag !== "--device-code" && flag !== "--json").length > 0 || deviceCode && action !== "login" || jsonOutput && (action === "login" || action === "logout" || deviceCode)) {
+	const originArgument = action === "trust-origin" || action === "untrust-origin" ? flags[0] : void 0;
+	const optionFlags = action === "trust-origin" || action === "untrust-origin" ? flags.slice(1) : flags;
+	const deviceCode = optionFlags.includes("--device-code");
+	const jsonOutput = optionFlags.includes("--json");
+	if (optionFlags.filter((flag) => flag !== "--device-code" && flag !== "--json").length > 0 || deviceCode && action !== "login" || jsonOutput && (action === "login" || action === "logout" || deviceCode) || (action === "trust-origin" || action === "untrust-origin") && (originArgument === void 0 || optionFlags.length !== 0)) {
 		process.stderr.write(`dsh-codex-connect: invalid options for ${action}: ${flags.join(" ")}\n`);
 		return 1;
 	}
@@ -126,6 +146,7 @@ async function run(argv) {
 				process.stdout.write([
 					`Codex Connect ${report.version} on ${report.node}`,
 					`OAuth file metadata: ${report.credentialFile.state} (${report.credentialFile.path})`,
+					...report.compatibility === void 0 ? [] : [`Compatibility: ${report.compatibility.status} (Node ${report.compatibility.node.installed ?? "unknown"}; DSH API ${report.compatibility.packages["@deepseek-ai/dsh-llm"].installed ?? "unknown"}; pi-ai ${report.compatibility.packages["@earendil-works/pi-ai"].installed ?? "unknown"})`],
 					`Optional capability defaults: search=${report.capabilities.search ? "enabled" : "disabled"}, imageTool=${report.capabilities.imageTool ? "enabled" : "disabled"}`,
 					"Harness defaults: unchanged by this plugin",
 					...report.hints.map((hint) => `Hint: ${hint}`),
@@ -153,6 +174,31 @@ async function run(argv) {
 				process.stdout.write(`Codex Connect: signed in${suffix}\n`);
 				return 0;
 			}
+			case "trusted-origins": {
+				const origins = await new OpenAICodexTrustedOriginsStore().list();
+				if (jsonOutput) printJson({
+					schemaVersion: JSON_SCHEMA_VERSION,
+					origins
+				});
+				else for (const origin of origins) process.stdout.write(`${origin}\n`);
+				return 0;
+			}
+			case "trust-origin": {
+				if (originArgument === void 0) return 1;
+				const normalized = normalizeTrustedOrigin(originArgument);
+				const origins = await new OpenAICodexTrustedOriginsStore().trust(originArgument);
+				process.stdout.write(`Trusted browser origin: ${normalized}\n`);
+				process.stdout.write(`Trusted origins: ${origins.join(", ") || "(none)"}\n`);
+				return 0;
+			}
+			case "untrust-origin": {
+				if (originArgument === void 0) return 1;
+				const normalized = normalizeTrustedOrigin(originArgument);
+				const origins = await new OpenAICodexTrustedOriginsStore().untrust(originArgument);
+				process.stdout.write(`Untrusted browser origin: ${normalized}\n`);
+				process.stdout.write(`Trusted origins: ${origins.join(", ") || "(none)"}\n`);
+				return 0;
+			}
 			case "logout":
 				await logoutOpenAICodex();
 				process.stdout.write(`Codex Connect: signed out; removed ${openAICodexAuthPath()}\n`);

package/lib/client.js

@@ -573,6 +573,19 @@ window.__ModuleLoader__.load({
 			borderRadius: 999,
 			background: "var(--dsw-alias-bg-layer-2, rgba(0, 0, 0, 0.08))"
 		};
+		const commandStyle = {
+			margin: 0,
+			padding: "10px 12px",
+			overflowX: "auto",
+			borderRadius: 8,
+			background: "var(--dsw-alias-bg-layer-2, rgba(0, 0, 0, 0.06))",
+			color: "var(--dsw-alias-label-primary)",
+			fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+			fontSize: 13,
+			lineHeight: "20px",
+			whiteSpace: "pre-wrap",
+			overflowWrap: "anywhere"
+		};
 		function progressFillStyle(percent) {
 			return {
 				width: `${Math.max(0, Math.min(100, percent))}%`,
@@ -666,9 +679,17 @@ window.__ModuleLoader__.load({
 				height: 9,
 				borderRadius: "50%",
 				flex: "0 0 auto",
-				background: status === "signed-in" ? "var(--dsw-alias-state-success-primary, #22a06b)" : status === "error" || status === "reauth-required" ? "var(--dsw-alias-state-error-primary, #d92d20)" : status === "signing-in" || status === "loading" ? "var(--dsw-alias-brand-primary, #1677ff)" : "var(--dsw-alias-label-dimmed, #9aa0a6)"
+				background: status === "signed-in" ? "var(--dsw-alias-state-success-primary, #22a06b)" : status === "error" || status === "reauth-required" || status === "remote-web-origin-not-trusted" ? "var(--dsw-alias-state-error-primary, #d92d20)" : status === "signing-in" || status === "loading" ? "var(--dsw-alias-brand-primary, #1677ff)" : "var(--dsw-alias-label-dimmed, #9aa0a6)"
 			};
 		}
+		var AccountRequestError = class extends Error {
+			code;
+			constructor(code, message) {
+				super(message);
+				this.code = code;
+				this.name = "AccountRequestError";
+			}
+		};
 		async function jsonRequest(path, method = "GET", signal) {
 			const response = await fetch(path, {
 				method,
@@ -678,8 +699,8 @@ window.__ModuleLoader__.load({
 			});
 			const value = await response.json().catch(() => void 0);
 			if (!response.ok) {
-				const message = typeof value === "object" && value !== null && "error" in value && typeof value.error === "string" ? value.error : `HTTP ${response.status}`;
-				throw new Error(message);
+				const code = typeof value === "object" && value !== null && "error" in value && typeof value.error === "string" ? value.error : `HTTP ${response.status}`;
+				throw new AccountRequestError(code, code);
 			}
 			return value;
 		}
@@ -688,7 +709,10 @@ window.__ModuleLoader__.load({
 			if (t === void 0) throw new Error("OpenAI Codex settings requires its translation function");
 			const [status, setStatus] = (0, react.useState)({ status: "loading" });
 			const [busy, setBusy] = (0, react.useState)(false);
+			const [copied, setCopied] = (0, react.useState)(false);
+			const [copyFailed, setCopyFailed] = (0, react.useState)(false);
 			const mounted = (0, react.useRef)(true);
+			const trustedOriginCommand = `dsh plugin --profile web exec dsh-codex-connect trust-origin ${window.location.origin}`;
 			(0, react.useEffect)(() => {
 				mounted.current = true;
 				return () => {
@@ -700,7 +724,7 @@ window.__ModuleLoader__.load({
 					const nextStatus = await jsonRequest(OPENAI_CODEX_AUTH_STATUS_PATH, "GET", signal);
 					if (mounted.current && signal?.aborted !== true) setStatus(nextStatus);
 				} catch (error) {
-					if (mounted.current && signal?.aborted !== true) setStatus({
+					if (mounted.current && signal?.aborted !== true) setStatus(error instanceof AccountRequestError && error.code === "remote-web-origin-not-trusted" ? { status: "remote-web-origin-not-trusted" } : {
 						status: "error",
 						message: error instanceof Error ? error.message : t("requestFailed")
 					});
@@ -746,7 +770,7 @@ window.__ModuleLoader__.load({
 					popup.location.replace(challenge.url);
 				} catch (error) {
 					popup?.close();
-					if (mounted.current) setStatus({
+					if (mounted.current) setStatus(error instanceof AccountRequestError && error.code === "remote-web-origin-not-trusted" ? { status: "remote-web-origin-not-trusted" } : {
 						status: "error",
 						message: error instanceof Error ? error.message : t("requestFailed")
 					});
@@ -754,6 +778,16 @@ window.__ModuleLoader__.load({
 					if (mounted.current) setBusy(false);
 				}
 			};
+			const copyTrustedOriginCommand = async () => {
+				setCopyFailed(false);
+				try {
+					if (navigator.clipboard?.writeText === void 0) throw new Error("clipboard unavailable");
+					await navigator.clipboard.writeText(trustedOriginCommand);
+					if (mounted.current) setCopied(true);
+				} catch {
+					if (mounted.current) setCopyFailed(true);
+				}
+			};
 			const signOut = async () => {
 				setBusy(true);
 				try {
@@ -768,7 +802,7 @@ window.__ModuleLoader__.load({
 					if (mounted.current) setBusy(false);
 				}
 			};
-			const label = status.status === "signed-in" ? t("signedIn") : status.status === "loading" ? t("loadingAccount") : status.status === "signing-in" ? t("signingIn") : status.status === "reauth-required" ? t("reauthRequired") : status.status === "error" ? t("requestFailed") : t("signedOut");
+			const label = status.status === "signed-in" ? t("signedIn") : status.status === "loading" ? t("loadingAccount") : status.status === "signing-in" ? t("signingIn") : status.status === "reauth-required" ? t("reauthRequired") : status.status === "remote-web-origin-not-trusted" ? t("remoteOriginTitle") : status.status === "error" ? t("requestFailed") : t("signedOut");
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("section", {
 				style: embedded ? embeddedPageStyle : pageStyle,
 				...embedded ? { "aria-label": t("title") } : { "aria-labelledby": "openai-codex-settings-title" },
@@ -798,7 +832,7 @@ window.__ModuleLoader__.load({
 									"aria-hidden": "true",
 									style: dotStyle(status.status)
 								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: label })]
-							}), status.status === "loading" ? null : status.status === "signed-in" ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+							}), status.status === "loading" || status.status === "remote-web-origin-not-trusted" ? null : status.status === "signed-in" ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 								type: "button",
 								style: buttonStyle,
 								disabled: busy,
@@ -820,6 +854,41 @@ window.__ModuleLoader__.load({
 							style: errorStyle,
 							children: status.message
 						}) : null,
+						status.status === "remote-web-origin-not-trusted" ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+							style: {
+								display: "flex",
+								flexDirection: "column",
+								gap: 10
+							},
+							children: [
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+									style: errorStyle,
+									children: t("remoteOriginDescription")
+								}),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+									style: bodyStyle,
+									children: t("remoteOriginCommandHelp")
+								}),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("code", {
+									style: commandStyle,
+									children: trustedOriginCommand
+								}),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+									style: rowStyle,
+									children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+										type: "button",
+										style: buttonStyle,
+										onClick: () => {
+											copyTrustedOriginCommand();
+										},
+										children: copied ? t("remoteOriginCopied") : t("remoteOriginCopy")
+									}), copyFailed ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+										style: errorStyle,
+										children: t("remoteOriginCopyFailed")
+									}) : null]
+								})
+							]
+						}) : null,
 						status.status === "signed-in" ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(UsageLimits, {
 							usage: status.usage,
 							...status.quotaError === void 0 ? {} : { quotaError: status.quotaError },
@@ -958,6 +1027,12 @@ window.__ModuleLoader__.load({
 			available: "Available",
 			quotaUnavailable: "Usage limits are temporarily unavailable.",
 			requestFailed: "The OpenAI Codex account request failed.",
+			remoteOriginTitle: "Remote browser origin is not trusted",
+			remoteOriginDescription: "Codex Connect accepts browser OAuth requests only from trusted local pages or origins explicitly approved by the device owner.",
+			remoteOriginCommandHelp: "Run this command manually on the device that runs DSH, then reload this page. This page never runs it:",
+			remoteOriginCopy: "Copy trust command",
+			remoteOriginCopied: "Copied",
+			remoteOriginCopyFailed: "Copy was unavailable. Copy the command manually.",
 			capabilitiesHeading: "Optional capabilities",
 			capabilitiesIntro: "Choose which extra Codex capabilities this dsh profile may register.",
 			enableSearch: "Enable Codex search provider",
@@ -1017,6 +1092,12 @@ window.__ModuleLoader__.load({
 			available: "可用",
 			quotaUnavailable: "暂时无法获取使用额度。",
 			requestFailed: "OpenAI Codex 账户请求失败。",
+			remoteOriginTitle: "未信任远程浏览器 origin",
+			remoteOriginDescription: "Codex Connect 只接受来自本机页面或设备所有者明确批准的 origin 的浏览器 OAuth 请求。",
+			remoteOriginCommandHelp: "请在运行 DSH 的设备上手动执行下面的服务器命令，然后重新加载此页面。本页面不会自动执行：",
+			remoteOriginCopy: "复制授权命令",
+			remoteOriginCopied: "已复制",
+			remoteOriginCopyFailed: "当前无法访问剪贴板，请手动复制命令。",
 			capabilitiesHeading: "可选能力",
 			capabilitiesIntro: "选择允许此 dsh profile 注册哪些额外的 Codex 能力。",
 			enableSearch: "启用 Codex 搜索提供方",

package/lib/index.d.ts

@@ -7,6 +7,68 @@ import { Context } from "@deepseek-ai/cordis";
 /** Stable Codex tool name. */
 declare const VIEW_IMAGE_TOOL_NAME = "view_image";
 //#endregion
+//#region src/compatibility.d.ts
+declare const COMPATIBILITY_SCHEMA_VERSION: 1;
+declare const SUPPORTED_NODE_RANGE = "^22.19.0 || >=24.0.0";
+declare const SUPPORTED_DSH_PLUGIN_API_VERSION = "0.1.0-rc.6";
+declare const SUPPORTED_PI_AI_VERSION = "0.82.1";
+declare const PI_AI_PACKAGE = "@earendil-works/pi-ai";
+declare const DSH_PLUGIN_API_PACKAGES: readonly ["@deepseek-ai/dsh-agent", "@deepseek-ai/dsh-atomic-write", "@deepseek-ai/dsh-attachment", "@deepseek-ai/dsh-home-paths", "@deepseek-ai/dsh-host-webserver", "@deepseek-ai/dsh-invariants", "@deepseek-ai/dsh-llm", "@deepseek-ai/dsh-llm-pi-ai", "@deepseek-ai/dsh-fs", "@deepseek-ai/dsh-session", "@deepseek-ai/dsh-settings", "@deepseek-ai/dsh-tools", "@deepseek-ai/dsh-web"];
+declare const COMPATIBILITY_PACKAGES: readonly ["@deepseek-ai/dsh-llm", "@deepseek-ai/dsh-llm-pi-ai", "@earendil-works/pi-ai"];
+type CompatibilityPackageName = (typeof COMPATIBILITY_PACKAGES)[number];
+type CompatibilityStatus = 'compatible' | 'incompatible' | 'unknown';
+interface CompatibilityEntry {
+  supported: string;
+  installed: string | null;
+  status: CompatibilityStatus;
+}
+interface CompatibilityReport {
+  schemaVersion: typeof COMPATIBILITY_SCHEMA_VERSION;
+  status: CompatibilityStatus;
+  node: CompatibilityEntry;
+  packages: Record<CompatibilityPackageName, CompatibilityEntry>;
+}
+interface CompatibilityEvaluationInput {
+  /** Node version to evaluate; defaults to the running process in detectCompatibility. */
+  nodeVersion?: string | null;
+  /** Alias accepted by callers that already group installed values. */
+  node?: string | null;
+  /** Installed package versions keyed by package name. */
+  packageVersions?: Partial<Record<CompatibilityPackageName, string | null | undefined>>;
+  /** Alias accepted by callers that already group installed values. */
+  packages?: Partial<Record<CompatibilityPackageName, string | null | undefined>>;
+  /** Nested installed values are useful when feeding a captured diagnostic fixture. */
+  installed?: {
+    node?: string | null;
+    packages?: Partial<Record<CompatibilityPackageName, string | null | undefined>>;
+  };
+}
+interface CompatibilityDetectionOptions extends CompatibilityEvaluationInput {
+  /** Test seam for package metadata resolution; no package paths are returned. */
+  readPackageVersion?: (name: CompatibilityPackageName) => string | null | undefined | Promise<string | null | undefined>;
+}
+/** Public contract data mirrored by compatibility.json without importing JSON at runtime. */
+declare const COMPATIBILITY_CONTRACT: {
+  readonly schemaVersion: 1;
+  readonly engines: {
+    readonly node: "^22.19.0 || >=24.0.0";
+  };
+  readonly dshPluginApi: {
+    readonly version: "0.1.0-rc.6";
+    readonly packages: readonly ["@deepseek-ai/dsh-agent", "@deepseek-ai/dsh-atomic-write", "@deepseek-ai/dsh-attachment", "@deepseek-ai/dsh-home-paths", "@deepseek-ai/dsh-host-webserver", "@deepseek-ai/dsh-invariants", "@deepseek-ai/dsh-llm", "@deepseek-ai/dsh-llm-pi-ai", "@deepseek-ai/dsh-fs", "@deepseek-ai/dsh-session", "@deepseek-ai/dsh-settings", "@deepseek-ai/dsh-tools", "@deepseek-ai/dsh-web"];
+  };
+  readonly piAi: {
+    readonly package: "@earendil-works/pi-ai";
+    readonly version: "0.82.1";
+  };
+};
+/** Evaluate a captured set of versions without touching the filesystem. */
+declare function evaluateCompatibility(input?: CompatibilityEvaluationInput): CompatibilityReport;
+/** Alias for callers that prefer assessment terminology. */
+declare const assessCompatibility: typeof evaluateCompatibility;
+/** Read installed package metadata and return only versions and statuses. */
+declare function detectCompatibility(options?: CompatibilityDetectionOptions): Promise<CompatibilityReport>;
+//#endregion
 //#region src/doctor.d.ts
 /** Inputs that are safe to obtain without booting OAuth. */
 interface OpenAICodexDiagnosticOptions {
@@ -18,6 +80,8 @@ interface OpenAICodexDiagnosticOptions {
   enableSearch?: boolean;
   /** Whether the optional image tool is enabled. */
   enableImageTool?: boolean;
+  /** Optional pure-function seam for compatibility checks in tests/diagnostic callers. */
+  compatibilityOptions?: CompatibilityDetectionOptions;
 }
 interface OpenAICodexDiagnosticReport {
   package: 'dsh-codex-connect';
@@ -36,6 +100,7 @@ interface OpenAICodexDiagnosticReport {
     changesHarnessSearchRoute: false;
   };
   providerConflict: boolean;
+  compatibility: CompatibilityReport;
   hints: string[];
 }
 /** Actionable message for legacy/manual `openai-codex` adapter collisions. */
@@ -330,4 +395,4 @@ declare const Config: z<Config>;
  */
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { Config, DEFAULT_OPENAI_CODEX_SEARCH_CONTEXT_SIZE, DEFAULT_OPENAI_CODEX_SEARCH_MAX_OUTPUT_TOKENS, DEFAULT_OPENAI_CODEX_SEARCH_MODE, DEFAULT_OPENAI_CODEX_SEARCH_MODEL, DEFAULT_OPENAI_CODEX_SETTINGS, OPENAI_CODEX_AUTH_FILENAME, OPENAI_CODEX_BASE_URL, OPENAI_CODEX_PROVIDER, OPENAI_CODEX_SEARCH_MODEL_REQUEST_EVENT, OPENAI_CODEX_SEARCH_PROVIDER, OPENAI_CODEX_SEARCH_URL, OPENAI_CODEX_SETTINGS_NAMESPACE, OPENAI_CODEX_SETTINGS_NS, OPENAI_CODEX_USAGE_URL, type OpenAICodexAuthStatus, OpenAICodexCredentialStore, type OpenAICodexCredits, type OpenAICodexDiagnosticOptions, type OpenAICodexDiagnosticReport, type OpenAICodexIndividualLimit, type OpenAICodexRateLimit, type OpenAICodexRateLimitWindow, type OpenAICodexSearchContextSize, type OpenAICodexSearchMode, OpenAICodexSearchProvider, type OpenAICodexSearchProviderOptions, type OpenAICodexSearchRequestRecord, type OpenAICodexSettingsConfig, type OpenAICodexUsage, VIEW_IMAGE_TOOL_NAME, apply, assertNoOpenAICodexProviderConflict, decodeOpenAICodexSettings, diagnoseOpenAICodex, inject, installOpenAICodexSearchEvent, loginOpenAICodex, logoutOpenAICodex, mapOpenAICodexSearchResponse, name, openAICodexAuthPath, openAICodexAuthStatus, openAICodexConflictMessage, parseOpenAICodexUsage, readOpenAICodexRateLimits, recordOpenAICodexSearchRequest, resolveOpenAICodexSettings };
+export { COMPATIBILITY_CONTRACT, COMPATIBILITY_PACKAGES, COMPATIBILITY_SCHEMA_VERSION, type CompatibilityDetectionOptions, type CompatibilityEntry, type CompatibilityEvaluationInput, type CompatibilityPackageName, type CompatibilityReport, type CompatibilityStatus, Config, DEFAULT_OPENAI_CODEX_SEARCH_CONTEXT_SIZE, DEFAULT_OPENAI_CODEX_SEARCH_MAX_OUTPUT_TOKENS, DEFAULT_OPENAI_CODEX_SEARCH_MODE, DEFAULT_OPENAI_CODEX_SEARCH_MODEL, DEFAULT_OPENAI_CODEX_SETTINGS, DSH_PLUGIN_API_PACKAGES, OPENAI_CODEX_AUTH_FILENAME, OPENAI_CODEX_BASE_URL, OPENAI_CODEX_PROVIDER, OPENAI_CODEX_SEARCH_MODEL_REQUEST_EVENT, OPENAI_CODEX_SEARCH_PROVIDER, OPENAI_CODEX_SEARCH_URL, OPENAI_CODEX_SETTINGS_NAMESPACE, OPENAI_CODEX_SETTINGS_NS, OPENAI_CODEX_USAGE_URL, type OpenAICodexAuthStatus, OpenAICodexCredentialStore, type OpenAICodexCredits, type OpenAICodexDiagnosticOptions, type OpenAICodexDiagnosticReport, type OpenAICodexIndividualLimit, type OpenAICodexRateLimit, type OpenAICodexRateLimitWindow, type OpenAICodexSearchContextSize, type OpenAICodexSearchMode, OpenAICodexSearchProvider, type OpenAICodexSearchProviderOptions, type OpenAICodexSearchRequestRecord, type OpenAICodexSettingsConfig, type OpenAICodexUsage, PI_AI_PACKAGE, SUPPORTED_DSH_PLUGIN_API_VERSION, SUPPORTED_NODE_RANGE, SUPPORTED_PI_AI_VERSION, VIEW_IMAGE_TOOL_NAME, apply, assertNoOpenAICodexProviderConflict, assessCompatibility, decodeOpenAICodexSettings, detectCompatibility, diagnoseOpenAICodex, evaluateCompatibility, inject, installOpenAICodexSearchEvent, loginOpenAICodex, logoutOpenAICodex, mapOpenAICodexSearchResponse, name, openAICodexAuthPath, openAICodexAuthStatus, openAICodexConflictMessage, parseOpenAICodexUsage, readOpenAICodexRateLimits, recordOpenAICodexSearchRequest, resolveOpenAICodexSettings };

package/lib/index.js

@@ -1,2 +1,2 @@
-import { A as loginOpenAICodex, C as assertNoOpenAICodexProviderConflict, D as OPENAI_CODEX_USAGE_URL, F as OpenAICodexCredentialStore, I as openAICodexAuthPath, M as openAICodexAuthStatus, N as OPENAI_CODEX_AUTH_FILENAME, O as parseOpenAICodexUsage, P as OPENAI_CODEX_PROVIDER, S as VIEW_IMAGE_TOOL_NAME, T as openAICodexConflictMessage, _ as decodeOpenAICodexSettings, a as name, b as installOpenAICodexSearchEvent, c as OPENAI_CODEX_SEARCH_URL, d as DEFAULT_OPENAI_CODEX_SEARCH_CONTEXT_SIZE, f as DEFAULT_OPENAI_CODEX_SEARCH_MAX_OUTPUT_TOKENS, g as OPENAI_CODEX_SETTINGS_NAMESPACE, h as DEFAULT_OPENAI_CODEX_SETTINGS, i as inject, j as logoutOpenAICodex, k as readOpenAICodexRateLimits, l as OpenAICodexSearchProvider, m as DEFAULT_OPENAI_CODEX_SEARCH_MODEL, n as OPENAI_CODEX_SETTINGS_NS, o as OPENAI_CODEX_BASE_URL, p as DEFAULT_OPENAI_CODEX_SEARCH_MODE, r as apply, s as OPENAI_CODEX_SEARCH_PROVIDER, t as Config, u as mapOpenAICodexSearchResponse, v as resolveOpenAICodexSettings, w as diagnoseOpenAICodex, x as recordOpenAICodexSearchRequest, y as OPENAI_CODEX_SEARCH_MODEL_REQUEST_EVENT } from "./src-Bk1Nq6B4.js";
-export { Config, DEFAULT_OPENAI_CODEX_SEARCH_CONTEXT_SIZE, DEFAULT_OPENAI_CODEX_SEARCH_MAX_OUTPUT_TOKENS, DEFAULT_OPENAI_CODEX_SEARCH_MODE, DEFAULT_OPENAI_CODEX_SEARCH_MODEL, DEFAULT_OPENAI_CODEX_SETTINGS, OPENAI_CODEX_AUTH_FILENAME, OPENAI_CODEX_BASE_URL, OPENAI_CODEX_PROVIDER, OPENAI_CODEX_SEARCH_MODEL_REQUEST_EVENT, OPENAI_CODEX_SEARCH_PROVIDER, OPENAI_CODEX_SEARCH_URL, OPENAI_CODEX_SETTINGS_NAMESPACE, OPENAI_CODEX_SETTINGS_NS, OPENAI_CODEX_USAGE_URL, OpenAICodexCredentialStore, OpenAICodexSearchProvider, VIEW_IMAGE_TOOL_NAME, apply, assertNoOpenAICodexProviderConflict, decodeOpenAICodexSettings, diagnoseOpenAICodex, inject, installOpenAICodexSearchEvent, loginOpenAICodex, logoutOpenAICodex, mapOpenAICodexSearchResponse, name, openAICodexAuthPath, openAICodexAuthStatus, openAICodexConflictMessage, parseOpenAICodexUsage, readOpenAICodexRateLimits, recordOpenAICodexSearchRequest, resolveOpenAICodexSettings };
+import { A as DSH_PLUGIN_API_PACKAGES, B as OPENAI_CODEX_USAGE_URL, C as assertNoOpenAICodexProviderConflict, D as COMPATIBILITY_CONTRACT, F as assessCompatibility, G as openAICodexAuthStatus, H as readOpenAICodexRateLimits, I as detectCompatibility, J as OpenAICodexCredentialStore, K as OPENAI_CODEX_AUTH_FILENAME, L as evaluateCompatibility, M as SUPPORTED_DSH_PLUGIN_API_VERSION, N as SUPPORTED_NODE_RANGE, O as COMPATIBILITY_PACKAGES, P as SUPPORTED_PI_AI_VERSION, S as VIEW_IMAGE_TOOL_NAME, T as openAICodexConflictMessage, U as loginOpenAICodex, V as parseOpenAICodexUsage, W as logoutOpenAICodex, Y as openAICodexAuthPath, _ as decodeOpenAICodexSettings, a as name, b as installOpenAICodexSearchEvent, c as OPENAI_CODEX_SEARCH_URL, d as DEFAULT_OPENAI_CODEX_SEARCH_CONTEXT_SIZE, f as DEFAULT_OPENAI_CODEX_SEARCH_MAX_OUTPUT_TOKENS, g as OPENAI_CODEX_SETTINGS_NAMESPACE, h as DEFAULT_OPENAI_CODEX_SETTINGS, i as inject, j as PI_AI_PACKAGE, k as COMPATIBILITY_SCHEMA_VERSION, l as OpenAICodexSearchProvider, m as DEFAULT_OPENAI_CODEX_SEARCH_MODEL, n as OPENAI_CODEX_SETTINGS_NS, o as OPENAI_CODEX_BASE_URL, p as DEFAULT_OPENAI_CODEX_SEARCH_MODE, q as OPENAI_CODEX_PROVIDER, r as apply, s as OPENAI_CODEX_SEARCH_PROVIDER, t as Config, u as mapOpenAICodexSearchResponse, v as resolveOpenAICodexSettings, w as diagnoseOpenAICodex, x as recordOpenAICodexSearchRequest, y as OPENAI_CODEX_SEARCH_MODEL_REQUEST_EVENT } from "./src-DztMY1zT.js";
+export { COMPATIBILITY_CONTRACT, COMPATIBILITY_PACKAGES, COMPATIBILITY_SCHEMA_VERSION, Config, DEFAULT_OPENAI_CODEX_SEARCH_CONTEXT_SIZE, DEFAULT_OPENAI_CODEX_SEARCH_MAX_OUTPUT_TOKENS, DEFAULT_OPENAI_CODEX_SEARCH_MODE, DEFAULT_OPENAI_CODEX_SEARCH_MODEL, DEFAULT_OPENAI_CODEX_SETTINGS, DSH_PLUGIN_API_PACKAGES, OPENAI_CODEX_AUTH_FILENAME, OPENAI_CODEX_BASE_URL, OPENAI_CODEX_PROVIDER, OPENAI_CODEX_SEARCH_MODEL_REQUEST_EVENT, OPENAI_CODEX_SEARCH_PROVIDER, OPENAI_CODEX_SEARCH_URL, OPENAI_CODEX_SETTINGS_NAMESPACE, OPENAI_CODEX_SETTINGS_NS, OPENAI_CODEX_USAGE_URL, OpenAICodexCredentialStore, OpenAICodexSearchProvider, PI_AI_PACKAGE, SUPPORTED_DSH_PLUGIN_API_VERSION, SUPPORTED_NODE_RANGE, SUPPORTED_PI_AI_VERSION, VIEW_IMAGE_TOOL_NAME, apply, assertNoOpenAICodexProviderConflict, assessCompatibility, decodeOpenAICodexSettings, detectCompatibility, diagnoseOpenAICodex, evaluateCompatibility, inject, installOpenAICodexSearchEvent, loginOpenAICodex, logoutOpenAICodex, mapOpenAICodexSearchResponse, name, openAICodexAuthPath, openAICodexAuthStatus, openAICodexConflictMessage, parseOpenAICodexUsage, readOpenAICodexRateLimits, recordOpenAICodexSearchRequest, resolveOpenAICodexSettings };

package/lib/{src-Bk1Nq6B4.js → src-DztMY1zT.js}

@@ -6,9 +6,10 @@ import { openaiCodexProvider } from "@earendil-works/pi-ai/providers/openai-code
 import { createUserMessage, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
 import { PiAiAdapter } from "@deepseek-ai/dsh-llm-pi-ai";
 import { lstat, mkdir, readFile, rm, stat } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, join, parse, resolve } from "node:path";
 import { withFileLock, writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
 import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
+import { fileURLToPath } from "node:url";
 import { AttachmentId } from "@deepseek-ai/dsh-attachment";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { lookup } from "node:dns/promises";
@@ -29,16 +30,16 @@ const OPENAI_CODEX_AUTH_FILENAME = ".openai-codex-auth.json";
 /** Current on-disk format; pre-release readers reject every other version. */
 const AUTH_FORMAT_VERSION = 1;
 /** Whether a filesystem error reports an absent path. */
-function isENOENT(error) {
+function isENOENT$1(error) {
 	return error?.code === "ENOENT";
 }
 /** Reject a credential document readable by another POSIX user. */
-async function assertOwnerOnly(filename) {
+async function assertOwnerOnly$1(filename) {
 	let mode;
 	try {
 		mode = (await stat(filename)).mode;
 	} catch (error) {
-		if (isENOENT(error)) return;
+		if (isENOENT$1(error)) return;
 		throw error;
 	}
 	/* v8 ignore next -- native Windows coverage takes the mode-less branch */
@@ -48,7 +49,7 @@ async function assertOwnerOnly(filename) {
 	/* v8 ignore stop */
 }
 /** Validate the strict JSON document without quoting token-bearing input. */
-function parseDocument(text, filename) {
+function parseDocument$1(text, filename) {
 	let value;
 	try {
 		value = JSON.parse(text);
@@ -105,15 +106,15 @@ var OpenAICodexCredentialStore = class {
 	}
 	/** Read and validate the current document without acquiring the writer lock. */
 	async readCurrent() {
-		await assertOwnerOnly(this.filename);
+		await assertOwnerOnly$1(this.filename);
 		let text;
 		try {
 			text = await readFile(this.filename, "utf8");
 		} catch (error) {
-			if (isENOENT(error)) return void 0;
+			if (isENOENT$1(error)) return void 0;
 			throw error;
 		}
-		return cloneCredential(parseDocument(text, this.filename).credential);
+		return cloneCredential(parseDocument$1(text, this.filename).credential);
 	}
 	/** @inheritdoc */
 	async read(providerId) {
@@ -137,7 +138,7 @@ var OpenAICodexCredentialStore = class {
 			const current = await this.readCurrent();
 			const candidate = await fn(current);
 			if (candidate === void 0) return current;
-			const document = parseDocument(JSON.stringify({
+			const document = parseDocument$1(JSON.stringify({
 				version: AUTH_FORMAT_VERSION,
 				credential: candidate
 			}), this.filename);
@@ -405,6 +406,172 @@ const OPENAI_CODEX_AUTH_STATUS_PATH = "/plugins/dsh-openai-codex/auth/status";
 const OPENAI_CODEX_AUTH_LOGIN_PATH = "/plugins/dsh-openai-codex/auth/login";
 /** Plugin-owned logout endpoint consumed by its browser half. */
 const OPENAI_CODEX_AUTH_LOGOUT_PATH = "/plugins/dsh-openai-codex/auth/logout";
+//#endregion
+//#region src/trusted-origins.ts
+/** Owner-only allowlist for browser origins that may reach the Web OAuth routes. */
+/** Basename of the DSH-home-scoped browser-origin allowlist. */
+const OPENAI_CODEX_TRUSTED_ORIGINS_FILENAME = ".openai-codex-trusted-origins.json";
+/** Only supported policy mode; a future mode must not be silently accepted. */
+const TRUSTED_ORIGINS_MODE = "allowlist";
+/** Whether a filesystem error reports an absent path. */
+function isENOENT(error) {
+	return error?.code === "ENOENT";
+}
+/** Reject a sidecar readable by another POSIX user. */
+async function assertOwnerOnly(filename) {
+	let metadata;
+	try {
+		metadata = await lstat(filename);
+	} catch (error) {
+		if (isENOENT(error)) return;
+		throw error;
+	}
+	if (!metadata.isFile()) throw new Error(`openai-codex: ${filename} is not a regular file`);
+	/* v8 ignore next -- native Windows coverage takes the mode-less branch */
+	if (process.platform === "win32") return;
+	/* v8 ignore start -- POSIX tests cover this branch; Windows cannot express it */
+	if ((metadata.mode & 63) !== 0) throw new Error(`openai-codex: ${filename} is readable beyond its owner (mode ${(metadata.mode & 511).toString(8)}); run "chmod 600 ${filename}" before starting again`);
+	/* v8 ignore stop */
+}
+/** Reject malformed input without echoing its contents into an error. */
+function parseDocument(text, filename) {
+	let value;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		throw new Error(`openai-codex: ${filename} is not valid JSON`);
+	}
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`openai-codex: ${filename} must contain an object`);
+	const document = value;
+	if (Object.keys(document).some((key) => ![
+		"version",
+		"mode",
+		"origins"
+	].includes(key))) throw new Error(`openai-codex: ${filename} contains an unknown top-level field`);
+	if (document["version"] !== 1) throw new Error(`openai-codex: ${filename} has unsupported trusted-origins format version ${String(document["version"])}`);
+	if (document["mode"] !== "allowlist") throw new Error(`openai-codex: ${filename} has unsupported trusted-origins mode`);
+	const rawOrigins = document["origins"];
+	if (!Array.isArray(rawOrigins)) throw new Error(`openai-codex: ${filename} origins must be an array`);
+	const origins = /* @__PURE__ */ new Set();
+	for (const rawOrigin of rawOrigins) {
+		if (typeof rawOrigin !== "string") throw new Error(`openai-codex: ${filename} origins must contain strings`);
+		try {
+			origins.add(normalizeTrustedOrigin(rawOrigin));
+		} catch {
+			throw new Error(`openai-codex: ${filename} contains an invalid trusted origin`);
+		}
+	}
+	return {
+		version: 1,
+		mode: TRUSTED_ORIGINS_MODE,
+		origins: [...origins].sort()
+	};
+}
+/**
+* Normalize one exact browser origin.
+*
+* Only HTTP(S) origins are accepted. Credentials, non-root paths, queries,
+* fragments, wildcards, and CIDR-looking host paths are rejected. WHATWG URL
+* normalization lowercases the scheme/host and removes default ports.
+*/
+function normalizeTrustedOrigin(rawOrigin) {
+	if (typeof rawOrigin !== "string" || rawOrigin.length === 0 || rawOrigin.trim() !== rawOrigin) throw new Error("trusted origin must be a non-empty URL without surrounding whitespace");
+	let origin;
+	try {
+		origin = new URL(rawOrigin);
+	} catch {
+		throw new Error("trusted origin must be a valid URL");
+	}
+	if (origin.protocol !== "http:" && origin.protocol !== "https:") throw new Error("trusted origin protocol must be http or https");
+	if (origin.username !== "" || origin.password !== "") throw new Error("trusted origin must not contain credentials");
+	if (origin.pathname !== "/" || origin.search !== "" || origin.hash !== "") throw new Error("trusted origin must not contain a path, query, or fragment");
+	if (origin.hostname === "" || origin.hostname.includes("*")) throw new Error("trusted origin host must be exact");
+	if (origin.pathname !== "/" || /(?:^|\/)\d+\/\d+$/u.test(rawOrigin)) throw new Error("trusted origin must not be a CIDR or path");
+	if (origin.origin === "null") throw new Error("trusted origin must have an HTTP(S) host");
+	return origin.origin;
+}
+/** Resolve the sidecar path under one DSH home. */
+function openAICodexTrustedOriginsPath(dshHome) {
+	return resolve(join(resolveDshHome(dshHome), OPENAI_CODEX_TRUSTED_ORIGINS_FILENAME));
+}
+/** File-backed exact-origin allowlist. */
+var OpenAICodexTrustedOriginsStore = class {
+	/** Absolute sidecar path. */
+	filename;
+	constructor(filename = openAICodexTrustedOriginsPath()) {
+		this.filename = resolve(filename);
+	}
+	async readCurrent() {
+		await assertOwnerOnly(this.filename);
+		let text;
+		try {
+			text = await readFile(this.filename, "utf8");
+		} catch (error) {
+			if (isENOENT(error)) return {
+				version: 1,
+				mode: TRUSTED_ORIGINS_MODE,
+				origins: []
+			};
+			throw error;
+		}
+		return parseDocument(text, this.filename);
+	}
+	/** Read the current canonical list without acquiring the writer lock. */
+	async list() {
+		return [...(await this.readCurrent()).origins];
+	}
+	/** Whether an exact normalized origin is currently trusted. */
+	async has(origin) {
+		const normalized = normalizeTrustedOrigin(origin);
+		return (await this.readCurrent()).origins.includes(normalized);
+	}
+	/** Add one origin idempotently and return the resulting sorted list. */
+	async trust(origin) {
+		const normalized = normalizeTrustedOrigin(origin);
+		await mkdir(dirname(this.filename), {
+			recursive: true,
+			mode: 448
+		});
+		return withFileLock(this.filename, async () => {
+			const current = await this.readCurrent();
+			if (current.origins.includes(normalized)) return [...current.origins];
+			const next = {
+				version: 1,
+				mode: TRUSTED_ORIGINS_MODE,
+				origins: [...current.origins, normalized].sort()
+			};
+			await writeFileAtomic(this.filename, `${JSON.stringify(next, null, 2)}\n`, {
+				mode: 384,
+				dirMode: 448
+			});
+			return [...next.origins];
+		});
+	}
+	/** Remove one origin idempotently and return the resulting sorted list. */
+	async untrust(origin) {
+		const normalized = normalizeTrustedOrigin(origin);
+		await mkdir(dirname(this.filename), {
+			recursive: true,
+			mode: 448
+		});
+		return withFileLock(this.filename, async () => {
+			const current = await this.readCurrent();
+			if (!current.origins.includes(normalized)) return [...current.origins];
+			const next = {
+				version: 1,
+				mode: TRUSTED_ORIGINS_MODE,
+				origins: current.origins.filter((candidate) => candidate !== normalized)
+			};
+			await writeFileAtomic(this.filename, `${JSON.stringify(next, null, 2)}\n`, {
+				mode: 384,
+				dirMode: 448
+			});
+			return [...next.origins];
+		});
+	}
+};
+/** Stable, non-sensitive error returned when a browser origin needs CLI trust. */
+const REMOTE_WEB_ORIGIN_NOT_TRUSTED = "remote-web-origin-not-trusted";
 /** Redact provider diagnostics before they cross to the browser. */
 function safeMessage(error) {
 	return (error instanceof Error ? error.message : String(error)).replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/gu, "[redacted token]").replace(/(\b(?:code|token|refresh_token|access_token)=)[^&\s]+/giu, "$1[redacted]").slice(0, 1e3);
@@ -569,25 +736,61 @@ function loopbackHost(rawHost) {
 }
 function exactOrigin(req, rawHost, rawOrigin) {
 	try {
-		const origin = new URL(rawOrigin);
-		if (origin.username !== "" || origin.password !== "" || origin.pathname !== "/" || origin.search !== "" || origin.hash !== "") return false;
-		const encrypted = req.socket.encrypted === true;
-		return origin.origin === new URL(`${encrypted ? "https" : "http"}://${rawHost}`).origin;
+		const effective = normalizeTrustedOrigin(`${req.socket.encrypted === true ? "https" : "http"}://${rawHost}`);
+		return normalizeTrustedOrigin(rawOrigin) === effective;
 	} catch {
 		return false;
 	}
 }
-/** Whether a request comes from this loopback page rather than a remote/rebinding site. */
-function trustedRequest(req) {
-	const remote = req.socket.remoteAddress;
-	if (remote !== "127.0.0.1" && remote !== "::1" && remote !== "::ffff:127.0.0.1") return false;
-	if (req.headers["sec-fetch-site"] === "cross-site") return false;
-	const host = req.headers.host;
-	if (typeof host !== "string" || !loopbackHost(host)) return false;
+function effectiveOrigin(req, rawHost) {
+	try {
+		return normalizeTrustedOrigin(`${req.socket.encrypted === true ? "https" : "http"}://${rawHost}`);
+	} catch {
+		return;
+	}
+}
+function sameOriginMetadata(req, host) {
 	const origin = req.headers.origin;
 	if (origin === void 0) return true;
 	return typeof origin === "string" && exactOrigin(req, host, origin);
 }
+/** Evaluate one request against loopback defaults and the current sidecar. */
+async function trustedRequestDecision(req, trustedOrigins = new OpenAICodexTrustedOriginsStore()) {
+	const remote = req.socket.remoteAddress;
+	const localPeer = remote === "127.0.0.1" || remote === "::1" || remote === "::ffff:127.0.0.1";
+	const fetchSite = req.headers["sec-fetch-site"];
+	if (typeof fetchSite === "string" ? fetchSite.trim().toLowerCase() === "cross-site" : Array.isArray(fetchSite) && fetchSite.some((value) => value.trim().toLowerCase() === "cross-site")) return {
+		trusted: false,
+		error: "forbidden"
+	};
+	const host = req.headers.host;
+	if (typeof host !== "string") return {
+		trusted: false,
+		error: "forbidden"
+	};
+	const origin = effectiveOrigin(req, host);
+	if (origin === void 0) return {
+		trusted: false,
+		error: "forbidden"
+	};
+	if (!sameOriginMetadata(req, host)) return {
+		trusted: false,
+		error: "forbidden"
+	};
+	if (localPeer && loopbackHost(host)) return { trusted: true };
+	try {
+		if (await trustedOrigins.has(origin)) return { trusted: true };
+	} catch {
+		return {
+			trusted: false,
+			error: "forbidden"
+		};
+	}
+	return {
+		trusted: false,
+		error: REMOTE_WEB_ORIGIN_NOT_TRUSTED
+	};
+}
 function json(res, status, value) {
 	res.writeHead(status, {
 		"content-type": "application/json; charset=utf-8",
@@ -597,16 +800,24 @@ function json(res, status, value) {
 	res.end(JSON.stringify(value));
 }
 /** Register the plugin-owned OAuth routes when the Web server is composed. */
-function registerOpenAICodexAuthRoutes(ctx, store) {
+function registerOpenAICodexAuthRoutes(ctx, store, trustedOriginsOverride) {
 	const auth = new OpenAICodexWebAuth(store);
+	const storedFilename = store.filename;
+	const trustedOrigins = trustedOriginsOverride ?? (typeof storedFilename === "string" ? new OpenAICodexTrustedOriginsStore(join(dirname(storedFilename), ".openai-codex-trusted-origins.json")) : new OpenAICodexTrustedOriginsStore());
 	ctx.effect(() => {
+		const authorize = async (req, res) => {
+			const decision = await trustedRequestDecision(req, trustedOrigins);
+			if (decision.trusted) return true;
+			json(res, 403, { error: decision.error });
+			return false;
+		};
 		const routes = [
 			ctx.webServer.register({
 				kind: "exact",
 				path: OPENAI_CODEX_AUTH_STATUS_PATH,
 				handler: async (req, res) => {
 					if (req.method !== "GET") return json(res, 405, { error: "method not allowed" });
-					if (!trustedRequest(req)) return json(res, 403, { error: "forbidden" });
+					if (!await authorize(req, res)) return;
 					json(res, 200, await auth.status());
 				}
 			}),
@@ -615,7 +826,7 @@ function registerOpenAICodexAuthRoutes(ctx, store) {
 				path: OPENAI_CODEX_AUTH_LOGIN_PATH,
 				handler: async (req, res) => {
 					if (req.method !== "POST") return json(res, 405, { error: "method not allowed" });
-					if (!trustedRequest(req)) return json(res, 403, { error: "forbidden" });
+					if (!await authorize(req, res)) return;
 					try {
 						json(res, 200, await auth.signIn());
 					} catch (error) {
@@ -628,7 +839,7 @@ function registerOpenAICodexAuthRoutes(ctx, store) {
 				path: OPENAI_CODEX_AUTH_LOGOUT_PATH,
 				handler: async (req, res) => {
 					if (req.method !== "POST") return json(res, 405, { error: "method not allowed" });
-					if (!trustedRequest(req)) return json(res, 403, { error: "forbidden" });
+					if (!await authorize(req, res)) return;
 					try {
 						await auth.signOut();
 						json(res, 200, { ok: true });
@@ -645,8 +856,146 @@ function registerOpenAICodexAuthRoutes(ctx, store) {
 	}, "dsh-codex-connect: Web OAuth routes");
 }
 //#endregion
+//#region src/compatibility.ts
+const COMPATIBILITY_SCHEMA_VERSION = 1;
+const SUPPORTED_NODE_RANGE = "^22.19.0 || >=24.0.0";
+const SUPPORTED_DSH_PLUGIN_API_VERSION = "0.1.0-rc.6";
+const SUPPORTED_PI_AI_VERSION = "0.82.1";
+const PI_AI_PACKAGE = "@earendil-works/pi-ai";
+const DSH_PLUGIN_API_PACKAGES = [
+	"@deepseek-ai/dsh-agent",
+	"@deepseek-ai/dsh-atomic-write",
+	"@deepseek-ai/dsh-attachment",
+	"@deepseek-ai/dsh-home-paths",
+	"@deepseek-ai/dsh-host-webserver",
+	"@deepseek-ai/dsh-invariants",
+	"@deepseek-ai/dsh-llm",
+	"@deepseek-ai/dsh-llm-pi-ai",
+	"@deepseek-ai/dsh-fs",
+	"@deepseek-ai/dsh-session",
+	"@deepseek-ai/dsh-settings",
+	"@deepseek-ai/dsh-tools",
+	"@deepseek-ai/dsh-web"
+];
+const COMPATIBILITY_PACKAGES = [
+	"@deepseek-ai/dsh-llm",
+	"@deepseek-ai/dsh-llm-pi-ai",
+	PI_AI_PACKAGE
+];
+/** Public contract data mirrored by compatibility.json without importing JSON at runtime. */
+const COMPATIBILITY_CONTRACT = {
+	schemaVersion: 1,
+	engines: { node: SUPPORTED_NODE_RANGE },
+	dshPluginApi: {
+		version: SUPPORTED_DSH_PLUGIN_API_VERSION,
+		packages: DSH_PLUGIN_API_PACKAGES
+	},
+	piAi: {
+		package: PI_AI_PACKAGE,
+		version: SUPPORTED_PI_AI_VERSION
+	}
+};
+const PACKAGE_JSON_SEARCH_DEPTH = 8;
+function compareVersion(left, right) {
+	return left === right ? "compatible" : "incompatible";
+}
+function parseNodeVersion(value) {
+	const match = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+][0-9A-Za-z.-]+)?$/u.exec(value.trim());
+	if (match === null) return void 0;
+	const major = Number(match[1]);
+	const minor = Number(match[2]);
+	const patch = Number(match[3]);
+	if (![
+		major,
+		minor,
+		patch
+	].every(Number.isSafeInteger)) return void 0;
+	return [
+		major,
+		minor,
+		patch
+	];
+}
+function nodeStatus(value) {
+	if (value === void 0 || value === null || value.trim() === "") return "unknown";
+	const parsed = parseNodeVersion(value);
+	if (parsed === void 0) return "unknown";
+	const [major, minor, patch] = parsed;
+	if (major === 22) return minor > 19 || minor === 19 && patch >= 0 ? "compatible" : "incompatible";
+	return major >= 24 ? "compatible" : "incompatible";
+}
+function packageEntry(supported, installed) {
+	return {
+		supported,
+		installed: installed ?? null,
+		status: installed === void 0 || installed === null || installed === "" ? "unknown" : compareVersion(installed, supported)
+	};
+}
+function nodeEntry(installed) {
+	return {
+		supported: SUPPORTED_NODE_RANGE,
+		installed: installed ?? null,
+		status: nodeStatus(installed)
+	};
+}
+function aggregateStatus(entries) {
+	if (entries.some((entry) => entry.status === "incompatible")) return "incompatible";
+	if (entries.some((entry) => entry.status === "unknown")) return "unknown";
+	return "compatible";
+}
+/** Evaluate a captured set of versions without touching the filesystem. */
+function evaluateCompatibility(input = {}) {
+	const installedNode = input.nodeVersion ?? input.node ?? input.installed?.node;
+	const suppliedPackages = input.packageVersions ?? input.packages ?? input.installed?.packages ?? {};
+	const packages = {
+		"@deepseek-ai/dsh-llm": packageEntry(SUPPORTED_DSH_PLUGIN_API_VERSION, suppliedPackages["@deepseek-ai/dsh-llm"]),
+		"@deepseek-ai/dsh-llm-pi-ai": packageEntry(SUPPORTED_DSH_PLUGIN_API_VERSION, suppliedPackages["@deepseek-ai/dsh-llm-pi-ai"]),
+		[PI_AI_PACKAGE]: packageEntry(SUPPORTED_PI_AI_VERSION, suppliedPackages[PI_AI_PACKAGE])
+	};
+	const node = nodeEntry(installedNode);
+	return {
+		schemaVersion: 1,
+		status: aggregateStatus([node, ...Object.values(packages)]),
+		node,
+		packages
+	};
+}
+/** Alias for callers that prefer assessment terminology. */
+const assessCompatibility = evaluateCompatibility;
+async function readPackageVersionFromEntry(name) {
+	let entry;
+	try {
+		const resolved = import.meta.resolve(name);
+		if (!resolved.startsWith("file:")) return void 0;
+		entry = fileURLToPath(resolved);
+	} catch {
+		return;
+	}
+	let directory = dirname(entry);
+	for (let depth = 0; depth < PACKAGE_JSON_SEARCH_DEPTH; depth += 1) {
+		const candidate = join(directory, "package.json");
+		try {
+			const parsed = JSON.parse(await readFile(candidate, "utf8"));
+			if (parsed.name === name && typeof parsed.version === "string") return parsed.version;
+		} catch {}
+		const parent = parse(directory).root === directory ? directory : dirname(directory);
+		if (parent === directory) break;
+		directory = parent;
+	}
+}
+/** Read installed package metadata and return only versions and statuses. */
+async function detectCompatibility(options = {}) {
+	const readVersion = options.readPackageVersion ?? readPackageVersionFromEntry;
+	const packageVersions = options.packageVersions ?? options.packages ?? options.installed?.packages;
+	const resolvedPackages = packageVersions === void 0 ? Object.fromEntries(await Promise.all(COMPATIBILITY_PACKAGES.map(async (name) => [name, await readVersion(name)]))) : packageVersions;
+	return evaluateCompatibility({
+		nodeVersion: options.nodeVersion ?? options.node ?? options.installed?.node ?? process.version,
+		packageVersions: resolvedPackages
+	});
+}
+//#endregion
 //#region src/version.ts
-const CODEX_CONNECT_VERSION = "0.1.0-alpha.4.7";
+const CODEX_CONNECT_VERSION = "0.1.0-alpha.4.8";
 //#endregion
 //#region src/doctor.ts
 /** Secret-free diagnostics and duplicate-provider guidance. */
@@ -678,6 +1027,7 @@ async function diagnoseOpenAICodex(options = {}) {
 		state = error?.code === "ENOENT" ? "missing" : "unreadable-metadata";
 	}
 	const providerConflict = options.providerIds?.includes("openai-codex") ?? false;
+	const compatibility = await detectCompatibility(options.compatibilityOptions);
 	const hints = [];
 	if (state === "missing") hints.push("Sign in only when you are ready; installation does not start OAuth.");
 	if (state === "permissions-too-broad") hints.push(`Restrict the OAuth file to its owner before use (current mode ${mode}).`);
@@ -685,6 +1035,8 @@ async function diagnoseOpenAICodex(options = {}) {
 	if (state === "unreadable-metadata") hints.push("Harness could not inspect the OAuth file metadata; check the parent directory and file ownership.");
 	if (providerConflict) hints.push(openAICodexConflictMessage());
 	if (!providerConflict) hints.push("If Harness reports a duplicate openai-codex adapter, remove the legacy bundle or manual provider row.");
+	if (compatibility.status === "incompatible") hints.push("Compatibility mismatch: install the declared DSH plugin API versions and pin @earendil-works/pi-ai to 0.82.1, then run doctor again; no files are changed automatically.");
+	else if (compatibility.status === "unknown") hints.push("Compatibility is unknown: verify the declared DSH plugin API and @earendil-works/pi-ai versions, then run doctor again.");
 	return {
 		package: "dsh-codex-connect",
 		version: CODEX_CONNECT_VERSION,
@@ -702,6 +1054,7 @@ async function diagnoseOpenAICodex(options = {}) {
 			changesHarnessSearchRoute: false
 		},
 		providerConflict,
+		compatibility,
 		hints
 	};
 }
@@ -1509,4 +1862,4 @@ function apply(ctx, config) {
 	scheduleCapabilities();
 }
 //#endregion
-export { loginOpenAICodex as A, assertNoOpenAICodexProviderConflict as C, OPENAI_CODEX_USAGE_URL as D, CODEX_CONNECT_VERSION as E, OpenAICodexCredentialStore as F, openAICodexAuthPath as I, openAICodexAuthStatus as M, OPENAI_CODEX_AUTH_FILENAME as N, parseOpenAICodexUsage as O, OPENAI_CODEX_PROVIDER as P, VIEW_IMAGE_TOOL_NAME as S, openAICodexConflictMessage as T, decodeOpenAICodexSettings as _, name as a, installOpenAICodexSearchEvent as b, OPENAI_CODEX_SEARCH_URL as c, DEFAULT_OPENAI_CODEX_SEARCH_CONTEXT_SIZE as d, DEFAULT_OPENAI_CODEX_SEARCH_MAX_OUTPUT_TOKENS as f, OPENAI_CODEX_SETTINGS_NAMESPACE as g, DEFAULT_OPENAI_CODEX_SETTINGS as h, inject as i, logoutOpenAICodex as j, readOpenAICodexRateLimits as k, OpenAICodexSearchProvider as l, DEFAULT_OPENAI_CODEX_SEARCH_MODEL as m, OPENAI_CODEX_SETTINGS_NS as n, OPENAI_CODEX_BASE_URL as o, DEFAULT_OPENAI_CODEX_SEARCH_MODE as p, apply as r, OPENAI_CODEX_SEARCH_PROVIDER as s, Config as t, mapOpenAICodexSearchResponse as u, resolveOpenAICodexSettings as v, diagnoseOpenAICodex as w, recordOpenAICodexSearchRequest as x, OPENAI_CODEX_SEARCH_MODEL_REQUEST_EVENT as y };
+export { DSH_PLUGIN_API_PACKAGES as A, OPENAI_CODEX_USAGE_URL as B, assertNoOpenAICodexProviderConflict as C, COMPATIBILITY_CONTRACT as D, CODEX_CONNECT_VERSION as E, assessCompatibility as F, openAICodexAuthStatus as G, readOpenAICodexRateLimits as H, detectCompatibility as I, OpenAICodexCredentialStore as J, OPENAI_CODEX_AUTH_FILENAME as K, evaluateCompatibility as L, SUPPORTED_DSH_PLUGIN_API_VERSION as M, SUPPORTED_NODE_RANGE as N, COMPATIBILITY_PACKAGES as O, SUPPORTED_PI_AI_VERSION as P, OpenAICodexTrustedOriginsStore as R, VIEW_IMAGE_TOOL_NAME as S, openAICodexConflictMessage as T, loginOpenAICodex as U, parseOpenAICodexUsage as V, logoutOpenAICodex as W, openAICodexAuthPath as Y, decodeOpenAICodexSettings as _, name as a, installOpenAICodexSearchEvent as b, OPENAI_CODEX_SEARCH_URL as c, DEFAULT_OPENAI_CODEX_SEARCH_CONTEXT_SIZE as d, DEFAULT_OPENAI_CODEX_SEARCH_MAX_OUTPUT_TOKENS as f, OPENAI_CODEX_SETTINGS_NAMESPACE as g, DEFAULT_OPENAI_CODEX_SETTINGS as h, inject as i, PI_AI_PACKAGE as j, COMPATIBILITY_SCHEMA_VERSION as k, OpenAICodexSearchProvider as l, DEFAULT_OPENAI_CODEX_SEARCH_MODEL as m, OPENAI_CODEX_SETTINGS_NS as n, OPENAI_CODEX_BASE_URL as o, DEFAULT_OPENAI_CODEX_SEARCH_MODE as p, OPENAI_CODEX_PROVIDER as q, apply as r, OPENAI_CODEX_SEARCH_PROVIDER as s, Config as t, mapOpenAICodexSearchResponse as u, resolveOpenAICodexSettings as v, diagnoseOpenAICodex as w, recordOpenAICodexSearchRequest as x, OPENAI_CODEX_SEARCH_MODEL_REQUEST_EVENT as y, normalizeTrustedOrigin as z };

package/package.json

@@ -2,7 +2,7 @@
   "name": "dsh-codex-connect",
   "displayName": "Codex Connect",
   "description": "ChatGPT OAuth and Codex models for DeepSeek Harness.",
-  "version": "0.1.0-alpha.4.7",
+  "version": "0.1.0-alpha.4.8",
   "author": "Frank Song",
   "contributors": [
     "Yan-Zero (original dsh-codex author)"
@@ -42,9 +42,11 @@
     "build": "tsdown",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.client.json",
+    "check:compatibility": "node scripts/check-compatibility.mjs",
     "pack:check": "node scripts/check-pack.mjs",
     "check:dsh-install": "node scripts/check-dsh-install.mjs",
-    "check": "pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run build && pnpm run pack:check",
+    "check:release-workflow": "node scripts/check-release-workflow.mjs",
+    "check": "pnpm run check:release-workflow && pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run build && pnpm --silent run check:compatibility && pnpm run pack:check",
     "prepublishOnly": "pnpm --config.minimum-release-age=0 run check"
   },
   "exports": {
@@ -58,10 +60,12 @@
     },
     "./client": "./lib/client.js",
     "./cordis.patch.yml": "./cordis.patch.yml",
+    "./compatibility.json": "./compatibility.json",
     "./package.json": "./package.json"
   },
   "files": [
     "lib",
+    "compatibility.json",
     "cordis.patch.yml",
     "docs",
     "INSTALL.md",
@@ -86,21 +90,21 @@
     }
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "^0.82.1",
+    "@earendil-works/pi-ai": "0.82.1",
     "@deepseek-ai/cordis": "^4.0.1-rc.1",
-    "@deepseek-ai/dsh-agent": "*",
-    "@deepseek-ai/dsh-atomic-write": "*",
-    "@deepseek-ai/dsh-attachment": "*",
-    "@deepseek-ai/dsh-home-paths": "*",
-    "@deepseek-ai/dsh-host-webserver": "*",
-    "@deepseek-ai/dsh-invariants": "*",
-    "@deepseek-ai/dsh-llm": "*",
-    "@deepseek-ai/dsh-llm-pi-ai": "*",
-    "@deepseek-ai/dsh-fs": "*",
-    "@deepseek-ai/dsh-session": "*",
-    "@deepseek-ai/dsh-settings": "*",
-    "@deepseek-ai/dsh-tools": "*",
-    "@deepseek-ai/dsh-web": "*",
+    "@deepseek-ai/dsh-agent": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-atomic-write": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-attachment": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-home-paths": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-host-webserver": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-invariants": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm-pi-ai": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-fs": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-web": "0.1.0-rc.6",
     "@deepseek-ai/schemastery": "^3.18.1-rc.1",
     "react": "^18.2.0"
   },