indusagi 0.12.32 → 0.12.34

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;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Ledger — the run event hub and snapshot accumulator.
+ *
+ * {@link RunLedger} fans published {@link import("../contract").RunEvent}s out to
+ * subscribers; {@link SnapshotAccumulator} folds the snapshot-bearing ones into a
+ * single readable latest state. Together they are the seam between the pure loop
+ * and any host that renders or persists progress.
+ */
+export { RunLedger } from "./bus";
+export type { RunEventHandler, Unsubscribe } from "./bus";
+export { SnapshotAccumulator } from "./accumulator";

package/dist/types/runtime/memory/compactor.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Context condensation.
+ *
+ * When a conversation's estimated footprint approaches the model's window, the
+ * oldest stretch of history is replaced by a single dense summary turn while a
+ * verbatim tail of recent turns is preserved. This module decides *whether* to
+ * condense ({@link shouldCompact}), *where* the boundary falls without severing
+ * a tool call from its result ({@link findCutPoint}), *how* the prefix is
+ * distilled into one turn ({@link summarize}), and finally stitches the two
+ * together ({@link compact}).
+ */
+import type { ModelCard, Turn } from "../../llmgateway/contract";
+import type { CompactionPolicy } from "../contract";
+import type { ModelInvoker } from "../contract";
+/**
+ * Decide whether the history has grown enough to warrant condensation.
+ *
+ * Compares the estimated token footprint against `triggerRatio` of the model's
+ * context window. Returns `false` for a non-positive window (nothing meaningful
+ * to compare against) so callers never condense on a misconfigured card.
+ */
+export declare function shouldCompact(messages: readonly Turn[], model: ModelCard, cfg?: CompactionPolicy): boolean;
+/**
+ * Locate the boundary index separating the prefix to condense from the tail to
+ * preserve.
+ *
+ * The tail starts at `length - keepRecent`, clamped into range. The boundary is
+ * then nudged *forward* (shrinking the tail, enlarging the condensed prefix)
+ * while the candidate first-preserved turn carries tool results, so a
+ * `tool_call`/`tool_result` pair is never split across the boundary. Returns the
+ * index of the first turn that survives verbatim: `0` means nothing is
+ * condensed; `length` means everything is.
+ */
+export declare function findCutPoint(messages: readonly Turn[], keepRecent: number): number;
+/**
+ * Distill a stretch of history into one synthetic turn.
+ *
+ * Builds a conversation whose system preamble is the {@link DISTILL_INSTRUCTION}
+ * and whose single user turn is the rendered transcript of `messages`, invokes
+ * the injected model, and folds the streamed response into a `user`-role turn.
+ * Filing the summary under the `user` role keeps it valid input for the next
+ * invocation regardless of which provider follows, and marks it visibly with
+ * {@link SUMMARY_HEADING}.
+ */
+export declare function summarize(messages: readonly Turn[], invoke: ModelInvoker): Promise<Turn>;
+/**
+ * Condense a history: replace its older prefix with a single distilled turn and
+ * keep the recent tail verbatim.
+ *
+ * Resolves the policy (falling back to {@link DEFAULT_POLICY}), finds the
+ * tool-safe cut point, and — when there is a prefix worth condensing — invokes
+ * {@link summarize} on it. The result is `[summary, ...tail]`. When the cut
+ * point is `0` (nothing old enough to drop) the original history is returned
+ * unchanged, so `compact` is safe to call unconditionally.
+ */
+export declare function compact(messages: readonly Turn[], model: ModelCard, cfg: CompactionPolicy | undefined, invoke: ModelInvoker): Promise<readonly Turn[]>;

package/dist/types/runtime/memory/estimate.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Cheap context-size estimation.
+ *
+ * Before any model invocation the loop needs a rough sense of how much of the
+ * window the accumulated history occupies. A real tokenizer is provider-specific
+ * and costly to run on every turn, so this module uses a coarse heuristic: it
+ * serializes each turn's textual content and divides the character count by an
+ * average characters-per-token ratio. The estimate is intentionally an
+ * over-approximation in spirit — it errs toward triggering condensation a little
+ * early rather than overflowing the window.
+ */
+import type { Turn } from "../../llmgateway/contract";
+/**
+ * Estimate the token footprint of an entire history.
+ *
+ * Sums the character counts of every block across every turn, converts to
+ * tokens via {@link CHARS_PER_TOKEN}, and adds a small fixed surcharge per turn
+ * for role/message framing. The result is a non-negative integer suitable for
+ * comparison against a model's context window.
+ */
+export declare function estimateContextTokens(messages: readonly Turn[]): number;

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

@@ -0,0 +1,8 @@
+/**
+ * Context compaction engine — public surface.
+ *
+ * The runtime reaches condensation through this barrel: a cheap token estimator
+ * and the four-part condensation flow (decide, locate, distill, stitch).
+ */
+export { estimateContextTokens } from "./estimate";
+export { shouldCompact, findCutPoint, summarize, compact, } from "./compactor";

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

@@ -0,0 +1,15 @@
+/**
+ * Behavioral-parity tests for the agent runtime.
+ *
+ * Every test drives a real {@link createAgent} but injects a *scripted*
+ * {@link ModelInvoker} so no network is touched: each model turn is a
+ * pre-recorded list of {@link Emission}s replayed as a {@link Channel}. Tools are
+ * fulfilled by a tiny in-memory {@link ToolBox}. The four scenarios cover the
+ * load-bearing behaviours of the conductor:
+ *
+ *   1. a multi-turn tool loop settling cleanly;
+ *   2. an abort mid-stream faulting with kind `aborted`;
+ *   3. branch/resume reconstructing a persisted message path;
+ *   4. compaction firing under a tiny trigger ratio and shrinking history.
+ */
+export {};

package/dist/types/runtime/store/dag.d.ts

@@ -0,0 +1,72 @@
+/**
+ * In-memory session DAG.
+ *
+ * {@link SessionGraph} holds the content-addressed nodes of one session and a
+ * moving head. Appending a turn chains a fresh node onto the current head and
+ * advances the head to it; branching points the head back at an older node so a
+ * subsequent append forks a new line of history. The linear context handed to a
+ * model is the path from a chosen leaf back to the root, reversed into
+ * root→leaf order.
+ */
+import type { Turn } from "../../llmgateway/contract";
+import type { SessionNode } from "../contract";
+/** Source of wall-clock timestamps, injectable for deterministic tests. */
+export type Clock = () => number;
+/**
+ * A mutable, branchable graph of {@link SessionNode}s for a single session.
+ *
+ * Nodes are immutable once added and keyed by their content hash. The graph
+ * tracks a `head` — the node a fresh {@link SessionGraph.append} will chain
+ * onto — which starts unset for an empty session.
+ */
+export declare class SessionGraph {
+    readonly sessionId: string;
+    private readonly nodes;
+    private head;
+    private readonly clock;
+    constructor(sessionId: string, clock?: Clock);
+    /**
+     * Rebuild a graph from previously persisted nodes plus its leaf pointer.
+     *
+     * Nodes may arrive in any order; parents are not required to precede children.
+     * The provided `leaf` becomes the head, or the loner node if exactly one
+     * exists and no leaf is named.
+     */
+    static hydrate(sessionId: string, nodes: readonly SessionNode[], leaf: string | null, clock?: Clock): SessionGraph;
+    /** The id of the node a fresh append will chain onto, or `null` if empty. */
+    get leaf(): string | null;
+    /** Total number of nodes across every branch. */
+    get size(): number;
+    /** Look up a node by its content hash. */
+    get(nodeId: string): SessionNode | undefined;
+    /** Every node in the graph, in insertion order. */
+    all(): SessionNode[];
+    /**
+     * Chain a new turn onto the current head and advance the head to it.
+     *
+     * Returns the freshly minted node. If the content hash collides with an
+     * existing node (identical lineage, turn, and timestamp), the head simply
+     * advances to that node without duplicating it.
+     */
+    append(turn: Turn): SessionNode;
+    /**
+     * Move the head to an existing node so the next append forks from there.
+     *
+     * Throws if `nodeId` is not part of this graph.
+     */
+    branchFrom(nodeId: string): SessionNode;
+    /**
+     * Resolve the linear context ending at `leaf`, ordered root→leaf.
+     *
+     * Walks parent pointers from the leaf back to a root, then reverses. Throws if
+     * `leaf` is unknown or the chain references a missing parent.
+     */
+    pathTo(leaf: string): Turn[];
+    /**
+     * Adopt `leaf` as the head and return its full root→leaf turn context.
+     *
+     * Convenience for re-entering a session at a chosen tip: combines {@link
+     * branchFrom} (positioning) with {@link pathTo} (context).
+     */
+    resume(leaf: string): Turn[];
+}

package/dist/types/runtime/store/hash.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Content addressing for session nodes.
+ *
+ * A node's identity is derived purely from its content: the parent hash it
+ * chains onto, the turn it carries, and its creation time. Two nodes built from
+ * identical lineage and content collapse to the same id, which is what makes the
+ * session history a content-addressed DAG rather than a mutable list.
+ */
+import type { Turn } from "../../llmgateway/contract";
+/**
+ * Compute the content hash that serves as a node's id.
+ *
+ * The hash is a SHA-256 over a canonical encoding of the parent id, the turn,
+ * and the creation timestamp, rendered as hex and truncated to {@link
+ * HASH_WIDTH} characters. A `null` parent (a root) is encoded distinctly from
+ * any real hash so roots never collide with chained nodes.
+ */
+export declare function hashNode(parent: string | null, turn: Turn, createdAt: number): string;

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

@@ -0,0 +1,12 @@
+/**
+ * Session store — public surface.
+ *
+ * A content-addressed, branchable session DAG with a JSONL-on-disk backing.
+ * `hashNode` derives node ids from content; `SessionGraph` is the in-memory DAG
+ * (append / branch / path / resume); `SessionStore` persists and reloads
+ * sessions, applying a migrator pipeline on load.
+ */
+export { hashNode } from "./hash";
+export { SessionGraph } from "./dag";
+export type { Clock } from "./dag";
+export { SessionStore } from "./persist";

package/dist/types/runtime/store/persist.d.ts

@@ -0,0 +1,49 @@
+/**
+ * On-disk session store.
+ *
+ * Each session lives in its own append-only JSONL file under a sessions root.
+ * Every line is one record: either a node (the full content-addressed {@link
+ * SessionNode}) or a head marker naming the current leaf. Appending a node
+ * writes its record and a fresh head marker; loading a session replays the file,
+ * runs each raw record through the {@link Migrator} pipeline, and reconstructs
+ * an in-memory {@link SessionGraph}.
+ */
+import type { Migrator, SessionNode } from "../contract";
+import { SessionGraph } from "./dag";
+/**
+ * A filesystem-backed store of branchable session DAGs.
+ *
+ * The store owns a root directory; sessions are files within it. A migrator
+ * pipeline is applied to every record on load so older on-disk schemas upgrade
+ * forward transparently.
+ */
+export declare class SessionStore {
+    private readonly root;
+    private readonly migrators;
+    constructor(root: string, migrators?: readonly Migrator[]);
+    /** Absolute path of a session's JSONL file. */
+    private fileFor;
+    /** Ensure the sessions root directory exists. */
+    private ensureRoot;
+    /**
+     * Append one node to a session and advance its persisted head.
+     *
+     * Writes the node record followed by a head record pointing at it, so the last
+     * head marker in the file always names the live leaf.
+     */
+    appendNode(sessionId: string, node: SessionNode): Promise<void>;
+    /**
+     * Load a session from disk into a {@link SessionGraph}.
+     *
+     * Replays every line, upgrades it through the migrator pipeline, collects the
+     * node records, and tracks the last head marker as the leaf. Blank lines are
+     * skipped. A missing session file yields an empty graph.
+     */
+    loadSession(sessionId: string): Promise<SessionGraph>;
+    /**
+     * List the ids of every session present in the store.
+     *
+     * Returns an empty list if the root does not yet exist.
+     */
+    listSessions(): Promise<string[]>;
+}