@basein/runner 0.2.8 → 0.2.11

package/dist/bin/bir-hooks.js

@@ -2,7 +2,11 @@
 /**
  * bir-hooks — the Claude Code hook receiver and the control server (Tier 1).
  *
- * Run it in the project you will launch `claude` from, in its own terminal:
+ * Normally nobody runs it: `bir install` makes it the SessionStart hook
+ * (`bir-hooks ensure`), which starts it in the background for the project when no
+ * recorder is running there, and `bir up` / `bir down` start and stop that
+ * background process by hand. Its audit lines then go to
+ * ~/.baseinstrunner/logs/<project-key>.log. It can still be run in a terminal:
  *
  *     bir-hooks                       # start; Ctrl-C to stop
  *     bir-hooks 2>&1 | tee -a ~/.baseinstrunner/audit.log
@@ -13,7 +17,8 @@
  *   3. owns run identity, the monotonic `stepIndex`, and the recorder chain (D5).
  *
  * Environment:
- *   BIR_AUTH_URL              BaseIn auth-service (required to record anything)
+ *   BIR_AUTH_URL              BaseIn auth-service. Unset, the address `bir setup`
+ *                             stored in ~/.baseinstrunner/config.json is used
  *   BIR_CONTROL_PORT          preferred port (default 53411; falls back if busy)
  *   BIR_CORRELATION_DECISION  `allow` (default) or `ask` — see below
  *   BIR_NO_CORRELATION=1      never inject a call id; join on fingerprints
@@ -61,13 +66,19 @@
  * fingerprint matching, which is lossy under identical concurrent calls.
  */
 import { hostname } from "node:os";
+import { Console } from "node:console";
+import { createWriteStream } from "node:fs";
 import { ControlServer, DEFAULT_CONTROL_PORT } from "../control/server.js";
-import { removeDiscovery, writeDiscovery } from "../control/discovery.js";
-import { authenticate, clearCredentials, normalizeAuthUrl } from "../auth/client.js";
+import { HEARTBEAT_MS, removeDiscovery, writeDiscovery, } from "../control/discovery.js";
+import { DAEMON_ENV, DAEMON_LOG_ENV } from "../control/daemon.js";
+import { runEnsureHook } from "../control/ensure-hook.js";
+import { ENSURE_ARG } from "../config/adapters/claude-code.js";
+import { authenticate, clearCredentials, normalizeAuthUrl, resolveAuthUrl, } from "../auth/client.js";
+import { packageVersion } from "../util/version.js";
 import { NullRecorder } from "../record/recorder.js";
 import { RemoteRecorder } from "../record/remote-recorder.js";
 import { parseAllowList } from "../replay/coverage.js";
-import { readSidecar } from "../config/generate.js";
+import { projectRecord, projectToken, readSidecar } from "../config/generate.js";
 import { resolveServers } from "../config/resolve.js";
 import { isWrapped } from "../config/generate.js";
 import { logLine, errText } from "../util/log.js";
@@ -89,9 +100,14 @@ function wrappedServersFor(cwd) {
     }
 }
 async function buildRecorder() {
-    const configured = (process.env.BIR_AUTH_URL ?? "").replace(/\/+$/, "");
+    // BIR_AUTH_URL, or the address 'bir setup' stored. Read the same way by the
+    // proxies and the CLI, so a recorder started by a hook — with whatever
+    // environment the host had — still knows where the steps go.
+    const configured = resolveAuthUrl();
     if (!configured) {
-        logLine("recorder.disabled", { why: "BIR_AUTH_URL is not set — running without recording" });
+        logLine("recorder.disabled", {
+            why: "no service address — run 'bir setup', or set BIR_AUTH_URL; running without recording",
+        });
         return { recorder: new NullRecorder() };
     }
     // A plain-http URL fronted by a TLS proxy answers `308 → https`, and following
@@ -133,22 +149,26 @@ function parseIntentSources(value) {
         .filter((s) => allowed.includes(s));
     return new Set(wanted);
 }
-/**
- * Assemble the replay configuration (docs/calculatedReplay.md §5.3 of the guide).
- *
- * The steer threshold defaults **above** the service's own detection threshold
- * (0.9). Detection decides "do not record this again", which is cheap — the worst
- * case is a lost recording. Steering decides "do not think about this again",
- * which is a much stronger claim, and a 0.90-similar prompt usually covers only
- * part of the live task.
- */
-function buildReplayOptions(auth) {
-    const enabled = process.env.BIR_REPLAY !== "0";
-    const allowServers = parseAllowList(process.env.BIR_REPLAY_ALLOW_SERVERS);
-    const minSimilarity = Number(process.env.BIR_MIN_STEER_SIMILARITY);
+function buildReplayOptions(auth, policy) {
+    // The environment still wins — an operator at a terminal is the most
+    // deliberate signal there is — but a recorder started by the SessionStart
+    // hook has Claude Code's environment, not that terminal's, and it reads the
+    // switches the project stored instead of forgetting them (generate.ts).
+    const envReplay = process.env.BIR_REPLAY;
+    const envAllow = process.env.BIR_REPLAY_ALLOW_SERVERS;
+    const envMin = Number(process.env.BIR_MIN_STEER_SIMILARITY);
+    const fromEnv = envReplay !== undefined || envAllow !== undefined || Number.isFinite(envMin);
+    const source = fromEnv ? "env" : policy ? "sidecar" : "default";
+    const enabled = envReplay !== undefined ? envReplay !== "0" : policy?.enabled !== false;
+    const allowServers = envAllow !== undefined
+        ? parseAllowList(envAllow)
+        : policy?.allowServers
+            ? parseAllowList(policy.allowServers.join(","))
+            : undefined;
+    const minSimilarity = Number.isFinite(envMin) ? envMin : (policy?.minSimilarity ?? 0.92);
     const opts = {
         enabled,
-        minSimilarity: Number.isFinite(minSimilarity) ? minSimilarity : 0.92,
+        minSimilarity,
         allowServers,
         budgets: {
             matchMs: positiveInt(process.env.BIR_MATCH_BUDGET_MS, 2_500),
@@ -194,10 +214,11 @@ function buildReplayOptions(auth) {
                     ? "the service"
                     : "recorded sample values — sign in, or a scenario with a target will not run",
             intentMatch: opts.intentMatch?.enabled ? "on" : "off",
+            source,
             why: "matched prompts will run their calculated scenario — steered steps are auto-approved",
         });
     }
-    return opts;
+    return { opts, source };
 }
 async function main() {
     const argv = process.argv.slice(2);
@@ -206,61 +227,126 @@ async function main() {
         process.stderr.write("[bir] logged out — cached credentials cleared.\n");
         return;
     }
+    if (argv[0] === ENSURE_ARG) {
+        // The SessionStart hook: start the recorder for this directory if there is
+        // none, then relay the payload. Always exit 0 (control/ensure-hook.ts).
+        process.exitCode = await runEnsureHook(process.cwd());
+        return;
+    }
     const cwd = process.cwd();
+    const daemon = process.env[DAEMON_ENV] === "1";
+    const logFile = daemon ? process.env[DAEMON_LOG_ENV] : undefined;
+    if (logFile) {
+        // A background recorder owns its log. Nothing was inherited from whoever
+        // started it (control/daemon.ts says why), so the audit lines — every
+        // `logLine` goes through `console.error` — are pointed at the file here.
+        const stream = createWriteStream(logFile, { flags: "a" });
+        globalThis.console = new Console({ stdout: stream, stderr: stream });
+    }
     const sidecar = readSidecar();
+    // The port this project's hooks were written with. An explicit BIR_CONTROL_PORT
+    // still wins; the per-project record is what lets two projects record at once.
+    const pinned = process.env.BIR_CONTROL_PORT !== undefined || projectRecord(sidecar, cwd) !== undefined;
+    const preferredPort = parsePort(process.env.BIR_CONTROL_PORT ??
+        String(projectRecord(sidecar, cwd)?.port ?? sidecar.controlPort ?? ""));
     // Open before anything logs: the journal is what `bir investigate` reads
     // later, and the startup lines are part of the story.
     const journalFile = openJournal(cwd);
     const auth = await buildRecorder();
+    const replay = buildReplayOptions(auth, projectRecord(sidecar, cwd)?.replay);
     const server = new ControlServer({
         recorder: auth.recorder,
         cwd,
-        port: parsePort(process.env.BIR_CONTROL_PORT ?? String(sidecar.controlPort ?? "")),
-        token: sidecar.token,
+        port: preferredPort,
+        // This project's token (generate.ts); the machine-wide one for a record
+        // written before tokens were per project.
+        token: projectToken(sidecar, cwd),
         wrappedServers: wrappedServersFor(cwd),
         host: { app: "claude-code" },
         correlationDecision: process.env.BIR_CORRELATION_DECISION === "ask" ? "ask" : "allow",
         noCorrelation: process.env.BIR_NO_CORRELATION === "1",
         deriveRecentResults: nonNegativeInt(process.env.BIR_DERIVE_RECENT_RESULTS, 5),
         intentSources: parseIntentSources(process.env.BIR_INTENT_SOURCES),
-        replay: buildReplayOptions(auth),
+        replay: replay.opts,
+        replaySource: replay.source,
+        account: auth.session?.user.email,
+        // In the background with a port the hooks name, a fallback port is a
+        // recorder every hook but SessionStart would miss. Exit with a reason instead.
+        portFallback: !(daemon && pinned),
+        // 'bir down', and the SessionStart hook replacing an out-of-date recorder,
+        // ask over HTTP rather than sending a signal: on Windows a signal is a kill.
+        onStopRequested: () => void shutdown(),
     });
-    const address = await server.listen();
-    const discoveryFile = writeDiscovery({
+    let address;
+    try {
+        address = await server.listen();
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "EADDRINUSE" || code === "EACCES") {
+            logLine("control.port_busy", {
+                port: preferredPort,
+                code,
+                fix: `port ${preferredPort} is held by another program or excluded by the system — run \`bir setup --port <another>\` in this directory`,
+            });
+            process.exit(1);
+        }
+        throw err;
+    }
+    const info = {
         url: address.url,
         token: address.token,
         sessionId: address.sessionId,
         pid: process.pid,
         startedAt: Date.now(),
         cwd,
-    });
+        version: packageVersion(),
+        ...(daemon ? { daemon: true, logFile: process.env[DAEMON_LOG_ENV] } : {}),
+    };
+    const discoveryFile = writeDiscovery(info);
+    // A background recorder outlives the discovery file's 24-hour freshness
+    // window; the heartbeat is what keeps it findable (discovery.ts).
+    const heartbeat = setInterval(() => {
+        try {
+            writeDiscovery({ ...info, heartbeatAt: Date.now() });
+        }
+        catch (err) {
+            logLine("control.heartbeat_failed", { error: errText(err) });
+        }
+    }, HEARTBEAT_MS);
+    heartbeat.unref();
     logLine("control.listening", {
         url: address.url,
         cwd,
         discovery: discoveryFile,
         journal: journalFile,
         machine: hostname(),
+        version: packageVersion(),
+        background: daemon ? "yes" : undefined,
         wrapped: wrappedServersFor(cwd).join(",") || "(none)",
     });
-    if (sidecar.controlPort && sidecar.controlPort !== address.port) {
-        // The hook URLs in settings.json name a port; if we could not take it, the
-        // hooks will POST into the void. Say so rather than looking healthy.
-        logLine("control.port_mismatch", {
-            installed: sidecar.controlPort,
-            actual: address.port,
-            why: "hooks point at the installed port — re-run `bir install` or free that port",
-        });
+    if (preferredPort !== DEFAULT_CONTROL_PORT || sidecar.controlPort || projectRecord(sidecar, cwd)) {
+        if (preferredPort !== address.port) {
+            // The hook URLs in settings.json name a port; if we could not take it,
+            // the hooks will POST into the void. Say so rather than looking healthy.
+            logLine("control.port_mismatch", {
+                installed: preferredPort,
+                actual: address.port,
+                why: "hooks point at the installed port — re-run `bir install` or free that port",
+            });
+        }
     }
     let closing = false;
-    const shutdown = async () => {
+    async function shutdown() {
         if (closing)
             return;
         closing = true;
+        clearInterval(heartbeat);
         await server.close().catch((err) => logLine("control.close_failed", { error: errText(err) }));
         removeDiscovery(cwd);
         logLine("control.stopped", {});
         process.exit(0);
-    };
+    }
     process.on("SIGINT", () => void shutdown());
     process.on("SIGTERM", () => void shutdown());
     process.on("uncaughtException", (err) => logLine("control.uncaught", { error: errText(err) }));

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

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 /**
- * bir-scenario — a first-party MCP server with exactly one tool
- * (docs/calculatedReplay.md §6.3).
+ * bir-scenario — the first-party `bir` MCP server (docs/calculatedReplay.md §6.3):
+ * `run_scenario`, plus the tools that read and fix a calculated scenario
+ * (editSteps.md in the BaseIn repository; docs/calculatedReplayGuide.md §9.2).
  *
  * 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
@@ -17,6 +18,21 @@
  * control server exactly as a proxy does — `~/.baseinstrunner/control/<key>.json`,
  * mode 0600, bearer token — and forwards one call.
  *
+ * 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.
+ *
+ * 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.
+ *
  * 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.
  */