@basein/runner 0.1.0

package/dist/record/truncate.js

@@ -0,0 +1,85 @@
+/**
+ * truncate — payload size caps (Phase 4.4).
+ *
+ * A single `chrome-devtools` screenshot is a megabyte of base64. Left alone it
+ * dominates the run, the request body and the corpus, and it is worth nothing to
+ * a scenario. So every recorded payload is capped twice:
+ *
+ *   1. **Per string**, so one enormous leaf cannot hide inside an otherwise small
+ *      structure and so the rest of that structure still survives intact.
+ *   2. **Per payload**, on the serialized form, as the actual guarantee. If the
+ *      whole thing still exceeds the cap after step 1 it is replaced by an
+ *      explicit marker rather than silently clipped mid-JSON.
+ *
+ * Truncation is always **visible**: a truncated string keeps a suffix naming the
+ * bytes dropped, and a truncated payload serialises to
+ * `{ truncated: true, originalBytes, preview }`. A consumer can tell a short
+ * result from a clipped one, which is the whole point.
+ */
+/** 64 KiB per payload, as suggested in Phase 4.4. */
+export const DEFAULT_MAX_PAYLOAD_BYTES = 64 * 1024;
+/** 8 KiB per individual string leaf. */
+export const DEFAULT_MAX_STRING_BYTES = 8 * 1024;
+const utf8 = (s) => Buffer.byteLength(s, "utf8");
+/** Clip one string to `max` bytes, appending a marker naming what was dropped. */
+export function truncateString(text, max) {
+    const bytes = utf8(text);
+    if (bytes <= max)
+        return text;
+    // Slice on a byte boundary, then repair any split multi-byte character.
+    const head = Buffer.from(text, "utf8").subarray(0, max).toString("utf8").replace(/�$/, "");
+    return `${head}… [truncated ${bytes - utf8(head)} of ${bytes} bytes]`;
+}
+/** Deep-copy `value`, clipping every string leaf. Input is never mutated. */
+export function truncateStrings(value, max, depth = 0) {
+    if (depth > 32)
+        return "[max depth]";
+    if (typeof value === "string")
+        return truncateString(value, max);
+    if (Array.isArray(value))
+        return value.map((v) => truncateStrings(v, max, depth + 1));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = truncateStrings(v, max, depth + 1);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Serialize `value` for recording, capped and with truncation made explicit.
+ * Never throws: an unserialisable payload becomes a marker string.
+ */
+export function serializeCapped(value, opts = {}) {
+    const maxPayload = opts.maxPayloadBytes ?? DEFAULT_MAX_PAYLOAD_BYTES;
+    const maxString = opts.maxStringBytes ?? DEFAULT_MAX_STRING_BYTES;
+    let original;
+    try {
+        original = JSON.stringify(value) ?? "null";
+    }
+    catch {
+        return JSON.stringify({ truncated: true, reason: "unserializable" });
+    }
+    const originalBytes = utf8(original);
+    if (originalBytes <= maxPayload)
+        return original;
+    let clipped;
+    try {
+        clipped = JSON.stringify(truncateStrings(value, maxString)) ?? "null";
+    }
+    catch {
+        clipped = "null";
+    }
+    if (utf8(clipped) <= maxPayload) {
+        return JSON.stringify({ truncated: true, originalBytes, value: JSON.parse(clipped) });
+    }
+    // Still too big: the structure itself is the problem (thousands of nodes, not
+    // one fat leaf). Keep a readable preview and say so.
+    return JSON.stringify({
+        truncated: true,
+        originalBytes,
+        preview: truncateString(clipped, Math.max(1024, Math.floor(maxPayload / 2))),
+    });
+}
+//# sourceMappingURL=truncate.js.map

package/dist/replay/bundle.d.ts

@@ -0,0 +1,36 @@
+/**
+ * bundle — laying executed steps out as text the model can answer from
+ * (docs/calculatedReplay.md §8).
+ *
+ * Ported from RRepeat's `payload-executor.ts`, whose fair-share rule is the
+ * right one and is worth restating: a naive "truncate the whole thing at N"
+ * drops the *last* steps entirely, and the last steps are the ones carrying the
+ * answer. So labels and computed inputs get a fixed budget, and whatever remains
+ * is split evenly across the N responses — every step stays represented, and the
+ * ones that were shortened say so.
+ *
+ * `recorded: true` marks a response that came from the source run rather than a
+ * fresh execution (§8.1). It is surfaced in the header *and* per entry, because
+ * a bundle that quietly passed off a stale result as a live one would be the
+ * worst outcome available here.
+ */
+/** `permissionDecisionReason` is fed to the model as text; keep denials bounded. */
+export declare const MAX_REPLAY_REASON = 60000;
+/** One executed step, pre-stringified and ready to lay out. */
+export interface BundleEntry {
+    toolName: string;
+    /** JSON of the computed tool input, already capped. */
+    input: string;
+    response: string;
+    /** True when `response` is a recorded output, not a fresh run. */
+    recorded?: boolean;
+}
+/** Cap a computed input for inclusion in a bundle. */
+export declare function bundleInput(value: unknown): string;
+/**
+ * Compose the bundle. `maxChars` is a hard ceiling on the returned string.
+ */
+export declare function assembleBundle(entries: readonly BundleEntry[], maxChars: number): string;
+/** Truncate to `max` chars, appending a marker naming how much was dropped. */
+export declare function truncate(s: string, max: number): string;
+//# sourceMappingURL=bundle.d.ts.map

package/dist/replay/bundle.js

@@ -0,0 +1,89 @@
+/**
+ * bundle — laying executed steps out as text the model can answer from
+ * (docs/calculatedReplay.md §8).
+ *
+ * Ported from RRepeat's `payload-executor.ts`, whose fair-share rule is the
+ * right one and is worth restating: a naive "truncate the whole thing at N"
+ * drops the *last* steps entirely, and the last steps are the ones carrying the
+ * answer. So labels and computed inputs get a fixed budget, and whatever remains
+ * is split evenly across the N responses — every step stays represented, and the
+ * ones that were shortened say so.
+ *
+ * `recorded: true` marks a response that came from the source run rather than a
+ * fresh execution (§8.1). It is surfaced in the header *and* per entry, because
+ * a bundle that quietly passed off a stale result as a live one would be the
+ * worst outcome available here.
+ */
+/** `permissionDecisionReason` is fed to the model as text; keep denials bounded. */
+export const MAX_REPLAY_REASON = 60_000;
+/** Cap each computed input so one huge argument object cannot starve responses. */
+const MAX_INPUT_CHARS = 2_000;
+/** Fixed structural overhead reserved per step (labels, separators). */
+const PER_STEP_OVERHEAD = 80;
+/** Cap a computed input for inclusion in a bundle. */
+export function bundleInput(value) {
+    let text;
+    try {
+        text = JSON.stringify(value) ?? "null";
+    }
+    catch {
+        text = "[unserializable]";
+    }
+    return truncate(text, MAX_INPUT_CHARS);
+}
+/**
+ * The header must say what actually happened. Every entry not marked `recorded`
+ * was executed for real, moments ago, against the live system — and a model told
+ * the opposite ("previously recorded") cannot verify a write without calling a
+ * tool, so it reasonably redoes the whole task. On a CRUD scenario that measured
+ * at +40% over baseline with perfect plumbing (docs/mcpmark.md §12).
+ */
+const LIVE_HEADER = "[BaseInstRunner calculated replay] The tool sequence below has JUST been executed " +
+    "for real, moments ago, against the live system, on the user's behalf. Every result " +
+    "is that call's actual output, and every side effect — rows written, tables created, " +
+    "files changed — is already in place. Do NOT repeat, redo or re-verify this work, and " +
+    "do NOT call any tools. Answer the user's request from these results.";
+const LIVE_FOOTER = "\n\nThe work above is already done. Answer the user's request from these results. " +
+    "Do not call any tools.";
+/** Some entry stood in from the source run: say which, and keep the caveat. */
+const MIXED_HEADER = "[BaseInstRunner calculated replay] A known-good tool sequence was executed for this " +
+    "request. Below are the tool calls and their results, in order. Steps not marked " +
+    "(recorded) ran for real just now and their side effects are already in place. " +
+    "Results marked (recorded) come from an earlier recording rather than a fresh run, " +
+    "because their tool cannot be executed here — treat them as possibly out of date. " +
+    "Use them to answer the user's request now — do NOT call any tools.";
+const MIXED_FOOTER = "\n\nAnswer the user's request using the results above. Do not call any tools.";
+/**
+ * Compose the bundle. `maxChars` is a hard ceiling on the returned string.
+ */
+export function assembleBundle(entries, maxChars) {
+    const n = entries.length;
+    const anyRecorded = entries.some((e) => e.recorded);
+    const header = anyRecorded ? MIXED_HEADER : LIVE_HEADER;
+    const footer = anyRecorded ? MIXED_FOOTER : LIVE_FOOTER;
+    const fixedCost = header.length +
+        footer.length +
+        entries.reduce((sum, e) => sum + PER_STEP_OVERHEAD + e.toolName.length + e.input.length, 0);
+    const responseBudget = Math.max(0, maxChars - fixedCost);
+    const perResponse = n > 0 ? Math.floor(responseBudget / n) : responseBudget;
+    const sections = entries.map((e, i) => {
+        const response = truncate(e.response, perResponse);
+        return (`\n\n--- Step ${i + 1}: ${e.toolName} ---\n` +
+            `Call: ${e.input}\n` +
+            `Result${e.recorded ? " (recorded)" : ""}: ${response}`);
+    });
+    return truncate(header + sections.join("") + footer, maxChars);
+}
+/** Truncate to `max` chars, appending a marker naming how much was dropped. */
+export function truncate(s, max) {
+    if (max <= 0)
+        return "";
+    if (s.length <= max)
+        return s;
+    const marker = (dropped) => `…[truncated ${dropped} chars]`;
+    // Reserve room for the marker so the total stays within `max`.
+    const reserve = marker(s.length).length;
+    const keep = Math.max(0, max - reserve);
+    return s.slice(0, keep) + marker(s.length - keep);
+}
+//# sourceMappingURL=bundle.js.map

package/dist/replay/controller.d.ts

@@ -0,0 +1,300 @@
+/**
+ * controller — everything replay decides, in one place (docs/calculatedReplay.md).
+ *
+ * The control server owns runs, ordering and recording. This owns the *plan*:
+ * the gate ladder, the mode choice, arming, pinning, threading, direct
+ * execution, divergence recovery and the execution report. `ControlServer`
+ * delegates to it and stores one {@link ReplayState} per run.
+ *
+ * THE GOVERNING RULE IS UNCHANGED and outranks every optimisation here: the host
+ * session must never fail because of BaseInstRunner. Every method below either
+ * degrades to "run the turn normally" or returns something the session can
+ * ignore. Nothing throws at a hook.
+ */
+import type { ExecutionReport } from "../record/recorder.js";
+import { type ReplayMode, type StepReach } from "./coverage.js";
+import { deriveParameters } from "./derive.js";
+import { ProxyWorkQueue } from "./executor.js";
+import { ScenarioReplayPlan } from "./plan.js";
+import { SourceRunOutputs } from "./source-run.js";
+import { type ExecutionOutcome, type ExecutionStepResult, type SerializedScenario } from "./types.js";
+/** The first-party tool a `direct` plan is delivered through (§6.3). */
+export declare const DIRECT_TOOL_NAME = "mcp__bir__run_scenario";
+/** How long a `/proxy/poll` is held open before it answers empty. */
+export declare const POLL_HOLD_MS = 25000;
+export interface ReplayBudgets {
+    /** How long `/session/prompt` waits for the match. */
+    matchMs: number;
+    /** How long the first `PreToolUse` waits for derivation. */
+    deriveMs: number;
+    /** Ceiling on a whole direct plan. */
+    planMs: number;
+    /** Ceiling on one direct `tools/call`. */
+    stepMs: number;
+}
+export declare const DEFAULT_BUDGETS: ReplayBudgets;
+export interface ReplayOptions {
+    /** `BIR_REPLAY=1`. Everything here is inert when false. */
+    enabled: boolean;
+    /** Minimum similarity to steer — deliberately above the service's detection threshold. */
+    minSimilarity: number;
+    /** `BIR_REPLAY_ALLOW_SERVERS`; undefined means every wrapped server. */
+    allowServers?: ReadonlySet<string>;
+    budgets?: Partial<ReplayBudgets>;
+    /** For the lazy source-run fetch and nothing else. */
+    authUrl?: string;
+    authToken?: () => string;
+    /** Injected by tests. */
+    deriveImpl?: typeof deriveParameters;
+    fetchImpl?: typeof fetch;
+    /** Anthropic key for derivation. Absent → recorded sample values, free. */
+    apiKey?: string;
+}
+/** One pinned call, remembered so its output is threaded from the right source. */
+interface PinnedCall {
+    stepIndex: number;
+    reach: StepReach;
+    toolName: string;
+    /** When it was pinned — a steered step's duration is measured across hooks. */
+    pinnedAt: number;
+}
+/**
+ * Per-run replay state. Created on every match — including declined ones,
+ * because a decline still has to be reported as a baseline sample (§11.1).
+ */
+export interface ReplayState {
+    scenarioId: string | null;
+    ticket?: string;
+    similarity: number;
+    matchedRunId: string;
+    mode: ReplayMode;
+    /** Server keys a proxy wraps — decides where an output is threaded from (§7.2). */
+    wrapped: ReadonlySet<string>;
+    /** Undefined when a gate declined. */
+    plan?: ScenarioReplayPlan;
+    /** `tool_use_id` → the step it pinned. */
+    pinned: Map<string, PinnedCall>;
+    outcome: ExecutionOutcome;
+    deriveCostUsd: number;
+    fallbackCostUsd: number;
+    stepsPlanned: number;
+    stepsPinned: number;
+    /**
+     * One verdict per step this run reached, by `stepIndex`. Reported with the
+     * execution so the recording page can say which step of the chain failed and
+     * why, instead of showing a healthy-looking scenario that never works.
+     *
+     * A map, not an array: a steered step is decided across two hooks (pinned in
+     * `PreToolUse`, threaded in `PostToolUse`), and the second word on a step
+     * replaces the first rather than appending a second verdict for it.
+     */
+    stepResults: Map<number, ExecutionStepResult>;
+    armedAt: number;
+    reported: boolean;
+    sourceRun?: SourceRunOutputs;
+    /** Set once a plan has been retired, so nothing re-arms mid-turn. */
+    retired: boolean;
+}
+/** What `PreToolUse` should do about this call. */
+export type PreToolAction = 
+/** Pin the arguments and let the real tool run. */
+{
+    kind: "pin";
+    input: Record<string, unknown>;
+    stepIndex: number;
+}
+/** Not ours — the server handles it normally. */
+ | {
+    kind: "passthrough";
+}
+/** Rewrite a `Bash` call to `cat` the bundle, so the model reads real output. */
+ | {
+    kind: "bash";
+    command: string;
+}
+/** Deny this call, handing the bundle back as the reason. */
+ | {
+    kind: "deny";
+    reason: string;
+}
+/** Give up; continue as an ordinary turn. */
+ | {
+    kind: "abort";
+};
+export declare class ReplayController {
+    readonly enabled: boolean;
+    readonly work: ProxyWorkQueue;
+    readonly budgets: ReplayBudgets;
+    private readonly opts;
+    constructor(opts: ReplayOptions);
+    /** The plan's own delivery vehicle is never a scenario step. */
+    isDirectTool(toolName: string): boolean;
+    /**
+     * Await a match under {@link ReplayBudgets.matchMs}.
+     *
+     * Budget expiry is not an error and never blocks the user: it means this turn
+     * runs normally, and the one `replay.decision` line says so. Resolving `null`
+     * covers both "no match" and "too slow", which are the same thing from here.
+     */
+    awaitMatch(pending: Promise<unknown>): Promise<RunMatchLike | null>;
+    /**
+     * Run the gate ladder and, if every gate passes, arm a plan.
+     *
+     * Always returns a state — a declined match still has a ticket to redeem and a
+     * baseline sample to contribute, and losing that is how a savings ledger ends
+     * up with a denominator nobody measured.
+     */
+    arm(match: RunMatchLike, prompt: string, wrapped: ReadonlySet<string>): ReplayState;
+    /** The directive to inject via `additionalContext`, or undefined when declined. */
+    directiveFor(state: ReplayState): string | undefined;
+    /**
+     * `PreToolUse`, while a plan is active.
+     *
+     * Three tiers (§8): pin the expected call; on divergence execute the remainder
+     * and hand it back through the best channel available; if even that fails,
+     * abort to an ordinary turn.
+     */
+    preTool(state: ReplayState, toolName: string, toolUseId: string): Promise<PreToolAction>;
+    /**
+     * `PostToolUse` for a call this plan pinned.
+     *
+     * `output` must be serialized the way the step's output was **recorded**: for a
+     * wrapped MCP step that is the proxy's whole `CallToolResult`, which is why the
+     * server threads those from `/proxy/step` rather than from the hook (§7.2).
+     * Returns true when the plan is now complete.
+     */
+    postTool(state: ReplayState, toolUseId: string, output: string): boolean;
+    /** Whether a pinned call's output is threaded from the proxy's report (§7.2). */
+    threadsFromProxy(state: ReplayState, toolUseId: string): boolean;
+    /** True when this call belongs to the active plan. */
+    isPinned(state: ReplayState, toolUseId: string): boolean;
+    /**
+     * `POST /scenario/run` — the whole of a `direct` plan, executed here.
+     *
+     * Every step runs through the proxy that already owns its upstream, so the
+     * model spends nothing beyond the turn that reads the results.
+     */
+    runArmed(state: ReplayState): Promise<{
+        ok: boolean;
+        why?: string;
+        text?: string;
+        responseModel?: Record<string, unknown>;
+        steps?: number;
+        partial?: boolean;
+    }>;
+    /**
+     * Build the execution report for a sealed run, or undefined when there is
+     * nothing to report.
+     *
+     * `costUsd <= 0` on a decline is not worth sending: the service answers
+     * `202 { recorded: false }` for a baseline sample with no measured cost, and a
+     * report that books nothing is noise on both sides.
+     */
+    buildReport(state: ReplayState, d: {
+        sessionCostUsd: number;
+        measured: boolean;
+        durationMs: number;
+        prompt?: string;
+    }): ExecutionReport | undefined;
+    /**
+     * The step a failed replay is fairly blamed on: the first whose own logic
+     * threw, or failing that the first that could not run at all.
+     *
+     * A `failed` step outranks a `skipped` one however early the skip came — a
+     * scenario whose logic throws is broken for everybody, while a step that could
+     * not run here says something about this machine.
+     */
+    private blameStep;
+    /**
+     * Run a scenario that no match armed — `bir replay` (§12.1).
+     *
+     * The same plan, the same executor, the same live proxies; only the trigger
+     * differs. It is how you test a scenario without a session, how a Tier 2 or
+     * non-Claude-Code client gets any replay at all, and the first thing to reach
+     * for when a steered turn behaves oddly.
+     *
+     * Deliberately outside the gate ladder: the operator typed the scenario id, so
+     * there is nothing to be similar *to* and nothing to decline. It books no
+     * execution either — there is no ticket, and inventing a saving for a manual
+     * invocation is exactly the kind of number a ledger must never contain.
+     */
+    runAdHoc(scenario: SerializedScenario, prompt: string, wrapped: ReadonlySet<string>): Promise<{
+        ok: boolean;
+        why?: string;
+        text?: string;
+        responseModel?: Record<string, unknown>;
+        steps?: number;
+        partial?: boolean;
+        trace?: Array<{
+            step: number;
+            tool: string;
+            input: unknown;
+            outcome: string;
+            ms: number;
+        }>;
+    }>;
+    /** Release every parked poller. Called at control-server shutdown. */
+    close(): void;
+    /**
+     * Kick off derivation without awaiting it (§10). The prompt hook returns the
+     * directive the moment the match lands; the first `PreToolUse` — or
+     * `/scenario/run`, which has no hook timeout at all — is where the wait lands.
+     */
+    private startDerivation;
+    /**
+     * Divergence (§8). Execute the remaining steps for real, then deliver.
+     *
+     * The plan is retired first: whatever happens next, this turn neither steers
+     * nor re-injects again.
+     */
+    private diverge;
+    /**
+     * The executor handed to a plan: dispatch a step to the proxy that owns its
+     * upstream.
+     *
+     * Rejecting means "could not be run **here**" — which is the only condition
+     * under which a recorded output may stand in. A tool that ran and failed
+     * resolves with its failure as the response, exactly as it would in a session.
+     */
+    private executeStep;
+    /**
+     * Where a pinned step's output will arrive from — the proxy's report, or the
+     * hook's `tool_response` (§7.2).
+     *
+     * NOT the same question as {@link reachOf}'s, and conflating them is a silent
+     * bug. `reachOf` answers "may *we* execute this step ourselves", which the
+     * allowlist restricts. This answers "will a `bir-proxy` see this call and
+     * report it", which depends only on whether the server is **wrapped** — a
+     * wrapped server the allowlist excludes is still proxied, still reported, and
+     * still recorded in the proxy's serialization. Threading such a step from the
+     * hook's differently-shaped view would derive nothing at all.
+     */
+    private reachFor;
+    /**
+     * Log a step and remember its verdict, in that order.
+     *
+     * Every driver passes this — direct, divergence recovery and ad-hoc alike — so
+     * there is exactly one place a step's fate is decided, and the console can
+     * never be told something the log does not also say.
+     */
+    private observeStep;
+    /** Upsert one step's verdict. Later news about a step replaces earlier news. */
+    private recordStep;
+    /** The step verdicts, in chain order, for the execution report. */
+    private stepResultsOf;
+    private logStep;
+    /** Outcomes only move forward; `not_steered` is the floor (§11.1). */
+    private upgrade;
+    private retire;
+    private withBudget;
+}
+/** The subset of `RunMatch` replay consumes. Structural, so tests need no recorder. */
+export interface RunMatchLike {
+    runId: string;
+    scenarioId: string | null;
+    similarity: number;
+    scenario: Record<string, unknown> | null;
+    executionTicket?: string;
+}
+export {};
+//# sourceMappingURL=controller.d.ts.map