@basein/runner 0.3.8 → 0.3.10

package/dist/bin/update.js

@@ -0,0 +1,194 @@
+/**
+ * `bir update` — put the newest version where THIS copy of the runner is.
+ *
+ * There are two ways the runner gets onto a machine, and each keeps it in a
+ * different place:
+ *
+ *   - the console's install line (scripts/install.sh, install.ps1) installs it
+ *     into `~/.baseinstrunner/npm`, with the npm that sits beside the Node its
+ *     launchers name. `npm i -g` never writes there: typed by hand it adds a
+ *     second copy in npm's own prefix and leaves the one the launchers start
+ *     as old as before, and which copy a shell then finds depends on its PATH;
+ *   - `npm install -g @basein/runner`, into npm's own prefix.
+ *
+ * So the command that updates the runner depends on where the runner is, and
+ * the copy that is running is the one that knows. A copy under
+ * `~/.baseinstrunner/npm` repeats what the install line did: the same Node,
+ * the npm beside it, `--prefix` that folder. Any other installed copy runs
+ * `npm install -g`, after asking npm where it keeps its global packages: when
+ * this copy is not there (pnpm, yarn, another Node's prefix), npm would write
+ * the second copy this command exists to prevent, so nothing is installed.
+ *
+ * It replaces the package and nothing else. `bir setup` in each project is
+ * what moves the wiring and replaces an older recorder, and it is the next
+ * thing the output names.
+ *
+ * NOT TESTED on Windows against a live session: npm replaces the folder this
+ * process and the recorder were loaded from. Neither keeps a file of it open,
+ * and the install line has always done the same replacement, but if npm ends
+ * with EPERM or EBUSY the answer is to close Claude Code and run it again.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PACKAGE_NAME } from "../config/generate.js";
+import { normalizePath } from "../control/paths.js";
+import { packageVersion } from "../util/version.js";
+/** What `bir update` installs. */
+const SPEC = `${PACKAGE_NAME}@latest`;
+/**
+ * The one Node flag the install scripts hand to npm. `--use-env-proxy` is not
+ * carried: npm reads HTTPS_PROXY itself.
+ */
+const NPM_NODE_FLAGS = ["--use-system-ca"];
+/** The folder of this package: the nearest `package.json` that names it. */
+export function packageRoot(from = fileURLToPath(import.meta.url)) {
+    let dir = dirname(from);
+    for (let i = 0; i < 5; i += 1) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+            if (pkg.name === PACKAGE_NAME)
+                return dir;
+        }
+        catch {
+            /* keep walking */
+        }
+        dir = dirname(dir);
+    }
+    return undefined;
+}
+/** Where a global install into `prefix` keeps this package: npm adds `lib` everywhere but on Windows. */
+export function packageDirIn(prefix, platform = process.platform) {
+    const modules = platform === "win32" ? join(prefix, "node_modules") : join(prefix, "lib", "node_modules");
+    return join(modules, ...PACKAGE_NAME.split("/"));
+}
+/** The `npm-cli.js` that ships beside a Node binary, where the install scripts look for it. */
+export function npmCliBeside(execPath, platform = process.platform) {
+    const dir = dirname(execPath);
+    return platform === "win32"
+        ? join(dir, "node_modules", "npm", "bin", "npm-cli.js")
+        : join(dir, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js");
+}
+function samePath(a, b) {
+    const real = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return p;
+        }
+    };
+    return normalizePath(real(a)) === normalizePath(real(b));
+}
+/** Decide what `bir update` runs. Changes nothing. */
+export function planUpdate(deps = {}) {
+    const root = deps.packageRoot ?? packageRoot();
+    const platform = deps.platform ?? process.platform;
+    if (!root)
+        return { kind: "refused", why: "this bir cannot tell where its own package is, so it cannot update it." };
+    if (/[\\/]_npx[\\/]/.test(root)) {
+        return {
+            kind: "refused",
+            why: "this bir runs from npx's cache, so there is no installed copy to update. " +
+                `Install it (npm install -g ${PACKAGE_NAME}), then run \`bir setup\` in the project.`,
+        };
+    }
+    if (!/[\\/]node_modules[\\/]/.test(root)) {
+        return {
+            kind: "refused",
+            why: `this bir runs from a checkout (${root}), not from an installed package: \`git pull\` and \`npm run build\` there update it.`,
+        };
+    }
+    const prefix = join(deps.home ?? homedir(), ".baseinstrunner", "npm");
+    if (samePath(root, packageDirIn(prefix, platform))) {
+        const execPath = deps.execPath ?? process.execPath;
+        const npmCli = deps.npmCli ?? npmCliBeside(execPath, platform);
+        if (!existsSync(npmCli)) {
+            return {
+                kind: "refused",
+                why: `the Node this bir runs on (${execPath}) has no npm beside it any more (${npmCli} is missing). ` +
+                    "Paste the install line from the console again: it puts both back.",
+            };
+        }
+        const flags = (deps.execArgv ?? process.execArgv).filter((a) => NPM_NODE_FLAGS.includes(a));
+        return {
+            kind: "private",
+            root,
+            command: execPath,
+            args: [...flags, npmCli, "install", "-g", "--prefix", prefix, "--no-fund", "--no-audit", SPEC],
+        };
+    }
+    return { kind: "npm", root, command: "npm", args: ["install", "-g", SPEC] };
+}
+/**
+ * `npm` on PATH is `npm.cmd` on Windows, which Node starts only through a
+ * shell. The whole line is passed as one string then (every word of it is
+ * ours), and an absolute path — the private copy's Node — never needs it.
+ */
+function needsShell(command) {
+    return process.platform === "win32" && command === "npm";
+}
+function defaultRun(command, args) {
+    const r = needsShell(command)
+        ? spawnSync([command, ...args].join(" "), { stdio: "inherit", shell: true, windowsHide: true })
+        : spawnSync(command, args, { stdio: "inherit", windowsHide: true });
+    return r.error ? null : r.status;
+}
+function defaultCapture(command, args) {
+    const opts = { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], windowsHide: true };
+    const r = needsShell(command)
+        ? spawnSync([command, ...args].join(" "), { ...opts, shell: true })
+        : spawnSync(command, args, opts);
+    return r.error || r.status !== 0 ? undefined : r.stdout;
+}
+function versionAt(root) {
+    try {
+        return JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `bir update`. Returns the exit code: 1 when nothing was updated. */
+export function runUpdate(deps) {
+    const plan = planUpdate(deps);
+    if (plan.kind === "refused") {
+        deps.err(plan.why);
+        return 1;
+    }
+    const run = deps.run ?? defaultRun;
+    if (plan.kind === "npm") {
+        // Where would npm put it? Somewhere else means a second copy, and the
+        // `bir` a shell finds would stay this one. An npm that cannot say is not
+        // held against the update: npm itself reports what is wrong with it.
+        const answer = (deps.capture ?? defaultCapture)("npm", ["root", "-g"]);
+        const globalModules = answer?.split(/\r?\n/).map((l) => l.trim()).filter(Boolean).pop();
+        if (globalModules && !samePath(join(globalModules, ...PACKAGE_NAME.split("/")), plan.root)) {
+            deps.err(`npm keeps its global packages in ${globalModules}, and this bir is not there (it runs from ${plan.root}): ` +
+                "`npm install -g` would add a second copy and leave this one as it is. " +
+                "Update it with the tool that installed it, then run `bir setup` in each project.");
+            return 1;
+        }
+    }
+    const before = versionAt(plan.root) ?? packageVersion();
+    deps.out(`Updating bir ${before} in ${plan.root}`);
+    deps.out(`  ${[plan.command, ...plan.args].map((a) => (/\s/.test(a) ? `"${a}"` : a)).join(" ")}`);
+    const code = run(plan.command, plan.args);
+    if (code !== 0) {
+        deps.err(code === null
+            ? `${plan.command} could not be started, so nothing was updated.`
+            : `npm ended with exit code ${code}, so bir was not updated; the lines above say why.`);
+        if (process.platform === "win32") {
+            deps.err("If they name EPERM or EBUSY, a running program holds the runner's files: close Claude Code and run `bir update` again.");
+        }
+        return 1;
+    }
+    const after = versionAt(plan.root);
+    deps.out(after && after !== before ? `bir is now ${after} (it was ${before}).` : `bir ${after ?? before} is the newest version; nothing changed.`);
+    deps.out("Next: `bir setup` in each project that uses it. It moves the wiring to this version and replaces an older recorder;");
+    deps.out("one that is serving a Claude Code session mid-turn stays until `bir up --restart`, once that session ends.");
+    return 0;
+}
+//# sourceMappingURL=update.js.map

package/dist/config/adapters/claude-code.d.ts

@@ -20,6 +20,7 @@
  * committed and would carry this machine's node and runner paths to every
  * clone, and never the user scope, which applies to every project.
  */
+import { type InstalledSidecar } from "../generate.js";
 import { type McpServerConfig, type Scope } from "../resolve.js";
 export interface ClaudeCodePaths {
     /** `~/.claude.json` (user + local scopes). */
@@ -106,6 +107,22 @@ export declare function addAllowRules(settingsPath: string, rules: string[]): {
 export declare function removeAllowRules(settingsPath: string, rules: string[]): string | undefined;
 /** True when `settingsPath` holds any hook of ours. */
 export declare function hasBirHooks(settingsPath: string): boolean;
+/**
+ * Whether `cwd` is set up for Claude Code: an install wrapped a server for
+ * it, or hooks of ours are in its settings files.
+ */
+export declare function claudeCodeSetUp(cwd: string, sidecar: InstalledSidecar): boolean;
+/**
+ * The hosts other than Claude Code that `cwd` was set up for (`bir setup
+ * --host langchain`), or an empty list.
+ */
+export declare function otherHosts(cwd: string, sidecar: InstalledSidecar): string[];
+/**
+ * Whether `cwd` is set up for another host and NOT for Claude Code. Asked
+ * afresh each time rather than stored: a later `bir setup` for Claude Code in
+ * the same folder must be seen at once.
+ */
+export declare function otherHostOnly(cwd: string, sidecar: InstalledSidecar): boolean;
 /** Which file holds a given scope's `mcpServers` for this cwd. */
 export declare function fileForScope(scope: Scope, paths: ClaudeCodePaths): string;
 export declare function sha256(text: string): string;

package/dist/config/adapters/claude-code.js

@@ -23,8 +23,9 @@
 import { createHash } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join, parse as parsePath, resolve as resolvePath } from "node:path";
+import { normalizePath } from "../../control/paths.js";
 import { writeFileAtomic } from "../../util/atomic-write.js";
-import { FIRST_PROJECT_PORT, PACKAGE_NAME, SCENARIO_SERVER_KEY } from "../generate.js";
+import { FIRST_PROJECT_PORT, PACKAGE_NAME, SCENARIO_SERVER_KEY, projectRecord, } from "../generate.js";
 import { claudeJsonPath, parseJsonFile, parseJsonText, projectKeyFor, } from "../resolve.js";
 export function claudeCodePaths(cwd, claudeJsonOverride) {
     return {
@@ -258,6 +259,32 @@ export function hasBirHooks(settingsPath) {
         return false;
     return Object.values(hooks).some((matchers) => (matchers ?? []).some((m) => (m.hooks ?? []).some((h) => isBirHook(h))));
 }
+/**
+ * Whether `cwd` is set up for Claude Code: an install wrapped a server for
+ * it, or hooks of ours are in its settings files.
+ */
+export function claudeCodeSetUp(cwd, sidecar) {
+    const here = normalizePath(cwd);
+    if (Object.values(sidecar.servers ?? {}).some((record) => normalizePath(record.cwd) === here))
+        return true;
+    const paths = claudeCodePaths(cwd);
+    return hasBirHooks(paths.settingsLocal) || hasBirHooks(paths.settings);
+}
+/**
+ * The hosts other than Claude Code that `cwd` was set up for (`bir setup
+ * --host langchain`), or an empty list.
+ */
+export function otherHosts(cwd, sidecar) {
+    return projectRecord(sidecar, cwd)?.hosts ?? [];
+}
+/**
+ * Whether `cwd` is set up for another host and NOT for Claude Code. Asked
+ * afresh each time rather than stored: a later `bir setup` for Claude Code in
+ * the same folder must be seen at once.
+ */
+export function otherHostOnly(cwd, sidecar) {
+    return otherHosts(cwd, sidecar).length > 0 && !claudeCodeSetUp(cwd, sidecar);
+}
 /** Which file holds a given scope's `mcpServers` for this cwd. */
 export function fileForScope(scope, paths) {
     switch (scope) {

package/dist/config/generate.d.ts

@@ -484,6 +484,20 @@ export interface ProjectRecord {
      * approved by the runner) was shown for this project; it is said once.
      */
     approvalNoteShown?: boolean;
+    /**
+     * Hosts other than Claude Code this folder was set up for, with
+     * `bir setup --host <name>` (`langchain`). Such a host needs no hooks and
+     * no wrapped servers — its adapter runs inside the application and finds
+     * the recorder by its control file — so the entry is all there is: the
+     * folder's own port and token, and its replay switch.
+     *
+     * A folder that is set up for such a host and not for Claude Code gets its
+     * recorder started with a small environment (control/daemon.ts,
+     * `smallEnv`): the application's keys and passwords are not the recorder's
+     * to hold. One set up for Claude Code too keeps the whole environment, as
+     * Claude Code's own steps may need it.
+     */
+    hosts?: string[];
 }
 export interface InstalledSidecar {
     version: 1;

package/dist/control/daemon.d.ts

@@ -206,6 +206,12 @@ export interface EnsureOptions {
      * instead of clearing it, and throw {@link RecorderStoppedError} when found.
      */
     revive?: boolean;
+    /**
+     * Start the recorder with the small environment ({@link smallEnv}) or with
+     * the whole one. Unset, the folder decides: small when it is set up for
+     * another host and not for Claude Code. Tests pass it.
+     */
+    smallEnv?: boolean;
 }
 export interface EnsureResult {
     status: DaemonStatus;
@@ -358,8 +364,27 @@ export declare function reviveDaemon(cwd: string, opts?: Pick<EnsureOptions, "ho
  * happened to start it switched all of them off for the recorder's life. That
  * window's SessionStart hook tells the recorder its own session is off
  * instead (ensure-hook.ts); the flag files still switch everything.
+ *
+ * `small` starts from {@link smallEnv} rather than from everything the
+ * caller has: for a folder set up for another host and not for Claude Code.
+ */
+export declare function daemonEnv(base: NodeJS.ProcessEnv, cwd: string, logFile: string, small?: boolean): NodeJS.ProcessEnv;
+/**
+ * The small environment: what a recorder gets in a folder that is set up for
+ * a host other than Claude Code, and not for Claude Code.
+ *
+ * {@link daemonEnv} otherwise copies everything but three names, so a model
+ * key or a database password in the window that started the recorder reaches
+ * it — and step code runs inside the recorder, with no sandbox. With Claude
+ * Code that window is the developer's own. In such a folder it is the window
+ * of an application, and the recordings its plans are written from hold what
+ * that application's users typed. The same list as the LangChain adapter's
+ * own, which starts the recorder with it in every folder.
+ *
+ * A plan's step that needs a variable outside the list fails for it. That is
+ * by design: step code must not depend on the application's secrets.
  */
-export declare function daemonEnv(base: NodeJS.ProcessEnv, cwd: string, logFile: string): NodeJS.ProcessEnv;
+export declare function smallEnv(base: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /**
  * Stop the control server for `cwd`.
  *

package/dist/control/daemon.js

@@ -64,6 +64,7 @@ import { ControlClient } from "./client.js";
 import { listSupersededRecorders, pidAlive, readDiscovery, removeDiscovery, removeDiscoveryIfOwned, removeSupersededRecord, writeDiscovery, writeSupersededRecord, } from "./discovery.js";
 import { configDir, controlDir, controlKey, daemonLogPath, downMarkerPath, ensureDir, logsDir, normalizePath, portProblemPath, } from "./paths.js";
 import { nodeFlagsToCarry, projectRecord, projectToken, readSidecar, } from "../config/generate.js";
+import { otherHostOnly } from "../config/adapters/claude-code.js";
 import { writeFileAtomic } from "../util/atomic-write.js";
 import { timeoutSignal } from "../util/service-health.js";
 import { errText, logLine } from "../util/log.js";
@@ -686,7 +687,7 @@ export async function ensureDaemon(cwd, opts = {}) {
         const script = opts.hooksScript ?? hooksScriptPath();
         ensureDir(logsDir());
         rotateLog(logFile);
-        const childEnv = daemonEnv(env, cwd, logFile);
+        const childEnv = daemonEnv(env, cwd, logFile, opts.smallEnv ?? startsSmall(cwd));
         const launchedAt = Date.now();
         const launched = process.platform === "win32" && childEnv[WINDOWS_LAUNCH_ENV] !== "spawn"
             ? launchWindows(script, childEnv, clamp(remaining(deadline) - 1_000, 2_000, 8_000))
@@ -816,9 +817,12 @@ export async function reviveDaemon(cwd, opts = {}) {
  * happened to start it switched all of them off for the recorder's life. That
  * window's SessionStart hook tells the recorder its own session is off
  * instead (ensure-hook.ts); the flag files still switch everything.
+ *
+ * `small` starts from {@link smallEnv} rather than from everything the
+ * caller has: for a folder set up for another host and not for Claude Code.
  */
-export function daemonEnv(base, cwd, logFile) {
-    const env = { ...base };
+export function daemonEnv(base, cwd, logFile, small = false) {
+    const env = small ? smallEnv(base) : { ...base };
     deleteEnv(env, SETUP_TOKEN_ENV);
     if (base[USE_API_KEY_ENV] !== "1")
         deleteEnv(env, "ANTHROPIC_API_KEY");
@@ -835,6 +839,52 @@ export function daemonEnv(base, cwd, logFile) {
     env[DAEMON_CWD_ENV] = isAbsolute(cwd) ? cwd : resolvePath(cwd);
     return env;
 }
+/**
+ * What {@link smallEnv} lets through besides the `BIR_*` variables: the path,
+ * the home and temp folders, what the system needs to start a process (on
+ * Windows, Node does not start without `SystemRoot`), and the proxy and
+ * certificate settings the recorder's own calls to the service need.
+ */
+const SMALL_ENV_KEPT = new Set([
+    "PATH", "HOME", "TMPDIR", "TEMP", "TMP",
+    "USERPROFILE", "HOMEDRIVE", "HOMEPATH", "APPDATA", "LOCALAPPDATA",
+    "SYSTEMROOT", "SYSTEMDRIVE", "WINDIR", "COMSPEC", "PATHEXT",
+    "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "ALL_PROXY",
+    "NODE_EXTRA_CA_CERTS", "SSL_CERT_FILE", "SSL_CERT_DIR",
+]);
+/**
+ * The small environment: what a recorder gets in a folder that is set up for
+ * a host other than Claude Code, and not for Claude Code.
+ *
+ * {@link daemonEnv} otherwise copies everything but three names, so a model
+ * key or a database password in the window that started the recorder reaches
+ * it — and step code runs inside the recorder, with no sandbox. With Claude
+ * Code that window is the developer's own. In such a folder it is the window
+ * of an application, and the recordings its plans are written from hold what
+ * that application's users typed. The same list as the LangChain adapter's
+ * own, which starts the recorder with it in every folder.
+ *
+ * A plan's step that needs a variable outside the list fails for it. That is
+ * by design: step code must not depend on the application's secrets.
+ */
+export function smallEnv(base) {
+    const env = {};
+    for (const [key, value] of Object.entries(base)) {
+        const name = key.toUpperCase();
+        if (SMALL_ENV_KEPT.has(name) || name.startsWith("BIR_"))
+            env[key] = value;
+    }
+    return env;
+}
+/** Whether `cwd`'s recorder is started with {@link smallEnv}. Never throws: unreadable settings mean the whole environment, as before. */
+function startsSmall(cwd) {
+    try {
+        return otherHostOnly(cwd, readSidecar());
+    }
+    catch {
+        return false;
+    }
+}
 /** Delete `name` from an env copy — case-insensitively on Windows, where env names are. */
 function deleteEnv(env, name) {
     for (const key of Object.keys(env)) {

package/dist/control/pin-guard.d.ts

@@ -78,6 +78,11 @@ export declare function commandShape(command: string, depth?: number, escape?: s
 /**
  * Whether the model's call `modelArgs` to `toolName` may be pinned to the
  * step's `pinnedArgs`. See the file comment for the rule.
+ *
+ * `otherHost` is a session whose host is not Claude Code. Every rule above
+ * the last one reads a tool's name as Claude Code's (`Bash`, `Write`, `Read`,
+ * an `mcp__` name), and another host's tool of the same name is another tool:
+ * only the general rule is applied there.
  */
-export declare function pinCompatible(toolName: string, modelArgs: unknown, pinnedArgs: unknown): PinVerdict;
+export declare function pinCompatible(toolName: string, modelArgs: unknown, pinnedArgs: unknown, otherHost?: boolean): PinVerdict;
 //# sourceMappingURL=pin-guard.d.ts.map

package/dist/control/pin-guard.js

@@ -487,12 +487,26 @@ function statementVerdict(model, step) {
 /**
  * Whether the model's call `modelArgs` to `toolName` may be pinned to the
  * step's `pinnedArgs`. See the file comment for the rule.
+ *
+ * `otherHost` is a session whose host is not Claude Code. Every rule above
+ * the last one reads a tool's name as Claude Code's (`Bash`, `Write`, `Read`,
+ * an `mcp__` name), and another host's tool of the same name is another tool:
+ * only the general rule is applied there.
  */
-export function pinCompatible(toolName, modelArgs, pinnedArgs) {
+export function pinCompatible(toolName, modelArgs, pinnedArgs, otherHost = false) {
     const model = record(modelArgs);
     const step = record(pinnedArgs);
     if (stableStringify(model) === stableStringify(step))
         return { ok: true };
+    if (otherHost) {
+        const modelKeys = Object.keys(model);
+        const stepKeys = Object.keys(step);
+        if (modelKeys.length === 0 || stepKeys.length === 0)
+            return { ok: true };
+        return modelKeys.some((k) => stepKeys.includes(k))
+            ? { ok: true }
+            : { ok: false, why: "it shares no argument with the step" };
+    }
     if (toolName === "Bash" || toolName === "PowerShell") {
         const mine = typeof model.command === "string" ? model.command.trim() : "";
         const theirs = typeof step.command === "string" ? step.command.trim() : "";

package/dist/control/recorder-keeper.js

@@ -47,6 +47,7 @@ import { SwitchableRecorder } from "../record/switchable-recorder.js";
 import { configPath } from "./paths.js";
 import { isUnhealthyStatus, serviceHealth, serviceTimeoutMs, timeoutSignal } from "../util/service-health.js";
 import { isRunnerOff } from "../util/off-switch.js";
+import { serviceHeaders } from "../util/service-headers.js";
 import { errText, logDetail, logLine } from "../util/log.js";
 /** What `authenticate()` hands out under `BIR_AUTH_DISABLE=1` (auth/client.ts). */
 const LOCAL_DEV_SESSION = {
@@ -187,7 +188,7 @@ export async function refreshSession(baseUrl, session, fetchImpl = fetch, timeou
     try {
         res = await fetchImpl(`${trimUrl(baseUrl)}/auth/refresh`, {
             method: "POST",
-            headers: { "content-type": "application/json" },
+            headers: { "content-type": "application/json", ...serviceHeaders() },
             body: JSON.stringify({ refreshToken: session.refreshToken }),
             signal: timeoutSignal(timeoutMs),
         });