@basein/runner 0.1.0

package/dist/proxy/session.js

@@ -0,0 +1,319 @@
+/**
+ * proxy/session — tier negotiation and the proxy's recording lifecycle (§0.1).
+ *
+ * D5 says the hook binary owns run identity. D8 says support any MCP client.
+ * Only Claude Code has hooks, so both cannot hold universally, and ownership is
+ * negotiated here at startup:
+ *
+ *   **Tier 1 — Bound.** A control server is discoverable for this cwd. It owns
+ *   the run; this proxy only reports steps. Built-ins and MCP land in one
+ *   ordered stream, with the prompt and the final answer.
+ *
+ *   **Tier 2 — Standalone.** No control server inside the discovery window. The
+ *   proxy owns a run of its own and records MCP calls only — no prompt, no final
+ *   answer, no built-in steps. That is not a degraded bug; it is the honest
+ *   ceiling of what an MCP proxy can observe, and the run says so in
+ *   `metadata.tier` so nothing downstream mistakes it for a complete trace.
+ *
+ * THE DISCOVERY WINDOW EXISTS BECAUSE OF A RACE: the host may spawn MCP servers
+ * before `SessionStart` fires, and the ordering between the two is not
+ * guaranteed. So steps are **buffered in memory** while the search runs, and
+ * flushed into whichever owner wins. Nothing is lost to the race, and nothing
+ * blocks: relaying never waits on this.
+ */
+import { hostname } from "node:os";
+import { ControlClient } from "../control/client.js";
+import { resolveControl } from "../control/discovery.js";
+import { qualifyToolName } from "../control/correlation.js";
+import { authenticate } from "../auth/client.js";
+import { NullRecorder } from "../record/recorder.js";
+import { RemoteRecorder } from "../record/remote-recorder.js";
+import { StepQueue } from "../record/queue.js";
+import { StepIndexAllocator } from "../control/ordering.js";
+import { serializeCapped } from "../record/truncate.js";
+import { redact } from "../record/redact.js";
+import { logLine, logDetail, errText } from "../util/log.js";
+import { packageVersion } from "../util/version.js";
+/** How long a proxy waits for a control server before falling to Tier 2. */
+export const DISCOVERY_WINDOW_MS = 5_000;
+export class ProxySession {
+    serverName;
+    opts;
+    tierValue = "pending";
+    control;
+    /** Tier 2 only. */
+    recorder;
+    runId;
+    ordering = new StepIndexAllocator();
+    queue = new StepQueue({
+        onDrop: (dropped) => {
+            if (!this.lossyValue)
+                logLine("run.lossy", { why: "step queue overflowed", dropped });
+            this.lossyValue = true;
+        },
+        onError: (err) => logLine("proxy.step_failed", { error: errText(err) }),
+    });
+    /** Steps that arrived before the tier was known. */
+    buffer = [];
+    lossyValue = false;
+    negotiation;
+    startedAt = Date.now();
+    /** The replay work loop, when one was started. */
+    workLoop;
+    closing = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.serverName = opts.serverName;
+    }
+    get tier() {
+        return this.tierValue;
+    }
+    get lossy() {
+        return this.lossyValue;
+    }
+    /**
+     * Whether the schema-relaxation half of correlation should be applied to
+     * `tools/list` (Phase 6). Only ever true in Tier 1 with correlation enabled:
+     * relaxation is visible to the model on every call, so it is never paid for
+     * unless it is actually buying a merge.
+     */
+    get correlationActive() {
+        return this.tierValue === "bound" && !this.opts.noCorrelation;
+    }
+    /** Begin tier negotiation. Returns immediately; relaying never waits on it. */
+    start() {
+        if (this.negotiation)
+            return;
+        this.negotiation = this.negotiate().catch((err) => {
+            logLine("proxy.negotiation_failed", { server: this.serverName, error: errText(err) });
+            this.tierValue = "standalone";
+        });
+    }
+    async negotiate() {
+        if (this.opts.standalone) {
+            await this.becomeStandalone("--standalone was requested");
+            return;
+        }
+        const window = this.opts.discoveryWindowMs ?? DISCOVERY_WINDOW_MS;
+        const found = await resolveControl(this.opts.cwd, window);
+        if (!found?.url) {
+            await this.becomeStandalone(`no control server within ${window}ms`);
+            return;
+        }
+        const client = new ControlClient(found.url, found.token);
+        const registered = await client.register({
+            serverName: this.serverName,
+            pid: process.pid,
+            cwd: this.opts.cwd,
+            version: packageVersion(),
+        });
+        if (!registered) {
+            await this.becomeStandalone("control server did not answer /proxy/register");
+            return;
+        }
+        this.control = client;
+        this.tierValue = "bound";
+        logLine("tier.bound", {
+            server: this.serverName,
+            control: found.url,
+            sess: registered.sessionId,
+            correlation: this.opts.noCorrelation ? "fingerprint" : "injected",
+            replay: registered.replay ? "on" : undefined,
+        });
+        this.flushBuffer();
+        if (registered.replay)
+            this.startWorkLoop(client, registered.pollHoldMs ?? 25_000);
+    }
+    /**
+     * Take calculated-scenario steps from the control server and run them on the
+     * upstream this proxy already owns (docs/calculatedReplay.md §16.2).
+     *
+     * The whole point of the design lives in three lines below: `upstream.request`
+     * allocates an id in the reserved `bir:` space and the transport consumes its
+     * own response in `accept()` before the relay's handlers ever see it — so this
+     * costs **zero tokens**, the model is not involved, and `RecordingInterceptor`
+     * cannot double-record it. That interface comment says `request()` is "never
+     * used by the relay"; it was built for `bir doctor` and tests, and this is its
+     * second, load-bearing user.
+     */
+    startWorkLoop(client, holdMs) {
+        const upstream = this.opts.upstream;
+        if (!upstream || this.workLoop)
+            return;
+        this.workLoop = (async () => {
+            logLine("replay.worker", { server: this.serverName, why: "polling for scenario steps" });
+            while (!this.closing) {
+                let work;
+                try {
+                    work = await client.poll(this.serverName, holdMs);
+                }
+                catch {
+                    work = undefined;
+                }
+                if (this.closing)
+                    break;
+                if (!work) {
+                    // Either an empty hold (normal) or an unreachable server. A short
+                    // pause keeps the second case from becoming a busy loop.
+                    await new Promise((resolve) => {
+                        const t = setTimeout(resolve, 250);
+                        t.unref?.();
+                    });
+                    continue;
+                }
+                try {
+                    const result = await upstream.request("tools/call", { name: work.toolName, arguments: work.arguments }, AbortSignal.timeout(work.timeoutMs));
+                    await client.result(work.workId, result);
+                }
+                catch (err) {
+                    // A rejection here means the step could not be RUN — which is exactly
+                    // the condition under which the control server may substitute the
+                    // step's recorded output. A tool that ran and failed resolves with its
+                    // failure as the result, and is not this branch.
+                    await client.result(work.workId, undefined, errText(err));
+                }
+            }
+        })().catch((err) => logLine("replay.worker_failed", { server: this.serverName, error: errText(err) }));
+    }
+    /**
+     * Take ownership of a run ourselves.
+     *
+     * ORDER MATTERS HERE. The recorder is built (which may mean an auth round
+     * trip) *before* the tier is published, because `dispatch` routes on the tier:
+     * publishing "standalone" first opens a window in which a step is neither
+     * buffered nor recordable, and every `tools/call` in that window is lost.
+     * `dispatch` re-buffers defensively too — belt and braces on a race whose
+     * failure mode is silent data loss.
+     */
+    async becomeStandalone(why) {
+        logLine("tier.standalone", {
+            server: this.serverName,
+            why,
+            records: "MCP calls only — no prompt, no final answer, no built-in steps",
+        });
+        this.recorder = await this.buildRecorder();
+        this.runId = this.recorder.startRun("", {
+            recorder: "baseinstrunner",
+            tier: "standalone",
+            host: { app: process.env.BIR_HOST_APP ?? "unknown", version: process.env.BIR_HOST_VERSION },
+            wrappedServers: [this.serverName],
+            lossy: this.lossyValue,
+            machine: hostname(),
+            cwd: this.opts.cwd,
+        });
+        this.tierValue = "standalone";
+        logLine("run.start", { run: this.runId, tier: "standalone", server: this.serverName });
+        this.flushBuffer();
+    }
+    async buildRecorder() {
+        if (this.opts.recorderFactory) {
+            return (await this.opts.recorderFactory()) ?? new NullRecorder();
+        }
+        const baseUrl = (process.env.BIR_AUTH_URL ?? "").replace(/\/+$/, "");
+        if (!baseUrl) {
+            logLine("recorder.disabled", { why: "BIR_AUTH_URL is not set" });
+            return new NullRecorder();
+        }
+        // Non-interactive: a proxy runs inside the host's process tree with its stdio
+        // bound to the JSON-RPC stream. There is nowhere to prompt, and blocking on
+        // one would hang the host's server startup.
+        const session = await authenticate({ authUrl: baseUrl, nonInteractive: true });
+        if (!session) {
+            logLine("recorder.disabled", { why: "no BaseIn session — run `bir login`" });
+            return new NullRecorder();
+        }
+        return new RemoteRecorder({ baseUrl, session });
+    }
+    /**
+     * Record one completed `tools/call`. Fire-and-forget by contract: it is called
+     * *after* the result is already on its way to the host, and it never awaits.
+     */
+    reportStep(step) {
+        if (this.tierValue === "pending") {
+            this.bufferStep(step);
+            return;
+        }
+        this.dispatch(step);
+    }
+    /** Hold a step until an owner exists. Bounded, and honest when it overflows. */
+    bufferStep(step) {
+        if (this.buffer.length >= 1000) {
+            this.buffer.shift();
+            if (!this.lossyValue) {
+                logLine("run.lossy", { why: "discovery buffer overflowed", server: this.serverName });
+            }
+            this.lossyValue = true;
+        }
+        this.buffer.push(step);
+    }
+    flushBuffer() {
+        const buffered = this.buffer.splice(0, this.buffer.length);
+        for (const step of buffered)
+            this.dispatch(step);
+        if (buffered.length) {
+            logDetail("proxy.buffer_flushed", { server: this.serverName, steps: buffered.length });
+        }
+    }
+    dispatch(step) {
+        if (this.tierValue === "bound" && this.control) {
+            const control = this.control;
+            this.queue.push(async () => {
+                const ok = await control.report(step);
+                if (!ok) {
+                    // §10: the control server died mid-session. Everything after this is
+                    // Tier 2, and the run is flagged lossy — the steps already sent live in
+                    // the bound run, the rest in ours.
+                    logLine("tier.downgrade", {
+                        server: this.serverName,
+                        why: "control server stopped answering",
+                    });
+                    this.control = undefined;
+                    this.lossyValue = true;
+                    await this.becomeStandalone("control server stopped answering");
+                    this.dispatch(step);
+                }
+            });
+            return;
+        }
+        const recorder = this.recorder;
+        const runId = this.runId;
+        if (!recorder || !runId) {
+            // No owner yet — mid-downgrade, or the recorder is still being built.
+            // Buffering costs a moment; dropping costs the step.
+            this.bufferStep(step);
+            return;
+        }
+        const pair = this.ordering.allocatePair();
+        const toolName = step.qualifiedName || qualifyToolName(step.serverName, step.toolName);
+        const toolInput = serializeCapped(redact(step.args));
+        const toolOutput = step.isError ? undefined : serializeCapped(redact(step.result));
+        const toolError = step.isError
+            ? (step.errorMessage ?? serializeCapped(redact(step.result)))
+            : undefined;
+        this.queue.push(() => {
+            recorder.recordToolSelected(runId, pair.selected, { toolName, toolInput });
+            recorder.recordToolResponse(runId, pair.response, { toolName, toolOutput, toolError });
+        });
+    }
+    /** Close the Tier 2 run, if we own one, and drain the queue. */
+    async close() {
+        // Stops the work loop at its next turn. It is not awaited: it may be parked
+        // in a 25 s long-poll, and shutdown does not wait on a poll that will be
+        // answered by the control server closing anyway.
+        this.closing = true;
+        await this.negotiation?.catch(() => undefined);
+        this.flushBuffer();
+        await this.queue.flush();
+        if (this.recorder && this.runId) {
+            this.recorder.finishRun(this.runId, undefined, { durationMs: Date.now() - this.startedAt });
+            await this.recorder.flush(this.runId).catch(() => undefined);
+            logLine("run.finish", {
+                run: this.runId,
+                tier: "standalone",
+                steps: this.ordering.next,
+                lossy: this.lossyValue,
+            });
+        }
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/record/housekeeping.d.ts

@@ -0,0 +1,34 @@
+/**
+ * housekeeping — host tools that are not work, and must not be treated as it.
+ *
+ * A host calls tools of its own that have nothing to do with the user's task.
+ * Claude Code opens a turn with `ToolSearch` to load deferred tool definitions,
+ * and writes a `TodoWrite` list while it plans. Neither reads or changes
+ * anything the user asked about.
+ *
+ * They must be excluded in TWO places, and missing either one is expensive:
+ *
+ *   1. **Recording.** A `ToolSearch` recorded as a step becomes a step of the
+ *      calculated scenario — observed in production as a five-step scenario
+ *      whose first step was `ToolSearch`. That is not merely untidy: the step's
+ *      generated `reasoning` goes into the steering directive the model reads on
+ *      every matched turn (~150 chars of it), it is not an MCP tool so it drags
+ *      the whole scenario from `direct` mode into `steer`, and the analyser
+ *      spends a Claude call writing input/output logic for a tool that has no
+ *      output worth threading.
+ *
+ *   2. **Replay** (`ReplayController.preTool`). A divergence retires the plan,
+ *      so treating the host's first housekeeping call as "the model went
+ *      off-script" kills the replay before the model has had a chance to follow
+ *      it — observed as `replay.diverge ... called=ToolSearch step=0/4`, after
+ *      which the turn cost full price.
+ *
+ * DELIBERATELY TINY. Every entry must be pure host bookkeeping that cannot
+ * possibly be the user's task. `Read`, `Bash` and `Grep` are NOT here: they do
+ * real work, they belong in a recording, and reaching for one mid-replay
+ * usually *is* the model doing the task another way.
+ */
+/** Host tools that are never recorded as steps and never count as divergence. */
+export declare const HOUSEKEEPING_TOOLS: ReadonlySet<string>;
+export declare function isHousekeeping(toolName: string): boolean;
+//# sourceMappingURL=housekeeping.d.ts.map

package/dist/record/housekeeping.js

@@ -0,0 +1,39 @@
+/**
+ * housekeeping — host tools that are not work, and must not be treated as it.
+ *
+ * A host calls tools of its own that have nothing to do with the user's task.
+ * Claude Code opens a turn with `ToolSearch` to load deferred tool definitions,
+ * and writes a `TodoWrite` list while it plans. Neither reads or changes
+ * anything the user asked about.
+ *
+ * They must be excluded in TWO places, and missing either one is expensive:
+ *
+ *   1. **Recording.** A `ToolSearch` recorded as a step becomes a step of the
+ *      calculated scenario — observed in production as a five-step scenario
+ *      whose first step was `ToolSearch`. That is not merely untidy: the step's
+ *      generated `reasoning` goes into the steering directive the model reads on
+ *      every matched turn (~150 chars of it), it is not an MCP tool so it drags
+ *      the whole scenario from `direct` mode into `steer`, and the analyser
+ *      spends a Claude call writing input/output logic for a tool that has no
+ *      output worth threading.
+ *
+ *   2. **Replay** (`ReplayController.preTool`). A divergence retires the plan,
+ *      so treating the host's first housekeeping call as "the model went
+ *      off-script" kills the replay before the model has had a chance to follow
+ *      it — observed as `replay.diverge ... called=ToolSearch step=0/4`, after
+ *      which the turn cost full price.
+ *
+ * DELIBERATELY TINY. Every entry must be pure host bookkeeping that cannot
+ * possibly be the user's task. `Read`, `Bash` and `Grep` are NOT here: they do
+ * real work, they belong in a recording, and reaching for one mid-replay
+ * usually *is* the model doing the task another way.
+ */
+/** Host tools that are never recorded as steps and never count as divergence. */
+export const HOUSEKEEPING_TOOLS = new Set([
+    "ToolSearch",
+    "TodoWrite",
+]);
+export function isHousekeeping(toolName) {
+    return HOUSEKEEPING_TOOLS.has(toolName);
+}
+//# sourceMappingURL=housekeeping.js.map

package/dist/record/queue.d.ts

@@ -0,0 +1,48 @@
+/**
+ * queue — the bounded, fire-and-forget step queue (Phase 8, backpressure).
+ *
+ * Two rules from §3 and §10 meet here:
+ *
+ *   - **Never let recording block a tool call.** Work is enqueued after the
+ *     result is already on its way to the host, and `push` is synchronous.
+ *   - **Never grow without bound.** A recorder that is slow or down must not turn
+ *     into a memory leak in the host's own process tree. Past `capacity` the
+ *     *oldest* item is dropped and the run is flagged `lossy` — losing the start
+ *     of a long run is strictly better than losing its end, which is where the
+ *     final answer lives.
+ *
+ * A dropped item is reported through {@link onDrop} so the flag reaches the run's
+ * metadata rather than dying in a log line.
+ */
+export interface StepQueueOptions {
+    /** Max queued items before the oldest is dropped. Default 1000. */
+    capacity?: number;
+    /** Called once per dropped item, with the running drop total. */
+    onDrop?: (dropped: number) => void;
+    /** Called when a task throws. Sends are best-effort; failure is logged, not retried. */
+    onError?: (err: unknown) => void;
+}
+export declare const DEFAULT_CAPACITY = 1000;
+/** A FIFO of async tasks, drained one at a time, with a hard size bound. */
+export declare class StepQueue {
+    private readonly items;
+    private readonly capacity;
+    private readonly onDrop?;
+    private readonly onError?;
+    /** Resolved (and cleared) every time the queue goes idle. */
+    private readonly waiters;
+    private draining;
+    private droppedCount;
+    constructor(opts?: StepQueueOptions);
+    /** True once anything has been dropped — the run's `lossy` flag. */
+    get lossy(): boolean;
+    get dropped(): number;
+    get size(): number;
+    get busy(): boolean;
+    /** Enqueue work. Synchronous and never throws. */
+    push(task: () => Promise<void> | void): void;
+    private drain;
+    /** Await the queue draining. Resolves immediately when already idle. */
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/record/queue.js

@@ -0,0 +1,96 @@
+/**
+ * queue — the bounded, fire-and-forget step queue (Phase 8, backpressure).
+ *
+ * Two rules from §3 and §10 meet here:
+ *
+ *   - **Never let recording block a tool call.** Work is enqueued after the
+ *     result is already on its way to the host, and `push` is synchronous.
+ *   - **Never grow without bound.** A recorder that is slow or down must not turn
+ *     into a memory leak in the host's own process tree. Past `capacity` the
+ *     *oldest* item is dropped and the run is flagged `lossy` — losing the start
+ *     of a long run is strictly better than losing its end, which is where the
+ *     final answer lives.
+ *
+ * A dropped item is reported through {@link onDrop} so the flag reaches the run's
+ * metadata rather than dying in a log line.
+ */
+export const DEFAULT_CAPACITY = 1000;
+/** A FIFO of async tasks, drained one at a time, with a hard size bound. */
+export class StepQueue {
+    items = [];
+    capacity;
+    onDrop;
+    onError;
+    /** Resolved (and cleared) every time the queue goes idle. */
+    waiters = [];
+    draining = false;
+    droppedCount = 0;
+    constructor(opts = {}) {
+        this.capacity = opts.capacity ?? DEFAULT_CAPACITY;
+        this.onDrop = opts.onDrop;
+        this.onError = opts.onError;
+    }
+    /** True once anything has been dropped — the run's `lossy` flag. */
+    get lossy() {
+        return this.droppedCount > 0;
+    }
+    get dropped() {
+        return this.droppedCount;
+    }
+    get size() {
+        return this.items.length;
+    }
+    get busy() {
+        return this.draining || this.items.length > 0;
+    }
+    /** Enqueue work. Synchronous and never throws. */
+    push(task) {
+        if (this.items.length >= this.capacity) {
+            this.items.shift();
+            this.droppedCount += 1;
+            this.onDrop?.(this.droppedCount);
+        }
+        this.items.push(task);
+        void this.drain();
+    }
+    async drain() {
+        if (this.draining)
+            return;
+        this.draining = true;
+        try {
+            for (;;) {
+                const task = this.items.shift();
+                if (!task)
+                    break;
+                try {
+                    await task();
+                }
+                catch (err) {
+                    this.onError?.(err);
+                }
+            }
+        }
+        finally {
+            this.draining = false;
+            // A task enqueued during the last await is still in `items`; restart
+            // rather than waking waiters on a queue that is not actually empty.
+            if (this.items.length > 0) {
+                void this.drain();
+            }
+            else {
+                const waiting = this.waiters.splice(0, this.waiters.length);
+                for (const resolve of waiting)
+                    resolve();
+            }
+        }
+    }
+    /** Await the queue draining. Resolves immediately when already idle. */
+    flush() {
+        if (!this.busy)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+}
+//# sourceMappingURL=queue.js.map

package/dist/record/recorder.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Recorder — the surface both tiers use (§5).
+ *
+ * Deliberately identical in shape to RRepeat's `RemoteRecorder`, so the BaseIn
+ * service needs no new endpoints for v1: a BaseInstRunner run is the same row
+ * shape as an RRepeat one, discriminated only by `metadata.recorder`.
+ */
+import type { ExecutionStage, ExecutionStepResult } from "../replay/types.js";
+export interface RunMetrics {
+    costUsd?: number;
+    durationMs?: number;
+}
+export interface Recorder {
+    /** Create the run; returns the client-generated runId synchronously. */
+    startRun(input: string, metadata?: Record<string, unknown>): string;
+    recordToolSelected(runId: string, stepIndex: number, d: {
+        toolName: string;
+        toolInput: string;
+        context?: string;
+    }): string;
+    recordToolResponse(runId: string, stepIndex: number, d: {
+        toolName: string;
+        toolOutput?: string;
+        toolError?: string;
+    }): string;
+    recordFinalAnswer(runId: string, stepIndex: number, d: {
+        answer: string;
+    }): string;
+    finishRun(runId: string, finalOutput?: string, metrics?: RunMetrics): void;
+    /** Await every queued send for a run. Called once at session end. */
+    flush(runId: string): Promise<void>;
+}
+/**
+ * A similar-prompt hit reported by `POST /recordings/runs`. On a hit the server
+ * does **not** create a run, so every later step post for that id would 404 —
+ * callers must stop recording it. What the caller does *instead* of recording is
+ * v2's subject (docs/calculatedReplay.md); stopping is mandatory either way.
+ */
+export interface RunMatch {
+    runId: string;
+    scenarioId: string | null;
+    similarity: number;
+    scenario: Record<string, unknown> | null;
+    executionTicket?: string;
+}
+/** Optional capability: `null` means "fresh run, keep recording". */
+export interface MatchAware {
+    getMatch(runId: string): Promise<RunMatch | null>;
+}
+export declare function isMatchAware(r: Recorder): r is Recorder & MatchAware;
+/**
+ * What a matched turn actually cost, reported once per match
+ * (docs/calculatedReplay.md §11).
+ *
+ * `not_steered` and `failed` mean the agent ran the task the ordinary way; the
+ * service files those as **baseline samples** rather than savings, which is what
+ * keeps the ledger's denominator honest. `steered_full` and `diverged` book a
+ * saving against that baseline.
+ */
+export interface ExecutionReport {
+    scenarioId: string;
+    /** The match's claim token. It *is* the execution row's id, so a doubled report books once. */
+    ticket?: string;
+    outcome: "steered_full" | "diverged" | "not_steered" | "failed";
+    /** The derivation call — the only tokens replay itself spends. */
+    deriveCostUsd: number;
+    /** The live turn, from the transcript usage delta. */
+    sessionCostUsd: number;
+    /** Divergence recovery. Zero here by construction: the proxies run for free. */
+    fallbackCostUsd: number;
+    durationMs: number;
+    stepsPlanned: number;
+    stepsPinned: number;
+    /** False when the usage watermark was missing — "unmeasured" beats a wrong baseline. */
+    measured: boolean;
+    pricingVersion: string;
+    prompt?: string;
+    /**
+     * One verdict per step this run reached (errorshandling.md). Absent when the
+     * run reached none — a decline, or a turn that died before the first step.
+     *
+     * This is the only channel through which "step 2 of your scenario throws"
+     * reaches the person who owns the scenario: the log line is on their machine,
+     * the recording page is not.
+     */
+    steps?: ExecutionStepResult[];
+    /** The headline failure, lifted from the first step that broke. */
+    error?: string;
+    errorStage?: ExecutionStage;
+    errorStepIndex?: number;
+    errorToolName?: string;
+}
+/** Optional capability: reporting needs a service, and a NullRecorder has none. */
+export interface ScenarioReporter {
+    reportExecution(report: ExecutionReport): void;
+}
+export declare function isScenarioReporter(r: Recorder): r is Recorder & ScenarioReporter;
+/**
+ * A recorder that drops everything. Used when auth is unavailable: recording is
+ * best-effort, and a session must never fail because BaseIn is unreachable (§10).
+ */
+export declare class NullRecorder implements Recorder {
+    private n;
+    startRun(): string;
+    recordToolSelected(): string;
+    recordToolResponse(): string;
+    recordFinalAnswer(): string;
+    finishRun(): void;
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=recorder.d.ts.map