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

package/CHANGELOG.md

@@ -0,0 +1,119 @@
+# 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.1]
+
+### Added
+
+- A language switch in both READMEs (`English · 简体中文`). GitHub only renders
+  `README.md`, so the pair is linked rather than auto-detected.
+
+### Fixed
+
+- `README.zh.md` was a translation of the UPSTREAM plugin: four hosted engines, no
+  registry chapter, nothing about grok/minimaxcode or the ACP capability bridges. It
+  is rewritten from the English README section by section (same nine sections, same
+  order).
+- `tsconfig.json` no longer extends a `../deepseek-harness/` checkout that only
+  exists in the author's working tree, and `vitest.config.ts` applies its harness
+  aliases only when that checkout is present. Before this, a fresh clone could not
+  run `node build.mjs` (TS5083) or `vitest run` (32 suites could not resolve
+  `@deepseek-ai/cordis`).
+
+## [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,224 @@
-# 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.
+**English** · [简体中文](README.zh.md)
+
+[![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.