dsh-loop-engine 0.1.7-rc2 → 0.1.7-rc4

package/README.md

@@ -1,76 +1,76 @@
-# dsh-loop-engine
-
-[![npm version](https://img.shields.io/npm/v/dsh-loop-engine?color=cb3837)](https://www.npmjs.com/package/dsh-loop-engine)
-
-Pick the agent loop engine of **dsh web** the same way you pick a model — **per session**: the built-in `in-process` loop (the default), or one of the four hosted engines `claude-code`, `codex`, `pi`, `kimi`. The engine is the plugin's own per-session record, so **any open, idle session can be moved to another engine** — between two hosted engines it is an **in-place handover**, and a move involving `in-process` releases that session's agent and reloads the page (the `dsh web` process never restarts). Sessions are independent, so one chat can run Codex while another runs Kimi. None of this changes anything in the main repository.
-
-## Install
-
-```sh
-dsh plugin --profile web add dsh-loop-engine
-```
-
-Boot `dsh web` so the profile recomposes with the plugin, then open **Settings → Loop engine**. One boot is enough: the router retries for a bounded window while the base bundle's `agent-loop` row still holds the factory slot.
-
-> Installing rewrites one **engine-agnostic** managed block in `cordis.patch.yml`: it disables the base bundle's `agent-loop` row so the plugin's own router can own the process's single agent-factory slot, and every other byte you wrote in that file is preserved. Upgrading from an earlier release needs no hand edit — a block that named the one pinned engine is rewritten to this form on the next boot, and seeds the Settings default with that engine.
-
-> **pnpm users:** pnpm 10+ blocks dependency build scripts by default, so the install may fail with `ERR_PNPM_IGNORED_BUILDS` naming `esbuild`, `@google/genai`, and `protobufjs` (all reached through the engine SDKs). Allow them and retry — `pnpm approve-builds`, or `allowBuilds` in `pnpm-workspace.yaml`. Only the installing project can grant this; the plugin cannot pre-approve its own dependencies.
-
-### Running against a harness source checkout
-
-A **published** dsh needs no extra setup. Booting the harness from its **source checkout** (`cd deepseek-harness && pnpm dsh web`) takes one more step: bridge the profile's harness peer packages to the checkout source with `file:` shims, so both halves share one module instance (a scope minted through one instance is invisible to the other, and session resume fails with `agent-presets: refusing to compose an unscoped context`). The peer list includes `@deepseek-ai/dsh-agent-loop`. The runnable shim steps are in [docs/source-checkout.md](docs/source-checkout.md); why every `@deepseek-ai/*` package must stay a single instance is in [docs/architecture.md](docs/architecture.md). Installing the plugin as a local **`link:`** checkout sidesteps this entirely.
-
-## Version compatibility
-
-dsh-loop-engine is versioned **in lockstep with the harness it targets**: `<harness version>-rcN`. From `0.1.7-rc1` on, **one release serves two harness generations**: the 0.1.5 line (`>=0.1.5-rc.1 <0.1.6-0`, all sharing the old settings API) and the 0.1.7 line (`>=0.1.7-rc.1 <0.1.8-0`, whose `rc.1` and `rc.2` are both verified). It detects the running generation at load and takes the matching code path, so a single published package installs onto either. Every harness package it consumes declares that union range in `peerDependencies`; a harness outside it fails loudly at boot or session resume. Within a covered line a new `rc` needs no plugin release unless the API surfaces it depends on moved — `docs/compatibility.md` §1 lists the surfaces and the diff command that decides it. `0.1.5-rc3` … `0.1.5-rc5` target harness `0.1.5-rc.2`; `0.1.5-rc1`/`0.1.5-rc2` target `0.1.5-rc.1`; `1.0.0-rc8` … `1.0.0-rc15` target `0.1.2-rc.1`; `1.0.0-rc7` and earlier target `0.1.1-rc.2`.
-
-### Requirements
-
-- **Claude Code**: the Claude Code CLI installed and logged in on the host.
-- **Codex**: authenticated via `codex login` on the host, or a `CODEX_API_KEY` environment entry.
-- **Pi**: authenticated the way `pi` expects (its own `~/.pi/agent/auth.json`, or the provider's API-key environment variable such as `ANTHROPIC_API_KEY`).
-- **Kimi Code**: the `kimi` CLI installed and logged in (e.g. `kimi login`), and reachable on `PATH` (or pinned to an absolute path via `kimiBin` in the composition entry).
-- Running the harness from a source checkout needs the extra `dsh-agent-loop` `file:` shim above.
-
-## Usage
-
-**The engine is chosen per session.** Pick `Claude Code`, `Codex`, `Pi`, or `Kimi Code` on the new-session screen's preset chip (beside the workspace picker); keep the deployment's own default (usually `standard`) to run the built-in in-process loop. Different sessions can run different engines at the same time, and a child agent inherits the engine of the agent that spawned it.
-
-- **Settings → Loop engine** sets the default for **new** sessions only — it lands immediately, with no restart and no page reload, and sessions already running are unaffected. Choosing **In-process** restores whatever default the plugin replaced.
-- **Moving a session you are in** uses the composer's engine selector (enable *Show the engine selector in the chat page*), which calls the plugin's own `remote.loopEngine.select`. Any open, idle session can move — including one that has already run many turns.
-  - **Between two hosted engines the move is an in-place handover**: the session stays open, only the agent is replaced — it applies on the spot, with nothing to confirm.
-  - **A move involving `in-process` cannot be handed over in place** (the harness loop neither accepts a session it did not create nor hands a live one over), so the composer asks first: the switch reloads the page, and this page's scroll position and unsent draft go with it (the conversation record does not). On confirm the host RELEASES that session's agent and answers `reload: true`; the page reloads itself and reopens the same session, which is what makes the host build it on the recorded engine. The process never restarts.
-  - A session that is **mid-turn is refused** rather than interrupted, and a **subagent's** session cannot be moved at all.
-- **Models**: every hosted engine shares ONE `external` group in the model menu, holding exactly one entry, `default` — meaning "the engine decides". Picking a **real dsh model** hands it to the engine **with its endpoint and credential** (whether the engine can serve it is the engine's business — a refusal is reported, not swallowed). `in-process` sessions use dsh's models as usual.
-- **Uninstall**: `dsh plugin --profile web remove dsh-loop-engine`, then manually delete the plugin's managed block from the profile's `cordis.patch.yml` — the block outlives the plugin, and while it is present the base `agent-loop` row stays disabled, leaving the profile with no agent factory.
-
-### What a hosted engine takes over
-
-- Its preset is a copy of `standard` minus the dsh-native rows an external engine replaces — dsh's `/plan`, `/compact` (and auto-compaction), the model-facing goal tool, the human `/goal` command, and the dsh skill rows (one stripped preset per engine, under `$DSH_HOME/.agent-presets/loop-engine-<engine>/`).
-- The engine's own slash commands and skill catalog are registered into **that agent's own scope**, so two sessions on different engines never see each other's menus, and the whole surface is released with the agent.
-- Engine-agnostic dsh commands (`/export`, `/feedback`, `/permission`) keep working and stay.
-
-## Known limitations
-
-- **The engine record lives in the plugin's sidecar, `$DSH_HOME/.loop-engine/engines.json`, not in the session log.** Changing machine or `DSH_HOME` loses it, and the session falls back gracefully to the preset mapping. See [docs/per-session-engine.md](docs/per-session-engine.md) §5.5 and [docs/architecture.md](docs/architecture.md) §3.9.
-- **A move involving `in-process` reloads the page**, because the harness loop neither hands over a live session nor adopts one it did not create. See [docs/per-session-engine.md](docs/per-session-engine.md) §5.2/§5.4.
-- **The engine is settled at session creation / blank period**; once a turn has run, changing engines rebuilds that session's agent (idle only). See [docs/per-session-engine.md](docs/per-session-engine.md) §5.
-- **Old sessions carrying the legacy single preset id (`loop-engine`)** show as "legacy hosted engine" and need one rebuild before the new semantics take over. See [docs/per-session-engine.md](docs/per-session-engine.md) §7.
-- **Under a hosted engine a dsh model pick matters only if you pick a real dsh model** — `default` means "hand it back to the engine". See [docs/per-session-engine.md](docs/per-session-engine.md) §5.2.
-- **Same-engine sessions share that CLI's own auth directory**, with no lock added by the plugin. See [docs/per-session-engine.md](docs/per-session-engine.md) §6.
-- **Switching to `in-process` leaves the shared `external` provider group in the model menu** (the catalog is not scoped per session). See [docs/architecture.md](docs/architecture.md) §3.6.
-
-## Where the details live
-
-- [docs/per-session-engine.md](docs/per-session-engine.md) — the full user-visible behavior of per-session engines.
-- [docs/source-checkout.md](docs/source-checkout.md) — the `file:` shims a source-launched harness needs.
-- [docs/architecture.md](docs/architecture.md) — plugin core: the single factory slot, the managed block, routing, per-session engine facts, the provider route.
-- [docs/compatibility.md](docs/compatibility.md) — **start here when the harness upgrades**: every generation-dependent code site, the four techniques for spanning them, and the checklist for adding the next generation.
-- [docs/driver-core.md](docs/driver-core.md) — the shared driver infrastructure.
-- [docs/engine-claude.md](docs/engine-claude.md), [docs/engine-codex.md](docs/engine-codex.md), [docs/engine-kimi.md](docs/engine-kimi.md), [docs/engine-pi.md](docs/engine-pi.md) — per-engine internals.
-- [docs/optimization-backlog.md](docs/optimization-backlog.md) — known issues and the optimization list.
-- [docs/proposals/](docs/proposals/) — main-repo proposals: `append-ignorable-events.md`, `harness-agent-handover.md`, and the two model-selection ones (`dsh-model-into-hosted-engines.md`, `per-session-model-for-hosted-engines.md`).
-
-## License
-
-MIT
+# dsh-loop-engine
+
+[![npm version](https://img.shields.io/npm/v/dsh-loop-engine?color=cb3837)](https://www.npmjs.com/package/dsh-loop-engine)
+
+Pick the agent loop engine of **dsh web** the same way you pick a model — **per session**: the built-in `in-process` loop (the default), or one of the four hosted engines `claude-code`, `codex`, `pi`, `kimi`. The engine is the plugin's own per-session record, so **any open, idle session can be moved to another engine** — between two hosted engines it is an **in-place handover**, and a move involving `in-process` releases that session's agent and reloads the page (the `dsh web` process never restarts). Sessions are independent, so one chat can run Codex while another runs Kimi. None of this changes anything in the main repository.
+
+## Install
+
+```sh
+dsh plugin --profile web add dsh-loop-engine
+```
+
+Boot `dsh web` so the profile recomposes with the plugin, then open **Settings → Loop engine**. One boot is enough: the router retries for a bounded window while the base bundle's `agent-loop` row still holds the factory slot.
+
+> Installing rewrites one **engine-agnostic** managed block in `cordis.patch.yml`: it disables the base bundle's `agent-loop` row so the plugin's own router can own the process's single agent-factory slot, and every other byte you wrote in that file is preserved. Upgrading from an earlier release needs no hand edit — a block that named the one pinned engine is rewritten to this form on the next boot, and seeds the Settings default with that engine.
+
+> **pnpm users:** pnpm 10+ blocks dependency build scripts by default, so the install may fail with `ERR_PNPM_IGNORED_BUILDS` naming `esbuild`, `@google/genai`, and `protobufjs` (all reached through the engine SDKs). Allow them and retry — `pnpm approve-builds`, or `allowBuilds` in `pnpm-workspace.yaml`. Only the installing project can grant this; the plugin cannot pre-approve its own dependencies.
+
+### Running against a harness source checkout
+
+A **published** dsh needs no extra setup. Booting the harness from its **source checkout** (`cd deepseek-harness && pnpm dsh web`) takes one more step: bridge the profile's harness peer packages to the checkout source with `file:` shims, so both halves share one module instance (a scope minted through one instance is invisible to the other, and session resume fails with `agent-presets: refusing to compose an unscoped context`). The peer list includes `@deepseek-ai/dsh-agent-loop`. The runnable shim steps are in [docs/source-checkout.md](docs/source-checkout.md); why every `@deepseek-ai/*` package must stay a single instance is in [docs/architecture.md](docs/architecture.md). Installing the plugin as a local **`link:`** checkout sidesteps this entirely.
+
+## Version compatibility
+
+dsh-loop-engine is versioned **in lockstep with the harness it targets**: `<harness version>-rcN`. From `0.1.7-rc1` on, **one release serves two harness generations**: the 0.1.5 line (`>=0.1.5-rc.1 <0.1.6-0`, all sharing the old settings API) and the 0.1.7 line (`>=0.1.7-rc.1 <0.1.8-0`, whose `rc.1` and `rc.2` are both verified). It detects the running generation at load and takes the matching code path, so a single published package installs onto either. Every harness package it consumes declares that union range in `peerDependencies`; a harness outside it fails loudly at boot or session resume. Within a covered line a new `rc` needs no plugin release unless the API surfaces it depends on moved — `docs/compatibility.md` §1 lists the surfaces and the diff command that decides it. `0.1.5-rc3` … `0.1.5-rc5` target harness `0.1.5-rc.2`; `0.1.5-rc1`/`0.1.5-rc2` target `0.1.5-rc.1`; `1.0.0-rc8` … `1.0.0-rc15` target `0.1.2-rc.1`; `1.0.0-rc7` and earlier target `0.1.1-rc.2`.
+
+### Requirements
+
+- **Claude Code**: the Claude Code CLI installed and logged in on the host.
+- **Codex**: authenticated via `codex login` on the host, or a `CODEX_API_KEY` environment entry.
+- **Pi**: authenticated the way `pi` expects (its own `~/.pi/agent/auth.json`, or the provider's API-key environment variable such as `ANTHROPIC_API_KEY`).
+- **Kimi Code**: the `kimi` CLI installed and logged in (e.g. `kimi login`), and reachable on `PATH` (or pinned to an absolute path via `kimiBin` in the composition entry).
+- Running the harness from a source checkout needs the extra `dsh-agent-loop` `file:` shim above.
+
+## Usage
+
+**The engine is chosen per session.** Pick `Claude Code`, `Codex`, `Pi`, or `Kimi Code` on the new-session screen's preset chip (beside the workspace picker); keep the deployment's own default (usually `standard`) to run the built-in in-process loop. Different sessions can run different engines at the same time, and a child agent inherits the engine of the agent that spawned it.
+
+- **Settings → Loop engine** sets the default for **new** sessions only — it lands immediately, with no restart and no page reload, and sessions already running are unaffected. Choosing **In-process** restores whatever default the plugin replaced.
+- **Moving a session you are in** uses the composer's engine selector (enable *Show the engine selector in the chat page*), which calls the plugin's own `remote.loopEngine.select`. Any open, idle session can move — including one that has already run many turns.
+  - **Between two hosted engines the move is an in-place handover**: the session stays open, only the agent is replaced — it applies on the spot, with nothing to confirm.
+  - **A move involving `in-process` cannot be handed over in place** (the harness loop neither accepts a session it did not create nor hands a live one over), so the composer asks first: the switch reloads the page, and this page's scroll position and unsent draft go with it (the conversation record does not). On confirm the host RELEASES that session's agent and answers `reload: true`; the page reloads itself and reopens the same session, which is what makes the host build it on the recorded engine. The process never restarts.
+  - A session that is **mid-turn is refused** rather than interrupted, and a **subagent's** session cannot be moved at all.
+- **Models**: every hosted engine shares ONE `external` group in the model menu, holding exactly one entry, `default` — meaning "the engine decides". Picking a **real dsh model** hands it to the engine **with its endpoint and credential** (whether the engine can serve it is the engine's business — a refusal is reported, not swallowed). `in-process` sessions use dsh's models as usual.
+- **Uninstall**: `dsh plugin --profile web remove dsh-loop-engine`, then manually delete the plugin's managed block from the profile's `cordis.patch.yml` — the block outlives the plugin, and while it is present the base `agent-loop` row stays disabled, leaving the profile with no agent factory.
+
+### What a hosted engine takes over
+
+- Its preset is a copy of `standard` minus the dsh-native rows an external engine replaces — dsh's `/plan`, `/compact` (and auto-compaction), the model-facing goal tool, the human `/goal` command, and the dsh skill rows (one stripped preset per engine). The preset is a harness-generation-dependent artifact: a directory under `$DSH_HOME/.agent-presets/loop-engine-<engine>/` on the 0.1.5 line, and an `@deepseek-ai/dsh-agent-preset` row inserted into the profile patch on the 0.1.7 line, which no longer reads that directory. See [docs/architecture.md](docs/architecture.md) §3.5.
+- The engine's own slash commands and skill catalog are registered into **that agent's own scope**, so two sessions on different engines never see each other's menus, and the whole surface is released with the agent.
+- Engine-agnostic dsh commands (`/export`, `/feedback`, `/permission`) keep working and stay.
+
+## Known limitations
+
+- **The engine record lives in the plugin's sidecar, `$DSH_HOME/.loop-engine/engines.json`, not in the session log.** Changing machine or `DSH_HOME` loses it, and the session falls back gracefully to the preset mapping. See [docs/per-session-engine.md](docs/per-session-engine.md) §5.5 and [docs/architecture.md](docs/architecture.md) §3.9.
+- **A move involving `in-process` reloads the page**, because the harness loop neither hands over a live session nor adopts one it did not create. See [docs/per-session-engine.md](docs/per-session-engine.md) §5.2/§5.4.
+- **The engine is settled at session creation / blank period**; once a turn has run, changing engines rebuilds that session's agent (idle only). See [docs/per-session-engine.md](docs/per-session-engine.md) §5.
+- **Old sessions carrying the legacy single preset id (`loop-engine`)** show as "legacy hosted engine" and need one rebuild before the new semantics take over. See [docs/per-session-engine.md](docs/per-session-engine.md) §7.
+- **Under a hosted engine a dsh model pick matters only if you pick a real dsh model** — `default` means "hand it back to the engine". See [docs/per-session-engine.md](docs/per-session-engine.md) §5.2.
+- **Same-engine sessions share that CLI's own auth directory**, with no lock added by the plugin. See [docs/per-session-engine.md](docs/per-session-engine.md) §6.
+- **Switching to `in-process` leaves the shared `external` provider group in the model menu** (the catalog is not scoped per session). See [docs/architecture.md](docs/architecture.md) §3.6.
+
+## Where the details live
+
+- [docs/per-session-engine.md](docs/per-session-engine.md) — the full user-visible behavior of per-session engines.
+- [docs/source-checkout.md](docs/source-checkout.md) — the `file:` shims a source-launched harness needs.
+- [docs/architecture.md](docs/architecture.md) — plugin core: the single factory slot, the managed block, routing, per-session engine facts, the provider route.
+- [docs/compatibility.md](docs/compatibility.md) — **start here when the harness upgrades**: every generation-dependent code site, the four techniques for spanning them, and the checklist for adding the next generation.
+- [docs/driver-core.md](docs/driver-core.md) — the shared driver infrastructure.
+- [docs/engine-claude.md](docs/engine-claude.md), [docs/engine-codex.md](docs/engine-codex.md), [docs/engine-kimi.md](docs/engine-kimi.md), [docs/engine-pi.md](docs/engine-pi.md) — per-engine internals.
+- [docs/optimization-backlog.md](docs/optimization-backlog.md) — known issues and the optimization list.
+- [docs/proposals/](docs/proposals/) — main-repo proposals: `append-ignorable-events.md`, `harness-agent-handover.md`, and the two model-selection ones (`dsh-model-into-hosted-engines.md`, `per-session-model-for-hosted-engines.md`).
+
+## License
+
+MIT

package/README.zh.md

@@ -46,7 +46,7 @@ dsh plugin --profile web add dsh-loop-engine
 
 ### 托管引擎接管什么
 
-- 它的预设是 `standard` 的副本,去掉了外部引擎会替代掉的 dsh 原生行——dsh 的 `/plan`、`/compact`(与自动压缩)、模型可见的 goal 工具、人类 `/goal` 命令、以及 dsh skill 行(每引擎一份剥离后的 preset,位于 `$DSH_HOME/.agent-presets/loop-engine-<engine>/`)。
+- 它的预设是 `standard` 的副本,去掉了外部引擎会替代掉的 dsh 原生行——dsh 的 `/plan`、`/compact`(与自动压缩)、模型可见的 goal 工具、人类 `/goal` 命令、以及 dsh skill 行(每引擎一份剥离后的 preset)。preset 的**载体随 harness 代际而变**:0.1.5 上是 `$DSH_HOME/.agent-presets/loop-engine-<engine>/` 目录,0.1.7 上是插进 profile patch 的一行 `@deepseek-ai/dsh-agent-preset`(0.1.7 已不再读那个目录)。详见 [docs/architecture.md](docs/architecture.md) §3.5。
 - 引擎自己的斜杠命令与技能目录会注册进**这个 agent 自己的 scope**,因此两个跑不同引擎的会话互相看不到对方的菜单,整份表面随 agent 一起回收。
 - 与引擎无关的 dsh 命令(`/export`、`/feedback`、`/permission`)照常可用、保留在菜单里。
 

package/lib/index.js

@@ -5856,6 +5856,64 @@ var MANAGED_HEADER = `# Managed by dsh-loop-engine: the deployment's "${SOURCE_P
 # from "${SOURCE_PRESET_ID}" on boot \u2014 hand edits are overwritten. The preset id
 # names the engine this session runs.
 `;
+var PRESET_ROWS_BEGIN = "# -- dsh-loop-engine presets --";
+var PRESET_ROWS_END = "# -- /dsh-loop-engine presets --";
+var ENGINE_PRESET_ORDER = 100;
+var PLUGIN_LIST_INDENT = " ".repeat(10);
+function pluginListLines(composition) {
+  const text = composition.replace(/\n+$/, "");
+  const lines = text.split("\n");
+  if (!lines.some((line) => line.startsWith("- "))) return ["        plugins: []"];
+  return ["        plugins:", ...lines.map((line) => line.trim() === "" ? "" : `${PLUGIN_LIST_INDENT}${line}`)];
+}
+function renderEnginePresetRow(engine, composition) {
+  const id = enginePresetId(engine);
+  return [
+    "- insert:",
+    `    - id: preset-${id}`,
+    `      name: '@deepseek-ai/dsh-agent-preset'`,
+    "      config:",
+    `        id: ${id}`,
+    `        order: ${ENGINE_PRESET_ORDER}`,
+    ...pluginListLines(stripPresetRows(composition))
+  ].join("\n");
+}
+function renderPresetRows(composition) {
+  return [
+    PRESET_ROWS_BEGIN,
+    "# One `@deepseek-ai/dsh-agent-preset` declaration per hosted engine: the",
+    `# deployment's "${SOURCE_PRESET_ID}" preset minus the dsh-native command/skill rows a`,
+    `# hosted loop engine replaces. Regenerated from "${SOURCE_PRESET_ID}" on boot \u2014 hand`,
+    "# edits are overwritten. The preset id names the engine a session runs.",
+    ...HOSTED_ENGINE_IDS.map((engine) => renderEnginePresetRow(engine, composition)),
+    `${PRESET_ROWS_END}
+`
+  ].join("\n");
+}
+function presetRowsSpan(text) {
+  const begin = text.indexOf(PRESET_ROWS_BEGIN);
+  if (begin === -1) return { head: text, tail: "", present: false, blankBefore: false };
+  const endAt = text.indexOf(PRESET_ROWS_END, begin);
+  const spanEnd = endAt === -1 ? text.length : endAt + PRESET_ROWS_END.length + 1;
+  const before = text.slice(0, begin);
+  const blankBefore = before.endsWith("\n\n");
+  return {
+    head: blankBefore ? before.slice(0, -1) : before,
+    tail: text.slice(spanEnd),
+    present: true,
+    blankBefore
+  };
+}
+function applyEnginePresetRows(text, composition) {
+  const region = renderPresetRows(composition);
+  const span = presetRowsSpan(text);
+  if (!span.present) {
+    if (text === "") return region;
+    return dropSeedPlaceholder(`${ensureTrailingNewline(text)}
+${region}`);
+  }
+  return dropSeedPlaceholder(`${span.head}${span.blankBefore ? "\n" : ""}${region}${span.tail}`);
+}
 function managedMetadata(engine) {
   return `name: ${ENGINE_DISPLAY_NAMES[engine]}
 description: ${ENGINE_DISPLAY_NAMES[engine]}, with the dsh-native commands and skills it replaces removed.
@@ -5937,6 +5995,18 @@ ${stripPresetRows(composition)}`;
   }
   return changed;
 }
+async function readTextOrEmpty(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+async function ensureEnginePresetRows(patchPath, source) {
+  const composition = await readComposition(source, SOURCE_PRESET_ID);
+  const current = await readTextOrEmpty(patchPath);
+  return writeIfDifferent(patchPath, applyEnginePresetRows(current, composition));
+}
 
 // src/router-loop.ts
 import AgentLoop, { DEFAULT_MAX_PARALLEL_TOOL_CALLS } from "@deepseek-ai/dsh-agent-loop";
@@ -7444,6 +7514,10 @@ function resolvePatchPath(config) {
     config.patchFilename ?? "cordis.patch.yml"
   );
 }
+function authorHostedPresets(patchPath, presets) {
+  if (LEGACY_HARNESS) return ensureEnginePresets(resolveDshHome2(), presets);
+  return ensureEnginePresetRows(patchPath, presets);
+}
 function isMissing2(error) {
   return error?.code === "ENOENT";
 }
@@ -7530,6 +7604,8 @@ function apply(ctx, config) {
   const AGENT_PRESETS_NS = "agent-presets";
   const PRESET_DEFAULT_ATTEMPTS = 30;
   const PRESET_DEFAULT_RETRY_MS = 100;
+  const PRESET_SOURCE_ATTEMPTS = 20;
+  const PRESET_SOURCE_RETRY_MS = 100;
   const ROUTE_ATTEMPTS = 30;
   const ROUTE_RETRY_MS = 100;
   const ROUTER_ATTEMPTS = 40;
@@ -7605,11 +7681,24 @@ function apply(ctx, config) {
       }
       return void 0;
     }
-    const settled = authoring ??= ensureEnginePresets(resolveDshHome2(), presets).catch((error) => {
-      ctx.logger.error(`loop-engine: engine preset authoring failed: ${String(error)}`);
+    const settled = authoring ??= (async () => {
+      let lastError;
+      for (let attempt2 = 0; attempt2 <= PRESET_SOURCE_ATTEMPTS; attempt2 += 1) {
+        try {
+          return await authorHostedPresets(patchPath, presets);
+        } catch (error) {
+          lastError = error;
+          if (attempt2 < PRESET_SOURCE_ATTEMPTS) {
+            await new Promise((resolve5) => {
+              setTimeout(resolve5, PRESET_SOURCE_RETRY_MS);
+            });
+          }
+        }
+      }
+      ctx.logger.error(`loop-engine: engine preset authoring failed: ${String(lastError)}`);
       authoring = void 0;
       return false;
-    });
+    })();
     return { presets, settled };
   };
   let authoring;

package/lib/types/index.d.ts

@@ -15,16 +15,20 @@
  * Because the router owns the slot, the plugin keeps the base bundle's
  * `agent-loop` row disabled for as long as it is composed. That managed block
  * lives in the profile's `cordis.patch.yml` (see `patch-manager.ts`) and is the
- * plugin's only footprint in the harness's configuration; the block names no
- * engine, because the engine is a per-session decision.
+ * plugin's only footprint in the harness's configuration alongside the preset
+ * rows below; the block names no engine, because the engine is a per-session
+ * decision.
  *
- * The plugin authors one preset per hosted engine into the user preset root
- * (`$DSH_HOME/.agent-presets/loop-engine-<engine>`, see `preset.ts`), each a
- * copy of `standard` minus the dsh-native command and skill rows an external
- * engine replaces, and it serves every hosted engine's provider route label in
- * the llm registry (`provider-route.ts`): an engine logs its own label into
- * each session's request/header, and the web host refuses a turn whose session
- * selection names a provider no adapter serves. The preset is now only the
+ * The plugin authors one preset per hosted engine — each a copy of `standard`
+ * minus the dsh-native command and skill rows an external engine replaces — and
+ * it serves every hosted engine's provider route label in the llm registry
+ * (`provider-route.ts`): an engine logs its own label into each session's
+ * request/header, and the web host refuses a turn whose session selection names
+ * a provider no adapter serves. WHERE that copy lives depends on the harness
+ * generation — a directory under `$DSH_HOME/.agent-presets/loop-engine-<engine>`
+ * on the 0.1.5 line, a `@deepseek-ai/dsh-agent-preset` insert row in the profile
+ * patch on the 0.1.7 line, which stopped reading the directory (see
+ * `preset.ts`, {@link authorHostedPresets}). The preset is now only the
  * session's agent-plane composition (and the engine's own default for a session
  * with no record) — it is no longer the thing that decides a running session's
  * engine.

package/lib/types/patch-manager.d.ts

@@ -69,6 +69,26 @@ export declare function hasManagedBlock(text: string): boolean;
  * engine this build does not recognize.
  */
 export declare function legacyBlockEngineOf(text: string): LoopEngineId | undefined;
+/** Normalize a file so a managed span sits on its own lines with a blank separator. */
+export declare function ensureTrailingNewline(text: string): string;
+/**
+ * The profile seed template (`cordis.patch.yml` on a fresh profile) is a lone
+ * root-level empty flow sequence `[]`. The plugin's managed block is itself a
+ * root-level block sequence of loader entries, so a block coexisting with a
+ * surviving `[]` is TWO root collections in one document — YAML the harness
+ * rejects with "end of the stream or a document separator is expected", and the
+ * web app then fails to boot. Remove a whole-line root `[]` placeholder so the
+ * managed block is the sole top-level collection. Anchored to column 0 so an
+ * indented `[]` that is a real value inside an entry's nested config is never
+ * touched.
+ *
+ * Shared with the preset-rows region (`./preset.ts`): both regions are
+ * root-level collections appended to the same file, so either one can be the
+ * first thing that meets a surviving seed.
+ * @param text - the patch-file text.
+ * @returns the text without a whole-line root `[]` placeholder.
+ */
+export declare function dropSeedPlaceholder(text: string): string;
 /**
  * Produce the next patch-file text carrying the managed block, preserving every
  * byte outside the managed span. Appends the span when absent and replaces it

package/lib/types/preset.d.ts

@@ -10,9 +10,29 @@
  * advisory prompt text an external engine never assembles, dsh `/compact`
  * cannot shrink a context the engine's child process holds, and dsh skills
  * would sit next to the engine's own catalog. Those rows live inside the
- * agent-preset composition, which a profile patch cannot reach, so the plugin
- * authors a stripped preset per engine into the user preset root
- * (`$DSH_HOME/.agent-presets/<id>`).
+ * agent-preset composition, which a profile patch cannot otherwise reach, so
+ * the plugin authors a stripped copy of that composition per engine.
+ *
+ * WHICH mechanism carries that copy is the running harness generation's
+ * business, and the two share everything but the carrier:
+ *
+ *  - the 0.1.5 line reads presets from a DIRECTORY per preset under the user
+ *    preset root (`$DSH_HOME/.agent-presets/<id>`), so there it is two files
+ *    per engine ({@link ensureEnginePresets});
+ *  - the 0.1.7 line replaced that with composed plugin rows: a preset is one
+ *    `@deepseek-ai/dsh-agent-preset` row whose `config.plugins` list IS the
+ *    composition, declared wherever a composition is declared. Nothing reads
+ *    `.agent-presets` any more, so there it is four `insert` rows in the
+ *    profile patch the plugin already manages
+ *    ({@link ensureEnginePresetRows}). The rows mirror the shipped shape
+ *    (`packages/bundle/web-app/presets/standard.patch.yml` in the harness),
+ *    with this plugin's own id, order, and stripped composition.
+ *
+ * Both mechanisms regenerate from the current `standard` composition on every
+ * boot: text on disk is never authoritative, so a harness upgrade that changes
+ * `standard` flows through. Neither re-parses YAML — the strip is a line
+ * transform that preserves everything it does not drop byte for byte, comments
+ * included, and the row form only re-indents that text.
  *
  * The preset id is ALSO the per-session engine selector: the harness resolves
  * one preset per session and hands its id to the agent factory at create time
@@ -21,12 +41,6 @@
  * makes "session A on Codex, session B on Kimi, concurrently" expressible in a
  * harness that admits exactly one AgentFactory.
  *
- * The presets are REGENERATED from the current `standard` composition on every
- * boot: text on disk is never authoritative, so a harness upgrade that changes
- * `standard` flows through. The file is plain YAML the loader already accepts —
- * the strip is a line transform that preserves everything it does not drop byte
- * for byte, comments included.
- *
  * @module dsh-loop-engine/preset
  */
 export { HOSTED_PRESET_PREFIX, SOURCE_PRESET_ID, engineOfPreset, enginePresetId, hostedEngineOf, sessionEngineOf, } from './agent-preset-ids.ts';
@@ -56,6 +70,47 @@ export declare const HOSTED_PRESET_IDS: readonly string[];
  *   its context and its own `/compact` (Claude, Kimi).
  */
 export declare const STRIPPED_ROWS: readonly ["skill-filesystem", "tool-skill", "tool-goal", "command-goal", "planning", "compaction"];
+/**
+ * Begin marker of the plugin-managed preset-rows region inside a profile patch
+ * file. The region is what registers the hosted engines' presets on the 0.1.7
+ * line, where a preset is a composed row rather than a directory.
+ *
+ * Deliberately NOT the managed block's marker: the two regions are located and
+ * rewritten independently, so editing one never rewrites the other's bytes.
+ */
+export declare const PRESET_ROWS_BEGIN = "# -- dsh-loop-engine presets --";
+/** End marker of the plugin-managed preset-rows region inside a profile patch file. */
+export declare const PRESET_ROWS_END = "# -- /dsh-loop-engine presets --";
+/**
+ * Roster order of every preset this plugin authors. The shipped presets occupy
+ * 1..4 (`standard` 1, `ptc` 2, `minimal` 3, `cordis` 4), and the roster sorts
+ * by order and then by id, so one constant past that range puts every managed
+ * preset after every shipped one — the deployment's own presets stay at the top
+ * of the picker and the engines' copies trail it, which is also where the
+ * order they are listed in (selection order) is readable.
+ */
+export declare const ENGINE_PRESET_ORDER = 100;
+/**
+ * The managed preset-rows region: one preset row per hosted engine, bracketed
+ * by the markers that make it locatable and rewritable.
+ * @param composition - the source `standard` composition.
+ * @returns the region's text, ending in a newline.
+ */
+export declare function renderPresetRows(composition: string): string;
+/**
+ * Produce the next patch-file text carrying the preset-rows region, preserving
+ * every byte outside that span — including the managed block, which is located
+ * by its own markers. Appends the region when absent and replaces it when
+ * present, so an unchanged composition leaves the text byte for byte identical.
+ *
+ * The region is a root-level collection like the managed block, so a leftover
+ * seed `[]` is dropped with it: two root collections in one document is YAML
+ * the harness rejects, and the profile would stop booting.
+ * @param text - current patch-file text.
+ * @param composition - the source `standard` composition.
+ * @returns the rewritten patch-file text.
+ */
+export declare function applyEnginePresetRows(text: string, composition: string): string;
 /**
  * Remove top-level entries by id from a preset composition, preserving every
  * other byte. Each entry owns the comment/blank run directly above its opener
@@ -87,4 +142,24 @@ export interface PresetCompositionSource {
  * @throws when the source preset cannot be read or the writes fail.
  */
 export declare function ensureEnginePresets(dshHome: string, source: PresetCompositionSource): Promise<boolean>;
+/**
+ * Regenerate every hosted engine's preset as an `insert` row in the profile
+ * patch the plugin already manages, from the roster's `standard` preset.
+ *
+ * This is the 0.1.7 mechanism: a preset there is a composed plugin row, and the
+ * user preset root is not read at all — so a preset written as a directory
+ * would simply never register, leaving the roster without the id every hosted
+ * session records. The rows go in the profile's own `cordis.patch.yml` because
+ * that is the one composition layer the plugin owns: it is already the file the
+ * managed block lives in, it is applied after the bundle's own preset rows, and
+ * a rewrite of it is what the harness's live patch reload picks up.
+ *
+ * Idempotent: an up-to-date region is left byte for byte alone, so a rewrite
+ * that changes nothing does not touch the file's stamp.
+ * @param patchPath - absolute path of the profile's patch file.
+ * @param source - the roster's composition reader.
+ * @returns whether the patch file was written.
+ * @throws when the source preset cannot be read or the write fails.
+ */
+export declare function ensureEnginePresetRows(patchPath: string, source: PresetCompositionSource): Promise<boolean>;
 //# sourceMappingURL=preset.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-loop-engine",
   "description": "Web-switchable agent loop engine selection for the DeepSeek Harness - out-of-tree plugin (Claude Code / Codex / Pi / Kimi Code drivers) maintained by @kuun993, zero main-repo changes",
-  "version": "0.1.7-rc2",
+  "version": "0.1.7-rc4",
   "publishConfig": {
     "access": "public"
   },