dsh-loop-engine 0.1.5-rc2 → 0.1.5-rc4

package/lib/invariant.js

@@ -1,20 +1,27 @@
 // src/settings.ts
 import z from "@deepseek-ai/schemastery";
+
+// src/agent-preset-ids.ts
 var LOOP_ENGINE_IDS = ["in-process", "claude-code", "codex", "pi", "kimi"];
+var HOSTED_ENGINE_IDS = LOOP_ENGINE_IDS.filter(
+  (id) => id !== "in-process"
+);
+
+// src/settings.ts
 var LOOP_ENGINE_SETTINGS_SCHEMA = z.object({
   engine: z.union(LOOP_ENGINE_IDS.map((id) => z.const(id))).default("in-process"),
   showInComposer: z.boolean().default(true)
 });
 
 // src/patch-manager.ts
-var MANAGED_BLOCK_BEGIN = "# -- dsh-loop-engine managed block: ";
+var MANAGED_BLOCK_BEGIN = "# -- dsh-loop-engine managed block --";
+var LEGACY_MANAGED_BLOCK_BEGIN = "# -- dsh-loop-engine managed block: ";
 var MANAGED_BLOCK_END = "# -- /dsh-loop-engine managed block --";
 var END_MARKER_LINE = `${MANAGED_BLOCK_END}
 `;
-function renderManagedBlock(engine) {
-  if (engine === "in-process") return "";
+function renderManagedBlock() {
   return [
-    `${MANAGED_BLOCK_BEGIN}${engine} --`,
+    MANAGED_BLOCK_BEGIN,
     "- id: agent-loop",
     "  disabled: true",
     "- id: command-goal",
@@ -22,18 +29,18 @@ function renderManagedBlock(engine) {
     END_MARKER_LINE
   ].join("\n");
 }
-var BEGIN_MARKER_RE = /^# -- dsh-loop-engine managed block: (\S+) --$/m;
-function managedBlockEngineOf(text) {
-  const engine = BEGIN_MARKER_RE.exec(text)?.[1];
-  return LOOP_ENGINE_IDS.includes(engine ?? "") ? engine : void 0;
+function hasManagedBlock(text) {
+  return text.includes("# -- dsh-loop-engine managed block");
 }
-function currentEngineOf(text) {
-  return managedBlockEngineOf(text) ?? "in-process";
+var LEGACY_BEGIN_MARKER_RE = /^# -- dsh-loop-engine managed block: (\S+) --$/m;
+function legacyBlockEngineOf(text) {
+  const engine = LEGACY_BEGIN_MARKER_RE.exec(text)?.[1];
+  return LOOP_ENGINE_IDS.includes(engine ?? "") ? engine : void 0;
 }
 function managedSpan(text) {
-  const begin = text.indexOf(MANAGED_BLOCK_BEGIN);
+  const begin = text.indexOf("# -- dsh-loop-engine managed block");
   if (begin === -1) return { head: text, tail: "", present: false, blankBefore: false };
-  const afterBegin = begin + MANAGED_BLOCK_BEGIN.length;
+  const afterBegin = begin + LEGACY_MANAGED_BLOCK_BEGIN.length;
   const endAt = text.indexOf(MANAGED_BLOCK_END, afterBegin);
   const spanEnd = endAt === -1 ? text.length : endAt + END_MARKER_LINE.length;
   const before = text.slice(0, begin);
@@ -49,38 +56,18 @@ function ensureTrailingNewline(text) {
   return text.endsWith("\n") ? text : `${text}
 `;
 }
-function hasRootEntry(text) {
-  return /^(?:- |\[)/m.test(text);
-}
 function dropSeedPlaceholder(text) {
   return text.replace(/^\[\]\n/m, "");
 }
-function seedEmptyArray(text) {
-  const head = text.replace(/\n+$/, "");
-  return head === "" ? "[]\n" : `${head}
-[]
-`;
-}
-function applyManagedBlock(text, engine) {
-  const block = renderManagedBlock(engine);
+function applyManagedBlock(text) {
+  const block = renderManagedBlock();
   const span = managedSpan(text);
-  let result;
   if (!span.present) {
-    if (block === "") {
-      result = text;
-    } else {
-      const base = ensureTrailingNewline(text);
-      result = `${base}
-${block}`;
-    }
-  } else if (block === "") {
-    result = span.tail.startsWith("\n") ? `${span.head}${span.tail.slice(1)}` : `${span.head}${span.tail}`;
-  } else {
-    result = `${span.head}${span.blankBefore ? "\n" : ""}${block}${span.tail}`;
+    if (text === "") return block;
+    return dropSeedPlaceholder(`${ensureTrailingNewline(text)}
+${block}`);
   }
-  if (block !== "") return dropSeedPlaceholder(result);
-  if (text.trim() === "") return result;
-  return hasRootEntry(result) ? result : seedEmptyArray(result);
+  return dropSeedPlaceholder(`${span.head}${span.blankBefore ? "\n" : ""}${block}${span.tail}`);
 }
 
 // src/invariant.ts
@@ -91,16 +78,27 @@ var install = (ctx, fail) => {
   void ctx;
   const seed = "";
   const commentOnly = "# dsh profile patch layer\n";
+  const applied = applyManagedBlock(seed);
+  if (applyManagedBlock(applied) !== applied) fail("the managed block is not a fixed point");
+  if (!hasManagedBlock(renderManagedBlock())) fail("the rendered block is not recognized by hasManagedBlock");
+  if (!applied.includes("- id: agent-loop")) fail("the managed block must disable the base agent-loop row");
+  if (legacyBlockEngineOf(applied) !== void 0) fail("the current block must not read as a legacy engine pin");
   for (const engine of LOOP_ENGINE_IDS) {
-    const applied = applyManagedBlock(seed, engine);
-    const reborn = applyManagedBlock(applied, currentEngineOf(applied));
-    if (reborn !== applied) fail(`bare round trip for ${engine} is not a fixed point`);
-    if (engine === "in-process" && applied !== seed) fail("in-process engine must leave a bare layer unchanged");
-    if (engine !== "in-process" && currentEngineOf(renderManagedBlock(engine)) !== engine) fail(`${engine} block must read back as the ${engine} engine`);
-    if (engine === "in-process" && applyManagedBlock(commentOnly, engine) === commentOnly) {
-      fail("in-process engine must re-seed a comment-only file to a loadable top-level array");
+    const head = "# user patch layer\n";
+    const legacy = `${head}
+${LEGACY_MANAGED_BLOCK_BEGIN}${engine} --
+- id: agent-loop
+  disabled: true
+${MANAGED_BLOCK_END}
+`;
+    if (legacyBlockEngineOf(legacy) !== engine) fail(`a legacy ${engine} block must still read as the ${engine} pin`);
+    if (applyManagedBlock(legacy) !== applyManagedBlock(head)) {
+      fail(`a legacy ${engine} block must migrate to the current block`);
     }
   }
+  if (applyManagedBlock(commentOnly) === commentOnly) {
+    fail("a comment-only file must gain the block as its top-level array");
+  }
 };
 var apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
 export {

package/lib/types/agent-preset-ids.d.ts

@@ -0,0 +1,303 @@
+/**
+ * Loop engine ids, the agent-preset ids that select them, and the two plain
+ * wire shapes both halves of the plugin share — in a module with no imports at
+ * all.
+ *
+ * The mapping is pure identity arithmetic (an engine to a preset id and back),
+ * so it belongs to neither half; it lives here for the same reason
+ * `./namespace.ts` does — the browser bundle needs it, and the files that
+ * otherwise carry it are host-side: `./settings.ts` imports `schemastery` and
+ * the `dsh-settings` brand type, `./preset.ts` imports `node:fs/promises`.
+ * Importing either from `src/client/**` would pull a host package into the
+ * client artifact. Both of them re-export what this module defines, so the
+ * existing import paths and names stay valid on the node side.
+ *
+ * The two shapes are here for that same reason: {@link SessionEngine} is what
+ * the browser half renders and {@link LoopEngineSelectResult} is what its switch
+ * comes back with, so both halves name the same types without either half's
+ * modules crossing the boundary. The refusal codes travel with the second one
+ * ({@link LoopEngineRefusalCode}) for the same reason plus one more: the browser
+ * half is what turns a refusal into copy, so the codes it may read have to be
+ * knowable without importing the host's router.
+ *
+ * @module dsh-loop-engine/agent-preset-ids
+ */
+/** The installed engine driving new Agent turns. */
+export declare const LOOP_ENGINE_IDS: readonly ["in-process", "claude-code", "codex", "pi", "kimi"];
+/** Installed agent loop engine id. */
+export type LoopEngineId = (typeof LOOP_ENGINE_IDS)[number];
+/** An engine this plugin hosts itself; `in-process` is the harness's own loop. */
+export type HostedEngineId = Exclude<LoopEngineId, 'in-process'>;
+/** Every hosted engine id, in selection order. */
+export declare const HOSTED_ENGINE_IDS: HostedEngineId[];
+/**
+ * Whether an engine is one this plugin hosts — an external CLI some other
+ * vendor runs, which owns its own model — rather than the harness's own loop.
+ *
+ * The judgement a surface needs to say "the model is the engine's own business"
+ * without hardcoding one engine's name: every hosted engine behaves the same
+ * way here, and naming one of them would make a general fact read as a property
+ * of that engine. An engine nobody has answered for yet is not hosted: a surface
+ * that does not know says nothing rather than claiming the wrong half.
+ * @param engine - an engine id, or undefined while one is still being read.
+ * @returns whether that engine is hosted by this plugin.
+ */
+export declare function isHostedEngine(engine: LoopEngineId | undefined): engine is HostedEngineId;
+/**
+ * The single provider route label EVERY hosted engine logs into its sessions'
+ * `request/header`, and the one placeholder route this plugin registers in the
+ * llm registry.
+ *
+ * One label for all four engines, because the browser model catalog is built
+ * for the whole Host GENERATION and is not scoped to a session
+ * (`packages/api/session-controller/src/catalog.ts` — "Build the browser model
+ * catalog without requiring a Session"; it walks `ctx.llm.listProviders()`
+ * once). A per-engine label would therefore surface one provider group per
+ * engine in every session's menu at once — four identical `default` entries —
+ * which is what this constant collapses away.
+ *
+ * The value is ASCII on purpose: it is a WIRE value. It is written into each
+ * session's `request/header`, it travels through selections, and the host
+ * compares it (`providerInfo().id` must equal the provider the adapter
+ * registered for — `packages/llm/llm/src/index.ts` `prepareRoutes`). The
+ * display name ({@link HOSTED_ROUTE_NAME}) is the same token, for the reason
+ * that constant documents.
+ */
+export declare const HOSTED_ROUTE_LABEL = "external";
+/**
+ * The user-visible name of the one hosted route ({@link HOSTED_ROUTE_LABEL}),
+ * shown as the model menu's provider group label.
+ *
+ * The same token as the wire value, and deliberately not localized: the catalog
+ * carries exactly one string per provider group (`ModelCatalog`'s `group.name`,
+ * taken from `LlmProviderInfo.name`) and the browser half has no hook to
+ * re-translate it, so one fixed name is what every locale sees.
+ */
+export declare const HOSTED_ROUTE_NAME = "external";
+/**
+ * The one model id a hosted engine's provider route advertises to the model
+ * menu, and the model label that engine logs into its sessions'
+ * `request/header` when the deployment pins none.
+ *
+ * The two are ONE string on purpose, and that is a host-side requirement rather
+ * than a style choice: the picker builds its selection out of a catalog entry
+ * (`ModelSelect.tsx` `choices` — `model: model.id`) and resolves a session's
+ * `(provider, model)` back to that entry by comparing the pair with the logged
+ * header (`selectedIndex`), so an entry whose `id` differs from the logged
+ * label falls through to the raw `provider/model` string — how a menu ends up
+ * showing a model that does not exist. The label is the engine's own word for
+ * "whatever it decides"; `name` is the same string because `LlmModelInfo.name`
+ * is rendered verbatim and has no localization hook.
+ */
+export declare const HOSTED_DEFAULT_MODEL = "default";
+/** Prefix every plugin-authored preset id carries. */
+export declare const HOSTED_PRESET_PREFIX = "loop-engine-";
+/** The deployment's own preset id, which selects the harness loop. */
+export declare const SOURCE_PRESET_ID = "standard";
+/**
+ * The pre-routing single preset id: older versions of this plugin authored one
+ * preset for every hosted engine and pinned the profile to one of them, so a
+ * session carrying this id DID run a hosted engine — but the id does not say
+ * which one. It is not a hosted preset id ({@link engineOfPreset} reads it as
+ * `undefined`, so the router keeps such a session on the harness loop), and it
+ * is not `standard` either; surfaces that name a session's engine must report it
+ * as "a hosted engine, unrecorded" rather than claim the in-process loop.
+ */
+export declare const LEGACY_HOSTED_PRESET_ID = "loop-engine";
+/**
+ * The preset id that selects one engine for a session. `in-process` names the
+ * deployment's own `standard` preset: the harness loop is not something this
+ * plugin authors a preset for.
+ * @param engine - the engine a session should run.
+ * @returns the preset id to record on the session.
+ */
+export declare function enginePresetId(engine: LoopEngineId): string;
+/**
+ * Whether an untyped value is one of {@link LOOP_ENGINE_IDS}.
+ *
+ * The boundary test both halves need: a value crossing the wire, the sidecar
+ * file, or a projection read is only an engine when it is one of these.
+ * @param value - the value to classify.
+ * @returns whether `value` is an installed engine id.
+ */
+export declare function isLoopEngineId(value: unknown): value is LoopEngineId;
+/**
+ * The engine a preset id selects, or `undefined` for a preset this plugin does
+ * not own (any deployment-authored preset, including `standard`).
+ * @param presetId - the session's preset id, when it has one.
+ * @returns the hosted engine it names, or undefined for the harness loop.
+ */
+export declare function engineOfPreset(presetId: string | undefined): HostedEngineId | undefined;
+/**
+ * What a session's recorded preset says about the engine that session runs.
+ *
+ * Not every session has an answer: the pre-routing single preset id names a
+ * hosted engine without recording which one, and a deployment that composes no
+ * presets (or a transcript whose projection is gone) records nothing at all.
+ * Both are reported as themselves — a surface that names a session's engine must
+ * never read "unknown" as the in-process loop.
+ */
+export type SessionEngine = {
+    readonly kind: 'engine';
+    readonly engine: LoopEngineId;
+}
+/** The pre-routing preset: this session ran a hosted engine, but the id does not say which. */
+ | {
+    readonly kind: 'legacy';
+}
+/** The session records no preset at all (a deployment that composes none, or one created before presets existed). */
+ | {
+    readonly kind: 'unset';
+};
+/**
+ * What one session's engine report carries: the engine the session ACTUALLY
+ * runs, and — when they differ — the engine its own record names for it.
+ *
+ * The two are one answer because a surface must never render the second as if it
+ * were the first. A session switched onto or off the harness loop has its agent
+ * RELEASED (`src/router-loop.ts` `move`), so the session is simply cold
+ * afterwards and its record IS what its next build runs — no second fact, no
+ * pending. This field therefore survives for the one case in which a live agent
+ * still differs from the record: the release did not take (its teardown failed,
+ * or another process wrote the record), so the session keeps running its old
+ * engine while the record names another. Reporting only the live agent would
+ * hide that a switch was accepted at all — the "显示在撒谎" bug this report
+ * exists to prevent — so both travel, and {@link pending} says which is which.
+ */
+export interface SessionEngineReport {
+    /** The engine driving this session NOW. */
+    readonly engine: SessionEngine;
+    /**
+     * Present only while the session has an engine recorded that its LIVE agent is
+     * not running — i.e. a recorded switch whose release did not complete. Absent
+     * whenever the record and the live agent agree, and always absent for a session
+     * with no live agent (there the record IS what the session runs).
+     */
+    readonly pending?: LoopEngineId;
+}
+/**
+ * Every way this plugin refuses to move a session to another engine, as a stable
+ * code.
+ *
+ * A code exists because the host's own sentence is not what a surface shows any
+ * more: the browser half localizes the refusal from the code (`refusalFace` in
+ * `./client/locales.ts`) and keeps {@link LoopEngineRefusal.reason} only as
+ * detail, so the codes are part of the wire contract and a value may be added but
+ * never quietly repurposed. The list is exactly the refusals the host can produce
+ * — one per branch of `RouterLoop.selectEngine`, plus the Remote's own
+ * "no router mounted" answer:
+ *
+ *  - `session-closed`: the session has no agent in this process (nothing is open
+ *    to move);
+ *  - `turn-running`: a turn is in flight, and it is never interrupted;
+ *  - `subagent-session`: a delegated child's agent belongs to its delegation;
+ *  - `not-driven`: an agent is live but this router did not build it (the mount
+ *    window in which the base loop still owns the factory slot);
+ *  - `router-unmounted`: no router is mounted at all yet;
+ *  - `record-failed`: the plugin's own per-session record could not be written,
+ *    so the choice could not be committed;
+ *  - `rebuild-failed`: the outgoing machine was retired, the successor could not
+ *    be built, and the session was left cold on the recorded engine.
+ *
+ * A malformed REQUEST is deliberately NOT one of these: it travels as a
+ * `RemoteError` with `gateway/bad-request`, because it is the caller's fault
+ * rather than a state of the session.
+ */
+export declare const LOOP_ENGINE_REFUSAL_CODES: readonly ["session-closed", "turn-running", "subagent-session", "not-driven", "router-unmounted", "record-failed", "rebuild-failed"];
+/** Why one session's engine switch was refused. */
+export type LoopEngineRefusalCode = (typeof LOOP_ENGINE_REFUSAL_CODES)[number];
+/**
+ * Whether an untyped value is one of {@link LOOP_ENGINE_REFUSAL_CODES}.
+ *
+ * The boundary test the browser half needs: a code is only a code when this
+ * build knows it, so a value it does not recognize is normalized away and the
+ * host's `reason` stays readable instead (`./client/session-engine.ts`
+ * `parseSelectResult`).
+ * @param value - the value to classify.
+ * @returns whether `value` is a known refusal code.
+ */
+export declare function isLoopEngineRefusalCode(value: unknown): value is LoopEngineRefusalCode;
+/**
+ * What one attempt to move a session to another engine produced.
+ *
+ * A refusal is a VALUE rather than a thrown error: every reason below is a
+ * predictable state of the session (it is not open, it is mid-turn, it belongs
+ * to subagent routing) that the surface must show — localized by
+ * {@link LoopEngineRefusal.code}, with the host's own sentence kept as detail —
+ * and only a malformed REQUEST is the caller's fault (`gateway/bad-request`).
+ */
+export type LoopEngineSelectResult = {
+    readonly ok: true;
+    readonly engine: LoopEngineId;
+    /**
+     * Present when the switch was made to land by RELEASING the session's live
+     * agent rather than by moving it: a change with the harness loop on either
+     * side of it cannot be applied in place, so the agent is torn down, the
+     * session goes cold, and the record's engine is what its next build uses.
+     *
+     * The page must reload for that next build to happen: releasing publishes
+     * `session/disposed`, which the browser half reads as this session being
+     * gone — with no way back in that page's lifetime — so a reload (and a
+     * re-open of the session) is what replaces the page state with a fresh list
+     * and a fresh build. The flag is how the surface knows to do that instead of
+     * leaving the user on a session that looks broken.
+     */
+    readonly reload?: true;
+}
+/** The switch did not happen; the branch that refused it is `code`. */
+ | {
+    readonly ok: false;
+    /**
+     * Which refusal this is, for the surface to localize
+     * ({@link LoopEngineRefusalCode}). Every refusal this plugin's host produces
+     * carries one — `refuse(code, reason)` in `./router-loop.ts` takes it as a
+     * required argument, so the node half cannot forget it.
+     *
+     * Optional in the SHAPE only, because the browser half is what reads it off
+     * the wire: a code this build does not know (a newer host, or a hand-written
+     * answer) is normalized to absent so that `reason` — which is always there —
+     * is what the user reads, instead of the whole answer failing the boundary
+     * check and leaving the surface with nothing to show.
+     */
+    readonly code?: LoopEngineRefusalCode;
+    /**
+     * The host's own complete sentence about this session. It is DETAIL, not the
+     * message any more: a surface shows its own localized copy for `code` and
+     * keeps this beside it (small print) or falls back to it when `code` is
+     * absent.
+     */
+    readonly reason: string;
+};
+/**
+ * The engine one session's recorded preset says it runs, with the harness's own
+ * fallback for a preset this plugin does not own: the deployment's `standard` and
+ * anything else a deployment authored keep the session on the harness loop.
+ *
+ * The two answers that are not an engine stay distinct: {@link LEGACY_HOSTED_PRESET_ID}
+ * is a hosted engine whose name was never recorded, and a missing preset is this
+ * session recording nothing.
+ *
+ * This is the ONE preset-id → engine judgement: the router routes on what it
+ * returns and the plugin's own Remote reports it, so "what the session runs" and
+ * "what the session is shown as running" cannot disagree
+ * (`src/engine-of-session.ts` supplies the preset id from the durable log;
+ * `src/engine-remote.ts` publishes the answer to the browser half).
+ * @param presetId - the session's recorded preset id, when it has one. Reads off
+ * an untyped projection, so anything that is not a string is as good as no
+ * preset at all.
+ * @returns what that id says about the session's engine.
+ */
+export declare function sessionEngineOf(presetId: unknown): SessionEngine;
+/**
+ * The hosted engine one {@link SessionEngine} names, or `undefined` for every
+ * answer that is not this plugin's own engine preset.
+ *
+ * This is the router's half of the judgement: the harness loop still owns
+ * `in-process`, the pre-routing id and an unrecorded session both run whatever
+ * the deployment's own composition gives them (the harness loop).
+ * @param session - what a session's preset says about its engine.
+ * @returns the hosted engine to build a driver runtime for, or undefined for the
+ * harness loop.
+ */
+export declare function hostedEngineOf(session: SessionEngine): HostedEngineId | undefined;
+//# sourceMappingURL=agent-preset-ids.d.ts.map

package/lib/types/client/LoopEngineBadge.d.ts

@@ -1,34 +1,61 @@
 /**
- * Session header engine badge: a read-only chip naming the loop engine that
- * drives this session. The engine is a deployment-level choice, so the chip
- * reports the same value for every session — naming what sessions run is the
- * honest affordance; the switch itself lives in the settings section.
+ * Session header engine chip: a read-only pill naming the engine THIS session
+ * runs, read from this plugin's own Remote — which answers from the plugin's own
+ * per-session record and, for a session with none, from the session's durable
+ * log: the same read the router routes on, so the chip cannot disagree with what
+ * the session is actually driven by.
+ *
+ * It deliberately does NOT read the client session list's `agentPreset`
+ * projection: that value is a cache-shaped hint, and it names the preset the
+ * session was CREATED with, which is the wrong answer both for a session that
+ * switched while it was blank and for one that switched after it started. The
+ * harness's own preset label reads that same hint and lags the same way; this
+ * chip does not.
+ *
+ * The settings section's engine is NOT what this chip shows: that value is only
+ * the default for sessions created later, and a session created before a default
+ * change keeps running the engine it has. The two sessions that name no engine
+ * are reported as themselves rather than as the in-process loop: the pre-routing
+ * single preset id reads as "legacy hosted engine" (it ran a hosted engine, the
+ * id just never recorded which), and a session whose engine is not known — no
+ * record, no preset, or no answer from the host — renders nothing, which is also
+ * what the chip does until the host's first answer arrives.
+ *
+ * "What the session runs" is the ACTUAL engine, and for a live session that is
+ * the agent in front of it rather than the plugin's record: a switch onto the
+ * harness loop makes the host RELEASE the session's agent and reload the page,
+ * and if that release did not take, the session keeps running the engine it had
+ * while its record names another. This chip never renders the record as its name;
+ * it appends the `切到 X · 尚未接管` marker beside the engine that really runs,
+ * and its tooltip says what to do about it (`pendingSessionNotice`). See
+ * `SessionEngineReport` in `src/agent-preset-ids.ts`.
  *
  * Styling is token-driven inline styles like the settings section (the
  * client-module bundle is esbuild-built without a CSS loader).
  * @module dsh-loop-engine/client/badge
  */
 import type { JSX } from 'react';
-import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
-import type { InjectFace } from '@deepseek-ai/dsh-client-ui-slots';
-import type { LoopEngineState } from './store.ts';
-import type { en } from './locales.ts';
+import type { InjectFace, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { SessionEngineCache, SessionSeat } from './session-engine.ts';
+import { type en } from './locales.ts';
 /** Registration-side business face for the header badge. */
 export interface LoopEngineBadgeInjected {
-    hooks: {
-        /** Engine snapshot bound by the renderer as useSnapshot. */
-        snapshot: SnapshotStore<LoopEngineState>;
-    };
+    /** The plugin's authoritative per-session engine cache. */
+    sessionEngines: SessionEngineCache;
     /** Section copy bound to the engine dictionaries. */
     t: (key: keyof typeof en) => string;
 }
-/** Props delivered by the slot outlet (the renderer erases the share boundary). */
-export type LoopEngineBadgeProps = Partial<InjectFace<LoopEngineBadgeInjected>>;
 /**
- * Render the session header's loop-engine chip. Hides until the settings
- * scope settles, so the header never flashes a provisional engine.
+ * Props delivered by the slot outlet (the renderer erases the share boundary).
+ * The seat members stay partial here so the registration face matches the slot's
+ * own props; {@link BadgeFace} asserts them the way the component reads them.
+ */
+export type LoopEngineBadgeProps = PropsRuntime<'conversation.session.header.actions'> & Partial<SessionSeat> & Partial<InjectFace<LoopEngineBadgeInjected>>;
+/**
+ * Render the session header's loop-engine chip for the session on screen.
  * @param props - composed slot props.
- * @returns the chip, or null while the engine is unknown.
+ * @returns the chip, or null when the seat carries no session to speak about or
+ * the session's engine is not known yet (or not recorded at all).
  */
 export declare function LoopEngineBadge(props: LoopEngineBadgeProps): JSX.Element | null;
 //# sourceMappingURL=LoopEngineBadge.d.ts.map

package/lib/types/client/LoopEngineComposerSelect.d.ts

@@ -1,12 +1,68 @@
 /**
  * Composer loop-engine picker: a compact dropdown registered at the
  * `conversation.input.right` seat, so it sits immediately left of the model
- * select in the composer's tool row. The engine is a deployment-level choice,
- * so this surface shares the same settings-backed {@link LoopEngineStore} as
- * the settings section and the header badge — a change in any one is what the
- * others show next. Switching still asks for confirmation first (it interrupts
- * sessions still running on the previous engine) and reloads the page once the
- * commit lands, matching the settings section's semantics.
+ * select in the composer's tool row.
+ *
+ * It picks the engine of the session it is rendered in — the picker's value is
+ * this plugin's own authoritative read of that session's engine, and a pick
+ * moves the session over this plugin's own `loopEngine/select` Remote. Any
+ * session can be moved, at any point in its life, as long as it is open and no
+ * turn is in flight, and the host picks one of two ways to make the pick land:
+ *
+ *  - between two hosted engines it REBUILDS that session's agent IN PLACE, on the
+ *    session's own live Session object, so the conversation it is rendered beside
+ *    never closes;
+ *  - when the harness loop is on either side of the change, the host RELEASES
+ *    that session's agent and answers `reload: true`: the session goes cold with
+ *    its record naming the new engine, this page is reloaded (which is what
+ *    clears the client state a `session/disposed` leaves behind), and the page
+ *    that comes back opens the same session again — the host then builds it on
+ *    the engine the record names (`src/client/reload.ts`). This control says so
+ *    in a notice rather than letting the reload look like a glitch.
+ *
+ * Either way the host refuses one that is
+ * running, and a refusal leaves the session's engine untouched — the label goes
+ * back to the engine the session actually runs. The refusal is rendered from its
+ * CODE in the user's own language (`refusalFace`), with the host's own sentence
+ * kept as detail — never as the message itself, which is how a raw
+ * `session "…" is running; …` used to reach the user.
+ *
+ * A pick commits as soon as the host can apply it, with ONE exception: when the
+ * target and the engine this session ACTUALLY runs differ in being the in-process
+ * one, the host cannot hand the session over in place, so the switch releases its
+ * agent and reloads this page — and a reload costs this page's scroll position and
+ * any unsent draft in it. That one pick is staged behind a confirmation
+ * (`switchNeedsReload(报告里的实际引擎, 目标引擎)`, resolved before anything is
+ * sent) and only then committed; a pick between two hosted engines, which swaps
+ * the agent in place and reloads nothing, still commits immediately and opens no
+ * dialog at all. That judgement is only ever made about an engine somebody knows:
+ * until the host has answered what this session runs there is no engine to judge,
+ * and a session with no answer may reload in EITHER direction — so the control is
+ * DISABLED for as long as it is reading (`engineSwitchReady`), rather than
+ * guessing a direction. This control deliberately asks NOTHING else: whether the session
+ * can be moved right now is the host's own judgement — it refuses one that is not
+ * open, one that is mid-turn, and a subagent's own session, each with a code and a
+ * sentence — so a pick that cannot land costs nothing, and the control never
+ * reads an idle hint off a cached session list.
+ *
+ * So it opens two dialogs, with different jobs: the CONFIRMATION (two buttons,
+ * cancel and switch) that a reloading pick must pass before it is sent, and the
+ * NOTICE (one button, close) that reports what the host answered — the refusal's
+ * localized copy with the host's sentence as detail, or this plugin's own
+ * sentence for a reloaded pick.
+ *
+ * WITH a session, the settings default is never shown — not even while the first
+ * answer is still in flight: a session on the pre-routing single preset id reads
+ * "legacy hosted engine", one whose engine is not recorded (or not readable)
+ * reads "not recorded", and a session whose engine has not been answered yet
+ * reads "reading" AND is disabled while it does (see above) — a default or a stale
+ * hint would be a claim about a session this control has no facts for, and a pick
+ * would have to be judged against an engine nobody knows. Without a session (the
+ * seat renders only with one, so this is the defensive branch) the trigger names
+ * the default and a pick writes it — immediately, like every other pick here, and
+ * with the control usable from the start: a new-session page is waiting for
+ * nothing, and that pick reloads nothing. The settings section's own picker is the
+ * one that still stages its choice behind a confirmation.
  *
  * Styling is token-driven inline styles like the badge and section (the
  * client-module bundle is esbuild-built without a CSS loader).
@@ -14,9 +70,10 @@
  */
 import { type JSX } from 'react';
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
-import type { InjectFace } from '@deepseek-ai/dsh-client-ui-slots';
+import type { InjectFace, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
 import type { LoopEngineStore, LoopEngineState } from './store.ts';
-import type { en } from './locales.ts';
+import { type SessionEngineCache, type SessionEngineSwitcher, type SessionSeat } from './session-engine.ts';
+import { type en } from './locales.ts';
 /** Injected dependencies of {@link LoopEngineComposerSelect} (slot `inject`). */
 export interface LoopEngineComposerSelectInjected {
     /** The selection store (loaded on mount, refreshed by scope pushes). */
@@ -25,16 +82,25 @@ export interface LoopEngineComposerSelectInjected {
         /** Engine snapshot bound by the UI renderer as useSnapshot. */
         snapshot: SnapshotStore<LoopEngineState>;
     };
+    /** The plugin's authoritative per-session engine cache. */
+    sessionEngines: SessionEngineCache;
+    /** Move one session to another engine. */
+    switchEngine: SessionEngineSwitcher;
     /** Composer copy bound to the loop engine dictionaries. */
     t: (key: keyof typeof en) => string;
 }
-/** Props delivered by the slot outlet (the renderer erases the share boundary). */
-export type LoopEngineComposerSelectProps = Partial<InjectFace<LoopEngineComposerSelectInjected>>;
 /**
- * Render the composer's loop-engine dropdown. Hides until the settings scope
- * settles, so the composer never flashes a provisional engine.
+ * Props delivered by the slot outlet (the renderer erases the share boundary).
+ * The seat members stay partial here so the registration face matches the slot's
+ * own props; {@link ComposerFace} asserts them the way the component reads them.
+ */
+export type LoopEngineComposerSelectProps = PropsRuntime<'conversation.input.right'> & Partial<SessionSeat> & Partial<InjectFace<LoopEngineComposerSelectInjected>>;
+/**
+ * Render the composer's loop-engine dropdown for the session on screen. Hides
+ * until the settings scope settles, so the picker never flashes a provisional
+ * default while a session's own engine is already known.
  * @param props - composed slot props.
- * @returns the picker, or null while the engine is unknown.
+ * @returns the picker, or null while the picker is unavailable or switched off.
  */
 export declare function LoopEngineComposerSelect(props: LoopEngineComposerSelectProps): JSX.Element | null;
 //# sourceMappingURL=LoopEngineComposerSelect.d.ts.map

package/lib/types/client/LoopEngineSection.d.ts

@@ -1,8 +1,9 @@
 /**
- * Loop engine settings section component: one dropdown choosing the agent
- * loop engine, backed by the duplicated settings scope through the inject face.
- * Changing the engine asks for confirmation first, because the switch
- * interrupts sessions still running on the previous engine.
+ * Loop engine settings section component: one dropdown choosing the DEFAULT
+ * agent loop engine for new sessions, backed by the duplicated settings scope
+ * through the inject face. The commit is confirmed first because it changes
+ * what every future session runs; sessions that already exist keep the engine
+ * they run, so nothing is interrupted and nothing reloads.
  *
  * Styling is token-driven like the rest of the settings shell (`--dsw-*`
  * aliases), with the picker rendered through the shared `Menu` primitive and