@basein/runner 0.2.12 → 0.3.1

package/dist/bin/bir-proxy.js

@@ -15,25 +15,47 @@
  *   --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)
+ *   --restart             restart a dead stdio upstream once (in-flight calls
+ *                         are answered; the host's handshake is replayed to it)
+ *   --discovery-ms <n>    how long to look for a control server (default 10000)
  *
  * Environment:
  *   BIR_CONTROL_URL / BIR_CONTROL_TOKEN   control server, bypassing discovery
  *   BIR_AUTH_URL                          BaseIn service, for Tier 2 recording
+ *   BIR_UPSTREAM_HEADERS                  a remote upstream's headers, as a JSON
+ *                                         object of name → value; `--header`
+ *                                         wins on a clash. Read once, then
+ *                                         removed from the environment: no
+ *                                         process started from here sees it
+ *   BIR_OFF=1                             the kill switch (also `bir off`): run
+ *                                         the server as if it were not wrapped
+ *   BIR_PROXY_STAY_UP=1                   keep answering after the upstream
+ *                                         dies, instead of exiting with it
  *   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.
+ *
+ * STDERR IS NOT FREE EITHER. Claude Code files every stderr line of an MCP
+ * server as a "Server stderr" error in its MCP logs, so routine lines (started,
+ * spawned, bound, stopped) are `BIR_VERBOSE`-only; what is left on stderr is a
+ * decision or a failure somebody may need to read.
  */
-import { StdioUpstreamClient } from "../upstream/stdio-client.js";
+import { spawn } from "node:child_process";
+import { constants as osConstants } from "node:os";
+import { StdioUpstreamClient, resolveCommand } 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 { RecordingInterceptor, StripCallIdInterceptor } from "../proxy/intercept.js";
 import { ProxySession } from "../proxy/session.js";
-import { logLine, errText } from "../util/log.js";
+import { mergeHeaders, parseUpstreamHeaders, sendableHeaders, UPSTREAM_HEADERS_ENV } from "../upstream/headers.js";
+import { exemptLoopbackFromProxy } from "../config/generate.js";
+import { offSource } from "../util/off-switch.js";
+import { logLine, logDetail, logOnce, errText } from "../util/log.js";
+/** Hard ceiling on shutdown: the recorder's last chance, and the upstream's. */
+const SHUTDOWN_BUDGET_MS = 3_000;
 function usage(message) {
     if (message)
         process.stderr.write(`[bir] ${message}\n`);
@@ -79,8 +101,10 @@ export function parseArgs(argv) {
             case "--header": {
                 const raw = argv[++i] ?? "";
                 const sep = raw.indexOf(":");
+                // Never echo `raw`: a header is usually a credential, and a malformed
+                // one (`Authorization Bearer …`, no colon) is still the whole token.
                 if (sep <= 0)
-                    usage(`bad --header (expected 'Name: value'): ${raw}`);
+                    usage("bad --header (expected 'Name: value')");
                 out.headers[raw.slice(0, sep).trim()] = raw.slice(sep + 1).trim();
                 break;
             }
@@ -113,7 +137,49 @@ export function parseArgs(argv) {
         usage("give either --url or -- <command>");
     return out;
 }
-function buildUpstream(args) {
+/**
+ * `BIR_UPSTREAM_HEADERS` merged under the `--header` arguments (which win on a
+ * clash, so an older entry keeps meaning what it meant), and the variable
+ * removed from this process's environment either way: a stdio upstream — the
+ * user's own server — and anything else started from here must never inherit
+ * a remote server's credentials. A variable that is not usable is said once,
+ * by its shape; neither it nor any value is ever logged.
+ */
+function takeUpstreamHeaders(args) {
+    const raw = process.env[UPSTREAM_HEADERS_ENV];
+    delete process.env[UPSTREAM_HEADERS_ENV];
+    if (!args.url)
+        return args.headers;
+    const fromEnv = parseUpstreamHeaders(raw);
+    if (fromEnv.problem) {
+        logOnce("upstream.headers_invalid:env", "upstream.headers_invalid", {
+            server: args.serverName,
+            source: UPSTREAM_HEADERS_ENV,
+            why: fromEnv.problem,
+        });
+    }
+    const fromArgs = sendableHeaders(args.headers);
+    if (fromArgs.problem) {
+        logOnce("upstream.headers_invalid:args", "upstream.headers_invalid", {
+            server: args.serverName,
+            source: "--header",
+            why: fromArgs.problem,
+        });
+    }
+    return mergeHeaders(fromEnv.headers, fromArgs.headers);
+}
+/**
+ * The proxy-variable changes {@link exemptLoopbackFromProxy} made to this
+ * process, undone for the user's own server: its networking is not ours to
+ * change. Empty when nothing was changed.
+ */
+function environmentAsStarted(before, changed) {
+    if (!changed)
+        return {};
+    // On Windows the two spellings are one variable.
+    return process.platform === "win32" ? { NO_PROXY: before.NO_PROXY } : { NO_PROXY: before.NO_PROXY, no_proxy: before.no_proxy };
+}
+function buildUpstream(args, stdioEnv) {
     const create = () => {
         if (args.url) {
             return new HttpUpstreamClient({
@@ -126,6 +192,7 @@ function buildUpstream(args) {
         return new StdioUpstreamClient({
             command: args.command,
             args: args.commandArgs,
+            env: stdioEnv,
             label: args.serverName,
             restartDelayMs: args.restart ? 500 : 0,
         });
@@ -134,60 +201,187 @@ function buildUpstream(args) {
     // header comment in upstream/lazy-client.ts for why that is the honest limit.
     return args.lazy ? new LazyUpstreamClient(create) : create();
 }
+/**
+ * The kill switch, for a stdio upstream: run the real server as the host would
+ * have run it — same stdin, same stdout, same stderr — and leave with its exit
+ * status. No relay, no parsing, no recording, no control server; the only thing
+ * left of the runner is one idle parent process.
+ */
+function runAsPipe(args) {
+    const resolved = resolveCommand(args.command, args.commandArgs, process.env);
+    let child;
+    try {
+        child = spawn(resolved.command, resolved.args, {
+            stdio: "inherit",
+            shell: false,
+            windowsHide: true,
+            windowsVerbatimArguments: resolved.windowsVerbatimArguments,
+        });
+    }
+    catch (err) {
+        logLine("upstream.exited", { server: args.serverName, error: errText(err) });
+        process.exit(1);
+    }
+    child.once("error", (err) => {
+        logLine("upstream.exited", { server: args.serverName, error: errText(err) });
+        process.exit(1);
+    });
+    child.once("exit", (code, signal) => {
+        if (signal) {
+            const n = osConstants.signals[signal] ?? 0;
+            process.exit(128 + n);
+        }
+        process.exit(code ?? 1);
+    });
+    // A signal meant for the server reaches it, and we leave when it does.
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+        try {
+            process.on(sig, () => {
+                try {
+                    child.kill(sig);
+                }
+                catch {
+                    /* already gone */
+                }
+            });
+        }
+        catch {
+            /* a signal this platform does not have */
+        }
+    }
+}
+/** Resolve once everything already written to stdout has been handed off, or after `ms`. */
+function stdoutDrained(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+        try {
+            process.stdout.write("", () => {
+                clearTimeout(timer);
+                resolve();
+            });
+        }
+        catch {
+            clearTimeout(timer);
+            resolve();
+        }
+    });
+}
 async function main() {
     const args = parseArgs(process.argv.slice(2));
+    const cwd = process.cwd();
+    // First, before anything can be spawned: the variable leaves the
+    // environment even on the kill-switch path below.
+    args.headers = takeUpstreamHeaders(args);
+    // THE KILL SWITCH (`bir off`, BIR_OFF=1). Decided once, at startup: a
+    // server already running keeps the path it started with, and the next
+    // session picks up the flip.
+    const off = offSource(cwd);
+    if (off && !args.url) {
+        logDetail("proxy.off", { server: args.serverName, source: off, why: "running the server unwrapped" });
+        runAsPipe(args);
+        return;
+    }
+    // Started with --use-env-proxy (entries carry it behind a proxy) in an
+    // environment whose NO_PROXY does not name 127.0.0.1: without this, every
+    // call to the control server — register, step reports, the replay work
+    // loop — went to the proxy, failed, and the proxy fell to Tier 2 or to
+    // nothing. Before any loopback fetch, as `bir` does. The pure pipe above
+    // runs no fetch and hands the user's server the environment untouched.
+    const noProxyBefore = { NO_PROXY: process.env.NO_PROXY, no_proxy: process.env.no_proxy };
+    const exempted = exemptLoopbackFromProxy();
     // 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,
-    });
+    const asStarted = environmentAsStarted(noProxyBefore, exempted);
+    const upstream = buildUpstream(args, asStarted);
+    // Off, with a remote upstream (there is no process to hand stdio to): relay
+    // only — no recording, no control server, no schema change. The call id is
+    // still stripped (StripCallIdInterceptor): `bir on` mid-session can make a
+    // control server inject one into a call routed here.
+    const session = off
+        ? undefined
+        : new ProxySession({
+            serverName: args.serverName,
+            cwd,
+            standalone: args.standalone,
+            noCorrelation: args.noCorrelation,
+            discoveryWindowMs: args.discoveryMs,
+            upstream,
+            // A recorder that dies under this proxy is started again with the
+            // environment the host gave us (proxy/revive.ts) — without the
+            // loopback exemption made above, and without BIR_UPSTREAM_HEADERS,
+            // which left this process's environment at the top of main().
+            revive: { env: { ...process.env, ...asStarted } },
+        });
+    if (off)
+        logDetail("proxy.off", { server: args.serverName, source: off, why: "relaying without recording" });
     // Negotiation runs in the background: relaying must start now, because the
     // host may already be writing `initialize` at us.
-    session.start();
+    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) });
     });
+    // Declared before anything that can call `shutdown`.
+    let shuttingDown = false;
     const relay = new Relay({
         upstream,
         hostIn: process.stdin,
         hostOut: process.stdout,
-        interceptor: new RecordingInterceptor({ serverName: args.serverName, session }),
+        interceptor: session
+            ? new RecordingInterceptor({ serverName: args.serverName, session })
+            : new StripCallIdInterceptor(),
         label: args.serverName,
         onHostDisconnect: () => void shutdown(0),
     });
     relay.start();
-    logLine("proxy.started", {
+    // An upstream that is gone for good takes the proxy with it — after the
+    // relay (registered first) has answered whatever was in flight. The host
+    // then sees what it would have seen unwrapped: the server disconnected, shown
+    // as failed in /mcp with a reconnect offered, its tools gone from the model's
+    // list. Staying up instead left the tools listed and every call answering an
+    // error, turn after turn, with nothing to tell the user to reconnect.
+    upstream.onClose((info) => {
+        if (shuttingDown || process.env.BIR_PROXY_STAY_UP === "1")
+            return;
+        logLine("proxy.upstream_gone", {
+            server: args.serverName,
+            code: info.code,
+            signal: info.signal,
+            why: "exiting with it, as the server would have unwrapped",
+        });
+        // Its own exit status where it had one, as the host would have seen it.
+        void shutdown(typeof info.code === "number" ? info.code : 1);
+    });
+    logDetail("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.
+        // The upstream gets its polite close (stdin EOF, a moment to exit, then a
+        // tree kill), and the recorder its last chance — side by side, and never
+        // longer than the budget: a run that loses its final steps is a worse
+        // artefact than a proxy that takes an extra moment to exit, but a proxy
+        // that lingers is worse than both.
+        const closing = Promise.allSettled([
+            session?.close(),
+            upstream.shutdown ? upstream.shutdown() : Promise.resolve(upstream.close()),
+        ]);
         await Promise.race([
-            session.close(),
+            closing,
             new Promise((resolve) => {
-                const t = setTimeout(resolve, 3_000);
+                const t = setTimeout(resolve, SHUTDOWN_BUDGET_MS);
                 t.unref?.();
             }),
         ]);
-        logLine("proxy.stopped", { server: args.serverName, tier: session.tier });
+        logDetail("proxy.stopped", { server: args.serverName, tier: session?.tier ?? "off" });
+        await stdoutDrained(500);
         process.exit(code);
     }
     process.on("SIGINT", () => void shutdown(0));

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

@@ -18,31 +18,71 @@
  * control server exactly as a proxy does — `~/.baseinstrunner/control/<key>.json`,
  * mode 0600, bearer token — and forwards one call.
  *
+ * WHOSE CALL. A stdio MCP server is never told its session, and the control
+ * server runs a plan only for the session whose `PreToolUse` for
+ * `mcp__bir__run_scenario` it saw. Claude Code names the tool use in every
+ * MCP call's `params._meta["claudecode/toolUseId"]` — the same id that hook
+ * carried as `tool_use_id` — so the request forwards it as `toolUseId` and the
+ * control server matches it exactly instead of inferring the session. A host
+ * that names nothing sends an empty body, as before.
+ *
+ * IT RUNS IN EVERY SESSION, SO IT MUST NEVER BE WHY ONE GOES WRONG. Startup and
+ * `tools/list` are answered from local files alone (the hello to the recorder
+ * that follows them is sent after the answer, and never awaited). `run_scenario` never answers
+ * with an error or with the runner's internals ("fetch failed", "not_ready",
+ * "HTTP 404"): a turn with nothing to run is told so in one neutral sentence,
+ * and a replay that cannot be delivered becomes "do the task normally" — the
+ * real reason goes to the audit log, where `bir doctor` and a person look. A
+ * model called it on its own in the first session of every freshly installed
+ * project; a red error under a tool the user never asked about, five seconds
+ * late, was the result. `BIR_SCENARIO_DEBUG=1` brings the raw reasons back.
+ *
  * THE SCENARIO TOOLS RUN `bir` ITSELF. `scenario_show`, `scenario_check` and
  * the rest are the `bir scenario …` commands, spawned from this same package
  * with `--json` (D1: one path, whether a person types it or the model calls
  * it). That keeps this server credential-free — `bir` signs in the way it
- * always does — and means the model sees exactly the answer a person would.
- * Logic bodies travel through temporary files, never argv, and a non-zero exit
- * is an `isError` result that carries the output, refusal and report included.
- *
- * A CALL IN FLIGHT IS OWNED UNTIL IT ENDS. Each scenario call's `bir` child and
- * its temporary directory are tracked. When the host goes away (stdin closes,
- * SIGINT, SIGTERM) the children are stopped and the directories removed before
- * the process exits — `process.exit` never resumes a pending `finally`, so
- * cleanup left to one was cleanup that did not happen, and an orphaned `bir`
- * went on to save an edit for a session that had ended (C13). A
- * `notifications/cancelled` (the person pressed Esc) stops that call's child
- * the same way, and the call gets no answer, as MCP asks. A request the
- * service already received may still complete there; nothing here can call
- * it back, and `bir scenario edits` shows it.
- *
- * The tools that CHANGE a scenario are offered only where a person ran
- * `bir scenario editing on` (D2): this server runs in every session of every
- * installed project, a fleet included, and a plan must not change because some
- * agent there decided it should. The switch is read when the host lists the
- * tools, and again on every call, so a call to a tool that was never offered —
- * or was offered before the switch went off — is refused rather than run.
+ * always does — and means the model sees exactly the answer a person would,
+ * compact (`BIR_MCP=1`) and capped in size. Logic bodies travel through
+ * temporary files, never argv, and a non-zero exit is an `isError` result that
+ * carries the output, refusal and report included.
+ *
+ * A CALL IN FLIGHT IS OWNED UNTIL IT ENDS. Each call's `bir` child, temporary
+ * directory or control-server request is tracked. When the host goes away
+ * (stdin closes, SIGINT, SIGTERM) the children are stopped and the directories
+ * removed before the process exits — `process.exit` never resumes a pending
+ * `finally`, so cleanup left to one was cleanup that did not happen, and an
+ * orphaned `bir` went on to save an edit for a session that had ended (C13). A
+ * `notifications/cancelled` (the person pressed Esc) stops that call the same
+ * way — a `run_scenario` request is aborted, and the control server stops
+ * starting steps when its request closes — and the call gets no answer, as MCP
+ * asks. A request the service already received may still complete there;
+ * nothing here can call it back, and `bir scenario edits` shows it.
+ *
+ * WHICH TOOLS ARE OFFERED. `run_scenario`, always — unless the runner is
+ * switched off (`bir off`), when nothing is: an inert runner adds nothing to
+ * the model's context, and a call from a list taken before the switch starts
+ * nothing and asks nobody. The reading tools come with `bir scenario editing on`
+ * (or `BIR_SCENARIO_TOOLS=read` in this server's environment): their
+ * definitions ride along with every request of every session, and only
+ * somebody working on a scenario ever calls them. The tools that CHANGE a
+ * scenario are offered only where a person ran `bir scenario editing on` (D2):
+ * this server runs in every session of every installed project, a fleet
+ * included, and a plan must not change because some agent there decided it
+ * should. The switch is read when the host lists the tools, and again on every
+ * call, so a call to a tool that was never offered — or was offered before the
+ * switch went off — is refused rather than run. Turning the runner off or on
+ * mid-session tells the host its list changed (`notifications/tools/list_changed`).
+ *
+ * IT SAYS IT IS HERE, AND IT BRINGS THE RECORDER BACK (scenario-liveness.ts).
+ * A configured `bir` server is not a connected one, so the recorder announces
+ * a direct plan — "call run_scenario first" — only on this server's word: a
+ * `POST /scenario/hello` (pid, version, how many tools, off or not) on
+ * `initialize`, on `tools/list`, when the off switch flips, to each new
+ * recorder, and every 5 min. And this is the one long-lived process in every
+ * session of an installed project, so when the recorder's pid is dead and its
+ * address refuses, it starts `bir-hooks revive` — detached, rate-limited —
+ * rather than leave every later hook to fail until the next session start.
+ * Neither is ever awaited on the MCP path.
  *
  * 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.