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

package/lib/types/router-loop.d.ts

@@ -0,0 +1,458 @@
+/**
+ * The process-wide agent factory, dispatching each session to the engine it
+ * runs.
+ *
+ * The harness admits exactly ONE `AgentFactory` per process
+ * (`AgentRegistry.setFactory` throws on a second registration) and exposes no
+ * per-session way to resolve one, so "session A on Codex while session B runs
+ * Kimi" is only expressible if the single factory itself routes. This class is
+ * that router: it extends the harness's own `AgentLoop`, inheriting the
+ * in-process loop in full (turn boundary projection, prompt variables, the
+ * agent-loop settings section, the factory registration), and overrides the two
+ * AgentFactory entry points to hand a session to its engine's runtime.
+ *
+ * Which engine that is comes from {@link engineOfSession} — the plugin's own
+ * per-session record first, the recorded agent preset otherwise — with one
+ * create-time exception spelled out on {@link RouterLoop.engineFor}:
+ *   - create: the record, else `CreateAgentOptions.meta.agentPreset` (already
+ *     resolved by the caller, `packages/api/session-controller/src/agent.ts`
+ *     `composeAgent`), with a live parent's engine as the fallback for a child;
+ *   - resume: the record, else the persisted `agentPreset` projection.
+ *     `ResumeAgentOptions` carries no metadata, so that projection is read
+ *     through {@link engineOfSession} — the same fold the host itself reads
+ *     before choosing the composition to mount, and the same one the plugin's
+ *     own Remote reports to the browser half.
+ *
+ * The session can also be moved while it is LIVE — that is what
+ * {@link RouterLoop.selectEngine} is for, and it is the half of the story the
+ * preset channel cannot express (the harness refuses a preset change on a
+ * started session, `agent-preset/locked`). Between two hosted engines the move
+ * is an IN-PLACE SWAP: the successor is built onto the session's own `Session`
+ * object and the outgoing machine is retired around it, so the session — and
+ * the page attached to it — never witnesses a lifecycle edge
+ * ({@link RouterLoop.hotSwap}). A move that involves the harness loop on either
+ * side cannot be done in place at all, so it is made to land the other way:
+ * the session's agent is RELEASED, which leaves the session cold with its
+ * record already naming the new engine, and the outcome asks the browser half
+ * to reload the page ({@link RouterLoop.move}) — the reload is what reopens the
+ * session, and the host's next resolve then builds it on the record's engine.
+ *
+ * `in-process` sessions are served by `super`; every hosted engine gets one
+ * {@link HostedEngineRuntime} built on first use, which is also what makes the
+ * engines concurrent: their agents, subprocesses, and scopes are all
+ * per-session, and each runtime owns only its own live agents.
+ *
+ * The router also answers what a session is running
+ * ({@link RouterLoop.reportEngine}) from the same bookkeeping that routes it,
+ * because it is the only thing that knows which engine built a live agent — see
+ * {@link SessionEngineReport} for why "what runs now" and "what the record says"
+ * are two facts that must travel separately.
+ *
+ * @module dsh-loop-engine-allinone/router-loop
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import AgentLoop from '@deepseek-ai/dsh-agent-loop';
+import type { AgentHandle, CreateAgentOptions, ResumeAgentOptions } from '@deepseek-ai/dsh-agent';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { LoopEngineSelectResult, SessionEngineReport } from './agent-preset-ids.ts';
+import type { HostedAgent, HostedEngineRuntime } from './driver-core/hosted-engine-runtime.ts';
+import type { EngineRecordStore } from './session-engine-store.ts';
+import type { HostedEngineId, LoopEngineId } from './settings.ts';
+/**
+ * The preset roster announces a committed per-session preset change on the
+ * shared event bus so consumers can invalidate state derived from that
+ * session's composition. Declared here rather than imported from
+ * `@deepseek-ai/dsh-agent-presets`: the plugin consumes the notification but
+ * takes no build-time dependency on the roster, which a minimal profile may not
+ * compose at all.
+ */
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        /**
+         * One session committed a different agent preset to its durable log.
+         * @mode emit
+         * @param sessionId - the session whose composition changed.
+         * @param agentPreset - the preset recorded by the committed selection.
+         */
+        'agent-preset/selected'(sessionId: SessionId, agentPreset: string): void;
+    }
+}
+/**
+ * Services the router's context must inject.
+ *
+ * Taken from the harness loop verbatim rather than re-listed: the router IS the
+ * harness loop for `in-process` sessions, and cordis refuses a service
+ * PROPERTY READ on a context whose fiber did not inject it
+ * (`cannot get property "tools" without inject`). The loop's turn machinery
+ * reads `ctx.tools` and `ctx.llm` directly, so a shorter gate here compiles and
+ * even creates agents, then dies on the first real turn.
+ */
+export declare const ROUTER_SERVICES: readonly string[];
+/**
+ * Any hosted engine's runtime, as this router holds it. The engines differ only
+ * in configuration and driver; the transaction surface the router calls is
+ * identical, so the map is type-erased once here.
+ */
+export type RouterEngine = HostedEngineRuntime<object, HostedAgent>;
+/** Builds (or returns the memoized) driver runtime of one hosted engine. */
+export type EngineBuilder = (engine: HostedEngineId) => RouterEngine;
+/**
+ * The single AgentFactory, routing per session.
+ *
+ * Constructed by the plugin once the services the harness loop needs are
+ * active; its effects belong to the constructing fiber, so unloading the plugin
+ * tears every engine down.
+ */
+export declare class RouterLoop extends AgentLoop {
+    private readonly engines;
+    private readonly live;
+    private readonly build;
+    private readonly records;
+    private readonly warn;
+    /**
+     * Diagnostics already reported: a condition that repeats on every build (a
+     * session whose engine cannot be read, a projection that will not fold) is
+     * worth naming once, not once per rebuild.
+     */
+    private readonly warned;
+    /**
+     * The model-selection half of routing: the seat a session's engine owns, moved
+     * at a switch ({@link RouterLoop.moveModelSelection}) and written at a build
+     * ({@link RouterLoop.engineOptions}). Owned here because each warning it owes
+     * is owed once per process, not once per session.
+     */
+    private readonly selectionReset;
+    /**
+     * @param ctx - the context the router's effects belong to.
+     * @param build - memoized builder for one hosted engine's runtime.
+     * @param records - the plugin's own per-session engine record, which outranks
+     *   every preset-derived answer and is what {@link selectEngine} writes.
+     * @param warn - diagnostic sink for a skipped engine command.
+     */
+    constructor(ctx: Context, build: EngineBuilder, records: EngineRecordStore, warn: (message: string) => void);
+    /** The engine that drives one session's agent. */
+    private engineFor;
+    /**
+     * The engine to build one session on for a CREATE, with the plugin's own
+     * record read ahead of the caller's preset.
+     *
+     * Reading an engine is a read of the HOST's session state, and a session this
+     * plugin does not own is the host's business: a failure here (a session-query
+     * lease that refuses, a projection that cannot be computed, a corrupt log)
+     * must never become the reason that session cannot be created. Every failure
+     * degrades to the harness loop, which is what would have served the session if
+     * this plugin were not installed at all.
+     * @param sessionId - the session being created.
+     * @param presetId - the preset the caller composed with, when it named one.
+     * @param parent - the live parent agent, for a child session's inheritance.
+     * @returns the engine, or the harness loop when the answer could not be read.
+     */
+    private engineForCreate;
+    /**
+     * The engine to build a PERSISTED session on, degrading exactly as
+     * {@link engineForCreate} does.
+     *
+     * The read is the same plugin record first, then the durable `agentPreset`
+     * projection — and a resumed session is the case where those reads touch the
+     * host the most (a cold open, a repair, a projection fold), so it is the case
+     * where a read failure is most likely and least acceptable to surface as
+     * "this session will not open".
+     * @param sessionId - the persisted session being resumed.
+     * @param parent - the live parent agent, for a child session's inheritance.
+     * @returns the engine, or the harness loop when the answer could not be read.
+     */
+    private engineForResume;
+    /**
+     * Report one unreadable engine answer and hand the session to the harness
+     * loop. Owed once per session, not once per build: a session that fails to
+     * read keeps failing on every rebuild, and the point of the warning is to name
+     * the session, not to count the retries.
+     * @param sessionId - the session the plugin could not answer for.
+     * @param error - the failure the read produced.
+     * @returns the engine the session is degraded to.
+     */
+    private degradeToHarnessLoop;
+    /**
+     * Report one diagnostic once per process, for a condition that repeats on
+     * every build of the session it names.
+     * @param message - the diagnostic to report at most once.
+     */
+    private warnOnce;
+    /** The engine's runtime, built on first use and kept for the plugin's lifetime. */
+    private runtimeOf;
+    /**
+     * Record one published agent so a later engine change can rebuild it, and
+     * bridge the engine's command/skill surface into its session.
+     * @param engine - the engine that built the handle.
+     * @param handle - the published handle.
+     * @param recipe - how it was built, for a hot swap's successor.
+     * @param handover - a hosted handle's session handover; absent for the
+     *   harness loop, whose handle carries neither the session's lifetime nor a
+     *   way to retire the machine without releasing it.
+     * @returns the handle the harness tracks.
+     */
+    private adopt;
+    /** Drop one tracked session, if the record still points at that exact agent. */
+    private forget;
+    /**
+     * Create a session's agent on the engine it runs.
+     *
+     * The plugin's own record is consulted FIRST, ahead of the preset the caller
+     * composed with: a session that already has a record must be built on the
+     * engine the plugin reports for it, or the router and the Remote would answer
+     * differently about one session. Only a session with no record — every session
+     * this plugin has never switched, including every brand-new one — falls
+     * through to the preset.
+     * @param ownerCtx - caller context that owns the lifecycle.
+     * @param options - identities, metadata (carrying the preset), and setup.
+     * @returns the published handle.
+     */
+    createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>;
+    /**
+     * Resume a persisted session on the engine it runs.
+     *
+     * The read is {@link engineOfSession}: the plugin's own record first, then the
+     * durable `agentPreset` projection, which folds the session header together
+     * with every committed `agent-preset/selected`. The session header alone would
+     * name the preset the session was CREATED with, which is exactly the wrong
+     * answer for a session that switched engine while it was blank — and the
+     * record is the only answer for one that switched after it started, which no
+     * preset can express.
+     *
+     * A resume is not a create: the session's seat is one a previous build already
+     * put in its log (`model-selection-reset.ts`, the switch and build triggers), so
+     * a hosted engine's resume leaves the selection exactly as it finds it. Only
+     * the harness loop's own resume is wrapped, with the narrower trigger that
+     * applies to it — it makes real model calls, so it must not be left selecting a
+     * placeholder route.
+     * @param ownerCtx - caller context that owns load, setup, and the lifecycle.
+     * @param options - persisted identity, loop options, and setup.
+     * @returns the published handle.
+     */
+    resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>;
+    /**
+     * Wrap the caller's setup so the session's ENGINE gets its model seat written
+     * before the host installs the session's selection, and hand a hosted engine
+     * the `agentOptions` that seat names.
+     *
+     * The wrap is what makes the write land at all: the host installs the session's
+     * model selection from INSIDE the caller's own setup
+     * (`ApiSessionAgentController.selectionFor`), and that read takes the log's
+     * pending `model/selection` — so the write has to happen before it, and the
+     * caller's setup has to run unchanged afterwards. Both of the router's engines
+     * are wrapped, each with its own trigger: the harness loop's build keeps the
+     * narrow one (only a session that would otherwise select a placeholder route),
+     * while a hosted engine's build is where a NEW session gets its seat. The
+     * resume path calls this with `in-process` alone (see {@link resume}).
+     *
+     * The `agentOptions` half keeps the two answers consistent: a hosted engine is
+     * handed the very selection written into the session (`external/default`), not
+     * the deployment default that seat replaced. In-process keeps the caller's own
+     * options, which ARE its route.
+     *
+     * The caller's setup is copied, never mutated: the same options object is the
+     * router's rebuild recipe, which replays the caller's own closure.
+     * @param options - the create or resume options the caller supplied.
+     * @param engine - the engine building this session.
+     * @returns a copy whose setup writes the seat first, then the caller's own.
+     */
+    private engineOptions;
+    /**
+     * Report what one session ACTUALLY runs, and — when they differ — the engine
+     * its record names.
+     *
+     * This is the read the plugin's own Remote publishes, and the reason it is the
+     * router's to make is the live bookkeeping below: for a session with an agent
+     * this router built, {@link RouterLoop.live} says which engine built it, and
+     * that beats every record — it is what is running. A session this router does
+     * not drive (cold, or still on the base loop's slot during the mount window)
+     * has no live fact to report, so the record answers, exactly as it does for a
+     * session about to be built; and since every switch this plugin performs
+     * either swaps the agent in place or releases it, the two facts differ only
+     * for a release that did not take.
+     * @param sessionId - the session to report on.
+     * @returns the engine driving it now, plus the engine its record names for its
+     * next build when the two differ.
+     */
+    reportEngine(sessionId: SessionId): Promise<SessionEngineReport>;
+    /**
+     * Move one live session to another engine.
+     *
+     * The one entry point that makes "switch this session's engine" possible after
+     * a session has started, which the harness's own preset channel refuses
+     * (`agent-preset/locked`, `packages/preset/agent-presets/src/index.ts`). The
+     * order below is load-bearing:
+     *
+     *  1. the checks, so a session that cannot be moved is refused with a reason
+     *     instead of half-moved;
+     *  2. the record, because it is the answer the router, the Remote, and the
+     *     host's next resolve all read — and a record that could not be written
+     *     must leave the session where it is;
+     *  3. the session's model seat, which moves with the choice
+     *     ({@link moveModelSelection}) — before the move below, because the move is
+     *     what detaches (or re-installs) the agent that reads it;
+     *  4. the move itself: an in-place swap between two hosted engines, or — when
+     *     the harness loop is on either side — a release of the session's agent
+     *     plus a request that the page reload (`reload: true`), which is what
+     *     makes the host build the session again on the recorded engine.
+     *
+     * A session already on the requested engine is recorded and left running: the
+     * record is the user's explicit choice, while tearing an untouched agent down
+     * would cost the session's rebuild for no change at all. "Already on" is
+     * judged on the LIVE AGENT's engine, not on the record: the two can differ
+     * while a released agent is still in flight, and then re-selecting the engine
+     * the session is actually running is how a user takes that record back — the
+     * record follows the agent back, and nothing is torn down.
+     * @param sessionId - the session to move.
+     * @param engine - the engine it should run.
+     * @returns the engine now recorded for it, whether the page must reload for it
+     *   to be built, or — as `ok: false` — the {@link LoopEngineRefusalCode} of the
+     *   branch that refused it plus its own sentence about this session. Every
+     *   refusal this method produces carries a code; the browser half localizes
+     *   from it and keeps the sentence as detail.
+     */
+    selectEngine(sessionId: SessionId, engine: LoopEngineId): Promise<LoopEngineSelectResult>;
+    /**
+     * Make a just-recorded engine change take effect on the live session.
+     *
+     * Between two hosted engines the change is an IN-PLACE SWAP
+     * ({@link hotSwap}): the session's `Session` object is kept, its agent is
+     * replaced, and the browser half attached to that session sees no lifecycle
+     * edge at all.
+     *
+     * A change with the harness loop on EITHER side cannot be done in place, and
+     * this is a limit of the harness rather than a choice: `AgentLoop` neither
+     * hands a live session over nor accepts one it did not create. Its factory
+     * holds the session's store entry and write handle in private closure state
+     * (`agent-loop/src/index.ts` `prepare`), its publication enters the session
+     * (`sessions.enter`, which refuses an id already in the store), and its own
+     * agent class is not exported. So the session's agent is RELEASED instead
+     * ({@link release}) and the change lands on the session's next build, which
+     * the returned `reload: true` puts in the user's hands: the session goes cold
+     * with the record already naming its engine, and the page — reloaded, and
+     * reopening that session — is what makes the host resolve it again, on the
+     * engine the record names.
+     *
+     * The page really does have to reload, and that is the one cost of this path:
+     * a release emits `session/disposed`, and the browser half reads that as this
+     * session being gone, with no way back in that page's lifetime
+     * (`session.ts` `handleRemoved` sets a `removed` flag nothing ever clears), so
+     * a page that stayed put would show a session that can no longer be typed
+     * into. The alternative — leaving the live agent alone and letting the record
+     * wait for a process restart — is what this plugin used to do, and it cost the
+     * user a restart for a switch the host can perform itself.
+     * @param entry - the live session's record; the caller verified it is movable.
+     * @param engine - the engine just recorded for it.
+     * @returns the switch outcome, asking for the page reload that builds the
+     *   session again when its agent had to be released.
+     */
+    private move;
+    /**
+     * Replace one live session's agent with a machine the incoming engine builds
+     * onto the SAME `Session`.
+     *
+     * The order is load-bearing. The outgoing machine is retired FIRST and
+     * completely: only one agent may be registered per session id (`agents.enter`
+     * refuses a duplicate), and two machines folded over one session's inbox would
+     * splice each other's queued messages, so the outgoing machine must be settled
+     * before any input can reach the successor. The SESSION is never released:
+     * its store entry and write handle travel in the lifetime the outgoing machine
+     * hands over, which is exactly why the page attached to this session stays
+     * usable across the swap.
+     *
+     * A failure after the handover cannot be undone — the outgoing machine is
+     * gone and the successor never published. The lifetime is then released, so
+     * the session goes cold and reopens on the recorded engine the way any session
+     * the host has not loaded does, and the refusal says what happened.
+     * @param entry - the live session's record; the caller verified it is movable.
+     * @param handover - the outgoing machine's session handover.
+     * @param engine - the hosted engine to build the successor on.
+     * @returns the switch outcome.
+     */
+    private hotSwap;
+    /** Read the host session-projection registry, structurally. */
+    private projections;
+    /**
+     * Drop one tracked session's agent so the host's next resolve rebuilds it.
+     *
+     * Two callers, and they both want the engine change to land at the session's
+     * next build rather than in place:
+     *
+     *  - {@link move}, the engine picker's path involving the harness loop, which
+     *    WAITS for the teardown (the outcome it is about to return says the
+     *    session is cold, and that must be true when it says so);
+     *  - the harness's own preset switch on a blank session, which fire-and-forgets
+     *    it because it runs inside a synchronous event handler. It is the one
+     *    engine change this plugin still makes by releasing the session rather
+     *    than by moving it: the successor's composition is the NEW preset's, which
+     *    only the API layer composes (a preset the harness mounted itself reaches
+     *    the plugin as an id, not as a composition callback), so the plugin cannot
+     *    build a correctly-composed successor in place.
+     *
+     * The record is forgotten before the teardown runs, so a teardown-driven event
+     * can never find the entry it is releasing and start a second teardown of the
+     * same agent; a failure is reported rather than thrown, and the returned
+     * promise settles either way.
+     * @param entry - the live session record to release.
+     * @returns the teardown, once it settled.
+     */
+    private release;
+    /**
+     * Follow the harness's own preset switch, for a BLANK session.
+     *
+     * The harness's preset switch on a blank session re-parents the live agent's
+     * scope and records the choice; it does not rebuild the agent, so the engine
+     * would keep running the one the session was created with. Dropping the agent
+     * instead lets the host's own next resolve fall back to a resume
+     * (`ApiSessionAgentController.resolve`), which composes from the recorded
+     * preset and lands on the new engine — the same path a reopened session
+     * takes, with the durable log as the only carry-over.
+     *
+     * LAST USER ACTION WINS: for a session this plugin already holds a record
+     * for, the harness's picker is an engine choice too, so the record follows it
+     * before the agent is released. Without that, the two entry points would
+     * contradict each other — the picker would rebuild the session on the preset's
+     * engine, while the very next resume would read the plugin's record and move
+     * it back. A session with NO record keeps reading its engine off the preset,
+     * exactly as before, and gets none: only an explicit choice is recorded.
+     *
+     * A session that has already run a turn is left alone — its live engine and
+     * its record both stay where they are, so the router and the Remote keep
+     * agreeing about it. (A started session cannot reach here through the
+     * harness's picker anyway: the roster refuses with `agent-preset/locked`.)
+     *
+     * The session's model seat moves with the choice, before the release
+     * ({@link moveModelSelection}) — the picker is an engine change like the
+     * picker's own switcher, and this is the one place the harness can make it.
+     */
+    private rebuildOnEngineChange;
+    /**
+     * Hand one session's model seat to the engine it is being switched to.
+     *
+     * A session's selection follows its engine: a hosted engine owns its model
+     * natively and the shared provider label it logs is served only by this
+     * plugin's placeholder route (which fails loud, `HOSTED_ENGINE_ROUTE`, when a
+     * real model call reaches it), while the harness loop DOES make real calls and therefore needs
+     * a real model selected. So a switch moves the seat — the shared
+     * `external/default` for a hosted engine, the deployment default for the
+     * harness loop. A selection that
+     * names a real model of its own is never touched: the model notice the browser
+     * half shows beside a hosted engine says that selection is inert there, not
+     * that it is gone. The write itself, its judgements, and why an engine change
+     * with no logged selection writes nothing are in `model-selection-reset.ts`;
+     * this method is only the router's half.
+     *
+     * The selection is written at the moment of the switch, not at the moment the
+     * engine changes. Between two hosted engines the move is an in-place swap whose
+     * `setup` installs the selection onto the successor, and for anything involving
+     * the harness loop the switch releases the session's agent and the page reloads
+     * ({@link move}) — either way the write has to be in the log before the move
+     * runs, which is what this ordering buys.
+     * @param entry - the live session being switched.
+     * @param engine - the engine it is being switched to.
+     * @returns nothing; a selection this process cannot name is skipped with one
+     *   warning, and the session keeps what its log records.
+     */
+    private moveModelSelection;
+}
+//# sourceMappingURL=router-loop.d.ts.map

package/lib/types/session-engine-store.d.ts

@@ -0,0 +1,138 @@
+/**
+ * The plugin's own per-session engine record: one sidecar file beside the
+ * harness home, deliberately NOT an event in the session log.
+ *
+ * The engine a session runs is a per-session host-plane fact, and the session
+ * log is where this project records such facts — so the obvious home for it is
+ * a plugin-authored session event. It cannot be done:
+ *
+ *  - `Session.append` builds the event envelope itself and offers no way to set
+ *    the envelope's `ignorable?: true` marker (the only options it takes are
+ *    surface metadata);
+ *  - the persistence read path refuses a stored event whose type is outside the
+ *    harness's generated `KNOWN_SESSION_EVENT_TYPES` unless the envelope carries
+ *    that marker;
+ *  - so the append succeeds in memory, the write succeeds on disk, and the NEXT
+ *    cold read of that session refuses the whole log:
+ *    `SessionFormatUnsupportedError: … contains event type "…" unknown to this
+ *    harness and not marked ignorable; refusing to interpret the log`.
+ *
+ * That is a destroyed session per engine switch, so this plugin keeps the fact
+ * out of the log instead. `docs/proposals/append-ignorable-events.md` asks the
+ * harness for the missing seam; if it lands, this record can move into the log
+ * with the file kept as the fallback for sessions recorded before the change.
+ *
+ * Storage semantics (all of them deliberate):
+ *
+ *  - one small JSON document, `{ version, engines: { <sessionId>: <engine> } }`,
+ *    written whole through a same-directory temp file + rename, so a crash
+ *    mid-write can never leave a truncated record behind;
+ *  - the in-memory view advances only after the write committed, so a failed
+ *    write leaves both the file and the view exactly as they were;
+ *  - a missing file is the normal first-run state (no diagnostic); an
+ *    unreadable or unrecognizable file degrades to "no record" with ONE warn
+ *    (the document is read at most once per process, so no lookup repeats a
+ *    failure), because a broken record must cost a session its remembered
+ *    engine, never its ability to open: the routing read falls back to the
+ *    preset mapping;
+ *  - entries are added, never removed: one line per session ever switched, which
+ *    a deployment cannot notice, and a stale entry for a deleted session is
+ *    simply never asked about.
+ *
+ * @module dsh-loop-engine-allinone/session-engine-store
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import { type LoopEngineId } from './agent-preset-ids.ts';
+/** Harness-home-relative directory holding the plugin's own records. */
+export declare const ENGINE_RECORD_DIR = ".loop-engine";
+/** File name of the per-session engine record document. */
+export declare const ENGINE_RECORD_FILE = "engines.json";
+/** Format version of the record document; a mismatch is treated as no record. */
+export declare const ENGINE_RECORD_VERSION = 1;
+/**
+ * The record file's path under the harness home (`$DSH_HOME/.loop-engine/engines.json`).
+ * @returns the absolute path of the engine record document.
+ */
+export declare function resolveEngineRecordPath(): string;
+/**
+ * Read one session's engine off the plugin's own record.
+ *
+ * The narrow face the routing read depends on, so a test can hand the router an
+ * exact set of records instead of a file.
+ */
+export interface EngineRecordSource {
+    /**
+     * The engine this plugin's record names for one session.
+     * @param sessionId - the session to look up.
+     * @returns the recorded engine, or undefined when this session has no record.
+     */
+    engineOf(sessionId: SessionId): LoopEngineId | undefined;
+}
+/**
+ * The record as the ROUTER uses it: the read every routing decision makes, plus
+ * the write an engine switch commits.
+ */
+export interface EngineRecordStore extends EngineRecordSource {
+    /**
+     * Record one session's engine, replacing any earlier record for it.
+     * @param sessionId - the session whose engine is recorded.
+     * @param engine - the engine that session now runs.
+     */
+    record(sessionId: SessionId, engine: LoopEngineId): void;
+}
+/**
+ * Replace one file atomically: same-directory temp file, then rename over the
+ * target, so a reader never sees a partial document. The temp name is unique
+ * per write, so two writers cannot collide on it.
+ * @param path - the file to replace (its directory is created as needed).
+ * @param text - the next file content.
+ */
+export declare function writeFileAtomicSync(path: string, text: string): void;
+/**
+ * The plugin's per-session engine record, held in memory and mirrored to one
+ * atomically written JSON file.
+ *
+ * The file is read once, lazily, on the first lookup; every later lookup is a
+ * map read, so routing never pays for filesystem I/O.
+ */
+export declare class SessionEngineStore implements EngineRecordSource {
+    private readonly path;
+    private readonly warn;
+    private entries;
+    /**
+     * @param path - the record document's absolute path.
+     * @param warn - diagnostic sink for a record this build cannot read.
+     */
+    constructor(path: string, warn: (message: string) => void);
+    /**
+     * The engine this plugin's record names for one session.
+     * @param sessionId - the session to look up.
+     * @returns the recorded engine, or undefined when there is no usable record.
+     */
+    engineOf(sessionId: SessionId): LoopEngineId | undefined;
+    /**
+     * Record one session's engine, replacing any earlier record for it.
+     *
+     * The write commits before the in-memory view moves, so a caller that sees a
+     * rejection knows the store still answers what it answered before.
+     * @param sessionId - the session whose engine is recorded.
+     * @param engine - the engine that session now runs.
+     * @throws when the document could not be written; the previous file is intact.
+     */
+    record(sessionId: SessionId, engine: LoopEngineId): void;
+    /** The in-memory record, read from disk on first use. */
+    private load;
+    /** Read the document once, degrading to an empty record. */
+    private read;
+    /**
+     * Report one unusable record and answer "no record".
+     *
+     * The load is memoized, so this runs at most once per store — once per process
+     * for a path — rather than once per lookup: a broken record costs one line, and
+     * the degraded view serves every later read.
+     * @param problem - what is wrong with the record, with the path.
+     * @returns the empty record.
+     */
+    private degrade;
+}
+//# sourceMappingURL=session-engine-store.d.ts.map

package/lib/types/settings.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared loop-engine identity, namespaces, and schemas.
+ *
+ * Both the namespace literals and the engine/preset-id mapping live in
+ * zero-import modules (`./namespace.ts`, `./agent-preset-ids.ts`) so both halves
+ * agree on them: the node half brands the literal as a `SettingsNamespace` and
+ * builds these schemas, while the browser half imports the same literals
+ * without pulling host-side packages (`dsh-settings`, `schemastery`, `node:fs`)
+ * into the client bundle (cross-plugin value imports go through cordis
+ * services). This module re-exports them so node-side importers keep their
+ * paths.
+ *
+ * The two live schema families exist because one build serves two harness
+ * generations: the 0.1.5 line addresses a settings SECTION registered by a
+ * provider under a namespace string ({@link LOOP_ENGINE_SETTINGS_SCHEMA} via
+ * {@link loopEngineSettingsNamespace}), while the 0.1.7 line makes the plugin's
+ * three live fields profile-backed Config entries
+ * ({@link LOOP_ENGINE_ENGINE_SCHEMA} / {@link LOOP_ENGINE_SHOW_IN_COMPOSER_SCHEMA}
+ * / {@link LOOP_ENGINE_SHOW_ENGINE_BADGE_SCHEMA}).
+ * Which family a running plugin builds is decided by `./compat.ts`
+ * (`LEGACY_HARNESS`) in `./index.ts`.
+ *
+ * @module dsh-loop-engine-allinone/settings
+ */
+import z from '@deepseek-ai/schemastery';
+import type { SettingsNamespace } from '@deepseek-ai/dsh-settings';
+import type { LoopEngineId } from './agent-preset-ids.ts';
+export { LOOP_ENGINE_SETTINGS_NAMESPACE_LITERAL, LEGACY_LOOP_ENGINE_SETTINGS_NAMESPACE_LITERAL } from './namespace.ts';
+export { HOSTED_ENGINE_IDS, HOSTED_PRESET_PREFIX, LOOP_ENGINE_IDS, SOURCE_PRESET_ID, engineOfPreset, enginePresetId, } from './agent-preset-ids.ts';
+export type { HostedEngineId, LoopEngineId } from './agent-preset-ids.ts';
+/** Stored and composed loop engine selection. */
+export interface LoopEngineSettings {
+    /** The engine NEW sessions are created on; the engine a given session runs is the plugin's own per-session record. */
+    engine: LoopEngineId;
+    /** Whether the composer's loop engine picker is shown on the chat page. */
+    showInComposer: boolean;
+    /** Whether the conversation header shows this plugin's engine badge. */
+    showEngineBadge: boolean;
+}
+/**
+ * Schema of the loop engine settings section, as the 0.1.5 line's settings host
+ * consumes it. The engine union derives from {@link LOOP_ENGINE_IDS}, so adding
+ * an engine there also admits it here.
+ */
+export declare const LOOP_ENGINE_SETTINGS_SCHEMA: z<LoopEngineSettings>;
+/** The 0.1.5-line namespace branded as a settings namespace on the node side. */
+export declare function loopEngineSettingsNamespace(): SettingsNamespace;
+/**
+ * Live Config field schema for the default engine (0.1.7 line). `.volatile()`
+ * declares it profile-backed: the settings shell projects it as a form field,
+ * and a committed edit reaches the running plugin through the live Config
+ * reference. The engine union derives from {@link LOOP_ENGINE_IDS}, so adding
+ * an engine there admits it here too.
+ */
+export declare const LOOP_ENGINE_ENGINE_SCHEMA: z<"claude-code" | "codex" | "pi" | "kimi" | "agy" | "zcode" | "qoderclicn" | "hermes" | "grok" | "minimaxcode" | "in-process", "claude-code" | "codex" | "pi" | "kimi" | "agy" | "zcode" | "qoderclicn" | "hermes" | "grok" | "minimaxcode" | "in-process", "volatile-defined">;
+/** Live Config field schema for the composer picker toggle (0.1.7 line). */
+export declare const LOOP_ENGINE_SHOW_IN_COMPOSER_SCHEMA: z<boolean, boolean, "volatile-defined">;
+/** Live Config field schema for the conversation-header badge toggle (0.1.7 line). */
+export declare const LOOP_ENGINE_SHOW_ENGINE_BADGE_SCHEMA: z<boolean, boolean, "volatile-defined">;
+//# sourceMappingURL=settings.d.ts.map