@yaag/cli 0.1.0

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

@@ -0,0 +1,8 @@
+/**
+ * Every Lifecycle Event identifies its Agent, so an unnamed Agent still needs a
+ * name and a duplicate is suffixed rather than rejected — spawning in a loop
+ * must not fail.
+ *
+ * `taken` is mutated: the chosen name is reserved.
+ */
+export declare function uniqueAgentName(requested: string | undefined, ordinal: number, taken: Set<string>): string;

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

@@ -0,0 +1,16 @@
+import type { Frame, TokenBreakdown } from "./transport.ts";
+export interface AgentUsageSnapshot {
+    readonly tokens: TokenBreakdown;
+    readonly cost: number;
+}
+/**
+ * Accumulates complete assistant `message_end` usage across an Agent's lifetime.
+ *
+ * Invalid or non-assistant frames never change the reported accounting.
+ */
+export declare class AgentUsage {
+    #private;
+    constructor(report: (snapshot: AgentUsageSnapshot) => void);
+    /** Observes one raw Agent frame and reports after each valid assistant completion. */
+    observe(frame: Frame): void;
+}

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

@@ -0,0 +1,36 @@
+import type { Static, TSchema } from "typebox";
+import type { EventSink } from "./events.ts";
+import type { AgentStats, AgentTransport } from "./transport.ts";
+import type { AskOptions, Handle, SpawnOptions, StructuredAskOptions } from "./types.ts";
+export interface AgentOptions {
+    readonly name: string;
+    readonly cwd: string;
+    readonly branch: string | undefined;
+    readonly transport: AgentTransport;
+    readonly emit: EventSink;
+    /** The options this Agent was spawned with, for the ADR-0014 Ask hash. */
+    readonly spawnOptions: SpawnOptions;
+    /** Definition-owned defaults merged below explicit per-Ask options. */
+    readonly askDefaults?: AskOptions;
+    /** Definition identity recorded on its Asks, outside replay identity. */
+    readonly definitionName?: string;
+    /** Test-only override for the fixed duration-limit grace. */
+    readonly askLimitGraceMs?: number;
+    /** Test-only override for the bounded wait for `agent_settled` after an idle abort. */
+    readonly idleAbortSettleMs?: number;
+}
+/** One Agent as an Orchestration Program sees it. Lives above the transport seam. */
+export declare class Agent implements Handle {
+    #private;
+    readonly name: string;
+    readonly cwd: string;
+    readonly branch: string | undefined;
+    readonly model: string;
+    constructor(options: AgentOptions);
+    ask<Schema extends TSchema>(prompt: string, options: StructuredAskOptions<Schema>): Promise<Static<Schema>>;
+    ask(prompt: string, options?: AskOptions): Promise<string>;
+    /** True when the Agent was killed mid-Ask, so its cost is a floor (ADR-0012). */
+    get incomplete(): boolean;
+    /** Shuts the Agent down and reports its cost. Idempotent. */
+    close(): Promise<AgentStats>;
+}

package/assets/types/runtime/args-validation.d.ts

@@ -0,0 +1,3 @@
+import type { TSchema } from "typebox";
+/** Throws ARGS_INVALID when value violates schema, without changing value. */
+export declare function validateArgs(schema: TSchema, value: unknown): void;

package/assets/types/runtime/ask-activity.d.ts

@@ -0,0 +1,9 @@
+import type { AgentActivity } from "./events.ts";
+import type { Frame } from "./transport.ts";
+/** Reports complete Ask activity transitions derived from already-observed frames. */
+export declare class AskActivityTracker {
+    #private;
+    constructor(onChange: (activity: AgentActivity) => void);
+    /** Inspects one Agent frame and ignores malformed or unsupported shapes. */
+    observe(frame: Frame): void;
+}

package/assets/types/runtime/ask-contract-identity.d.ts

@@ -0,0 +1,25 @@
+import type { TSchema } from "typebox";
+/** A JSON value suitable for deterministic Cassette identity. */
+export type CanonicalJson = null | boolean | number | string | CanonicalJson[] | CanonicalJsonObject;
+/** A JSON object with recursively sorted keys. */
+export interface CanonicalJsonObject {
+    readonly [key: string]: CanonicalJson;
+}
+/** The conditional behavioral output contract of a structured Ask. */
+export interface AskOutputContract {
+    readonly outputSchema: CanonicalJsonObject;
+    readonly extractionPolicy: string;
+    readonly maxSteers?: number;
+}
+/**
+ * Copies a TypeBox schema into recursively key-sorted JSON form without mutating it.
+ *
+ * Throws when the value cannot be represented in a Cassette JSON artifact.
+ */
+export declare function canonicalizeSchema(value: unknown): CanonicalJsonObject;
+/** Builds the recorded and hashed behavioral contract for one structured Ask. */
+export declare function createAskOutputContract(schema: TSchema, maxSteers?: number): AskOutputContract;
+/** Validates an externally supplied canonical schema representation. */
+export declare function validateCanonicalOutputSchema(value: unknown): CanonicalJsonObject;
+/** Validates a policy identifier while allowing future versions to load and diverge at replay. */
+export declare function validateExtractionPolicy(value: unknown): string;

package/assets/types/runtime/ask-exchange-events.d.ts

@@ -0,0 +1,13 @@
+import type { AgentActivity, AskOutputChannel, EventSink } from "./events.ts";
+import type { NodeSnapshot } from "./node-tracker.ts";
+/** Emits the four Ask-scoped Lifecycle Events for one exchange. */
+export declare class AskEvents {
+    #private;
+    constructor(emit: EventSink, agent: string, index: number);
+    start(prompt: string, replayed: boolean): void;
+    activity: (activity: AgentActivity) => void;
+    output: (channel: AskOutputChannel, text: string) => void;
+    /** Composes the Nested Node path from this Ask's identity, then reports it. */
+    node: (snapshot: NodeSnapshot) => void;
+    end(durationMs: number, ok: boolean, maxFrameGapMs: number | undefined): void;
+}

package/assets/types/runtime/ask-exchange-options.d.ts

@@ -0,0 +1,30 @@
+import type { EffectiveAskOptions } from "./ask-hash.ts";
+import type { Connection } from "./connection.ts";
+import type { EventSink } from "./events.ts";
+import type { AgentTransport, Frame } from "./transport.ts";
+import type { SpawnOptions } from "./types.ts";
+/** A frame consumer whose lifetime exceeds one Ask; the Agent's AgentUsage satisfies it. */
+export interface FrameObserver {
+    observe(frame: Frame): void;
+}
+/** Options that connect one Ask exchange to its Agent's identity and event stream. */
+export interface AskExchangeOptions {
+    readonly agent: string;
+    readonly connection: Connection;
+    readonly transport: AgentTransport;
+    readonly prompt: string;
+    readonly index: number;
+    readonly ask: EffectiveAskOptions;
+    readonly spawnOptions: SpawnOptions;
+    readonly definitionName: string | undefined;
+    /** Lifecycle Event sink; the exchange emits every Ask-scoped event itself. */
+    readonly emit: EventSink;
+    /** The Agent's persistent usage accumulator; fed frames only during live Asks. */
+    readonly usage: FrameObserver;
+    /** Kills the Agent on ASK_TIMEOUT and destructive stalls — the one upward capability. */
+    readonly close: () => void;
+    /** Test-only override for the fixed duration-limit grace. */
+    readonly askLimitGraceMs: number | undefined;
+    /** Test-only override for the bounded settle wait after an idle abort. */
+    readonly idleAbortSettleMs: number | undefined;
+}

package/assets/types/runtime/ask-exchange.d.ts

@@ -0,0 +1,4 @@
+import type { AskExchangeOptions } from "./ask-exchange-options.ts";
+export type { AskExchangeOptions } from "./ask-exchange-options.ts";
+/** Runs one Ask's transport exchange, including controls and structured-output correction. */
+export declare function exchangeAsk(options: AskExchangeOptions): Promise<unknown>;

package/assets/types/runtime/ask-hash.d.ts

@@ -0,0 +1,32 @@
+import type { TSchema } from "typebox";
+import { type AskOutputContract } from "./ask-contract-identity.ts";
+import type { AskMarkerContext } from "./transport.ts";
+import type { AskOptions, SpawnOptions, StructuredAskOptions } from "./types.ts";
+/** The combined option shape used internally after Definition defaults merge. */
+export type EffectiveAskOptions = AskOptions | StructuredAskOptions<TSchema>;
+/** Inputs that identify an Ask in a Cassette. */
+export interface AskHashOptions {
+    readonly spawnOptions: SpawnOptions;
+    readonly index: number;
+    readonly prompt: string;
+    /** Soft-limit behavior and structured output contract, unlike timeoutMs, identify replay. */
+    readonly ask?: EffectiveAskOptions;
+    /** Precomputed once so marker metadata and hashing cannot drift. */
+    readonly outputContract?: AskOutputContract;
+}
+/**
+ * Identity of one Ask: sha256 over the prompt and behavioral Agent/Ask options.
+ *
+ * The optional canonical output schema, explicit steer bound, and extraction
+ * policy identify schema-bearing Asks. `timeoutMs` remains excluded.
+ */
+export declare function askHash(options: AskHashOptions): string;
+/**
+ * Retains Ask hash inputs for Definition-backed Cassette divergence diagnostics.
+ *
+ * `timeoutMs` remains excluded. Structured output schemas, explicit steer bounds,
+ * and extraction policy are retained because they participate in `askHash`.
+ */
+export declare function askMarkerContext({ spawnOptions, prompt, ask, outputContract, }: AskHashOptions): AskMarkerContext;
+/** Creates structured identity only when the Ask explicitly carries a schema. */
+export declare function structuredOutputContract(ask: EffectiveAskOptions | undefined): AskOutputContract | undefined;

package/assets/types/runtime/ask-limit.d.ts

@@ -0,0 +1,46 @@
+import type { AskLimitOutcome } from "./errors.ts";
+import type { Frame } from "./transport.ts";
+import type { AskOptions } from "./types.ts";
+/** The message sent when an Ask uses its allotted soft budget. */
+export declare const DEFAULT_WRAP_UP_PROMPT = "Please wrap up now and provide your final answer.";
+/** Fixed time allowed to conclude after a duration limit trips. */
+export declare const ASK_LIMIT_DURATION_GRACE_MS = 5000;
+export interface AskLimitOptions {
+    readonly ask: AskOptions;
+    readonly command: (frame: Frame) => Promise<boolean>;
+    readonly durationGraceMs?: number;
+    readonly now?: () => number;
+}
+/**
+ * Per-Ask soft-limit controller.
+ *
+ * A budget trips at equality. The triggering turn is allowed to finish and one
+ * later `turn_start` is grace, because pi delivers steering between turns.
+ */
+export declare class AskLimit {
+    #private;
+    constructor(options: AskLimitOptions);
+    /** Starts wall-clock accounting immediately before the prompt command is sent. */
+    start(): void;
+    /** Observes frames without changing their interpretation for the Ask itself. */
+    observe(frame: Frame): void;
+    /**
+     * Enters one output-contract correction effort when no limit is wrapping up.
+     *
+     * Returns false after a limit has tripped, so callers never reopen its grace
+     * window with a validator steer.
+     */
+    enterOutputCorrection(): boolean;
+    /** Leaves an output-contract correction effort after its text was retrieved. */
+    leaveOutputCorrection(): void;
+    /** Cancels timers when the whole logical Ask reaches a terminal result. */
+    settled(): void;
+    /** Cancels timers on every other Ask exit path. Idempotent. */
+    cleanup(): void;
+    /** Rejects when a steer or abort RPC is refused. */
+    get failed(): Promise<never>;
+    /** True once a limit has sent its wrap-up steer and owns the grace window. */
+    get tripped(): boolean;
+    /** Present only after yaag itself has sent the limit abort command. */
+    get abortOutcome(): AskLimitOutcome | null;
+}

package/assets/types/runtime/ask-output-steering.d.ts

@@ -0,0 +1,28 @@
+import type { TSchema } from "typebox";
+/** The per-Ask bound when a structured Ask omits `maxSteers`. */
+export declare const DEFAULT_MAX_STEERS = 3;
+export interface AskOutputSteeringOptions {
+    readonly agent: string;
+    readonly schema: TSchema;
+    readonly maxSteers: number | undefined;
+    /** Atomically enters a correction effort, or false after a limit starts wrap-up. */
+    readonly beginCorrection: () => boolean;
+    /** True once a soft limit has sent its wrap-up steer. */
+    readonly wrappingUp: () => boolean;
+    /** Re-arms settlement tracking, sends the steer, and returns its settled text. */
+    readonly correct: (message: string) => Promise<string>;
+    /** Re-arms settlement tracking, sends abort, and waits for its settlement. */
+    readonly abort: () => Promise<void>;
+}
+/**
+ * Validates structured output and corrects it without creating another logical Ask.
+ *
+ * Control-command failures propagate from `correct` or `abort` as Agent failures,
+ * rather than being reported as invalid-output exhaustion.
+ */
+export declare class AskOutputSteering {
+    #private;
+    constructor(options: AskOutputSteeringOptions);
+    /** Resolves a valid parsed value or rejects after the abort settlement on exhaustion. */
+    resolve(text: string): Promise<unknown>;
+}

package/assets/types/runtime/ask-output-tail.d.ts

@@ -0,0 +1,28 @@
+import type { AskOutputChannel } from "./events.ts";
+import type { Frame } from "./transport.ts";
+/** The timer boundary used to test output batching without changing its wire rate. */
+export interface AskOutputTailScheduler<Handle = unknown> {
+    schedule(callback: () => void): Handle;
+    cancel(timer: Handle): void;
+}
+interface AskOutputTailOptions {
+    readonly report: (channel: AskOutputChannel, text: string) => void;
+    readonly scheduler?: AskOutputTailScheduler;
+}
+/**
+ * Coalesces live assistant deltas into channel-tagged, UTF-8-bounded output tails.
+ *
+ * Malformed and unsupported frames are ignored. `close()` flushes synchronously and
+ * prevents a timer from emitting after an Ask terminal event.
+ */
+export declare class AskOutputTail {
+    #private;
+    constructor(options: AskOutputTailOptions);
+    /** Inspects one frame and queues only non-empty assistant thinking or text deltas. */
+    observe(frame: Frame): void;
+    /** Emits one pending batch immediately and cancels its scheduled trailing flush. */
+    flush(): void;
+    /** Flushes remaining output and prevents future observations or timer emissions. */
+    close(): void;
+}
+export {};

package/assets/types/runtime/ask-output.d.ts

@@ -0,0 +1,29 @@
+import type { TSchema } from "typebox";
+import type { AskInvalidOutputOutcome } from "./errors.ts";
+import { YaagError } from "./errors.ts";
+import type { AskInvalidOutputPlayback } from "./transport.ts";
+/** Versioned extraction behavior. It becomes Cassette identity in issue 04. */
+export declare const ASK_OUTPUT_EXTRACTION_POLICY = "json-first-block/v1";
+/** The currently implemented extraction policy identifier. */
+export type AskOutputExtractionPolicy = typeof ASK_OUTPUT_EXTRACTION_POLICY;
+export type AskOutputResult = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly errors: readonly string[];
+};
+/** Extracts the first parseable JSON object or array and validates it without coercion. */
+export declare function validateAskOutput(text: string, schema: TSchema): AskOutputResult;
+/** Produces the deterministic prompt for one correction effort. */
+export declare function formatAskOutputCorrection(errors: readonly string[]): string;
+/**
+ * Resolves a replayed Ask's structured output from its recorded text and outcome.
+ *
+ * A recorded invalid-output outcome rethrows deterministically (ADR-0027); otherwise
+ * the text is re-validated so playback and live settlement agree. Throws the same
+ * recoverable ASK_INVALID_OUTPUT error as a live Ask on validation failure.
+ */
+export declare function resolvePlaybackAskOutput(agent: string, schema: TSchema, text: string, recordedOutcome: AskInvalidOutputPlayback | undefined): unknown;
+/** Creates the recoverable error for final structured-output validation failure. */
+export declare function invalidAskOutputError(agent: string, outcome: AskInvalidOutputOutcome): YaagError;

package/assets/types/runtime/ask-settlement.d.ts

@@ -0,0 +1,11 @@
+import { YaagError } from "./errors.ts";
+export interface AwaitAskSettlementOptions {
+    readonly settled: Promise<void>;
+    readonly closed: Promise<void>;
+    readonly timeoutMs: number | undefined;
+    readonly controlFailure: Promise<never>;
+    readonly error: (code: YaagError["code"], message: string) => YaagError;
+    readonly close: () => void;
+}
+/** Waits for one effort's settlement while preserving the Ask-wide timeout and death semantics. */
+export declare function awaitAskSettlement(options: AwaitAskSettlementOptions): Promise<void>;

package/assets/types/runtime/ask-turn.d.ts

@@ -0,0 +1,25 @@
+import type { Frame } from "./transport.ts";
+/**
+ * Interprets the frames of one Ask (ticket 01's 8-point contract).
+ *
+ * Two rules here are counter-intuitive and load-bearing:
+ * - `agent_end` is ignored entirely. `willRetry: true` is followed by a second
+ *   `agent_start` for the same Ask; only `agent_settled` terminates one.
+ * - Only the *last* assistant `message_end` decides success. A retried-then-
+ *   successful Ask emits an early `stopReason: "error"`, so an earlier one would
+ *   falsely reject a recovered turn.
+ */
+export declare class AskTurn {
+    #private;
+    observe(frame: Frame): void;
+    /** True once `agent_settled` has been seen — settled says nothing about success. */
+    get settled(): boolean;
+    /** Starts a new correction effort without retaining the preceding terminal state. */
+    rearm(): void;
+    /**
+     * The failure message when the turn ended badly, else null.
+     * `agent_settled` fires on failed turns too, so this check is what
+     * distinguishes them (ticket 01 §3).
+     */
+    failure(): string | null;
+}

package/assets/types/runtime/cassette-loader.d.ts

@@ -0,0 +1,11 @@
+import { type Cassette } from "./cassette.ts";
+/**
+ * Reads and validates one Cassette artifact before replay begins.
+ *
+ * Rejects unreadable, unparsable, unsupported, and malformed artifacts at the
+ * filesystem boundary; replay never receives unchecked external data. The
+ * schema checks structure; the five named invariants below check semantics.
+ * A version 1 artifact is upgraded in memory to version 2 (ADR-0021).
+ * Unknown fields are retained, never dropped (forward tolerance).
+ */
+export declare function loadCassette(path: string): Promise<Cassette>;

package/assets/types/runtime/cassette-publish.d.ts

@@ -0,0 +1,11 @@
+import type { Cassette } from "./cassette.ts";
+/** Prefix of every in-flight publication temp file, so a later start can clean stale ones (ADR-0021). */
+export declare const CASSETTE_TEMP_PREFIX = ".yaag-tmp-";
+/**
+ * Publishes a Cassette crash-durably: temp file, fsync, rename, destination
+ * directory fsync. Resolves only after all four steps complete (ADR-0021).
+ *
+ * Rejects with an error naming `path` when any step fails; the temp file is
+ * removed on a best-effort basis first.
+ */
+export declare function publishCassette(path: string, cassette: Cassette): Promise<void>;

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

@@ -0,0 +1,24 @@
+import type { CassetteAgent } from "./cassette.ts";
+import type { AgentStats, AskMarker, AskPlayback, Frame } from "./transport.ts";
+/**
+ * Replays one Cassette Agent's frame streams at the transport seam.
+ *
+ * It owns frame ordering and command-id remapping, but deliberately leaves
+ * mismatch policy to its caller. `finish()` ends playback for a live handoff.
+ */
+export declare class CassetteReplay {
+    #private;
+    readonly model: string;
+    readonly stats: AgentStats;
+    constructor(agent: CassetteAgent);
+    /** Returns the recorded Agent whose Ask cursors this instance plays. */
+    get agent(): CassetteAgent;
+    /** Sends a frame through the recorded conversation, synthesizing internal responses. */
+    send(frame: Frame): void;
+    /** Returns a single ordered stream of recorded incoming frames. */
+    frames(): AsyncIterable<Frame>;
+    /** Moves playback to an Ask that its caller has already identity-checked. */
+    beginAsk(marker: AskMarker): AskPlayback;
+    /** Ends the stream cleanly, allowing a caller to switch to another source. */
+    finish(): void;
+}

package/assets/types/runtime/cassette-schema.d.ts

@@ -0,0 +1,111 @@
+import { type Static, Type } from "typebox";
+import type { CanonicalJsonObject } from "./ask-contract-identity.ts";
+import type { CassetteArtifact } from "./cassette.ts";
+import type { Frame } from "./transport.ts";
+/**
+ * Structure gate for one Cassette artifact read from disk. `run` stays optional
+ * here because version 1 predates it; the loader's presence invariant rejects a
+ * version 2 artifact without one, so field-path errors stay precise (no union
+ * of whole-artifact schemas).
+ */
+export declare const CassetteSchema: Type.TObject<{
+    v: Type.TUnion<[Type.TLiteral<1>, Type.TLiteral<2>]>;
+    run: Type.TOptional<Type.TObject<{
+        outcome: Type.TUnion<Type.TLiteral<"completed" | "failed" | "paused" | "stopped">[]>;
+        programFile: Type.TOptional<Type.TString>;
+        args: Type.TOptional<Type.TUnknown>;
+        programHash: Type.TOptional<Type.TString>;
+    }>>;
+    agents: Type.TArray<Type.TObject<{
+        spawn: Type.TObject<{
+            model: Type.TOptional<Type.TString>;
+            systemPrompt: Type.TOptional<Type.TString>;
+            thinking: Type.TOptional<Type.TUnion<Type.TLiteral<"high" | "low" | "max" | "medium" | "minimal" | "off" | "xhigh">[]>>;
+            appendSystemPrompt: Type.TOptional<Type.TString>;
+            tools: Type.TOptional<Type.TArray<Type.TString>>;
+            disallowedTools: Type.TOptional<Type.TArray<Type.TString>>;
+            skills: Type.TOptional<Type.TArray<Type.TString>>;
+            disallowedSkills: Type.TOptional<Type.TArray<Type.TString>>;
+            name: Type.TString;
+            cwd: Type.TString;
+            worktree: Type.TOptional<Type.TLiteral<true>>;
+        }>;
+        model: Type.TString;
+        sessionFile: Type.TOptional<Type.TString>;
+        worktree: Type.TOptional<Type.TObject<{
+            cwd: Type.TString;
+            branch: Type.TString;
+        }>>;
+        git: Type.TOptional<Type.TObject<{
+            branch: Type.TString;
+            head: Type.TString;
+        }>>;
+        sentFrames: Type.TArray<Type.TUnsafe<Frame>>;
+        receivedFrames: Type.TArray<Type.TUnsafe<Frame>>;
+        asks: Type.TArray<Type.TObject<{
+            outputSchema: Type.TOptional<Type.TUnsafe<CanonicalJsonObject>>;
+            maxSteers: Type.TOptional<Type.TInteger>;
+            extractionPolicy: Type.TOptional<Type.TString>;
+            index: Type.TNumber;
+            hash: Type.TString;
+            definitionName: Type.TOptional<Type.TString>;
+            context: Type.TOptional<Type.TObject<{
+                prompt: Type.TString;
+                spawn: Type.TObject<{
+                    model: Type.TOptional<Type.TString>;
+                    systemPrompt: Type.TOptional<Type.TString>;
+                    thinking: Type.TOptional<Type.TUnion<Type.TLiteral<"high" | "low" | "max" | "medium" | "minimal" | "off" | "xhigh">[]>>;
+                    appendSystemPrompt: Type.TOptional<Type.TString>;
+                    tools: Type.TOptional<Type.TArray<Type.TString>>;
+                    disallowedTools: Type.TOptional<Type.TArray<Type.TString>>;
+                    skills: Type.TOptional<Type.TArray<Type.TString>>;
+                    disallowedSkills: Type.TOptional<Type.TArray<Type.TString>>;
+                    cwd: Type.TOptional<Type.TString>;
+                    worktree: Type.TOptional<Type.TBoolean>;
+                }>;
+                ask: Type.TObject<{
+                    outputSchema: Type.TOptional<Type.TUnsafe<CanonicalJsonObject>>;
+                    maxSteers: Type.TOptional<Type.TInteger>;
+                    extractionPolicy: Type.TOptional<Type.TString>;
+                    maxTurns: Type.TOptional<Type.TNumber>;
+                    maxToolCalls: Type.TOptional<Type.TNumber>;
+                    maxDurationMs: Type.TOptional<Type.TNumber>;
+                    idleMs: Type.TOptional<Type.TNumber>;
+                    wrapUpPrompt: Type.TOptional<Type.TString>;
+                }>;
+            }>>;
+            sentFrames: Type.TArray<Type.TUnsafe<Frame>>;
+            receivedFrames: Type.TArray<Type.TUnsafe<Frame>>;
+            limit: Type.TOptional<Type.TObject<{
+                kind: Type.TUnion<[Type.TLiteral<"turns">, Type.TLiteral<"toolCalls">, Type.TLiteral<"durationMs">]>;
+                count: Type.TInteger;
+            }>>;
+            stalled: Type.TOptional<Type.TObject<{
+                idleMs: Type.TNumber;
+                destructive: Type.TBoolean;
+            }>>;
+            outcome: Type.TOptional<Type.TObject<{
+                kind: Type.TLiteral<"invalid_output">;
+                steeringEfforts: Type.TInteger;
+            }>>;
+        }>>;
+        stats: Type.TObject<{
+            tokens: Type.TUnion<[Type.TNull, Type.TObject<{
+                input: Type.TNumber;
+                output: Type.TNumber;
+                cacheRead: Type.TNumber;
+                cacheWrite: Type.TNumber;
+                total: Type.TNumber;
+            }>]>;
+            cost: Type.TUnion<[Type.TNull, Type.TNumber]>;
+        }>;
+    }>>;
+}>;
+/**
+ * Compile-time soundness: every schema-accepted value IS a Cassette, so the
+ * loader's cast cannot drift. Completeness (schema not over-strict) is pinned
+ * by the committed real-pi fixture round-trip tests.
+ */
+type AssertAssignable<T extends Base, Base> = T;
+export type CassetteSchemaIsSound = AssertAssignable<Static<typeof CassetteSchema>, CassetteArtifact>;
+export {};

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

@@ -0,0 +1,118 @@
+import type { CanonicalJsonObject } from "./ask-contract-identity.ts";
+import type { AskLimitOutcome, AskStalledOutcome } from "./errors.ts";
+import type { RunOutcome } from "./events.ts";
+import type { AgentStats, AskInvalidOutputPlayback, AskMarker, AskMarkerContext, Frame, OpenOptions, WorktreeResolution } from "./transport.ts";
+import type { ThinkingLevel } from "./types.ts";
+/** The Cassette format this runtime writes; the loader also reads version 1. */
+export declare const CASSETTE_VERSION: 2;
+/** Run-level settlement record; the ADR-0021 v2 block. */
+export interface CassetteRun {
+    /** The Run's terminal outcome. `paused` arrives with the pause slice. */
+    readonly outcome: RunOutcome;
+    /** Invocation identity: what a resume is about to re-execute. */
+    readonly programFile?: string;
+    readonly args?: unknown;
+    /** Advisory content hash of the program file; SHA-256 hex. */
+    readonly programHash?: string;
+}
+/** Versioned JSON artifact containing the frames exchanged during one Run. */
+export interface Cassette {
+    readonly v: typeof CASSETTE_VERSION;
+    readonly run: CassetteRun;
+    readonly agents: readonly CassetteAgent[];
+}
+/** On-disk shape the loader accepts: v1 carries no run block, v2 carries one. */
+export interface CassetteArtifact {
+    readonly v: 1 | typeof CASSETTE_VERSION;
+    readonly run?: CassetteRun;
+    readonly agents: readonly CassetteAgent[];
+}
+/** Git state observed at Agent spawn, when its cwd is a work tree. */
+export interface CassetteGit {
+    readonly branch: string;
+    readonly head: string;
+}
+/** One Agent's independently ordered frame streams. */
+export interface CassetteAgent {
+    readonly spawn: CassetteSpawn;
+    readonly model: string;
+    readonly sessionFile?: string;
+    /** Nondeterministic worktree location, deliberately outside spawn matching. */
+    readonly worktree?: WorktreeResolution;
+    readonly git?: CassetteGit;
+    readonly sentFrames: readonly Frame[];
+    readonly receivedFrames: readonly Frame[];
+    readonly asks: readonly CassetteAsk[];
+    readonly stats: AgentStats;
+}
+/** Behavioural identity supplied when opening a recorded Agent. */
+export interface CassetteSpawn {
+    readonly name: string;
+    readonly cwd: string;
+    readonly model?: string;
+    readonly systemPrompt?: string;
+    /** pi thinking level, present only when explicitly requested. */
+    readonly thinking?: ThinkingLevel;
+    /** Text appended to pi's system prompt, present even when empty. */
+    readonly appendSystemPrompt?: string;
+    /** Tool allowlist, including an explicit empty list that disables all tools. */
+    readonly tools?: readonly string[];
+    /** Tool denylist, applied after the allowlist. */
+    readonly disallowedTools?: readonly string[];
+    /** Skill-name allowlist; resolved filesystem paths never enter a Cassette. */
+    readonly skills?: readonly string[];
+    /** Skill-name denylist; resolved filesystem paths never enter a Cassette. */
+    readonly disallowedSkills?: readonly string[];
+    /** Deterministic request, present only when the Agent requested a worktree. */
+    readonly worktree?: true;
+}
+/** The frames attributed to one Ask marker. */
+export interface CassetteAsk {
+    readonly index: number;
+    readonly hash: string;
+    /** Canonical schema behavioral identity, never recorded model output. */
+    readonly outputSchema?: CanonicalJsonObject;
+    /** Explicit correction bound; omission remains distinct from the runtime default. */
+    readonly maxSteers?: number;
+    /** Extraction behavior identity, never recorded model output. */
+    readonly extractionPolicy?: string;
+    /** Definition identity for replay divergence diagnostics, never Ask identity. */
+    readonly definitionName?: string;
+    /** Recorded hash inputs for definition-specific divergence diagnostics. */
+    readonly context?: AskMarkerContext;
+    readonly sentFrames: readonly Frame[];
+    readonly receivedFrames: readonly Frame[];
+    /** Present only when the Ask surfaced ASK_LIMIT. */
+    readonly limit?: AskLimitOutcome;
+    /** Present only when the Ask surfaced ASK_STALLED. */
+    readonly stalled?: AskStalledOutcome;
+    /** Present only when the Ask surfaced ASK_INVALID_OUTPUT. */
+    readonly outcome?: AskInvalidOutputPlayback;
+}
+/** Sink consumed by recordingTransport without exposing its mutable state. */
+export interface CassetteSink {
+    reserve(options: OpenOptions): CassetteRecorder;
+    cassette(run: CassetteRun): Cassette;
+}
+/** Per-Agent recorder returned when a factory open begins. */
+export interface CassetteOpened {
+    readonly model: string;
+    readonly sessionFile?: string;
+    readonly worktree?: WorktreeResolution;
+    readonly git?: CassetteGit;
+}
+export interface CassetteRecorder {
+    opened(metadata: CassetteOpened): void;
+    failed(): void;
+    sent(frame: Frame): void;
+    received(frame: Frame): void;
+    beginAsk(marker: AskMarker): void;
+    finishAsk(outcome?: AskLimitOutcome, stalled?: AskStalledOutcome, invalidOutput?: AskInvalidOutputPlayback): void;
+    closed(stats: AgentStats): void;
+}
+/** Collects a Cassette in memory; `executeRun` serializes it at Run settlement. */
+export declare class CassetteCollector implements CassetteSink {
+    #private;
+    reserve(options: OpenOptions): CassetteRecorder;
+    cassette(run: CassetteRun): Cassette;
+}