@basein/runner 0.1.0

package/dist/replay/coverage.d.ts

@@ -0,0 +1,41 @@
+/**
+ * coverage — which rung of the ladder a scenario lands on (docs/calculatedReplay.md §5).
+ *
+ * The whole mode decision is a pure function of two things: the scenario's step
+ * list, and the set of server keys a `bir-proxy` has registered for this session.
+ * That is the §0 asymmetry made mechanical — a step whose tool we can reach on a
+ * connection we already hold costs nothing to run, and a step we cannot reach can
+ * only happen inside the live session.
+ *
+ * `live` covers three genuinely different cases and treats them identically,
+ * correctly: a built-in (`Bash`, `Read`, `Edit`, …), an MCP server the user chose
+ * not to wrap, and `claude-in-chrome` — which is `scope: "dynamic"`, appears in
+ * no config file, and therefore can never be wrapped at all.
+ */
+import type { SerializedScenarioStep } from "./types.js";
+/** Where a step's tool can actually be executed. */
+export type StepReach = "direct" | "live";
+/** How the whole scenario will be run. */
+export type ReplayMode = "direct" | "steer" | "none";
+/**
+ * `direct` when the tool is `mcp__<server>__<tool>` for a server this control
+ * plane has a proxy for; `live` otherwise.
+ *
+ * `allow` is the `BIR_REPLAY_ALLOW_SERVERS` allowlist (§13.2, mitigation 2): a
+ * wrapped server outside it is deliberately demoted to `live`, so it can still be
+ * steered inside the session — where the user's own permission rules apply — but
+ * is never called unattended by us.
+ */
+export declare function reachOf(toolName: string, wrapped: ReadonlySet<string>, allow?: ReadonlySet<string>): StepReach;
+/** The mode for a whole scenario: `direct` only when *every* step is reachable. */
+export declare function modeFor(steps: readonly SerializedScenarioStep[], wrapped: ReadonlySet<string>, allow?: ReadonlySet<string>): ReplayMode;
+/** Per-step reach, in step order — what `plan.armed` logs and `bir doctor` shows. */
+export declare function coverageOf(steps: readonly SerializedScenarioStep[], wrapped: ReadonlySet<string>, allow?: ReadonlySet<string>): StepReach[];
+/**
+ * Parse `BIR_REPLAY_ALLOW_SERVERS`. Unset (or empty) means *every wrapped
+ * server*, which is why the return is `undefined` rather than an empty set — an
+ * empty allowlist that silently allowed nothing would look like a broken replay,
+ * and one that silently allowed everything would defeat the flag.
+ */
+export declare function parseAllowList(value: string | undefined): ReadonlySet<string> | undefined;
+//# sourceMappingURL=coverage.d.ts.map

package/dist/replay/coverage.js

@@ -0,0 +1,56 @@
+/**
+ * coverage — which rung of the ladder a scenario lands on (docs/calculatedReplay.md §5).
+ *
+ * The whole mode decision is a pure function of two things: the scenario's step
+ * list, and the set of server keys a `bir-proxy` has registered for this session.
+ * That is the §0 asymmetry made mechanical — a step whose tool we can reach on a
+ * connection we already hold costs nothing to run, and a step we cannot reach can
+ * only happen inside the live session.
+ *
+ * `live` covers three genuinely different cases and treats them identically,
+ * correctly: a built-in (`Bash`, `Read`, `Edit`, …), an MCP server the user chose
+ * not to wrap, and `claude-in-chrome` — which is `scope: "dynamic"`, appears in
+ * no config file, and therefore can never be wrapped at all.
+ */
+import { parseQualifiedName } from "../control/correlation.js";
+/**
+ * `direct` when the tool is `mcp__<server>__<tool>` for a server this control
+ * plane has a proxy for; `live` otherwise.
+ *
+ * `allow` is the `BIR_REPLAY_ALLOW_SERVERS` allowlist (§13.2, mitigation 2): a
+ * wrapped server outside it is deliberately demoted to `live`, so it can still be
+ * steered inside the session — where the user's own permission rules apply — but
+ * is never called unattended by us.
+ */
+export function reachOf(toolName, wrapped, allow) {
+    const mcp = parseQualifiedName(toolName);
+    if (!mcp || !wrapped.has(mcp.serverName))
+        return "live";
+    if (allow && !allow.has(mcp.serverName))
+        return "live";
+    return "direct";
+}
+/** The mode for a whole scenario: `direct` only when *every* step is reachable. */
+export function modeFor(steps, wrapped, allow) {
+    if (steps.length === 0)
+        return "none";
+    return steps.every((s) => reachOf(s.toolName, wrapped, allow) === "direct") ? "direct" : "steer";
+}
+/** Per-step reach, in step order — what `plan.armed` logs and `bir doctor` shows. */
+export function coverageOf(steps, wrapped, allow) {
+    return steps.map((s) => reachOf(s.toolName, wrapped, allow));
+}
+/**
+ * Parse `BIR_REPLAY_ALLOW_SERVERS`. Unset (or empty) means *every wrapped
+ * server*, which is why the return is `undefined` rather than an empty set — an
+ * empty allowlist that silently allowed nothing would look like a broken replay,
+ * and one that silently allowed everything would defeat the flag.
+ */
+export function parseAllowList(value) {
+    const names = (value ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return names.length > 0 ? new Set(names) : undefined;
+}
+//# sourceMappingURL=coverage.js.map

package/dist/replay/derive.d.ts

@@ -0,0 +1,58 @@
+/**
+ * derive — fill a scenario's parameter schema from the live prompt
+ * (docs/calculatedReplay.md §16.3).
+ *
+ * The only tokens replay itself spends. One Haiku call, over raw `fetch`.
+ *
+ * NO SDK, ON PURPOSE. `bir-proxy` is spawned inside the host's process tree for
+ * *every* wrapped server; an npm install that drags a model SDK into that path is
+ * a startup-latency and supply-chain cost paid N times per session, for a feature
+ * most sessions never arm. This is ~40 lines of `fetch` and it keeps the package
+ * at zero runtime dependencies.
+ *
+ * NO KEY IS A SUPPORTED CONFIGURATION. Without `ANTHROPIC_API_KEY` the extraction
+ * is skipped entirely and every parameter takes the value it had in the recorded
+ * run — a plain replay of the recorded parameters, at zero cost. For a scenario
+ * whose parameters rarely change that is a complete, free replay; for one that
+ * keys off the prompt, it is why you want the key.
+ *
+ * The prompt and the parsing tolerances mirror RRepeat's
+ * `deriveParametersFromScenarioPayload` exactly, so the two produce the same
+ * parameters from the same prompt — otherwise a scenario would behave one way
+ * under RRepeat and another under BaseInstRunner.
+ */
+import type { ParamsSchema } from "./types.js";
+export declare const DEFAULT_DERIVE_MODEL = "claude-haiku-4-5-20251001";
+export interface DeriveOptions {
+    prompt: string;
+    intent: string;
+    paramsObject: ParamsSchema | null;
+    /** Absent → sample values, at zero cost. */
+    apiKey?: string;
+    model?: string;
+    signal?: AbortSignal;
+    /** Injected by tests. Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+export interface DeriveResult {
+    params: Record<string, unknown>;
+    costUsd: number;
+    /** False when the values came from the recorded samples rather than the model. */
+    derived: boolean;
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+}
+/**
+ * First balanced `{…}` in a text blob. Models wrap JSON in prose and fences more
+ * often than they emit it bare, and a failed parse here costs a whole replay.
+ */
+export declare function extractJsonObject(text: string): string | undefined;
+/**
+ * Derive the scenario's parameters from `prompt`. Never throws: every failure
+ * path resolves with the recorded sample values, because a replay with stale
+ * parameters is worth more than no replay, and the caller's audit line is what
+ * records which happened.
+ */
+export declare function deriveParameters(opts: DeriveOptions): Promise<DeriveResult>;
+//# sourceMappingURL=derive.d.ts.map

package/dist/replay/derive.js

@@ -0,0 +1,166 @@
+/**
+ * derive — fill a scenario's parameter schema from the live prompt
+ * (docs/calculatedReplay.md §16.3).
+ *
+ * The only tokens replay itself spends. One Haiku call, over raw `fetch`.
+ *
+ * NO SDK, ON PURPOSE. `bir-proxy` is spawned inside the host's process tree for
+ * *every* wrapped server; an npm install that drags a model SDK into that path is
+ * a startup-latency and supply-chain cost paid N times per session, for a feature
+ * most sessions never arm. This is ~40 lines of `fetch` and it keeps the package
+ * at zero runtime dependencies.
+ *
+ * NO KEY IS A SUPPORTED CONFIGURATION. Without `ANTHROPIC_API_KEY` the extraction
+ * is skipped entirely and every parameter takes the value it had in the recorded
+ * run — a plain replay of the recorded parameters, at zero cost. For a scenario
+ * whose parameters rarely change that is a complete, free replay; for one that
+ * keys off the prompt, it is why you want the key.
+ *
+ * The prompt and the parsing tolerances mirror RRepeat's
+ * `deriveParametersFromScenarioPayload` exactly, so the two produce the same
+ * parameters from the same prompt — otherwise a scenario would behave one way
+ * under RRepeat and another under BaseInstRunner.
+ */
+import { calculateCostUsd } from "./pricing.js";
+export const DEFAULT_DERIVE_MODEL = "claude-haiku-4-5-20251001";
+const ANTHROPIC_URL = "https://api.anthropic.com/v1/messages";
+const ANTHROPIC_VERSION = "2023-06-01";
+/** Every parameter at its recorded sample value. The zero-cost fallback. */
+function sampleValues(schema) {
+    const out = {};
+    for (const key of Object.keys(schema))
+        out[key] = schema[key].sampleValue;
+    return out;
+}
+/**
+ * First balanced `{…}` in a text blob. Models wrap JSON in prose and fences more
+ * often than they emit it bare, and a failed parse here costs a whole replay.
+ */
+export function extractJsonObject(text) {
+    const start = text.indexOf("{");
+    if (start === -1)
+        return undefined;
+    let depth = 0;
+    let inStr = false;
+    let esc = false;
+    for (let i = start; i < text.length; i += 1) {
+        const ch = text[i];
+        if (inStr) {
+            if (esc)
+                esc = false;
+            else if (ch === "\\")
+                esc = true;
+            else if (ch === '"')
+                inStr = false;
+            continue;
+        }
+        if (ch === '"')
+            inStr = true;
+        else if (ch === "{")
+            depth += 1;
+        else if (ch === "}") {
+            depth -= 1;
+            if (depth === 0)
+                return text.slice(start, i + 1);
+        }
+    }
+    return undefined;
+}
+function buildExtractionPrompt(prompt, intent, schema) {
+    const descriptions = Object.keys(schema)
+        .map((key) => {
+        const { description, sampleValue } = schema[key];
+        return `- ${key}: ${description} (sample: ${JSON.stringify(sampleValue)})`;
+    })
+        .join("\n");
+    return `You are extracting parameter values from a user prompt to execute a pre-defined scenario.
+
+Scenario intent: ${intent}
+
+Parameters needed (with sample values from past runs):
+${descriptions}
+
+User prompt:
+${prompt}
+
+Extract the parameter values from the user prompt. If a value is not explicitly mentioned, infer a reasonable default from the sample values above.
+
+Respond ONLY with a valid JSON object mapping each parameter name to its value. No markdown fences, no prose.
+Example: { "directory": "src/utils", "pattern": "*.ts" }`;
+}
+/**
+ * Derive the scenario's parameters from `prompt`. Never throws: every failure
+ * path resolves with the recorded sample values, because a replay with stale
+ * parameters is worth more than no replay, and the caller's audit line is what
+ * records which happened.
+ */
+export async function deriveParameters(opts) {
+    const schema = opts.paramsObject ?? {};
+    const keys = Object.keys(schema);
+    if (keys.length === 0)
+        return { params: {}, costUsd: 0, derived: false };
+    const apiKey = opts.apiKey ?? process.env.ANTHROPIC_API_KEY;
+    if (!apiKey)
+        return { params: sampleValues(schema), costUsd: 0, derived: false };
+    const model = opts.model ?? process.env.BIR_DERIVE_MODEL ?? DEFAULT_DERIVE_MODEL;
+    const doFetch = opts.fetchImpl ?? fetch;
+    const res = await doFetch(ANTHROPIC_URL, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "x-api-key": apiKey,
+            "anthropic-version": ANTHROPIC_VERSION,
+        },
+        body: JSON.stringify({
+            model,
+            max_tokens: 2024,
+            messages: [
+                { role: "user", content: buildExtractionPrompt(opts.prompt, opts.intent, schema) },
+            ],
+        }),
+        signal: opts.signal,
+    });
+    if (!res.ok) {
+        const detail = await res.text().catch(() => "");
+        throw new Error(`derive failed: HTTP ${res.status}${detail ? ` — ${detail.slice(0, 200)}` : ""}`);
+    }
+    const body = (await res.json());
+    const text = (body.content ?? [])
+        .filter((b) => b.type === "text")
+        .map((b) => b.text ?? "")
+        .join("");
+    const inputTokens = body.usage?.input_tokens ?? 0;
+    const outputTokens = body.usage?.output_tokens ?? 0;
+    const costUsd = calculateCostUsd(model, {
+        inputTokens,
+        outputTokens,
+        cacheReadTokens: body.usage?.cache_read_input_tokens ?? 0,
+        cacheCreationTokens: body.usage?.cache_creation_input_tokens ?? 0,
+    });
+    // `undefined` is not JSON, but models emit it; normalise before parsing so one
+    // stray token does not cost the whole extraction.
+    const normalized = text.replace(/:\s*undefined\b/g, ": null");
+    const cleaned = extractJsonObject(normalized) ??
+        normalized
+            .replace(/^```(?:json)?\s*/m, "")
+            .replace(/\s*```\s*$/m, "")
+            .trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(cleaned);
+    }
+    catch {
+        throw new Error(`derive returned invalid JSON: ${text.slice(0, 200)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("derive returned a non-object");
+    }
+    // A missing or null key falls back to its recorded sample, so a partial
+    // extraction still yields a runnable parameter set.
+    for (const key of keys) {
+        if (parsed[key] === null || parsed[key] === undefined)
+            parsed[key] = schema[key].sampleValue;
+    }
+    return { params: parsed, costUsd, derived: true, model, inputTokens, outputTokens };
+}
+//# sourceMappingURL=derive.js.map

package/dist/replay/executor.d.ts

@@ -0,0 +1,78 @@
+/**
+ * executor — how the control server makes a proxy run a tool
+ * (docs/calculatedReplay.md §16.2).
+ *
+ * THE ASYMMETRY THIS EXISTS TO EXPLOIT. Every wrapped server is already reached
+ * through a `bir-proxy` holding an initialized, live `UpstreamClient`. Issuing a
+ * `tools/call` on that connection costs **zero tokens** — no second agent, no
+ * subprocess, no model in the loop. That is the whole reason this design has a
+ * free rung where RRepeat has an Agent SDK session.
+ *
+ * WHY LONG-POLLING, AND NOT A CALLBACK URL (D12). The control plane was
+ * one-directional: proxies dial out to report steps. Keeping it that way costs
+ * nothing here — the proxy holds one request open, the server answers it with
+ * work — and it avoids N new loopback listeners, N new tokens and N new things
+ * `bir doctor` must verify, for a latency saving of milliseconds on a path
+ * already dominated by the upstream's own round trip.
+ *
+ * A proxy that never polls (an old build, or one started without `BIR_REPLAY`)
+ * is not an error: `call` rejects with `no_proxy`, and the caller falls back to
+ * the step's recorded output.
+ */
+/** One dispatched tool call, as the proxy receives it. */
+export interface Work {
+    workId: string;
+    /** Upstream-local name (`navigate_page`), not `mcp__server__navigate_page`. */
+    toolName: string;
+    arguments: unknown;
+    timeoutMs: number;
+}
+/** Rejection reason when no proxy is polling for a server. */
+export declare const NO_PROXY = "no_proxy";
+export declare class ProxyWorkQueue {
+    /** Work dispatched while its proxy was mid-round-trip, per server. */
+    private readonly pending;
+    /** Pollers currently parked, per server. */
+    private readonly waiters;
+    /** Work handed out and awaiting a result. */
+    private readonly inFlight;
+    /** serverName → when it last polled. A proxy between polls is still present. */
+    private readonly lastSeen;
+    private closed;
+    /** Servers a proxy is currently serving — what `bir doctor` reports. */
+    pollingServers(): string[];
+    /** True when a proxy for `serverName` is available to take work. */
+    hasPoller(serverName: string): boolean;
+    /** Parked now, or polled recently enough to be mid-round-trip. */
+    private isPresent;
+    /**
+     * `POST /proxy/poll`. Resolves with work, or with `undefined` at the poll
+     * deadline so the proxy re-polls. Work queued while this proxy was between
+     * polls is handed over immediately.
+     */
+    waitForWork(serverName: string, pollDeadlineMs: number, signal?: AbortSignal): Promise<Work | undefined>;
+    /** `POST /proxy/result`. Unknown ids are ignored — a late result after a timeout. */
+    complete(workId: string, result?: unknown, error?: string): boolean;
+    /**
+     * Dispatch one call and await its result.
+     *
+     * Rejects with {@link NO_PROXY} when nothing is polling for `serverName`, and
+     * with `timeout` when the proxy takes the work but never answers. Both are
+     * "could not be run here", which is exactly the condition under which the
+     * caller may substitute a recorded output.
+     */
+    call(serverName: string, toolName: string, args: unknown, timeoutMs: number): Promise<unknown>;
+    /** Remove queued work that timed out, so a later poll never gets stale work. */
+    private dropPending;
+    /** Fail everything in flight and release every poller. */
+    close(): void;
+    /**
+     * The oldest *live* poller. Waiters whose request has already gone are
+     * discarded rather than handed work they can never run.
+     */
+    private takeWaiter;
+    private removeWaiter;
+    /** Drop a waiter's timer and abort listener. Idempotent. */
+    private detach;
+}
+//# sourceMappingURL=executor.d.ts.map

package/dist/replay/executor.js

@@ -0,0 +1,233 @@
+/**
+ * executor — how the control server makes a proxy run a tool
+ * (docs/calculatedReplay.md §16.2).
+ *
+ * THE ASYMMETRY THIS EXISTS TO EXPLOIT. Every wrapped server is already reached
+ * through a `bir-proxy` holding an initialized, live `UpstreamClient`. Issuing a
+ * `tools/call` on that connection costs **zero tokens** — no second agent, no
+ * subprocess, no model in the loop. That is the whole reason this design has a
+ * free rung where RRepeat has an Agent SDK session.
+ *
+ * WHY LONG-POLLING, AND NOT A CALLBACK URL (D12). The control plane was
+ * one-directional: proxies dial out to report steps. Keeping it that way costs
+ * nothing here — the proxy holds one request open, the server answers it with
+ * work — and it avoids N new loopback listeners, N new tokens and N new things
+ * `bir doctor` must verify, for a latency saving of milliseconds on a path
+ * already dominated by the upstream's own round trip.
+ *
+ * A proxy that never polls (an old build, or one started without `BIR_REPLAY`)
+ * is not an error: `call` rejects with `no_proxy`, and the caller falls back to
+ * the step's recorded output.
+ */
+import { randomUUID } from "node:crypto";
+import { logDetail } from "../util/log.js";
+/** Rejection reason when no proxy is polling for a server. */
+export const NO_PROXY = "no_proxy";
+/**
+ * How long after its last poll a proxy is still considered present.
+ *
+ * A proxy is only parked *between* round trips: while it is POSTing one step's
+ * result and re-polling, nothing is waiting, and that window falls squarely
+ * between the steps of a multi-step plan. Treating it as absent would make every
+ * plan lose every step after the first.
+ */
+const PRESENT_MS = 60_000;
+export class ProxyWorkQueue {
+    /** Work dispatched while its proxy was mid-round-trip, per server. */
+    pending = new Map();
+    /** Pollers currently parked, per server. */
+    waiters = new Map();
+    /** Work handed out and awaiting a result. */
+    inFlight = new Map();
+    /** serverName → when it last polled. A proxy between polls is still present. */
+    lastSeen = new Map();
+    closed = false;
+    /** Servers a proxy is currently serving — what `bir doctor` reports. */
+    pollingServers() {
+        const now = Date.now();
+        return [...this.lastSeen.entries()]
+            .filter(([, at]) => now - at <= PRESENT_MS)
+            .map(([name]) => name);
+    }
+    /** True when a proxy for `serverName` is available to take work. */
+    hasPoller(serverName) {
+        if ((this.waiters.get(serverName)?.length ?? 0) > 0)
+            return true;
+        return this.isPresent(serverName);
+    }
+    /** Parked now, or polled recently enough to be mid-round-trip. */
+    isPresent(serverName) {
+        const at = this.lastSeen.get(serverName);
+        return at !== undefined && Date.now() - at <= PRESENT_MS;
+    }
+    /**
+     * `POST /proxy/poll`. Resolves with work, or with `undefined` at the poll
+     * deadline so the proxy re-polls. Work queued while this proxy was between
+     * polls is handed over immediately.
+     */
+    waitForWork(serverName, pollDeadlineMs, signal) {
+        if (this.closed)
+            return Promise.resolve(undefined);
+        this.lastSeen.set(serverName, Date.now());
+        const queued = this.pending.get(serverName);
+        if (queued && queued.length > 0) {
+            return Promise.resolve(queued.shift());
+        }
+        if (signal?.aborted)
+            return Promise.resolve(undefined);
+        return new Promise((resolve) => {
+            const list = this.waiters.get(serverName) ?? [];
+            const waiter = {
+                serverName,
+                resolve,
+                signal,
+                timer: setTimeout(() => {
+                    this.removeWaiter(waiter);
+                    resolve(undefined);
+                }, Math.max(0, pollDeadlineMs)),
+            };
+            if (signal) {
+                waiter.onAbort = () => {
+                    logDetail("replay.poller_gone", { server: serverName, why: "its request closed" });
+                    this.removeWaiter(waiter);
+                    resolve(undefined);
+                };
+                signal.addEventListener("abort", waiter.onAbort, { once: true });
+            }
+            waiter.timer.unref?.();
+            list.push(waiter);
+            this.waiters.set(serverName, list);
+        });
+    }
+    /** `POST /proxy/result`. Unknown ids are ignored — a late result after a timeout. */
+    complete(workId, result, error) {
+        const entry = this.inFlight.get(workId);
+        if (!entry)
+            return false;
+        this.inFlight.delete(workId);
+        clearTimeout(entry.timer);
+        if (error)
+            entry.reject(new Error(error));
+        else
+            entry.resolve(result);
+        return true;
+    }
+    /**
+     * Dispatch one call and await its result.
+     *
+     * Rejects with {@link NO_PROXY} when nothing is polling for `serverName`, and
+     * with `timeout` when the proxy takes the work but never answers. Both are
+     * "could not be run here", which is exactly the condition under which the
+     * caller may substitute a recorded output.
+     */
+    call(serverName, toolName, args, timeoutMs) {
+        if (this.closed)
+            return Promise.reject(new Error(NO_PROXY));
+        const work = { workId: "birwork_" + randomUUID(), toolName, arguments: args, timeoutMs };
+        const waiter = this.takeWaiter(serverName);
+        if (!waiter && !this.isPresent(serverName)) {
+            // No proxy has ever polled for this server, or one has been gone for a
+            // minute. Do NOT queue: the caller is inside a turn the user is waiting on,
+            // and work that sits until some proxy happens to appear would stall it past
+            // every budget. Fail fast, and let the recorded-output fallback decide.
+            return Promise.reject(new Error(NO_PROXY));
+        }
+        return new Promise((resolve, reject) => {
+            const entry = {
+                serverName,
+                resolve,
+                reject,
+                timer: setTimeout(() => {
+                    this.inFlight.delete(work.workId);
+                    this.dropPending(serverName, work.workId);
+                    reject(new Error(`timeout after ${timeoutMs}ms`));
+                }, timeoutMs),
+            };
+            entry.timer.unref?.();
+            this.inFlight.set(work.workId, entry);
+            logDetail("replay.dispatch", {
+                server: serverName,
+                tool: toolName,
+                work: work.workId,
+                queued: waiter ? undefined : true,
+            });
+            if (waiter) {
+                waiter.resolve(work);
+                return;
+            }
+            // The proxy is mid-round-trip — POSTing the previous step's result, about
+            // to poll again. Hold the work for it; the per-call timeout above is what
+            // bounds the wait if it never comes back.
+            const list = this.pending.get(serverName) ?? [];
+            list.push(work);
+            this.pending.set(serverName, list);
+        });
+    }
+    /** Remove queued work that timed out, so a later poll never gets stale work. */
+    dropPending(serverName, workId) {
+        const list = this.pending.get(serverName);
+        if (!list)
+            return;
+        const i = list.findIndex((w) => w.workId === workId);
+        if (i >= 0)
+            list.splice(i, 1);
+    }
+    /** Fail everything in flight and release every poller. */
+    close() {
+        this.closed = true;
+        for (const [, list] of this.waiters) {
+            for (const waiter of list) {
+                this.detach(waiter);
+                waiter.resolve(undefined);
+            }
+        }
+        this.waiters.clear();
+        this.pending.clear();
+        // A closed queue has no proxies, whatever they were doing a moment ago.
+        this.lastSeen.clear();
+        for (const [, entry] of this.inFlight) {
+            clearTimeout(entry.timer);
+            entry.reject(new Error("control server closed"));
+        }
+        this.inFlight.clear();
+    }
+    /**
+     * The oldest *live* poller. Waiters whose request has already gone are
+     * discarded rather than handed work they can never run.
+     */
+    takeWaiter(serverName) {
+        const list = this.waiters.get(serverName);
+        if (!list)
+            return undefined;
+        for (;;) {
+            const waiter = list.shift();
+            if (!waiter)
+                return undefined;
+            this.detach(waiter);
+            if (waiter.signal?.aborted) {
+                // Its proxy is gone. Release the promise and keep looking.
+                waiter.resolve(undefined);
+                continue;
+            }
+            return waiter;
+        }
+    }
+    removeWaiter(waiter) {
+        this.detach(waiter);
+        const list = this.waiters.get(waiter.serverName);
+        if (!list)
+            return;
+        const i = list.indexOf(waiter);
+        if (i >= 0)
+            list.splice(i, 1);
+    }
+    /** Drop a waiter's timer and abort listener. Idempotent. */
+    detach(waiter) {
+        clearTimeout(waiter.timer);
+        if (waiter.signal && waiter.onAbort) {
+            waiter.signal.removeEventListener("abort", waiter.onAbort);
+            waiter.onAbort = undefined;
+        }
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/replay/logic.d.ts

@@ -0,0 +1,31 @@
+/**
+ * logic — the four stored-JS evaluators (docs/calculatedReplay.md §9).
+ *
+ * A calculated scenario carries JavaScript function *bodies*, one per hook
+ * point, each ending in `return { … }`. They are compiled with `new Function`
+ * and run here.
+ *
+ * PORTED FROM THE SERVICE, DELIBERATELY. BaseIn's `src/scenarios/logic.ts` is
+ * the copy the service itself evaluates in a dry replay, so it is the one that
+ * defines what a scenario *means*. Porting RRepeat's near-identical copy instead
+ * would let a scenario behave one way under `bir scenario replay --dry` and
+ * another way here — an untestable difference. Argument order and the
+ * plain-object guard both match the service exactly.
+ *
+ * THERE IS NO SANDBOX, and the doc says so plainly (§13.1). A `new Function`
+ * body gets its declared arguments and the global scope: `require`/`import` are
+ * unreachable under ESM, but `fetch`, `process` and `globalThis` are not. What
+ * makes this acceptable is provenance, not containment — the payload arrives
+ * only in an authenticated response from the configured `BIR_AUTH_URL`,
+ * describing the caller's own recorded runs — and replay is opt-in for exactly
+ * this reason.
+ */
+/** Transform the derived parameters once, before any step runs. */
+export declare function evalParamsLogic(code: string, parameters: Record<string, unknown>, intent: string): Record<string, unknown>;
+/** Derive one step's tool input from params, intent and the accumulated respParams. */
+export declare function evalToolInputLogic(code: string, parameters: Record<string, unknown>, intent: string, respParams?: Record<string, unknown>): Record<string, unknown>;
+/** Extract keys from a step's real output, to merge into respParams for later steps. */
+export declare function evalToolOutputLogic(code: string, toolOutput: string, parameters: Record<string, unknown>, intent: string, respParams?: Record<string, unknown>): Record<string, unknown>;
+/** Build the final response model from everything the steps accumulated. */
+export declare function evalResponseParamsLogic(code: string, respParams: Record<string, unknown>, parameters: Record<string, unknown>, intent: string): Record<string, unknown>;
+//# sourceMappingURL=logic.d.ts.map