@yaag/cli 0.1.0

package/assets/types/runtime/node-decoder.d.ts

@@ -0,0 +1,21 @@
+import type { NodeState, NodeUsage } from "./events.ts";
+/** One decoded Nested Node, relative to the tool call that produced it. */
+export interface DecodedNode {
+    /** Names from the tool call downwards, e.g. `["test-writer", "1", "fixture-gen"]`. */
+    readonly segments: readonly string[];
+    readonly state: NodeState;
+    readonly activityGist?: string;
+    readonly usage?: NodeUsage;
+}
+/**
+ * Knows one nesting tool's detail shape.
+ *
+ * `matches` is best-effort tool-name matching, not a protocol guarantee, so an
+ * unrecognised tool yields no decoder and therefore no nodes. `decode` returns
+ * null when the details do not carry this tool's shape, and never throws.
+ */
+export interface NodeDecoder {
+    readonly id: string;
+    matches(toolName: string): boolean;
+    decode(details: unknown): readonly DecodedNode[] | null;
+}

package/assets/types/runtime/node-decoders.d.ts

@@ -0,0 +1,3 @@
+import type { NodeDecoder } from "./node-decoder.ts";
+/** The decoders the runtime consults, in order, for every observed tool call. */
+export declare const DEFAULT_NODE_DECODERS: readonly NodeDecoder[];

package/assets/types/runtime/node-details.d.ts

@@ -0,0 +1,22 @@
+import type { NodeUsage } from "./events.ts";
+/**
+ * Reading untrusted nesting-tool detail payloads. Every decoder narrows from
+ * `unknown` through here, so a malformed payload is skipped, never thrown on.
+ */
+/** Narrows a detail payload to a plain object, the shape every decoder needs. */
+export declare function isRecord(value: unknown): value is Readonly<Record<string, unknown>>;
+/**
+ * Flattens decoded text to one capped line for a Nested Node's `activityGist`.
+ * Prompts never reach this function (ticket 09).
+ */
+export declare function nodeGist(value: string): string;
+/**
+ * Reads one nesting tool's accounting record into a Nested Node's `usage`.
+ *
+ * `NodeUsage` holds optional facts, so this function emits validated facts
+ * only. It emits a token breakdown when all four counts are finite and not
+ * negative, and it emits a cost when the cost is finite and not negative. It
+ * emits each fact independently, and it returns `undefined` when the record
+ * holds no valid fact. It never reports a missing or malformed field as zero.
+ */
+export declare function nodeUsage(value: unknown): NodeUsage | undefined;

package/assets/types/runtime/node-path.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The Nested Node path grammar `name(:askIndex(/childName…))` (spec §1).
+ *
+ * The Ask index is the wire index carried by `ask_start.index` — 0-based, so a
+ * path always equals a fact already on the wire. Renderers keep displaying
+ * `#index + 1`; they never re-derive identity from the display form.
+ */
+/** One Nested Node's identity, e.g. `dev:3/test-writer:1/fixture-gen`. */
+export type NodePath = string;
+/** Builds the path of one Agent's Ask from its name and the wire Ask index. */
+export declare function agentAskPath(agent: string, askIndex: number): NodePath;
+/** Appends one child segment below a parent path, sanitizing the child name. */
+export declare function childPath(parent: NodePath, childName: string): NodePath;
+/**
+ * Removes the path separators `:` and `/`, control characters, and newlines
+ * from an untrusted node name, so a decoded name cannot forge another node's
+ * path. Returns `node` when nothing printable remains.
+ */
+export declare function sanitizeNodeName(name: string): string;

package/assets/types/runtime/node-tracker.d.ts

@@ -0,0 +1,30 @@
+import type { NodeState, NodeUsage } from "./events.ts";
+import type { NodeDecoder } from "./node-decoder.ts";
+import type { Frame } from "./transport.ts";
+/** One Nested Node observation, relative to the tool call that produced it. */
+export interface NodeSnapshot {
+    readonly segments: readonly string[];
+    readonly state: NodeState;
+    readonly activityGist?: string;
+    readonly usage?: NodeUsage;
+}
+export interface NodeTrackerOptions {
+    readonly report: (node: NodeSnapshot) => void;
+    readonly decoders?: readonly NodeDecoder[];
+}
+/**
+ * Reports Nested Node snapshots decoded from an Agent's own `tool_execution_*`
+ * frames — a sibling of `AskActivityTracker`, above the transport seam, so it
+ * knows frames only (architecture §2).
+ *
+ * Coalescing is dedupe-only, with no timer: a snapshot is reported only when it
+ * differs from the last one reported for that node. That keeps the event stream
+ * a pure function of the frames, so a Cassette replay re-derives it exactly
+ * (ADR-0013).
+ */
+export declare class NodeTracker {
+    #private;
+    constructor(options: NodeTrackerOptions);
+    /** Inspects one Agent frame and ignores malformed or unsupported shapes. */
+    observe(frame: Frame): void;
+}

package/assets/types/runtime/pi-state.d.ts

@@ -0,0 +1,16 @@
+import type { AgentStats, Frame, OpenOptions } from "./transport.ts";
+/** The command line for one Agent. */
+export declare function piCommand(options: OpenOptions, toolProbeExtensionPath?: string): string[];
+/**
+ * `provider/id` from a `get_state` response — what the Agent actually resolved
+ * to, not the pattern that was requested. Null when the payload has no model.
+ */
+export declare function readModel(response: Frame): string | null;
+/** Returns pi's persisted session path from a startup `get_state` response, when valid. */
+export declare function readSessionFile(response: Frame): string | null;
+/**
+ * The full token breakdown and cost from a `get_session_stats` response.
+ * Missing fields become null rather than 0, so "unknown" and "free" stay
+ * distinguishable (ADR-0012); a partial breakdown is treated as unknown.
+ */
+export declare function readStats(response: Frame): AgentStats;

package/assets/types/runtime/prompt-gist.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Condenses an Ask prompt for the `ask_start` Lifecycle Event.
+ *
+ * Selects the first non-blank line, collapses its whitespace, and caps it at
+ * `PROMPT_GIST_MAX_CHARS`; it never includes content from later lines. Returns
+ * `""` for an all-whitespace prompt and never throws.
+ */
+export declare function promptGist(prompt: string): string;

package/assets/types/runtime/prompt.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Renders an indented template literal as a clean prompt string.
+ *
+ * Dedents static template text only and inserts interpolated values verbatim.
+ * Strings pass through, numbers and booleans stringify, and arrays render their
+ * items recursively separated by newlines. Throws `TypeError` for unsupported
+ * values or static indentation that mixes tabs and spaces.
+ */
+export declare function prompt(strings: TemplateStringsArray, ...values: unknown[]): string;

package/assets/types/runtime/reap.d.ts

@@ -0,0 +1,22 @@
+/** The process facts reaping needs. Kept behind an interface so it is testable. */
+export interface ReapTarget {
+    /** Resolves when the Agent's process is gone. */
+    readonly exited: Promise<unknown>;
+    /** Close the Agent's stdin. */
+    endStdin(): void;
+    /** SIGTERM to the pid — pi handles it and still reaps its own children. */
+    terminate(): void;
+    /** SIGKILL to the process group. Last resort; may leak bash-tool children. */
+    destroyGroup(): void;
+}
+export type ReapPath = "stdin-close" | "sigterm" | "sigkill";
+/**
+ * Shuts an Agent down (ticket 02's shutdown contract).
+ *
+ * Repeated requests for the same process share the initial attempt and its
+ * outcome. stdin EOF first, because pi's graceful shutdown is the only thing
+ * that reaps the bash-tool children it spawned into their own process groups —
+ * a group SIGKILL kills pi and leaves the user's `npm run dev` running. SIGINT
+ * is never sent: RPC mode registers SIGTERM and SIGHUP only.
+ */
+export declare function reap(target: ReapTarget, graceMs?: number): Promise<ReapPath>;

package/assets/types/runtime/recording-transport.d.ts

@@ -0,0 +1,9 @@
+import type { CassetteSink } from "./cassette.ts";
+import type { TransportFactory } from "./transport.ts";
+/**
+ * Wraps a transport factory and records frames at the public transport seam.
+ *
+ * Delegation is unchanged; failures from the wrapped factory and transport are
+ * preserved. The supplied sink holds the artifact until its owner serializes it.
+ */
+export declare function recordingTransport(inner: TransportFactory, sink: CassetteSink): TransportFactory;

package/assets/types/runtime/replay-divergence.d.ts

@@ -0,0 +1,19 @@
+import type { CassetteAgent } from "./cassette.ts";
+import type { AskMarker, OpenOptions } from "./transport.ts";
+/** A pure description of the first strict replay identity mismatch. */
+export interface ReplayMismatch {
+    readonly kind: "unexpected-spawn" | "spawn-options" | "changed-ask" | "extra-ask";
+    readonly agent: string;
+    readonly index?: number;
+    readonly expectedHash: string;
+    readonly actualHash: string;
+    readonly definitionName?: string;
+    readonly changedFields?: readonly string[];
+}
+/** Pure identity comparisons that ADR-0014 can reuse with a lenient reaction. */
+export declare const replayMismatch: {
+    spawn(expected: CassetteAgent | null, actual: OpenOptions): ReplayMismatch | null;
+    ask(agent: CassetteAgent, cursor: number, actual: AskMarker): ReplayMismatch | null;
+};
+/** Converts a detected mismatch into strict replay's public failure. */
+export declare function strictReplay(mismatch: ReplayMismatch): never;

package/assets/types/runtime/replay-transport.d.ts

@@ -0,0 +1,9 @@
+import type { Cassette } from "./cassette.ts";
+import type { TransportFactory } from "./transport.ts";
+/**
+ * Creates a strict Cassette-backed transport factory without starting pi.
+ *
+ * Each opened transport owns its Ask and frame cursors, so independent Agents
+ * may replay their recorded conversations in a different interleaving.
+ */
+export declare function replayTransport(cassette: Cassette): TransportFactory;

package/assets/types/runtime/resume-preconditions.d.ts

@@ -0,0 +1,8 @@
+import type { CassetteAgent } from "./cassette.ts";
+/**
+ * Validates that a recorded Agent can safely continue from its persisted session.
+ *
+ * Rejects with RESUME_REFUSED before replaying any frames when its session or
+ * working-tree facts cannot establish the recorded continuation point.
+ */
+export declare function checkResumePreconditions(agent: CassetteAgent): Promise<void>;

package/assets/types/runtime/resume-transport.d.ts

@@ -0,0 +1,9 @@
+import type { Cassette } from "./cassette.ts";
+import type { TransportFactory } from "./transport.ts";
+/**
+ * Creates a Cassette-prefix transport that continues with live pi at divergence.
+ *
+ * Matched Agents validate their recorded continuation point before replaying.
+ * Spawn mismatches intentionally bypass those checks and start a fresh Agent.
+ */
+export declare function resumeTransport(cassette: Cassette, live: TransportFactory): TransportFactory;

package/assets/types/runtime/run-checkpoint.d.ts

@@ -0,0 +1,28 @@
+import type { CassetteCollector } from "./cassette.ts";
+import type { RunOutcome } from "./events.ts";
+/**
+ * One Run's publication request: what settled, what it collected, and where the
+ * artifact may go. `record` wins over `checkpointDir`; a Run that neither
+ * recorded nor stopped publishes nothing.
+ */
+export interface RunCheckpointOptions {
+    /** Terminal outcome of the Run; only `stopped` publishes without `record`. */
+    readonly outcome: RunOutcome;
+    readonly collector: CassetteCollector;
+    /** Explicit `--record` destination; overrides the default checkpoint directory. */
+    readonly record: string | undefined;
+    /** Already-resolved default directory a stopped Run publishes into. */
+    readonly checkpointDir: string;
+    /** Program entry point recorded as invocation identity; omitted when unknown. */
+    readonly programFile: string | undefined;
+    readonly args: unknown;
+}
+/**
+ * Publishes the collected Cassette when the Run must be restorable: always under
+ * `--record`, and additionally into the checkpoint directory when the Run
+ * stopped (ADR-0021/0024). Returns the error that must become the Run's outcome,
+ * or null when there was nothing to publish or a primary program error owns it.
+ */
+export declare function publishRunCheckpoint(options: RunCheckpointOptions): Promise<unknown | null>;
+/** Reports a secondary Cassette publication failure without displacing the Run's primary error. */
+export declare function writeRecordingDiagnostic(error: unknown): void;

package/assets/types/runtime/run-context.d.ts

@@ -0,0 +1,18 @@
+import type { AgentDefinition } from "./define-agent.ts";
+import type { Handle, SpawnOptions, SpawnOverrides } from "./types.ts";
+/** What an Orchestration Program is handed. */
+export interface RunContext<Args = unknown> {
+    /** Program arguments, validated when the program declares a schema (ADR-0010). */
+    readonly args: Args;
+    /**
+     * Starts an Agent and resolves once it is confirmed up.
+     *
+     * Waits on a `get_state` round-trip, so a bad model fails here, before any
+     * tokens are spent. Killed automatically when the Run ends. Worktrees survive
+     * the Run and are never managed after creation. Definitions own policy;
+     * spawn overrides own topology. Runtime callers are validated even when they
+     * bypass TypeScript.
+     */
+    spawn(options?: SpawnOptions): Promise<Handle>;
+    spawn(definition: AgentDefinition, overrides?: SpawnOverrides): Promise<Handle>;
+}

package/assets/types/runtime/run.d.ts

@@ -0,0 +1,60 @@
+import { type Cassette, CassetteCollector } from "./cassette.ts";
+import { type OrchestrationProgram } from "./define-run.ts";
+import type { StampedEventSink } from "./events.ts";
+import { type SkillProbeFactory } from "./skill-probe.ts";
+import type { TransportFactory } from "./transport.ts";
+export interface RunOptions {
+    /** Where Agents come from. Defaults to real `pi --mode rpc` processes. */
+    readonly transport?: TransportFactory;
+    readonly events?: StampedEventSink;
+    /** Delivered as `ctx.args`; validated when the program declares an args schema (ADR-0010). */
+    readonly args?: unknown;
+    /** Session storage directory for every Agent of this Run (ticket 06). */
+    readonly sessionDir?: string;
+    /**
+     * Absolute Orchestration Program source path used to resolve portable relative
+     * extension declarations. This is Run context, never an Agent working directory.
+     */
+    readonly programFile?: string;
+    /** Resolves pi's enabled skills for live restriction requests. */
+    readonly skillProbe?: SkillProbeFactory;
+    /** Write every public transport-seam frame once the Run settles. */
+    readonly record?: string;
+    /** Re-run against this versioned Cassette instead of opening a live transport. */
+    readonly replay?: string;
+    /** Replay a matching Cassette prefix, then continue live from its session. */
+    readonly resume?: string;
+    /** Ends the Run early; every Agent is still reaped and costed. */
+    readonly signal?: AbortSignal;
+    /** Overrides the default checkpoint directory a stopped Run publishes into (ADR-0021). */
+    readonly checkpointDir?: string;
+}
+/**
+ * Executes one Orchestration Program and resolves with its return value.
+ *
+ * Every Agent is dead by the time this settles — on success, on failure, and on
+ * abort (ADR-0002) — and every Agent's cost has been emitted. Rejects with
+ * ARGS_INVALID before emitting an event when declared argument schema validation fails.
+ */
+export declare function executeRun<Args, Result>(program: OrchestrationProgram<Args, Result>, options?: RunOptions): Promise<Result>;
+/**
+ * Inputs that select the Run's transport composition. The collector receives
+ * every frame from every Run. Replay and resume hold the loaded Cassettes, or
+ * null when the Run does not use them.
+ */
+export interface FactorySelection {
+    readonly options: RunOptions;
+    readonly collector: CassetteCollector;
+    readonly replay: Cassette | null;
+    readonly resume: Cassette | null;
+}
+/**
+ * Composes the Run's transport. Strict replay deliberately bypasses the
+ * worktree wrapper; resume retains its worktree-wrapped live side for unmatched
+ * spawns (ADR-0013). The live order is worktree → skill restriction → live, so
+ * skill discovery occurs in the resolved worktree cwd.
+ *
+ * The recorder is the outermost wrapper of every composition, replay included:
+ * it observes only, and never changes delegation (ADR-0013/0021).
+ */
+export declare function selectFactory(selection: FactorySelection): TransportFactory;

package/assets/types/runtime/skill-probe.d.ts

@@ -0,0 +1,71 @@
+/** One enabled skill reported by pi's `get_commands` response. */
+export interface DiscoveredSkill {
+    readonly name: string;
+    readonly path: string;
+    /** True when an extension injects the skill after `--no-skills` is processed. */
+    readonly extensionInjected: boolean;
+}
+/** Cwd-scoped skill discovery seam, separate from long-lived Agent transports. */
+export interface SkillProbeFactory {
+    probe(cwd: string): Promise<readonly DiscoveredSkill[]>;
+}
+/** The stdin operations owned by one short-lived skill discovery process. */
+export interface SkillProbeStdin {
+    write(input: string): void;
+    flush(): void;
+    end(): void;
+}
+/**
+ * The short-lived process boundary used only while discovering skills.
+ *
+ * `probe()` always ends stdin, escalates to SIGKILL when needed, and awaits
+ * `exited`; implementations must make `exited` settle once the child is reaped.
+ */
+export interface SkillProbeProcess {
+    readonly stdin: SkillProbeStdin;
+    readonly stdout: ReadableStream<Uint8Array>;
+    readonly exited: Promise<number>;
+    kill(signal: "SIGKILL"): void;
+}
+/** Creates a short-lived discovery process in the supplied child cwd. */
+export interface SkillProbeProcessFactory {
+    create(cwd: string): SkillProbeProcess;
+}
+/** Injectable timings for a short-lived skill discovery process. */
+export interface SkillProbeTimings {
+    readonly responseTimeoutMs?: number;
+    readonly cleanupGraceMs?: number;
+}
+/** The fixed process configuration used by pi's short-lived discovery adapter. */
+export interface SkillProbeSpawnOptions {
+    readonly cmd: readonly string[];
+    readonly cwd: string;
+    readonly stdin: "pipe";
+    readonly stdout: "pipe";
+    readonly stderr: "ignore";
+}
+/**
+ * Parses pi's successful `get_commands` response into pi-compatible skill names.
+ *
+ * Rejects malformed skill entries instead of claiming a restriction was enforced.
+ */
+export declare function parseSkillCommands(response: unknown): readonly DiscoveredSkill[];
+/** Wraps a process constructor as the narrow discovery-process factory seam. */
+export declare function createSkillProbeProcessFactory(create: (cwd: string) => SkillProbeProcess): SkillProbeProcessFactory;
+/**
+ * Adapts a pi process spawner to the discovery-process seam.
+ *
+ * It always starts `pi --mode rpc --no-session` with piped stdin/stdout so a
+ * probe is isolated from an Agent's long-lived transport.
+ */
+export declare function createBunSkillProbeProcessFactory(spawn: (options: SkillProbeSpawnOptions) => SkillProbeProcess): SkillProbeProcessFactory;
+/**
+ * Creates a short-lived pi skill discovery probe.
+ *
+ * Rejects when pi exits, emits malformed output, or misses the response timeout.
+ * Every outcome ends stdin, escalates to SIGKILL after the cleanup grace period,
+ * and waits for process reaping before this method settles.
+ */
+export declare function createSkillProbe(processFactory: SkillProbeProcessFactory, timings?: SkillProbeTimings): SkillProbeFactory;
+/** The production skill probe, backed by Bun's short-lived pi process. */
+export declare const liveSkillProbe: SkillProbeFactory;

package/assets/types/runtime/skill-restriction-transport.d.ts

@@ -0,0 +1,8 @@
+import type { SkillProbeFactory } from "./skill-probe.ts";
+import type { TransportFactory } from "./transport.ts";
+/**
+ * Restricts live Agent skills by resolving pi's enabled names before startup.
+ *
+ * The cache belongs to one Run: concurrent requests for one cwd share its probe.
+ */
+export declare function skillRestrictionTransport(inner: TransportFactory, probe: SkillProbeFactory): TransportFactory;

package/assets/types/runtime/spawn.d.ts

@@ -0,0 +1,24 @@
+import { Agent } from "./agent.ts";
+import type { EventSink } from "./events.ts";
+import type { RunContext } from "./run-context.ts";
+import type { TransportFactory } from "./transport.ts";
+/** Dependencies for one Run's Agent-spawn gate. */
+export interface SpawnDependencies {
+    readonly factory: TransportFactory;
+    readonly agents: Agent[];
+    readonly emit: EventSink;
+    readonly sessionDir: string | undefined;
+    readonly programFile: string | undefined;
+}
+/** A RunContext spawn function that can synchronously stop accepting new Agents. */
+export interface SpawnGate {
+    readonly spawn: RunContext["spawn"];
+    close(): void;
+}
+/**
+ * Builds the Run-scoped Agent spawn gate.
+ *
+ * Allocates unique names within one Run and rejects with RUN_CLOSED once closed.
+ * Successfully opened Agents are registered immediately so Run cleanup reaps them.
+ */
+export declare function makeSpawn(deps: SpawnDependencies): SpawnGate;

package/assets/types/runtime/summary-agent.d.ts

@@ -0,0 +1,123 @@
+import type { AgentActivity } from "./events.ts";
+import type { NodeInfo } from "./summary-nodes.ts";
+import type { TokenBreakdown, WorktreeResolution } from "./transport.ts";
+export type { AgentActivity } from "./events.ts";
+export type { NodeInfo } from "./summary-nodes.ts";
+/** The observer-facing lifecycle state of an Agent. */
+export type AgentState = "idle" | "asking" | "exited";
+/** Identity and accounting facts that apply in every observer Agent state. */
+interface AgentInfoBase {
+    readonly model: string | null;
+    readonly cwd: string | null;
+    readonly branch: string | null;
+    /** pi's session file for this Agent, when the spawn reported one; a Peek reads it. */
+    readonly sessionFile: string | null;
+    readonly activity: AgentActivity | null;
+    readonly tokens: TokenBreakdown | null;
+    readonly cost: number | null;
+    readonly incomplete: boolean;
+    readonly stateChangedAt: number | null;
+    /** Timestamp ordering only cumulative live accounting, never lifecycle state. */
+    readonly usageUpdatedAt: number | null;
+    readonly askStartedAt: number | null;
+    /** This Agent's bounded Nested Node table, in first-seen order (spec §3). */
+    readonly nodes: readonly NodeInfo[];
+    /** Exited Nested Nodes dropped to keep the table bounded. */
+    readonly finishedNodesPruned: number;
+}
+/** An Agent between Asks; its latest settled Ask identity, if any, is retained. */
+export interface IdleAgentInfo extends AgentInfoBase {
+    readonly state: "idle";
+    readonly askIndex: number | null;
+    readonly promptGist: string | null;
+}
+/** An Agent with one active Ask, whose identity and start timestamp are known. */
+export interface AskingAgentInfo extends AgentInfoBase {
+    readonly state: "asking";
+    readonly askIndex: number;
+    readonly promptGist: string;
+    /** Whether the active Ask is served from Cassette playback. */
+    readonly replayed: boolean;
+    /** Null only for a legacy unstamped Ask start; no timestamp is synthesized. */
+    readonly askStartedAt: number | null;
+}
+/** A terminal Agent observation retaining its final usage and latest Ask identity. */
+export interface ExitedAgentInfo extends AgentInfoBase {
+    readonly state: "exited";
+    readonly askIndex: number | null;
+    readonly promptGist: string | null;
+}
+/**
+ * The discriminated observer projection for one Agent.
+ *
+ * Transition helpers below are pure and clock-free. Stamped state events older
+ * than the folded state are ignored; unstamped legacy events use stream order.
+ */
+export type AgentInfo = IdleAgentInfo | AskingAgentInfo | ExitedAgentInfo;
+/** Internal fold record, deliberately identical to the public observer projection. */
+export type AgentRecord = AgentInfo;
+/** Cumulative assistant-completion usage observed while an Agent is still live. */
+export interface AgentUsageObservation {
+    readonly tokens: TokenBreakdown;
+    readonly cost: number;
+}
+/** Final usage and optional worktree identity reported when an Agent exits. */
+export interface AgentExitObservation {
+    readonly tokens: TokenBreakdown | null;
+    readonly cost: number | null;
+    readonly incomplete: boolean;
+    readonly worktree?: WorktreeResolution;
+}
+/**
+ * Reconciles spawn identity without reopening a terminal Agent or losing facts
+ * learned from a prior exit. A late spawn fills only missing identity fields.
+ */
+export declare function spawnAgent(current: AgentRecord | undefined, identity: {
+    readonly model: string;
+    readonly cwd: string;
+    readonly branch?: string;
+    readonly sessionFile?: string;
+}, at: number | null): AgentRecord;
+/**
+ * Folds an Ask start into the asking arm when it is not older than the folded
+ * Agent state or Ask identity. Legacy unstamped events retain arrival order.
+ */
+export declare function startAsk(current: AgentRecord | undefined, ask: {
+    readonly index: number;
+    readonly promptGist: string;
+    readonly replayed: boolean;
+}, at: number | null): AgentRecord;
+/**
+ * Folds an Ask-scoped activity only into its current asking Agent. Older stamped
+ * observations, mismatched Ask identities, and terminal states are ignored.
+ */
+export declare function setActivity(current: AgentRecord | undefined, index: number, activity: AgentActivity, at: number | null): AgentRecord;
+/**
+ * Folds an Ask settlement into the idle arm, retaining the settled Ask identity.
+ * Older stamped events are ignored and legacy unstamped events use stream order.
+ */
+export declare function endAsk(current: AgentRecord | undefined, index: number, at: number | null): AgentRecord;
+/**
+ * Folds a cumulative usage snapshot without changing Agent lifecycle state.
+ *
+ * Terminal Agent accounting is never replaced; equal usage timestamps retain
+ * stream order while older stamped observations are ignored.
+ */
+export declare function setUsage(current: AgentRecord | undefined, observation: AgentUsageObservation, at: number | null): AgentRecord;
+/**
+ * Folds authoritative shutdown accounting into the terminal Agent state.
+ *
+ * Worktree identity is enriched even when a stale exit cannot alter state or
+ * usage, so late observations remain useful.
+ */
+export declare function exitAgent(current: AgentRecord | undefined, observation: AgentExitObservation, at: number | null): AgentRecord;
+/**
+ * Computes Run-wide accounting from every Agent's newest snapshot. A live Agent
+ * without an assistant completion contributes zero; an exited Agent without
+ * final stats preserves the established unknown-accounting semantics.
+ */
+export declare function totalsFromAgents(agents: Readonly<Record<string, AgentRecord>>): {
+    readonly cost: number;
+    readonly tokens: TokenBreakdown | null;
+    readonly incomplete: boolean;
+};

package/assets/types/runtime/summary-nodes.d.ts

@@ -0,0 +1,28 @@
+import type { LifecycleEventBody, NodeState } from "./events.ts";
+import type { AgentRecord } from "./summary-agent.ts";
+import type { TokenBreakdown } from "./transport.ts";
+/** One Nested Node's folded row in an Agent's bounded node table. */
+export interface NodeInfo {
+    readonly path: string;
+    readonly state: NodeState;
+    readonly activityGist: string | null;
+    readonly tokens: TokenBreakdown | null;
+    readonly cost: number | null;
+    readonly updatedAt: number | null;
+}
+type NodeUpdateEvent = Extract<LifecycleEventBody, {
+    readonly type: "node_update";
+}>;
+/**
+ * Folds one `node_update` into an Agent's bounded node table.
+ *
+ * Rows upsert by path and keep first-seen order. A stamped update older than
+ * the folded row is ignored, mirroring `setActivity`. Past
+ * `AGENT_NODE_TABLE_MAX` rows, exited nodes prune oldest-first into
+ * `finishedNodesPruned`. Running nodes are never pruned, so the table retains
+ * at most `max(AGENT_NODE_TABLE_MAX, simultaneously running node count)` rows:
+ * the row count is unbounded if upstream concurrency is unbounded. Only each
+ * row's snapshot size is bounded (spec §3).
+ */
+export declare function applyNodeUpdate(agent: AgentRecord, event: NodeUpdateEvent, at: number | null): AgentRecord;
+export {};

package/assets/types/runtime/summary.d.ts

@@ -0,0 +1,55 @@
+import type { LifecycleEvent, LifecycleEventBody, RunOutcome } from "./events.ts";
+import type { AgentInfo } from "./summary-agent.ts";
+import type { TokenBreakdown } from "./transport.ts";
+export type { NodeState, NodeUsage, RunOutcome } from "./events.ts";
+export type { AgentActivity, AgentInfo, AgentState, AskingAgentInfo, ExitedAgentInfo, IdleAgentInfo, NodeInfo, } from "./summary-agent.ts";
+/** The observer-facing lifecycle state of a Run. */
+export type RunState = "running" | "ended";
+/** Accounting and identity facts shared by all Run observer states. */
+interface RunSummaryBase {
+    readonly program: string;
+    readonly startedAt: number | null;
+    readonly agents: Readonly<Record<string, AgentInfo>>;
+    readonly asksStarted: number;
+    readonly asksSettled: number;
+    readonly cost: number;
+    readonly tokens: TokenBreakdown | null;
+    readonly incomplete: boolean;
+    readonly durationMs: number;
+    readonly worstFrameGapMs: number;
+}
+/** A Run that has not settled; it has neither outcome nor compatibility result. */
+export interface RunningRunSummary extends RunSummaryBase {
+    readonly runState: "running";
+    readonly outcome: null;
+    readonly ok: null;
+}
+/** A settled Run with its outcome, compatibility result, and ending event time. */
+export interface EndedRunSummary extends RunSummaryBase {
+    readonly runState: "ended";
+    readonly outcome: RunOutcome;
+    readonly ok: boolean;
+    /** The `run_end.at` event fact used to reject strictly older stamped endings. */
+    readonly endedAt: number | null;
+}
+/**
+ * The pure, discriminated observer fold of a Run's Lifecycle Events.
+ *
+ * It stores event facts only, reads no clock, and never synthesizes durations:
+ * `run_end.durationMs` is authoritative. Unknown events are no-ops. Stamped
+ * state events use timestamp order (ties retain stream order); legacy unstamped
+ * bodies use arrival order because no timestamp can be compared.
+ */
+export type RunSummary = RunningRunSummary | EndedRunSummary;
+/** Returns the deterministic, running Summary for a Run that emitted nothing. */
+export declare function initialSummary(): RunningRunSummary;
+/**
+ * Folds one Lifecycle Event into a fresh Summary without mutating either input.
+ *
+ * A stamped `run_end` older than the folded terminal timestamp is a no-op;
+ * equal times retain stream order. Legacy unstamped endings retain arrival order
+ * and may replace a stamped ending because no ordering fact exists. A late
+ * `run_start` enriches program/start metadata but never reopens a settled Run.
+ */
+export declare function applyEvent(summary: RunSummary, event: LifecycleEvent): RunSummary;
+export declare function applyEvent(summary: RunSummary, event: LifecycleEventBody): RunSummary;