@basein/runner 0.1.0

package/dist/bin/bir-proxy.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/**
+ * bir-proxy — the recording MCP proxy. One process per wrapped upstream.
+ *
+ * Usage:
+ *   bir-proxy --server-name <key> -- <command> [args…]        # stdio upstream
+ *   bir-proxy --server-name <key> --url <url> [--transport http|sse]
+ *                                 [--header 'K: V']…          # remote upstream
+ *
+ * Options:
+ *   --server-name <key>   the client's config key for this server (required)
+ *   --transport <t>       `http` (default) or `sse`, with `--url`
+ *   --header 'K: V'       extra header for a remote upstream; repeatable
+ *   --standalone          skip control-server discovery; record as Tier 2
+ *   --no-correlation      never relax tool schemas; join on argument fingerprints
+ *   --lazy                create the upstream on the first host message, not at
+ *                         startup (see upstream/lazy-client.ts for the caveat)
+ *   --restart             restart a dead stdio upstream once
+ *   --discovery-ms <n>    how long to look for a control server (default 5000)
+ *
+ * Environment:
+ *   BIR_CONTROL_URL / BIR_CONTROL_TOKEN   control server, bypassing discovery
+ *   BIR_AUTH_URL                          BaseIn service, for Tier 2 recording
+ *   BIR_VERBOSE=1                         per-message detail on stderr
+ *
+ * STDOUT IS SACRED. It is the host's JSON-RPC stream; every log line, every
+ * upstream stderr line and every diagnostic goes to stderr instead. A single
+ * stray byte here corrupts the session and surfaces somewhere else entirely.
+ */
+import { StdioUpstreamClient } from "../upstream/stdio-client.js";
+import { HttpUpstreamClient } from "../upstream/http-client.js";
+import { LazyUpstreamClient } from "../upstream/lazy-client.js";
+import { Relay } from "../proxy/relay.js";
+import { RecordingInterceptor } from "../proxy/intercept.js";
+import { ProxySession } from "../proxy/session.js";
+import { logLine, errText } from "../util/log.js";
+function usage(message) {
+    if (message)
+        process.stderr.write(`[bir] ${message}\n`);
+    process.stderr.write("Usage:\n" +
+        "  bir-proxy --server-name <key> -- <command> [args…]\n" +
+        "  bir-proxy --server-name <key> --url <url> [--transport http|sse] [--header 'K: V']…\n");
+    process.exit(2);
+}
+export function parseArgs(argv) {
+    const out = {
+        serverName: "",
+        transport: "http",
+        headers: {},
+        commandArgs: [],
+        standalone: false,
+        noCorrelation: false,
+        lazy: false,
+        restart: false,
+    };
+    let i = 0;
+    for (; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--") {
+            // Everything after `--` is the upstream's own invocation, verbatim.
+            out.command = argv[i + 1];
+            out.commandArgs = argv.slice(i + 2);
+            break;
+        }
+        switch (arg) {
+            case "--server-name":
+                out.serverName = argv[++i] ?? "";
+                break;
+            case "--url":
+                out.url = argv[++i];
+                break;
+            case "--transport": {
+                const t = argv[++i];
+                if (t !== "http" && t !== "sse")
+                    usage(`unknown transport: ${t}`);
+                out.transport = t;
+                break;
+            }
+            case "--header": {
+                const raw = argv[++i] ?? "";
+                const sep = raw.indexOf(":");
+                if (sep <= 0)
+                    usage(`bad --header (expected 'Name: value'): ${raw}`);
+                out.headers[raw.slice(0, sep).trim()] = raw.slice(sep + 1).trim();
+                break;
+            }
+            case "--standalone":
+                out.standalone = true;
+                break;
+            case "--no-correlation":
+                out.noCorrelation = true;
+                break;
+            case "--lazy":
+                out.lazy = true;
+                break;
+            case "--restart":
+                out.restart = true;
+                break;
+            case "--discovery-ms":
+                out.discoveryMs = Number(argv[++i]);
+                break;
+            case "-h":
+            case "--help":
+                usage();
+                break;
+            default:
+                usage(`unknown option: ${arg}`);
+        }
+    }
+    if (!out.serverName)
+        usage("--server-name is required");
+    if (!out.url && !out.command)
+        usage("give either --url or -- <command>");
+    return out;
+}
+function buildUpstream(args) {
+    const create = () => {
+        if (args.url) {
+            return new HttpUpstreamClient({
+                url: args.url,
+                transport: args.transport,
+                headers: args.headers,
+                label: args.serverName,
+            });
+        }
+        return new StdioUpstreamClient({
+            command: args.command,
+            args: args.commandArgs,
+            label: args.serverName,
+            restartDelayMs: args.restart ? 500 : 0,
+        });
+    };
+    // `--lazy` defers to the first host message, not to `tools/list` — see the
+    // header comment in upstream/lazy-client.ts for why that is the honest limit.
+    return args.lazy ? new LazyUpstreamClient(create) : create();
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    // The upstream is built first so the session can be handed it: on a matched
+    // turn the control server runs the scenario's steps on this very connection
+    // (docs/calculatedReplay.md §16.2), which is what makes replay cost nothing.
+    const upstream = buildUpstream(args);
+    const session = new ProxySession({
+        serverName: args.serverName,
+        cwd: process.cwd(),
+        standalone: args.standalone,
+        noCorrelation: args.noCorrelation,
+        discoveryWindowMs: args.discoveryMs,
+        upstream,
+    });
+    // Negotiation runs in the background: relaying must start now, because the
+    // host may already be writing `initialize` at us.
+    session.start();
+    upstream.ready.catch((err) => {
+        // §10: the upstream failing to start is one broken server, not a broken
+        // session. The relay stays up and answers requests with a tool-level error.
+        logLine("upstream.unavailable", { server: args.serverName, error: errText(err) });
+    });
+    const relay = new Relay({
+        upstream,
+        hostIn: process.stdin,
+        hostOut: process.stdout,
+        interceptor: new RecordingInterceptor({ serverName: args.serverName, session }),
+        label: args.serverName,
+        onHostDisconnect: () => void shutdown(0),
+    });
+    relay.start();
+    logLine("proxy.started", {
+        server: args.serverName,
+        upstream: args.url ?? args.command,
+        transport: args.url ? args.transport : "stdio",
+        pid: process.pid,
+    });
+    let shuttingDown = false;
+    async function shutdown(code) {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        relay.stop();
+        upstream.close();
+        // Give the recorder its last chance; a run that loses its final steps is a
+        // worse artefact than a proxy that takes an extra moment to exit.
+        await Promise.race([
+            session.close(),
+            new Promise((resolve) => {
+                const t = setTimeout(resolve, 3_000);
+                t.unref?.();
+            }),
+        ]);
+        logLine("proxy.stopped", { server: args.serverName, tier: session.tier });
+        process.exit(code);
+    }
+    process.on("SIGINT", () => void shutdown(0));
+    process.on("SIGTERM", () => void shutdown(0));
+    process.on("uncaughtException", (err) => {
+        // Never take the host's session down. Log, and keep relaying if we can.
+        logLine("proxy.uncaught", { server: args.serverName, error: errText(err) });
+    });
+    process.on("unhandledRejection", (err) => {
+        logLine("proxy.unhandled_rejection", { server: args.serverName, error: errText(err) });
+    });
+}
+void main().catch((err) => {
+    logLine("proxy.fatal", { error: errText(err) });
+    process.exit(1);
+});
+//# sourceMappingURL=bir-proxy.js.map

package/dist/bin/bir-scenario.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * bir-scenario — a first-party MCP server with exactly one tool
+ * (docs/calculatedReplay.md §6.3).
+ *
+ * WHY THIS EXISTS. On a fully-wrapped match the whole scenario runs server-side,
+ * through proxies that are already connected, and the model's only job is to read
+ * the results. Delivering those results as `additionalContext` was the obvious
+ * shortcut and is wrong three times over: it must finish inside
+ * `UserPromptSubmit`'s timeout; it is *asserted* rather than corroborated by the
+ * transcript; and RRepeat learned expensively that a model reads an injected
+ * `deny` reason as adversarial interception. A genuine `tool_result` has none of
+ * those problems — which is why RRepeat eventually grew a whole MCP bridge to
+ * fake one, and why we simply serve one.
+ *
+ * It holds no state, no credentials, and no upstream connections. It finds the
+ * control server exactly as a proxy does — `~/.baseinstrunner/control/<key>.json`,
+ * mode 0600, bearer token — and forwards one call.
+ *
+ * STDOUT IS SACRED, as in every MCP server here: it is the host's JSON-RPC
+ * stream, and every log line goes to stderr instead.
+ */
+export {};
+//# sourceMappingURL=bir-scenario.d.ts.map

package/dist/bin/bir-scenario.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/**
+ * bir-scenario — a first-party MCP server with exactly one tool
+ * (docs/calculatedReplay.md §6.3).
+ *
+ * WHY THIS EXISTS. On a fully-wrapped match the whole scenario runs server-side,
+ * through proxies that are already connected, and the model's only job is to read
+ * the results. Delivering those results as `additionalContext` was the obvious
+ * shortcut and is wrong three times over: it must finish inside
+ * `UserPromptSubmit`'s timeout; it is *asserted* rather than corroborated by the
+ * transcript; and RRepeat learned expensively that a model reads an injected
+ * `deny` reason as adversarial interception. A genuine `tool_result` has none of
+ * those problems — which is why RRepeat eventually grew a whole MCP bridge to
+ * fake one, and why we simply serve one.
+ *
+ * It holds no state, no credentials, and no upstream connections. It finds the
+ * control server exactly as a proxy does — `~/.baseinstrunner/control/<key>.json`,
+ * mode 0600, bearer token — and forwards one call.
+ *
+ * STDOUT IS SACRED, as in every MCP server here: it is the host's JSON-RPC
+ * stream, and every log line goes to stderr instead.
+ */
+import { readFrames, writeFrame } from "../jsonrpc/framing.js";
+import { JsonRpcErrorCode, errorResponse, isRequest, paramsObject, } from "../jsonrpc/types.js";
+import { resolveControl } from "../control/discovery.js";
+import { logLine, logDetail, errText } from "../util/log.js";
+/** Must match `DIRECT_TOOL_NAME`'s suffix in the replay controller. */
+const TOOL_NAME = "run_scenario";
+/** How long to look for a control server before answering that there is none. */
+const DISCOVERY_MS = 5_000;
+/** The plan can be long; the whole-plan budget lives on the control server. */
+const RUN_TIMEOUT_MS = 180_000;
+const TOOL = {
+    name: TOOL_NAME,
+    description: "Run the pre-calculated tool sequence BaseInstRunner has armed for the current request, " +
+        "and return its results. Call once, with no arguments, when instructed to.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+};
+/** Ask the control server to run the armed plan. Never throws. */
+async function runArmedPlan(cwd) {
+    const found = await resolveControl(cwd, DISCOVERY_MS);
+    if (!found?.url)
+        return { ok: false, why: "no control server for this directory" };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), RUN_TIMEOUT_MS);
+    timer.unref?.();
+    try {
+        const res = await fetch(`${found.url.replace(/\/+$/, "")}/scenario/run`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${found.token}`,
+            },
+            body: "{}",
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return { ok: false, why: `control server answered HTTP ${res.status}` };
+        return (await res.json());
+    }
+    catch (err) {
+        return { ok: false, why: errText(err) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * A `CallToolResult`. A turn with no armed plan is a **tool failure**, not a
+ * protocol error: the model called a tool that had nothing to do — usually
+ * because it remembered the tool from an earlier turn — and reacting to that is
+ * something models do well and routinely.
+ */
+function toolResult(result) {
+    if (!result.ok || !result.text) {
+        const why = result.why === "no_plan"
+            ? "no scenario is armed for this turn — answer the user's request normally"
+            : (result.why ?? "the scenario could not be run");
+        return { content: [{ type: "text", text: why }], isError: true };
+    }
+    const notes = [];
+    if (result.partial)
+        notes.push("(partial: the plan's time budget was reached)");
+    const structured = result.responseModel && Object.keys(result.responseModel).length > 0
+        ? `\n\nResponse model (derived by the scenario's own logic):\n${JSON.stringify(result.responseModel)}`
+        : "";
+    // NO `structuredContent`, AND THAT IS THE WHOLE POINT.
+    //
+    // A client that receives both MAY render `structuredContent` and drop
+    // `content` — Claude Code does. The replay then reaches the model as the bare
+    // response model: a few hundred bytes of derived keys, with no bundle header,
+    // no per-step calls and no tool results. Observed in a real session as a
+    // 744-character `{"services":[…],"worstService":…}` where a 30 KB, 8-step
+    // bundle should have been.
+    //
+    // The model behaved correctly given what it saw — it could not answer from
+    // that, so it re-ran all eight tools itself. The replay had executed
+    // perfectly, cost nothing, and bought nothing, because its results never
+    // arrived. The bundle is the payload; the response model rides inside it as
+    // text rather than competing with it for the client's attention.
+    return {
+        content: [
+            { type: "text", text: `${result.text}${structured}${notes.length ? `\n\n${notes.join(" ")}` : ""}` },
+        ],
+        isError: false,
+    };
+}
+function main() {
+    const cwd = process.cwd();
+    let closing = false;
+    const reply = (msg) => writeFrame(process.stdout, msg);
+    readFrames(process.stdin, {
+        onMessage: (msg) => {
+            if (!isRequest(msg))
+                return; // notifications need no answer
+            const { id, method } = msg;
+            if (method === "initialize") {
+                const params = paramsObject(msg.params);
+                reply({
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        // Echo the host's protocol version when it names one; a server that
+                        // insists on its own is a server the host may refuse to talk to.
+                        protocolVersion: String(params.protocolVersion ?? "2025-06-18"),
+                        capabilities: { tools: {} },
+                        serverInfo: { name: "bir-scenario", version: "1" },
+                    },
+                });
+                return;
+            }
+            if (method === "tools/list") {
+                reply({ jsonrpc: "2.0", id, result: { tools: [TOOL] } });
+                return;
+            }
+            if (method === "ping") {
+                reply({ jsonrpc: "2.0", id, result: {} });
+                return;
+            }
+            if (method === "tools/call") {
+                const params = paramsObject(msg.params);
+                if (String(params.name ?? "") !== TOOL_NAME) {
+                    reply(errorResponse(id, JsonRpcErrorCode.MethodNotFound, `unknown tool: ${params.name}`));
+                    return;
+                }
+                logDetail("scenario.call", { cwd });
+                void runArmedPlan(cwd).then((result) => {
+                    logLine("scenario.answered", {
+                        ok: result.ok ?? false,
+                        steps: result.steps,
+                        why: result.ok ? undefined : result.why,
+                    });
+                    reply({ jsonrpc: "2.0", id, result: toolResult(result) });
+                });
+                return;
+            }
+            // Anything else: this server advertises only tools, so an unknown method
+            // is a protocol error rather than something to guess at.
+            reply(errorResponse(id, JsonRpcErrorCode.MethodNotFound, `unsupported method: ${method}`));
+        },
+        onParseError: (detail) => logLine("scenario.frame_error", { reason: detail.reason }),
+        onEnd: () => {
+            // The host closed our stdin: the session is over.
+            if (closing)
+                return;
+            closing = true;
+            process.exit(0);
+        },
+    });
+    logLine("scenario.started", { cwd, pid: process.pid });
+    process.on("SIGINT", () => process.exit(0));
+    process.on("SIGTERM", () => process.exit(0));
+    process.on("uncaughtException", (err) => logLine("scenario.uncaught", { error: errText(err) }));
+    process.on("unhandledRejection", (err) => logLine("scenario.unhandled_rejection", { error: errText(err) }));
+}
+main();
+//# sourceMappingURL=bir-scenario.js.map

package/dist/bin/bir.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * bir — the command line (Phase 7).
+ *
+ *   bir install [--config <path>] [--server <name>]… [--local] [--no-hooks]
+ *   bir uninstall [--config <path>]
+ *   bir status
+ *   bir doctor
+ *   bir wrap --server-name <key> -- <command> [args…]
+ *   bir login | logout
+ *   bir --version
+ *
+ * `bir install` is reversible by construction: every file it edits is stashed
+ * verbatim first, so `bir uninstall` restores it byte-for-byte unless somebody
+ * else edited it in the meantime (in which case it repairs the entries and says
+ * so). `bir doctor` proves the install *works* by asking the control server which
+ * proxies actually registered — never by reading the config file back, and never
+ * from `serverInfo`, which must stay the upstream's (Phase 3).
+ */
+export {};
+//# sourceMappingURL=bir.d.ts.map