@shuind/dsh-codex-harness 0.1.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# @shuind/dsh-codex-harness
+
+English | [中文](README.zh.md)
+
+A minimal Codex harness for GPT models that do not fit DSH's native interface. It keeps the DSH runtime, profiles, services, and plugin ecosystem, while presenting the model with the compact Codex prompt and core tool protocol. Existing DSH plugins continue to work; this package only replaces the model-facing layer.
+
+## DSH compatibility
+
+This package is a model-facing compatibility layer, not a replacement runtime. DSH still owns the session, services, profile composition, providers, and plugin lifecycle. Install it into an existing DSH profile and continue composing other DSH plugins normally.
+
+## Install, enable, and select
+
+These are separate operations:
+
+1. Install the plugin into the profile used by Web:
+
+   ```sh
+   dsh plugin --profile web add @shuind/dsh-codex-harness
+   ```
+
+   The package remains a normal DSH bundle, so it appears in the plugin list and does not produce peer warnings from its DSH dependencies.
+
+2. Enable it by starting or restarting that profile. The bundle installs the packaged `codex` preset into `$DSH_HOME/.agent-presets/codex` when that directory does not already exist. It never overwrites an existing user preset.
+
+3. Create a new conversation and choose `Codex 模式` in the mode menu. The plugin list and the agent preset roster are different surfaces. DSH 0.1.0-rc.6 discovers user presets from `$DSH_HOME/.agent-presets`; newer DSH versions may provide a system `codex` preset themselves.
+
+If an older manual copy left `$DSH_HOME/.agent-presets/codex` without a valid `agent.cordis.yml`, repair or remove that directory and restart the profile. The installer preserves existing directories by design.
+
+The selected preset is fixed when a session is created. Selecting Codex affects new conversations; it does not rewrite the prompt or tool catalog of an existing session.
+
+## What it does
+
+The packaged `codex` preset mounts this package together with the dsh Skill filesystem and Skill tool. The package owns the Codex prompt section and these exact model-facing tool names and descriptions:
+
+- `exec_command` — runs a command in a PTY, returning output or a session id for ongoing interaction.
+- `write_stdin` — writes characters to an existing unified exec session and returns recent output.
+- `apply_patch` — accepts the complete freeform patch text through one required `input` string.
+- `update_plan` — accepts an optional explanation and a required plan of `step` / `status` items.
+
+The exported tool registrations are authoritative for the complete schemas. The first two tools return the Codex-compatible execution fields (`chunk_id`, `wall_time_seconds`, `exit_code`, `session_id`, `original_token_count`, and `output`) and render the same `Chunk ID` / `Wall time` / `Output` response envelope. `apply_patch` returns the changed file list and renders the familiar `Success. Updated the following files:` summary. `update_plan` writes the durable `todo/write` event and returns `Plan updated`.
+
+## dsh composition
+
+`exec_command` uses the dsh Shell service for pipe-backed commands and the dsh Terminal service for optional PTY sessions. The Codex `shell`, `login`, `yield_time_ms`, and `max_output_tokens` arguments remain model-visible and are translated at the service seams. `write_stdin` addresses the per-agent unified session registry.
+
+`apply_patch` parses the Codex patch language, resolves targets through dsh `fs`, applies version-checked writes/removes, observes the resulting filesystem state, and routes sandbox decisions through `sandboxPolicy`. It never writes through a second filesystem implementation. Add, update, delete, and move operations use dsh's normal filesystem errors and durable observations.
+
+`update_plan` appends the session's `todo/write` event. It does not depend on an extra runtime projection helper or maintain a second plan store; DSH owns the projection and replay path. This keeps the package compatible with both the older and newer `dsh-tool-todo` packages. The Codex package does not mount `todo_write`.
+
+## Configuration
+
+The package accepts `defaultYieldTimeMs`, `pollYieldTimeMs`, `writeYieldTimeMs`, and `maxOutputBytes`. They control execution timing and retained output; protocol names, argument names, descriptions, and result fields are fixed. A sandboxing filesystem requires the corresponding dsh `sandboxPolicy` service.
+
+`apply_patch` uses the ordinary dsh tool definition in DSH 0.1.0-rc.6. Its `input` value is still the complete Codex freeform patch, while provider-specific tool serialization remains owned by the DSH route.
+
+## Bundle and preset composition
+
+The package declares a `dsh.bundle` patch, but that patch only installs the preset template. It does not globally mount `@shuind/dsh-codex-harness` or add Codex tools to standard, code, minimal, or other presets. The packaged `presets/codex/agent.cordis.yml` contains the single `codex-tools` row, so a Codex session mounts the prompt and four core tools exactly once.
+
+If you author another Codex preset, add `@shuind/dsh-codex-harness` inside that preset's `agent.cordis.yml`, not to the profile's top-level patch. This also avoids a duplicate when a newer DSH release already ships a system Codex preset.
+
+The preset deliberately keeps Skills, filesystem policy, shell providers, terminal providers, and Web presentation on dsh extension points. They can be changed by composing a different preset or adding the corresponding dsh rows without changing the Codex tool protocol.
+
+## Model Experience
+
+### Prompt and tool catalog
+
+#### What the model sees
+
+The request contains the Codex base prompt, the four Codex core tools, and any explicitly mounted dsh extension such as `skill`. Tool names, descriptions, argument names, and result envelopes match the Codex harness protocol; dsh-specific implementation services stay behind the tools.
+
+#### Token effect
+
+The Codex prompt and core schemas add a fixed prefix cost to each request in this preset. Skill content and tool results remain data-dependent.
+
+#### KV Cache effect
+
+The fixed prompt and tool prefix remains reusable while the session's mounted composition is unchanged. Skill discovery or other explicitly mounted extensions change the suffix after the Codex prefix.
+
+### Tool calls and results
+
+#### What the model sees
+
+Command calls return the Codex execution envelope, patch calls return the changed-file envelope and summary text, and plan calls return a durable plan acknowledgement. Filesystem and session events reconstruct the model-visible effects during replay.
+
+#### Token effect
+
+Tool results are data-dependent: command output and changed-file summaries are retained in the session, while a plan acknowledgement is small and fixed.
+
+#### KV Cache effect
+
+Tool results append to the conversation. A filesystem change or plan update affects later context through the normal dsh session log and projection rather than through hidden mutable state.
+
+## Known Limitations and Deferred Work
+
+- The preset is fixed for a session. Choosing `codex` affects new sessions; changing the selected preset in Web does not rewrite an existing session's prompt or tools.
+- PTY behavior depends on the mounted dsh Terminal provider. The shipped Windows composition disables the optional bash terminal row; pipe execution remains available through the selected shell service.
+- Pipe-backed `write_stdin` sessions do not accept non-empty stdin; interactive input requires a PTY-backed command.
+- Provider-specific custom-tool or grammar serialization is outside this package; the Codex patch protocol remains usable through the ordinary dsh tool definition.
+- The package implements the Codex core protocol and deliberately leaves Skills, filesystem policy, shell providers, terminal providers, and Web presentation extensible through dsh plugins.

package/README.zh.md

@@ -0,0 +1,100 @@
+# @shuind/dsh-codex-harness
+
+[English](README.md) | 中文
+
+面向不适配 DSH 原生接口的 GPT 模型，提供一个极简的 Codex harness。它保留 DSH 的运行时、profile、服务和插件生态，只把模型看到的提示词与核心工具切换为紧凑的 Codex 协议；现有 DSH 插件仍可继续使用，本包只替换模型面向的这一层。
+
+## DSH 兼容性
+
+本包是模型面向的兼容层，不是另一套运行时。会话、服务、profile 组合、provider 和插件生命周期仍由 DSH 管理。把它安装到现有 DSH profile 后，其他 DSH 插件仍可按原方式组合使用。
+
+## 安装、启用和选择
+
+这三件事是分开的：
+
+1. 把插件安装到 Web 使用的 profile：
+
+   ```sh
+   dsh plugin --profile web add @shuind/dsh-codex-harness
+   ```
+
+   本包仍是标准 DSH bundle，因此会显示在插件列表中；它的 DSH 依赖是 optional peer，不会因为本包产生 peer warning。
+
+2. 启用插件：启动或重启该 profile。bundle 会在 `$DSH_HOME/.agent-presets/codex` 不存在时，把随包提供的 `codex` preset 安装到这里；已经存在的用户 preset 不会被覆盖。
+
+3. 新建对话，在模式菜单中选择 `Codex 模式`。插件列表和 Agent preset 列表不是同一个界面。DSH 0.1.0-rc.6 会从 `$DSH_HOME/.agent-presets` 发现用户 preset；更新版 DSH 也可能自己提供 system `codex` preset。
+
+如果之前手动创建的 `$DSH_HOME/.agent-presets/codex` 缺少有效的 `agent.cordis.yml`，请修复或删除该目录后重启 profile。安装器有意保留已有目录，不会强行覆盖。
+
+preset 在会话创建时确定。选择 Codex 只影响新建对话，不会改写已有会话的提示词和工具目录。
+
+## 功能
+
+随包提供的 `codex` preset 会挂载本包，以及 dsh 的 Skill 文件系统和 Skill 工具。本包拥有 Codex 提示词区段，以及以下精确的模型工具名称和描述：
+
+- `exec_command`：在 PTY 中运行命令，返回输出或用于后续交互的 session id。
+- `write_stdin`：向已有的统一 exec 会话写入字符并返回最近输出。
+- `apply_patch`：通过唯一必填的 `input` 字符串接收完整的自由格式 patch 文本。
+- `update_plan`：接收可选 explanation，以及由 `step`／`status` 项组成的必填 plan。
+
+完整 schema 以导出的工具注册为准。前两个工具返回 Codex 兼容的执行字段（`chunk_id`、`wall_time_seconds`、`exit_code`、`session_id`、`original_token_count` 和 `output`），并使用相同的 `Chunk ID`／`Wall time`／`Output` 响应信封。`apply_patch` 返回变更文件列表，并渲染熟悉的 `Success. Updated the following files:` 摘要。`update_plan` 写入持久化的 `todo/write` 事件，并返回 `Plan updated`。
+
+## dsh 组合
+
+`exec_command` 使用 dsh Shell 服务执行管道命令，并使用 dsh Terminal 服务执行可选的 PTY 会话。Codex 的 `shell`、`login`、`yield_time_ms` 和 `max_output_tokens` 参数仍然面向模型，并在服务接口处完成转换。`write_stdin` 通过每个 agent 的统一会话注册表寻址。
+
+`apply_patch` 解析 Codex patch 语言，通过 dsh `fs` 解析目标，执行带版本检查的写入／删除，记录文件系统结果，并通过 `sandboxPolicy` 处理沙箱决策。它不引入第二套文件系统实现。新增、更新、删除和移动都使用 dsh 的标准文件系统错误和持久化观测事件。
+
+`update_plan` 只追加会话中的 `todo/write` 事件，不依赖额外的运行时投影 helper，也不维护第二个 plan 存储；投影和回放仍由 DSH 负责。因此它同时兼容旧版和新版 `dsh-tool-todo`。Codex 包不会挂载 `todo_write`。
+
+## 配置
+
+本包接受 `defaultYieldTimeMs`、`pollYieldTimeMs`、`writeYieldTimeMs` 和 `maxOutputBytes`。它们控制执行时序和保留的输出大小；协议名称、参数名称、描述和结果字段是固定的。使用沙箱文件系统时，必须同时提供对应的 dsh `sandboxPolicy` 服务。
+
+在 DSH 0.1.0-rc.6 中，`apply_patch` 使用普通 dsh 工具定义；它的 `input` 仍然接收完整的 Codex freeform patch，具体 provider 的工具序列化由 DSH 路由负责。
+
+## Bundle 与 preset 组合
+
+本包声明了 `dsh.bundle` patch，但这个 patch 只负责安装 preset 模板，不会把 `@shuind/dsh-codex-harness` 全局挂载，也不会把 Codex 工具加入 standard、code、minimal 或其他 preset。随包的 `presets/codex/agent.cordis.yml` 只包含一个 `codex-tools` 行，因此 Codex 会话只挂载一次提示词和四个核心工具。
+
+如果你自己编写 Codex preset，请把 `@shuind/dsh-codex-harness` 放在该 preset 的 `agent.cordis.yml` 中，不要放到 profile 顶层 patch。这样也不会和新版 DSH 自带的 system Codex preset 重复。
+
+preset 仍把 Skills、文件系统策略、shell provider、terminal provider 和 Web 展示留给 dsh 扩展点；可以通过其他 preset 或对应的 dsh 行扩展，而不改变 Codex 工具协议。
+
+## 模型体验
+
+### 提示词和工具目录
+
+#### 模型看到的内容
+
+请求包含 Codex 基础提示词、四个 Codex 核心工具，以及显式挂载的 dsh 扩展（例如 `skill`）。工具名称、描述、参数名称和结果封装与 Codex harness 协议一致；dsh 的实现服务隐藏在工具之后。
+
+#### Token 影响
+
+该 preset 的每次请求都承担 Codex 提示词和核心 schema 的固定前缀成本。Skill 内容和工具结果取决于实际数据。
+
+#### KV Cache 影响
+
+会话挂载组合不变时，固定提示词和工具前缀可以复用。Skill 发现结果和其他显式挂载的扩展会从 Codex 前缀之后改变请求后缀。
+
+### 工具调用和结果
+
+#### 模型看到的内容
+
+命令调用返回 Codex 执行封装，patch 调用返回变更文件封装和摘要文本，plan 调用返回持久化的计划确认。文件系统事件和会话事件会在回放时重建模型可见的效果。
+
+#### Token 影响
+
+工具结果取决于数据：命令输出和变更文件摘要会保留在会话中，而计划确认的大小固定且很小。
+
+#### KV Cache 影响
+
+工具结果追加到会话上下文。文件变更或计划更新通过标准 dsh 会话日志和投影影响后续上下文，而不是依赖隐藏的可变状态。
+
+## 已知限制与暂缓事项
+
+- preset 对一个会话固定不变。选择 `codex` 会影响新会话；在 Web 中改变选中的 preset 不会重写已有会话的提示词或工具。
+- PTY 行为取决于挂载的 dsh Terminal provider。出厂的 Windows 组合禁用可选的 bash terminal 行；管道执行仍可通过选中的 shell 服务使用。
+- 管道会话不接受非空的 `write_stdin` 输入；交互式输入需要 PTY 会话。
+- provider 专用的 custom tool 或 grammar 序列化不属于本包；Codex patch 协议通过普通 dsh 工具定义即可使用。
+- 本包实现 Codex 核心协议，并刻意通过 dsh 插件保留 Skills、文件系统策略、shell provider、terminal provider 和 Web 展示的可扩展性。

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+- insert:
+    # The bundle is host-plane installation only. The Codex tool/prompt row
+    # lives in presets/codex/agent.cordis.yml, so other presets stay unchanged.
+    - id: codex-preset-installer
+      name: '@shuind/dsh-codex-harness/installer'