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

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

@@ -0,0 +1,98 @@
+/**
+ * The terminal bridge: an ACP agent's `terminal/*` calls, executed through the
+ * harness's own shell service.
+ *
+ * This is the piece that makes a tool-using ACP engine actually work. Grok Build
+ * runs every shell tool by asking the CLIENT to execute the command
+ * (`terminal/create`); a client that answers `methodNotFound` gives the model a
+ * broken tool, which is what this plugin shipped before. The bridge fixes that
+ * without touching the engine and without inventing a second execution path:
+ *
+ *   - the command goes through `ctx.shell` (`ShellExecutor.resolve` +
+ *     `execute`), which is the SAME service dsh's own `bash` tool uses — so the
+ *     sandbox mode, the timeout policy and the output caps are dsh's, not a
+ *     plugin-local imitation of them;
+ *   - when the composition has no shell service the bridge REFUSES rather than
+ *     falling back to a bare `child_process.spawn`: an unconfined execution
+ *     channel is exactly the thing a sandbox exists to prevent, and silently
+ *     becoming it would be worse than the tool failing;
+ *   - the reverse-RPC approval gate still runs first, so a session whose approval
+ *     policy says `ask` denies the command before it is ever spawned.
+ *
+ * ## Terminal lifecycle
+ *
+ * ACP models a terminal as a long-lived object: `create` returns an id, the agent
+ * polls `terminal/output`, awaits `terminal/wait_for_exit`, and finally calls
+ * `terminal/release`. The harness's shell handle already has that shape
+ * (`readOutput` is incremental, `done` settles at close, `kill` stops it), so the
+ * bridge is a thin adapter over one execution.
+ *
+ * @module dsh-loop-engine-allinone/driver-acp/terminal
+ */
+import type { AcpTerminal, AcpTerminalSpawnOptions } from './capabilities.ts';
+/**
+ * The part of the harness shell service this bridge uses, declared structurally.
+ *
+ * The real service is `@deepseek-ai/dsh-shell`'s `ShellExecutor`. It is declared
+ * here for the same reason every other host service in this plugin is: the plugin
+ * depends on the CONTRACT it consumes, and a minimal composition may not carry the
+ * package at all.
+ */
+export interface ShellExecutorLike {
+    /**
+     * Fill in and cap an execution request.
+     * @param request - the caller's request.
+     * @returns the resolved spec to hand to {@link ShellExecutorLike.execute}.
+     */
+    resolve(request: ShellExecRequestLike): ShellExecSpecLike;
+    /**
+     * Prepare and spawn one command.
+     * @param spec - a resolved spec.
+     * @returns the prepared handle.
+     */
+    execute(spec: ShellExecSpecLike): Promise<ShellExecutionLike>;
+}
+/** The subset of the shell request shape this bridge fills in. */
+export interface ShellExecRequestLike {
+    command: string;
+    workdir?: string;
+    timeoutMs?: number;
+    onExpiry?: 'kill' | 'none';
+    env?: Record<string, string>;
+}
+/** The resolved spec, echoed so the handle's result can be read. */
+export interface ShellExecSpecLike extends ShellExecRequestLike {
+    workdir: string;
+    timeoutMs: number;
+    onExpiry: 'kill' | 'none';
+}
+/** The part of one shell execution this bridge reads. */
+export interface ShellExecutionLike {
+    readonly done: Promise<void>;
+    readonly exitCode: number | null;
+    readOutput(): {
+        readonly stdout: string;
+        readonly stderr: string;
+    };
+    kill(): boolean;
+    result(): Promise<{
+        readonly exitCode: number | null;
+        readonly stdout: {
+            readonly text: string;
+        } | string;
+        readonly stderr: {
+            readonly text: string;
+        } | string;
+    }>;
+}
+/**
+ * Create the bridge an ACP client uses to answer `terminal/*`.
+ *
+ * @param shell - the harness shell service, or undefined when the composition has
+ *   none (the bridge then refuses every command, see the module note).
+ * @param defaultCwd - the session's working directory, used when the agent names
+ *   none of its own.
+ * @returns a spawn function for {@link AcpReverseHandlers.spawnTerminal}.
+ */
+export declare function createTerminalBridge(shell: ShellExecutorLike | undefined, defaultCwd: string): (command: string, options: AcpTerminalSpawnOptions) => Promise<AcpTerminal>;
+//# sourceMappingURL=terminal.d.ts.map

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

@@ -0,0 +1,43 @@
+/**
+ * The process transport an ACP driver speaks over, engine-neutral.
+ *
+ * The driver hands the client a handle carrying the child's stdin/stdout/stderr
+ * (projected from the dsh subprocess seam). The three engines differ in HOW the
+ * child is launched — `kimi acp`, `grok agent stdio`, `mcode acp` — and not at
+ * all in what the driver does with it, so the transport is declared once here and
+ * each engine's `process.ts` owns its own argv and executable resolution.
+ *
+ * The names are deliberately this generic: an engine that wants its own spelling
+ * for the published surface (`KimiProcess`) aliases these rather than restating
+ * them, so a change to the seam cannot reach one engine and miss another.
+ *
+ * @module dsh-loop-engine-allinone/driver-acp/transport
+ */
+import type { Readable, Writable } from 'node:stream';
+/** The exact argv/cwd/env the driver requests for one ACP child. */
+export interface AcpSpawnSpec {
+    /** The program plus its flags; `argv[0]` is the engine's executable. */
+    readonly argv: readonly string[];
+    /** The session's working directory, also the ACP session's `cwd`. */
+    readonly cwd: string;
+    /** The child's environment, layered over the credential-scrubbed parent. */
+    readonly env: Record<string, string>;
+    /** Cancellation: the seam escalates process-tree termination when it fires. */
+    readonly signal?: AbortSignal;
+}
+/** A spawned ACP agent process, as the client's transport needs it. */
+export interface AcpProcess {
+    /** Child stdin (JSON-RPC request frames). */
+    readonly stdin: Writable;
+    /** Child stdout (responses and `session/update` notifications). */
+    readonly stdout: Readable;
+    /** Child stderr (diagnostics; drained and dropped). */
+    readonly stderr: Readable;
+    /** Resolves when the child closes. */
+    readonly done: Promise<unknown>;
+    /** Request process-tree termination. */
+    terminate(): void;
+}
+/** Spawns one ACP child over the given spec (the driver's spawn capability). */
+export type AcpSpawnCapability = (spec: AcpSpawnSpec) => AcpProcess;
+//# sourceMappingURL=transport.d.ts.map

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

@@ -0,0 +1,152 @@
+/**
+ * Agent Client Protocol (ACP) wire types shared by every ACP engine driver.
+ *
+ * Three engines speak ACP over stdio (JSON-RPC 2.0): Kimi Code (`kimi acp`),
+ * Grok Build (`grok agent stdio`) and MiniMax Code (`mcode acp`). The driver
+ * speaks the minimal, stable subset a normal agent flow needs: initialize,
+ * session/new, session/prompt, session/cancel, plus the `session/update`
+ * notifications carrying incremental assistant text (`agent_message_chunk`),
+ * thinking (`agent_thought_chunk`), and tool calls (`tool_call` /
+ * `tool_call_update`). Tool-approval arrives as the reverse-RPC
+ * `session/request_permission`, which the client must answer.
+ *
+ * The shapes below were READ from live frames, not from the specification, and
+ * each engine's own deltas are recorded where they matter
+ * (`docs/engine-registry.md`): kimi nests tool content
+ * as `{ type: 'content', content: { type: 'text' } }`, all three carry text
+ * chunks as `content: { type: 'text', text }`, and a model is selected through
+ * a DIFFERENT method per engine (`session/set_model` on kimi,
+ * `session/set_config_option` on grok and MiniMax Code). Content blocks tolerate
+ * block types this build does not know by ignoring them. The image block is
+ * modelled for the OUTGOING side — the bytes a dsh step delivers as an ACP
+ * image block.
+ *
+ * @module dsh-loop-engine-allinone/driver-acp/types
+ */
+/** A text content block in an ACP update (the observed kimi shape). */
+export interface AcpTextContent {
+    readonly type: 'text';
+    readonly text: string;
+}
+/** One tool-call content block: the observed kimi `{ type: 'content', content }` nesting. */
+export interface AcpToolContentBlock {
+    readonly type: 'content';
+    readonly content: AcpTextContent;
+}
+/** An image content block, as ACP/MCP spells it (base64 bytes + media type). */
+export interface AcpImageContent {
+    readonly type: 'image';
+    /** Base64-encoded image bytes. */
+    readonly data: string;
+    /** The image's own media type. */
+    readonly mimeType: string;
+}
+/** A content block in a chunk/thought update; text is handled, others are ignored. */
+export type AcpContentBlock = AcpTextContent | AcpImageContent | {
+    readonly type: 'resource_link' | 'audio' | string;
+    readonly [key: string]: unknown;
+};
+/** One `session/update` notification (partial; the discriminator is `sessionUpdate`). */
+export interface AcpUpdate {
+    readonly sessionUpdate: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * A tool-call announcement (`sessionUpdate: 'tool_call'`).
+ *
+ * Measured against kimi 0.28.x: an announcement carries the call's identity
+ * (`toolCallId`/`title`/`kind`) and an empty content card, but **never** its
+ * input — `rawInput` only ever arrives on a later `tool_call_update` (the
+ * execution-start frame).
+ */
+export interface AcpToolCallExt extends AcpUpdate {
+    readonly sessionUpdate: 'tool_call';
+    readonly toolCallId: string;
+    readonly title: string;
+    readonly kind: string;
+    readonly status: string;
+    readonly content?: readonly AcpToolContentBlock[];
+    /** The call's real input; absent on the announcement (see above). */
+    readonly rawInput?: unknown;
+}
+/** A tool-call progress/result stream (`sessionUpdate: 'tool_call_update'`). */
+export interface AcpToolCallStreamExt extends AcpUpdate {
+    readonly sessionUpdate: 'tool_call_update';
+    readonly toolCallId: string;
+    readonly status: string;
+    readonly content?: readonly AcpToolContentBlock[];
+    /** The call's real input, first present on the execution-start frame. */
+    readonly rawInput?: unknown;
+    /** The tool's raw structured output, present once the call settles. */
+    readonly rawOutput?: unknown;
+}
+/** One option the agent offers for a `session/request_permission`. */
+export interface AcpPermissionOption {
+    /** Opaque id the client sends back in `outcome.optionId` (the only field the agent reads). */
+    readonly optionId: string;
+    /** Human-readable label for the option. */
+    readonly name?: string;
+    /** Option class: `allow_once` / `allow_always` / `reject_once` / `reject_always`. */
+    readonly kind?: string;
+}
+/** The `session/request_permission` reverse-RPC params. */
+export interface AcpPermissionRequest {
+    readonly sessionId?: string;
+    /** Every option the agent will accept an answer for; empty means no answerable choice. */
+    readonly options?: readonly AcpPermissionOption[];
+    /** The tool call the prompt belongs to (presentation/correlation only). */
+    readonly toolCall?: unknown;
+}
+/**
+ * Terminal outcome of a permission request: the option the client picked, or
+ * `cancelled` when it had no answer to give.
+ */
+export type AcpPermissionOutcome = {
+    readonly outcome: 'selected';
+    readonly optionId: string;
+} | {
+    readonly outcome: 'cancelled';
+};
+/** The `session/request_permission` result the agent expects (ACP `RequestPermissionResponse`). */
+export interface AcpPermissionResponse {
+    readonly outcome: AcpPermissionOutcome;
+}
+/** Result of a completed `session/prompt` request (opaque; the turn ended). */
+export interface AcpPromptResult {
+    readonly [key: string]: unknown;
+}
+/** The id-scoped response to a request (result or error). */
+export interface AcpResponse {
+    readonly id: number;
+    readonly result?: unknown;
+    readonly error?: {
+        readonly code: number;
+        readonly message: string;
+    };
+}
+/** A JSON-RPC request/notification frame on the wire. */
+export interface AcpFrame {
+    readonly jsonrpc: '2.0';
+    readonly id?: number;
+    readonly method?: string;
+    readonly params?: unknown;
+    readonly result?: unknown;
+    readonly error?: {
+        readonly code: number;
+        readonly message: string;
+    };
+}
+/** Guards toolkit: is the frame a `session/update` notification carrying an update. */
+export declare function isUpdateFrame(frame: AcpFrame): frame is AcpFrame & {
+    readonly method: 'session/update';
+    readonly params: {
+        readonly sessionId: string;
+        readonly update: AcpUpdate;
+    };
+};
+/** Guards toolkit: is the frame a reverse-RPC request needing an approval answer. */
+export declare function isPermissionRequestFrame(frame: AcpFrame): frame is AcpFrame & {
+    readonly id: number;
+    readonly method: 'session/request_permission';
+};
+//# sourceMappingURL=types.d.ts.map

package/lib/types/driver-cli/capability.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Capability guards: what a driver does when its engine cannot do what the step
+ * asked for.
+ *
+ * The plugin's rule is that an engine which cannot honour something says so,
+ * rather than accepting it and quietly doing something else ("能力不足的引擎如实
+ * 降级，不假装支持"). The registry declares each engine's capabilities
+ * (`EngineCapabilities`), and this module turns a declaration into the check a
+ * driver runs before it spends a child process on a request the engine will
+ * mistranslate.
+ *
+ * The distinction that matters: a capability the engine LACKS is a refusal with
+ * the user's next action named, not a silent drop. Dropping an image and sending
+ * the text alone would look to the user like the engine read the picture.
+ *
+ * @module dsh-loop-engine-allinone/driver-cli/capability
+ */
+import type { UserMessage } from '@deepseek-ai/dsh-session';
+import type { EngineDescriptor } from '../engine-registry.ts';
+/**
+ * Count the image blocks this step delivers.
+ *
+ * Only THIS step's own messages, not the whole transcript: an older image in the
+ * history is already a text placeholder in the serialized prompt (that is what
+ * `serializeHistory` does), so only a fresh attachment can be lost by an engine
+ * with no image channel.
+ * @param messages - the step's message batch.
+ * @returns how many image blocks they carry.
+ */
+export declare function stepImageCount(messages: readonly UserMessage[]): number;
+/**
+ * The refusal to report when a step delivers images to an engine that declared
+ * it cannot take them, or undefined when the step is fine.
+ *
+ * The message names the engine, the count, and what the user can do — which is
+ * the difference between a refusal and a puzzle.
+ * @param messages - the step's message batch.
+ * @param descriptor - the engine's registry row.
+ * @returns the refusal message, or undefined.
+ */
+export declare function unsupportedImagesRefusal(messages: readonly UserMessage[], descriptor: EngineDescriptor): string | undefined;
+//# sourceMappingURL=capability.d.ts.map

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

@@ -0,0 +1,258 @@
+/**
+ * The shared CLI agent: the turn/step lifecycle every external-CLI engine runs,
+ * in one place.
+ *
+ * The four original drivers each carry their own copy of this machinery — about
+ * 450 near-identical lines apiece (the `jscpd:ignore` markers in
+ * `src/engine-<id>/agent.ts` mark exactly that duplication). Keeping those copies
+ * was the right call at the time: they were written and hardened one engine at a
+ * time, against protocols whose failure modes differed. It is the wrong call for
+ * engines added after this refactor, because the machinery is where the subtle
+ * bugs live (a missing `agent/error`, a step left open, an inbox claim that
+ * never wakes the driver) and a new engine should not have to rediscover them.
+ *
+ * So a NEW engine implements {@link CliHostedAgent} instead. It supplies:
+ *
+ *  - {@link CliHostedAgent.runStep} — the protocol round trip, which is the only
+ *    part that is actually engine-specific; and
+ *  - whatever transport, argv and frame mapping that round trip needs.
+ *
+ * Everything else — the phase machine, the durable inbox, cancellation, the
+ * pre-step waterfall, skill injection, maintenance, the status transitions —
+ * is inherited and therefore identical across engines by construction.
+ *
+ * The durable-log half of a step is {@link SessionSink}, which this base owns
+ * and hands to the subclass. The split is deliberate: the base owns *when*
+ * things happen (turn opened, step started, step closed), the sink owns *what
+ * lands in the log* (messages, tool calls, results, streams), and the subclass
+ * owns *what the engine said*.
+ *
+ * @module dsh-loop-engine-allinone/driver-cli/cli-agent
+ */
+import type { Agent, AgentCancelCause, AgentOptions, AgentStatus, CancelOptions, InboxTarget } from '@deepseek-ai/dsh-agent';
+import type { ImageAttachmentAccessResolver, Message } from '@deepseek-ai/dsh-llm';
+import type { Scope } from '@deepseek-ai/dsh-scope';
+import type { Session, SessionId, TurnEndReason, UserMessage } from '@deepseek-ai/dsh-session';
+import type { Context } from '@deepseek-ai/cordis';
+import type { HostedEngineId } from '../engine-registry.ts';
+import { DriverInbox } from '../driver-core/inbox.ts';
+import { SessionSink, type SinkPosition } from './session-sink.ts';
+/**
+ * Provider route label every hosted engine logs into `request/header` and into
+ * message provenance — the ONE route they share
+ * ({@link HOSTED_ROUTE_LABEL}), so the model menu carries a single `external`
+ * group instead of one per engine.
+ */
+export declare const CLI_PROVIDER = "external";
+/** The ending a step reports, before the turn loop folds it. */
+type StepEndReason = Extract<TurnEndReason, {
+    kind: 'completed' | 'max-tokens';
+}>;
+/**
+ * What one subclass needs to tell the base about itself.
+ *
+ * A small object rather than a long constructor parameter list, because every
+ * engine adds fields to it over time and a positional list makes each addition a
+ * breaking change for every subclass.
+ */
+export interface CliAgentHost {
+    /** Which engine this agent runs, for tool-name projection and diagnostics. */
+    readonly engine: HostedEngineId;
+    /**
+     * The model label logged into `request/header` and message provenance.
+     *
+     * The engine's own word for "whatever it decides" when the deployment pinned
+     * none — it is what makes the session's `(provider, model)` resolve to this
+     * plugin's placeholder route entry instead of a composite string naming a
+     * model no adapter serves.
+     */
+    readonly model: string | undefined;
+    /**
+     * The environment entries the child is spawned with, layered over the
+     * credential-scrubbed parent environment.
+     */
+    readonly env: Record<string, string>;
+}
+/**
+ * The shared base for every external-CLI engine.
+ *
+ * Subclasses implement {@link runStep} only. Everything else here is the
+ * lifecycle the harness's `Agent` contract requires, written once.
+ */
+export declare abstract class CliHostedAgent implements Agent {
+    /**
+     * The context the agent was built on.
+     *
+     * Protected rather than private: a subclass's protocol round trip needs the
+     * same host reads the four original drivers make from this context (the
+     * session's model selection, the attachment service), and re-deriving them
+     * from the agent-scoped context would be a second, subtly different read.
+     */
+    protected readonly loopCtx: Context;
+    /** This agent's session id. */
+    readonly id: SessionId;
+    /** The loop options the session was built with. */
+    readonly options: AgentOptions;
+    /** The durable session this agent serves. */
+    readonly session: Session;
+    /** Engine facts the base cannot answer for itself. */
+    protected readonly hostFacts: CliAgentHost;
+    /** The durable inbox, driven from the session's own log. */
+    readonly inbox: DriverInbox;
+    /** The agent-scoped registration boundary; the lifecycle owner unwinds it after the driver exits. */
+    readonly scope: Scope;
+    /** The agent's own context, carrying the agent in its store. */
+    readonly ctx: Context;
+    /** The shared durable-log writer for this agent's lifecycle. */
+    protected readonly sink: SessionSink;
+    /** Resolves the read-only path behind each image block of the prompt. */
+    protected readonly imageAccess: ImageAttachmentAccessResolver;
+    private phase;
+    private activityDone;
+    private readonly dispatch;
+    private requestHeaderLogged;
+    /**
+     * Whether a wake was requested while the activity could not accept it.
+     *
+     * Held on the phase rather than here so it is reset with the phase, which is
+     * what makes "the last wake wins" true across a turn boundary.
+     */
+    constructor(
+    /**
+     * The context the agent was built on.
+     *
+     * Protected rather than private: a subclass's protocol round trip needs the
+     * same host reads the four original drivers make from this context (the
+     * session's model selection, the attachment service), and re-deriving them
+     * from the agent-scoped context would be a second, subtly different read.
+     */
+    loopCtx: Context, 
+    /** This agent's session id. */
+    id: SessionId, 
+    /** The loop options the session was built with. */
+    options: AgentOptions, 
+    /** The durable session this agent serves. */
+    session: Session, 
+    /** Engine facts the base cannot answer for itself. */
+    hostFacts: CliAgentHost);
+    /** The label the session's requests and messages are recorded under. */
+    protected modelLabel(): string;
+    /** The engine this agent runs. */
+    protected get engine(): HostedEngineId;
+    /** The environment entries the child is spawned with. */
+    protected get env(): Record<string, string>;
+    /**
+     * Run one step's protocol round trip.
+     *
+     * The ONLY method a subclass must implement, and the only place an engine is
+     * actually different. It is handed the position its frames belong to and must
+     * feed them to {@link CliHostedAgent.sink}; returning means the engine
+     * settled.
+     *
+     * A protocol failure (a malformed frame, a child that died mid-run) should
+     * throw — the base reports it as the turn's `error` ending. An engine that
+     * merely answered badly is NOT a protocol failure: report it through the sink
+     * (`{ kind: 'error' }`) and the base turns it into a failed turn with the
+     * engine's own words.
+     * The return value is the step's own verdict on the turn: `{ kind: 'completed' }`
+     * for an ordinary answer, `{ kind: 'max-tokens' }` when the engine hit its
+     * output ceiling, or `null` to say the sink's own verdict stands. The turn loop
+     * takes the FIRST verdict a step reports and keeps it for the turn.
+     * @param messages - the messages this step delivers.
+     * @param position - the turn/step the frames belong to.
+     * @param signal - cancellation.
+     * @returns the step's ending.
+     */
+    protected abstract runStep(messages: readonly UserMessage[], position: SinkPosition, signal: AbortSignal): Promise<StepEndReason | null>;
+    /**
+     * Called after the sink rotates to a new step, so a subclass can reset any
+     * per-step state it holds.
+     * @param step - the step number now open.
+     */
+    protected onStepRotated(step: number): void;
+    /**
+     * Release whatever the subclass opened for the step that just ended.
+     *
+     * Called from the step's `finally`, so it runs on success, failure and
+     * cancellation alike. A driver that spawns per step disposes its child here; a
+     * driver holding a persistent child leaves it.
+     */
+    protected releaseStep(): void;
+    /**
+     * The transport's own teardown, when the agent's scope is unwound.
+     *
+     * Where a persistent child is finally closed. A per-step transport has
+     * nothing to do here, because {@link releaseStep} already released it.
+     */
+    protected disposeTransport(): void;
+    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.
+     * @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;
+    /** Open one turn and run its steps until the inbox stops feeding it. */
+    private turn;
+    /**
+     * Claim this step's messages and run them past the pre-step waterfall.
+     * @param target - which inbox queue to claim from.
+     * @param position - the turn/step being proposed.
+     * @returns the step's decision.
+     */
+    private preStep;
+    /**
+     * Scan the step's user messages for `/name` skill gestures, load each matching
+     * skill, and inject the rendered content into the batch.
+     * @param messages - the step's message batch.
+     * @param signal - cancellation (aborted loads are silently dropped).
+     * @returns the original batch, or an extended one.
+     */
+    private injectSkills;
+    /**
+     * Append the session's request-header snapshot, once per loop instance.
+     *
+     * Written by the driver rather than the sink because it describes the request
+     * the ENGINE was asked to make, and only the driver knows when the first one
+     * is about to go out.
+     */
+    protected assertRequestHeader(): void;
+    /** Append a `tool/call` event for one call this step announced. */
+    protected appendToolCall(callId: string, name: string, args: string): void;
+    /** The engine-scope teardown hook, installed in the constructor. */
+    protected installTransportTeardown(): void;
+    /** The transcript this step should send, as the sink's caller sees it. */
+    protected history(): Message[];
+}
+export {};
+//# sourceMappingURL=cli-agent.d.ts.map

package/lib/types/driver-cli/cli-loop.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The shared runtime base for every external-CLI engine.
+ *
+ * Each engine's own `loop.ts` used to carry the same four lines of ceremony:
+ * resolve the subprocess service, throw a loud engine-specific error if the
+ * profile has none, and build a spawn capability that remembers the termination
+ * grace period and whether the prompt travels on stdin. That is identical for
+ * every CLI engine, so it lives here, and an engine's runtime is left with the
+ * two things that are actually its own: how to read its composition-entry knobs,
+ * and how to construct its agent.
+ *
+ * The subprocess service is still resolved LAZILY (at construction, not at
+ * plugin apply), which is the original drivers' deliberate choice and is
+ * preserved here: an engine is built only when a session actually selects it, so
+ * a profile without the subprocess service fails THAT session loud instead of
+ * stalling the whole plugin at boot.
+ *
+ * @module dsh-loop-engine-allinone/driver-cli/cli-loop
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { HostedEngineRuntime } from '../driver-core/hosted-engine-runtime.ts';
+import type { HostedAgent } from '../driver-core/hosted-engine-runtime.ts';
+import type { CliSpawnCapability } from './transport.ts';
+/**
+ * One CLI engine's creation/resume machinery.
+ *
+ * `TConfig` is the engine's own resolved configuration and `TAgent` its agent;
+ * the spawn capability is owned here so a subclass never has to thread it.
+ */
+export declare abstract class CliEngineRuntime<TConfig, TAgent extends HostedAgent> extends HostedEngineRuntime<TConfig, TAgent> {
+    /**
+     * The engine's spawn capability: the dsh subprocess seam with this engine's
+     * grace period and stdin decision already applied.
+     */
+    protected readonly spawn: CliSpawnCapability;
+    /**
+     * @param ctx - the owning context.
+     * @param label - effect-label prefix, e.g. `agentLoopQoderclicn`.
+     * @param config - already-resolved engine configuration.
+     * @param engine - the engine id, for the "needs the subprocess service" diagnostic.
+     * @param graceMs - grace period for process-tree termination.
+     * @param pipeStdin - whether this engine reads its prompt from the child's stdin.
+     */
+    constructor(ctx: Context, label: string, config: TConfig, engine: string, graceMs: number, pipeStdin: boolean);
+}
+//# sourceMappingURL=cli-loop.d.ts.map

package/lib/types/driver-cli/flatten.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Flatten one engine-reported tool result to the text a durable message stores.
+ *
+ * Its own module rather than a helper inside the sink, for one structural
+ * reason: the protocol adapters need it (`stream-json.ts` calls it for every
+ * `tool_result` block), and the sink imports the HOST plane
+ * (`@deepseek-ai/dsh-llm`, `@deepseek-ai/dsh-session`). Keeping the flattener
+ * here means an adapter can be exercised against a real CLI — as
+ * `scripts/probe/smoke-driver.ts` does — without loading a Cordis context.
+ *
+ * The rules:
+ *
+ *  - a string is the answer;
+ *  - `null`/`undefined` is empty, which the caller turns into a visible
+ *    placeholder rather than an unrenderable empty block;
+ *  - a list of blocks is joined, reading each block's own `text`;
+ *  - a block that carries no text is JSON-encoded rather than dropped, so a
+ *    structured result stays inspectable in the transcript;
+ *  - an object with a `content` member is unwrapped, because that is the
+ *    wrapper several CLIs put around their real payload.
+ *
+ * @module dsh-loop-engine-allinone/driver-cli/flatten
+ */
+/**
+ * Flatten one engine tool result to the text dsh stores.
+ *
+ * Engines report a result as a string, as a list of content blocks, or as an
+ * arbitrary JSON value; dsh's durable shape is text. Anything that is not text
+ * is JSON-encoded rather than dropped, so a structured result stays inspectable
+ * in the transcript instead of vanishing.
+ * @param result - the engine's result payload.
+ * @returns the text to store.
+ */
+export declare function flattenToolResult(result: unknown): string;
+//# sourceMappingURL=flatten.d.ts.map