/**
 * 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;
}
