dsh-codex-connect 0.1.0-alpha.4.3

package/INSTALL.md

@@ -0,0 +1,72 @@
+# Installation Runbook for CLI Agents
+
+Install `dsh-codex-connect` into one requested DeepSeek Harness profile without changing its current default model, search route, global configuration, or OAuth state.
+
+## Safety requirements
+
+- Never read, print, copy, move, or modify `~/.codex/auth.json`.
+- Never print or inspect `$DSH_HOME/.openai-codex-auth.json`; `doctor` may inspect pathname metadata only.
+- Never add OAuth URLs, codes, tokens, account identifiers, or generated profile state to Git.
+- Preserve every unrelated profile dependency and patch row.
+- Do not start login unless the user explicitly asks to authenticate.
+
+## Install and validate
+
+1. Check `dsh --version` or `dsh --help`. From a Harness checkout use `pnpm dsh`.
+2. Install the package:
+
+   ```sh
+   dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.3'
+   ```
+
+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.
+5. Run secret-free diagnostics:
+
+   ```sh
+   dsh plugin --profile web exec dsh-codex-connect doctor
+   ```
+
+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.
+
+## 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.
+
+Apply only requested choices and preserve unrelated keys:
+
+```yaml
+- id: llm-openai-codex
+  config:
+    enableSearch: true
+    enableImageTool: false
+    searchMode: live
+
+- id: web
+  config:
+    searchProvider: openai-codex
+
+- id: agent-default-model
+  config:
+    provider: openai-codex
+    model: gpt-5.6-sol
+```
+
+Do not add the last two rows unless the user separately requested those routing changes.
+
+## Conflict handling
+
+`openai-codex` can have only one adapter. If startup reports a collision, inspect the effective config and remove only the old `dsh-codex` bundle or manual `openai-codex` provider row after confirming it is the conflicting owner. Do not delete auth files or unrelated providers.
+
+## Update and removal
+
+```sh
+dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#<new-release-tag>'
+dsh plugin --profile web remove dsh-codex-connect
+```
+
+Removal of the package and removal of its separate OAuth file are different actions. Run `dsh plugin --profile web exec dsh-codex-connect logout` only with explicit credential-deletion authorization.
+
+## Completion report
+
+Report the profile, installed version, effective default model, effective search route, enabled optional capabilities, signed-in/signed-out state only if checked, and Web client detection. Never report OAuth URLs, codes, token timestamps, account ids, or auth-file contents.

package/LICENSE

@@ -0,0 +1,202 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "[]"
+replaced with your own identifying information. (Don't include
+the brackets!) The text should be enclosed in the appropriate
+comment syntax for the file format. We also recommend that a
+file or class name and description of purpose be included on the
+same "printed page" as the copyright notice for easier
+identification within third-party archives.
+
+Copyright 2026 Yan-Zero
+Copyright 2026 Frank Song (modifications and additional work)
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/MIGRATION.md

@@ -0,0 +1,12 @@
+# Migrating from `dsh-codex`
+
+`dsh-codex-connect` uses the same provider id (`openai-codex`), OAuth filename (`.openai-codex-auth.json`), Cordis row id (`llm-openai-codex`), and browser auth routes for compatibility. The packages cannot be active together because Harness forbids duplicate provider adapters.
+
+1. Record the effective default model, search route, and `llm-openai-codex` config without reading any OAuth file.
+2. Remove `dsh-codex` from the selected profile and add `dsh-codex-connect`.
+3. Keep exactly one `llm-openai-codex` row loading `dsh-codex-connect`.
+4. Decide explicitly whether to set `enableSearch` and `enableImageTool`; both default to `false` after migration.
+5. Preserve the prior `agent-default-model` and `web.searchProvider` only when the user wants those routes to remain selected.
+6. Run `--dump-config`, then `dsh-codex-connect doctor`. Do not run OAuth again when `status` already reports signed in.
+
+Rollback is the inverse package swap. Do not delete or copy the separate OAuth file during either direction. If Harness reports a duplicate `openai-codex` adapter, the old bundle or a manual provider row is still active; resolve that one row instead of changing credentials.

package/NOTICE

@@ -0,0 +1,15 @@
+dsh-codex-connect
+Copyright 2026 Frank Song
+
+This product includes software derived from Yan-Zero/dsh-codex:
+https://github.com/Yan-Zero/dsh-codex
+Copyright 2026 Yan-Zero
+
+Modifications and additional work for Codex Connect are Copyright 2026
+Frank Song. They include a distinct package identity, opt-in routing and
+capabilities, secret-free diagnostics, provider-conflict guidance, migration
+documentation, security hardening, live plugin configuration, and Alpha
+release validation.
+
+The upstream material and the Codex Connect modifications are distributed
+under the Apache License, Version 2.0 included in LICENSE.

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:
+#   git hash-object README.md README.zh.md
+README.md: e7a63add3ad36f0291b42190cdbf16e2c655a3b8
+README.zh.md: bae8717ef5c8c8221d7576ec5b889b9a206991f3

package/README.md

@@ -0,0 +1,110 @@
+# Codex Connect
+
+English | [中文](README.zh.md)
+
+Connect your ChatGPT subscription to DeepSeek Harness with OAuth, user-controlled defaults, Harness-native approvals, diagnostics, and reliable session recovery.
+
+`dsh-codex-connect` adds the `openai-codex` model catalog and a separate ChatGPT OAuth login. Models run through Harness's normal LLM service, so streaming, tool calls, reasoning replay, compaction, filesystem controls, permission gates, and approval prompts remain Harness-owned. It does not turn a ChatGPT subscription into an OpenAI Platform API credential.
+
+Installation is additive. The bundle does not replace the current default model or search route, and its standalone search provider and `view_image` tool are disabled until explicitly enabled.
+
+## Install
+
+```sh
+dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.3'
+dsh web
+```
+
+This installs the current alpha directly from its tagged GitHub release using Harness's supported Git package path. From a DeepSeek Harness source checkout, prefix commands with `pnpm`. For a local checkout, install `link:/absolute/path/to/dsh-codex-connect`.
+
+Sign in from **Settings → Plugins → Plugin configuration → Codex Connect → Sign in with ChatGPT**, or use the CLI:
+
+```sh
+dsh plugin --profile web exec dsh-codex-connect login
+dsh plugin --profile web exec dsh-codex-connect status
+dsh plugin --profile web exec dsh-codex-connect doctor
+```
+
+The doctor command reads process and filesystem metadata only. It never opens the OAuth document or prints a token, authorization URL, authorization code, account id, or auth-file content.
+
+## Explicit configuration
+
+Open **Settings → Plugins → Plugin configuration → Codex Connect** to manage the ChatGPT account and optional capabilities in one card. Changes use Harness's revision-fenced settings store and apply live. **Save changes** affects only this plugin's capability section; it never selects a default model or global search route.
+
+The installed bundle row remains the composition base and is intentionally inert beyond model-provider registration:
+
+```yaml
+- id: llm-openai-codex
+  config:
+    enableSearch: false
+    enableImageTool: false
+```
+
+To make a Codex model the default for new agents, add or update the separate Harness row yourself:
+
+```yaml
+- id: agent-default-model
+  config:
+    provider: openai-codex
+    model: gpt-5.6-sol
+```
+
+The card can enable Codex standalone search. Selecting it as the profile's global search provider remains a separate explicit choice:
+
+```yaml
+- id: llm-openai-codex
+  config:
+    enableSearch: true
+    searchMode: live
+    searchContextSize: medium
+
+- id: web
+  config:
+    searchProvider: openai-codex
+```
+
+To add the image-loading tool, set `enableImageTool: true` on `llm-openai-codex`. Browser paste/drop remains a Harness attachment feature and does not depend on this tool.
+
+| Field | Default | Values |
+|---|---:|---|
+| `enableSearch` | `false` | boolean |
+| `enableImageTool` | `false` | boolean |
+| `searchModel` | `gpt-5.6-sol` | Codex model id |
+| `searchMode` | `cached` | `cached`, `indexed`, `live` |
+| `searchContextSize` | `medium` | `low`, `medium`, `high` |
+| `searchMaxOutputTokens` | `10000` | positive integer |
+
+## Credentials, diagnostics, and conflicts
+
+- 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 are created with owner-only permissions where supported. Writes are atomic, and refresh writes use a cross-process file lock.
+- Status and diagnostics return only non-sensitive state. OAuth flow output is confined to an explicit `login` operation.
+- Browser OAuth routes accept only loopback clients and loopback Host/Origin values; sign-in fails closed when no valid HTTPS authorization URL arrives within 30 seconds.
+- A second adapter cannot own `openai-codex`. Startup fails with a focused hint when the legacy `dsh-codex` bundle or a manual provider row conflicts.
+- 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.
+- 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.
+- Remote `view_image` URLs are limited to public HTTP(S) destinations. Every DNS result and redirect is checked, and the connection is pinned to the validated address so localhost, private networks, link-local services, and cloud metadata endpoints remain unreachable.
+- No real OAuth operation is required for installation, build, tests, doctor, or package validation.
+
+See [INSTALL.md](INSTALL.md) for the idempotent agent runbook, [MIGRATION.md](MIGRATION.md) for migration from `dsh-codex`, and [docs/design.md](docs/design.md) for architecture details.
+
+## Development
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run check
+```
+
+## 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.
+
+## License
+
+Apache-2.0

package/README.zh.md

@@ -0,0 +1,93 @@
+# Codex Connect
+
+[English](README.md) | 中文
+
+通过 OAuth 将你的 ChatGPT 订阅连接到 DeepSeek Harness，同时保留用户自主默认项、Harness 原生审批、非敏感诊断和可靠的会话恢复。
+
+`dsh-codex-connect` 提供 `openai-codex` 模型目录和独立的 ChatGPT OAuth 登录。模型仍走 Harness 标准 LLM 服务，因此流式输出、工具调用、reasoning replay、压缩、文件系统控制、权限门禁和审批提示仍由 Harness 负责。ChatGPT 订阅不会因此变成 OpenAI Platform API 凭据。
+
+安装是增量的：bundle 不会替换当前主模型或搜索路由；独立搜索提供方和 `view_image` 工具也默认关闭，必须显式开启。
+
+## 安装
+
+```sh
+dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.3'
+dsh web
+```
+
+该命令通过 Harness 支持的 Git package 方式，直接安装 GitHub 上带版本标签的当前 Alpha。在 DeepSeek Harness 源码 checkout 中运行时，在命令前加 `pnpm`。本地开发可安装 `link:/absolute/path/to/dsh-codex-connect`。
+
+可在 **设置 → 插件 → 插件配置 → Codex Connect → 使用 ChatGPT 登录**，也可使用 CLI：
+
+```sh
+dsh plugin --profile web exec dsh-codex-connect login
+dsh plugin --profile web exec dsh-codex-connect status
+dsh plugin --profile web exec dsh-codex-connect doctor
+```
+
+`doctor` 只读取进程与文件系统元数据，不打开 OAuth 文件，也不会输出 token、授权 URL、授权码、账户 ID 或认证文件内容。
+
+## 显式配置
+
+打开 **设置 → 插件 → 插件配置 → Codex Connect**，可以在同一张卡片中管理 ChatGPT 账户和可选能力。更改通过 Harness 带 revision 防护的设置存储保存，并即时生效；**保存更改**只影响本插件的能力配置，绝不会选择默认模型或全局搜索路由。
+
+安装后的 bundle 行仍是 composition base，只注册模型提供方，不改变路由：
+
+```yaml
+- id: llm-openai-codex
+  config:
+    enableSearch: false
+    enableImageTool: false
+```
+
+如需把 Codex 模型设为新 agent 的默认模型，需要自行添加或修改 Harness 的独立配置项：
+
+```yaml
+- id: agent-default-model
+  config:
+    provider: openai-codex
+    model: gpt-5.6-sol
+```
+
+卡片可以启用 Codex 独立搜索；如需把它选为 profile 的全局搜索提供方，仍需单独显式配置：
+
+```yaml
+- id: llm-openai-codex
+  config:
+    enableSearch: true
+    searchMode: live
+    searchContextSize: medium
+
+- id: web
+  config:
+    searchProvider: openai-codex
+```
+
+如需图片加载工具，在 `llm-openai-codex` 上设置 `enableImageTool: true`。浏览器粘贴/拖放属于 Harness 附件能力，不依赖该工具。
+
+## 凭据、诊断与冲突
+
+- OAuth 单独存储于 `$DSH_HOME/.openai-codex-auth.json`（默认 `~/.dsh`），不会复制或修改 `~/.codex/auth.json`。
+- 支持的平台上，父目录与文件使用仅所有者可访问权限；写入采用原子替换，刷新写入使用跨进程文件锁。
+- 状态和诊断只返回非敏感信息；OAuth 交互只会由显式 `login` 操作触发。
+- 浏览器 OAuth 路由只接受 loopback 客户端和 loopback Host/Origin；30 秒内没有得到有效的 HTTPS 授权地址时会安全失败，不会一直挂起。
+- 两个 adapter 不能同时占用 `openai-codex`。旧 `dsh-codex` bundle 或手动 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。
+- ChatGPT 套餐资格、模型权限、额度和后端行为由 OpenAI 控制，可能变化。
+- shell、文件系统、skills、MCP、subagents、审批、权限、附件、会话持久化、压缩与恢复继续由当前 Harness profile 提供。
+- 远程 `view_image` 只允许公共 HTTP(S) 目标；每一次 DNS 结果与重定向都会重新检查，并将连接固定到已验证地址，从而阻止 localhost、私网、link-local 服务和云元数据地址。
+- 安装、构建、测试、doctor 和包内容验证均不需要真实 OAuth。
+
+详见 [INSTALL.md](INSTALL.md)、[MIGRATION.md](MIGRATION.md) 与 [docs/design.zh.md](docs/design.zh.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 不存在隶属关系，也未获得其背书。
+
+## 许可证
+
+Apache-2.0

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# Install the provider without changing the profile's current default model or
+# web-search route. Optional capabilities require explicit profile config.
+- insert:
+    - id: llm-openai-codex
+      name: dsh-codex-connect
+      config:
+        enableSearch: false
+        enableImageTool: false

package/docs/design.i18n.yaml

@@ -0,0 +1,4 @@
+# Bilingual-pair consistency record for the design document. Re-record with:
+#   git hash-object docs/design.md docs/design.zh.md
+design.md: c03949ff0c973040401b558cadf34f92cdccf568
+design.zh.md: 2bd55edd9b6a6f079775eaf6dcc5892755ef6fda

package/docs/design.md

@@ -0,0 +1,29 @@
+# Codex Connect: Alpha design
+
+## Ownership and composition
+
+The package registers `openai-codex` through Harness's public `LlmRuntime` and `PiAiAdapter` surfaces. The main model path is not a one-shot subagent: it remains the normal Harness agent loop, preserving native tool approvals, permission policy, streaming, attachment resolution, reasoning replay, session persistence, compaction, and recovery.
+
+The bundle patch inserts only `llm-openai-codex`. It never writes `agent-default-model` or `web.searchProvider`. `enableSearch` and `enableImageTool` are capability gates defaulting to `false`; the optional service injections are not registered while disabled.
+
+The Host registers `llm-openai-codex` as the plugin-owned settings namespace and declares `OpenAI Codex` in the LLM configurable-provider directory. The browser binds that namespace through Harness's settings-scope transport and renders account, quota, Save/Discard capability controls in the existing Plugin configuration card. Revision-fenced field writes preserve unrelated settings. Committed changes reconcile search and image registrations live; the default-model and global-search namespaces are never written.
+
+## 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 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.
+
+## Search and images
+
+When `enableSearch: true`, the plugin registers its standalone search provider and secret-free request event. Harness still requires explicit `web.searchProvider: openai-codex` when multiple providers exist. Search responses are mapped to Harness text and citation records.
+
+When `enableImageTool: true`, `view_image` is registered only after tools, filesystem, and attachment services are available. Local files remain bounded by the Harness filesystem surface. Remote images allow only credential-free public HTTP(S): all DNS answers must be public unicast, each redirect is revalidated, and each socket is pinned to the validated address to close DNS-rebinding gaps. The tool also checks bounded bytes, accepted media signatures, and current-model image support before saving a Harness attachment.
+
+## Conflicts and diagnostics
+
+Before registration the plugin checks current provider ids. An existing `openai-codex` adapter produces a focused message naming the likely legacy-bundle or manual-provider cause. The boot-free CLI `doctor` reports package/runtime version, OAuth path metadata, capability defaults, and safe conflict guidance without returning auth content.
+
+## Compatibility boundary
+
+The Alpha pins Harness `0.1.0-rc.6` development dependencies while targeting the current `0.1.0-rc.5` main-line composition and compatible APIs; supported Node.js is `^22.19.0 || >=24.0.0`. It pins `@earendil-works/pi-ai` `0.82.1`. Backend eligibility, quotas, models, and protocol details remain controlled upstream. Tests use temporary OAuth documents and mocked network responses; CI does not perform real authentication.

package/docs/design.zh.md

@@ -0,0 +1,25 @@
+# Codex Connect：Alpha 设计
+
+## 所有权与组合
+
+本包通过 Harness 公共 `LlmRuntime` 与 `PiAiAdapter` 注册 `openai-codex`。主模型路径不是一次性 subagent，而是标准 Harness agent loop，因此原生工具审批、权限策略、流式输出、附件解析、reasoning replay、会话持久化、压缩与恢复均保持有效。
+
+bundle patch 只插入 `llm-openai-codex`，不会写入 `agent-default-model` 或 `web.searchProvider`。`enableSearch` 与 `enableImageTool` 默认均为 `false`；关闭时不会注册对应可选服务。
+
+Host 将 `llm-openai-codex` 注册为插件自有 settings namespace，并在 LLM 可配置 provider 目录中声明显示名为 `OpenAI Codex`。浏览器通过 Harness settings-scope transport 绑定该 namespace，把账户、额度以及带保存/放弃的能力配置放在现有“插件配置”卡片中。带 revision 防护的逐字段写入不会覆盖无关设置；提交后会即时协调搜索与图片能力的注册状态，且绝不写入默认模型或全局搜索 namespace。
+
+## OAuth 持久化
+
+插件使用 `$DSH_HOME/.openai-codex-auth.json`，与 Codex CLI/Desktop 状态分离。文件格式严格且有版本号；POSIX 上会拒绝组/其他用户可读文件。父目录和文件按仅所有者权限创建，写入采用原子替换，刷新修改使用 Harness 跨进程文件锁，返回给调用方的是凭据副本。
+
+为兼容迁移，设置页路由、OAuth 路径和 provider id 不改名。浏览器请求必须来自 loopback 对端，并带有 loopback Host；若带 Origin，则必须与该本地 HTTP(S) 源精确匹配。登录挑战只接受不含凭据的 HTTPS 地址；30 秒内未得到地址、provider 已结束但没有地址、退出登录或插件卸载时，所有 waiter 都会被清理。只有显式登录会输出授权 URL 或代码；状态输出会脱敏。doctor 只用 `lstat` 检查元数据，不打开文件。
+
+## 搜索与图片
+
+仅当 `enableSearch: true` 时注册 Codex 独立搜索提供方和不含凭据的请求事件。多 provider 环境仍需显式设置 `web.searchProvider: openai-codex`。仅当 `enableImageTool: true` 且 tools、filesystem、attachments 服务存在时注册 `view_image`。本地文件继续受 Harness 文件系统边界与大小限制；远程图片只允许不含凭据的公共 HTTP(S)，所有 DNS 结果必须是公共单播地址，每次重定向都会重新验证，并把实际连接固定到已验证地址以关闭 DNS rebinding 缺口。
+
+## 冲突、诊断与兼容边界
+
+注册前检查现有 provider id；发现 `openai-codex` 已被占用时，给出旧 bundle 或手动 provider 配置的定向迁移提示。boot-free CLI doctor 只报告包/运行时版本、OAuth 路径元数据、能力默认值和安全提示。
+
+Alpha 固定使用 Harness `0.1.0-rc.6` 开发依赖，同时面向当前 `0.1.0-rc.5` 主线组合与兼容 API；Node.js 支持 `^22.19.0 || >=24.0.0`。`@earendil-works/pi-ai` 固定为 `0.82.1`。资格、额度、模型和后端协议仍由上游控制。测试仅使用临时 OAuth 文档和模拟网络响应，CI 不执行真实认证。

package/lib/bin.d.ts

@@ -0,0 +1,6 @@
+//#region src/bin.d.ts
+/** Standalone credential CLI for the optional OpenAI Codex bundle. */
+/** Execute one boot-free credential command. */
+declare function run(argv: readonly string[]): Promise<number>;
+//#endregion
+export { run };