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

package/lib/types/driver-acp/client.d.ts

@@ -0,0 +1,297 @@
+/**
+ * JSON-RPC 2.0 client for an ACP agent subprocess (Agent Client Protocol over
+ * stdio), shared by every ACP engine driver.
+ *
+ * The driver hands the client a process handle carrying its stdin/stdout/stderr
+ * (projected from the dsh subprocess seam). The client frames JSON-RPC 2.0
+ * records on a bare `\n` (via a byte decoder, tolerating a trailing `\r`),
+ * correlates request responses by `id`, dispatches every `session/update`
+ * notification to a buffered event stream, and answers the reverse-RPC
+ * `session/request_permission` requests the agent publishes. The child is
+ * long-lived (one per factory) and stepped over via `newSession` + `prompt`.
+ *
+ * ## What is per-ENGINE here, and what is not
+ *
+ * The framing, correlation and dispatch are protocol facts and identical for
+ * every ACP engine. Three things are NOT:
+ *
+ *   - the `protocolVersion` announced at `initialize`, which is a REGISTRY
+ *     DECLARATION (`capabilities.acpProtocolVersion`, default 1) rather than a
+ *     constant: three engines sharing one skeleton must not share one hardcoded
+ *     version, which is the protocol-drift risk this parameter removes;
+ *   - how a MODEL is selected (`session/set_model` on kimi,
+ *     `session/set_config_option` on grok and MiniMax Code), exposed as separate
+ *     methods so each driver calls the one its engine was measured to accept;
+ *   - the engine's name in diagnostics, which travels as `label` so a message
+ *     from a `grok agent stdio` child never says "kimi".
+ *
+ * @module dsh-loop-engine-allinone/driver-acp/client
+ */
+import type { AcpProcess, AcpSpawnCapability, AcpSpawnSpec } from './transport.ts';
+import { type AcpClientCapabilities, type AcpReverseHandlers } from './capabilities.ts';
+import { type AcpFrame, type AcpImageContent, type AcpPermissionOption, type AcpPermissionResponse, type AcpUpdate } from './types.ts';
+/** How the client answers one `session/request_permission`. */
+export type AcpPermissionHandler = (request: AcpFrame) => boolean | Promise<boolean>;
+/**
+ * The answerable options of one `session/request_permission` frame. The wire is
+ * untrusted, so entries without a usable `optionId` are dropped rather than
+ * echoed back.
+ * @param frame - the reverse-RPC request frame.
+ * @returns the options the client may answer with.
+ */
+export declare function permissionOptionsOf(frame: AcpFrame): readonly AcpPermissionOption[];
+/**
+ * Encode one approval decision as the ACP `RequestPermissionResponse` the agent
+ * correlates against the options it advertised. The agent reads a terminal
+ * *option*, never a boolean: an outcome it cannot resolve (or a response that
+ * fails to parse at all) is reported to the model as a user rejection, so a
+ * decision that no single option expresses becomes `cancelled` — the honest
+ * "this client has no answer". Kimi re-uses this RPC for its question and
+ * plan-review bridges, which offer one `allow_once` option per choice; picking
+ * one of those would answer a question no human was asked, so any ambiguous
+ * set (zero or several `allow_once`/`reject_once` candidates) cancels instead.
+ * `allow_once` is preferred over `allow_always` because the decision is re-read
+ * from the session knobs on every request: letting the agent cache a session
+ * grant would outlive a mid-session switch back to `ask`.
+ * @param approved - whether the driver approves the request.
+ * @param options - the options the agent advertised for this request.
+ * @returns the result payload to send back.
+ */
+export declare function permissionResponse(approved: boolean, options: readonly AcpPermissionOption[]): AcpPermissionResponse;
+/** Callback receiving every non-response event line. */
+export type AcpUpdateHandler = (update: AcpUpdate) => void;
+/**
+ * Per-engine facts the shared client needs, all of them data.
+ *
+ * Defaulted rather than required, so `new AcpClient(process)` keeps meaning
+ * "kimi, protocol version 1" — which is what the existing callers and tests
+ * construct.
+ */
+export interface AcpClientOptions {
+    /**
+     * The ACP protocol version this client announces at `initialize`.
+     *
+     * From the engine's registry row (`capabilities.acpProtocolVersion`), whose
+     * documented default is 1. A caller that pins nothing gets 1 — the version
+     * every engine on this fork's reference host was verified against.
+     */
+    readonly protocolVersion?: number;
+    /** The engine's name in diagnostics (`kimi`, `grok`, `minimaxcode`). */
+    readonly label?: string;
+    /**
+     * The reverse-RPC methods this client can answer, and how.
+     *
+     * Absent means "none": the client announces no client capabilities and answers
+     * every reverse request with `methodNotFound`, which is what the kimi driver has
+     * always done and remains a supported configuration. A driver that supplies
+     * `spawnTerminal` gets the `terminal` capability announced for it — the
+     * declaration is DERIVED from the handlers so the two cannot drift.
+     */
+    readonly handlers?: AcpReverseHandlers;
+}
+/**
+ * ACP client over one agent child. Created once per driver scope and reused
+ * across steps, matching the Pi RPC client's lifecycle.
+ */
+export declare class AcpClient {
+    private readonly process;
+    private readonly pending;
+    private readonly updateBuffer;
+    private updateWake;
+    private updateHandler;
+    private permissionHandler;
+    private sealed;
+    private nextId;
+    private readonly decoder;
+    private buffer;
+    /** The protocol version this client announces (registry-declared, default 1). */
+    private readonly protocolVersion;
+    /** The engine's name in diagnostics. */
+    private readonly label;
+    /** What this client can answer, and how (see {@link AcpClientOptions.handlers}). */
+    private readonly handlers;
+    /** Every terminal this client owns, so a disposed client cannot leak a process. */
+    private readonly terminals;
+    /** Monotonic id source for the terminals the agent creates. */
+    private nextTerminalId;
+    /** Whether this client was sealed or its process exited. */
+    get closed(): boolean;
+    /** Mount a client over an already-spawned ACP agent process. */
+    constructor(process: AcpProcess, options?: AcpClientOptions);
+    /**
+     * Create a client, spawning the ACP child through the supplied capability (or
+     * the default node spawn when none is given).
+     * @param spec - the argv/cwd/env the child should run with.
+     * @param spawn - optional process-spawn capability (the subprocess seam).
+     * @param options - the engine's declared protocol version and diagnostic label.
+     * @returns the connected client.
+     */
+    static create(spec: AcpSpawnSpec, spawn?: AcpSpawnCapability, options?: AcpClientOptions): AcpClient;
+    /** Register the event dispatch handler. */
+    onUpdate(handler: AcpUpdateHandler): void;
+    /** Register the permission-approval handler (reverse-RPC answers). */
+    onPermission(handler: AcpPermissionHandler): void;
+    /** Send one request and await the correlated response. */
+    request(method: string, params: unknown): Promise<unknown>;
+    /** Send a notification (no correlated response awaited). */
+    notify(method: string, params: unknown): void;
+    /**
+     * The client capabilities to announce, DERIVED from what this client can
+     * actually answer.
+     *
+     * Declaring a capability is a promise an agent plans around, so this never
+     * announces more than the handlers implement: no `spawnTerminal` means no
+     * `terminal: true`, and no `readTextFile` means no `fs.readTextFile`. A client
+     * built with no handlers announces nothing, which is the pre-bridge behavior.
+     * @returns the capability block for `initialize`.
+     */
+    clientCapabilities(): AcpClientCapabilities;
+    /**
+     * Open the protocol handshake, announcing the engine's DECLARED protocol
+     * version and the capabilities this client can honour.
+     * @returns the agent's `initialize` result.
+     */
+    initialize(): Promise<unknown>;
+    /**
+     * Authenticate with one of the methods the agent advertised at `initialize`.
+     *
+     * Part of the ACP flow rather than an engine extension: an agent that requires
+     * authentication refuses `session/new` until the client answers with the method
+     * id it published (`grok agent stdio` does exactly that — measured on this
+     * host; reproduce it with `scripts/probe/acp-handshake.mjs`).
+     * @param methodId - one `authMethods[].id` from the initialize result.
+     * @returns the agent's response to `authenticate`.
+     */
+    authenticate(methodId: string): Promise<unknown>;
+    /**
+     * Start a fresh ACP session and resolve to its session id.
+     * @param cwd - the session's working directory.
+     * @param extra - engine-specific `session/new` params (grok's `_meta`, for
+     *   example), merged over the two every engine takes.
+     * @returns the new session id.
+     */
+    newSession(cwd: string, extra?: Record<string, unknown>): Promise<string>;
+    /**
+     * Load (resume) an existing ACP session by id.
+     *
+     * Measured: `session/load` is accepted by MiniMax Code and advertised by grok
+     * (both answer `loadSession: true`). The driver itself replays the durable
+     * transcript and opens a fresh ACP session per step, so this exists for the
+     * probe and for a deployment that later wants engine-side session resume.
+     * @param sessionId - the session to load.
+     * @param cwd - the session's working directory.
+     * @returns the agent's response to `session/load`.
+     */
+    loadSession(sessionId: string, cwd: string): Promise<unknown>;
+    /**
+     * Select a session config option with the BARE value ACP's second-generation
+     * schema takes (`session/set_config_option` with `value: 'x'`).
+     *
+     * Measured on MiniMax Code 0.6.12: both `model` and `permissionMode` accept
+     * this spelling and answer `-32602 Invalid params` to the `{ value }` wrapper.
+     * @param sessionId - the ACP session the option applies to.
+     * @param configId - the option's id, as `session/new` advertised it.
+     * @param value - the new value (a string id, or a boolean for a boolean option).
+     * @returns the agent's response, which carries the updated option list.
+     */
+    setConfigOption(sessionId: string, configId: string, value: string | boolean): Promise<unknown>;
+    /**
+     * Select a session config option with the `{ value }` WRAPPER spelling, which
+     * Grok's own documentation shows.
+     *
+     * Its own method because the two spellings are mutually exclusive on the wire:
+     * an engine accepts one and rejects the other with `-32602 Invalid params`, so
+     * a driver tries the documented one and falls back — never a guess baked into
+     * a single call.
+     * @param sessionId - the ACP session the option applies to.
+     * @param configId - the option's id.
+     * @param value - the new string value.
+     * @returns the agent's response.
+     */
+    setConfigOptionValue(sessionId: string, configId: string, value: string): Promise<unknown>;
+    /**
+     * Switch the session's ACP MODE (`session/new` answers with `modes`).
+     *
+     * MiniMax Code advertises `default` and `plan` and accepts this call
+     * (measured). It is NOT the tool-permission switch — that is the engine's
+     * `permissionMode` config option — so the driver keeps the two apart.
+     * @param sessionId - the ACP session.
+     * @param modeId - one of the advertised mode ids.
+     * @returns the agent's response to `session/set_mode`.
+     */
+    setMode(sessionId: string, modeId: string): Promise<unknown>;
+    /**
+     * 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.
+     * @param sessionId - the ACP session to prompt.
+     * @param text - the serialized transcript, or a bare slash command.
+     * @param images - image blocks to carry after the text block; omitted or
+     *   empty leaves the request exactly the text-only shape.
+     * @returns the agent's response to `session/prompt`.
+     */
+    prompt(sessionId: string, text: string, images?: readonly AcpImageContent[]): Promise<unknown>;
+    /** Cancel the active turn in a session (fire-and-forget). */
+    cancel(sessionId: string): void;
+    /**
+     * Answer a pending `session/request_permission`.
+     * @param id - the reverse-RPC request id.
+     * @param response - the ACP outcome to answer with.
+     */
+    respondPermission(id: number, response: AcpPermissionResponse): void;
+    /** Consume every buffered update as an async generator. */
+    updates(): AsyncGenerator<AcpUpdate, void, void>;
+    /** Seal the client and request child termination. */
+    dispose(): void;
+    private feed;
+    /** Dispatch one parsed line: a response, an update notification, or a reverse-RPC request. */
+    private dispatch;
+    private settle;
+    private handlePermission;
+    /**
+     * Answer one client-side capability request (`fs/read_text_file`, `terminal/*`).
+     *
+     * A capability this client did not announce is still answered `methodNotFound`
+     * rather than guessed at: an agent that calls one anyway gets the same honest
+     * refusal it would get from a client that never claimed it.
+     * @param id - the reverse-RPC request id.
+     * @param method - the ACP method name.
+     * @param params - the request params.
+     */
+    private handleCapability;
+    /**
+     * Perform one capability request and return its ACP result payload.
+     * @param method - the ACP method name.
+     * @param params - the request params.
+     * @returns the result object to send back.
+     */
+    private capabilityResult;
+    /**
+     * The terminal id one capability frame names.
+     * @param params - the request params.
+     * @returns the id.
+     */
+    private terminalIdOf;
+    /**
+     * The live terminal one capability frame names.
+     * @param params - the request params.
+     * @returns the terminal.
+     */
+    private terminalOf;
+    /**
+     * Write one reverse-RPC answer (result or error).
+     * @param id - the request id being answered.
+     * @param result - the result payload.
+     * @param error - the error payload, when the request failed.
+     */
+    private writeResult;
+}
+//# sourceMappingURL=client.d.ts.map

package/lib/types/driver-acp/executable.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Finding an external CLI and launching it correctly, shared by the ACP engines.
+ *
+ * Two Windows-specific facts make "just spawn the name" wrong, and both were
+ * measured on this fork's reference host rather than assumed:
+ *
+ *   - an npm-installed CLI is a `mcode.cmd` / `grok.cmd` SHIM, and node's spawn
+ *     cannot execute a `.cmd` — `spawn('mcode', …)` fails with `ENOENT` while
+ *     `mcode --version` works in a shell. The shim has to go through
+ *     `cmd.exe /c`, or the package's own JS entrypoint has to be spawned under
+ *     `process.execPath`;
+ *   - a PATH lookup therefore has to consider `PATHEXT`, not just the bare name,
+ *     or it finds the extension-less shell script npm also writes (which the OS
+ *     cannot execute either).
+ *
+ * @module dsh-loop-engine-allinone/driver-acp/executable
+ */
+/**
+ * The argv prefix that launches one executable, accounting for what the resolved
+ * path actually IS.
+ *
+ * A `.js`/`.cjs`/`.mjs` file is a package entrypoint and runs under the CURRENT
+ * node (`process.execPath`), never directly (Windows answers `EFTYPE`/`ENOENT`);
+ * a `.cmd`/`.bat` shim goes through the command interpreter; anything else is a
+ * real executable and is spawned as itself.
+ * @param bin - the resolved executable or script path.
+ * @returns the argv prefix, ending in the file to run.
+ */
+export declare function execArgvPrefix(bin: string): string[];
+/**
+ * Resolve a bare command name against `PATH`, honouring `PATHEXT` on Windows.
+ *
+ * Written by hand rather than shelled out (`where`/`which`) on purpose: this runs
+ * inside the plugin's own process, where spawning a helper to answer a question
+ * about spawning would be its own failure mode.
+ * @param name - the command name, without an extension.
+ * @param env - the environment to read `PATH`/`PATHEXT` from.
+ * @returns the first existing match, or undefined when nothing matches.
+ */
+export declare function resolveOnPath(name: string, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Find one npm package's entrypoint under a global npm prefix.
+ *
+ * Both npm layouts are probed (the Windows prefix puts `node_modules` directly
+ * under it; a POSIX prefix keeps it under `lib`), because the plugin may be
+ * running under either and a wrong guess only costs one `existsSync`.
+ * @param prefix - an npm prefix, or the directory holding `node_modules`.
+ * @param pkg - the package name, scope included (`@minimax-ai/code`).
+ * @param entry - the file inside the package that starts the CLI (`cli.js`).
+ * @returns the entrypoint path when it exists.
+ */
+export declare function npmPackageEntry(prefix: string, pkg: string, entry: string): string | undefined;
+//# sourceMappingURL=executable.d.ts.map

package/lib/types/driver-acp/mapping.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Maps ACP `session/update` events to dsh session-log projections.
+ *
+ * Every ACP engine streams the same event vocabulary: incremental assistant text
+ * (`agent_message_chunk`), incremental thinking (`agent_thought_chunk`), a
+ * tool-call announcement (`tool_call`) and its progress/result updates
+ * (`tool_call_update`). Assistant text and thinking are Deltas; a tool update's
+ * content is a whole Snapshot that replaces the previous one. A tool call's
+ * identity arrives on the announcement but its input (`rawInput`) does not —
+ * only a later update carries it.
+ *
+ * This module is pure and engine-neutral: it classifies an update, extracts chunk
+ * deltas, and projects the tool-call identity/input/content/result so the agent
+ * can fold them into the durable log. The one shape it reads is the content-block
+ * nesting measured on the wire — `{ type: 'content', content: { type: 'text',
+ * text } }` for a tool card, `{ type: 'text', text }` for a message chunk — and a
+ * block type this build does not know is ignored rather than guessed at.
+ *
+ * @module dsh-loop-engine-allinone/driver-acp/mapping
+ */
+import type { ToolResultMessage } from '@deepseek-ai/dsh-llm';
+import type { AcpContentBlock, AcpToolCallExt, AcpToolCallStreamExt, AcpUpdate } from './types.ts';
+/** Whether the update is an incremental assistant text chunk. */
+export declare function isTextChunk(update: AcpUpdate): update is AcpUpdate & {
+    readonly sessionUpdate: 'agent_message_chunk';
+    readonly content: AcpContentBlock;
+};
+/** Whether the update is an incremental thinking chunk. */
+export declare function isThoughtChunk(update: AcpUpdate): update is AcpUpdate & {
+    readonly sessionUpdate: 'agent_thought_chunk';
+    readonly content: AcpContentBlock;
+};
+/** Whether the update announces a tool call. */
+export declare function isToolCall(update: AcpUpdate): update is AcpToolCallExt;
+/** Whether the update streams a tool call's progress/result. */
+export declare function isToolCallUpdate(update: AcpUpdate): update is AcpToolCallStreamExt;
+/** The delta text of a text/thinking chunk. */
+export declare function chunkDelta(update: AcpUpdate): string;
+/** The raw tool-call id (+ content index) as the wire carries it. */
+export declare function toolCallIdOf(update: AcpUpdate): string;
+/** The tool display name (`title`). */
+export declare function toolCallName(update: AcpUpdate): string;
+/**
+ * The tool call's real input as the JSON `arguments` string the durable
+ * `tool/call` carries, when the frame supplies it.
+ *
+ * The `tool_call` announcement never carries `rawInput`; a later
+ * `tool_call_update` does (measured against kimi 0.28.x: the execution-start
+ * frame, `status: 'in_progress'`). A call's arguments are therefore unknowable
+ * at announce time, and the driver logs the call only once an update supplies
+ * them — or when the call settles, whichever comes first.
+ * @param update - one tool-call announcement or update.
+ * @returns the arguments string, or `undefined` when the frame omits the field.
+ */
+export declare function toolRawInput(update: AcpToolCallExt | AcpToolCallStreamExt): string | undefined;
+/** Whether a tool stream status is settled (no longer streaming). */
+export declare function isToolSettledStatus(status: string): boolean;
+/** Whether a tool stream status denotes a failure. */
+export declare function isToolErrorStatus(status: string): boolean;
+/**
+ * The tool call's content as ONE update carries it: the joined text of its
+ * observed `{ type: 'content', content: { type: 'text', text } }` blocks.
+ *
+ * Kimi re-sends the call's whole content on every `tool_call_update` rather than
+ * streaming deltas (measured against 0.28.1: the string grows from the tool
+ * input's rendering to the final output), so this is a *snapshot* — callers
+ * replace with it, never append. `undefined` means the update carried no
+ * content field at all (nothing to replace), which is distinct from a present
+ * but empty one.
+ * @param update - one tool-call announcement or update.
+ * @returns the content snapshot, or `undefined` when the field is absent.
+ */
+export declare function toolContentText(update: AcpToolCallExt | AcpToolCallStreamExt): string | undefined;
+/** Project a completed tool call to a durable tool/result message. */
+export declare function toolResult(callId: string, text: string, isError: boolean): ToolResultMessage;
+//# sourceMappingURL=mapping.d.ts.map

package/lib/types/driver-acp/profile.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The engines' side of the shared ACP driver, as data plus four small hooks.
+ *
+ * `driver-acp/agent.ts` holds the whole turn/step machine, and this module is
+ * everything that varies between the engines that run on it. The split is the
+ * same one the registry makes for the driver TABLE (one row per engine, and a
+ * new engine adds no branch to shared code): a new ACP engine is a profile, not
+ * a copy of a 900-line driver.
+ *
+ * ## What is a hook here, and why
+ *
+ * Four engine facts are CALLS rather than data, because each is a conversation
+ * with the agent rather than a constant:
+ *
+ *   - {@link AcpEngineProfile.openSession} — grok refuses `session/new` until the
+ *     client authenticates, MiniMax Code does not;
+ *   - {@link AcpEngineProfile.selectModel} — kimi takes `session/set_model`,
+ *     both new engines take `session/set_config_option` (and the two do not even
+ *     agree on that call's parameter SHAPE);
+ *   - {@link AcpEngineProfile.handoverEnv} — only kimi can translate a dsh
+ *     endpoint into its own environment variables;
+ *   - {@link AcpEngineProfile.approve} — the approval fold is a policy, and an
+ *     engine whose own permission switch already bounds the tool may answer
+ *     differently.
+ *
+ * `protocolVersion` is deliberately DATA and comes from the engine's registry
+ * row (`capabilities.acpProtocolVersion`): the value announced at `initialize`
+ * used to be hardcoded in the shared client, which is exactly the protocol-drift
+ * risk three engines on one skeleton must not inherit.
+ *
+ * @module dsh-loop-engine-allinone/driver-acp/profile
+ */
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { DshModelHandover } from '../driver-core/model-handover.ts';
+import type { HostedEngineId } from '../engine-registry.ts';
+import type { AcpClient } from './client.ts';
+/**
+ * One ACP driver's configuration after defaults and load-time validation.
+ *
+ * Shared because every ACP engine resolves the same four facts; the engines'
+ * own `process.ts` modules own the EXECUTABLE, which is what actually differs and
+ * what the profile's `argv` consumes.
+ */
+export interface AcpResolvedConfig {
+    /** Model the session selects when it has none of its own; the engine decides when omitted. */
+    readonly model: string | undefined;
+    /** Explicit environment entries layered over the credential-scrubbed parent environment. */
+    readonly env: Record<string, string>;
+    /** The engine's CLI executable (or, for an npm-installed CLI, its entry path). */
+    readonly bin: string;
+    /**
+     * How long an idle session keeps its ACP child, in milliseconds; zero or less
+     * keeps it for the session's whole life. See `driver-core/idle-child.ts` for
+     * why the child, and not the agent, is what gets released.
+     */
+    readonly childIdleMs: number;
+}
+/** One ACP engine's protocol dialect, as the shared driver reads it. */
+export interface AcpEngineProfile {
+    /** The registry id, used for the engine's own tool-name vocabulary. */
+    readonly engine: HostedEngineId;
+    /** The engine's name in diagnostics and error messages (`kimi`, `grok`, `minimaxcode`). */
+    readonly label: string;
+    /** The `LlmError` code a step with no assistant output fails with. */
+    readonly errorCode: string;
+    /**
+     * The ACP protocol version announced at `initialize`.
+     *
+     * From the registry row's `capabilities.acpProtocolVersion`; every engine on
+     * this fork's reference host answered protocol version 1 to a client that
+     * announced 1, which is also the documented default.
+     */
+    readonly protocolVersion: number;
+    /** The argv that launches this engine's ACP server, `argv[0]` being the executable. */
+    readonly argv: (bin: string) => string[];
+    /** Whether the engine accepts image blocks in a prompt (measured per engine). */
+    readonly images: boolean;
+    /**
+     * Whether the session's dsh approval knobs approve a reverse-RPC permission
+     * request. Absent means the ACP default: approve everything except under an
+     * `ask` policy, which the unattended runtime answers with a denial.
+     */
+    readonly approve?: (session: Session) => boolean;
+    /**
+     * Select the model for one ACP session, in this engine's own dialect.
+     *
+     * Absent means the engine has no model selection on this surface at all, and
+     * the deployment's `model`/the session's pick is dropped rather than sent as a
+     * call the agent would reject.
+     */
+    readonly selectModel?: (client: AcpClient, sessionId: string, model: string) => Promise<void>;
+    /**
+     * Open one ACP session, including whatever handshake the engine requires first.
+     *
+     * Absent means the plain `session/new` every ACP engine answers.
+     */
+    readonly openSession?: (client: AcpClient, cwd: string, session: Session, initializeResult: unknown) => Promise<string>;
+    /**
+     * Translate a dsh endpoint handover into this engine's own environment.
+     *
+     * Absent means the engine owns its provider credential and there is nothing to
+     * hand over — the shared driver then never resolves a dsh endpoint for it.
+     */
+    readonly handoverEnv?: (handover: DshModelHandover) => Record<string, string>;
+    /**
+     * Whether this engine drives its tools THROUGH the client, and so needs the
+     * client-side capability bridges.
+     *
+     * Measured, and it is the whole reason this field exists: MiniMax Code runs its
+     * own tools and reports results (`rawOutput.details.execution.exitCode`), so it
+     * needs nothing from us. Grok Build asks the CLIENT to read files
+     * (`fs/read_text_file`) and run commands (`terminal/create`), so without these
+     * bridges every one of its tools fails. An engine that omits this gets no
+     * bridges and announces no capabilities — exactly the pre-bridge behavior.
+     */
+    readonly clientBridges?: readonly AcpClientBridge[];
+}
+/**
+ * One client-side capability bridge an engine needs.
+ *
+ * Declared as a name rather than a flag per capability so the set is explicit at
+ * the engine's own row, and so `tests/driver-acp/capabilities.spec.ts` can assert
+ * that a declared bridge is really implemented and announced.
+ */
+export type AcpClientBridge = 'readTextFile' | 'terminal';
+//# sourceMappingURL=profile.d.ts.map

package/lib/types/driver-acp/runtime.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The runtime half every ACP engine shares: one persistent child, one driver.
+ *
+ * Extracted from the kimi engine when two more ACP engines landed. It is the
+ * same machinery for all of them — hand the driver a spawn capability projected
+ * through the dsh subprocess seam (the only privilege boundary available) and
+ * let it construct the engine's agent per session. What differs per engine is
+ * the profile (the dialect) and the executable resolver, both of which that
+ * engine's own `process.ts`/`agent.ts` own.
+ *
+ * @module dsh-loop-engine-allinone/driver-acp/runtime
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AgentOptions } from '@deepseek-ai/dsh-agent';
+import type { Session, SessionId } from '@deepseek-ai/dsh-session';
+import { HostedEngineRuntime } from '../driver-core/hosted-engine-runtime.ts';
+import { AcpEngineAgent } from './agent.ts';
+import type { AcpEngineProfile, AcpResolvedConfig } from './profile.ts';
+import type { AcpSpawnCapability } from './transport.ts';
+export { acpSubprocessSpec, fromSubprocess } from './subprocess.ts';
+/**
+ * Creation/resume machinery for one ACP engine.
+ *
+ * A plain class, not a Cordis plugin: the process-wide AgentFactory slot belongs
+ * to the router, which delegates each session to the engine its preset names.
+ * The generic agent parameter is what lets an engine with its own driver class
+ * (kimi's `KimiAgent`) keep it while an engine that needs nothing beyond the
+ * shared body uses {@link AcpEngineAgent} directly.
+ */
+export declare abstract class AcpEngineRuntime<TAgent extends AcpEngineAgent = AcpEngineAgent> extends HostedEngineRuntime<AcpResolvedConfig, TAgent> {
+    protected readonly profile: AcpEngineProfile;
+    /** One-shot spawn capability handed to every agent, sandboxed by the subprocess seam. */
+    readonly spawn: AcpSpawnCapability;
+    /**
+     * @param ctx - the owning context; its fiber's unload tears every live agent down.
+     * @param label - effect-label prefix, e.g. `agentLoopKimi`.
+     * @param config - this engine's already-resolved configuration.
+     * @param profile - this engine's ACP dialect.
+     * @param disposeGraceMs - grace for process-tree termination through the seam.
+     */
+    constructor(ctx: Context, label: string, config: AcpResolvedConfig, profile: AcpEngineProfile, disposeGraceMs: number);
+    /** Construct the driver for one prepared session. */
+    protected abstract buildAgent(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session): TAgent;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/lib/types/driver-acp/subprocess.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Projection of one ACP spawn request onto the dsh subprocess seam.
+ *
+ * Its own module, apart from `./runtime.ts`, for a concrete reason: the seam types
+ * are type-only, so this file imports NO host service, and an engine's
+ * `process.ts` (argv + executable resolution) can therefore stay importable
+ * without the driver class — which is what lets `scripts/probe/smoke-acp.ts`
+ * exercise a real dialect against a real CLI in a process that has no dsh
+ * composition at all.
+ *
+ * @module dsh-loop-engine-allinone/driver-acp/subprocess
+ */
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+import type { AcpProcess, AcpSpawnSpec } from './transport.ts';
+/** Project one driver spawn request onto the dsh subprocess seam. */
+export declare function acpSubprocessSpec(spec: AcpSpawnSpec, graceMs: number): SubprocessSpawnSpec;
+/** Project a dsh subprocess handle onto the ACP process transport. */
+export declare function fromSubprocess(handle: SubprocessHandle): AcpProcess;
+//# sourceMappingURL=subprocess.d.ts.map