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

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

@@ -0,0 +1,24 @@
+/**
+ * Grok Build's loop Agent: the shared ACP body with the dialect in `./profile.ts`.
+ *
+ * The class is this engine's published driver shape (and the seam a
+ * grok-specific behaviour would land on); the dialect itself — argv, protocol
+ * version, model selection, session handshake — lives in `./profile.ts`, which
+ * imports no host service so it can be exercised by `scripts/probe/smoke-acp.ts`
+ * against the real CLI.
+ *
+ * @module dsh-loop-engine-allinone/engine-grok/agent
+ */
+import type { AgentOptions } from '@deepseek-ai/dsh-agent';
+import type { Session, SessionId } from '@deepseek-ai/dsh-session';
+import type { Context } from '@deepseek-ai/cordis';
+import type { AcpResolvedConfig } from '../driver-acp/profile.ts';
+import type { AcpSpawnCapability } from '../driver-acp/transport.ts';
+import { AcpEngineAgent } from '../driver-acp/agent.ts';
+import { grokProfile } from './profile.ts';
+export { grokProfile };
+/** Grok Build's loop Agent: the shared ACP body with the profile's dialect. */
+export declare class GrokAgent extends AcpEngineAgent {
+    constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: AcpResolvedConfig, spawn: AcpSpawnCapability, bin?: string);
+}
+//# sourceMappingURL=agent.d.ts.map

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

@@ -0,0 +1,61 @@
+/**
+ * Grok Build loop engine module: drives every session it is handed through a
+ * persistent `grok agent stdio` 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.
+ *
+ * Everything below the dialect is the shared ACP runtime
+ * (`driver-acp/runtime.ts`); grok contributes its argv, its protocol version (from
+ * the registry row) and the `authenticate`-then-`session/new` handshake its own
+ * ACP server requires.
+ *
+ * @module dsh-loop-engine-allinone/engine-grok
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { AgentOptions } from '@deepseek-ai/dsh-agent';
+import type { Session, SessionId } from '@deepseek-ai/dsh-session';
+import { AcpEngineRuntime } from '../driver-acp/runtime.ts';
+import { GrokAgent } from './agent.ts';
+import type { AcpResolvedConfig } from '../driver-acp/profile.ts';
+/** Deployment-owned configuration for the Grok Build engine. */
+export interface Config {
+    /** Model sent per ACP session (`session/set_config_option`) when the session selects none. */
+    model?: string;
+    /**
+     * Explicit environment entries passed to the child.
+     *
+     * Usually empty on purpose: Grok reads its own `~/.grok/auth.json` (or
+     * `XAI_API_KEY`) from the INHERITED environment, and `GROK_HOME` is how a
+     * deployment points it at a second profile.
+     */
+    env?: Record<string, string>;
+    /** The `grok` executable (or its npm shim); the vendor install location, then PATH, when not pinned. */
+    bin?: string;
+    /** Idle window in milliseconds before a session's ACP child is shut down; zero or less keeps it. */
+    childIdleMs?: number;
+}
+/** Schema of the Grok Build engine configuration. */
+export declare const Config: z<Config>;
+/** Resolve the driver configuration at the plugin config boundary. */
+export declare function resolveConfig(config: Config): AcpResolvedConfig;
+/** Host-face ctx key this engine's runtime is registered under. */
+export declare const GROK_ENGINE_LABEL = "agentLoopGrok";
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        agentLoopGrok: GrokLoop;
+    }
+}
+/**
+ * Creation/resume machinery for the Grok Build 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 GrokLoop extends AcpEngineRuntime<GrokAgent> {
+    constructor(ctx: Context, config: Config);
+    /** Construct the Grok ACP driver for one prepared session. */
+    protected buildAgent(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session): GrokAgent;
+}
+//# sourceMappingURL=loop.d.ts.map

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

@@ -0,0 +1,46 @@
+/**
+ * Grok Build process projection: where the `grok` executable is, and the argv that
+ * starts its ACP server.
+ *
+ * Measured and documented facts this file encodes (see
+ * Grok's shipped user guide, and the frames `scripts/probe/acp-handshake.mjs` dumps):
+ *
+ *   - the ACP server is `grok agent [options] stdio` — agent options go AFTER
+ *     `agent` and BEFORE the mode name, so `grok agent stdio` is the bare form;
+ *   - the released binary installs to `<GROK_HOME>/bin/grok[.exe]`
+ *     (`x.ai/cli/install.sh`, `GROK_HOME` defaulting to `~/.grok`), while the npm
+ *     package `@xai-official/grok` installs a `grok.cmd` shim that launches its
+ *     own JS bootstrap;
+ *   - the CLI has no `.exe` on PATH after an npm install, so the shim case is
+ *     handled through the shared executable helper rather than by spawning the
+ *     bare name.
+ *
+ * @module dsh-loop-engine-allinone/engine-grok/process
+ */
+/** Grace in milliseconds for Grok process-tree termination. */
+export declare const GROK_DISPOSE_GRACE_MS = 3000;
+/** Resolve the Grok home directory from `GROK_HOME` or the current user's home. */
+export declare function grokHomeDir(): string;
+/**
+ * Resolve the `grok` executable.
+ *
+ * An explicit config path wins. Otherwise the released-binary location is probed
+ * first (it is a real executable and the vendor's own install target), then PATH —
+ * where an npm install leaves a `.cmd` shim that {@link grokAcpArgv} knows how to
+ * launch.
+ * @param configBin - an operator-pinned path (or a bare name), if any.
+ * @returns the executable to spawn as `argv[0]`.
+ */
+export declare function grokBinResolver(configBin?: string): string;
+/**
+ * Build the argv that starts `grok agent stdio` (the ACP server over stdio).
+ *
+ * `--always-approve` is deliberately NOT here: it is a per-SESSION decision, and
+ * the engine expresses that per session through `session/new`'s `_meta.yoloMode`
+ * (see `./agent.ts`), which keeps this argv stable for every session the child
+ * serves and leaves the approval fold in one place.
+ * @param bin - the Grok executable (or its npm shim).
+ * @returns the argv, ending in the `stdio` mode name.
+ */
+export declare function grokAcpArgv(bin: string): string[];
+//# sourceMappingURL=process.d.ts.map

package/lib/types/engine-grok/profile.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Grok Build's ACP dialect: the shared ACP body with grok's own handshake.
+ *
+ * Three measured facts shape this profile, all of them from real frames dumped by
+ * `scripts/probe/acp-handshake.mjs` against the released `grok` 1.0.59 binary:
+ *
+ *   1. `initialize` answers `protocolVersion: 1`, advertises ONE auth method
+ *      (`id: grok.com`, name `Grok`) and reports
+ *      `promptCapabilities.image: false` — so this engine never receives image
+ *      blocks from the driver;
+ *   2. `session/new` REFUSES an unauthenticated client with
+ *      `-32000 Authentication required / "no auth method id provided"`, which is
+ *      ACP's own flow: the client answers `authenticate` with the advertised
+ *      method id, then opens the session. Grok on a signed-in host is expected to
+ *      accept `authenticate` immediately (its cached credentials live in
+ *      `~/.grok/auth.json`); on an unsigned host that call is what starts the
+ *      vendor's sign-in, and a failure after it is reported with the registry's
+ *      own login hint so the user is told what to run instead of reading a raw
+ *      JSON-RPC error;
+ *   3. the model is selected through `session/set_config_option` (Grok's user
+ *      guide documents the `{ value }` wrapper). MiniMax Code rejects that wrapper
+ *      and takes the bare value, so the driver tries the documented spelling and
+ *      falls back to the bare one, recording which the engine accepted — the
+ *      dialect difference is real and guessing it would break a working engine.
+ *
+ * `session/new` also carries `_meta.yoloMode` when the session's dsh approval
+ * knobs auto-approve, which maps the dsh policy onto Grok's own always-approve
+ * switch. When they do not, the driver leaves it off and answers the reverse-RPC
+ * `session/request_permission` itself (denying under an `ask` policy, since the
+ * unattended runtime has no human to ask).
+ *
+ * @module dsh-loop-engine-allinone/engine-grok/profile
+ */
+import type { AcpClient } from '../driver-acp/client.ts';
+import type { AcpEngineProfile } from '../driver-acp/profile.ts';
+/** Grok's model config option id, as its user guide documents it. */
+export declare const GROK_MODEL_CONFIG_ID = "model";
+/** The registry's login instruction, used when the engine reports it needs auth. */
+export declare function grokLoginHint(): string;
+/**
+ * Whether an error from `session/new` is ACP's "this client is not authenticated
+ * yet" refusal.
+ *
+ * Matched on the message because that is what the shared client surfaces from an
+ * error frame (`settle()` keeps `error.message`); measured text on 1.0.59 is
+ * exactly `Authentication required`.
+ * @param error - the rejection from `session/new`.
+ * @returns whether the agent refused for want of authentication.
+ */
+export declare function isAuthenticationRequired(error: unknown): boolean;
+/**
+ * The first auth method id an `initialize` result advertises.
+ *
+ * The driver takes the FIRST method rather than choosing among several: ACP
+ * publishes them in the agent's own preference order, and a client that ranks them
+ * itself would be inventing a policy the engine already stated.
+ * @param initializeResult - the raw `initialize` result.
+ * @returns the method id, or undefined when the agent advertised none.
+ */
+export declare function firstAuthMethodId(initializeResult: unknown): string | undefined;
+/**
+ * Select Grok's model through `session/set_config_option`, with the BARE value.
+ *
+ * MEASURED after signing in (this supersedes the earlier guess): Grok accepts
+ * `value: 'grok-4.7'` and REJECTS the `{ value }` wrapper its own documentation
+ * shows, with `-32602 "data did not match any variant of untagged enum
+ * SessionConfigOptionValue"`. So there is no fallback to try: the wrapper is
+ * simply wrong for this engine, and both ACP engines that speak
+ * `set_config_option` (this one and MiniMax Code) take the bare form.
+ *
+ * A model id the engine does not know is refused with `-32602 "unknown model
+ * id"`, which is the honest loud failure: the registry's `models` list is a
+ * declaration, and a stale entry must surface at the engine rather than be
+ * silently replaced by its default.
+ * @param client - the connected ACP client.
+ * @param sessionId - the ACP session.
+ * @param model - the model id to select.
+ */
+export declare function selectGrokModel(client: AcpClient, sessionId: string, model: string): Promise<void>;
+/** Grok Build's ACP dialect, as the shared driver reads it. */
+export declare function grokProfile(bin: string): AcpEngineProfile;
+//# sourceMappingURL=profile.d.ts.map

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

@@ -0,0 +1,47 @@
+/**
+ * Hermes Agent: one `hermes -z "prompt"` child per dsh step, with the durable
+ * session log as the sole source of model context.
+ *
+ * Hermes is the plugin's plain-text engine. It prints a finished answer and
+ * exits, with no frames, no tool events and no usage — so the driver's whole job
+ * is: serialize the transcript, spawn, read stdout to completion, and commit it
+ * as one assistant message through the shared sink.
+ *
+ * The consequences are declared rather than papered over
+ * (`EngineCapabilities`): `streaming: false` means the UI must not promise
+ * token-by-token output, and the absence of tool events means a tool Hermes ran
+ * internally appears nowhere in the transcript. That is a faithful record of
+ * what the engine reported.
+ *
+ * @module dsh-loop-engine-allinone/engine-hermes/agent
+ */
+import type { AgentOptions } from '@deepseek-ai/dsh-agent';
+import type { Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session';
+import type { Context } from '@deepseek-ai/cordis';
+import type { HostedEngineId } from '../engine-registry.ts';
+import { CliHostedAgent } from '../driver-cli/cli-agent.ts';
+import type { SinkPosition } from '../driver-cli/session-sink.ts';
+import type { CliSpawnCapability } from '../driver-cli/transport.ts';
+/** Deployment-resolved configuration for the Hermes engine. */
+export interface ResolvedHermesConfig {
+    /** Pinned executable, when the deployment named one. */
+    readonly bin: string | undefined;
+    /** Explicit environment entries layered over the scrubbed parent environment. */
+    readonly env: Record<string, string>;
+    /** Pinned model. */
+    readonly model: string | undefined;
+    /** Pinned reasoning level. */
+    readonly reasoning: string | undefined;
+}
+/** The engine id this driver registers under. */
+export declare const HERMES_ENGINE: HostedEngineId;
+/** Drives one session through turn and step boundaries on Hermes Agent. */
+export declare class HermesAgent extends CliHostedAgent {
+    private readonly config;
+    private readonly spawn;
+    constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedHermesConfig, spawn: CliSpawnCapability);
+    protected runStep(messages: readonly UserMessage[], position: SinkPosition, signal: AbortSignal): Promise<{
+        kind: 'completed';
+    } | null>;
+}
+//# sourceMappingURL=agent.d.ts.map

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

@@ -0,0 +1,56 @@
+/**
+ * Hermes Agent loop engine module: drives every session it is handed through one
+ * `hermes -z "prompt"` child 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.
+ *
+ * Hermes has no permission-mode switch this driver maps, so the effective
+ * boundary is the dsh subprocess sandbox the whole child is spawned under
+ * (default read-only).
+ *
+ * @module dsh-loop-engine-allinone/engine-hermes
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { AgentOptions } from '@deepseek-ai/dsh-agent';
+import type { Session, SessionId } from '@deepseek-ai/dsh-session';
+import { CliEngineRuntime } from '../driver-cli/cli-loop.ts';
+import { HermesAgent, type ResolvedHermesConfig } from './agent.ts';
+/** Deployment-owned configuration for the Hermes Agent engine. */
+export interface Config {
+    /** Model for the CLI (`-m`); Hermes' own configuration owns the model when omitted. */
+    model?: string;
+    /**
+     * Explicit environment entries passed to the child.
+     *
+     * Usually empty on purpose: Hermes reads its own `HERMES_HOME` and `auth.json`
+     * from the INHERITED environment. Setting `HERMES_HOME` here is how a
+     * deployment points the plugin at a second Hermes profile.
+     */
+    env?: Record<string, string>;
+    /** The `hermes` executable; PATH (and the CLI's own venv location) when not pinned. */
+    bin?: string;
+    /** Reasoning level (`--reasoning`). */
+    reasoning?: string;
+}
+/** Schema of the Hermes Agent engine configuration. */
+export declare const Config: z<Config>;
+/** Host-face ctx key this engine's runtime is registered under. */
+export declare const HERMES_ENGINE_LABEL = "agentLoopHermes";
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        agentLoopHermes: HermesLoop;
+    }
+}
+/**
+ * Creation/resume machinery for the Hermes Agent 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 HermesLoop extends CliEngineRuntime<ResolvedHermesConfig, HermesAgent> {
+    constructor(ctx: Context, config: Config);
+    /** Construct the Hermes driver for one prepared session. */
+    protected buildAgent(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session): HermesAgent;
+}
+//# sourceMappingURL=loop.d.ts.map

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

@@ -0,0 +1,92 @@
+/**
+ * Hermes Agent CLI process projection.
+ *
+ * Hermes is a Python CLI whose non-interactive surface is a single flag:
+ * `hermes -z "prompt"` runs one prompt and prints the answer. There is no
+ * structured output mode to speak of — the probe recorded in
+ * `docs/probes/hermes.md` found plain text on stdout and nothing else — so this
+ * driver reads the whole of stdout as one reply (`src/driver-cli/text.ts`).
+ *
+ * ## The environment, which is the interesting part
+ *
+ * Hermes keeps ALL of its state under `HERMES_HOME` (this machine: a directory
+ * outside the user profile holding 147 sessions, 105 skills and `auth.json`).
+ * The plugin never reads, writes or forwards that path — the child inherits it
+ * from the ambient environment like any other variable, because the dsh
+ * subprocess seam's scrub only removes `DSH_*` facts and names matching
+ * `KEY|PASSWORD|SECRET|TOKEN`, and `HERMES_HOME` matches neither.
+ *
+ * That inheritance is a FEATURE and not an accident worth leaving untested: if
+ * the plugin ever blanket-replaced the child environment, every Hermes session
+ * would silently start against an empty `HERMES_HOME` — a fresh install with no
+ * login — and the failure would look like "the model is broken" rather than
+ * "the plugin dropped an environment variable". `tests/engine-hermes/process.spec.ts`
+ * pins it.
+ *
+ * @module dsh-loop-engine-allinone/engine-hermes/process
+ */
+import type { CliSpawnRequest } from '../driver-cli/transport.ts';
+/** Grace in milliseconds for Hermes process-tree termination. */
+export declare const HERMES_DISPOSE_GRACE_MS = 3000;
+/** The flag that runs one prompt non-interactively. */
+export declare const HERMES_PROMPT_FLAG = "-z";
+/** The environment variable holding Hermes' entire state directory. */
+export declare const HERMES_HOME_ENV = "HERMES_HOME";
+/**
+ * Resolve the `hermes` executable.
+ *
+ * An explicit config path wins; then the well-known venv location; then PATH.
+ * The venv probe exists because that is where Hermes' own installer puts the
+ * CLI, and a profile started from a desktop shortcut does not always see the
+ * PATH entry pointing at it.
+ * @param configBin - an operator-pinned path, if any.
+ * @returns the executable to spawn as `argv[0]`.
+ */
+export declare function hermesBinResolver(configBin?: string): string;
+/**
+ * Whether a PATH entry looks like it could hold a `hermes` executable.
+ *
+ * Exported because the diagnostic surface (the settings page's engine check)
+ * wants to report "found on PATH" without spawning anything.
+ * @param pathEnv - the PATH value to inspect.
+ * @returns whether any entry names an existing `hermes` file.
+ */
+export declare function hermesOnPath(pathEnv: string | undefined): boolean;
+/** Everything one step's Hermes child needs. */
+export interface HermesSpawnSpec {
+    /** The resolved executable (`argv[0]`). */
+    readonly bin: string;
+    /** The prompt, passed as an argv argument. */
+    readonly prompt: string;
+    /** The session's working directory. */
+    readonly cwd: string;
+    /**
+     * Explicit environment entries layered over the scrubbed parent environment.
+     *
+     * Deliberately usually EMPTY: Hermes needs no forwarded credential, because
+     * it reads its own `HERMES_HOME` (inherited) and its own `auth.json`. A
+     * deployment may still add entries here, and one that sets `HERMES_HOME`
+     * explicitly overrides the inherited value — which is how a user points the
+     * plugin at a second Hermes profile.
+     */
+    readonly env: Record<string, string>;
+    /** Pinned model, when the deployment or the session named one. */
+    readonly model: string | undefined;
+    /** Pinned reasoning level, when the deployment named one. */
+    readonly reasoning: string | undefined;
+    /** Cancellation. */
+    readonly signal: AbortSignal;
+}
+/**
+ * Build the argv for one non-interactive Hermes step.
+ * @param spec - the step's spawn spec.
+ * @returns the argv.
+ */
+export declare function hermesArgv(spec: HermesSpawnSpec): string[];
+/**
+ * Project one step's spawn spec onto the transport request.
+ * @param spec - the step's spawn spec.
+ * @returns the transport's request shape.
+ */
+export declare function hermesSpawnRequest(spec: HermesSpawnSpec): CliSpawnRequest;
+//# sourceMappingURL=process.d.ts.map

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

@@ -0,0 +1,123 @@
+/**
+ * JSON-RPC client for the `kimi acp` subprocess (Agent Client Protocol over
+ * stdio).
+ *
+ * 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`.
+ *
+ * @module dsh-loop-engine/engine-kimi/acp/client
+ */
+import type { KimiProcess, KimiSpawnCapability, KimiSpawnSpec } from '../process.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;
+/**
+ * ACP client over one `kimi acp` 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;
+    /** Whether this client was sealed or its process exited. */
+    get closed(): boolean;
+    /** Mount a client over an already-spawned `kimi acp` process. */
+    constructor(process: KimiProcess);
+    /**
+     * Create a client, spawning the `kimi acp` child through the supplied
+     * capability (or the default node spawn when none is given).
+     * @param spec - the `kimi acp` argv/cwd/env the child should run with.
+     * @param spawn - optional process-spawn capability (the subprocess seam).
+     * @returns the connected client.
+     */
+    static create(spec: KimiSpawnSpec, spawn?: KimiSpawnCapability): 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;
+    /** Open the protocol handshake. */
+    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.
+     * @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;
+}
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1,73 @@
+/**
+ * Maps `kimi acp` `session/update` events to dsh session-log projections.
+ *
+ * Kimi streams 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: 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.
+ * Content blocks use the observed kimi
+ * `{ type: 'content', content: { type: 'text', text } }` nesting; unknown block
+ * types are ignored.
+ *
+ * @module dsh-loop-engine/engine-kimi/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