dsh-loop-engine 0.1.5-rc3 → 0.1.5-rc5

package/lib/types/driver-core/session-lifetime.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The session-scoped half of one published hosted transaction: the session's
+ * entry in the store, and the write handle that stores its events.
+ *
+ * Ownership is ONE object rather than two closure variables because an engine
+ * swap MOVES it. A hot swap replaces a session's agent while the session itself
+ * stays live: the retiring machine hands its lifetime to the successor instead
+ * of releasing it, and the successor releases it later exactly as the agent that
+ * entered the session would have. Releasing it at the handover point would emit
+ * `session/disposed`, which the browser half reads as the session being gone —
+ * its session list drops the row, its composer renders "session unavailable",
+ * and the conversation view falls back to the workspace picker — so a live
+ * session would be torn out from under the page attached to it.
+ *
+ * The two release steps are separate operations because their ORDER around the
+ * agent registry's own release is load-bearing: `agent/disposed` is published
+ * after driver quiescence and BEFORE the session is detached (the event's
+ * contract in `@deepseek-ai/dsh-agent`), and the write handle closes before the
+ * store attachment is released so its buffered closing events are drained
+ * durably. Users of this type therefore close the handle, detach the agent, then
+ * leave the store.
+ *
+ * Neither step needs a memo of its own: `SessionHandle.close()` is idempotent by
+ * contract, and the detacher `SessionsService.enter` returns is single-shot.
+ *
+ * @module dsh-loop-engine/driver-core/session-lifetime
+ */
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { SessionHandle } from '@deepseek-ai/dsh-session-persistence';
+/**
+ * One live session's lifetime resources, owned by whichever agent drives it.
+ */
+export declare class SessionLifetime {
+    /** The live session these resources belong to. */
+    readonly session: Session;
+    /** The write handle this lifetime owns, or `undefined` when no persistence backend is mounted. */
+    private readonly handle;
+    /** The store's detacher; `undefined` until the entry is bound by the transaction that entered the session. */
+    private detach;
+    /**
+     * @param session - the live session whose entry and write handle these are.
+     * @param handle - the write handle the transaction acquired, if a backend is mounted.
+     */
+    constructor(session: Session, handle: SessionHandle | undefined);
+    /**
+     * Whether the session's store entry is already held: true for a lifetime a
+     * retiring machine handed over, false for one whose transaction still has to
+     * enter the session it prepared.
+     */
+    get entered(): boolean;
+    /**
+     * Bind the store entry this lifetime owns. Called once, by the transaction
+     * that enters the session; a joined session's entry is already bound.
+     * @param detach - the detacher the session's own `enter` returned.
+     */
+    bind(detach: () => void): void;
+    /** Drain and close the write handle — the durability barrier that precedes leaving the store. */
+    closeHandle(): Promise<void>;
+    /** Remove the session from the store, publishing its paired disposal exactly once. */
+    leaveStore(): void;
+}
+//# sourceMappingURL=session-lifetime.d.ts.map

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

@@ -0,0 +1,82 @@
+/**
+ * The dsh model selection a hosted engine is handed, and the ONE judgement that
+ * decides it.
+ *
+ * A session's model seat is the harness's own per-session fact: the host writes
+ * a `model/selection` event when the user picks a model, and derives the
+ * session's selection from the newest pending selection, else the logged
+ * `request/header` (`packages/api/session-controller/src/agent.ts`,
+ * `selectionFor`). A hosted engine owns its model natively, but it can still be
+ * handed a real dsh model when the session selected one — that is what this
+ * module answers.
+ *
+ * Three cases, decided once here and consumed by all four drivers:
+ *
+ *  - NO selection, or one whose provider is a hosted engine route label
+ *    ({@link isHostedProviderRoute}: today's shared `external`, or a label an
+ *    earlier build logged) → `undefined`. The engine keeps its own native
+ *    default or the model the deployment pinned in its composition; nothing is
+ *    sent, so the engine is not asked a question it never had an opinion on.
+ *  - a REAL dsh model (any other provider) → `{ provider, model }`. Each engine
+ *    renders that into its own interface: Pi's `--model <provider>/<model>`,
+ *    Claude Code's `Options.model`, Codex's `thread/start` `model`, and Kimi's
+ *    ACP `session/set_model`. Whether the engine can actually serve the model is
+ *    the engine's own business: a refusal is reported, never swallowed.
+ *
+ * The read is the host's own ({@link currentSelection}), so the value an engine
+ * gets is the value the host would install for the session — and it is taken
+ * fresh on every step, because a session's model can change mid-conversation.
+ *
+ * @module dsh-loop-engine/driver-core/session-model
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { SessionModelSelection, SessionProjectionsService } from './host-servers.ts';
+/** The model a session's own selection asks a hosted engine to run. */
+export interface SessionModelOverride {
+    /** Provider route the selection names, in the engine's own provider vocabulary. */
+    readonly provider: string;
+    /** Provider-owned model id the selection names. */
+    readonly model: string;
+}
+/**
+ * The selection the host will use for this session, by the host's own read
+ * (`ApiSessionAgentController.selectionFor`): a pending selection — one
+ * appended, not yet consumed by a matching recorded request — outranks the
+ * logged header, and the header answers when nothing is pending.
+ *
+ * A deployment with no session-projection registry is not an error: the read
+ * simply skips the pending half and answers from the logged header, exactly as
+ * a session whose log carries only a header would.
+ * @param session - the session whose selection is being read.
+ * @param projections - the host session-projection registry, when composed.
+ * @returns the current selection, or undefined when the log records none.
+ */
+export declare function currentSelection(session: Session, projections: SessionProjectionsService | undefined): SessionModelSelection | undefined;
+/**
+ * The model one hosted engine should be handed for this selection, or
+ * `undefined` to leave the engine to its own default (or the deployment's pin).
+ *
+ * The provider is the whole test: a hosted engine route label — the shared
+ * `external` this plugin serves as a placeholder, or a per-engine label an
+ * earlier build logged — means "the engine decides", not a model to send. Any
+ * other provider is a real dsh model, and the plugin passes it through rather
+ * than second-guessing whether the engine can serve it: a rejection is the
+ * engine's to report, and this plugin surfaces it.
+ * @param selection - the session's current selection, or undefined when none.
+ * @returns the model to hand over, or undefined to send nothing.
+ */
+export declare function sessionModelOverride(selection: SessionModelSelection | undefined): SessionModelOverride | undefined;
+/**
+ * The model override for one session, read live from its log and judged by
+ * {@link sessionModelOverride}.
+ *
+ * The four drivers' single entry: each calls this at the top of every step, so a
+ * model picked mid-conversation lands on the engine's next request rather than
+ * being frozen when the agent was built.
+ * @param ctx - the driver's context, carrying the session-projection registry.
+ * @param session - the session whose selection is being resolved.
+ * @returns the model to hand the engine, or undefined to send nothing.
+ */
+export declare function sessionModelOverrideOf(ctx: Context, session: Session): SessionModelOverride | undefined;
+//# sourceMappingURL=session-model.d.ts.map

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

@@ -12,8 +12,14 @@ import type { Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session';
 import type { Context } from '@deepseek-ai/cordis';
 import type { ResolvedConfig } from './types.ts';
 import { DriverInbox } from '../driver-core/inbox.ts';
-/** Provider route label used for logged header snapshots and message provenance. */
-export declare const PROVIDER = "claude-code";
+import { type SpawnCapability } from './sdk.ts';
+/**
+ * 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 Claude Code. */
 export declare class ClaudeCodeAgent implements Agent {
     private loopCtx;
@@ -21,6 +27,13 @@ export declare class ClaudeCodeAgent implements Agent {
     readonly options: AgentOptions;
     readonly session: Session;
     private readonly config;
+    /**
+     * Process-spawn capability handed down from the engine, which resolves it
+     * from the host's subprocess service. Held as a capability rather than read
+     * off the context because a service PROPERTY read requires the reading
+     * fiber to have injected it, and this agent's context is the engine's.
+     */
+    private readonly spawn;
     readonly inbox: DriverInbox;
     private phase;
     private activityDone;
@@ -44,7 +57,14 @@ export declare class ClaudeCodeAgent implements Agent {
      * usage record is only meaningful while one step holds the whole query.
      */
     private rotated;
-    constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedConfig);
+    constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedConfig, 
+    /**
+     * Process-spawn capability handed down from the engine, which resolves it
+     * from the host's subprocess service. Held as a capability rather than read
+     * off the context because a service PROPERTY read requires the reading
+     * fiber to have injected it, and this agent's context is the engine's.
+     */
+    spawn: SpawnCapability);
     get status(): AgentStatus;
     /** Commit a phase and publish its externally visible status transition. */
     private setPhase;

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

@@ -1,9 +1,9 @@
 /**
- * Claude Code loop engine module: hosts the AgentFactory that drives every
- * session through the official Claude Agent SDK, one stateless query per dsh
- * step, with the durable session log as the sole source of model context.
- * dsh-loop-engine constructs this factory when the Claude Code engine is
- * selected; this module is a library, not a Cordis plugin entry.
+ * Claude Code loop engine module: drives every session it is handed through
+ * the official Claude Agent SDK, one stateless query 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 recorded agent
+ * preset; this module is a library, not a Cordis plugin entry.
  *
  * @module dsh-loop-engine/engine-claude
  */
@@ -12,8 +12,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 { ClaudeCodeAgent } from './agent.ts';
+import { type SpawnCapability } from './sdk.ts';
 import type { ClaudeCodePermissionMode, ResolvedConfig } from './types.ts';
-import { HostedLoopFactory } from '../driver-core/hosted-loop-factory.ts';
+import { HostedEngineRuntime } from '../driver-core/hosted-engine-runtime.ts';
 /** Deployment-selectable non-interactive Claude Code permission modes. */
 export declare const CLAUDE_CODE_PERMISSION_MODES: readonly ClaudeCodePermissionMode[];
 /** Deployment-owned configuration for the Claude Code loop plugin. */
@@ -31,7 +32,7 @@ export interface Config {
     permissionMode?: ClaudeCodePermissionMode;
     /** Explicit environment entries layered over the credential-scrubbed parent environment. */
     env?: Record<string, string>;
-    /** Model label for the logged request header; Claude Code native settings own the actual model. */
+    /** Model passed to each query (`Options.model`, overridden by the session's own pick); also the request-header label. Claude Code native settings own the model when omitted. */
     model?: string;
     /** Grace in milliseconds for Claude Code process-tree termination. */
     disposeGraceMs?: number;
@@ -40,21 +41,21 @@ export interface Config {
 }
 /** Schema of the Claude Code loop plugin configuration. */
 export declare const Config: z<Config>;
-/** Host-face ctx key for the Claude Code loop service. */
+/** Host-face ctx key this engine's runtime is registered under. */
+export declare const CLAUDE_CODE_ENGINE_LABEL = "agentLoopClaudeCode";
 declare module '@deepseek-ai/cordis' {
     interface Context {
         agentLoopClaudeCode: ClaudeCodeLoop;
     }
 }
 /**
- * Concrete AgentFactory and driver service of the Claude Code 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 Claude Code 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 ClaudeCodeLoop extends HostedLoopFactory<ResolvedConfig, ClaudeCodeAgent> {
-    /** Services the loop resolves through its own fiber; blessed identically to the package-level entry inject. */
-    static inject: string[];
+export declare class ClaudeCodeLoop extends HostedEngineRuntime<ResolvedConfig, ClaudeCodeAgent> {
+    /** Process-spawn capability handed to every agent, sandboxed by the subprocess seam. */
+    readonly spawn: SpawnCapability;
     constructor(ctx: Context, config: Config);
     /** Construct the Claude Code driver for one prepared session. */
     protected buildAgent(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session): ClaudeCodeAgent;

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

@@ -19,8 +19,13 @@ import type { Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session';
 import type { Context } from '@deepseek-ai/cordis';
 import type { ResolvedConfig } from './types.ts';
 import { DriverInbox } from '../driver-core/inbox.ts';
-/** Provider route label used for logged header snapshots and message provenance. */
-export declare const PROVIDER = "codex";
+/**
+ * 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 Codex. */
 export declare class CodexAgent implements Agent {
     private loopCtx;
@@ -59,8 +64,22 @@ export declare class CodexAgent implements Agent {
     private beginSegment;
     /** Lazily created app-server client, reused across steps and released on scope teardown. */
     private appServer;
+    /**
+     * The spawn configuration (`argv` + `env`) the cached client was built from.
+     * Codex's endpoint lives in the child's own command line, so a handover change
+     * must respawn the child rather than reuse one configured for another endpoint.
+     */
+    private appServerConfig;
     constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedConfig);
-    /** Return the cached app-server client, spawning one on first use or after a dead process. */
+    /**
+     * Return the cached app-server client, spawning one on first use, after a dead
+     * process, or when the resolved dsh endpoint changed since the last spawn.
+     *
+     * A handover is codex's own `-c` configuration for a dsh provider, so a
+     * different endpoint (different provider, base URL, protocol, or credential)
+     * needs a different child — the config is fixed when the process starts.
+     * @param handover - the session's resolved dsh endpoint, or undefined to leave codex to its own configuration.
+     */
     private appServerClient;
     /**
      * Answer one server-initiated interaction. Approvals go through the dsh

package/lib/types/engine-codex/appserver/client.d.ts

@@ -35,8 +35,21 @@ export declare class AppServerClient {
     get closed(): boolean;
     /** Create a client by spawning `codex app-server`. */
     private constructor();
-    /** Spawn the pinned app-server dependency and initialize the client. */
-    static create(): Promise<AppServerClient>;
+    /**
+     * Spawn the pinned app-server dependency and initialize the client.
+     *
+     * `argv` appends the driver's own overrides to the bare `app-server`
+     * subcommand (codex's `-c key=value` configuration), and `env` layers the
+     * driver's explicit entries over the ambient environment — the child still
+     * needs `PATH` and, under a user's own codex setup, the ambient auth facts its
+     * configuration reads, so this is an overlay, not a replacement. Both default
+     * to nothing, which is the bare `codex app-server` the driver used before a
+     * dsh endpoint was ever handed over.
+     * @param argv - extra arguments after the `app-server` subcommand.
+     * @param env - explicit environment entries layered over the ambient one.
+     * @returns the initialized client.
+     */
+    static create(argv?: readonly string[], env?: NodeJS.ProcessEnv): Promise<AppServerClient>;
     /** Set the notification handler for streaming events. */
     onNotification(handler: NotificationHandler): void;
     /** Set the handler for server-initiated requests (e.g. approvals). */

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

@@ -1,9 +1,9 @@
 /**
- * Codex loop engine module: hosts the AgentFactory that drives every session
- * through the OpenAI Codex SDK, one stateless thread per dsh step, with the
- * durable session log as the sole source of model context. dsh-loop-engine
- * constructs this factory when the Codex engine is selected; this module is a
- * library, not a Cordis plugin entry. The Codex SDK spawns its own CLI binary
+ * Codex loop engine module: drives every session it is handed through the
+ * OpenAI Codex SDK, one stateless thread 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. The Codex SDK spawns its own CLI binary
  * (no spawn injection seam), so this loop deliberately does not inject the dsh
  * subprocess service.
  *
@@ -15,7 +15,7 @@ import type { AgentOptions } from '@deepseek-ai/dsh-agent';
 import type { Session, SessionId } from '@deepseek-ai/dsh-session';
 import { CodexAgent } from './agent.ts';
 import type { CodexApprovalPolicy, CodexSandboxMode, ResolvedConfig } from './types.ts';
-import { HostedLoopFactory } from '../driver-core/hosted-loop-factory.ts';
+import { HostedEngineRuntime } from '../driver-core/hosted-engine-runtime.ts';
 /** Codex CLI sandbox modes a deployment may pin. */
 export declare const CODEX_SANDBOX_MODES: readonly CodexSandboxMode[];
 /** Codex CLI approval policies a deployment may pin. */
@@ -38,26 +38,24 @@ export interface Config {
     approvalPolicy?: CodexApprovalPolicy;
     /** Explicit environment entries layered over the credential-scrubbed parent environment. */
     env?: Record<string, string>;
-    /** Model override for the SDK; Codex native settings own the model when omitted. */
+    /** Fallback model for the app-server thread, used when the session selects none; Codex native settings own the model when omitted. */
     model?: string;
 }
 /** Schema of the Codex loop plugin configuration. */
 export declare const Config: z<Config>;
-/** Host-face ctx key for the Codex loop service. */
+/** Host-face ctx key this engine's runtime is registered under. */
+export declare const CODEX_ENGINE_LABEL = "agentLoopCodex";
 declare module '@deepseek-ai/cordis' {
     interface Context {
         agentLoopCodex: CodexLoop;
     }
 }
 /**
- * Concrete AgentFactory and driver service of the Codex 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 Codex 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 CodexLoop extends HostedLoopFactory<ResolvedConfig, CodexAgent> {
-    /** Services the loop resolves through its own fiber; blessed identically to the package-level entry inject. */
-    static inject: string[];
+export declare class CodexLoop extends HostedEngineRuntime<ResolvedConfig, CodexAgent> {
     constructor(ctx: Context, config: Config);
     /** Construct the Codex driver for one prepared session. */
     protected buildAgent(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session): CodexAgent;

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

@@ -0,0 +1,56 @@
+/**
+ * Codex's dialect for a dsh endpoint: the `codex app-server` configuration
+ * overrides and environment that point it at dsh's model.
+ *
+ * Codex resolves a custom endpoint through `model_providers.<id>` in its own
+ * `config.toml` (`name`, `base_url`, `wire_api`, and an `env_key` naming the
+ * variable the credential is read from), and `codex app-server` accepts those as
+ * `-c key=value` overrides — so the handover needs no edit of `~/.codex`. The
+ * credential travels in the child's environment under {@link CODEX_DSH_API_KEY_ENV},
+ * which the `env_key` names.
+ *
+ * `name` is not optional in practice even though the CLI's own docs describe it
+ * as display metadata: codex 0.149.1 (the version this plugin pins) refuses to
+ * load a provider whose `name` is empty — "provider name must not be empty in
+ * `model_providers`" — and that config error kills `app-server` on startup, which
+ * the driver can only report as "process exited unexpectedly". Omitting it looked
+ * correct and failed before any request was ever sent, so every override this
+ * module builds carries it (verified against the pinned binary).
+ *
+ * Codex speaks only OpenAI's `responses` wire as of the version this plugin pins
+ * (0.149.1 dropped `chat`). A dsh protocol with no codex equivalent (Anthropic
+ * Messages, and now OpenAI Chat Completions) is NOT guessed: `wire_api` is
+ * omitted, so codex falls back to its own default wire and fails loud on the
+ * request — the honest outcome, since the plugin cannot make codex speak a
+ * protocol it does not implement. That default is `responses` as of 0.149.1: the
+ * request lands on `<baseURL>/responses`, which an Anthropic Messages or Chat
+ * Completions endpoint does not serve.
+ *
+ * @module dsh-loop-engine/engine-codex/model-handover
+ */
+import type { DshModelHandover } from '../driver-core/model-handover.ts';
+/** Provider id codex is configured with when dsh's endpoint is handed over. */
+export declare const CODEX_DSH_PROVIDER = "dsh";
+/** Environment variable codex reads the handed-over credential from. */
+export declare const CODEX_DSH_API_KEY_ENV = "DSH_LOOP_ENGINE_API_KEY";
+/** The `codex app-server` argv/env that hand one dsh endpoint over. */
+export interface CodexModelConfig {
+    /** `-c` overrides to append to the `app-server` subcommand. */
+    readonly argv: string[];
+    /** Environment the child needs to read the endpoint's credential. */
+    readonly env: Record<string, string>;
+}
+/**
+ * Translate one dsh endpoint handover into codex's `-c` overrides and the
+ * environment carrying the credential.
+ *
+ * The provider id ({@link CODEX_DSH_PROVIDER}) is a plugin-owned name: it exists
+ * only in this child's command line, so it cannot collide with a provider the
+ * user configured, and the model itself is still handed over as the thread's own
+ * `model` param. The provider's `name` repeats that id because codex rejects an
+ * empty one at config load, before any request is made.
+ * @param handover - the resolved dsh endpoint for the session's selection.
+ * @returns the argv entries and environment to spawn the app-server with.
+ */
+export declare function codexModelConfig(handover: DshModelHandover): CodexModelConfig;
+//# sourceMappingURL=model-handover.d.ts.map

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

@@ -83,6 +83,16 @@ export declare class AcpClient {
     initialize(): Promise<unknown>;
     /** Start a fresh ACP session and resolve to its session id. */
     newSession(cwd: string): Promise<string>;
+    /**
+     * Select the model for one ACP session. The agent answers with an error frame
+     * when it cannot serve the id, and {@link request} rejects on that frame — so
+     * an engine that refuses the model fails the step loud rather than silently
+     * running its own default.
+     * @param sessionId - the ACP session the model applies to.
+     * @param modelId - the model id to select.
+     * @returns the agent's response to `session/set_model`.
+     */
+    setModel(sessionId: string, modelId: string): Promise<unknown>;
     /** Prompt the agent in a session and resolve when the turn completes. */
     prompt(sessionId: string, text: string): Promise<unknown>;
     /** Cancel the active turn in a session (fire-and-forget). */

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

@@ -17,8 +17,13 @@ import type { Context } from '@deepseek-ai/cordis';
 import type { ResolvedConfig } from './types.ts';
 import { DriverInbox } from '../driver-core/inbox.ts';
 import type { KimiSpawnCapability } from './process.ts';
-/** Provider route label used for logged header snapshots and message provenance. */
-export declare const PROVIDER = "kimi";
+/**
+ * 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 Kimi Code. */
 export declare class KimiAgent implements Agent {
     private loopCtx;
@@ -44,6 +49,13 @@ export declare class KimiAgent implements Agent {
     private acp;
     /** The spawn spec the cached client was built from; a change forces a respawn. */
     private lastSpec;
+    /**
+     * The environment the last handover produced, memoized by its own content so
+     * an unchanged endpoint reuses ONE object: `specsEqual` compares environments
+     * by reference, and a fresh object per step would otherwise respawn the child
+     * every step.
+     */
+    private handoverEnvCache;
     constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedConfig, spawn: KimiSpawnCapability, bin: string);
     get status(): AgentStatus;
     /** Commit a phase and publish its externally visible status transition. */
@@ -107,6 +119,11 @@ export declare class KimiAgent implements Agent {
     private acpClient;
     /** Build the `kimi acp` argv/cwd/env for the persistent child. */
     private spawnSpec;
+    /**
+     * The child environment for one handover, memoized by content so an unchanged
+     * endpoint yields the SAME object across steps (see {@link handoverEnvCache}).
+     */
+    private handoverEnv;
     /** Run one `kimi acp` step for the current session history and map the streamed updates. */
     private step;
     /** Per-step accumulation state for streamed assistant blocks and tool calls. */

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

@@ -4,24 +4,28 @@
  * The dsh `commands` runtime executes a registered command locally — the line is
  * consumed and never reaches the model — so a command whose real processing
  * lives inside the Kimi engine must forward the raw line back to the agent, which
- * Kimi then expands (as far as the ACP prompt surface supports). Registering the
- * built-ins keeps them visible in the dsh web slash menu; unregistered `/lines`
- * pass through as user text, but the menu would hide the engine's command
- * surface.
+ * Kimi then expands natively. Registering the built-ins keeps them visible in
+ * the dsh web slash menu; unregistered `/lines` pass through as user text, but
+ * the menu would hide the engine's command surface.
  *
- * Kimi's slash commands are chiefly TUI controls (`/login`, `/provider`,
- * `/settings`, `/sessions`, `/tasks`, …) that the ACP prompt surface does not
- * expand the way an interactive TUI does; this bridge therefore registers the
- * subset that are meaningful to forward to the engine (session/mode/status and
- * the goal form). `skill:` commands are already carried by the dsh skill
- * injection seam and Kimi's own shorthand, so they are not duplicated here.
+ * The list below is exactly what the `kimi acp` command surface implements
+ * (verified against kimi 0.28.1, both by driving `session/prompt` directly and
+ * by reading the `available_commands_update` the child publishes): `compact`,
+ * `status`, `usage`, `mcp`, `tasks`, `help`. Everything else Kimi's TUI offers
+ * (`/login`, `/provider`, `/settings`, `/sessions`, `/clear`, `/plan`, …) is a
+ * TUI control the ACP surface does not implement — forwarding one answers
+ * `Unknown ACP command: /name.` — so none of them is registered. `skill:`
+ * commands are already carried by the dsh skill injection seam and Kimi's own
+ * shorthand, so they are not duplicated here.
  *
  * `model` is deliberately absent even though the CLI has it: the dsh web
  * client owns a `/model` contribution, and a same-named host command makes
  * `ui-commands` throw the whole command menu source away, leaving only the
- * skill group. `/goal` stays: the managed block disables dsh's `command-goal`
- * row for hosted engines, so the slot is free and the CLI's own goal mode
- * takes it over.
+ * skill group. `/goal` is absent too: the ACP surface implements no `/goal`, so
+ * registering one would only answer with an unknown-command error. Hosted
+ * sessions have no dsh `/goal` either — the engine preset they join strips the
+ * `command-goal` row (`src/preset.ts`, `STRIPPED_ROWS`) — so the command is
+ * simply not part of their menu.
  *
  * @module dsh-loop-engine/engine-kimi/commands
  */
@@ -35,6 +39,6 @@ import type { CommandDefinition, CommandInvocation, CommandResult } from '../com
  * @returns the command handler.
  */
 export declare function forwardKimiCommand(name: string): (invocation: CommandInvocation) => CommandResult;
-/** Kimi Code's built-in slash commands that make sense to forward to the engine. */
+/** Kimi Code's built-in slash commands that the ACP surface implements. */
 export declare const KIMI_COMMANDS: readonly CommandDefinition[];
 //# sourceMappingURL=commands.d.ts.map

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

@@ -1,10 +1,10 @@
 /**
- * Kimi Code loop engine module: hosts the AgentFactory that drives every
- * session through a persistent `kimi acp` child (Agent Client Protocol over
- * stdio), speaking one stateless `session/new` + `session/prompt` per dsh step,
- * with the durable session log as the sole source of model context.
- * dsh-loop-engine constructs this factory when the Kimi engine is selected; this
- * module is a library, not a Cordis plugin entry. Kimi has no host approval
+ * Kimi Code loop engine module: drives every session it is handed through a
+ * persistent `kimi acp` child (Agent Client Protocol over stdio), speaking one
+ * stateless `session/new` + `session/prompt` 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. Kimi has no host approval
  * callback, so tool approvals surfaced by ACP (`session/request_permission`) are
  * answered from the session's dsh approval knobs (an `ask` policy degrades to
  * denial); the whole child is spawned through the dsh subprocess seam — the only
@@ -21,12 +21,12 @@ import type { Session, SessionId } from '@deepseek-ai/dsh-session';
 import { KimiAgent } from './agent.ts';
 import type { KimiSpawnCapability } from './process.ts';
 import type { ResolvedConfig } from './types.ts';
-import { HostedLoopFactory } from '../driver-core/hosted-loop-factory.ts';
+import { HostedEngineRuntime } from '../driver-core/hosted-engine-runtime.ts';
 /** Grace in milliseconds for Kimi process-tree termination. */
 export declare const KIMI_DISPOSE_GRACE_MS = 3000;
 /** Deployment-owned configuration for the Kimi loop plugin. */
 export interface Config {
-    /** Model alias for the `kimi` child (`-m`); 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. */
     model?: string;
     /** Explicit environment entries passed to the `kimi` child. */
     env?: Record<string, string>;
@@ -35,21 +35,19 @@ export interface Config {
 }
 /** Schema of the Kimi loop plugin configuration. */
 export declare const Config: z<Config>;
-/** Host-face ctx key for the Kimi loop service. */
+/** Host-face ctx key this engine's runtime is registered under. */
+export declare const KIMI_ENGINE_LABEL = "agentLoopKimi";
 declare module '@deepseek-ai/cordis' {
     interface Context {
         agentLoopKimi: KimiLoop;
     }
 }
 /**
- * Concrete AgentFactory and driver service of the Kimi 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 Kimi Code 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 KimiLoop extends HostedLoopFactory<ResolvedConfig, KimiAgent> {
-    /** Services the loop resolves through its own fiber; blessed identically to the package-level entry inject. */
-    static inject: string[];
+export declare class KimiLoop extends HostedEngineRuntime<ResolvedConfig, KimiAgent> {
     /** One-shot spawn capability handed to every agent, sandboxed by the subprocess seam. */
     readonly spawn: KimiSpawnCapability;
     constructor(ctx: Context, config: Config);