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

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

@@ -0,0 +1,128 @@
+/**
+ * The normalized frame vocabulary every CLI protocol adapter maps onto.
+ *
+ * A hosted CLI speaks one of four wire families — line-delimited JSON, JSON-RPC
+ * 2.0, the Agent Client Protocol, or plain text — and each family spells the
+ * same handful of facts differently. What a driver actually has to do with those
+ * facts is identical in every case: open a turn, stream text and reasoning,
+ * announce and settle tool calls, and say how the turn ended.
+ *
+ * So the split is: a PROTOCOL ADAPTER turns wire frames into the events below,
+ * and {@link SessionSink} (`./session-sink.ts`) turns these events into the
+ * durable dsh session log. Neither half knows the other's vocabulary, and an
+ * engine driver is the small mapping in between plus its own transport.
+ *
+ * The vocabulary is deliberately narrow. Anything a protocol reports that dsh has
+ * no durable place for (a queue update, a compaction notice, an extension UI
+ * request) is simply not part of it: an adapter drops what it cannot express
+ * rather than inventing a frame the sink would have to ignore.
+ *
+ * @module dsh-loop-engine-allinone/driver-cli/frames
+ */
+/** One tool call the engine announced, before its result is known. */
+export interface ToolCallFrame {
+    /** The engine's own call id; dsh keys its pending-tool map by this. */
+    readonly id: string;
+    /** The engine's own tool name, before projection onto dsh's vocabulary. */
+    readonly name: string;
+    /** The call's arguments, as the engine sent them (a JSON string or a value). */
+    readonly arguments: unknown;
+}
+/** One tool result the engine reported for a call it announced. */
+export interface ToolResultFrame {
+    /** The call id this settles; must match an announced {@link ToolCallFrame}. */
+    readonly id: string;
+    /** The result text, already flattened to a string. */
+    readonly text: string;
+    /** Whether the engine reported the call as failed. */
+    readonly isError: boolean;
+}
+/**
+ * A protocol event, normalized.
+ *
+ * `delta` events are ordered and only meaningful inside a segment; `settle`
+ * ends the run. An adapter that cannot stream emits `text` once and then
+ * `settle` — that is exactly what the plain-text adapter does, and it is why
+ * {@link EngineCapabilities.streaming} is a declaration rather than a guess.
+ */
+export type CliFrame = 
+/** A new assistant segment began; deltas after this belong to it. */
+{
+    readonly kind: 'segment';
+}
+/**
+ * Streamed answer text.
+ *
+ * `index` is the protocol's own content-block index when it reports one, so a
+ * message with several text blocks keeps the model's own layout. An adapter
+ * that has no index leaves it out, and the sink assigns one.
+ */
+ | {
+    readonly kind: 'text';
+    readonly text: string;
+    readonly index?: number;
+}
+/** Streamed reasoning text; `index` as for the `text` member. */
+ | {
+    readonly kind: 'reasoning';
+    readonly text: string;
+    readonly index?: number;
+}
+/** The engine announced a tool call. */
+ | {
+    readonly kind: 'tool-call';
+    readonly call: ToolCallFrame;
+}
+/** The engine reported a tool result. */
+ | {
+    readonly kind: 'tool-result';
+    readonly result: ToolResultFrame;
+}
+/** Token usage for the turn, as the engine reported it. */
+ | {
+    readonly kind: 'usage';
+    readonly usage: CliUsage;
+}
+/**
+ * The engine's own verdict on the turn.
+ *
+ * A verdict is recorded rather than thrown on sight because an engine may
+ * retry: a run can report an errored attempt and still succeed, so only the
+ * verdict still standing when the stream ends is a failure
+ * ({@link CliRunOutcome}).
+ */
+ | {
+    readonly kind: 'error';
+    readonly message: string;
+}
+/** The run is over; no further frames will arrive. */
+ | {
+    readonly kind: 'settle';
+};
+/** Token usage in dsh's shape, as far as a CLI reports it. */
+export interface CliUsage {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead?: number;
+    readonly cacheWrite?: number;
+    readonly thinking?: number;
+}
+/**
+ * How one CLI run ended, after the sink folded every frame.
+ *
+ * `failed` is separate from a thrown error on purpose: an engine that reports a
+ * failed turn has still run correctly from the driver's point of view — the
+ * driver's job is to report the engine's answer, including a bad one. Only a
+ * protocol failure (a malformed stream, a child that died mid-frame) throws.
+ */
+export type CliRunOutcome = 
+/** The engine produced an answer. */
+{
+    readonly kind: 'completed';
+}
+/** The engine reported a failed turn; `message` is its own words. */
+ | {
+    readonly kind: 'failed';
+    readonly message: string;
+};
+//# sourceMappingURL=frames.d.ts.map

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

@@ -0,0 +1,106 @@
+/**
+ * The line-delimited-JSON protocol skeleton.
+ *
+ * Three of the four wire families are "one JSON document per line": the newline
+ * framing is identical, and only the FIELD NAMES inside each document differ.
+ * So the reader — split a byte stream into lines, parse each, hand it over,
+ * and surface a parse failure as a protocol error rather than silently skipping
+ * the line — lives here once, and an engine supplies only the mapping from a
+ * parsed document to {@link CliFrame}s.
+ *
+ * The reader also owns the two framing rules that are easy to get wrong and
+ * expensive to debug:
+ *
+ *  - **A trailing partial line is still a line.** A child that exits without a
+ *    final newline has still said something, so the last buffer is flushed on
+ *    close. Dropping it loses the engine's answer.
+ *  - **A blank line is not a document.** Engines interleave progress lines and
+ *    keep-alives; an empty line is skipped rather than reported as malformed.
+ *
+ * @module dsh-loop-engine-allinone/driver-cli/ndjson
+ */
+import type { Readable, Writable } from 'node:stream';
+import type { CliFrame } from './frames.ts';
+import type { CliTransport } from './transport.ts';
+/**
+ * Split a byte stream into lines.
+ *
+ * Yields each complete line WITHOUT its terminator, plus a trailing partial line
+ * when the stream ends. A line is decoded as UTF-8: every engine this plugin
+ * speaks to emits UTF-8 on its protocol channel (their own locale or OEM
+ * encodings, if any, apply to human-facing output rather than the wire).
+ * @param stream - the child's stdout.
+ * @returns an async iterator of lines.
+ */
+export declare function readLines(stream: Readable): AsyncIterable<string>;
+/**
+ * Parse one NDJSON line.
+ * @param line - the raw line.
+ * @returns the parsed document, or undefined when the line is blank or not JSON.
+ */
+export declare function parseJsonLine(line: string): unknown;
+/** What one NDJSON run needs. */
+export interface NdjsonRunSpec {
+    /** The spawned child. */
+    readonly transport: CliTransport;
+    /**
+     * A payload to write to the child's stdin before reading, when the prompt
+     * travels that way (`agy --input-format stream-json`). Omitted when the
+     * prompt is an argv argument.
+     */
+    readonly stdin?: string;
+    /**
+     * Map one parsed document to frames.
+     *
+     * Returning an empty array is normal: most protocol lines are progress,
+     * session bookkeeping or telemetry that has no durable place. Returning
+     * nothing at all is also normal for a document the adapter does not
+     * recognize — an unknown frame is DROPPED rather than raised, because a
+     * protocol that grows a new notification kind must not break a working
+     * engine.
+     * @param document - the parsed JSON document.
+     * @returns the frames it expresses, in order.
+     */
+    map(document: unknown): readonly CliFrame[];
+    /**
+     * Called when a non-blank line could not be parsed as JSON.
+     *
+     * Counted rather than raised, and only reported at the end: a child that
+     * prints a warning on its protocol channel is common, and failing the whole
+     * turn over one stray line would be worse than reporting it. If NO line ever
+     * parsed, the run fails and this is what says why.
+     * @param line - the unparseable line.
+     */
+    onUnparsed?(line: string): void;
+}
+/** What one NDJSON run produced. */
+export interface NdjsonRunResult {
+    /** Documents that parsed. */
+    readonly parsed: number;
+    /** Non-blank lines that did not parse. */
+    readonly unparsed: number;
+    /** The last unparseable line, for the diagnostic when nothing parsed. */
+    readonly lastUnparsed: string | undefined;
+}
+/**
+ * Drive one NDJSON run: write the prompt, decode every line, feed the adapter.
+ *
+ * Frames are handed to `accept` as they arrive rather than collected, so a
+ * long answer streams instead of materializing.
+ * @param spec - the run's transport, stdin payload and frame mapper.
+ * @param accept - sink for the frames.
+ * @returns what the run saw.
+ */
+export declare function runNdjson(spec: NdjsonRunSpec, accept: (frame: CliFrame) => void): Promise<NdjsonRunResult>;
+/**
+ * Write a payload to the child's stdin and close it.
+ *
+ * Closing matters: an engine reading `stream-json` from stdin runs one turn per
+ * line and waits, so a stdin left open hangs the run until the process is
+ * killed. A write failure is swallowed — the child may have exited already, and
+ * the exit code is the more useful diagnostic.
+ * @param stdin - the child's stdin, when the spawn requested a pipe.
+ * @param payload - the text to write.
+ */
+export declare function writeStdin(stdin: Writable | undefined, payload: string): void;
+//# sourceMappingURL=ndjson.d.ts.map

package/lib/types/driver-cli/session-sink.d.ts

@@ -0,0 +1,333 @@
+/**
+ * The shared session sink: one implementation of "turn these frames into the
+ * durable dsh session log", used by every CLI driver.
+ *
+ * This is the half of a driver that is genuinely hard to get right, and it is
+ * identical for every engine, so it lives in exactly one place. What it owns:
+ *
+ *  - **The assistant-message lifecycle.** Content arrives as deltas, is held,
+ *    and is committed as a durable `assistant/message` at a boundary. The live
+ *    attempt's frames are published as `agent/assistant-stream` and its compact
+ *    stream travels with the message ({@link DriverAssistantStream}).
+ *  - **The tool-call/tool-result pairing Session V4 enforces.** A `tool/result`
+ *    must follow the `assistant/message` that carries its `tool-call` block, and
+ *    each call may be settled EXACTLY once — a second result for one id is
+ *    refused on load and bricks the whole session log. Engines report results
+ *    inconsistently (twice for one execution, or before the message that
+ *    requested it), so this class synthesizes the owning message when it has to
+ *    and drops the repeat.
+ *  - **Step rotation.** A settled tool result means the segment that ran it is
+ *    complete, so the next assistant content belongs to a new step. Rotating at
+ *    a message boundary keeps the calls one model turn announced together in one
+ *    step. A step that still OWES a result never rotates — that would strand the
+ *    call in a step that can never resolve it, which is itself a log V4 refuses.
+ *  - **Closing a step honestly.** `closeStep` writes an explicit failure result
+ *    for every call still unsettled, because a `step/end` carrying an unresolved
+ *    announcement is a log that will not load.
+ *
+ * What it deliberately does NOT own: the turn/step loop, cancellation, the
+ * inbox, the prompt, and the protocol. Those stay in the driver, because they
+ * are where engines actually differ.
+ *
+ * @module dsh-loop-engine-allinone/driver-cli/session-sink
+ */
+import type { AgentEventDispatch } from '@deepseek-ai/dsh-agent';
+import type { ContentBlock, Message, TokenUsage } from '@deepseek-ai/dsh-llm';
+import { ToolCallId } from '@deepseek-ai/dsh-llm';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { CliFrame, CliUsage } from './frames.ts';
+import type { HostedEngineId } from '../engine-registry.ts';
+/** Where one run's frames land: the session position they belong to. */
+export interface SinkPosition {
+    /** The durable turn owning this run. */
+    turn: number;
+    /** The durable step this run opened on; the sink may rotate it. */
+    step: number;
+}
+/**
+ * What the sink needs from the driver it serves.
+ *
+ * Passed as a small interface rather than as the driver itself, so the sink can
+ * be tested without a driver and so it is obvious what it depends on. Every
+ * member is a question the sink cannot answer itself: which engine is speaking
+ * (tool-name projection is per-engine), which provider label to log, and where
+ * the live attempt's frames go.
+ */
+export interface SinkHost {
+    /** The session being written. */
+    readonly session: Session;
+    /** This agent's session id, for the attempt identity of a live stream. */
+    readonly sessionId: SessionId;
+    /** The engine whose vocabulary tool names are projected from. */
+    readonly engine: HostedEngineId;
+    /** The provider route label logged into message provenance. */
+    readonly provider: string;
+    /** The model label logged into message provenance. */
+    readonly model: string;
+    /** Agent-scoped notification publisher, for live stream frames. */
+    readonly dispatch: AgentEventDispatch;
+    /**
+     * Called when the sink rotates to a new step, so the driver can record the
+     * rotation and re-run whatever it owes a fresh step (announcing the step,
+     * re-checking the system head).
+     *
+     * The sink rotates; the DRIVER owns what a rotation means for its own
+     * bookkeeping, which is why this is a callback rather than something the sink
+     * does silently.
+     * @param step - the step number now open.
+     */
+    onStepRotated(step: number): void;
+}
+/**
+ * The shared sink. One instance per agent lifecycle.
+ *
+ * Not re-entrant and not concurrent: a session runs one step at a time, and the
+ * sink's buffers describe that one run. A second concurrent run on one session
+ * is refused upstream (the router never hands a live session to two machines).
+ */
+export declare class SessionSink {
+    private readonly host;
+    private readonly stepTools;
+    /** Calls announced in this step whose results have landed. */
+    private settledTools;
+    /** This run's live attempt, opened on the first chunk and settled by a message. */
+    private live;
+    /** Agent-lifecycle-local attempt counter, naming each streamed attempt. */
+    private streamAttempts;
+    /** The assistant message being assembled, if any. */
+    private held;
+    /** Text blocks already block-start-ed, by content index. */
+    private readonly startedText;
+    /** Reasoning blocks already block-start-ed, by content index. */
+    private readonly startedReasoning;
+    /** Reasoning accumulated by content index, for engines that stream it without a final block. */
+    private readonly thinkingByIndex;
+    /**
+     * Answer text accumulated by content index.
+     *
+     * Present so a message can be built from the DELTAS when the protocol never
+     * hands over a finished message — and so a whole-message commit can replace
+     * the accumulation instead of double-counting it.
+     */
+    private readonly textByIndex;
+    /**
+     * The content-block index each kind is currently appending to, and the next
+     * index to hand out when a kind starts a new block.
+     *
+     * Kept per kind rather than shared because text and reasoning interleave: a
+     * reasoning chunk between two text chunks must not split the text.
+     */
+    private readonly openIndex;
+    private nextIndex;
+    /** Call ids already announced, so a protocol that repeats one announces it once. */
+    private readonly announced;
+    /** Call ids already written a result, so a repeated report is dropped. */
+    private readonly settled;
+    /** Tool-call blocks not yet folded into a flushed assistant message. */
+    private pendingToolCalls;
+    /** `tool/call` events owed by the pending blocks, appended once their message lands. */
+    private pendingCallLog;
+    /** Calls released by the flush that just folded their owner message. */
+    private callsToLog;
+    /** Last usage snapshot, folded onto the message that closes the run. */
+    private lastUsage;
+    /** The engine's standing verdict on this run; cleared by a later successful report. */
+    private failure;
+    /** Whether an assistant message was already committed for this run. */
+    private assistantFlushed;
+    /** Whether a segment has been opened (so a `segment` frame before content is not double-counted). */
+    private segmentOpen;
+    constructor(host: SinkHost);
+    /**
+     * @param host - the driver-side facts the sink cannot answer itself.
+     */
+    /** Reset per-step bookkeeping. Called by the driver when a step opens. */
+    beginStep(): void;
+    /**
+     * Reset the per-RUN bookkeeping that must not leak between steps.
+     *
+     * `announced` and `settled` are deliberately NOT reset: call ids are unique
+     * for the life of a session, so retaining them only widens duplicate
+     * suppression and can never hide a legitimate result. A protocol that reuses
+     * an id across steps would be malformed anyway.
+     */
+    beginRun(): void;
+    /** The step number currently open, as the sink has rotated it. */
+    stepOf(position: SinkPosition): number;
+    /** The calls this step still owes a result, in announcement order. */
+    get pendingCalls(): readonly ToolCallId[];
+    /**
+     * The engine's standing verdict on the run so far.
+     * @returns the failure message, or undefined when the run is not (or no longer) failed.
+     */
+    get runFailure(): string | undefined;
+    /**
+     * Consume one normalized frame.
+     *
+     * The position object is mutated in place when the sink rotates a step, so the
+     * caller's own view of "which step is open" follows — that is what keeps the
+     * turn loop's fail-safe step close on the step that is actually open rather
+     * than the one the run started under.
+     * @param frame - the normalized frame.
+     * @param position - the turn/step this run belongs to; `step` may be bumped.
+     */
+    accept(frame: CliFrame, position: SinkPosition): void;
+    /**
+     * Open a new assistant segment.
+     *
+     * A segment after a settled tool result is the next step: the previous
+     * segment is complete and the content about to arrive belongs to the next one.
+     * A step that still owes a result does not rotate (see the module note).
+     * @param position - the open position, mutated when a rotation happens.
+     */
+    private openSegment;
+    /** Close the step currently open, writing explicit failures for anything unsettled. */
+    private closeOpenStep;
+    /**
+     * Close the step the sink currently holds, for the driver's step teardown.
+     * @param position - the open position.
+     */
+    closeStep(position: SinkPosition): void;
+    /** Open the step's own surface head, once, when the driver opens a step. */
+    openStep(position: SinkPosition): void;
+    /**
+     * Stream one chunk: publish its live frame AND accumulate it into the durable
+     * message being built.
+     *
+     * The two halves are both required and neither implies the other. The live
+     * frames are what the UI paints while the answer arrives; the accumulated
+     * blocks are what the session log stores. Accumulating only the frames (or
+     * only the blocks) produces a session whose durable message is missing the
+     * text the user watched being written — which is why this is one function.
+     *
+     * Blocks are keyed by content index, so a protocol that reports its own index
+     * keeps the model's own block layout, and one that does not gets a fresh block
+     * per switch between text and reasoning. Either way the durable message folds
+     * reasoning before text, matching the ordering the in-process loop produces.
+     * @param kind - whether this is answer text or reasoning.
+     * @param text - the delta.
+     * @param position - the open position, for the live attempt's framing.
+     * @param explicitIndex - the protocol's own content index, when it reports one.
+     */
+    private streamChunk;
+    /**
+     * The live attempt for the current segment, opened on first use.
+     *
+     * Chunks open one; the durable assistant message they built settles it and the
+     * next chunk opens a fresh attempt, so every message carries exactly its own
+     * timed stream.
+     * @param position - the open position, for the attempt's turn/step framing.
+     * @returns the live attempt.
+     */
+    private currentStream;
+    /**
+     * Record one announced tool call.
+     *
+     * The call is projected onto dsh's vocabulary ONCE, and the same projected
+     * name and arguments go to both the assistant message's `tool-call` block and
+     * the durable `tool/call` event — Session V4 pairs the two by id and refuses a
+     * log whose block and event disagree.
+     * @param call - the announced call.
+     */
+    private emitToolCall;
+    /**
+     * Settle one tool call, exactly once.
+     *
+     * The owning assistant message is flushed first when the call has none yet:
+     * the durable surface must always pair a result with a preceding assistant
+     * `tool-call` block, and an engine that executed a call without streaming an
+     * assistant message first would otherwise leave the result orphaned.
+     * @param id - the call being settled.
+     * @param text - the result text.
+     * @param isError - whether the engine reported a failure.
+     * @param position - the open position.
+     */
+    private settleTool;
+    /**
+     * Flush a synthesized assistant message carrying any tool-call blocks that have
+     * no committed owner yet.
+     * @param position - the open position.
+     */
+    private ensureToolCallOwner;
+    /**
+     * Commit the held assistant message, if any.
+     * @param position - the open position.
+     * @param usage - usage to attach, when this message closes the run.
+     */
+    private flushHeld;
+    /**
+     * Drop the deltas accumulated for the segment being replaced.
+     *
+     * A protocol that streams partials AND hands over a finished message has said
+     * the same thing twice; the finished message is authoritative, so the partials
+     * are discarded rather than committed as a second message.
+     */
+    private clearAccumulation;
+    /**
+     * Build the content blocks the streamed deltas accumulated.
+     *
+     * Reasoning first, then text: that is the ordering the in-process loop's own
+     * messages use, and a durable message that put the answer before the model's
+     * reasoning would read wrong on replay.
+     * @returns the accumulated blocks, in durable order.
+     */
+    private accumulatedBlocks;
+    /** Fold any not-yet-flushed tool-call blocks into the message being committed. */
+    private foldPendingCalls;
+    /**
+     * Commit the assistant message a whole-message protocol reports.
+     *
+     * A text-protocol engine has no deltas: it hands over a finished answer, and
+     * this is where it becomes the same durable shape a streaming engine produces.
+     * Reasoning is folded in before the text, matching the ordering the in-process
+     * loop produces, and any reasoning the protocol streamed but omitted from its
+     * final message is preserved rather than lost.
+     * @param text - the answer text.
+     * @param reasoning - the reasoning text, when the engine reported it separately.
+     * @param position - the open position.
+     */
+    commitWholeMessage(text: string, reasoning: string | undefined, position: SinkPosition): void;
+    /**
+     * Commit a message built from an authoritative content-block list.
+     *
+     * The streaming engines' path: the protocol's own final message is the source
+     * of truth, and anything it omits that was streamed (reasoning, pending tool
+     * calls) is folded back in so the durable log never loses content the model
+     * produced.
+     * @param content - the blocks the protocol reported.
+     * @param position - the open position.
+     * @param usage - usage to attach when this closes the run.
+     */
+    commitBlocks(content: ContentBlock[], position: SinkPosition, usage?: TokenUsage): void;
+    /**
+     * Finish the run: commit anything still held and report the engine's verdict.
+     *
+     * The verdict is checked before "did we commit a message", because an engine
+     * can settle cleanly with every turn failed (and send no reply at all);
+     * reporting that as success would hand the user a silent, empty turn. Its own
+     * words are the more useful thing to report in that case.
+     * @param position - the open position.
+     * @returns how the run ended.
+     */
+    finish(position: SinkPosition): {
+        kind: 'completed';
+    } | {
+        kind: 'failed';
+        message: string;
+    };
+}
+/**
+ * Project one engine-reported usage record onto dsh's `TokenUsage`.
+ *
+ * Absent fields are omitted rather than defaulted to zero: dsh distinguishes
+ * "reported zero" from "not reported", and a fabricated zero would corrupt the
+ * context accounting the compaction path reads.
+ * @param usage - the engine's usage record.
+ * @returns dsh's usage shape.
+ */
+export declare function mapUsage(usage: CliUsage): TokenUsage;
+export { flattenToolResult } from './flatten.ts';
+/** A message from any source, for the drivers that re-read the transcript. */
+export type SinkMessage = Message;
+//# sourceMappingURL=session-sink.d.ts.map

package/lib/types/driver-cli/stream-json.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The Claude-Code-compatible `stream-json` adapter.
+ *
+ * A whole family of CLIs speak one shared `--output-format stream-json`
+ * dialect: Claude Code itself, and the forks built on it (Qoder's CLI among
+ * them — verified by probing `qoderclicn -p --output-format stream-json`, whose
+ * frames carry the same `type`/`subtype`/`session_id` vocabulary). The dialect
+ * is NDJSON, one document per line, with four document kinds that matter:
+ *
+ *   - `system` / `init` — the session opened; carries `session_id`, the model
+ *     and the tool list. Useful for resume and diagnostics, no durable content.
+ *   - `assistant` — one assistant message, whose `message.content` is a list of
+ *     Anthropic-shaped blocks (`text`, `thinking`, `tool_use`). This is where
+ *     the answer and the tool calls come from.
+ *   - `user` — a tool RESULT being fed back (`tool_result` blocks). A CLI that
+ *     runs its own tools reports the outcome here.
+ *   - `result` — the run ended; carries `result` (the final text), `is_error`,
+ *     `usage` and the session id.
+ *
+ * Because the dialect is shared, the mapping lives here once and each engine
+ * supplies only its transport. That is also why tool names are NOT projected
+ * here: projection is per-engine (`normalizeHostedToolCall`), so this module
+ * reports the engine's own spelling and the sink projects it.
+ *
+ * Everything the dialect can carry that has no durable place — `hook_started`,
+ * `hook_progress`, `hook_response`, `artifacts_update`, `stream_event` and any
+ * future notification — is DROPPED rather than raised. A CLI that grows a new
+ * notification must not break a working driver.
+ *
+ * @module dsh-loop-engine-allinone/driver-cli/stream-json
+ */
+import type { CliFrame, CliUsage } from './frames.ts';
+/** What one stream-json run's frames were accepted by. */
+export type FrameSink = (frame: CliFrame) => void;
+/** What the adapter learned about the run beyond its frames. */
+export interface StreamJsonRun {
+    /** The session id the CLI reported, when it reported one. */
+    readonly sessionId: string | undefined;
+    /** Whether the CLI's own `result` document said the run failed. */
+    readonly reportedError: string | undefined;
+}
+/**
+ * Project one stream-json usage record onto {@link CliUsage}.
+ * @param usage - the engine's usage record.
+ * @returns the usage, omitting everything not reported.
+ */
+export declare function streamJsonUsage(usage: unknown): CliUsage | undefined;
+/**
+ * Map one parsed stream-json document to frames.
+ *
+ * The returned `run` is the adapter's accumulated knowledge (the session id and
+ * the CLI's own verdict), which the caller needs on top of the frames.
+ * @param document - the parsed document.
+ * @param accept - frame sink.
+ * @param run - the accumulator, updated in place.
+ */
+export declare function mapStreamJsonDocument(document: unknown, accept: FrameSink, run: {
+    sessionId: string | undefined;
+    reportedError: string | undefined;
+}): void;
+//# sourceMappingURL=stream-json.d.ts.map