dsh-loop-engine-allinone 0.0.0-stage → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+All notable changes to this fork. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.4.0]
+
+### Added
+
+- **Grok Build (`grok`)** — ACP engine over `grok agent stdio`.
+  - `session/new` refuses an unauthenticated client, so the driver answers ACP's
+    `authenticate` with the method id `initialize` published, retries once, and
+    otherwise reports the registry's login hint instead of a raw JSON-RPC error.
+  - Model selection is `session/set_config_option` with a **bare value**; the
+    `{ value }` wrapper the vendor's documentation shows is rejected `-32602`.
+    (Measured after signing in; the earlier "documented spelling first, fall back"
+    guess was wrong and is gone.)
+  - The model catalog is read from the signed-in agent's own
+    `initialize._meta.modelState` (`grok-4.7`), not from the unauthenticated
+    `grok models` command, which reports ids this surface refuses.
+  - Declares `images: false`: `promptCapabilities.image` is false, and sending an
+    image block would reject the whole prompt.
+- **MiniMax Code (`minimaxcode`)** — ACP engine over `mcode acp`, aimed at the
+  M Plan **subscription** rather than an API key (`mcode login`, then
+  `mcode provider use token-plan`; the plugin never logs in and never reads the
+  credential).
+  - Resolves the npm package entrypoint, and launches a Windows `.cmd` shim
+    through the command interpreter — `spawn('mcode')` fails `ENOENT` and
+    `spawn('mcode.cmd')` throws `EINVAL`, both measured.
+  - Region travels as `MAVIS_REGION` (measured as the variable this surface
+    honours; `MCODE_REGION` is inert here), with the `cn|en` value domain the CLI
+    validates — not the login flag's `cn|global`.
+  - States `permissionMode` on every opened session rather than inheriting
+    whatever the CLI last persisted, because that default can be Full access.
+- **ACP client-side capabilities** (`driver-acp/capabilities.ts`,
+  `driver-acp/terminal.ts`) — the other half of ACP, and what makes a
+  tool-using ACP engine actually work.
+  - `terminal/create` and its lifecycle, plus `fs/read_text_file`.
+  - The terminal bridge routes through the harness's own `shell` service, i.e. the
+    same executor dsh's `bash` tool uses, so an engine's command gets the same
+    sandbox, timeout policy and output caps. With no shell service it **refuses**
+    rather than falling back to an unconfined spawn.
+  - The announced `clientCapabilities` is derived from the implemented handlers, so
+    a declared capability is always an implemented one; a filesystem **write** is
+    never announced.
+- `capabilities.acpProtocolVersion` — the version announced at `initialize` is
+  registry data now, not a constant in the shared client.
+- `EngineDescriptor.region` — an engine whose CLI scopes accounts by region
+  declares the knob, the environment variable and the accepted values.
+- `scripts/probe/acp-handshake.mjs` and `scripts/probe/smoke-acp.ts` — dump an ACP
+  engine's frames, or drive one through the plugin's own profile.
+- `CONTRIBUTING.md`, `SECURITY.md`, this changelog.
+
+### Changed
+
+- **`engine-kimi/acp/` → `driver-acp/`**, and `KimiAgent`'s turn/step machine
+  generalised into `AcpEngineAgent`. Kimi keeps its class names and constructor
+  shapes; its entire suite passes unchanged, which is the regression pin for the
+  move.
+- An ACP engine is now a **profile** (argv, protocol version, model dialect,
+  session handshake, endpoint handover) plus four small files. Adding the fourth
+  one does not touch shared code.
+- Tool vocabulary: MiniMax Code's measured `bash` call is a **declared identity**
+  (a table row meaning "read and found to agree"), and grok deliberately has no
+  row — its only measured tool runs through the client-side terminal bridge, and
+  renaming it to dsh's `bash` would dress a failing call up as a working one.
+
+### Fixed
+
+- `smoke-acp.ts <engine>` skipped the engine name as if it were `--bin`'s value
+  when `--bin` was absent, so `smoke-acp.ts grok` silently ran minimaxcode.
+- grok's `authenticate` sat outside its `try`, so a failure there (which is what a
+  signed-out host produces, since the call starts the vendor's browser sign-in)
+  surfaced "process exited unexpectedly" instead of an actionable hint.
+- `.gitignore` now covers a stray CLI home directory: a relative `GROK_HOME` once
+  made an engine write its whole state dir — `auth.json` included — into this repo.
+
+### Known limitations
+
+- **grok's tools need the harness shell service.** Its shell tools run through the
+  client-side terminal bridge; a composition without `ctx.shell` refuses them
+  rather than running them unconfined. Grok's reasoning and conversation work
+  either way.
+- **`claudeBin` cannot unload the bundled SDK.** Pointing it at an external binary
+  changes what executes, but `@anthropic-ai/claude-agent-sdk` is a value import in
+  `engine-claude/agent.ts`, so the package stays required. `codexBin` and `piBin`
+  CAN fully unbind their bundled copies.
+- **Bundled engines have no runtime updater** by design: their version is this
+  package's dependency pin, so upgrading means changing the dependency, not
+  rewriting it in place.
+
+## [0.3.0] and earlier
+
+The upstream plugin's history. See
+[`kuun993/dsh-loop-engine`](https://github.com/kuun993/dsh-loop-engine).

package/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing
+
+Thanks for looking. This is a fork, and it stays useful only if it is easy to
+extend — so the most valuable contribution is **another engine**, not another
+refactor.
+
+## Before you start
+
+- Read [`docs/engine-registry.md`](docs/engine-registry.md). It is the "add an
+  engine" recipe, and it records the traps that cost real time.
+- **Probe first.** An engine's wire protocol is recorded from real frames before a
+  driver is written for it. A guessed frame shape produces a driver that looks
+  finished and silently answers nothing. `scripts/probe/` is that record.
+- Never guess a capability. `capabilities` describes what the DRIVER was verified
+  to do, not what the vendor's documentation claims. `images: false` for an engine
+  that turns out to accept images is a bug; `images: true` for one that rejects
+  them is a broken turn.
+
+## Adding an engine
+
+The full recipe is [`docs/engine-registry.md`](docs/engine-registry.md) §2. In
+short, for an ACP engine (three of them share one skeleton, so this is four small
+files):
+
+1. add the id to `HOSTED_ENGINE_IDS` (append only — ids are persisted);
+2. add its `ENGINE_REGISTRY` row (TypeScript refuses a missing one);
+3. write `src/engine-<id>/{process,profile,agent,loop}.ts`;
+4. add its driver factory to `src/engine-drivers.ts`;
+5. add its copy to `src/client/locales.ts` and its mark to
+   `src/client/engine-marks.ts`.
+
+Then:
+
+```sh
+node node_modules/typescript/bin/tsc -p tsconfig.build.json --noEmit
+node node_modules/vitest/vitest.mjs run
+node build.mjs
+```
+
+All three must pass. The suite is the contract: a new engine that lands without
+tests is a new engine nobody can safely change later.
+
+## What a pull request needs
+
+- **A probe artifact.** Frames dumped from the real CLI, in the PR body (not
+  necessarily committed — they can be large). Without it a protocol claim is a
+  guess.
+- **A driver smoke result**, when the CLI can run on your machine:
+  `node node_modules/tsx/dist/cli.mjs scripts/probe/smoke-driver.ts <engine>` for
+  the CLI-family drivers, or `smoke-acp.ts <engine>` for an ACP one.
+- **Tests for the behaviour you changed**, not just for the happy path. The
+  failures this codebase has actually shipped were mostly "no error, wrong data"
+  (a stream that never reached the durable log, a tool call split across two
+  messages, a config value that looked right and did nothing).
+- **An honest UNKNOWN.** If something could not be measured on your machine, say
+  so in the docs rather than filling it in. A documented gap is worth more than a
+  plausible invention.
+
+## Style
+
+- Comments explain **why**, and they cite the measurement or the failure that
+  produced the rule. "This is load-bearing because X failed" beats "this is
+  important".
+- Every module starts with a `@module` tag and a paragraph on what it is for.
+- Do not reformat code you are not changing. Diffs should be readable.
+
+## Reporting a bug
+
+Include: the engine, its version (`<cli> --version`), the harness line
+(0.1.5 / 0.1.7 / 0.2.0), the profile, and what you expected vs what happened. If
+the bug is protocol-shaped, the probe output is the single most useful thing you
+can attach.
+
+## Security
+
+Engine credentials are the engines' own business: this plugin never reads, writes
+or refreshes them, and a profile should never contain one. If you find a path where
+that is not true, treat it as a security report — see [SECURITY.md](SECURITY.md).

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 kuun993 (original author, https://github.com/kuun993/dsh-loop-engine)
+
+Copyright (c) 2026 dsh-loop-engine-allinone fork contributors
+
+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/NOTICE

@@ -0,0 +1,45 @@
+dsh-loop-engine-allinone
+========================
+
+This project is a fork of **dsh-loop-engine** by kuun993:
+
+    https://github.com/kuun993/dsh-loop-engine
+
+The original work is MIT-licensed. Its copyright notice is preserved in the
+`LICENSE` file, alongside this fork's own.
+
+## What the fork adds
+
+The upstream plugin already switches the agent loop engine per session. This fork
+contributes an ARCHITECTURE and the engines it made cheap to add:
+
+- **A single data-driven engine registry** (`src/engine-registry.ts`). The engine
+  roster, its capability declarations, its model catalogs and its display copy are
+  declared once; the settings schema, the preset ids, the driver dispatch and the
+  browser half all derive from that table. Upstream restated the roster in five
+  places, so adding an engine meant finding all five.
+- **A pluggable driver layer**: `driver-cli/` for line-delimited CLI protocols and
+  `driver-acp/` for the Agent Client Protocol. An ACP engine is a profile plus four
+  small files, and adding the fourth does not touch shared code.
+- **Six additional engines**: Antigravity, ZCode, Qoder CN, Hermes, Grok Build and
+  MiniMax Code.
+- **Client-side ACP capabilities** (`terminal/*`, `fs/read_text_file`), routed
+  through the harness's own shell and filesystem services, which is what lets an
+  engine that drives its tools through the client actually use them.
+
+## What the fork does NOT change
+
+The four original engines' protocol code is untouched. `kimi` was migrated onto the
+shared ACP skeleton without a behavior change, and its unchanged test suite is the
+regression pin for that move.
+
+## Third-party artwork
+
+The engine marks in `src/client/engine-marks.ts` are traced or measured from each
+vendor's own published artwork, and remain the trademarks of their respective
+owners. They are used here only to identify the engine a user selected.
+
+## Modifications
+
+Modifications made by this fork are licensed under the same MIT terms as the
+original. See `LICENSE`.

package/README.md

@@ -1,3 +1,222 @@
-# Temporary Holding Version
+# dsh-loop-engine-allinone
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Harness: 0.1.5 / 0.1.7 / 0.2.0](https://img.shields.io/badge/harness-0.1.5%20%7C%200.1.7%20%7C%200.2.0-6f42c1)](#version-compatibility)
+
+Pick **dsh web**'s agent loop engine **per session** — the built-in `in-process` loop (the default), or one of the hosted engines `claude-code` / `codex` / `pi` / `kimi` / `agy` / `zcode` / `qoderclicn` / `hermes` / `grok` / `minimaxcode`. Sessions are independent: one chat can run Codex while another runs Kimi. Any open, idle session can move engines — between two hosted engines the handover is **in place**, and a move involving `in-process` **reloads the page** (the `dsh web` process never restarts). Nothing in the main repository changes.
+
+> **A fork of [`kuun993/dsh-loop-engine`](https://github.com/kuun993/dsh-loop-engine).**
+> The upstream plugin already switched engines per session. This fork's contribution
+> is an **architecture** — a single data-driven engine registry plus a pluggable
+> driver layer — and the six engines that architecture made cheap to add.
+>
+> | | upstream | this fork |
+> |---|---|---|
+> | engine roster | hardcoded in five places | **one registry table**; everything else derives |
+> | adding an engine | edit five files | **one registry row + one driver** |
+> | engines | 4 | **10** |
+> | ACP engines | 1 (kimi) | **3** (kimi, grok, minimaxcode) sharing one skeleton |
+> | external-CLI drivers | per-engine | `driver-cli/` + `driver-acp/` |
+>
+> The four original engines' protocol code is untouched. `kimi` was migrated onto
+> the shared ACP skeleton **without a behavior change**, and its unchanged test
+> suite is the regression pin.
+>
+> Two things worth knowing before you add an engine:
+> - [`docs/engine-registry.md`](docs/engine-registry.md) §2 step 6 is the **entire**
+>   recipe for an ACP engine: a profile plus four small files.
+> - **Probe first.** Every protocol claim in this repository came from real frames
+>   (`scripts/probe/`), never from a specification. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Engine marks
+
+Every engine has its own mark in the engine picker and its own colour + glyph on
+the chat's turn-status row; **only `in-process` carries the DeepSeek fish**.
+
+The three engines this fork added as external CLIs are **traced or measured from
+the vendors' own artwork found on this machine** — Antigravity's arch, ZCode's
+knocked-out `Z` (written out from measured spans, because its straight edges
+defeat a raster trace), and Qoder's green disc with the white crescent between its
+two forms. Kimi's mark was rebuilt from its app tile: a bold `K` plus the brand's
+blue dot, which rides an `accent` subpath because one path can only be filled one
+way.
+
+Hermes is the exception worth knowing about: that vendor's mark is a detailed
+character portrait rather than a glyph, so its mark is the portrait's own line art.
+
+The two ACP engines this fork added are traced from the artwork the user supplied:
+**Grok Build**'s black ring-and-slash (its slash tips are ~1px diagonals, which is
+why that trace is 8-connected — a 4-connected contour lops the tips off), and
+**MiniMax Code**'s white blob on the brand's blue tile, whose gradient is why its
+mask rule is "the darkest channel is still high" rather than a luminance
+threshold. Grok's vendor-published ACP icon is the same mark drawn about one pixel
+bolder; the comparison is recorded in the fork's probe report.
+Marks live in [`src/client/engine-marks.ts`](src/client/engine-marks.ts) as data
+rather than JSX, so a test can assert that every registered engine has one.
+
+Both tables are exhaustive over the hosted roster and pinned by tests — the
+failure this prevents is real: when four engines were first added, every one of
+them fell through the mark switch's `default` arm and rendered the DeepSeek fish
+beside its name.
+
+## Engine registry
+
+Every engine-shaped decision derives from ONE table,
+[`src/engine-registry.ts`](src/engine-registry.ts): the id roster, the settings
+schema's union, the authored preset ids and display names, the browser half's
+option list and copy keys, and the driver dispatch
+([`src/engine-drivers.ts`](src/engine-drivers.ts)). Both tables are total over
+the hosted ids, so a half-added engine fails the build rather than shipping an
+engine that mounts but cannot be selected.
+
+Each row declares what the surfaces need to know: human-readable label, source
+repo, whether the engine is an npm-bundled dependency or an external CLI, the key
+its executable override reads, its version/update argv, its login hint, its
+credential paths, and its **capabilities** (`streaming`, wire `protocol`,
+`sessionResume`, `permissionModes`, `images`, `reasoningLevels`). Capabilities are
+declarations, not discoveries: a surface never promises more than the engine was
+verified to do, and a driver asked for something outside its declaration refuses
+with the user's next action rather than degrading silently.
+
+New engines implement one method. `src/driver-cli/` supplies the rest: the
+turn/step lifecycle (`cli-agent.ts`), the durable-log writer
+(`session-sink.ts` — where the session format's "refuse to load" rules are
+enforced in one place), the subprocess transport, and four protocol skeletons
+(`ndjson`, `stream-json` for the Claude-Code dialect, `text`, plus the existing
+engines' ACP and JSON-RPC drivers as their templates).
+
+## Install
+
+```sh
+# From this repository (the npm package name `dsh-loop-engine-allinone` belongs to
+# upstream, so installing from git names the fork explicitly):
+dsh plugin --profile web add yaliklinty/dsh-loop-engine-allinone
+
+# From a local checkout:
+dsh plugin --profile web add /path/to/dsh-loop-engine-allinone
+```
+
+Boot `dsh web` once (the router retries for a bounded window while the base bundle still holds the agent-factory slot), then open **Settings → Loop engine**.
+
+**Install notes**
+
+- The install rewrites one **engine-agnostic** managed block in the profile's `cordis.patch.yml`; every other byte you wrote there is preserved. Upgrading from an older release needs no hand edit.
+- **Installing into any profile but `web`** — the Desktop app's `desktop`, a `headless` deployment, a renamed profile — needs `profile: <name>` in the composition entry for that profile:
+  ```yaml
+  - id: loop-engine
+    config:
+      profile: desktop
+  ```
+  `profile` defaults to `web`, so without it the plugin writes its managed block into `<home>/profiles/web/cordis.patch.yml` while the running profile never reads it: the plugin mounts, but the base `agent-loop` row is never disabled, so its router cannot take the factory slot and no hosted engine is reachable. (Found by installing into the Desktop app.)
+- **Uninstall** is `dsh plugin --profile web remove dsh-loop-engine-allinone` **plus deleting that managed block** — the block outlives the plugin, and while it is present the profile has no agent factory, so no session can be created.
+- **pnpm 10+** may block dependency build scripts (`ERR_PNPM_IGNORED_BUILDS`, naming `esbuild`, `@google/genai`, `protobufjs`). Run `pnpm approve-builds` (or add an `allowBuilds` entry) and retry; only the installing project can grant this.
+- **Booting the harness from its source checkout** additionally needs the profile's harness peers bridged with `file:` shims — otherwise session resume fails with `agent-presets: refusing to compose an unscoped context`. Steps in [docs/source-checkout.md](docs/source-checkout.md).
+
+## Requirements
+
+| Engine | Needs, on the host |
+|---|---|
+| Claude Code | the Claude Code CLI installed and logged in (or none: the SDK ships a bundled binary) |
+| Codex | `codex login`, or a `CODEX_API_KEY` environment entry |
+| Pi | whatever `pi` expects (its own `~/.pi/agent/auth.json`, or the provider's API-key variable) |
+| Kimi Code | the `kimi` CLI installed and logged in, on `PATH` (or pinned via `bins.kimiBin`) |
+| Antigravity | the `agy` CLI installed and signed in to Google |
+| ZCode | the ZCode CLI and a live GLM Coding Plan subscription |
+| Qoder CN | the `qoderclicn` CLI installed and signed in |
+| Hermes Agent | the `hermes` CLI installed and signed in; it reads its own `HERMES_HOME`, which the child inherits |
+| Grok Build | the `grok` CLI installed (`~/.grok/bin/grok.exe`, or `npx @xai-official/grok@<pinned> agent stdio`) and signed in once through `grok` / `grok login` — its ACP server refuses `session/new` until it has an account |
+| MiniMax Code | `npm i -g @minimax-ai/code`, then `mcode login --region cn\|global` and `mcode provider use token-plan` to spend the M Plan allowance instead of an API key |
+
+## Usage
+
+- **New session** — pick the engine on the preset chip beside the workspace picker, or keep the deployment's default (`standard`) for the in-process loop. A child agent inherits its parent's engine.
+- **Settings → Loop engine** sets the default for **new** sessions. It lands immediately; running sessions are unaffected. **In-process** restores whatever default the plugin replaced.
+- **Move a session you are in** with the composer's engine selector (enable *Show the engine selector in the chat page*).
+  - Hosted → hosted: in place, applies on the spot.
+  - Anything involving `in-process`: the composer asks first, then the page reloads and reopens the same session (scroll position and unsent draft are lost; the record is not).
+  - A mid-turn session is refused, and a subagent's session cannot be moved.
+- **The header chip** beside the preset label names the engine the session on screen actually runs; *Show the engine badge in the conversation header* turns it off (and the header keeps no trace of the plugin).
+- **Models** — two kinds of group, on purpose.
+  - **An engine that declares its own catalog gets a group of its own**, named by the engine (today: `Antigravity`, `Grok Build`, `MiniMax Code`), holding `default` plus the models that engine's own subscription includes. Picking one hands that id to the engine — `agy --model gemini-3.8-flash-low`, or a `session/set_config_option` for the ACP engines — so you choose among the models you actually pay for instead of accepting "the engine decides". `default` still means exactly that.
+  - **Every other engine shares the `external` group** with its single `default`. That is not a leftover: the model catalog is built per Host *generation*, not per session, so a group per engine would put eight identical `default` rows in every session's menu. A group only earns its place by carrying models the others do not.
+  - Picking a **real dsh model** still hands it to the engine together with its endpoint and credential; whether the engine can serve it is the engine's business, and a refusal is reported rather than swallowed. A pick belonging to a *different* engine's group is refused with the mismatch named, never silently ignored.
+  - The catalog is **declared in the engine registry**, not probed at boot — this plugin starts no external process when the harness boots. A deployment whose subscription changed updates [`src/engine-registry.ts`](src/engine-registry.ts)'s `models` row; a stale id then fails loudly at the engine, which is the honest outcome.
+  - `in-process` sessions use dsh's models normally.
+- **`bins`** (composition entry, optional) — per-engine executable overrides, keyed by each engine's registry `binConfigKey`. Pointing a **bundled** engine at an external CLI is how it is unbound: `claudeBin` reaches the SDK's own `pathToClaudeCodeExecutable`, while `codexBin` / `piBin` replace the entrypoint those drivers launch. Not setting one keeps the bundled copy and its argv byte for byte:
+  ```yaml
+  - id: loop-engine
+    config:
+      bins:
+        claudeBin: 'D:/tools/claude.exe'
+        kimiBin: 'D:/tools/kimi.exe'
+        qoderclicnBin: 'D:/tools/qoderclicn.exe'
+        grokBin: 'C:/Users/me/.grok/bin/grok.exe'
+        minimaxcodeBin: 'D:/Programs/npm-global/node_modules/@minimax-ai/code/cli.js'
+  ```
+  An npm-installed CLI needs no pin (the resolver finds the package entrypoint, and
+  a Windows `.cmd` shim is launched through `cmd.exe` — node refuses a `.cmd`
+  directly), but a pin is the way to choose among several installs.
+- **`regions`** (composition entry, optional) — per-engine account **region**
+  overrides, keyed by each registry row's `region.configKey`. Today only MiniMax
+  Code declares one (`regions.mcodeRegion`, default `cn`), because its login
+  endpoint AND its stored credentials are region-scoped:
+  ```yaml
+  - id: loop-engine
+    config:
+      regions:
+        mcodeRegion: 'en'   # this engine's spelling of the non-China account
+  ```
+  The value is spelled into the child's environment as the variable that engine's
+  CLI actually reads (`MAVIS_REGION` — measured, and NOT `MCODE_REGION`, which is
+  inert on the `mcode acp` path). An unknown value, or a `region` that contradicts
+  the same variable in `env`, fails the engine's construction loud rather than
+  pointing the child at an account nobody chose.
+- **`childIdleMs`** (composition entry, milliseconds, default `0` = off) — Kimi and Codex keep **one child process per session** across steps; this closes it after that much idle time and respawns it on the next step. Only the child is closed, so nothing reloads. Pi and Claude Code spawn per step and are unaffected.
+- **`engineContextWindow`** (composition entry, tokens, default `262144`) — the context window dsh assumes for the shared hosted route. It is what dsh's auto-compaction measures a hosted session against (it fires at 80% of this by default), because a hosted engine reports no capacity of its own. Set it to the **smallest** window among the engines you run.
+- **`summarizerProvider` / `summarizerModel`** (composition entry, **set together or not at all**) — the real dsh model a hosted session's **compaction** summarizes through, e.g. `deepseek-official` / `deepseek-flash`. Compaction is dsh's own (its preset keeps the `compaction` group), but the summarizing *call* is an ordinary llm request, and a hosted session's routed model is the plugin's placeholder route — so without this pair a hosted session can never be folded down: every attempt logs a warning and the turn continues. The pair only serves that call; the engine still answers every user turn itself. Composing just one of the two (or an empty string) is refused at boot, not silently ignored.
+- **dsh's own commands** (`/export`, `/feedback`, `/permission`) keep working under a hosted engine. Its preset is a copy of `standard` with the dsh-native rows an external engine replaces stripped out (dsh's `/plan`, the goal tool and `/goal`, the skill rows). dsh's **compaction is kept**: it is what keeps the session log — and so the transcript replayed to the engine on every step — bounded, which an engine's own per-turn compaction cannot do (a fresh engine session is opened per step, so the engine's shrink is discarded while the log keeps growing). Configure `summarizerProvider` / `summarizerModel` (above) or its summarizing call has no model to run on.
+
+## Version compatibility
+
+One release serves the **0.1.5 line** (`>=0.1.5-rc.1 <0.1.6-0`), the **0.1.7 line** (`>=0.1.7-rc.1 <0.1.8-0`) and the **0.2.0 line** (`>=0.2.0-rc.1 <0.2.1-0`): the plugin detects the running generation at load and takes the matching code path. Those union ranges are what it declares in `peerDependencies`, and a harness outside them fails loudly at boot or session resume.
+
+Read the version as `<harness line>-rcN`, where **`rcN` is this plugin's own release counter for that line** — not the harness's `rc` number. Within a covered line a new harness `rc` needs no plugin release unless an API surface moved; [docs/compatibility.md](docs/compatibility.md) §1 lists those surfaces and the diff command that decides it.
+
+| Plugin | Harness |
+|---|---|
+| `0.2.0-rc1` | `0.2.0-rc.1`, `0.2.0-rc.2` |
+| `0.1.7-rc1` … `0.1.7-rc5` | `0.1.7-rc.1`, `0.1.7-rc.2` |
+| `0.1.5-rc3` … `0.1.5-rc5` | `0.1.5-rc.2` |
+| `0.1.5-rc1` / `0.1.5-rc2` | `0.1.5-rc.1` |
+| `1.0.0-rc8` … `1.0.0-rc15` | `0.1.2-rc.1` |
+| `1.0.0-rc7` and earlier | `0.1.1-rc.2` |
+
+`0.2.0-rc1` is the first release that serves three lines at once, and the first one published after the harness started enforcing a peer-range gate at boot: the plugin is still mounted alongside an incompatible one, but a harness outside the ranges above is now skipped by dsh itself rather than failing later.
+
+## Known limitations
+
+- **It replaces the harness's agent factory.** One facade serves every session, so the plugin promises to stay out of the way: any session it cannot answer for — including sessions with nothing to do with hosted engines — degrades to the `in-process` loop instead of failing to open. See [docs/per-session-engine.md](docs/per-session-engine.md) §6.
+- **The engine record is a sidecar**, `$DSH_HOME/.loop-engine/engines.json`, not part of the session log: changing machine or `DSH_HOME` loses it and the session falls back to its preset. See §5.5.
+- **Moving a session involving `in-process` reloads the page** — the harness loop neither hands over a live session nor adopts one it did not create. See §5.2/§5.4.
+- **Sessions that already ran a turn** can still move, but only while idle, and the move rebuilds that session's agent. See §5.
+- **Old sessions with the legacy preset id `loop-engine`** read as "legacy hosted engine" until rebuilt once. See §7.
+- **Same-engine sessions share that CLI's own auth directory**, with no lock added by the plugin. See §6.
+- **Switching back to `in-process` leaves the shared `external` group in the model menu** (the catalog is not scoped per session).
+
+## Where the details live
+
+- [docs/per-session-engine.md](docs/per-session-engine.md) — the full user-visible behavior (§ numbers above refer to it).
+- [docs/architecture.md](docs/architecture.md) — plugin core: the single factory slot, the managed block, routing, the provider route.
+- [docs/compatibility.md](docs/compatibility.md) — **start here when the harness upgrades**: every generation-dependent code site and the checklist for the next generation.
+- [docs/driver-core.md](docs/driver-core.md) — the shared driver infrastructure.
+- [docs/engine-claude.md](docs/engine-claude.md) · [engine-codex](docs/engine-codex.md) · [engine-kimi](docs/engine-kimi.md) · [engine-pi](docs/engine-pi.md) — per-engine internals. The ACP engines (`kimi` / `grok` / `minimaxcode`) share `driver-acp/`, whose per-engine surface is documented in [docs/engine-registry.md](docs/engine-registry.md) §2 step 6.
+- `scripts/probe/acp-handshake.mjs` · `scripts/probe/smoke-acp.ts` — dump a real ACP engine's frames, or drive one through the plugin's OWN profile (`node node_modules/tsx/dist/cli.mjs scripts/probe/smoke-acp.ts minimaxcode`).
+- [docs/source-checkout.md](docs/source-checkout.md) — the `file:` shims a source-launched harness needs.
+- [docs/optimization-backlog.md](docs/optimization-backlog.md) — known issues and the optimization list.
+- [docs/proposals/](docs/proposals/) — main-repo proposals.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for the full text. The upstream author's copyright
+notice is preserved there beside this fork's own; [NOTICE](NOTICE) records what the
+fork adds and what it deliberately leaves untouched.

package/README.zh.md

@@ -0,0 +1,89 @@
+# dsh-loop-engine-allinone
+
+[![npm version](https://img.shields.io/npm/v/dsh-loop-engine-allinone?color=cb3837)](https://www.npmjs.com/package/dsh-loop-engine-allinone)
+
+像选模型一样选 **dsh web** 的 agent 循环引擎——**按会话**选:内置的 `in-process`(默认),或四个托管引擎 `claude-code`、`codex`、`pi`、`kimi`。会话之间互不影响:一个对话跑 Codex,另一个可以同时跑 Kimi。只要会话打开且空闲,任何时候都能换引擎——两个托管引擎之间是**原地换手**,有一边是 `in-process` 时会让**页面重新载入**(`dsh web` 进程本身**不重启**)。以上**无需改动主仓库**。
+
+## 安装
+
+```sh
+dsh plugin --profile web add dsh-loop-engine-allinone
+```
+
+启动一次 `dsh web`(路由器会在有界窗口内重试,等基础 bundle 让出 factory 槽位),然后打开 **Settings → Loop engine**。
+
+**安装须知**
+
+- 安装会重写 profile 的 `cordis.patch.yml` 里一小段**不带引擎 id** 的受管理块;文件里你写的其它部分逐字节保留。从更早版本升级**不需要手工改文件**。
+- **装到 `web` 以外的 profile**(桌面版的 `desktop`、`headless` 部署、改过名的 profile)必须在该 profile 的组合条目里写上 `profile: <名字>`:
+  ```yaml
+  - id: loop-engine
+    config:
+      profile: desktop
+  ```
+  `profile` 默认是 `web`,不写的话插件会把受管块写进 `<home>/profiles/web/cordis.patch.yml`,而正在跑的那个 profile 永远不会读它:插件挂着,但基础 `agent-loop` 行没被禁,路由器拿不到 factory 槽位,任何托管引擎都不可达。(这是装进桌面版时踩出来的。)
+- **卸载**是 `dsh plugin --profile web remove dsh-loop-engine-allinone` **再加上删掉那段受管理块**——块会比插件活得久,而它还在时 profile 里没有任何 agent factory,会话一条也建不出来。
+- **pnpm 10+** 可能拦下依赖的 build script(`ERR_PNPM_IGNORED_BUILDS`,列出 `esbuild`、`@google/genai`、`protobufjs`)。执行 `pnpm approve-builds`(或加一条 `allowBuilds`)后重试;只有安装方能授予这个权限。
+- **用源码启动 harness** 时还要多做一步:用 `file:` shim 把 profile 的 harness peer 包桥接到 checkout 源码,否则恢复会话会报 `agent-presets: refusing to compose an unscoped context`。步骤见 [docs/source-checkout.md](docs/source-checkout.md)。
+
+## 环境要求
+
+| 引擎 | 本机需要 |
+|---|---|
+| Claude Code | 已安装并登录 Claude Code CLI |
+| Codex | 执行过 `codex login`,或配置 `CODEX_API_KEY` |
+| Pi | `pi` 自己要求的认证方式(其 `~/.pi/agent/auth.json`,或提供方的 API-key 环境变量) |
+| Kimi Code | 已安装并登录 `kimi` CLI,且在 `PATH` 上(或用 `kimiBin` 固定路径) |
+
+## 使用方法
+
+- **新会话**——在 preset 选择器(工作区选择器旁的 chip)上选引擎;保留部署自己的默认(通常是 `standard`)则走 in-process。子 agent 沿用拉起它的那个 agent 的引擎。
+- **Settings → Loop engine** 决定**新会话**的默认引擎:改完立即生效,已经在跑的会话不受影响。选 **In-process** 会把插件接手前的默认值恢复回去。
+- **换当前这条会话**用对话页 composer 的引擎选择器(勾选 *在对话页显示引擎选择器*)。
+  - 托管 → 托管:原地换手,当场生效。
+  - 涉及 `in-process` 的方向:先弹确认框,确认后页面重新载入并回到同一条会话(滚动位置与未发出的草稿会丢,会话记录不丢)。
+  - 正在跑一轮的会话会被**拒绝**,子 agent 的会话不能换。
+- **对话头部那个标记**(preset 标签旁边)写的是这条会话**实际在跑**的引擎;取消勾选 *在对话头部显示引擎标记* 即可关掉它(关掉后 header 上不留插件的任何痕迹)。
+- **模型**——所有托管引擎共用 **一个** `external` 分组,里面只有一条 `default`,含义是"交给引擎自己决定"。选一条**真实的 dsh 模型**会把模型连同它的端点与凭据一起交给引擎;引擎能不能用是引擎的事,**被拒会如实报错而不是悄悄吞掉**。`in-process` 会话照常用 dsh 的模型。
+- **`childIdleMs`**(组合条目,毫秒,默认 `0` = 不启用)——Kimi 与 Codex **每条会话保有一个常驻子进程**跨 step 复用;设了它就在空闲这么久之后把子进程关掉,下一步再重新拉起。只关子进程,所以不会触发任何重载。Pi 与 Claude Code 每步各起一次,不受影响。
+- **dsh 自己的命令**(`/export`、`/feedback`、`/permission`)在托管引擎下照常可用。托管引擎的 preset 是 `standard` 的副本,去掉了被外部引擎接管的那几行(dsh 的 `/plan`、`/compact`、goal 工具与 `/goal`、以及技能相关行)。
+
+## 版本兼容
+
+**一个发布版本同时服务两代 harness**:0.1.5 线(`>=0.1.5-rc.1 <0.1.6-0`)与 0.1.7 线(`>=0.1.7-rc.1 <0.1.8-0`)——它在加载期探测当前是哪一代、走对应分支。这两个并集范围就是它在 `peerDependencies` 里声明的范围;超出范围的 harness 会在启动或会话恢复时**响亮地失败**。
+
+版本读作 `<harness 线>-rcN`,其中 **`rcN` 是本插件对那条线的第 N 次发布号**,不是 harness 自己的 `rc` 号。在被覆盖的线里,新的 harness `rc` **不需要**插件跟版——除非某个 API 面动了;[docs/compatibility.md](docs/compatibility.md) §1 列出了这些面与"要不要改代码"的判定命令。
+
+| 插件 | 目标 harness |
+|---|---|
+| `0.1.7-rc1` … `0.1.7-rc5` | `0.1.7-rc.1`、`0.1.7-rc.2` |
+| `0.1.5-rc3` … `0.1.5-rc5` | `0.1.5-rc.2` |
+| `0.1.5-rc1` / `0.1.5-rc2` | `0.1.5-rc.1` |
+| `1.0.0-rc8` … `1.0.0-rc15` | `0.1.2-rc.1` |
+| `1.0.0-rc7` 及更早 | `0.1.1-rc.2` |
+
+## 已知限制
+
+- **它替掉了 harness 的 agent factory。** 唯一那个门面服务所有会话,所以插件对此的承诺是:它读不出引擎的会话——包括跟托管引擎毫无关系的会话——一律**降级到 `in-process`**,而不是打不开。见 [docs/per-session-engine.md](docs/per-session-engine.md) §6。
+- **引擎记录是侧车文件** `$DSH_HOME/.loop-engine/engines.json`,不在会话日志里:换机器或换 `DSH_HOME` 就丢,会话回退到自己的 preset。见 §5.5。
+- **涉及 `in-process` 的换引擎会重新载入页面**——harness loop 既不交出活会话,也不接受不是它建的会话。见 §5.2/§5.4。
+- **已经跑过一轮的会话**仍可换引擎,但只能在空闲时,且会重建那条会话的 agent。见 §5。
+- **带旧 preset id `loop-engine` 的老会话**在重建一次之前显示为"旧版托管引擎"。见 §7。
+- **同引擎的多条会话共享该 CLI 自己的认证目录**,插件不加锁。见 §6。
+- **切回 `in-process` 之后**,模型菜单里那个共享的 `external` 分组仍在(模型目录不按会话裁剪)。
+
+## 细节都在哪
+
+- [docs/per-session-engine.md](docs/per-session-engine.md) —— 按会话选引擎的完整用户可见行为(上面引的 § 就是它)。
+- [docs/architecture.md](docs/architecture.md) —— 插件核心:唯一 factory 槽位、受管理块、路由、provider 路由。
+- [docs/compatibility.md](docs/compatibility.md) —— **harness 升级时先看这篇**:所有依赖代际的代码点与"加下一代"的清单。
+- [docs/driver-core.md](docs/driver-core.md) —— 四个引擎共享的驱动层。
+- [docs/engine-claude.md](docs/engine-claude.md) · [engine-codex](docs/engine-codex.md) · [engine-kimi](docs/engine-kimi.md) · [engine-pi](docs/engine-pi.md) —— 逐引擎内部实现。
+- [docs/source-checkout.md](docs/source-checkout.md) —— 源码启动 harness 需要的 `file:` shim。
+- [docs/optimization-backlog.md](docs/optimization-backlog.md) —— 已知问题与优化清单。
+- [docs/proposals/](docs/proposals/) —— 提交给主仓的提案。
+
+## License
+
+MIT —— 全文见 [LICENSE](LICENSE)。上游作者的版权声明与本 fork 的声明并列保留在其中；
+本 fork 做了什么、刻意没动什么，见 [NOTICE](NOTICE)。

package/SECURITY.md

@@ -0,0 +1,39 @@
+# Security policy
+
+## What this plugin touches
+
+- **It does not own credentials.** Every hosted engine reads its own credentials
+  from its own directory (`~/.grok/auth.json`, `~/.kimi-code/…`, `~/.minimax/…`,
+  the Claude/Codex/Pi installs' own files). The plugin only checks whether an auth
+  path EXISTS, to show a signed-in/not-signed-in hint in the settings page. It
+  never opens one for reading its contents.
+- **It spawns external processes.** Every engine's CLI runs as a child, and every
+  child is spawned through the harness's subprocess seam (`ctx.subprocess`), which
+  is the privilege boundary. ACP engines additionally declare client-side
+  capabilities: an engine may ask the plugin to read a file or run a command. Both
+  go through the harness's own services (`ctx.fs`, `ctx.shell`), so the engine's
+  request is subject to the same policy as the harness's own tools — and the
+  terminal bridge REFUSES rather than falling back to an unconfined spawn when no
+  shell service is present.
+- **It writes to one place in your profile**: the managed block in the profile's
+  `cordis.patch.yml`, plus the agent presets it authors. Both are documented in the
+  README's install notes, and the block is what uninstall must remove.
+
+## Reporting
+
+Open a private security advisory on the repository, or email the maintainer listed
+in `package.json`'s `author` field. Please do not open a public issue for a
+credential-handling or sandbox-bypass problem.
+
+Include: what you expected, what happened, the profile composition (redact
+credentials), and the engine involved. A reproduction that does not need your own
+account is worth much more than one that does.
+
+## What is NOT a vulnerability
+
+- An engine's own tool call being denied by the harness sandbox. That is the
+  sandbox working; the plugin's job is to route the request INTO it, not around it.
+- A hosted engine reporting that it has no subscription or quota. The plugin
+  reports the engine's own words rather than hiding them.
+- The plugin failing to start an engine whose CLI is not installed. The engine is
+  an external dependency by design; see the README's Requirements table.

package/cordis.patch.yml

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