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

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

@@ -0,0 +1,289 @@
+/**
+ * The shared ACP loop Agent: drives one session through turn and step boundaries
+ * over a persistent ACP child (Agent Client Protocol over stdio), speaking one
+ * stateless `session/new` + `session/prompt` per dsh step.
+ *
+ * Three engines run on this one body — Kimi Code (`kimi acp`), Grok Build
+ * (`grok agent stdio`) and MiniMax Code (`mcode acp`) — because the whole
+ * turn/step machine, the durable-log projection, the streamed-update mapping and
+ * the reverse-RPC approval answer are ENGINE-INDEPENDENT. Everything that is not
+ * travels in {@link AcpEngineProfile} as data and four small hooks: the argv, the
+ * declared protocol version, how a model is selected, how a session is opened,
+ * and (for kimi only) the dsh endpoint handover.
+ *
+ * The dsh session log is the sole source of model context and the prompt is a
+ * pure serialization of the durable history, so the transcript stays
+ * Model-visible ⟺ logged. Each engine owns its system prompt and tools natively;
+ * the ACP child is spawned through the dsh subprocess seam (the only available
+ * privilege boundary) and tool approvals are answered from the session's dsh
+ * approval knobs (an `ask` policy degrades to denial, since the unattended
+ * runtime has no human to ask).
+ *
+ * @module dsh-loop-engine-allinone/driver-acp/agent
+ */
+import type { Agent, AgentCancelCause, AgentOptions, AgentStatus, CancelOptions, InboxTarget } from '@deepseek-ai/dsh-agent';
+import type { Scope } from '@deepseek-ai/dsh-scope';
+import type { Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session';
+import type { Context } from '@deepseek-ai/cordis';
+import type { AcpEngineProfile, AcpResolvedConfig } from './profile.ts';
+import { DriverInbox } from '../driver-core/inbox.ts';
+import type { AcpSpawnCapability } from './transport.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 every hosted engine selects `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 an ACP engine. */
+export declare class AcpEngineAgent implements Agent {
+    private loopCtx;
+    readonly id: SessionId;
+    readonly options: AgentOptions;
+    readonly session: Session;
+    private readonly config;
+    private readonly spawn;
+    private readonly profile;
+    readonly inbox: DriverInbox;
+    private phase;
+    private activityDone;
+    /** The agent-scoped registration boundary; the lifecycle owner unwinds it after the driver exits. */
+    readonly scope: Scope;
+    readonly ctx: Context;
+    /** Fused dispatcher, built once in the constructor so hot-path dispatches never allocate. */
+    private readonly dispatch;
+    /** Whether this loop instance has appended its initial/resume request anchor. */
+    private requestHeaderLogged;
+    /** Agent-lifecycle-local counter naming each streamed attempt. */
+    private streamAttempts;
+    /** Lazily created ACP client, reused across steps and released on scope teardown. */
+    private acp;
+    /** The last `initialize` result, where an agent publishes its auth methods. */
+    private initializeResult;
+    /** 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;
+    /**
+     * Countdown that shuts the child down once this agent has been idle past the
+     * configured window, so an idle session stops paying for a process nothing
+     * is driving. Armed and cancelled by {@link setPhase}.
+     */
+    private readonly idleChild;
+    /**
+     * Resolves the read-only path behind each image block of the prompt. The
+     * attachment service is read lazily on every call, so a host that composes it
+     * after this agent still reaches the transcript.
+     */
+    private readonly imageAccess;
+    constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: AcpResolvedConfig, spawn: AcpSpawnCapability, profile: AcpEngineProfile);
+    /** Shut the cached child down; the next step's {@link acpClient} spawns a fresh one. */
+    private closeChild;
+    get status(): AgentStatus;
+    /** Commit a phase and publish its externally visible status transition. */
+    private setPhase;
+    send(message: UserMessage, target: InboxTarget, wakeup: boolean): void;
+    /**
+     * Queue a message for the next turn and wake the driver.
+     * @param input - the user message to deliver.
+     */
+    followup(input: UserMessage): void;
+    /**
+     * Queue a message for the running step and wake the driver.
+     * @param input - the user message to deliver.
+     */
+    steer(input: UserMessage): void;
+    /**
+     * Queue a message for the running step without waking the driver.
+     * @param input - the user message to deliver.
+     */
+    inject(input: UserMessage): void;
+    cancel(cause: AgentCancelCause, options?: CancelOptions): void;
+    /**
+     * Run a maintenance job while the agent is idle.
+     * @param job - the maintenance operation, receiving the phase abort signal.
+     * @returns the maintenance result.
+     */
+    runMaintenance<T>(job: (signal: AbortSignal) => Promise<T>): Promise<T>;
+    /**
+     * Start one driver, or latch its wake behind maintenance or an aborted
+     * activity. A wake sent while idle always opens its turn boundary, even
+     * when its message was cleared; only a latched replay is suppressed when
+     * the queue no longer holds the wake.
+     * @param wakeAfterAbort - the {@link send} classification, captured before
+     *   the inbox insertion so a reentrant cancel cannot reclassify it.
+     */
+    private wakeDriver;
+    whenIdle(): Promise<void>;
+    /** Report one failure at its live boundary, then preserve it for driver containment. */
+    private throwError;
+    private kick;
+    private preStep;
+    /**
+     * Scan the step's user messages for `/name` skill gestures, load each
+     * matching skill, and inject the rendered skill content into the message
+     * batch. This mirrors what dsh-tool-skill does for the in-process engine.
+     * @param messages - the current step's message batch.
+     * @param signal - cancellation signal (aborted loads are silently dropped).
+     * @returns the original batch when no skill was invoked, or an extended
+     *   batch with injected skill-content messages appended.
+     */
+    private injectSkills;
+    /** Open one turn before claiming its first proposed step. */
+    private turn;
+    /** Model label recorded in the request header for one lifecycle. */
+    private modelLabel;
+    /** Append the request header snapshot once per loop instance. */
+    private assertRequestHeader;
+    /** Whether two spawn specs describe the same ACP child. */
+    private specsEqual;
+    /**
+     * The client-side capability bridges this engine declared, bound to the host.
+     *
+     * Built fresh per client because the terminal bridge closes over the session's
+     * working directory, which is per agent. An engine that declares no bridges gets
+     * an empty object, and the client then announces no capabilities at all.
+     * @param cwd - the session's working directory, the default for a terminal.
+     * @returns the handlers the client answers reverse RPCs with.
+     */
+    private reverseHandlers;
+    /** Return the cached ACP client, respawning when the spec or process changed. */
+    private acpClient;
+    /** Build the ACP child's argv/cwd/env for the persistent child. */
+    private spawnSpec;
+    /**
+     * The child environment for one step, with the engine's own dsh-endpoint
+     * handover applied when its profile declares one.
+     *
+     * Memoized by content so an unchanged endpoint yields the SAME object across
+     * steps (see {@link handoverEnvCache}): `specsEqual` compares environments by
+     * reference, and a fresh object per step would respawn the child every step.
+     *
+     * `handedOver` is what tells the step whether to select a model itself: an
+     * engine whose profile translates the endpoint into its own environment has
+     * already been told which model to use, and asking it again by the raw dsh
+     * model id would ask for an alias its env-model path never defined.
+     * @returns the environment, and whether a dsh endpoint travelled in it.
+     */
+    private childEnvironment;
+    /**
+     * Open the ACP session one step drives.
+     *
+     * The profile's hook is what makes an engine's own handshake differences
+     * expressible without touching this body: grok's `session/new` refuses an
+     * unauthenticated client (which its hook answers by authenticating with the
+     * method id `initialize` published), while MiniMax Code needs no such step.
+     * @param client - the connected ACP client.
+     * @param cwd - the session's working directory.
+     * @returns the ACP session id.
+     */
+    private openSession;
+    /**
+     * Run one `kimi acp` step for the current session history and map the streamed updates.
+     * @param messages - the messages this step delivers; only their images ride
+     *   with the prompt as ACP image blocks, and only they.
+     */
+    private step;
+    /** Per-step accumulation state for streamed assistant blocks and tool calls. */
+    private blocks;
+    /**
+     * Announced calls still waiting for the update that carries their input,
+     * keyed by call id, holding the latest content snapshot seen meanwhile (a
+     * frame can report output before it reports input). `toolContent` holds the
+     * calls already logged, so a call is in exactly one of the two.
+     */
+    private pendingCalls;
+    /** Whether the current step published any assistant message at all. */
+    private producedOutput;
+    /**
+     * Tool results logged into the currently open step. A result means the
+     * segment that requested the call is finished, so the next assistant content
+     * opens the next step (see {@link beginSegment}).
+     */
+    private stepSettledTools;
+    /**
+     * The current step's calls, and which of them already carry a result.
+     *
+     * Kimi announces a call and reports its outcome on separate ACP updates, so
+     * "which calls of THIS step are still open" is state the driver has to keep.
+     * Both halves of the Session V4 rule read it: a call may not be given a second
+     * result in one step, and a step may not end while a call it announced has no
+     * result at all — the closing pass writes the missing outcome instead
+     * ({@link closeStep}).
+     *
+     * Reset per step (see {@link step}), never on an internal segment rotation:
+     * call ids are unique for the life of the session, so retaining the marks only
+     * widens duplicate suppression and can never hide a legitimate result.
+     */
+    private readonly stepTools;
+    /**
+     * Tool calls the current segment has already received input for, awaiting the
+     * segment's single assistant message. A model turn that announces several
+     * calls before any result must land them all in ONE message — the chat node
+     * keys by `${turn}:${step}` and replaces blocks on every message, so a second
+     * message would overwrite the first one's reasoning/text (and tool-call head).
+     * The list is flushed once, when the segment closes (its first settled result).
+     */
+    private segmentCalls;
+    /** Latest content snapshot per logged tool call (see {@link applyUpdate}). */
+    private toolContent;
+    /** The live attempt framing the assistant message being assembled right now. */
+    private live;
+    private blockRef;
+    private ensureBlock;
+    /**
+     * Rotate to the next step when the segment that ran a tool has finished, so
+     * each assistant segment lands in its own step.
+     *
+     * Called as new assistant content begins. A step holding a settled tool
+     * result means the previous segment is complete, and the content about to be
+     * applied belongs to the next one. Rotating here (rather than when a call is
+     * announced) keeps calls that were announced before any result — one model
+     * turn — in a single step.
+     *
+     * A step that still OWES a result does not rotate: Kimi announces several
+     * calls in one turn and settles them one at a time, and rotating on the first
+     * outcome would strand the rest in a step that can never resolve them
+     * (`step/end leaves unresolved tool call …`). Those calls run one model turn
+     * later instead, which is what they belong to, and a call the engine never
+     * answers is closed by {@link closeStep} rather than by moving on.
+     */
+    private beginSegment;
+    /** Apply one streamed update to the open step's blocks and stream. */
+    private applyUpdate;
+    /** The live attempt framing the current segment, opened on its first chunk. */
+    private currentStream;
+    /**
+     * Flush the open segment's single assistant message and every `tool/call` it
+     * accumulated, in the load-bearing order assistant/message → tool/call. One
+     * segment produces exactly ONE message even when the model announced several
+     * calls before any result, because the chat view keys an assistant node by
+     * `${turn}:${step}` and replaces its blocks on every message — a second
+     * message in the same step would overwrite the first one's reasoning/text and
+     * leave only the last bare tool-call head visible.
+     * @param phase - the open step the segment belongs to.
+     */
+    private flushSegment;
+    /**
+     * Flush the accumulated assistant blocks into one durable assistant/message
+     * carrying the exact stream the attempt published live, optionally closing it
+     * with the tool-call block(s) that ended the segment.
+     *
+     * Every flush settles its own attempt (and so its own live `end` frame): a
+     * step emits one message per assistant segment, and the client pairs a durable
+     * message with the attempt whose `end` cites it, so two messages may not share
+     * one attempt.
+     * @param phase - the open step the message belongs to.
+     * @param toolCalls - the calls that closed this segment, rendered as trailing
+     *   `tool-call` content blocks. A segment with no blocks of its own — a step
+     *   whose only activity was a tool call — still emits this message, so its
+     *   `tool/call` and `tool/result` events have a parent to pair with.
+     */
+    private flushAssistant;
+}
+//# sourceMappingURL=agent.d.ts.map

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

@@ -0,0 +1,27 @@
+/**
+ * The shared tool-approval fold for ACP engines.
+ *
+ * An ACP agent surfaces a tool it wants to run as the reverse-RPC
+ * `session/request_permission`, which the client MUST answer; the dsh harness has
+ * no interactive approval callback in the unattended runtime, so the fold has to
+ * decide. It mirrors the codex/Pi bridges: an `ask` policy degrades to a denial
+ * (the only safe answer when no human is present), and anything else (`never`, or
+ * a knob-less session) auto-approves.
+ *
+ * It lives here rather than in one engine's directory because all three ACP
+ * engines arrive at the same gate; an engine whose own permission switch already
+ * bounds the tool can still override the fold through its profile's `approve`.
+ *
+ * @module dsh-loop-engine-allinone/driver-acp/approval
+ */
+import type { Session } from '@deepseek-ai/dsh-session';
+/**
+ * Whether the driver should answer `session/request_permission` with approval for
+ * one query. An `ask` policy denies; anything else auto-approves. The sandbox
+ * stance is not consulted: the engine's own tool policy bounds what a tool does,
+ * and the ACP approval is the host's gate, signalled by `approval/policy`.
+ * @param session - the session whose durable knobs are read.
+ * @returns whether tool requests are approved.
+ */
+export declare function acpDefaultApproval(session: Session): boolean;
+//# sourceMappingURL=approval.d.ts.map

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

@@ -0,0 +1,200 @@
+/**
+ * ACP client-side capabilities: the reverse-RPC methods an agent may call on US.
+ *
+ * ACP is bidirectional. Besides the requests a client sends (`initialize`,
+ * `session/new`, `session/prompt`), an agent may call BACK into the client for
+ * things it cannot do itself. Which ones it calls is the agent's decision, and a
+ * client that answers `methodNotFound` is a client that agent cannot fully use.
+ *
+ * This module is the measured list, not the specification's full menu. Two
+ * engines were driven with real tasks and every reverse RPC they issued was
+ * recorded with `scripts/probe/acp-handshake.mjs` against the real CLIs:
+ *
+ *   - `session/request_permission` — already implemented since the kimi driver;
+ *   - `fs/read_text_file` — Grok Build asks the client to read a file for it;
+ *   - `terminal/create` (+ its lifecycle calls) — Grok Build asks the client to
+ *     RUN a command and report its output.
+ *
+ * MiniMax Code asks for none of these: it executes its own tools and reports the
+ * result, which is why its tool calls work without any of this.
+ *
+ * ## Why the terminal bridge is the interesting one
+ *
+ * A command the AGENT wants run must not become a second, weaker execution path
+ * than the one dsh's own `bash` tool uses. So the bridge does not spawn anything
+ * itself: it resolves the harness's `shell` service (`ctx.shell`), which owns the
+ * sandbox policy, the timeout policy and the output caps. A grok tool call and a
+ * dsh `bash` call therefore run through the SAME executor with the SAME
+ * confinement — which is also what makes the approval question answerable: the
+ * reverse-RPC permission gate stays the single place a human's policy is applied.
+ *
+ * @module dsh-loop-engine-allinone/driver-acp/capabilities
+ */
+import type { Readable, Writable } from 'node:stream';
+/**
+ * One reverse-RPC request frame, as it arrived.
+ *
+ * `id` is a number for every request an agent sends (JSON-RPC allows strings, but
+ * all three measured engines use integers); the client echoes it back verbatim.
+ */
+export interface AcpReverseRequest {
+    readonly id: number;
+    readonly method: string;
+    readonly params: unknown;
+}
+/**
+ * What the client can do for an agent, as the agent was TOLD it can.
+ *
+ * The values travel in `initialize`'s `clientCapabilities`. Declaring a capability
+ * is a promise: an agent reads it to decide whether to send the request at all, so
+ * declaring one this client cannot honour is worse than declaring none — the
+ * agent would plan a tool call that then fails.
+ */
+export interface AcpClientCapabilities {
+    /** Whether `fs/read_text_file` and `fs/write_text_file` are answerable. */
+    readonly fs: {
+        readonly readTextFile: boolean;
+        readonly writeTextFile: boolean;
+    };
+    /** Whether the `terminal/*` lifecycle is answerable. */
+    readonly terminal: boolean;
+}
+/** The capabilities a client announces when it bridges every measured reverse RPC. */
+export declare const FULL_CLIENT_CAPABILITIES: AcpClientCapabilities;
+/**
+ * The capabilities a client announces when it bridges nothing.
+ *
+ * Kept as a named constant because it is a real, supported configuration: the
+ * kimi driver has always announced this, and a deployment that would rather not
+ * let an engine run commands can keep it.
+ */
+export declare const NO_CLIENT_CAPABILITIES: AcpClientCapabilities;
+/**
+ * Whether one ACP method name is a capability this client implements.
+ *
+ * The list is closed on purpose: it is exactly the measured set (plus the
+ * terminal lifecycle ACP defines around `terminal/create`). Anything else stays
+ * on the `methodNotFound` path, so an engine's private extension never gets a
+ * half-answer from a client that only meant to support the standard ones.
+ * @param method - the ACP method name from a reverse-RPC request.
+ * @returns whether {@link AcpReverseHandlers} can answer it.
+ */
+export declare function isCapabilityMethod(method: string): boolean;
+/**
+ * One live terminal the client owns on the agent's behalf.
+ *
+ * The agent creates it with a command, then polls/awaits it, then releases it. The
+ * client is responsible for the whole lifetime: an agent that never releases one
+ * must not leak a process, so the client closes every open terminal when its own
+ * process goes away.
+ */
+export interface AcpTerminal {
+    /** Output accumulated so far, plus whether the command has finished. */
+    snapshot(): AcpTerminalSnapshot;
+    /** Resolve when the command finishes, or reject when it could not start. */
+    waitForExit(): Promise<AcpTerminalExit>;
+    /** Terminate the command (idempotent) and drop the terminal. */
+    release(): void;
+}
+/** The `terminal/output` answer: what the command has produced so far. */
+export interface AcpTerminalSnapshot {
+    /** Everything written to stdout so far. */
+    readonly output: string;
+    /** Whether the command has finished (and so whether `output` is final). */
+    readonly exited: boolean;
+    /** Exit code, present once `exited`. */
+    readonly exitCode?: number;
+}
+/** The `terminal/wait_for_exit` answer. */
+export interface AcpTerminalExit {
+    /** Exit code; a signal-killed or timed-out command reports a non-zero code. */
+    readonly exitCode: number;
+}
+/**
+ * The seam a driver hands the client so it can answer the measured reverse RPCs.
+ *
+ * Every method is optional: a client built without a bridge answers
+ * `methodNotFound` for it, which is the honest answer and what the kimi driver
+ * has always done. The `terminal` capability is announced ONLY when
+ * {@link AcpReverseHandlers.spawnTerminal} is present, so the declaration and the
+ * implementation cannot drift apart.
+ */
+export interface AcpReverseHandlers {
+    /**
+     * Read one text file for the agent.
+     *
+     * The path arrives absolute (measured: grok sends the resolved path). It is
+     * read through the harness filesystem service when one is available, so dsh's
+     * observation policy applies; a plain `node:fs` read is the fallback for a
+     * composition without that service.
+     * @param path - the absolute path the agent asked for.
+     * @returns the file's decoded text.
+     */
+    readTextFile?(path: string): Promise<string>;
+    /**
+     * Start one command on the agent's behalf.
+     *
+     * Implementations MUST route through the harness's own executor (or an
+     * equivalently confined path) rather than spawning freely: this is the
+     * difference between "the engine can use tools" and "the engine bypasses the
+     * sandbox".
+     * @param command - the shell command line the agent asked to run.
+     * @param options - the agent's requested environment and working directory.
+     * @returns the live terminal handle.
+     */
+    spawnTerminal?(command: string, options: AcpTerminalSpawnOptions): Promise<AcpTerminal>;
+}
+/** What an agent may ask for when creating a terminal. */
+export interface AcpTerminalSpawnOptions {
+    /** Environment entries the agent wants layered over the child's own. */
+    readonly env?: Record<string, string>;
+    /** Working directory, when the agent named one. */
+    readonly cwd?: string;
+}
+/**
+ * One `terminal/create` params payload, as the agent sent it.
+ *
+ * ACP spells the environment as a LIST of `{name, value}` pairs, not a map —
+ * measured on grok, which sends 14 entries including its own `GROK_SESSION_ID`.
+ */
+export interface AcpTerminalCreateParams {
+    readonly sessionId?: string;
+    readonly command?: unknown;
+    readonly env?: unknown;
+    readonly cwd?: unknown;
+}
+/**
+ * Read the command out of `terminal/create` params, or undefined when absent.
+ * @param params - the reverse-RPC params.
+ * @returns the command line, when the frame carried a non-empty one.
+ */
+export declare function terminalCommandOf(params: unknown): string | undefined;
+/**
+ * Read the agent's environment request out of `terminal/create` params.
+ *
+ * The wire shape is a list of pairs; a malformed entry is skipped rather than
+ * failing the call, because a command with a partial environment is still a
+ * command the agent asked for, while a thrown error would fail the whole turn
+ * over a field the agent did not need.
+ * @param params - the reverse-RPC params.
+ * @returns the entries as a map, or undefined when the frame carried none.
+ */
+export declare function terminalEnvOf(params: unknown): Record<string, string> | undefined;
+/**
+ * Read the working directory out of `terminal/create` params.
+ * @param params - the reverse-RPC params.
+ * @returns the directory, when the frame carried a non-empty one.
+ */
+export declare function terminalCwdOf(params: unknown): string | undefined;
+/**
+ * The stream triple an ACP child exposes, as the capability layer needs it.
+ *
+ * Declared structurally rather than imported from `./transport.ts` so a test can
+ * build one without the rest of the transport contract.
+ */
+export interface AcpStdio {
+    readonly stdin: Writable;
+    readonly stdout: Readable;
+    readonly stderr: Readable;
+}
+//# sourceMappingURL=capabilities.d.ts.map