indusagi 0.12.32 → 0.12.33

package/dist/types/runtime/conductor/agent.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The conductor — the only stateful, side-effecting layer of the runtime.
+ *
+ * Everything beneath it is pure or single-purpose: the {@link cadence} reducer
+ * decides *what* should happen by returning {@link Effect}s; the conductor is
+ * the sole place those effects are actually carried out. It threads a serial
+ * stream of {@link Signal}s through the reducer, performs each emitted effect
+ * (reach the model, run tools, persist, condense, publish), and folds the
+ * resulting signals back in — turning over and over until the run reaches a
+ * `settled` or `faulted` terminal phase.
+ *
+ * The public {@link createAgent} returns an {@link Agent} whose `submit` drives
+ * one prompt to settlement, `subscribe` taps the live event stream, `abort`
+ * tears the current run down, `snapshot` reads the latest state, and `resume`
+ * rehydrates an earlier session from the store.
+ *
+ * The model entrypoint is injectable: by default it is the gateway bound to the
+ * configured model id, but tests pass a scripted {@link ModelInvoker} to make a
+ * run deterministic without touching the network.
+ */
+import type { Turn } from "../../llmgateway/contract";
+import type { AgentConfig, ModelInvoker, RunSnapshot } from "../contract";
+import type { RunEventHandler, Unsubscribe } from "../ledger";
+/** The handler shape a caller registers with {@link Agent.subscribe}. */
+export type AgentEventHandler = RunEventHandler;
+/**
+ * The optional collaborators a host may inject. All default to a production
+ * wiring; tests override `invokeModel` to script the model deterministically.
+ */
+export interface AgentDeps {
+    /**
+     * The seam through which the conductor reaches a model. Defaults to the
+     * gateway's `stream`, bound to {@link AgentConfig.model}.
+     */
+    readonly invokeModel?: ModelInvoker;
+    /** Where settled history is durably written. Typed loose to stay swappable. */
+    readonly store?: unknown;
+    /** Where run events are published. Typed loose to stay swappable. */
+    readonly ledger?: unknown;
+}
+/**
+ * The driveable agent. One agent owns one logical session; each {@link submit}
+ * opens a fresh run that streams to settlement.
+ */
+export interface Agent {
+    /**
+     * Drive a prompt to settlement and resolve the terminal snapshot.
+     *
+     * `input` is either a ready list of {@link Turn}s or a bare string (sugar for
+     * a single user text turn). If a run is already in flight, the input is folded
+     * into it as steering rather than starting a competing run.
+     */
+    submit(input: Turn[] | string): Promise<RunSnapshot>;
+    /** Tap the live {@link RunEvent} stream; returns a disposer. */
+    subscribe(handler: AgentEventHandler): Unsubscribe;
+    /** Tear down the current run, faulting it with an `aborted` error. */
+    abort(): void;
+    /** Read the latest {@link RunSnapshot}. */
+    snapshot(): RunSnapshot;
+    /** Rehydrate this agent's messages from a persisted session. */
+    resume(sessionId: string): Promise<void>;
+}
+/**
+ * Build a runnable {@link Agent} over a static {@link AgentConfig}.
+ *
+ * Wires the pure reducer to its real-world effect handlers: the model invoker
+ * (default = gateway), the tool scheduler (over `config.tools?.runner`), the
+ * session store, the condensation engine, and the event ledger. The returned
+ * agent is the host-facing handle.
+ */
+export declare function createAgent(config: AgentConfig, deps?: AgentDeps): Agent;

package/dist/types/runtime/conductor/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The conductor — public surface.
+ *
+ * The top-level orchestrator that ties the pure {@link import("../cadence").cadence}
+ * reducer to its real-world effect handlers (model, tools, store, condensation,
+ * ledger) and exposes the host-facing {@link Agent}. {@link createAgent} is the
+ * single entry point; everything beneath the conductor stays pure or
+ * single-purpose.
+ */
+export { createAgent } from "./agent";
+export type { Agent, AgentDeps, AgentEventHandler } from "./agent";

package/dist/types/runtime/contract/config.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Static configuration for a run.
+ *
+ * An {@link AgentConfig} is the immutable setup a caller supplies before any
+ * signals flow: which model to use, an optional system preamble, the tools the
+ * model may call, output and reasoning ceilings, and the policy that governs
+ * when history is condensed.
+ */
+import type { ThinkingLevel } from "../../llmgateway/contract";
+import type { ToolBox } from "./tools";
+/**
+ * The threshold policy for context condensation.
+ *
+ * When accumulated usage crosses `triggerRatio` of the model's window, the
+ * oldest history is condensed while the most recent `keepRecent` turns are
+ * preserved verbatim.
+ */
+export interface CompactionPolicy {
+    /** Fraction of the context window (0..1) at which condensation triggers. */
+    readonly triggerRatio: number;
+    /** Number of trailing turns kept untouched during condensation. */
+    readonly keepRecent: number;
+}
+/** The immutable setup for a run. */
+export interface AgentConfig {
+    /** The model id to bind the run to. */
+    readonly model: string;
+    /** Optional system preamble prepended to every model invocation. */
+    readonly system?: string;
+    /** The tools the model may call, and the runner that fulfils them. */
+    readonly tools?: ToolBox;
+    /** Hard ceiling on output tokens per model invocation. */
+    readonly maxOutputTokens?: number;
+    /** Requested reasoning depth for reasoning-capable models. */
+    readonly thinking?: ThinkingLevel;
+    /** When and how aggressively to condense history; absent disables it. */
+    readonly compaction?: CompactionPolicy;
+    /**
+     * Maximum number of model turns a single run may take before it is
+     * force-faulted. Guards against a model that loops forever (e.g. repeatedly
+     * requesting the same tool). Defaults to 64.
+     */
+    readonly maxTurns?: number;
+}

package/dist/types/runtime/contract/effect.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The side-effects the pure loop requests.
+ *
+ * The reducer performs no I/O. Instead it returns a list of {@link Effect}s
+ * describing what the outside world should do next: invoke the model, run a
+ * tool, persist a snapshot, condense history, or publish an event. A thin
+ * driver interprets each effect and feeds the results back in as
+ * {@link import("./signal").Signal}s, closing the loop.
+ */
+import type { Conversation, StreamOptions, Turn } from "../../llmgateway/contract";
+import type { RunSnapshot } from "./run-state";
+import type { ToolCall } from "./tools";
+import type { RunEvent } from "./events";
+/** Ask the driver to start a streaming model invocation for this conversation. */
+export interface InvokeModelEffect {
+    readonly kind: "invoke_model";
+    readonly conversation: Conversation;
+    readonly options: StreamOptions;
+}
+/** Ask the driver to execute one tool the model requested. */
+export interface RunToolEffect {
+    readonly kind: "run_tool";
+    readonly call: ToolCall;
+}
+/** Ask the driver to durably record the given snapshot. */
+export interface PersistEffect {
+    readonly kind: "persist";
+    readonly snapshot: RunSnapshot;
+}
+/** Ask the driver to condense the given history into a summary turn. */
+export interface CompactEffect {
+    readonly kind: "compact";
+    readonly messages: readonly Turn[];
+}
+/** Ask the driver to broadcast an event to subscribers. */
+export interface PublishEffect {
+    readonly kind: "publish";
+    readonly event: RunEvent;
+}
+/** The tagged union of every side-effect the pure loop can request. */
+export type Effect = InvokeModelEffect | RunToolEffect | PersistEffect | CompactEffect | PublishEffect;

package/dist/types/runtime/contract/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The run error model.
+ *
+ * Failures inside a run are surfaced as a typed, discriminable value rather
+ * than thrown exceptions or synthetic assistant messages. A {@link RunError}
+ * becomes the `error` field of a faulted {@link import("./run-state").RunSnapshot}
+ * and the payload of a `fault` signal, so callers branch on `kind` instead of
+ * matching message strings.
+ */
+/** The class of failure a {@link RunError} represents. */
+export type RunErrorKind = "model_failed" | "tool_failed" | "aborted" | "compaction_failed" | "turn_budget" | "invalid_state";
+/** A normalized, discriminable failure raised anywhere inside a run. */
+export interface RunError {
+    /** Which failure class this is. */
+    readonly kind: RunErrorKind;
+    /** A human-readable description. */
+    readonly message: string;
+    /** The underlying error or value that triggered this one, if any. */
+    readonly cause?: unknown;
+}
+/** Construct a {@link RunError}. Convenience over an object literal. */
+export declare function runError(kind: RunErrorKind, message: string, cause?: unknown): RunError;

package/dist/types/runtime/contract/events.d.ts

@@ -0,0 +1,63 @@
+/**
+ * What subscribers observe, and how the model is reached.
+ *
+ * A {@link RunEvent} is the outward-facing notification the loop publishes (via
+ * a `publish` effect) so hosts can render progress: each new snapshot, each
+ * incremental text/thinking delta, the lifecycle of every tool, and the
+ * terminal settle/fault. A {@link ModelInvoker} is the single injectable seam
+ * through which the loop reaches a model — defaulted to the gateway later, but
+ * swappable so tests can script a deterministic channel.
+ */
+import type { Channel, Conversation, StreamOptions } from "../../llmgateway/contract";
+import type { RunSnapshot } from "./run-state";
+import type { RunError } from "./errors";
+import type { ToolOutcome } from "./tools";
+/** A fresh immutable snapshot was produced. */
+export interface SnapshotEvent {
+    readonly kind: "snapshot";
+    readonly snapshot: RunSnapshot;
+}
+/** An incremental fragment of assistant prose arrived from the model. */
+export interface TextDeltaEvent {
+    readonly kind: "text_delta";
+    readonly delta: string;
+}
+/** An incremental fragment of model reasoning arrived. */
+export interface ThinkingDeltaEvent {
+    readonly kind: "thinking_delta";
+    readonly delta: string;
+}
+/** A tool the model requested began executing. */
+export interface ToolStartedEvent {
+    readonly kind: "tool_started";
+    readonly id: string;
+    readonly name: string;
+}
+/** A tool finished, successfully or not. */
+export interface ToolFinishedEvent {
+    readonly kind: "tool_finished";
+    readonly id: string;
+    readonly name: string;
+    readonly outcome: ToolOutcome;
+}
+/** The run reached a clean terminal state. */
+export interface SettledEvent {
+    readonly kind: "settled";
+    readonly snapshot: RunSnapshot;
+}
+/** The run reached a faulted terminal state. */
+export interface FaultedEvent {
+    readonly kind: "faulted";
+    readonly error: RunError;
+    readonly snapshot: RunSnapshot;
+}
+/** The tagged union of every notification a subscriber can receive. */
+export type RunEvent = SnapshotEvent | TextDeltaEvent | ThinkingDeltaEvent | ToolStartedEvent | ToolFinishedEvent | SettledEvent | FaultedEvent;
+/**
+ * The injectable model entrypoint.
+ *
+ * Given a provider-neutral conversation and per-call options, it returns a
+ * {@link Channel} of streaming emissions. The production wiring delegates to the
+ * gateway's `stream`; tests supply a function that yields a scripted channel.
+ */
+export type ModelInvoker = (conversation: Conversation, options: StreamOptions) => Channel;

package/dist/types/runtime/contract/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Frozen type vocabulary for the agent runtime.
+ *
+ * Every runtime module imports its shared types from this barrel. The contract
+ * is deliberately pure: types and the small `runError` helper only — no I/O, no
+ * loop logic. Gateway types (`Conversation`, `Turn`, `Reply`, `Emission`,
+ * `Channel`, `StreamOptions`, etc.) are re-exported by the modules that consume
+ * them and are not duplicated here.
+ */
+export type { RunPhase, PendingTool, RunSnapshot } from "./run-state";
+export type { SubmitSignal, EmissionSignal, StreamEndSignal, ToolSettledSignal, CompactedSignal, AbortSignalInput, FaultSignal, Signal, } from "./signal";
+export type { InvokeModelEffect, RunToolEffect, PersistEffect, CompactEffect, PublishEffect, Effect, } from "./effect";
+export type { ToolCall, ToolOutcome, ToolRunner, ToolBox } from "./tools";
+export type { RunErrorKind, RunError } from "./errors";
+export { runError } from "./errors";
+export type { SnapshotEvent, TextDeltaEvent, ThinkingDeltaEvent, ToolStartedEvent, ToolFinishedEvent, SettledEvent, FaultedEvent, RunEvent, ModelInvoker, } from "./events";
+export type { SessionNode, SessionHead, Migrator } from "./session";
+export type { CompactionPolicy, AgentConfig } from "./config";

package/dist/types/runtime/contract/run-state.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The immutable, event-sourced snapshot of a run.
+ *
+ * A run is the lifetime of one prompt-to-settlement interaction with a model:
+ * the system invokes the model, folds its stream, dispatches any tools it asks
+ * for, optionally condenses history, and finally settles or faults. Rather than
+ * mutating a working object in place, the loop derives a brand-new
+ * {@link RunSnapshot} after every {@link Signal}. The snapshot is the single
+ * source of truth that subscribers render and that the store persists.
+ */
+import type { Turn, Usage } from "../../llmgateway/contract";
+import type { RunError } from "./errors";
+/**
+ * The discrete macro-states a run can occupy.
+ * - `idle`        — created but not yet invoking the model.
+ * - `invoking`    — a model request has been requested but no stream yet.
+ * - `streaming`   — folding incremental emissions from the model.
+ * - `dispatching` — running the tools the model asked for.
+ * - `compacting`  — condensing history to stay under the context budget.
+ * - `settled`     — finished cleanly; no further work.
+ * - `faulted`     — finished with an unrecoverable {@link RunError}.
+ */
+export type RunPhase = "idle" | "invoking" | "streaming" | "dispatching" | "compacting" | "settled" | "faulted";
+/**
+ * One outstanding tool the model requested, tracked through its lifecycle.
+ * `stage` advances `queued` → `running` → `done`.
+ */
+export interface PendingTool {
+    readonly id: string;
+    readonly name: string;
+    readonly stage: "queued" | "running" | "done";
+}
+/**
+ * The complete, immutable state of a run at one point in time.
+ *
+ * Every field is read-only: a new snapshot is produced by the pure loop for
+ * each signal, never edited. `error` is present only when `phase` is
+ * `faulted`.
+ */
+export interface RunSnapshot {
+    /** Unique id for this run. */
+    readonly runId: string;
+    /** The session this run belongs to (links to the content-addressed store). */
+    readonly sessionId: string;
+    /** The current macro-state. */
+    readonly phase: RunPhase;
+    /** The accumulated conversation, oldest first. */
+    readonly messages: readonly Turn[];
+    /** Tools the model asked for that have not yet fully settled. */
+    readonly pending: readonly PendingTool[];
+    /** Running sum of token usage across every model invocation in this run. */
+    readonly usageTotal: Usage;
+    /** The model id this run is bound to. */
+    readonly model: string;
+    /** The terminal failure, set only when `phase === "faulted"`. */
+    readonly error?: RunError;
+}

package/dist/types/runtime/contract/session.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The content-addressed session store.
+ *
+ * History is kept as an immutable DAG: each {@link SessionNode} carries one turn
+ * and points at its parent by hash, so a node's `id` is a content hash of its
+ * turn plus its lineage. Branching is just two nodes sharing a parent; the
+ * linear context for a model call is the path from a leaf back to the root,
+ * reversed. A {@link SessionHead} names the current leaf of a session, and a
+ * {@link Migrator} upgrades stored records across schema versions.
+ */
+import type { Turn } from "../../llmgateway/contract";
+/** One immutable node in the session DAG. */
+export interface SessionNode {
+    /** Content hash of this node (over its turn and parent), serving as its id. */
+    readonly id: string;
+    /** The hash of the parent node, or `null` for a root. */
+    readonly parent: string | null;
+    /** The conversation turn this node carries. */
+    readonly turn: Turn;
+    /** Wall-clock creation time, in epoch milliseconds. */
+    readonly createdAt: number;
+}
+/** Names the current tip of a session within the store. */
+export interface SessionHead {
+    /** The session this head belongs to. */
+    readonly sessionId: string;
+    /** The hash of the leaf node the session currently points at. */
+    readonly leaf: string;
+}
+/**
+ * A single schema-upgrade step.
+ *
+ * Migrators are composed in sequence: each takes a raw record at version N and
+ * returns it shaped for version N+1. `id` identifies the step for logging and
+ * idempotency.
+ */
+export interface Migrator {
+    /** Stable identifier for this migration step. */
+    readonly id: string;
+    /** Transform one raw stored record forward by one schema version. */
+    upgrade(raw: unknown): unknown;
+}

package/dist/types/runtime/contract/signal.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The inputs that advance the run state machine.
+ *
+ * A {@link Signal} is the only thing that can move a run forward. The pure
+ * reducer takes the current snapshot plus one signal and returns the next
+ * snapshot together with the side-effects to perform. Every external happening —
+ * a caller's prompt, a streamed emission, a tool result, a completed
+ * compaction, an abort — enters the machine as exactly one of these.
+ */
+import type { Turn } from "../../llmgateway/contract";
+import type { Emission } from "../../llmgateway/contract";
+import type { ToolOutcome } from "./tools";
+import type { RunError } from "./errors";
+/** The caller submits new input turns to start or extend the run. */
+export interface SubmitSignal {
+    readonly kind: "submit";
+    readonly input: Turn[];
+}
+/** One streaming emission from the in-flight model invocation arrived. */
+export interface EmissionSignal {
+    readonly kind: "emission";
+    readonly emission: Emission;
+}
+/** The model's stream finished folding; the assistant turn is complete. */
+export interface StreamEndSignal {
+    readonly kind: "stream_end";
+}
+/** A dispatched tool finished and reported its result. */
+export interface ToolSettledSignal {
+    readonly kind: "tool_settled";
+    readonly id: string;
+    readonly result: ToolOutcome;
+}
+/** A compaction pass finished and produced a summary turn to splice in. */
+export interface CompactedSignal {
+    readonly kind: "compacted";
+    readonly summary: Turn;
+}
+/** The caller requested cancellation of the run. */
+export interface AbortSignalInput {
+    readonly kind: "abort";
+}
+/** An unrecoverable failure occurred and should terminate the run. */
+export interface FaultSignal {
+    readonly kind: "fault";
+    readonly error: RunError;
+}
+/** The tagged union of every input that drives the run state machine. */
+export type Signal = SubmitSignal | EmissionSignal | StreamEndSignal | ToolSettledSignal | CompactedSignal | AbortSignalInput | FaultSignal;

package/dist/types/runtime/contract/tools.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The tool-execution boundary.
+ *
+ * The pure loop never runs a tool itself; it emits a `run_tool` effect carrying
+ * a {@link ToolCall}, a driver hands that call to a {@link ToolRunner}, and the
+ * resulting {@link ToolOutcome} is fed back in as a `tool_settled` signal. A
+ * {@link ToolBox} bundles the descriptors the model is told about with the
+ * runner that fulfils them.
+ */
+import type { ToolDescriptor } from "../../llmgateway/contract";
+/** A single request to invoke a named tool, as parsed from the model's output. */
+export interface ToolCall {
+    /** The call id assigned by the model; pairs the outcome back to the request. */
+    readonly id: string;
+    /** The tool's name, matching a declared {@link ToolDescriptor}. */
+    readonly name: string;
+    /** The parsed arguments; shape is validated by the runner, not here. */
+    readonly input: unknown;
+}
+/** The result of running one {@link ToolCall}. */
+export interface ToolOutcome {
+    /** The originating call id. */
+    readonly id: string;
+    /** The tool's produced value, to be projected back into a tool turn. */
+    readonly output: unknown;
+    /** True when `output` represents a failure the model should be told about. */
+    readonly isError: boolean;
+}
+/**
+ * The injectable side that actually executes tools.
+ *
+ * Implementations perform real I/O; the loop only describes what to run. The
+ * passed `signal` lets a long-running tool observe cancellation (abort or a
+ * mid-dispatch interjection).
+ */
+export interface ToolRunner {
+    run(call: ToolCall, signal: AbortSignal): Promise<ToolOutcome>;
+}
+/** Bundles the tool catalog the model sees with the runner that fulfils it. */
+export interface ToolBox {
+    /** The descriptors advertised to the model on each invocation. */
+    descriptors(): ToolDescriptor[];
+    /** The executor for any call the model makes. */
+    readonly runner: ToolRunner;
+}

package/dist/types/runtime/dispatch/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The dispatch layer: the driver that executes one batch of tool calls.
+ *
+ * Re-exports the scheduler that bridges the pure reducer's `run_tool` effects to
+ * real {@link ToolRunner} execution, streaming a `tool_settled` signal back per
+ * finished call with per-call cancellation and bounded concurrency.
+ */
+export { createScheduler, DEFAULT_CONCURRENCY } from "./scheduler";
+export type { Scheduler } from "./scheduler";

package/dist/types/runtime/dispatch/scheduler.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The tool-execution scheduler.
+ *
+ * The pure reducer never runs a tool; it emits `run_tool` effects and waits for
+ * the matching `tool_settled` signals to come back. The scheduler is the driver
+ * that bridges that gap for one dispatch round: it takes the batch of
+ * {@link ToolCall}s the model asked for, hands each to the injected
+ * {@link ToolRunner}, and streams back a {@link ToolSettledSignal} as each one
+ * finishes — in completion order, not request order.
+ *
+ * Three properties define its behaviour:
+ *
+ * - **Per-call cancellation.** Every call is run under its own
+ *   {@link AbortController}, all chained to the caller's outer `signal` (and to
+ *   {@link createScheduler}'s own `cancel()`). Aborting tears down the whole
+ *   round: every in-flight runner observes its private signal firing, and the
+ *   generator stops once the calls already started have drained.
+ *
+ * - **Bounded concurrency.** At most {@link DEFAULT_CONCURRENCY} calls run at
+ *   once; the rest wait in request order until a slot frees up. A queued call
+ *   that is reached after an abort is skipped rather than started.
+ *
+ * - **Ordered in-flight tracking.** The set of calls currently `queued` or
+ *   `running` is kept as an ordered array of {@link PendingTool}, mirroring the
+ *   request order, so a host can render progress deterministically.
+ */
+import type { ToolCall, ToolRunner } from "../contract";
+import type { ToolSettledSignal } from "../contract";
+/** How many tool calls may execute simultaneously in one dispatch round. */
+export declare const DEFAULT_CONCURRENCY = 8;
+/** What {@link Scheduler.run} streams: one settled signal per finished call. */
+type SettledSignal = ToolSettledSignal;
+/** The driver returned by {@link createScheduler}. */
+export interface Scheduler {
+    /**
+     * Execute one batch of calls, yielding a `tool_settled` signal as each call
+     * finishes. Completion order — not request order — governs emission. The
+     * passed `signal` aborts the whole round; so does {@link Scheduler.cancel}.
+     */
+    run(calls: ToolCall[], signal: AbortSignal): AsyncGenerator<SettledSignal>;
+    /** Abort every dispatch round this scheduler has started. */
+    cancel(): void;
+}
+/**
+ * Build a tool-execution scheduler over a {@link ToolRunner}.
+ *
+ * The runner is the only side that performs real I/O; the scheduler owns
+ * concurrency, cancellation wiring, and in-flight bookkeeping. One scheduler may
+ * drive many sequential rounds; {@link Scheduler.cancel} fires the controllers
+ * of every round started so far.
+ */
+export declare function createScheduler(runner: ToolRunner, concurrency?: number): Scheduler;
+export {};

package/dist/types/runtime/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The agent runtime — public surface.
+ *
+ * One import site for everything a host needs to drive a model conversation to
+ * settlement: {@link createAgent} (the host-facing factory), the {@link Agent}
+ * handle it returns, and the public type vocabulary a caller branches on
+ * ({@link RunSnapshot}, {@link RunEvent}, {@link AgentConfig}, the tool boundary
+ * types, and {@link RunError}). The pure transition factory is re-exported as
+ * {@link step} for advanced hosts that want to drive the finite-state machine
+ * themselves rather than through the conductor.
+ *
+ * Gateway types (`Conversation`, `Turn`, `Block`, `ToolDescriptor`, `Reply`,
+ * `Emission`, `Channel`, `StreamOptions`, …) are intentionally *not* re-exported
+ * here; consumers import those directly from "../llmgateway" or
+ * "../llmgateway/contract" so there is a single source of truth for them.
+ */
+export { createAgent } from "./conductor";
+export type { Agent, AgentDeps, AgentEventHandler } from "./conductor";
+export type { RunSnapshot, RunPhase, PendingTool, RunEvent, AgentConfig, CompactionPolicy, ToolBox, ToolRunner, ToolCall, ToolOutcome, RunError, RunErrorKind, ModelInvoker, } from "./contract";
+export { runError } from "./contract";
+export { cadence as step, cadence, initialSnapshot } from "./cadence";
+export type { StepFn, Transition } from "./cadence";

package/dist/types/runtime/ledger/accumulator.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The latest-snapshot accumulator.
+ *
+ * Every {@link RunEvent} that carries a {@link RunSnapshot} — `snapshot`,
+ * `settled`, and `faulted` — moves the run forward. A {@link SnapshotAccumulator}
+ * watches the event stream and remembers only the most recent snapshot, so a
+ * host that just needs "where is the run right now" can read {@link
+ * SnapshotAccumulator.getSnapshot} instead of folding the whole stream itself.
+ *
+ * Delta events (`text_delta`, `thinking_delta`) and the tool lifecycle events
+ * carry no snapshot and are ignored here; they are rendered directly from the
+ * bus when a host wants incremental output.
+ */
+import type { RunEvent, RunSnapshot } from "../contract";
+import type { RunLedger } from "./bus";
+/**
+ * Tracks the most recent {@link RunSnapshot} seen on a stream of events.
+ *
+ * Stateless beyond the single latest snapshot. Construct one, feed it events
+ * (or {@link SnapshotAccumulator.attach} it to a {@link RunLedger}), and query
+ * {@link SnapshotAccumulator.getSnapshot} for the current state.
+ */
+export declare class SnapshotAccumulator {
+    /** The most recent snapshot observed, or `undefined` before the first one. */
+    private latest;
+    /**
+     * Fold one event in. Snapshot-bearing events replace the tracked snapshot;
+     * all other events are ignored.
+     */
+    observe(event: RunEvent): void;
+    /** The most recent snapshot, or `undefined` if none has been observed yet. */
+    getSnapshot(): RunSnapshot | undefined;
+    /** True once at least one snapshot-bearing event has been observed. */
+    get hasSnapshot(): boolean;
+    /** Forget the tracked snapshot, returning to the pre-observation state. */
+    reset(): void;
+    /**
+     * Subscribe this accumulator to a {@link RunLedger} so it folds every
+     * published event automatically.
+     *
+     * @returns the ledger's disposer; call it to stop tracking.
+     */
+    attach(ledger: RunLedger): () => void;
+}

package/dist/types/runtime/ledger/bus.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The run event hub.
+ *
+ * A {@link RunLedger} is a synchronous fan-out: hosts {@link RunLedger.subscribe}
+ * to receive every {@link RunEvent} the loop {@link RunLedger.publish}es, and the
+ * call returns a disposer that removes that handler. Delivery is sequential over
+ * the current handler set — each handler is invoked in turn, and a handler that
+ * throws never prevents the remaining handlers from observing the event.
+ *
+ * The handler set is snapshotted at publish time, so subscribing or
+ * unsubscribing from inside a handler is safe: the change takes effect on the
+ * next publish rather than mutating the iteration in flight.
+ */
+import type { RunEvent } from "../contract";
+/** A consumer of run events. */
+export type RunEventHandler = (event: RunEvent) => void;
+/** Removes a previously registered handler. Idempotent. */
+export type Unsubscribe = () => void;
+/**
+ * A subscribable, publishable hub for {@link RunEvent}s.
+ *
+ * Holds no run state of its own; it only delivers events to the currently
+ * registered handlers. Pair it with the accumulator when a host needs the
+ * latest snapshot rather than the raw event stream.
+ */
+export declare class RunLedger {
+    /** The live set of handlers. Insertion order is preserved for delivery. */
+    private readonly handlers;
+    /**
+     * Register a handler for every subsequent event.
+     *
+     * @returns a disposer that removes this handler. Calling it more than once is
+     * harmless. The same function reference may be subscribed only once; a
+     * duplicate subscription is a no-op that still returns a working disposer.
+     */
+    subscribe(handler: RunEventHandler): Unsubscribe;
+    /**
+     * Deliver an event to every currently registered handler.
+     *
+     * Handlers are notified in registration order over a snapshot of the set, so
+     * mutations made during delivery apply to the next publish. A throwing
+     * handler is isolated: its error is swallowed so siblings still receive the
+     * event and the loop is never broken by a faulty subscriber.
+     */
+    publish(event: RunEvent): void;
+    /** Drop every handler. Useful when tearing a host down. */
+    clear(): void;
+    /** How many handlers are currently registered. */
+    get size(): number;
+}