@alisio/core 0.6.0 → 0.8.0

package/dist/application.d.ts

@@ -21,6 +21,8 @@ import { GoalService } from "./goal/service.ts";
 import { HerdrBridge } from "./integrations/herdr.ts";
 import { McpConnector } from "./mcp/connector.ts";
 import { PluginHost } from "./plugins/host.ts";
+import { ProofVerifierRegistry } from "./proof/plugin-verifiers.ts";
+import { ProofStore } from "./proof/store.ts";
 import { ActiveProvider, ProviderRegistry } from "./providers/registry.ts";
 import { ProviderSettingsStore } from "./providers/settings.ts";
 import { ProjectContext } from "./resources/context.ts";
@@ -44,6 +46,8 @@ export interface AppOptions {
     /** Extra directories the tools may touch outside the workspace (per-run `--add-dir`). */
     addDirs?: string[];
     noHerdr?: boolean;
+    /** Home directory for user-level resources (skills, agents); defaults to `os.homedir()`. */
+    home?: string;
     model?: string;
     baseURL?: string;
     apiMode?: string;
@@ -183,6 +187,17 @@ export declare function createApplication(options?: AppOptions): Promise<{
     tasks: BackgroundTasks;
     /** Session goals (`/goal`): state, user actions, the continuation controller. */
     goals: GoalService;
+    /** The Proof ledger (specs/011): criteria and evidence of every session; user surfaces only. */
+    proof: ProofStore;
+    /** Verifiers plugins registered with `api.proof.registerVerifier`, keyed `<plugin>:<id>`. */
+    proofVerifiers: ProofVerifierRegistry;
+    /**
+     * Runs the verifier of one criterion on demand (`file`, `data-check`, `coverage`, `plugin`): a USER
+     * action, never reachable by the model. Core tool calls go through the normal gate.
+     */
+    verifyCriterion: (sessionId: string, criterionId: string, verifyOptions?: {
+        signal?: AbortSignal;
+    }) => Promise<import("./index.ts").VerifyOutcome>;
     /** Python discovery and job folders of `python_run`; `enabled` is false under --read-only. */
     analysis: {
         enabled: boolean;

package/dist/application.js

@@ -32,6 +32,10 @@ import { GoalStore } from "./goal/store.js";
 import { HerdrBridge } from "./integrations/herdr.js";
 import { McpConnector } from "./mcp/connector.js";
 import { discoverPlugins, PluginHost } from "./plugins/host.js";
+import { ProofVerifierRegistry } from "./proof/plugin-verifiers.js";
+import { ProofRecorder } from "./proof/recorder.js";
+import { ProofStore } from "./proof/store.js";
+import { verifyCriterion } from "./proof/verify.js";
 import { ActiveProvider, ProviderRegistry, UnconfiguredProvider } from "./providers/registry.js";
 import { availableProviderModels, resolveProviderModel as resolveConfiguredModel, } from "./providers/routing.js";
 import { ProviderSettingsStore } from "./providers/settings.js";
@@ -197,6 +201,9 @@ export async function createApplication(options = {}) {
             },
         },
     });
+    // Proof verifiers contributed by plugins (`api.proof`); bound before any plugin loads.
+    const proofVerifiers = new ProofVerifierRegistry();
+    plugins.setProofVerifiers(proofVerifiers);
     const stateRoot = options.db && options.db !== ":memory:" ? dirname(options.db) : stateHome();
     plugins.setPluginEnvironment({
         stateRoot,
@@ -216,7 +223,7 @@ export async function createApplication(options = {}) {
             cwd,
             stateHome: stateHome(),
             configHome: configHome(),
-            home: homedir(),
+            home: options.home ?? homedir(),
             trusted: !!options.trustProject || !!options.config,
             configDir: dirname(configFile(workspace, options.config ? { file: options.config } : { trustProject: options.trustProject })),
         };
@@ -380,7 +387,7 @@ export async function createApplication(options = {}) {
         await skills.discover(skillRoots({
             workspace,
             cwd,
-            home: homedir(),
+            home: options.home ?? homedir(),
             configHome: configHome(),
             trusted: !!options.trustProject || !!options.config,
             configSkills: config.skills,
@@ -543,6 +550,8 @@ export async function createApplication(options = {}) {
         // tools are opt-in: a run only sees them while its session has an active goal.
         const goals = new GoalService({
             store: new GoalStore(store.db),
+            // Proof (specs/011): `update_goal complete` is judged against the session's criteria.
+            proof: new ProofStore(store.db),
             settings: () => config.goal,
             ...(options.goals?.onChange ? { onChange: options.goals.onChange } : {}),
             ...(options.goals?.onLog ? { onLog: options.goals.onLog } : {}),
@@ -642,6 +651,8 @@ export async function createApplication(options = {}) {
             store,
             ui: plugins.ui,
             readOnly: !!options.readOnly,
+            // Criteria the model proposes become active only when the user approves the plan.
+            proof: new ProofStore(store.db),
             diagrams: () => ({
                 enabled: config.plan.diagrams,
                 max: config.plan.diagrams ? config.plan.maxDiagrams : 0,
@@ -982,6 +993,7 @@ export async function createApplication(options = {}) {
                 return known;
             },
             ...(options.approve && !options.readOnly ? { approve: options.approve } : {}),
+            proof: new ProofRecorder(store.db, { coverage: () => config.proof.coverage.enabled }),
             pathAccess,
             ...(analysisEnabled
                 ? {
@@ -1118,6 +1130,29 @@ export async function createApplication(options = {}) {
             tasks,
             /** Session goals (`/goal`): state, user actions, the continuation controller. */
             goals,
+            /** The Proof ledger (specs/011): criteria and evidence of every session; user surfaces only. */
+            proof: new ProofStore(store.db),
+            /** Verifiers plugins registered with `api.proof.registerVerifier`, keyed `<plugin>:<id>`. */
+            proofVerifiers,
+            /**
+             * Runs the verifier of one criterion on demand (`file`, `data-check`, `coverage`, `plugin`): a USER
+             * action, never reachable by the model. Core tool calls go through the normal gate.
+             */
+            verifyCriterion: (sessionId, criterionId, verifyOptions = {}) => verifyCriterion({
+                store: new ProofStore(store.db),
+                registry: proofVerifiers,
+                db: store.db,
+                coverage: () => config.proof.coverage.enabled,
+                callTool: (id, name, input, signal) => runner.runToolCall(id, name, input, {
+                    signal,
+                    workspace: sessionWorkspace(id),
+                }),
+            }, {
+                sessionId,
+                criterionId,
+                workspace: sessionWorkspace(sessionId),
+                ...(verifyOptions.signal ? { signal: verifyOptions.signal } : {}),
+            }),
             /** Python discovery and job folders of `python_run`; `enabled` is false under --read-only. */
             analysis: {
                 enabled: analysisEnabled,
@@ -1522,7 +1557,7 @@ export async function createApplication(options = {}) {
              */
             agentDefinitions: new AgentDefinitionService({
                 workspace,
-                home: homedir(),
+                home: options.home ?? homedir(),
                 registry: {
                     async reload() {
                         const handler = plugins.commands.get("agents");

package/dist/changelog/data.js

@@ -2,6 +2,45 @@
 export const CHANGELOG_DATA = {
     schema: 1,
     entries: [
+        {
+            version: "0.8.0",
+            date: "2026-10-14",
+            sections: [
+                {
+                    title: "Added",
+                    items: [
+                        "Proof ledger: acceptance criteria whose status (`verified`, `failed`, `not_checked`, `manual_review`, `not_applicable`) is computed from evidence captured from the commands, file reads and data queries the agent really ran. A criterion without a verifier stays `not_checked`.",
+                        "Verifiers `command`, `file`, `data-check`, opt-in `coverage` (`proof.coverage.enabled`) and plugin verifiers (`api.proof.registerVerifier`). An edit after the evidence expires it.",
+                        "The Proof card and tab in the web UI, `/proof` and `/goal override <reason>` in the terminal, and per-criterion review of the criteria a plan proposes (all-or-nothing in the terminal).",
+                        "`alisio run --proof`, `--criterion`, `--verify` and `--proof-file`: the run prints the ledger, ends with a `proof_ledger` JSONL line under `--json`, exits `0`, `10` or `11` (`proof.exitCodes`, `proof.ci`) and publishes `proof.md` and `proof.json`.",
+                        "A warning when the final answer claims tests, types or lint passed without matching evidence.",
+                        "Export in Markdown and versioned JSON (`proof/v1`) and the routes `GET /api/sessions/:sid/proof`, `POST` `…/proof/criteria`, `…/not-applicable` and `…/goal/override`.",
+                    ],
+                },
+                {
+                    title: "Improved",
+                    items: [
+                        "`update_goal` with `complete` is refused while a required criterion is `failed` or `not_checked`; only you can complete the goal over it. Without criteria, goal or plan nothing changes.",
+                    ],
+                },
+            ],
+        },
+        {
+            version: "0.7.0",
+            date: "2026-10-14",
+            sections: [
+                {
+                    title: "Added",
+                    items: [
+                        "`alisio eval list|run|record|compare|variants|export`: run evaluation suites against any configured provider, compare variants and export the results.",
+                        "Reliability Lab suites with deterministic verifiers (files, commands, tool sequences), so a pass or fail never depends on a model judging itself.",
+                        "`pass@k` and `pass^k` metrics with Wilson confidence intervals, so a comparison tells you whether a difference is real or noise.",
+                        "Cassettes: `alisio eval record` captures provider responses and later runs replay them offline, without network or cost.",
+                        "Bundled suites `smoke-coding`, `tool-sequences` and `long-context`, available from a source checkout.",
+                    ],
+                },
+            ],
+        },
         {
             version: "0.6.0",
             date: "2026-10-12",

package/dist/commands/builtins.js

@@ -151,6 +151,13 @@ export const BUILTIN_COMMANDS = [
         surfaces: INTERACTIVE,
         execution: "surface",
     },
+    {
+        name: "proof",
+        description: "Show the acceptance criteria of this session and the evidence behind each one",
+        argumentHint: "[add | edit | required | optional | na | export | help]",
+        surfaces: INTERACTIVE,
+        execution: "surface",
+    },
     {
         name: "decisions",
         description: "Show Decision Intelligence status, provider health and session metrics",

package/dist/config.d.ts

@@ -255,6 +255,16 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
         noToolTurnsLimit: z.ZodDefault<z.ZodNumber>;
         blockedRepeats: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strict>>;
+    proof: z.ZodDefault<z.ZodObject<{
+        ci: z.ZodDefault<z.ZodBoolean>;
+        exitCodes: z.ZodDefault<z.ZodObject<{
+            failed: z.ZodDefault<z.ZodNumber>;
+            unverified: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strict>>;
+        coverage: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
     plan: z.ZodDefault<z.ZodObject<{
         diagrams: z.ZodDefault<z.ZodBoolean>;
         maxDiagrams: z.ZodDefault<z.ZodNumber>;
@@ -415,6 +425,16 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
         noToolTurnsLimit: number;
         blockedRepeats: number;
     };
+    proof: {
+        ci: boolean;
+        exitCodes: {
+            failed: number;
+            unverified: number;
+        };
+        coverage: {
+            enabled: boolean;
+        };
+    };
     plan: {
         diagrams: boolean;
         maxDiagrams: number;
@@ -654,6 +674,16 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
         noToolTurnsLimit: number;
         blockedRepeats: number;
     };
+    proof: {
+        ci: boolean;
+        exitCodes: {
+            failed: number;
+            unverified: number;
+        };
+        coverage: {
+            enabled: boolean;
+        };
+    };
     plan: {
         diagrams: boolean;
         maxDiagrams: number;

package/dist/config.js

@@ -528,6 +528,38 @@ const configObjectSchema = z
         noToolTurnsLimit: 3,
         blockedRepeats: 2,
     })),
+    /**
+     * Proof (specs/011): acceptance criteria with evidence. `ci` makes `alisio run` behave as
+     * with `--proof` (the ledger as the final event and the exit codes below). `exitCodes` are
+     * what `--proof` exits with: `failed` when a required criterion failed, `unverified` when a
+     * required one is not checked or needs a manual review (0 when every required one is verified).
+     */
+    proof: z
+        .object({
+        ci: z.boolean().default(false),
+        exitCodes: z
+            .object({
+            failed: z.number().int().min(1).max(125).default(10),
+            unverified: z.number().int().min(1).max(125).default(11),
+        })
+            .strict()
+            .default(() => ({ failed: 10, unverified: 11 })),
+        /**
+         * The `coverage` verifier (opt-in). Off: a `coverage` criterion stays `not_checked` and
+         * Proof records nothing for its command. On: the percentage a coverage command printed
+         * (through the normal permission gate) is compared with the criterion's `minPercent`.
+         */
+        coverage: z
+            .object({ enabled: z.boolean().default(false) })
+            .strict()
+            .default(() => ({ enabled: false })),
+    })
+        .strict()
+        .default(() => ({
+        ci: false,
+        exitCodes: { failed: 10, unverified: 11 },
+        coverage: { enabled: false },
+    })),
     /**
      * Plan diagrams (`exit_plan`): the plan agent may add Mermaid diagrams to a plan. `diagrams`
      * off removes them from the tool and from the agent's instructions; `maxDiagrams` caps how

package/dist/core/runner.d.ts

@@ -1,4 +1,5 @@
 import { type Attachment, type DatasetRef, type Message, type ModelProvider, type RunEvent, type ToolDefinition, type ToolResult } from "@alisio/sdk";
+import type { ProofRecorder } from "../proof/recorder.ts";
 import type { PathAccess } from "../runtime/access.ts";
 import type { ApprovalHandler, ArtifactPublisherFactory, CapabilityGate, ContextSource, DecisionsFactory, Policy, RunnerExtensions, SessionStore } from "./contracts.ts";
 import { HumanWaits } from "./human-wait.ts";
@@ -83,6 +84,8 @@ export interface RunnerOptions {
     artifacts?: ArtifactPublisherFactory;
     /** Decision Intelligence bound to each tool call (`ToolContext.decisions`). */
     decisions?: DecisionsFactory;
+    /** Captures Proof evidence from executed calls (specs/011). Absent: the runner is unchanged. */
+    proof?: ProofRecorder;
     /**
      * Provider-native tool definitions (for example a hosted `web_search` tool) appended to every
      * request's `tools` alongside the registry's function tools. Opt-in, set once for the whole
@@ -285,6 +288,7 @@ export declare class AgentRunner {
         signal?: AbortSignal;
     }): Promise<{
         runId: string;
+        callId: string;
         status: "completed";
         result: ToolResult;
     }>;

package/dist/core/runner.js

@@ -414,6 +414,8 @@ export class AgentRunner {
         /** Set by the call itself (see `CallInternals`): it may have left effects. */
         let effectful = false;
         let dispatcher;
+        /** Proof ledger changes caused by this call, announced after `tool_completed`. */
+        let proofUpdates = [];
         /** Held from the scratchpad quota check until the write is done (L1). */
         let releaseScratch;
         // `effect` rides along so the TUI can group consecutive calls by capability kind
@@ -692,6 +694,25 @@ export class AgentRunner {
                 })),
             });
             result = await p.tool.execute(p.input, toolContext);
+            // Proof reads the RAW result of a call that really ran, before the model-facing bound below.
+            // It never throws into the call: a failed capture only means no evidence.
+            if (o.proof) {
+                try {
+                    proofUpdates = o.proof.capture({
+                        sessionId,
+                        runId,
+                        callId: call.id,
+                        name: call.name,
+                        input: p.input,
+                        result,
+                        workspace,
+                        durationMs: Date.now() - started,
+                    });
+                }
+                catch {
+                    proofUpdates = [];
+                }
+            }
             // The bound applies to what the model sees (the text projection): display-only
             // ui/image parts are bounded by their producers and must not push text over it.
             const projected = textProjection(result);
@@ -702,6 +723,25 @@ export class AgentRunner {
         }
         catch (error) {
             result = textResult(error instanceof Error ? error.message : String(error), true);
+            // A `read_file` of a missing file is evidence for a `file` criterion (specs/011): the call
+            // threw, so it never reached the capture above. Capture never throws into the call.
+            if (o.proof && call.name === "read_file") {
+                try {
+                    proofUpdates = proofUpdates.concat(o.proof.captureFailure({
+                        sessionId,
+                        runId,
+                        callId: call.id,
+                        name: call.name,
+                        input: p.input ?? {},
+                        result,
+                        workspace,
+                        durationMs: Date.now() - started,
+                    }));
+                }
+                catch {
+                    /* A failed capture only means no evidence. */
+                }
+            }
             // A cancellation after execution may have left effects, so the journal stays pending for
             // the user to inspect. A `read` call cannot have left any (and `exit_plan`, which is one,
             // is exactly what a stop or the run limit interrupts while a person decides): it is closed
@@ -725,6 +765,8 @@ export class AgentRunner {
                 .join("\n")
                 .slice(0, 2_000),
         });
+        for (const update of proofUpdates)
+            emit("proof_updated", update);
         return result;
     }
     /**
@@ -813,7 +855,7 @@ export class AgentRunner {
             o.store.append(sessionId, { role: "assistant", text, calls: [] });
             emit("run_completed", { tokens: 0, text });
             finish("completed");
-            return { runId, status: "completed", result };
+            return { runId, callId: call.id, status: "completed", result };
         }
         catch (error) {
             if (combined.aborted && isTimeoutReason(combined.reason)) {
@@ -1270,6 +1312,20 @@ export class AgentRunner {
                         });
                         final.truncated = true;
                     }
+                    if (o.proof) {
+                        // Display only (D8): the claims of the answer that the Proof ledger does not back.
+                        try {
+                            for (const d of o.proof.divergences(sessionId, lastText))
+                                emit("proof_divergence", {
+                                    claim: d.claim,
+                                    ...(d.criterionId ? { criterionId: d.criterionId } : {}),
+                                    actual: d.actualState,
+                                });
+                        }
+                        catch {
+                            // a failed check only means no warning
+                        }
+                    }
                     emit("run_completed", final);
                     finish("completed");
                     return {

package/dist/eval/canonical.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Canonical JSON of the reliability lab (specs/010 D10): equal values give equal text, so the same
+ * text can be hashed for the configuration hash, argument keys and cassette fingerprints.
+ *
+ * Rules: object keys sorted by UTF-16 code unit (the default string order), `undefined` members
+ * dropped (in arrays they become `null`, as `JSON.stringify` does), `null` kept, `-0` written as
+ * `0`, non-finite numbers rejected (JSON cannot carry them), string VALUES normalized to NFC
+ * (keys are left as written).
+ */
+/** JSON text with the canonical rules above. */
+export declare function canonicalJson(value: unknown): string;
+export declare const sha256Hex: (data: string | Buffer) => string;
+/** `sha256:<64 hex>` of the canonical JSON of `value`. */
+export declare function hashCanonical(value: unknown): string;

package/dist/eval/canonical.js

@@ -0,0 +1,40 @@
+/**
+ * Canonical JSON of the reliability lab (specs/010 D10): equal values give equal text, so the same
+ * text can be hashed for the configuration hash, argument keys and cassette fingerprints.
+ *
+ * Rules: object keys sorted by UTF-16 code unit (the default string order), `undefined` members
+ * dropped (in arrays they become `null`, as `JSON.stringify` does), `null` kept, `-0` written as
+ * `0`, non-finite numbers rejected (JSON cannot carry them), string VALUES normalized to NFC
+ * (keys are left as written).
+ */
+import { createHash } from "node:crypto";
+function normalize(value) {
+    if (typeof value === "string")
+        return value.normalize("NFC");
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError(`Cannot canonicalize a non-finite number (${value}).`);
+        return value === 0 ? 0 : value;
+    }
+    if (Array.isArray(value))
+        return value.map((item) => (item === undefined ? null : normalize(item)));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            const member = value[key];
+            if (member !== undefined)
+                out[key] = normalize(member);
+        }
+        return out;
+    }
+    return value;
+}
+/** JSON text with the canonical rules above. */
+export function canonicalJson(value) {
+    return JSON.stringify(normalize(value));
+}
+export const sha256Hex = (data) => createHash("sha256").update(data).digest("hex");
+/** `sha256:<64 hex>` of the canonical JSON of `value`. */
+export function hashCanonical(value) {
+    return `sha256:${sha256Hex(canonicalJson(value))}`;
+}

package/dist/eval/cassette.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Cassettes of the reliability lab (specs/010 5.3, D10, D11): `cassette/v1` JSONL, the provider
+ * that records a live run and the provider that serves it back.
+ *
+ *   line 1   header: {v:1, cassetteVersion, suiteId, taskId, harnessVersion, recordedAt, configHash,
+ *            provider, model, models?, texts, toolSets}
+ *   line n   one call to `ModelProvider.stream`: {call, lane, fingerprint, parts, messages?, events,
+ *            error?}
+ *
+ * `completed.message` is stored VERBATIM (tool-call ids, `providerData`, `truncated`) together with
+ * its usage; `reasoning_delta` is dropped (the SDK says it is never replayed). A provider error
+ * (for example the truncation signal) is stored as `error: {message, code}` so recovery replays.
+ *
+ * Replay serves the recorded events in strict order PER LANE. A lane is a session (the registered
+ * main session by its `<SESSION#n>` placeholder); a session the run did not register (a child /
+ * subagent) is bound to the lane whose first request has the same fingerprint, so concurrent
+ * children may interleave differently. v1 limitation: two children with an identical first request
+ * are interchangeable, and a child whose first request changes is reported as a divergence.
+ *
+ * This module (and everything it imports) must not touch the network: a test checks that
+ * statically, and replay needs no credentials. Replay promises no timing.
+ */
+import type { ModelInfo, ModelProvider, ProviderEvent, Usage } from "@alisio/sdk";
+import { type CassetteTexts, type FingerprintDiff, type FingerprintParts, type MessageView, type StreamRequest } from "./fingerprint.ts";
+import type { Normalizer } from "./normalize.ts";
+export declare const MAX_CASSETTE_BYTES: number;
+export declare const MAX_CASSETTE_DIR_BYTES: number;
+export declare const CASSETTE_SUFFIX = ".cassette.jsonl";
+export type RecordedEvent = {
+    type: "text_delta";
+    delta: string;
+} | {
+    type: "completed";
+    message: Extract<ProviderEvent, {
+        type: "completed";
+    }>["message"];
+    usage?: Usage;
+};
+export interface CassetteHeader {
+    v: 1;
+    cassetteVersion: number;
+    suiteId: string;
+    taskId: string;
+    harnessVersion: string;
+    recordedAt: number;
+    configHash: string;
+    provider: string;
+    model: string;
+    models?: ModelInfo[];
+    texts: CassetteTexts["texts"];
+    toolSets: CassetteTexts["toolSets"];
+}
+export interface CassetteCall {
+    call: number;
+    lane: string;
+    fingerprint: string;
+    parts: FingerprintParts;
+    /** Views of the messages that first appear in this call (the earlier ones are in earlier lines). */
+    messages?: Record<string, MessageView>;
+    events: RecordedEvent[];
+    error?: {
+        message: string;
+        code?: string;
+    };
+}
+export interface Cassette {
+    header: CassetteHeader;
+    calls: CassetteCall[];
+}
+export declare class CassetteFormatError extends Error {
+    constructor(message: string);
+}
+export declare class CassetteWriteError extends Error {
+    readonly reason: "secret" | "size" | "total";
+    constructor(message: string, reason: "secret" | "size" | "total");
+}
+export declare function serializeCassette(cassette: Cassette): string;
+export declare function parseCassette(text: string): Cassette;
+export declare function readCassette(path: string): Cassette;
+export interface WriteOptions {
+    /** Exact credential values of the run (provider profile, matching env vars). */
+    secrets?: readonly string[];
+    maxBytes?: number;
+    maxDirBytes?: number;
+}
+/**
+ * Writes `cassette` to `path` unless it holds a secret (REFUSES: it never strips, which would make
+ * the cassette lie about what the model saw) or exceeds the size limits (256 KB each, 2 MB for the
+ * directory). Nothing is written on refusal.
+ */
+export declare function writeCassette(path: string, cassette: Cassette, options?: WriteOptions): void;
+export interface CassetteMeta {
+    suiteId: string;
+    taskId: string;
+    harnessVersion: string;
+    configHash: string;
+    recordedAt: number;
+    provider: string;
+    model: string;
+    cassetteVersion?: number;
+}
+/** Collects the calls a `RecordingProvider` sees; `toCassette` turns them into the file content. */
+export declare class CassetteRecorder {
+    readonly calls: CassetteCall[];
+    /** Why the recording cannot be trusted (set, never cleared); `toCassette` refuses then. */
+    unstable: string | undefined;
+    models: ModelInfo[] | undefined;
+    private normalizer;
+    private readonly store;
+    private readonly childLanes;
+    private readonly laneCounts;
+    bind(normalizer: Normalizer): void;
+    /** Opens the record of the next call. */
+    begin(request: StreamRequest): CassetteCall;
+    private laneFor;
+    markUnstable(reason: string): void;
+    toCassette(meta: CassetteMeta): Cassette;
+}
+/**
+ * Wraps a real provider and tees what it emits into `sink`. The caller still receives every event
+ * (reasoning included). A call aborted before any event (a first-token retry, a timeout) or one the
+ * consumer abandons makes the recording unstable: replaying it would not reproduce the run.
+ */
+export declare class RecordingProvider implements ModelProvider {
+    private readonly inner;
+    private readonly sink;
+    readonly id: string;
+    readonly model: string;
+    readonly listModels?: ModelProvider["listModels"];
+    readonly dispose?: ModelProvider["dispose"];
+    constructor(inner: ModelProvider, sink: CassetteRecorder);
+    stream(request: StreamRequest): AsyncGenerator<ProviderEvent>;
+}
+/** The request of a call differs from the recorded one. Carries the structured diff. */
+export declare class ReplayDivergenceError extends Error {
+    readonly call: number;
+    readonly lane: string;
+    readonly diff: FingerprintDiff;
+    constructor(call: number, lane: string, diff: FingerprintDiff);
+}
+/** The run asked for a call the cassette has no (more) recording for. */
+export declare class ReplayExhausted extends Error {
+    readonly call: number;
+    readonly lane: string;
+    constructor(call: number, lane: string, detail: string);
+}
+/** Recorded calls the run never asked for (`ReplayProvider.assertConsumed`). */
+export declare class ReplayUnconsumedError extends Error {
+    readonly leftover: Array<{
+        call: number;
+        lane: string;
+    }>;
+    constructor(leftover: Array<{
+        call: number;
+        lane: string;
+    }>);
+}
+export declare class ReplayProvider implements ModelProvider {
+    readonly id: string;
+    readonly model: string;
+    readonly listModels?: ModelProvider["listModels"];
+    private readonly store;
+    private readonly lanes;
+    private readonly position;
+    private readonly bindings;
+    private readonly claimed;
+    private requests;
+    private readonly normalizer;
+    constructor(cassette: Cassette, options: {
+        normalizer: Normalizer;
+    });
+    /** The first divergence or exhaustion, kept even if the runner wraps the error it received. */
+    failure: ReplayDivergenceError | ReplayExhausted | undefined;
+    stream(request: StreamRequest): AsyncGenerator<ProviderEvent>;
+    /** The recorded call this request must be, consumed; throws when it is not. */
+    private match;
+    private laneFor;
+    /** Throws `ReplayUnconsumedError` when recorded calls were never requested (extra calls). */
+    assertConsumed(): void;
+}