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

package/lib/types/client/use-session-engine.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The React binding over the plugin's per-session engine cache.
+ *
+ * Separated from `./session-engine.ts` on purpose: the cache, the contribution,
+ * and the switcher are plain logic with no React import, so they are exercised
+ * in node (`tests/session-engine-cache.spec.ts`) — this file is the only part of
+ * the read path that needs a component to render.
+ *
+ * It is also the ONE driver of the chat turn-status row
+ * (`./turn-status.ts`): the row is painted through a document-level attribute,
+ * and a component is the only place that knows whether the session it renders is
+ * the one on screen. The cache cannot know that — it answers for every session a
+ * surface has watched — so a reflection made from there could be (and was) taken
+ * over by a background session. Here the chip and the composer of the session on
+ * screen declare that session as the row's subject while they are mounted, with
+ * the focus guard inside `reflectTurnStatusEngine`, and the reflection follows
+ * the cache's answer so a switch repaints the row.
+ *
+ * @module dsh-loop-engine/client/use-session-engine
+ */
+import { type SessionEngineReport } from '../agent-preset-ids.ts';
+import type { SessionEngineCache } from './session-engine.ts';
+/**
+ * Follow one session's engine report in a component, and — because a component
+ * is what knows whether this session is the one on screen — drive the chat
+ * turn-status row from it.
+ *
+ * The value is read from the cache DURING render, so a session switch can never
+ * paint the previous session's engine: only the re-render is deferred, and only
+ * until the host answers. The reflection runs in an effect rather than during
+ * render (it writes to the document), and re-runs when the ANSWER changes — not
+ * just when the session id does — so the row follows a switch: the picker's
+ * `invalidate` drops the cached answer, the cache re-asks, the hook's watcher
+ * bumps, the engine changes, and the attribute lands on the engine the session
+ * now runs.
+ *
+ * Only the ACTUAL engine reaches the row. A recorded engine that differs from it
+ * is one whose switch never took over (its release did not complete), so the row
+ * keeps painting what is really running — the same rule the chip and the composer
+ * follow when they name an engine; they merely also carry the marker
+ * ({@link SessionEngineReport}).
+ *
+ * The value is read from the cache DURING render, so a session switch can never
+ * paint the previous session's engine: only the re-render is deferred, and only
+ * until the host answers. This effect is also the trigger that re-reads the
+ * session: it runs when the session on screen CHANGES (a mount, a switch, or the
+ * same session opened again), and the subscription it installs re-reads the
+ * session on its first watch (`SessionEngineCache.watch` → `refresh`), so a
+ * session the user comes back to cannot keep rendering a report this page took
+ * before — coming back is not what moves the session (a switch is performed on
+ * the host, and the one that has to release the session reloads this page), but
+ * it is long enough for the answer to be old.
+ * Re-renders of the same session do not re-run this effect, so nothing here asks
+ * again while the session stays on screen.
+ *
+ * One effect does the whole thing, so the three steps cannot come apart: declare
+ * this session as the row's subject (`focusTurnStatusSession`), reflect its
+ * engine by that declaration (`reflectTurnStatusEngine`), and release the
+ * declaration when this surface goes away (`blurTurnStatusSession`, which
+ * withdraws it only while it is still this session's).
+ * @param cache - the cache the plugin mounted.
+ * @param sessionId - the session to follow, or undefined off a session scope.
+ * @returns the engine report, or undefined while it is unknown.
+ */
+export declare function useEngineOfSession(cache: SessionEngineCache, sessionId: string | undefined): SessionEngineReport | undefined;
+//# sourceMappingURL=use-session-engine.d.ts.map

package/lib/types/commands.d.ts

@@ -17,6 +17,14 @@
  * are cwd-dependent, and a global dsh registration would collide across
  * projects.
  *
+ * The built-in list is limited to commands the CLI actually recognizes in SDK
+ * mode (verified against Claude Code 2.1.220 by driving real SDK queries):
+ * unknown ones are not forwarded to the model at all — the CLI answers
+ * `Unknown command: /name` — but registering one would still advertise a
+ * command that does not exist. Note that some recognized commands report
+ * `isn't available in this environment` outside the interactive TUI; that
+ * report is the engine's own answer and travels back as an assistant message.
+ *
  * @module dsh-loop-engine/commands
  */
 import type { UserMessage } from '@deepseek-ai/dsh-session';
@@ -60,9 +68,9 @@ export declare const CLAUDE_CODE_COMMANDS: readonly CommandDefinition[];
 /**
  * Discover the user-level custom slash commands from `~/.claude/commands/*.md`
  * and build forwarding definitions for them. The scan is synchronous so the
- * mount path can register the commands before the engine-selection commit
- * returns; files without a usable name or description, and names already taken
- * by the built-ins, are skipped.
+ * agent-creation path can register the commands before the agent is published;
+ * files without a usable name or description, and names already taken by the
+ * built-ins, are skipped.
  * @returns forwarding definitions, sorted by file name.
  */
 export declare function discoverUserSlashCommands(): CommandDefinition[];

package/lib/types/driver-core/host-servers.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Minimal structural shapes of the optional host registries the plugin
+ * extends.
+ *
+ * Declared locally rather than imported from their packages: the plugin
+ * depends on the SERVICE CONTRACTS it consumes only where the harness exposes
+ * one (`dsh-agent`, `dsh-session`, …), and the command/skill registries are
+ * read through `ctx.get` and may legitimately be absent in a minimal profile.
+ * Keeping the shapes here means one definition shared by every consumer and no
+ * peer dependency that a headless composition does not need.
+ *
+ * @module dsh-loop-engine/driver-core/host-servers
+ */
+import type { CommandDefinition } from '../commands.ts';
+import type { SkillProvider, SkillProviderControl } from '../skills.ts';
+import type { SettingsNamespace, SettingsPathOp } from '@deepseek-ai/dsh-settings';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { HostedEngineRouteAdapter } from '../provider-route.ts';
+/** The host command registry (`ctx.commands`), as this plugin uses it. */
+export interface CommandsService {
+    /** Register one definition in the calling context's scope layer. */
+    register(def: CommandDefinition): () => void;
+}
+/** The host skill registry (`ctx.skills`), as this plugin uses it. */
+export interface SkillsService {
+    /** Register a provider in the calling context's scope layer. */
+    registerProvider(create: (control: SkillProviderControl) => SkillProvider): () => void;
+}
+/** The host preset roster (`ctx.agentPresets`), as this plugin uses it. */
+export interface AgentPresetsService {
+    /** The effective default preset id. */
+    readonly defaultId: string;
+    /** Read one preset's composition text. */
+    read(id: string): Promise<string>;
+}
+/** The host settings service's mutation seam, as this plugin uses it. */
+export interface SettingsMutator {
+    /** Apply ops to one namespace. */
+    mutate(ns: SettingsNamespace, ops: readonly SettingsPathOp[]): Promise<void>;
+    /** Registered namespaces, when the provider can enumerate them. */
+    describe?(): SettingsDescriptorLike[];
+}
+/**
+ * One registered settings namespace, as the host describes it
+ * (`@deepseek-ai/dsh-settings` `SettingsDescriptor`). Only the two fields this
+ * plugin reads are declared.
+ */
+export interface SettingsDescriptorLike {
+    /** Namespace name. */
+    readonly ns: string;
+    /**
+     * The composition's own value for this namespace, before the user layer. It is
+     * what a saved user-layer value overrode, which is why `model-selection-reset.ts`
+     * reads it: the deployment's own configured default model is a real model it
+     * can name when the saved default does not.
+     */
+    readonly base?: unknown;
+}
+/** The host llm registry (`ctx.llm`), as this plugin uses it. */
+export interface LlmRegistry {
+    /** Register a placeholder adapter for one or more provider labels. */
+    registerAdapter(providers: string[], adapter: HostedEngineRouteAdapter): () => void;
+}
+/** The host session-projection registry (`ctx.sessionProjections`), as this plugin uses it. */
+export interface SessionProjectionsService {
+    /** Folded projection state of one session, or undefined when it never advanced. */
+    stateOf(session: Session, key: 'turnBoundary'): TurnBoundaryFacts | undefined;
+    /** The same fold for the durable model selection (`model-selection-reset.ts`). */
+    stateOf(session: Session, key: 'modelSelection'): ModelSelectionFacts | undefined;
+}
+/**
+ * One complete model selection as the host's `model/selection` event and its
+ * projection carry it (`packages/api/session-controller/src/types.ts`,
+ * `ModelSelection`).
+ */
+export interface SessionModelSelection {
+    /** Registered provider route. */
+    readonly provider: string;
+    /** Provider-owned model id. */
+    readonly model: string;
+    /** Adapter-owned reasoning effort, or provider/default behavior when absent. */
+    readonly reasoningEffort?: string;
+}
+/**
+ * The slice of the host's `modelSelection` projection state this plugin reads.
+ * `lastUsed` is deliberately not declared: it is that fold's view of the newest
+ * `request/header`, which the plugin reads from the session itself
+ * (`Session.requestHeader()`) with the same result.
+ */
+export interface ModelSelectionFacts {
+    /** Later selection not yet consumed by a matching recorded request, or null. */
+    readonly pending: SessionModelSelection | null;
+}
+/**
+ * The turn-boundary facts this plugin reads. Mirrors `TurnBoundaryProjection`
+ * in `@deepseek-ai/dsh-agent` without depending on that module's projection
+ * registry augmentation, which a non-plugin consumer has no other reason to
+ * pull into its program.
+ */
+export interface TurnBoundaryFacts {
+    /** Seq of the open turn's `turn/start`, or null between turns. */
+    readonly openTurnStartSeq: number | null;
+    /** Turn number of the latest `turn/start`; 0 before the first turn. */
+    readonly lastTurn: number;
+}
+//# sourceMappingURL=host-servers.d.ts.map

package/lib/types/driver-core/hosted-engine-runtime.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Shared AgentFactory transaction machinery for the hosted loop engines.
+ *
+ * All four engines (Claude Code, Codex, Pi, Kimi Code) implement the harness's
+ * AgentFactory contract the same way: prepare a driver, scope, and one memoized
+ * reverse teardown for a session; run the caller's setup under a fused abort
+ * signal; publish through both registries and announce; and on resume, own a
+ * session's write handle across the cold read, crash repair, and
+ * re-publication. None of that touches an engine protocol — the whole
+ * engine-specific surface is one call, {@link HostedEngineRuntime.buildAgent}.
+ *
+ * One move has no counterpart in the harness's own factory contract and is what
+ * makes an in-place engine swap possible: a LIVE session changes drivers without
+ * being released. {@link HostedAgentHandle.retire} stops the outgoing machine
+ * while leaving the session entered, and {@link HostedEngineRuntime.swap} builds
+ * the incoming engine's machine onto that same Session. The session's store
+ * entry and write handle travel across the handover in a
+ * {@link SessionLifetime} — the one object that owns them.
+ *
+ * This body mirrors the default in-process `agent-loop` factory. It is a plain
+ * class, not a Cordis plugin: the process-wide AgentFactory slot is owned by
+ * the router (`router-loop.ts`, which subclasses the harness `AgentLoop`), and
+ * every hosted engine is one runtime instance the router delegates to. That is
+ * what lets several engines serve different sessions concurrently — the
+ * harness admits exactly one factory, so the factory itself must dispatch.
+ *
+ * Subclasses supply:
+ *   - the effect label prefix (`<label>.transactions()`,
+ *     `<label>.lifecycle(id)`, `<label>.resume-load(id)`) — the lifecycle label
+ *     is asserted by tests, so it must stay `<label>.lifecycle(...)`;
+ *   - their own configuration resolution;
+ *   - {@link HostedEngineRuntime.buildAgent}.
+ *
+ * @module dsh-loop-engine/driver-core/hosted-engine-runtime
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent, AgentFactory, AgentHandle, AgentOptions, AgentSetup, CreateAgentOptions, ResumeAgentOptions } from '@deepseek-ai/dsh-agent';
+import { SessionId } from '@deepseek-ai/dsh-session';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { Scope } from '@deepseek-ai/dsh-scope';
+import { SessionLifetime } from './session-lifetime.ts';
+/**
+ * What the transaction machinery needs of a driver beyond the harness `Agent`
+ * contract: a teardown entry point that also unwinds the driver's own scope.
+ * The concrete engines declare these; the base only spells them out so the
+ * shared body can call them generically.
+ */
+export interface HostedAgent extends Agent {
+    /** Stop the machine with the given cause, without waiting for it to settle. */
+    cancel(cause: Parameters<Agent['cancel']>[0]): void;
+    /** Resolves when the machine has no work in flight. */
+    whenIdle(): Promise<void>;
+    /** The driver's own resource scope, unwound after the machine settles. */
+    readonly scope: Scope;
+}
+/**
+ * The plugin's own handle for one published hosted agent: the harness contract
+ * plus the two facts an in-place engine swap needs.
+ *
+ * A swap is two moves by two different runtimes: the outgoing engine retires its
+ * machine and hands the session over, and the incoming engine builds onto that
+ * session. The router is the only caller and it tracks the handle already, so
+ * the harness's own `AgentHandle` — which carries neither fact — is widened
+ * here rather than reaching back into a transaction that has ended.
+ */
+export interface HostedAgentHandle extends AgentHandle {
+    /** The live session's lifetime resources, owned by this agent until it is disposed. */
+    readonly lifetime: SessionLifetime;
+    /**
+     * Retire this machine for good while LEAVING the session alive: stop it,
+     * unwind its scope, and leave the agent registry — the session's entry and
+     * write handle pass to {@link SessionLifetime}'s next owner instead of being
+     * released here. Only valid while this agent still owns the session: the
+     * router calls it for the session's live, idle agent only.
+     */
+    retire(): Promise<void>;
+}
+/** Options for {@link HostedEngineRuntime.swap}. */
+export interface SwapAgentOptions {
+    /** The live session's lifetime resources, handed over by the outgoing engine. */
+    readonly lifetime: SessionLifetime;
+    /** Loop options for the successor; the router replays the outgoing agent's own. */
+    readonly agentOptions?: AgentOptions | undefined;
+    /** The composition callback the session was built with, replayed onto the successor. */
+    readonly setup?: AgentSetup | undefined;
+    /** The outgoing agent's runtime owner, for a child session's inherited ownership. */
+    readonly parentAgent?: Agent | undefined;
+}
+/**
+ * Concrete creation/resume machinery for one hosted engine.
+ *
+ * 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`. {@link swap} follows the
+ * same transaction onto a session another agent entered, which is the only
+ * difference between taking a session over and owning it from birth.
+ */
+export declare abstract class HostedEngineRuntime<TConfig, TAgent extends HostedAgent> implements AgentFactory {
+    /** Validated configuration owned by this engine instance. */
+    readonly config: TConfig;
+    /** Effect-label prefix; also identifies the engine in diagnostics. */
+    readonly label: string;
+    /** Plain holder prevents Cordis from re-tracing the factory's dependency context through a caller shadow. */
+    protected readonly runtime: {
+        ctx: Context;
+    };
+    private readonly ownership;
+    /**
+     * @param ctx - the owning context; its fiber's unload tears every live agent down.
+     * @param label - effect-label prefix, e.g. `agentLoopKimi`.
+     * @param config - already-resolved engine configuration.
+     */
+    constructor(ctx: Context, label: string, config: TConfig);
+    /**
+     * Construct this engine's driver for one prepared session. Called once per
+     * create, resume, or swap, after the session exists and before setup runs; the
+     * hook is the engine's entire protocol surface.
+     */
+    protected abstract buildAgent(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session): TAgent;
+    /**
+     * Construct the driver, scope, and one memoized reverse teardown for a new
+     * agent. The teardown is registered with the factory and the owner fiber
+     * BEFORE publication, so a mid-setup unload rolls everything back; `signal`
+     * fuses caller cancellation with lifecycle teardown for setup awaits.
+     *
+     * `lifetime` carries the session's store entry and write handle rather than
+     * this body owning them: a fresh transaction binds them when it publishes,
+     * while a swap publishes a session whose entry another machine already bound
+     * and whose write handle another machine already opened.
+     */
+    private prepare;
+    /** Prepare one Agent around an acquired Session, run setup, and publish it. */
+    private setupAndPublish;
+    /**
+     * Create an agent and session under one caller-supplied identity, owned by
+     * the accessing fiber. When a persistence backend is mounted, the session's
+     * durable identity is stored before publication.
+     * @param ownerCtx - caller context that structurally owns the lifecycle.
+     * @param options - identities, optional live parent, session seed/metadata, loop options, setup, and cancellation.
+     * @returns the published handle.
+     */
+    createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<HostedAgentHandle>;
+    /**
+     * Take a fresh session's write ownership when persistence is mounted.
+     * Nothing is appended here: the constructor seed (which never re-emits
+     * through `session/event`) is stored by {@link appendUnstoredSuffix} at the
+     * publication commit point, so a failed or cancelled setup closes an
+     * unmaterialized handle and leaves no stored residue — the same id can be
+     * created again.
+     * @param session - the unpublished session to store.
+     * @param signal - optional cancellation forwarded to the backend create.
+     * @returns the owned handle and stored cursor, or `undefined` without a backend.
+     */
+    private createStoredSession;
+    /**
+     * Durably store the session events appended since the last stored cursor.
+     * Pre-publication appends (constructor seed markers, setup-window events)
+     * never re-emit through `session/event`, so publication must flush them
+     * through the handle before live events start routing into it.
+     * @param stored - the session's owned handle and stored cursor, if any.
+     * @param session - the unpublished session whose suffix is stored.
+     */
+    private appendUnstoredSuffix;
+    /**
+     * Resume an owned agent from the configured persistence service.
+     * @param ownerCtx - caller context that owns load, setup, and the live lifecycle.
+     * @param options - persisted identity, optional live parent, loop options, setup, and cancellation.
+     * @returns the published handle.
+     */
+    resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<HostedAgentHandle>;
+    /**
+     * Build this engine's agent onto a LIVE session another engine's agent left,
+     * taking the session's lifetime over.
+     *
+     * The counterpart of {@link HostedAgentHandle.retire}: together they are an
+     * in-place engine swap, and the harness's own factory contract has neither.
+     * Nothing is read from persistence and nothing is created in the store — the
+     * successor drives the Session object that is already live and already
+     * entered, so a browser half attached to that session sees no lifecycle edge
+     * at all. The lifetime carries the still-open write handle, so the session
+     * keeps being stored through the same channel it was already using.
+     * @param ownerCtx - caller context that structurally owns the lifecycle.
+     * @param options - the live session's lifetime, loop options, setup, and parent.
+     * @returns the published handle, which owns the session from here on.
+     */
+    swap(ownerCtx: Context, options: SwapAgentOptions): Promise<HostedAgentHandle>;
+    /** Resume through an explicit persistence service. */
+    private resumeWith;
+}
+//# sourceMappingURL=hosted-engine-runtime.d.ts.map

package/lib/types/driver-core/hosted-tool-vocabulary.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Projection of a hosted engine's tool vocabulary onto dsh's, plus the plan
+ * snapshot a hosted plan tool carries.
+ *
+ * The durable `tool/call` event is what the Web client's tool rows
+ * (`@deepseek-ai/dsh-client-ui-chat`'s tool Definition), the produced-files row
+ * and inline file links (`@deepseek-ai/dsh-client-ui-deliverables`'
+ * `mutationPath`), and the trajectory view read. Those consumers recognize only
+ * dsh's own tool names and argument shapes, while a hosted engine names its
+ * tools differently: Claude's `Write`/`Edit`/`Read`/`Bash`, Codex's
+ * `apply_patch`/`command_execution`, Kimi's title-cased `Bash`, Pi's
+ * `path`-keyed arguments. This module normalizes the event a driver appends
+ * while leaving the durable assistant message — and therefore the next step's
+ * serialized prompt — in the engine's own vocabulary. Session pairing is by
+ * callId, so the two spellings coexist.
+ *
+ * Only lossless projections are applied. A call whose arguments do not carry
+ * the dsh fields is passed through unchanged and simply renders as a generic
+ * row, so a new engine-side tool degrades instead of mis-rendering.
+ *
+ * Plan extraction is separate: dsh's todo panel is driven by the `todo/write`
+ * session event, not by the tool row, so a driver appends that event for the
+ * plan tool it recognizes.
+ *
+ * @module dsh-loop-engine/driver-core/hosted-tool-vocabulary
+ */
+/** A hosted loop engine id — the settings engine union without `in-process`. */
+export type HostedEngineId = 'claude-code' | 'codex' | 'pi' | 'kimi';
+/** One tool call projected into dsh's vocabulary for the durable `tool/call` event. */
+export interface NormalizedHostedToolCall {
+    /** dsh tool name when the projection recognizes the call, else the engine's own spelling. */
+    readonly name: string;
+    /** dsh-shaped arguments JSON when the projection rewrites them, else the engine's own string. */
+    readonly arguments: string;
+}
+/** One plan entry in the shape the `todo/write` event and the todo panel consume. */
+export interface HostedPlanTodo {
+    /** The task line, verbatim. */
+    readonly content: string;
+    /** Lifecycle state, restricted to dsh's three-state union. */
+    readonly status: 'pending' | 'in_progress' | 'completed';
+}
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        'todo/write': {
+            todos: {
+                content: string;
+                status: 'pending' | 'in_progress' | 'completed';
+            }[];
+        };
+    }
+}
+/**
+ * Project one hosted tool call onto dsh's `tool/call` vocabulary. The engine's
+ * own assistant-message block is untouched; only the event this returns is
+ * normalized, so the next step's serialized prompt keeps the engine's spelling.
+ * @param engine - the hosted engine the call came from.
+ * @param name - the engine's own tool name.
+ * @param argumentsJson - the engine's arguments JSON, verbatim.
+ * @returns the dsh name and (when reshaped) dsh-shaped arguments.
+ */
+export declare function normalizeHostedToolCall(engine: HostedEngineId, name: string, argumentsJson: string): NormalizedHostedToolCall;
+/**
+ * Read the whole todo list a hosted plan tool wrote, in the shape the
+ * `todo/write` session event carries.
+ * @param engine - the hosted engine the call came from.
+ * @param name - the engine's own tool name.
+ * @param argumentsJson - the engine's arguments JSON, verbatim.
+ * @returns the plan entries (possibly empty) when the call is a plan write, else `undefined`.
+ */
+export declare function planTodosOfHostedTool(engine: HostedEngineId, name: string, argumentsJson: string): readonly HostedPlanTodo[] | undefined;
+//# sourceMappingURL=hosted-tool-vocabulary.d.ts.map

package/lib/types/driver-core/model-handover.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The dsh endpoint, protocol, and credential a hosted engine is handed when a
+ * session selects a REAL dsh model — the second half of the model handover
+ * whose first half (`session-model.ts`) only carries the model name.
+ *
+ * A hosted engine owns its model natively, and today it also owns the endpoint
+ * and the credential: each CLI keeps its own provider table. That is why
+ * "handing over a dsh model" used to mean "the engine can find that model name
+ * in its own configuration". This module answers the other question — what
+ * `baseURL`, wire protocol, and credential does the session's selection name in
+ * dsh's own settings — so each driver can point its engine at dsh's endpoint.
+ *
+ * The two reads are the host's own seams, deliberately:
+ *
+ *  - the provider → settings address mapping comes from the llm registry's
+ *    configurable-provider directory (`LlmRuntime.listConfigurableProviders`,
+ *    `packages/llm/llm/src/types.ts` `LlmConfigurableProvider`). That directory
+ *    is the authoritative answer to "which namespace, at which path, configures
+ *    provider X": `llm-pi-ai` maps a route to `['providers', route]` under
+ *    `llm-pi-ai`, `llm-deepseek` maps its one route to the whole `llm-deepseek`
+ *    section. Reading the directory rather than hardcoding namespaces is what
+ *    keeps this plugin from inventing a mapping the deployment did not make.
+ *  - the credential is resolved through the credentials seam, because the
+ *    profile stores an `apiKeyEnv` NAME and its value lives in the harness's
+ *    credential store, never in the process environment
+ *    (`packages/bundle/base/cordis.patch.yml`).
+ *
+ * Both reads are reads of ANOTHER plugin's private namespace, and no contract in
+ * the harness guarantees their shape. Every step is therefore defensive: a shape
+ * this module does not recognize resolves to `undefined` (the engine keeps its
+ * own configuration, exactly today's behavior) and one warning, never a throw
+ * and never a guess. The warning names the provider and the model, never a
+ * credential.
+ *
+ * @module dsh-loop-engine/driver-core/model-handover
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionModelOverride } from './session-model.ts';
+/**
+ * The endpoint facts one hosted engine needs to speak to the dsh model a session
+ * selected: the model id, the base URL, dsh's wire protocol name for it, and the
+ * resolved credential value.
+ *
+ * The protocol is carried verbatim (`llm-pi-ai` values such as
+ * `anthropic-messages`, `openai-completions`, `openai-responses`), because each
+ * engine translates it into its own vocabulary — and an engine whose protocol
+ * the endpoint does not speak is left to fail loud on its own request rather
+ * than being silently given a different endpoint.
+ */
+export interface DshModelHandover {
+    /** Provider route the selection named (the engine's provider key). */
+    readonly provider: string;
+    /** Provider-owned model id the selection named. */
+    readonly model: string;
+    /** Endpoint base as dsh configured it. */
+    readonly baseURL: string;
+    /** dsh's wire protocol name for this endpoint. */
+    readonly api: string;
+    /** The resolved credential value; never logged, never evented. */
+    readonly apiKey: string;
+}
+/**
+ * One entry of the host llm registry's configurable-provider directory
+ * (`LlmConfigurableProvider`), narrowed to the address fields this module reads.
+ */
+export interface ConfigurableProviderAddress {
+    /** Provider route key the entry activates when configured. */
+    readonly provider: string;
+    /** User-settings namespace whose section configures this provider. */
+    readonly settingsNs: string;
+    /** Path from that section root to this provider's profile; empty when the section IS the profile. */
+    readonly settingsPath: readonly string[];
+}
+/**
+ * The host llm registry (`ctx.llm`), as this module uses it.
+ *
+ * `listConfigurableProviders` is optional: a minimal profile may serve the
+ * registry without the directory, and an older harness may predate it. A
+ * missing directory is "cannot map", not an error — the engine keeps its own
+ * configuration.
+ */
+export interface LlmDirectoryService {
+    /** Every provider route an adapter can activate through configuration. */
+    listConfigurableProviders?(): readonly ConfigurableProviderAddress[];
+}
+/** The host settings service (`ctx.settings`), as this module uses it. */
+export interface SettingsReader {
+    /** Read one registered namespace's resolved value. */
+    get?(ns: string): unknown;
+}
+/** The host credentials seam (`ctx.credentials`), as this module uses it. */
+export interface CredentialsService {
+    /** Resolve one reference (an environment-variable NAME) to its current value. */
+    resolve(ref: string): Promise<{
+        readonly value: string;
+    } | undefined>;
+}
+/**
+ * Resolve the session's own model selection into the endpoint triple a hosted
+ * engine can dial, or `undefined` to leave the engine to its own configuration.
+ *
+ * `undefined` is the answer in exactly two situations: the selection names no
+ * real dsh model ({@link SessionModelOverride} is already `undefined` for the
+ * hosted seat), or a real model whose endpoint/credential dsh does not disclose
+ * to this read. The second case warns once — it is a deployment-shape gap the
+ * operator can see and fix, not a silent downgrade.
+ *
+ * Called fresh on every step by each driver, so a model or provider picked
+ * mid-conversation reaches the engine's next request rather than being frozen
+ * when the agent was built.
+ * @param ctx - the driver's context, carrying the llm/settings/credentials seams.
+ * @param override - the session's dsh model selection, already judged by `sessionModelOverrideOf`.
+ * @returns the resolvable endpoint triple, or undefined to inject nothing.
+ */
+export declare function resolveModelHandover(ctx: Context, override: SessionModelOverride | undefined): Promise<DshModelHandover | undefined>;
+//# sourceMappingURL=model-handover.d.ts.map

package/lib/types/driver-core/ownership.d.ts

@@ -1,11 +1,12 @@
 /**
- * Shared factory ownership and abort-race machinery for the hosted engines.
+ * Shared engine ownership and abort-race machinery for the hosted engines.
  * All four loop drivers (Claude Code, Codex, Pi, Kimi Code) run the same
- * lifecycle: exactly one factory owns the AgentFactory slot, every live
- * agent's teardown is tracked until it settles, and setup awaits are raced
- * against a fused abort signal. These helpers are engine-free — they only
+ * lifecycle: one runtime per engine owns that engine's live agents, every
+ * live agent's teardown is tracked until it settles, and setup awaits are
+ * raced against a fused abort signal. The process-wide AgentFactory slot is
+ * the router's, not any engine's; these helpers are engine-free — they only
  * touch the fiber state, the session id type, and an AbortController — so the
- * loop modules share them verbatim.
+ * engine modules share them verbatim.
  *
  * @module dsh-loop-engine/driver-core/ownership
  */

package/lib/types/driver-core/prompt.d.ts

@@ -5,11 +5,43 @@
  * exact projection, so a later replay of the same log derives the identical
  * prompt (Model-visible ⟺ logged bridge).
  *
+ * A step whose live request is an engine slash command is the one exception to
+ * the transcript framing: {@link engineSlashPrompt} sends that command line
+ * verbatim, because the engines only recognize their own commands at the head
+ * of the prompt. It is still derived from the log alone, so the guarantee
+ * holds.
+ *
  * @module dsh-loop-engine/driver-core/prompt
  */
 import type { Message } from '@deepseek-ai/dsh-llm';
 /** Model-facing stand-in for an image block that the hosted engines cannot consume as bytes. */
 export declare const OMITTED_IMAGE_TEXT = "[image omitted: the driver does not transcribe images; read the file when a path is available]";
+/**
+ * The engine's own slash-command line to send as this step's entire prompt, or
+ * `undefined` when the step is an ordinary conversational step.
+ *
+ * Every hosted engine expands a slash command only when the text handed to it
+ * *starts* with `/` — Kimi's ACP adapter parses the first prompt block, Claude
+ * Code's local-command dispatch and Pi's input expansion both test the leading
+ * character of the message string. The serialized transcript never satisfies
+ * that (it opens with `<user>`), so a forwarded `/status` reaches the model as
+ * prose instead of the engine's own command surface. This helper lets a driver
+ * recognize the case and send the command line verbatim, with no transcript
+ * framing and no replay history: a slash command is a control line for the
+ * engine, not conversation for the model.
+ *
+ * The live request is the last derived message, so a step whose trailing
+ * message is a bare command line is a command step. A trailing skill-injection
+ * message (the `/name` skill gesture the drivers materialize as its own user
+ * message) displaces it and keeps the step on the transcript path.
+ *
+ * The returned line is a pure function of the log prefix, so the step stays
+ * replayable: the same log derives the same prompt.
+ * @param messages - derived history, oldest first, as returned by
+ *   `Session.deriveMessages()` at step time.
+ * @returns the raw command line, or `undefined` for an ordinary step.
+ */
+export declare function engineSlashPrompt(messages: readonly Message[]): string | undefined;
 /**
  * Serialize a derived conversation history into the prompt text of one hosted
  * query. The last message is the live user request that triggered the step;