dsh-loop-engine 1.0.0-rc10

package/README.md

@@ -0,0 +1,121 @@
+# dsh-loop-engine
+
+[![npm version](https://img.shields.io/npm/v/dsh-loop-engine?color=cb3837)](https://www.npmjs.com/package/dsh-loop-engine)
+
+Switch the agent loop engine of **dsh web** the same way you switch a model: a
+"Loop engine" dropdown in Settings chooses which driver runs your agents — the
+built-in in-process loop, the Claude Code CLI, the Codex CLI, the Pi CLI, or the
+Kimi Code CLI — without changing anything in the main repository.
+
+## Install
+
+```sh
+dsh plugin --profile web add dsh-loop-engine
+```
+
+Restart `dsh web`, then open **Settings → Loop engine**.
+
+> Switching engines rewrites a small managed block in `cordis.patch.yml`.
+> Everything else you wrote in that file is preserved; only the plugin's own
+> span changes.
+
+> **pnpm users:** pnpm 10+ blocks dependency build scripts by default, so the
+> install may report `@google/genai`, `node-pty`, and `protobufjs` as blocked.
+> This is expected — click **"Allow build scripts and retry"** (or run
+> `pnpm approve-builds`, or list them under `pnpm.onlyBuiltDependencies` in
+> your project root) and retry. Only the installing project can grant this;
+> the plugin cannot pre-approve its own dependencies.
+
+## Version compatibility
+
+dsh-loop-engine is versioned **independently** of the harness (`1.0.0-rcN`) but
+is bound to a specific harness release via `peerDependencies`. The two must be
+matched — a mismatch fails loudly at boot or session resume:
+
+| dsh-loop-engine | Requires harness |
+|---|---|
+| 1.0.0-rc10 | **0.1.2-rc.1** |
+| 1.0.0-rc9 | **0.1.2-rc.1** |
+| 1.0.0-rc8 | **0.1.2-rc.1** |
+| 1.0.0-rc7 | 0.1.1-rc.2 |
+
+- **1.0.0-rc10 (and 1.0.0-rc9 / rc8) is not compatible with harness 0.1.1-rc.2 or earlier.** It uses
+  the 0.1.2 persistence seam (`SessionPersistence.create` / `open` +
+  `SessionHandle`), the `installSection` settings API, `ToolCallId`, and
+  `Session.snapshotEvents()` — none of which exist in older harnesses.
+- To use the plugin with an older harness, install the loop-engine release that
+  matches it (e.g. `npm i dsh-loop-engine@1.0.0-rc7` for harness 0.1.1-rc.2).
+- The GitHub Release body of each tag states the harness version it targets.
+
+### Requirements
+
+- For the Claude Code engine: the Claude Code CLI installed and logged in on
+  the host.
+- For the Codex engine: authenticated either via `codex login` on the host or a
+  `CODEX_API_KEY` environment entry.
+- For the Pi engine: authenticated the way `pi` expects (its own
+  `~/.pi/agent/auth.json` or the provider's API-key environment variable such as
+  `ANTHROPIC_API_KEY`).
+- For the Kimi Code engine: the `kimi` CLI installed and logged in on the host
+  (e.g. `kimi login`), and reachable on `PATH` (or pinned to an absolute path
+  via `kimiBin` in the composition entry).
+
+## Usage
+
+1. Pick an engine in **Settings → Loop engine** — `in-process` (default),
+   `claude-code`, `codex`, `pi`, or `kimi` — then restart `dsh web`.
+2. To return to the default, pick **In-process** and restart again.
+3. To remove the plugin: `dsh plugin --profile web remove dsh-loop-engine`, then
+   restart `dsh web`.
+
+### What a hosted engine takes over
+
+While a hosted engine is selected, it owns the session's command and skill
+surface: the plugin disables dsh's own `/goal` and points new sessions at a
+managed `loop-engine` agent preset — a copy of `standard` minus the dsh-native
+`/compact`, `/plan`, goal-tool, and skill rows that an external engine cannot
+honor — so the slash menu shows the engine's bridged commands and its own
+skill catalog. Engine-agnostic dsh commands (`/export`, `/feedback`,
+`/permission`) keep working and stay. Switching back to `in-process` restores
+the previous preset default; already-running sessions always keep the preset
+they were created with.
+
+### Engine notes
+
+- The Claude Code driver runs one SDK query per step; its slash commands are
+  bridged into the web menu (built-ins plus user-level `~/.claude/commands/`)
+  and forwarded to the engine, which expands them natively. Project-level
+  `.claude/commands/` files stay engine-side and also work typed directly.
+- The Codex driver runs `codex app-server` and has no interactive tool
+  approval — permissions come from the session's `sandboxMode` +
+  `approvalPolicy`. Its `AGENTS.md` instruction files are surfaced through the
+  dsh skill-injection seam across every directory from the session cwd up to
+  the git root, plus `~/.codex/AGENTS.md`.
+- The Pi driver runs `pi --mode rpc`; Pi has no permission system, so the whole
+  child is sandboxed through the dsh subprocess service (default `read-only`).
+  Its context files (`AGENTS.md`/`CLAUDE.md` with `AGENTS.override.md`
+  preferred, plus the user-level file under the pi config dir) and its
+  `skills/` catalogs (`~/.pi/agent/skills/` and `.pi/skills/`) are surfaced
+  through the dsh skill-injection seam.
+- The Kimi Code driver runs a persistent `kimi acp` child (Agent Client
+  Protocol over stdio) and speaks one stateless `session/new` + `session/prompt`
+  per dsh step; the durable dsh session log is the sole model context. It streams
+  assistant text (`agent_message_chunk`) and thinking (`agent_thought_chunk`)
+  incrementally into the log, and maps tool calls/streams (`tool_call` /
+  `tool_call_update`) into `tool/call` + `tool/result`. ACP surfaces tool
+  approvals as `session/request_permission`, which the driver answers from the
+  session's dsh approval knobs (an `ask` policy denies, fail-closed). The child
+  is spawned through the dsh subprocess seam — the only privilege boundary
+  (default read-only sandbox). Its project `AGENTS.md` chain (cwd→git root) and
+  `.kimi-code/skills/` catalogs (user and project) are surfaced through the dsh
+  skill-injection seam, and its slash commands are bridged (built-ins forward the
+  raw `/name` line back to the engine, which expands it). The prompt is an ACP
+  request body — not an argv positional — so there is no command-line length
+  ceiling. Note Kimi's remaining slash-command surface is TUI-only
+  (`/login`, `/provider`, `/settings`, `/sessions`, …); those are not bridged
+  because the ACP prompt surface does not expand them, but `skill:` commands are
+  carried by the skill seam and Kimi's own shorthand.
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,38 @@
+# dsh-loop-engine
+
+[![npm version](https://img.shields.io/npm/v/dsh-loop-engine?color=cb3837)](https://www.npmjs.com/package/dsh-loop-engine)
+
+像切换模型一样切换 **dsh web** 的 agent 循环引擎:设置页的「Loop engine」下拉选择运行 agent 的驱动——内置 in-process 循环、Claude Code CLI、Codex CLI、Pi CLI,或 Kimi Code CLI——**无需改动主仓库**。
+
+## 安装
+
+```sh
+dsh plugin --profile web add dsh-loop-engine
+```
+
+重启 `dsh web`,然后打开 **Settings → Loop engine**。
+
+> 切换引擎会重写 `cordis.patch.yml` 中一小段受管理的内容,文件里你写的其它部分都会保留,只改动插件自己的区间。
+
+### 环境要求
+
+- 使用 Claude Code 引擎时需要本机已安装并登录 Claude Code CLI。
+- 使用 Codex 引擎时需要完成认证:本机执行过 `codex login`,或配置 `CODEX_API_KEY` 环境变量。
+- 使用 Pi 引擎时需要以 `pi` 要求的方式完成认证(其自身的 `~/.pi/agent/auth.json`,或提供方的 API-key 环境变量,如 `ANTHROPIC_API_KEY`)。
+- 使用 Kimi Code 引擎时需要本机已安装并登录 `kimi` CLI(例如 `kimi login`),且在 `PATH` 上(或在组合条目里用 `kimiBin` 固定为绝对路径)。
+
+## 使用方法
+
+1. 在 **Settings → Loop engine** 选择引擎——`in-process`(默认)、`claude-code`、`codex`、`pi` 或 `kimi`——然后重启 `dsh web`。
+2. 要切回默认,选 **In-process** 再重启即可。
+3. 卸载插件:`dsh plugin --profile web remove dsh-loop-engine`,然后重启 `dsh web`。
+
+### 引擎说明
+
+- Codex 驱动运行 `codex app-server`,没有交互式工具审批——权限来自会话的 `sandboxMode` + `approvalPolicy`。
+- Pi 驱动运行 `pi --mode rpc`;Pi 没有权限系统,所以整个子进程经 dsh subprocess 服务做沙箱化(默认 `read-only`)。
+- Kimi Code 驱动运行一个常驻的 `kimi acp` 子进程(Agent Client Protocol over stdio),每步一次无状态的 `session/new` + `session/prompt`;durable 会话日志是唯一模型上下文。它把助手文本(`agent_message_chunk`)与**思考**(`agent_thought_chunk`)**增量**写入日志,并把工具调用/流(`tool_call` / `tool_call_update`)映射为 `tool/call` + `tool/result`。ACP 通过 `session/request_permission` 暴露工具审批,驱动根据会话的 dsh 审批旋钮应答(ask 策略拒绝,失败关闭)。子进程经 dsh subprocess seam 拉起——唯一权限边界(默认只读沙箱)。其项目 `AGENTS.md` 链(cwd→git 根)与 `.kimi-code/skills/` 目录(用户与项目)通过 dsh 技能注入接口暴露,其斜杠命令也已桥接(内置命令把原始 `/name` 行转发回引擎展开)。prompt 是 ACP 请求体而非 argv 位置参数,因此**不存在命令行长度上限**。注意 Kimi 剩余的斜杠命令面是纯 TUI(`/login`、`/provider`、`/settings`、`/sessions`…),这些不桥接(ACP prompt 面不扩展它们);`skill:` 命令由技能接口与 kimi 自身的 shorthand 承载。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: loop-engine
+      name: 'dsh-loop-engine'