indusagi-coding-agent 0.1.59 → 0.1.60

package/dist/types/launch/pickers.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Launch pickers — `pickResumeTarget` and `browseSettings`.
+ *
+ * Two thin, injectable selection surfaces:
+ *
+ *   - {@link pickResumeTarget} loads the resumable sessions (current cwd plus
+ *     every directory), de-duplicates by path, sorts newest-first, and lets the
+ *     user choose one through the framework React-Ink `StartupSessionPicker`. On a
+ *     non-interactive stdin it skips the picker and resolves the newest session,
+ *     so a piped invocation still resumes deterministically.
+ *
+ *   - {@link browseSettings} prints a plain readline listing of the resolved
+ *     settings and the discovered user resources, then waits for a keypress. No
+ *     TUI — a flat console dump the user reads and dismisses.
+ *
+ * Both keep their effectful pieces (the Ink mount, the readline pause, the TTY
+ * probe) behind injectable seams so the selection logic is unit-testable without
+ * a terminal.
+ */
+import type { ResumeFault, ResumeRef, SessionLoader, SettingsBrowseOptions } from "./contract";
+/**
+ * The effectful seams {@link pickResumeTarget} depends on. Injected so a test can
+ * report a non-interactive terminal and stub the picker mount.
+ */
+export interface ResumeDeps {
+    /** Whether stdin is an interactive terminal (drives the non-TTY fast-path). */
+    isInteractive(): boolean;
+    /**
+     * Mount the picker over the session list and resolve with the chosen session,
+     * or `null` when the user dismisses it.
+     */
+    mountPicker(sessions: readonly ResumeRef[], totalCount: number): Promise<ResumeRef | null>;
+}
+/** The live {@link ResumeDeps}: a real TTY probe and the Ink picker mount. */
+export declare function defaultResumeDeps(): ResumeDeps;
+/**
+ * Merge two session lists into one newest-first list de-duplicated by path.
+ *
+ * Earlier entries win the path key, then the merged set is sorted by
+ * `lastModified` descending. Pure; the picker and the fast-path both consume it.
+ */
+export declare function mergeSessions(current: readonly ResumeRef[], all: readonly ResumeRef[]): ResumeRef[];
+/**
+ * The outcome of {@link pickResumeTarget}: the chosen session path, or `null`
+ * when there was nothing to resume or the user dismissed the picker. A typed
+ * {@link ResumeFault} is returned (never thrown) when the load or mount failed.
+ */
+export interface ResumeOutcome {
+    /** The selected session file path, or `null` for none. */
+    readonly path: string | null;
+    /** A typed failure, present only when the resume flow could not run. */
+    readonly fault?: ResumeFault;
+}
+/**
+ * Choose a session to resume.
+ *
+ * Loads the current-directory and all-directory session lists, merges them
+ * (de-dupe by path, newest first), and either mounts the React-Ink picker or —
+ * on a non-interactive stdin — resolves the newest session directly. An empty
+ * merged list resolves to `{ path: null }`.
+ *
+ * @param loadCurrent loader for sessions started in the active cwd
+ * @param loadAll     loader for sessions across every directory
+ * @param deps        injectable TTY probe and picker mount (defaults to live)
+ */
+export declare function pickResumeTarget(loadCurrent: SessionLoader, loadAll: SessionLoader, deps?: ResumeDeps): Promise<ResumeOutcome>;
+/**
+ * The effectful seams {@link browseSettings} depends on: a line sink and a pause
+ * that waits for the user to press a key. Injected so a test captures the listing
+ * and resolves the pause immediately.
+ */
+export interface SettingsBrowseIo {
+    /** Emit one line of the listing. */
+    print(line: string): void;
+    /** Wait for the user to dismiss the listing (e.g. press Enter). */
+    pause(prompt: string): Promise<void>;
+}
+/** The live {@link SettingsBrowseIo}: stdout plus a readline pause. */
+export declare function defaultSettingsBrowseIo(): SettingsBrowseIo;
+/**
+ * Build the entire settings listing as an array of lines. Pure — it consumes the
+ * resolved settings, the active cwd, the profile directory, and the grouped
+ * resource paths, and produces the flat dump {@link browseSettings} prints. Kept
+ * separate so a test can assert the content without an io seam.
+ */
+export declare function renderSettingsListing(opts: SettingsBrowseOptions): string[];
+/**
+ * Print the settings / resource listing and wait for the user to dismiss it.
+ *
+ * A plain console dump — no TUI. It renders the resolved settings summary and the
+ * discovered resources grouped by category, then pauses for a keypress so the
+ * listing stays on screen.
+ *
+ * @param opts the resolved settings, resource paths, cwd, and profile directory
+ * @param io   the injectable line sink and pause (defaults to stdout + readline)
+ */
+export declare function browseSettings(opts: SettingsBrowseOptions, io?: SettingsBrowseIo): Promise<void>;

package/dist/types/runtime-bridge/bridges/_drive.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Shared exchange driver — the transport-wiring half every bridge reuses.
+ *
+ * A bridge is meant to be *only* a per-dialect parser. Two concerns are common
+ * to all three shipped bridges and are factored here so a bridge never repeats
+ * them:
+ *
+ *   1. The lifecycle wiring: subscribe to the {@link ChildTransport}, forward
+ *      each inbound {@link ChildMessage} to the bridge's parser, settle the sink
+ *      on a terminal parser result, honour the caller's {@link AbortSignal}, and
+ *      always dispose the subscription + transport on the way out.
+ *   2. The seed: deriving the {@link BridgeMessageSeed} the sink stamps onto the
+ *      accumulated message from the bound {@link Model}.
+ *
+ * A bridge supplies a {@link ChildParser} (pure: child payload -> parser result)
+ * and an opening {@link ChildRequest}; {@link driveExchange} does the rest and
+ * returns the populated {@link AssistantMessageEventStream}.
+ *
+ * Crucially this module touches the transport only through the injected
+ * interface — no `child_process`, no `spawn`. A test hands a fake transport and
+ * drives the parser end-to-end with zero real binaries.
+ */
+import type { AssistantMessageEventStream, BridgeEventSink, ChildMessage, ChildRequest, ChildTransport, ExchangeOptions, Model, Api } from "../contract";
+import { type BridgeMessageSeed } from "../sink";
+/**
+ * The outcome a parser reports for one inbound child payload. A parser maps a
+ * single {@link ChildMessage} payload to the normalized events it produced and
+ * whether that payload terminated the exchange.
+ *
+ *   - `continue`  — zero or more events were emitted; the stream stays open.
+ *   - `done`      — the exchange settled (the parser already emitted the
+ *                   `finish` / `failed` event, or the driver should finish with
+ *                   the default reason). No further payloads are processed.
+ */
+export type ParseStep = {
+    readonly status: "continue";
+} | {
+    readonly status: "done";
+};
+/**
+ * A per-dialect parser: interpret one inbound child payload, drive the sink with
+ * whatever normalized events it yields, and report whether the exchange is over.
+ *
+ * The parser owns *interpretation* only; it never touches the framework stream
+ * directly — it calls sink methods (`text` / `thinking` / `toolCall` / `emit` /
+ * `finishSuccess` / `finishError`). Returning `{ status: "done" }` tells the
+ * driver to stop and (if the sink is not already settled) finish successfully.
+ */
+export type ChildParser = (message: ChildMessage, sink: BridgeEventSink) => ParseStep;
+/** Derive the message seed the sink stamps onto its accumulated message. */
+export declare function seedFromModel(model: Model<Api>): BridgeMessageSeed;
+/**
+ * Drive a full exchange over an injected transport.
+ *
+ * Returns the sink's {@link AssistantMessageEventStream} synchronously; the
+ * stream is populated asynchronously as the child emits. The driver:
+ *   - subscribes the parser to inbound messages;
+ *   - sends the opening request;
+ *   - settles + tears down on a terminal parse step, transport closure, abort,
+ *     or thrown parser error.
+ *
+ * @param model     the bound model (seeds the sink identity)
+ * @param opts      per-exchange options (only `signal` is consulted here)
+ * @param transport the injected child boundary
+ * @param request   the opening request to send once subscribed
+ * @param parse     the per-dialect parser
+ */
+export declare function driveExchange(model: Model<Api>, opts: ExchangeOptions, transport: ChildTransport, request: ChildRequest, parse: ChildParser): AssistantMessageEventStream;
+/** Best-effort single-line message for an unknown thrown value. */
+export declare function errorText(cause: unknown): string;
+/** Narrow an opaque payload to a string-keyed record (or `undefined`). */
+export declare function asRecord(value: unknown): Record<string, unknown> | undefined;
+/** Read a string field off a record, or `undefined` when absent/non-string. */
+export declare function strField(record: Record<string, unknown>, key: string): string | undefined;

package/dist/types/runtime-bridge/bridges/builtins.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Built-in external-runtime catalog — the shipped {@link ExternalRuntimeSpec}
+ * entries and the helper that *annotates* a model with one.
+ *
+ * The model catalog (Phase 2, `src/conductor/catalog`) owns the {@link Model}
+ * list; this layer never re-catalogues. Instead it carries a small table of the
+ * three runtimes this build ships and a single sanctioned way to stamp a runtime
+ * onto a model: rewrite the model's `baseUrl` to the synthetic
+ * `bridge:<adapter>` endpoint (so a card has a stable, non-HTTP address) and
+ * return the runtime annotation alongside it.
+ *
+ * Why a `baseUrl` rewrite rather than a new field on the card: the catalog card
+ * shape is frozen by Phase 2 and the framework {@link Model} has a fixed shape;
+ * the `bridge:<adapter>` convention lets a routing consumer recognize a
+ * runtime-backed model purely from its address (`baseUrl.startsWith(scheme)`),
+ * with the full spec resolved from this table — no schema change to the catalog.
+ */
+import type { CatalogCard } from "../../conductor/catalog";
+import { type Api, type ExternalRuntimeSpec, type Model, type RuntimeAdapterId } from "../contract";
+/**
+ * The three runtimes this build ships, keyed by adapter id.
+ *
+ * Each is `external-cli` (the spawned child owns its own login), so a model
+ * bound to one is offered as available with an empty credential vault. The
+ * `binaryPath` names the default executable the broker launches when a model's
+ * spec does not override it; `args` are extra flags prepended ahead of the
+ * bridge's own protocol flags.
+ */
+export declare const BUILTIN_RUNTIME_SPECS: Readonly<Record<RuntimeAdapterId, ExternalRuntimeSpec>>;
+/** The shipped adapter ids, in catalog order. */
+export declare const BUILTIN_ADAPTERS: readonly RuntimeAdapterId[];
+/** Look up a shipped {@link ExternalRuntimeSpec} by adapter id (`undefined` if none). */
+export declare function builtinRuntimeSpec(adapter: RuntimeAdapterId): ExternalRuntimeSpec | undefined;
+/**
+ * A model annotated with its external runtime: the rewritten framework model
+ * (its `baseUrl` now the `bridge:<adapter>` synthetic endpoint) paired with the
+ * resolved {@link ExternalRuntimeSpec}. This is the value a routing consumer
+ * stores in its side table keyed by canonical id.
+ */
+export interface RuntimeAnnotatedModel {
+    /** The framework model with its `baseUrl` rewritten to the synthetic endpoint. */
+    readonly model: Model<Api>;
+    /** The runtime spec the {@link RuntimeBroker} drives this model through. */
+    readonly spec: ExternalRuntimeSpec;
+}
+/**
+ * Rewrite a framework {@link Model}'s `baseUrl` to the synthetic
+ * `bridge:<adapter>` endpoint for `spec.adapter`. Returns a fresh model; the
+ * input is never mutated.
+ */
+export declare function withRuntimeEndpoint(model: Model<Api>, spec: ExternalRuntimeSpec): Model<Api>;
+/**
+ * Annotate one {@link CatalogCard} with a runtime spec.
+ *
+ * Resolves the spec from `spec` when given explicitly, else from the shipped
+ * table by `adapter`. Returns the card's framework model rewritten to the
+ * synthetic endpoint plus the resolved spec, or `undefined` when no spec is
+ * known for `adapter` (so a caller can skip non-runtime adapters).
+ *
+ * @param card    the catalog card whose model to annotate
+ * @param adapter the runtime adapter to bind the model to
+ * @param spec    an explicit spec override; defaults to the shipped one
+ */
+export declare function annotateCard(card: CatalogCard, adapter: RuntimeAdapterId, spec?: ExternalRuntimeSpec): RuntimeAnnotatedModel | undefined;
+/**
+ * Decode the runtime annotation off a framework {@link Model}, the inverse of
+ * {@link withRuntimeEndpoint}. Returns the shipped {@link ExternalRuntimeSpec}
+ * for the adapter named in a `bridge:<adapter>` `baseUrl`, or `undefined` when
+ * the model is a plain HTTP-provider model (its `baseUrl` is a real URL) or the
+ * named adapter is not a shipped runtime.
+ *
+ * This is the lookup a {@link RuntimeBroker} uses to recognize a runtime-backed
+ * model purely from its address.
+ *
+ * @param model the model whose `baseUrl` to inspect
+ */
+export declare function specFromModel(model: Model<Api>): ExternalRuntimeSpec | undefined;

package/dist/types/runtime-bridge/bridges/claude-cli.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `claude-cli` bridge — drives an Anthropic-flavoured CLI that emits
+ * line-delimited stream-json content blocks.
+ *
+ * Wire dialect (each inbound {@link ChildMessage.payload} is one parsed JSON
+ * line of the CLI's NDJSON stdout):
+ *   - `{ type: "system", subtype: "init", session_id }` — the CLI announces the
+ *     session id it allocated; surfaced as a `resume` event so the broker can
+ *     persist it and reattach the same CLI session later.
+ *   - `{ type: "content_block_start", content_block: { type } }` — a block opens;
+ *     a `tool_use` block carries `{ id, name, input }` which becomes a fully
+ *     formed tool call immediately (the CLI batches the input).
+ *   - `{ type: "content_block_delta", delta: { type, text | thinking } }` — a
+ *     `text_delta` / `thinking_delta` chunk; mapped to a `text` / `thinking`
+ *     normalized event. `input_json_delta` chunks (streamed tool arguments) are
+ *     ignored here because the bridge emits the tool call from the terminal
+ *     `content_block_stop` snapshot.
+ *   - `{ type: "message_delta", delta: { stop_reason } }` — carries the final
+ *     stop reason, recorded for the eventual `finish`.
+ *   - `{ type: "message_stop" }` / `{ type: "result" }` — the turn is over;
+ *     finish with the recorded reason.
+ *   - `{ type: "error", error: { message } }` — a runtime fault.
+ *
+ * The opening request is the user turn forwarded as the CLI's prompt body; the
+ * spec's binary/args/env are the {@link RuntimeBroker}'s concern when it builds
+ * the transport, so this bridge only formats the protocol body.
+ *
+ * The child process is reached exclusively through the injected
+ * {@link ChildTransport}; no `claude` binary is spawned here.
+ */
+import type { RuntimeBridge } from "../contract";
+/**
+ * The `claude-cli` {@link RuntimeBridge}. Stateless on the contract surface: it
+ * parses the injected transport's stream-json into the sink and returns the
+ * framework push stream.
+ */
+export declare const claudeCliBridge: RuntimeBridge;

package/dist/types/runtime-bridge/bridges/codex-cli.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `codex-cli` bridge — drives an OpenAI-flavoured CLI emitting `--json`
+ * turn/item events.
+ *
+ * Wire dialect (each inbound {@link ChildMessage.payload} is one parsed `--json`
+ * event object):
+ *   - `{ type: "thread.started", thread_id }` — the CLI opened a thread;
+ *     surfaced as a `resume` event so the broker can persist the thread id and
+ *     continue it on a later exchange.
+ *   - `{ type: "response.output_text.delta", delta }` — a chunk of answer text.
+ *   - `{ type: "response.reasoning_text.delta" | "response.reasoning.delta",
+ *        delta }` — a chunk of reasoning text.
+ *   - `{ type: "response.output_item.done", item }` /
+ *     `{ type: "item.completed", item }` — a completed item; a
+ *     `function_call` / `tool_call` item becomes a fully-formed tool call (its
+ *     `arguments` string is parsed into an object).
+ *   - `{ type: "turn.completed" | "response.completed" }` — the turn settled;
+ *     finish (tool-bearing turns settle as `toolUse`, else `stop`).
+ *   - `{ type: "error" | "turn.failed", error | message }` — a runtime fault.
+ *
+ * Item-level `*.delta` text is preferred; if a CLI variant only emits whole
+ * items, the completed-item handler still surfaces the text. The injected
+ * {@link ChildTransport} carries the events — no `codex` binary is spawned here.
+ */
+import type { RuntimeBridge } from "../contract";
+/** The `codex-cli` {@link RuntimeBridge}. */
+export declare const codexCliBridge: RuntimeBridge;

package/dist/types/runtime-bridge/bridges/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Bridges subsystem — public barrel.
+ *
+ * Bundles the three shipped external-runtime {@link RuntimeBridge}s — the
+ * Anthropic-flavoured `claude-cli`, the OpenAI-flavoured `codex-cli`, and the
+ * peer JSON-RPC `indusagi-cli` — plus the built-in runtime spec catalog and the
+ * model-annotation helpers. Consumers register the bridges with a
+ * {@link RuntimeBroker} and annotate catalog cards via this barrel rather than
+ * reaching into the individual modules.
+ */
+export { claudeCliBridge } from "./claude-cli";
+export { codexCliBridge } from "./codex-cli";
+export { indusagiCliBridge, makeIndusagiCliBridge } from "./indusagi-cli";
+export { BUILTIN_RUNTIME_SPECS, BUILTIN_ADAPTERS, builtinRuntimeSpec, annotateCard, withRuntimeEndpoint, specFromModel, type RuntimeAnnotatedModel, } from "./builtins";
+export { driveExchange, seedFromModel, asRecord, strField, errorText, type ChildParser, type ParseStep, } from "./_drive";

package/dist/types/runtime-bridge/bridges/indusagi-cli.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `indusagi-cli` bridge — drives a peer agent over JSON-RPC.
+ *
+ * Unlike the CLI bridges, the peer already speaks (a transport-framed form of)
+ * the framework event vocabulary, so its messages map onto
+ * {@link NormalizedEvent} near-directly. Each inbound {@link ChildMessage.payload}
+ * is a JSON-RPC frame:
+ *   - a **notification** `{ method, params }` streams one turn event:
+ *       · `stream/text`        params `{ delta }`       → `text`
+ *       · `stream/thinking`    params `{ delta }`       → `thinking`
+ *       · `stream/toolCall`    params `{ id, name, arguments }` → `tool_call`
+ *       · `session/resume`     params `{ resumeToken }` → `resume`
+ *       · `stream/done`        params `{ reason }`      → `finish`
+ *       · `stream/error`       params `{ message, aborted }` → `failed`
+ *   - a **response** `{ id, result | error }` to the opening `runExchange`
+ *     request: an `error` member fails the exchange; a `result` is treated as a
+ *     terminal acknowledgement (`finish`) if the stream has not already settled.
+ *
+ * The opening request is a JSON-RPC `runExchange` call carrying the context,
+ * delegate provider, and resume token. The peer is reached only through the
+ * injected {@link ChildTransport}; no peer process is spawned here.
+ */
+import type { ExternalRuntimeSpec, RuntimeBridge } from "../contract";
+/**
+ * Build the `indusagi-cli` {@link RuntimeBridge}. The bound {@link ExternalRuntimeSpec}
+ * is captured so the opening request can forward its `delegate` to the peer; the
+ * broker constructs one bridge per spec it routes to.
+ *
+ * @param spec the runtime annotation whose `delegate` the peer should target
+ */
+export declare function makeIndusagiCliBridge(spec: ExternalRuntimeSpec): RuntimeBridge;
+/**
+ * A default `indusagi-cli` bridge bound to a spec with no delegate. Use
+ * {@link makeIndusagiCliBridge} when a delegate provider must be forwarded.
+ */
+export declare const indusagiCliBridge: RuntimeBridge;

package/dist/types/runtime-bridge/broker.d.ts

@@ -0,0 +1,182 @@
+/**
+ * RuntimeBroker — the single decision point that routes every turn to either an
+ * external runtime (a spawned child coding-agent driven by a {@link RuntimeBridge})
+ * or the framework network stream (`streamSimple` over an HTTP provider).
+ *
+ * The broker is the only component the product asks "how is this turn produced?".
+ * It owns three concerns:
+ *
+ *   1. **Routing.** {@link RuntimeBroker.route} resolves the model's optional
+ *      {@link ExternalRuntimeSpec} (a `bridge:<adapter>` baseUrl decode) and a
+ *      matching registered {@link RuntimeBridge}. A model with a spec whose
+ *      adapter is registered routes `"external"`; everything else routes
+ *      `"framework"`.
+ *   2. **Dispatch.** {@link RuntimeBrokerRuntime.exchange} acts on that decision:
+ *      for an external route it builds (or is injected) a {@link ChildTransport}
+ *      and calls {@link RuntimeBridge.runExchange} over it; for a framework route
+ *      it calls the framework `streamSimple`. Either way it returns the framework
+ *      {@link AssistantMessageEventStream} the turn streams into — the two paths
+ *      are indistinguishable to the caller.
+ *   3. **Resume persistence.** When a bridge surfaces a `resume` token (a CLI
+ *      session id / thread id), the broker persists it through an injected
+ *      {@link RuntimeLinkStore} as a *renamed* custom transcript entry —
+ *      {@link RUNTIME_LINK_ENTRY} = `"external-runtime-link"`, shape
+ *      `{ source, bridge, resumeToken, at }` — so a later exchange can reattach
+ *      the same underlying session. Handle reuse keys on the composite
+ *      {@link runtimeSourceKey} (`source|model|bridge`), not three separate field
+ *      comparisons.
+ *
+ * The {@link ChildTransport} is injectable end to end: a production factory wraps
+ * a spawned process, a test factory returns a hand-written fake. The broker never
+ * imports `child_process`; nothing here spawns a real `claude`/`codex` binary.
+ */
+import type { Api, AssistantMessageEventStream, ChildTransport, Context, ExchangeOptions, ExternalRuntimeSpec, Model, NormalizedEvent, RuntimeBridge, RuntimeBroker } from "./contract";
+/**
+ * The custom transcript-entry tag under which a runtime resume token is logged.
+ *
+ * The record this build writes is its own `"external-runtime-link"` shape so the
+ * persisted log carries no inherited vocabulary. A consumer scanning the active
+ * branch backwards for a reattachable session matches on this tag.
+ */
+export declare const RUNTIME_LINK_ENTRY: "external-runtime-link";
+/** The literal type of {@link RUNTIME_LINK_ENTRY}. */
+export type RuntimeLinkEntryTag = typeof RUNTIME_LINK_ENTRY;
+/**
+ * The serializable payload persisted under {@link RUNTIME_LINK_ENTRY}.
+ *
+ * The renamed shape: `{ source, bridge, resumeToken, at }`. `source` is the
+ * model's provider slug, `bridge` is the owning {@link RuntimeBridge.adapter},
+ * `resumeToken` is the reattachable CLI session id / thread id the child
+ * reported, and `at` is the ISO instant it was captured. Reuse keys on
+ * {@link runtimeSourceKey}, derived from `source` + model id + `bridge`.
+ */
+export interface RuntimeLink {
+    /** The model's provider slug (its `source`). */
+    readonly source: string;
+    /** The owning bridge adapter id. */
+    readonly bridge: string;
+    /** The reattachable session id / thread id reported by the child runtime. */
+    readonly resumeToken: string;
+    /** ISO-8601 instant the token was captured. */
+    readonly at: string;
+}
+/**
+ * Compose the composite reuse key a broker matches a persisted {@link RuntimeLink}
+ * against. A single `source|model|bridge` string rather than three field
+ * comparisons — a stored link is reattachable iff its key equals the key of the
+ * exchange about to run.
+ *
+ * @param source the model provider slug
+ * @param modelId the model id
+ * @param bridge the bridge adapter id
+ */
+export declare function runtimeSourceKey(source: string, modelId: string, bridge: string): string;
+/**
+ * Injectable persistence boundary for resume tokens. The conductor's transcript
+ * store binds a real implementation (appending a {@link RUNTIME_LINK_ENTRY} custom
+ * entry to the active branch and scanning it backwards on lookup); tests pass an
+ * in-memory fake. Both methods are async to match a disk-backed transcript.
+ */
+export interface RuntimeLinkStore {
+    /**
+     * Persist a captured resume token as a renamed custom transcript entry. Called
+     * once per `resume` event a bridge surfaces during an exchange.
+     *
+     * @param link the renamed link record to append
+     */
+    save(link: RuntimeLink): Promise<void> | void;
+    /**
+     * Resolve the most recent reattachable token for a reuse key, or `undefined`
+     * when the active branch holds no matching {@link RUNTIME_LINK_ENTRY}. The key
+     * is {@link runtimeSourceKey}.
+     *
+     * @param sourceKey the composite `source|model|bridge` reuse key
+     */
+    find(sourceKey: string): Promise<string | undefined> | string | undefined;
+}
+/**
+ * The context handed to a {@link ChildTransportFactory} when the broker needs a
+ * transport for an external exchange. Carries everything a production factory
+ * needs to launch + wire the child (the resolved spec's binary/args/env, the
+ * working directory, a resume token to reattach) without the broker itself
+ * touching `child_process`.
+ */
+export interface TransportContext {
+    /** The resolved runtime spec (binary, args, env, delegate) for the child. */
+    readonly spec: ExternalRuntimeSpec;
+    /** The bound model the exchange runs for. */
+    readonly model: Model<Api>;
+    /** The per-exchange options (session id, cwd, resume, stream opts). */
+    readonly opts: ExchangeOptions;
+    /** A persisted resume token resolved for this exchange, if any. */
+    readonly resume?: string;
+}
+/**
+ * Mints a {@link ChildTransport} for an external exchange. The single seam the
+ * broker reaches the outside world through: a production factory spawns the
+ * process and adapts its stdio/RPC into the transport; a test factory returns a
+ * scripted fake. The broker calls it lazily, only on an external route.
+ */
+export type ChildTransportFactory = (ctx: TransportContext) => ChildTransport;
+/** The framework network-stream signature the broker falls through to. */
+export type FrameworkStream = (model: Model<Api>, context: Context, opts: ExchangeOptions) => AssistantMessageEventStream;
+/**
+ * Construction-time dependencies for {@link createRuntimeBroker}. All optional —
+ * an empty broker registers bridges later, routes everything to the framework
+ * until a transport factory is wired, and skips persistence when no store is set.
+ */
+export interface RuntimeBrokerDeps {
+    /**
+     * The seam that builds a {@link ChildTransport} for an external exchange. When
+     * absent, an external route still *decides* `"external"` but {@link
+     * RuntimeBrokerRuntime.exchange} cannot drive a child — so it falls through to
+     * the framework path. Tests inject a fake-transport factory here.
+     */
+    readonly transportFactory?: ChildTransportFactory;
+    /** Where resume tokens persist; omitted ⇒ tokens are not persisted. */
+    readonly linkStore?: RuntimeLinkStore;
+    /**
+     * Override for the framework network stream (defaults to `streamSimple`).
+     * Injected in tests so the framework path is observable without a network.
+     */
+    readonly frameworkStream?: FrameworkStream;
+    /** Bridges to pre-register at construction (equivalent to calling `register`). */
+    readonly bridges?: readonly RuntimeBridge[];
+}
+/**
+ * The broker the product drives. Extends the frozen {@link RuntimeBroker} routing
+ * surface with {@link exchange}: the dispatch half that acts on a {@link route}
+ * decision and returns the framework stream the turn streams into.
+ */
+export interface RuntimeBrokerRuntime extends RuntimeBroker {
+    /**
+     * Produce the turn for `model`. Routes (via {@link RuntimeBroker.route}); on an
+     * `"external"` route with a wired transport factory it drives the bridge's
+     * `runExchange` over a freshly-built {@link ChildTransport} (resolving + later
+     * persisting the resume token); otherwise it runs the framework stream. Returns
+     * the {@link AssistantMessageEventStream} synchronously, like `streamSimple`.
+     *
+     * @param model   the model the turn is bound to
+     * @param context the framework conversation context
+     * @param opts    per-exchange options
+     */
+    exchange(model: Model<Api>, context: Context, opts?: ExchangeOptions): AssistantMessageEventStream;
+}
+/**
+ * Construct a {@link RuntimeBrokerRuntime}. The single sanctioned way to obtain a
+ * broker: build one with optional dependencies (a transport factory, a resume
+ * link store, a framework-stream override, pre-registered bridges), then
+ * {@link RuntimeBroker.register} further bridges and drive turns through
+ * {@link RuntimeBrokerRuntime.exchange} / {@link RuntimeBroker.route}.
+ *
+ * @param deps optional construction-time dependencies
+ */
+export declare function createRuntimeBroker(deps?: RuntimeBrokerDeps): RuntimeBrokerRuntime;
+/**
+ * The normalized resume-event kind a bridge emits — re-exported so a transport
+ * tap / consumer can name the same `"resume"` discriminant the sink ignores on
+ * the stream but the broker persists out of band.
+ */
+export type ResumeEvent = Extract<NormalizedEvent, {
+    kind: "resume";
+}>;