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

package/lib/types/engine-kimi/process.d.ts

@@ -48,8 +48,8 @@ export declare function kimiBinResolver(configBin?: string): string;
 /**
  * Build the persistent `kimi acp` argv. The ACP child stays alive across steps
  * and is spoken to over JSON-RPC on stdio — the prompt is a request body, not an
- * argv positional — so there is no command-line length ceiling and no model flag
- * (Kimi owns model selection natively via its own config).
+ * argv positional — so there is no command-line length ceiling and no model flag:
+ * a model is selected per ACP session through `session/set_model`, not argv.
  * @param bin - the Kimi executable.
  * @returns the argv, `argv[0]` being the executable.
  */

package/lib/types/engine-kimi/types.d.ts

@@ -13,7 +13,7 @@
  */
 /** Driver configuration after defaults and load-time validation. */
 export interface ResolvedConfig {
-    /** Model alias the `kimi` child is launched with (`--model`); Kimi native config owns the model when omitted. */
+    /** Model sent per ACP session (`session/set_model`) when the session selects none; Kimi native config owns the model when omitted. */
     readonly model: string | undefined;
     /** Explicit environment entries layered over the credential-scrubbed parent environment. */
     readonly env: Record<string, string>;

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

@@ -0,0 +1,97 @@
+/**
+ * The engine one session runs: the single authoritative read, shared by the
+ * router's routing decision and the plugin's own Remote.
+ *
+ * Two facts can answer it, in this order:
+ *
+ *  1. THE PLUGIN'S OWN RECORD — `$DSH_HOME/.loop-engine/engines.json` (see
+ *     `./session-engine-store.ts`). It exists because a user may move a session
+ *     to another engine at any time, including long after the session started,
+ *     and the harness's preset channel refuses exactly that
+ *     (`agent-preset/locked`), so the plugin keeps the choice itself. When the
+ *     record names an engine, that IS the session's engine and nothing else is
+ *     consulted — not even the durable log, which is why a session with a record
+ *     still reads correctly when its persistence is unavailable.
+ *  2. THE RECORDED AGENT PRESET, for every session the plugin has no record
+ *     for: a session created before per-session switching existed, one created
+ *     on a preset this plugin does not own, or one in a deployment whose record
+ *     file is gone. That answer comes from the durable log — the harness's
+ *     `agentPreset` projection folds the session header together with every
+ *     committed `agent-preset/selected`, so reading it IS reading the log — and
+ *     it never comes from the session header alone (a creation fact, deep-frozen)
+ *     or from a client-side listing hint (a partial cache).
+ *
+ * This module is the ONLY read: the router routes on what it returns and the
+ * plugin's own Remote reports the same value, so the engine a session is driven
+ * by and the engine it is shown as running cannot disagree.
+ *
+ * There is one refinement on top of it, and it is the whole reason
+ * {@link engineReportOfSession} exists: a session with a LIVE agent has a better
+ * answer than its record — the agent in front of it — and the two can differ
+ * (only when a release of that agent did not take, since every other switch
+ * either swaps the agent in place or leaves the session cold). The report
+ * carries both, never blending them (see {@link SessionEngineReport}).
+ *
+ * The secondary read goes through the same seam the host itself uses before
+ * choosing the composition to mount
+ * (`ctx.sessionQuery.observeSession(id, { projectionMode: 'all' })`, see
+ * `packages/api/session-controller/src/agent.ts` in the harness). The
+ * observation is a read-only lease: it is released immediately through `using`,
+ * takes no write handle, and holds no write lock.
+ *
+ * @module dsh-loop-engine/engine-of-session
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import { type LoopEngineId, type SessionEngine, type SessionEngineReport } from './agent-preset-ids.ts';
+import type { EngineRecordSource } from './session-engine-store.ts';
+/**
+ * The engine one session runs, read from the plugin's own record first and from
+ * the durable `agentPreset` projection otherwise.
+ *
+ * A deployment that composes no `sessionQuery` service has no durable log to
+ * ask, so a session with no record reads as {@link SessionEngine} `unset`: no
+ * engine is claimed for it, and the router falls back exactly as it does for a
+ * session that recorded nothing.
+ * @param ctx - the context carrying the session-query seam.
+ * @param sessionId - the persisted session to inspect.
+ * @param records - the plugin's own per-session engine record.
+ * @returns what the plugin's record, or else the durable log, says about that
+ * session's engine.
+ */
+export declare function engineOfSession(ctx: Context, sessionId: SessionId, records: EngineRecordSource): Promise<SessionEngine>;
+/**
+ * Reports the engine of one session's LIVE agent, when this process has one:
+ * the loop router's own bookkeeping (`RouterLoop.live`), which is the only
+ * record of what it actually built for a session.
+ *
+ * A reader rather than the router itself, so this fold can be exercised without
+ * one — and so the router stays the only thing that owns its bookkeeping.
+ */
+export type LiveEngineReader = (sessionId: SessionId) => LoopEngineId | undefined;
+/**
+ * What one session actually runs, and — when they differ — the engine its own
+ * record names.
+ *
+ * The live agent outranks the record, because it is the answer to the question
+ * this report exists to answer honestly: what is driving this session NOW. The
+ * record is still consulted, but as the OTHER fact — the engine this session
+ * takes when it is next built. A record that equals the live agent is no news
+ * and travels as absent; a live agent with no record at all has nothing to
+ * report beside it, because a session with no record was never switched.
+ *
+ * A session with NO live agent answers exactly as {@link engineOfSession} does:
+ * nothing is running, so the record (or, with no record, the recorded preset) IS
+ * the engine that session runs — the one its next build will use, which is the
+ * state a switch that released the session's agent leaves it in. There is no
+ * second fact to report and never a pending one.
+ * @param ctx - the context carrying the session-query seam.
+ * @param sessionId - the session to report on.
+ * @param records - the plugin's own per-session engine record.
+ * @param liveEngineOf - the engine of this session's live agent, when this
+ * process has one (the router's bookkeeping).
+ * @returns the engine driving the session, plus the recorded engine it is not
+ * running when the two differ.
+ */
+export declare function engineReportOfSession(ctx: Context, sessionId: SessionId, records: EngineRecordSource, liveEngineOf: LiveEngineReader): Promise<SessionEngineReport>;
+//# sourceMappingURL=engine-of-session.d.ts.map

package/lib/types/engine-pi/agent.d.ts

@@ -15,11 +15,15 @@ import type { Scope } from '@deepseek-ai/dsh-scope';
 import type { Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session';
 import type { Context } from '@deepseek-ai/cordis';
 import type { ResolvedConfig } from './types.ts';
-import type { PiModelEntry } from './probe.ts';
 import { DriverInbox } from '../driver-core/inbox.ts';
 import { type PiSpawnCapability } from './rpc/client.ts';
-/** Provider route label used for logged header snapshots and message provenance. */
-export declare const PROVIDER = "pi";
+/**
+ * Provider route label this driver logs into request/header snapshots and
+ * message provenance — the ONE route every hosted engine shares
+ * ({@link HOSTED_ROUTE_LABEL}), so all four engines select `external/default`
+ * and the model menu carries a single group instead of one per engine.
+ */
+export declare const PROVIDER = "external";
 /** Drives one session through turn and step boundaries on Pi. */
 export declare class PiAgent implements Agent {
     private loopCtx;
@@ -29,7 +33,6 @@ export declare class PiAgent implements Agent {
     private readonly config;
     private readonly spawn;
     private readonly bin;
-    private readonly catalog;
     readonly inbox: DriverInbox;
     private phase;
     private activityDone;
@@ -61,9 +64,7 @@ export declare class PiAgent implements Agent {
      * @param phase - the running phase carrying the open step's position.
      */
     private beginSegment;
-    constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedConfig, spawn: PiSpawnCapability, bin: string, catalog: {
-        readonly entries: readonly PiModelEntry[];
-    });
+    constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedConfig, spawn: PiSpawnCapability, bin: string);
     /**
      * Open this step's RPC child. The Pi RPC process is single-session, so a step
      * never reuses one: the step teardown disposes it and the next step respawns
@@ -135,23 +136,24 @@ export declare class PiAgent implements Agent {
     /** Append the request header snapshot once per loop instance. */
     private assertRequestHeader;
     /**
-     * The harness Session's web-side model selection, if any was stored. The
-     * durable `model/selection` event carries `{ provider, model, ... }`; when a
-     * user picked a model via `/model`, this is the newest pick, and it overrides
-     * the deployment config (which stays the fallback). Returns `undefined` when
-     * no selection was stored, so the deployment config governs.
-     */
-    private dynamicModel;
-    /** Build the `pi --mode rpc` argv/cwd/env for one step's child process. */
-    /**
-     * Resolve the `--model` for the RPC child. The session-selected model (last
-     * `model/selection` event) is honored only when it is one of pi's discovered
-     * models; an unknown harness model (e.g. another provider's model such as
-     * `anyai-v1`, which pi cannot serve) is dropped so the child falls back to pi's
-     * own default instead of exiting with "Model ... not found". An empty catalog
-     * (probe not concluded) keeps the candidate, matching prior behavior.
+     * Build the `pi --mode rpc` argv/cwd/env for one step's child process.
+     *
+     * The model comes from the session's own selection when it names a real dsh
+     * model, else from the deployment's pinned configuration
+     * ({@link sessionModelOverrideOf}). Pi's `--model` flag is
+     * `"provider/id"`-qualified, so a session pick travels as the composite —
+     * which also carries the provider, leaving the deployment's `--provider` out
+     * of the argv for that step. A step with neither a selection nor a pin sends
+     * no `--model` at all and lets Pi's own configuration decide. Read every step,
+     * so a model picked mid-conversation lands on the next child.
+     *
+     * When dsh also discloses that model's ENDPOINT, the child is pointed at it:
+     * `--provider` names the provider pi's `models.json` declares, `--api-key`
+     * carries the credential, and `PI_CODING_AGENT_DIR` redirects pi's agent
+     * directory to the plugin-owned one holding that `models.json`
+     * ({@link piAgentDir}) — so the child runs on dsh's endpoint instead of its
+     * own `~/.pi` configuration, which is never touched.
      */
-    private pickModel;
     private spawnSpec;
     /**
      * Run one Pi RPC query for the current step and map its event stream into the

package/lib/types/engine-pi/loop.d.ts

@@ -1,10 +1,9 @@
 /**
- * Pi loop engine module: hosts the AgentFactory that drives every session
- * through the Pi CLI (`@earendil-works/pi-coding-agent`) over its JSONL RPC
- * mode, one stateless session per dsh step, with the durable session log as the
- * sole source of model context. dsh-loop-engine constructs this factory when
- * the Pi engine is selected; this module is a library, not a Cordis plugin
- * entry. Pi has no permission system, so the entire `pi --mode rpc` child is
+ * Pi loop engine module: drives every session it is handed through the Pi CLI
+ * (`@earendil-works/pi-coding-agent`) over its JSONL RPC mode, one stateless
+ * session per dsh step, with the durable session log as the sole source of
+ * model context. The router routes a session here on the plugin's own engine
+ * record, else its agent preset; this module is a library, not a Cordis plugin entry. Pi has no permission system, so the entire `pi --mode rpc` child is
  * spawned through the dsh subprocess seam — the only available privilege
  * boundary — and its `--tools` are pruned to the resolved sandbox stance.
  *
@@ -15,10 +14,9 @@ import z from '@deepseek-ai/schemastery';
 import type { AgentOptions } from '@deepseek-ai/dsh-agent';
 import type { Session, SessionId } from '@deepseek-ai/dsh-session';
 import { PiAgent } from './agent.ts';
-import type { PiModelEntry } from './probe.ts';
 import type { PiProcess, PiSpawnSpec } from './rpc/client.ts';
 import type { PiSandboxMode, ResolvedConfig } from './types.ts';
-import { HostedLoopFactory } from '../driver-core/hosted-loop-factory.ts';
+import { HostedEngineRuntime } from '../driver-core/hosted-engine-runtime.ts';
 /** Pi CLI sandbox modes a deployment may pin. */
 export declare const PI_SANDBOX_MODES: readonly PiSandboxMode[];
 /** Grace in milliseconds for Pi process-tree termination. */
@@ -35,40 +33,32 @@ export interface Config {
     sandboxMode?: PiSandboxMode;
     /** LLM provider for the `pi` child (`--provider`), when the deployment pins one. */
     provider?: string;
-    /** Model pattern for the `pi` child (`--model`); Pi native settings own the model when omitted. */
+    /** Fallback model for the `pi` child (`--model`), used when the session selects none; Pi native settings own the model when omitted. */
     model?: string;
     /** Thinking/reasoning level, appended to the `--model` pattern when pinned. */
     thinkingLevel?: string;
     /** Explicit environment entries passed to the `pi` child. */
     env?: Record<string, string>;
-    /** Shared Pi model catalog holder; the loop writes its `pi --list-models` probe result here. */
-    piCatalogHolder?: {
-        entries: readonly PiModelEntry[];
-    };
 }
 /** Schema of the Pi loop plugin configuration. */
 export declare const Config: z<Config>;
-/** Host-face ctx key for the Pi loop service. */
+/** Host-face ctx key this engine's runtime is registered under. */
+export declare const PI_ENGINE_LABEL = "agentLoopPi";
 declare module '@deepseek-ai/cordis' {
     interface Context {
         agentLoopPi: PiLoop;
     }
 }
 /**
- * Concrete AgentFactory and driver service of the Pi loop. Creation and resume
- * follow the registry factory contract and the shared publication transaction:
- * prepare, run setup, then publish through both registries, announce, and emit
- * `agent/session-start`.
+ * Creation/resume machinery for the Pi engine. The process-wide AgentFactory
+ * slot belongs to the router, which delegates each session to the engine its
+ * preset names; this class is that engine's driver, not a plugin.
  */
-export declare class PiLoop extends HostedLoopFactory<ResolvedConfig, PiAgent> {
-    /** Services the loop resolves through its own fiber; blessed identically to the package-level entry inject. */
-    static inject: string[];
+export declare class PiLoop extends HostedEngineRuntime<ResolvedConfig, PiAgent> {
     /** Process-tree spawn capability handed to every agent, sandboxed by the subprocess seam. */
     readonly spawn: (spec: PiSpawnSpec) => PiProcess;
     /** Resolved Pi CLI entrypoint; `argv[0]` of every Pi RPC child. */
     readonly bin: string;
-    /** Discovered Pi model catalog, forwarded to each agent so it can validate the session-selected model against what pi can actually serve. */
-    private readonly catalog;
     constructor(ctx: Context, config: Config);
     /** Construct the Pi RPC driver for one prepared session. */
     protected buildAgent(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session): PiAgent;

package/lib/types/engine-pi/model-handover.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pi's dialect for a dsh endpoint: a self-built agent directory plus the argv
+ * flags that point the `pi --mode rpc` child at dsh's model.
+ *
+ * Pi resolves a model through its own agent directory — `models.json` under
+ * `PI_CODING_AGENT_DIR` (or `~/.pi` when unset) — and its custom-provider schema
+ * has no `apiKeyEnv`: a provider's credential is either a literal `apiKey` in
+ * that file or the CLI's own `--api-key`. There is no `PI_*` variable for a base
+ * URL either. So the only automatic way to hand pi a dsh endpoint is to give it
+ * an agent directory THIS PLUGIN owns, containing a `models.json` that declares
+ * the dsh provider, and to point `PI_CODING_AGENT_DIR` at it.
+ *
+ * The user's `~/.pi` is deliberately never written or read: the plugin owns a
+ * separate directory under the OS temp dir, one per distinct endpoint, created
+ * 0700 with a 0600 file because it carries the credential. The cost is real and
+ * documented: redirecting the agent directory means the child no longer sees the
+ * user's own `~/.pi` skills/auth/theme. That is the trade the deployment makes
+ * by selecting a real dsh model on pi.
+ *
+ * @module dsh-loop-engine/engine-pi/model-handover
+ */
+import type { DshModelHandover } from '../driver-core/model-handover.ts';
+/**
+ * The agent directory for one handover, materialized on first use.
+ *
+ * The directory name is a hash of the endpoint facts, so two sessions on the
+ * same provider/model share one directory and a changed endpoint gets its own;
+ * `models.json` declares exactly the provider pi is told to use (`--provider`)
+ * and the one model it is told to run (`--model`), keyed the way pi's own
+ * schema reads it (`baseUrl`/`api`/`apiKey`/`models`).
+ * @param handover - the resolved dsh endpoint for the session's selection.
+ * @returns the absolute path to hand the child as `PI_CODING_AGENT_DIR`.
+ */
+export declare function piAgentDir(handover: DshModelHandover): string;
+//# sourceMappingURL=model-handover.d.ts.map

package/lib/types/engine-pi/types.d.ts

@@ -15,9 +15,9 @@ export type PiSandboxMode = 'read-only' | 'workspace-write' | 'danger-full-acces
 export interface ResolvedConfig {
     /** Pinned sandbox mode; `undefined` follows the session's dsh permission knobs per query. */
     readonly sandboxMode: PiSandboxMode | undefined;
-    /** LLM provider the `pi` RPC process is launched with (`--provider`). */
+    /** LLM provider the `pi` RPC process is launched with (`--provider`), when the session selects no model. */
     readonly provider: string | undefined;
-    /** Model pattern the `pi` RPC process is launched with (`--model`). */
+    /** Fallback model pattern for the `pi` RPC process (`--model`), used when the session selects none. */
     readonly model: string | undefined;
     /** Thinking/reasoning level for the model (`--model <id>:<level>` or set at runtime). */
     readonly thinkingLevel: string | undefined;

package/lib/types/engine-remote.d.ts

@@ -0,0 +1,192 @@
+/**
+ * The plugin's own Remote: "which engine does this session run?" and "move this
+ * session to another engine", both answered from the plugin's own per-session
+ * record, the session's live agent, and the durable log through one shared read.
+ *
+ * The browser half cannot answer the first question honestly from what the
+ * harness hands a page. The client Session list carries `projectionValues`
+ * computed by `@deepseek-ai/dsh-api-session-controller`'s `projectionsFor()`,
+ * which returns a `SessionProjectionHints` snapshot — "every currently cached
+ * wire value", and partial by its own documentation: a cell the page's cache has
+ * not folded yet is simply absent. The engine a session ACTUALLY runs is not a
+ * cache fact at all, so the plugin becomes its own authority:
+ *
+ *  - node half (here): a Typert Remote service, discovered by the host Gateway
+ *    through its visible `typertRemote` binding and its `@Remote` method marks
+ *    (`bindTypertRemote` / `@Remote` in `@deepseek-ai/dsh-typert-protocol`, the
+ *    same mechanism `@deepseek-ai/dsh-agent-presets` uses for its own roster).
+ *    Both endpoints go through {@link engineReportOfSession} /
+ *    {@link RouterLoop.reportEngine} / {@link RouterLoop.selectEngine} — the very
+ *    reads the router routes on — so what a session is driven by and what a
+ *    session is shown as running cannot disagree, because there is one answer.
+ *    The report carries the ONE case in which a session has two facts (a live
+ *    agent and a record that did not displace it) as two fields rather than
+ *    blending them; see {@link SessionEngineReport}.
+ *  - browser half (`src/client/session-engine.ts`): mounts these endpoints as
+ *    `remote.loopEngine.engine({ sessionId })` and
+ *    `remote.loopEngine.select({ sessionId, engine })`, and renders only what
+ *    they answer.
+ *
+ * Both methods take a PLAIN object parameter rather than an identity the Gateway
+ * resolves: typert resolves a parameter named `agent`/`session` into a LIVE
+ * object through its lookup providers, and these endpoints must answer for any
+ * PERSISTED session — including one no process has loaded.
+ *
+ * Wire contract (no codegen is involved; the Gateway derives the signature from
+ * the live method):
+ *
+ *  - endpoint `loopEngine/engine`;
+ *  - endpoint `loopEngine/select`;
+ *  - one `src-json` argument per endpoint whose wire name is the method's own
+ *    parameter name (`request`) — REQUIRED for the browser half to be
+ *    understood, so the parameter name is part of the contract and must not be
+ *    renamed or destructured (see the Gateway's `methodParameterNames`);
+ *  - `engine` results in the plain-JSON {@link SessionEngineReport} — the engine
+ *    the session ACTUALLY runs, plus (only while a live agent the record did not
+ *    displace keeps running) the one the record names; `select` results in the
+ *    plain-JSON {@link LoopEngineSelectResult} — a refusal is a VALUE, so a
+ *    predictable "no" travels as data the surface can render (a
+ *    {@link LoopEngineRefusalCode} plus the host's own sentence as detail, which
+ *    is what lets the browser half show localized copy instead of a raw English
+ *    one-liner), while only a malformed request is a `RemoteError`, and an
+ *    outcome carrying `reload` tells the browser half to reload the page, because
+ *    the switch was made to land by releasing the session's agent.
+ *
+ * @module dsh-loop-engine/engine-remote
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { SessionId } from '@deepseek-ai/dsh-session';
+import { type LoopEngineId, type SessionEngine, type SessionEngineReport, type LoopEngineSelectResult } from './agent-preset-ids.ts';
+/** Cordis service key AND wire namespace of the plugin's own Remote. */
+export declare const LOOP_ENGINE_REMOTE_KEY = "loopEngine";
+/** Endpoint method reporting one session's engine. */
+export declare const LOOP_ENGINE_REMOTE_METHOD = "engine";
+/** Endpoint method moving one session to another engine. */
+export declare const LOOP_ENGINE_REMOTE_SELECT_METHOD = "select";
+/** The wire request the reporting endpoint accepts. */
+export interface LoopEngineRequest {
+    /** The session to report on. A plain string, never a resolved live object. */
+    readonly sessionId: string;
+}
+/**
+ * The wire request the switching endpoint accepts. The engine is typed as a
+ * string because that is what the wire carries; the endpoint validates it
+ * against {@link LOOP_ENGINE_IDS} before anything acts on it.
+ */
+export interface LoopEngineSelectRequest {
+    /** The session to move. A plain string, never a resolved live object. */
+    readonly sessionId: string;
+    /** The engine that session should run. */
+    readonly engine: string;
+}
+/**
+ * The engine one session runs, read from the plugin's own record and the durable
+ * log (`engineOfSession`).
+ *
+ * The FALLBACK answer, not the whole one: it knows nothing about a live agent, so
+ * the endpoint uses it only while no router is mounted
+ * ({@link RouterSurfaceHolder}) — the mount window, in which no session is driven
+ * by this plugin anyway.
+ */
+export type SessionEngineResolver = (sessionId: SessionId) => Promise<SessionEngine>;
+/** Move one session to another engine, refusing with a reason rather than throwing. */
+export type SessionEngineSelector = (sessionId: SessionId, engine: LoopEngineId) => Promise<LoopEngineSelectResult>;
+/**
+ * The mounted loop router, as these two endpoints need it: the reporting read
+ * and the move, both of which only a live router can make.
+ *
+ * Structural rather than the class itself, so this module takes no build-time
+ * dependency on `./router-loop.ts` (which drags in the harness loop and every
+ * engine driver) and a test can stand in for it.
+ */
+export interface RouterSurface {
+    /** Report what one session actually runs, plus the recorded engine when the two differ. */
+    reportEngine(sessionId: SessionId): Promise<SessionEngineReport>;
+    /** Move one session to another engine, or answer why it was not moved. */
+    selectEngine(sessionId: SessionId, engine: LoopEngineId): Promise<LoopEngineSelectResult>;
+}
+/**
+ * Where the two endpoints find the mounted router.
+ *
+ * A holder rather than a fixed reference because the router is mounted
+ * asynchronously — and not at all until the harness's live patch reload drops the
+ * base bundle's `agent-loop` row (`src/index.ts` `mountRouter`). Until then both
+ * endpoints answer from what a router-less process still knows: the record and
+ * the log. A session that is not driven by this plugin has no live agent to
+ * report anyway, so the answers agree.
+ */
+export interface RouterSurfaceHolder {
+    /** The mounted router, or undefined while there is no router. */
+    current: RouterSurface | undefined;
+}
+/**
+ * `remote.loopEngine`: report one session's engine, and move it to another.
+ *
+ * Registered as a Cordis service under {@link LOOP_ENGINE_REMOTE_KEY} on the
+ * plugin's own fiber, so the binding and the method marks disappear with the
+ * plugin: a profile that mounts no Gateway never discovers it, and unmounting
+ * the plugin withdraws both.
+ */
+export declare class LoopEngineRemote extends TypertRemoteService {
+    private readonly resolve;
+    private readonly router;
+    private readonly warn;
+    /**
+     * @param ctx - the context the service (and its lifetime) belongs to.
+     * @param resolve - the router-less read; normally
+     *   `engineOfSession(ctx, sessionId, records)`.
+     * @param router - where both endpoints find the mounted loop router.
+     * @param warn - diagnostic sink for a session that could not be read.
+     */
+    constructor(ctx: Context, resolve: SessionEngineResolver, router: RouterSurfaceHolder, warn: (message: string) => void);
+    /**
+     * Report what one session runs — and, when its own record names a different
+     * engine than the live agent, that fact separately.
+     *
+     * The router answers when it is mounted, because the live agent outranks every
+     * record: only the router knows which engine built the agent driving this
+     * session now, and only the router can tell a record whose release did not take
+     * from one that already landed. Without a router (the mount-retry window) no
+     * session is driven by this plugin, so the record — i.e.
+     * {@link SessionEngineResolver} — is the whole answer.
+     *
+     * A session that cannot be read answers `unset` rather than throwing: a
+     * surface that asked about a session the durable log does not know must render
+     * "engine not recorded", not break the page it is rendered in. Failures are
+     * reported once on the host's log instead.
+     *
+     * A malformed REQUEST is a caller fault, not an unreadable session, and is
+     * refused the way every typert endpoint refuses one.
+     * @param request - the wire request carrying the session id.
+     * @returns the engine driving that session, plus the recorded engine it is not
+     * running when the two differ.
+     * @throws {RemoteError} with `gateway/bad-request` when no session id was sent.
+     */
+    engine(request: LoopEngineRequest): Promise<SessionEngineReport>;
+    /**
+     * Move one session to another engine.
+     *
+     * The move owns no policy of its own: the router decides whether this session
+     * can be moved right now and answers with a reason when it cannot, because
+     * only it knows the session's live agent, its turn state, and the teardown it
+     * would have to perform. This endpoint's job is the boundary — reject a
+     * malformed request the way every typert endpoint does, and hand a well-formed
+     * one to the selector.
+     * @param request - the wire request carrying the session id and target engine.
+     * @returns the engine now recorded for the session — with `reload: true` when
+     * its agent had to be released for the change to land, which the browser half
+     * acts on by reloading the page — or, as `ok: false`, the
+     * {@link LoopEngineRefusalCode} of the branch that refused it together with the
+     * host's own sentence about this session (`router-unmounted` is this
+     * endpoint's own, `session-closed` / `turn-running` / `subagent-session` /
+     * `not-driven` / `record-failed` / `rebuild-failed` come from the router's
+     * checks). The browser half localizes from the code and keeps the sentence as
+     * detail, so the code is part of this endpoint's contract even though the
+     * shape allows it to be absent.
+     * @throws {RemoteError} with `gateway/bad-request` when the session id is not
+     * a non-empty string or the engine is not an installed engine id.
+     */
+    select(request: LoopEngineSelectRequest): Promise<LoopEngineSelectResult>;
+}
+//# sourceMappingURL=engine-remote.d.ts.map

package/lib/types/engine-surface.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Per-session command and skill surface of the hosted engines.
+ *
+ * A hosted engine owns its session's slash-command menu and skill catalog: the
+ * engine expands `/name` itself and reads its own instruction files, so the
+ * plugin bridges both into the session the engine serves and nothing more.
+ *
+ * The registrations are made through the AGENT's own context, which is what
+ * makes them session-scoped: `commands.register` and
+ * `skills.registerProvider` file a definition into the layer of the calling
+ * context's scope (`packages/core/scope/src/store.ts` `effect()` keys the layer
+ * by `scopeOf(ctx)`), and an agent's scope key is the agent itself
+ * (`createScope(loopCtx, this)` in the default loop; the hosted drivers do the
+ * same). Two sessions running different engines therefore never see each
+ * other's menus, and the whole surface disappears with the agent's scope — no
+ * plugin-side bookkeeping, no leak across an engine switch.
+ *
+ * @module dsh-loop-engine/engine-surface
+ */
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { HostedEngineId } from './settings.ts';
+/**
+ * Bridge one hosted engine's commands and skills into the session it serves.
+ *
+ * Best-effort like the rest of the plugin's host-service use: a profile without
+ * the commands or skills registry simply has no surface to extend. A name that
+ * collides with an already-registered command in the same layer is skipped with
+ * a warning rather than failing the agent: the engine expands the raw `/name`
+ * line itself, so a shyer menu beats an agent that refuses to start.
+ *
+ * @param agent - the freshly built agent whose scope owns the registrations.
+ * @param engine - the hosted engine driving that agent.
+ * @param warn - sink for the skip diagnostics.
+ */
+export declare function registerEngineSurface(agent: Agent, engine: HostedEngineId, warn: (message: string) => void): void;
+//# sourceMappingURL=engine-surface.d.ts.map