@basein/runner 0.3.1 → 0.3.3

package/README.md

@@ -413,6 +413,8 @@ what to do when they register, so there is one switch and no second copy of it:
 |---|---|
 | `BIR_REPLAY` | `0` turns replay off and any other value on, over the project's stored switch (`bir replay on` / `off`; a first plain `bir install` stores off). Nothing below matters while it is off. |
 | `BIR_REPLAY_ALLOW_SERVERS` | Server keys bir may call unattended: **direct** execution, and a steered plan's recovery. Unset means the list `bir replay allow` stored for the project, else every wrapped server; narrowing it is the recommendation. |
+| `BIR_BUILTIN_TOOLS` | Built-in tools bir may execute itself during a replay — in the session's own project directory, and confined to it. Default `Read,Glob,Grep` (read-only). Add `Edit,Write,Bash` only deliberately: a runner-side step never reaches Claude Code's permission prompts. `none` turns it off, and a built-in step hands the turn back as before. |
+| `BIR_BASH_ALLOW` | Command prefixes a runner-side `Bash` step may run (`*` for all). Unset, `Bash` never executes on the runner, even when `BIR_BUILTIN_TOOLS` lists it. A plan's Bash steps share a working directory, as Claude Code's do (variables and functions do not persist, also as in Claude Code). |
 | `BIR_MIN_STEER_SIMILARITY` | Minimum match similarity to replay (default `0.92`, above the service's own `0.9` detection threshold). |
 | `BIR_DERIVE_API_KEY` | **Optional.** Working out what a new request is about — which fleet, which file, which date — is done for you by the service on its own key, as long as you are signed in. Set this (an Anthropic key) only to keep that reading on your machine, on your key. Signed out *and* unset, a scenario whose values change between requests is declined rather than replayed on stale ones. |
 | `ANTHROPIC_API_KEY` | Not used by the background recorder, which has Claude Code's environment and would bill your own key — unless `BIR_USE_ANTHROPIC_API_KEY=1`. A `bir-hooks` run by hand in a terminal uses that terminal's key. |

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

@@ -61,6 +61,18 @@
  *                             mode; every other tool call is asked as usual.
  *   BIR_REPLAY_ALLOW_SERVERS  comma-separated server keys eligible for *direct*
  *                             execution. Unset means every wrapped server
+ *   BIR_BUILTIN_TOOLS         comma-separated built-ins the runner may execute
+ *                             itself during a replay, in the session's own
+ *                             project directory and confined to it
+ *                             (replay/builtins.ts). Default Read,Glob,Grep —
+ *                             the read-only set. Add Edit,Write,Bash only
+ *                             deliberately: a runner-side step never reaches
+ *                             the host's permission prompts. `none` turns
+ *                             built-ins off, and then a built-in step hands
+ *                             the turn back, as before
+ *   BIR_BASH_ALLOW            command prefixes a runner-side Bash step may run
+ *                             (`*` for all). Unset, Bash never executes on the
+ *                             runner even when BIR_BUILTIN_TOOLS lists it
  *   BIR_MIN_STEER_SIMILARITY  minimum match similarity to replay (default 0.92)
  *   BIR_DERIVE_API_KEY        OPTIONAL. Derivation — reading what this turn acts
  *                             on — is done by the service for a signed-in

package/dist/bin/bir-hooks.js

@@ -61,6 +61,18 @@
  *                             mode; every other tool call is asked as usual.
  *   BIR_REPLAY_ALLOW_SERVERS  comma-separated server keys eligible for *direct*
  *                             execution. Unset means every wrapped server
+ *   BIR_BUILTIN_TOOLS         comma-separated built-ins the runner may execute
+ *                             itself during a replay, in the session's own
+ *                             project directory and confined to it
+ *                             (replay/builtins.ts). Default Read,Glob,Grep —
+ *                             the read-only set. Add Edit,Write,Bash only
+ *                             deliberately: a runner-side step never reaches
+ *                             the host's permission prompts. `none` turns
+ *                             built-ins off, and then a built-in step hands
+ *                             the turn back, as before
+ *   BIR_BASH_ALLOW            command prefixes a runner-side Bash step may run
+ *                             (`*` for all). Unset, Bash never executes on the
+ *                             runner even when BIR_BUILTIN_TOOLS lists it
  *   BIR_MIN_STEER_SIMILARITY  minimum match similarity to replay (default 0.92)
  *   BIR_DERIVE_API_KEY        OPTIONAL. Derivation — reading what this turn acts
  *                             on — is done by the service for a signed-in

package/dist/control/recorder-main.js

@@ -26,6 +26,7 @@ import { DISCOVERY_CHECK_MS, HEARTBEAT_MS, pidAlive, readDiscovery, removeDiscov
 import { DAEMON_CWD_ENV, DAEMON_ENV, DAEMON_LOG_ENV, DERIVE_KEY_ENV, DaemonLog, USE_API_KEY_ENV, clearPortProblem, compareVersions, probeHealth, projectEndpoint, rediscover, validPort, writePortProblem, } from "./daemon.js";
 import { configDir, normalizePath, supersededLogPath } from "./paths.js";
 import { RecorderKeeper } from "./recorder-keeper.js";
+import { parseBashAllow, parseBuiltinTools } from "../replay/builtins.js";
 import { parseAllowList } from "../replay/coverage.js";
 import { sweepDeliveries } from "../replay/bash-channel.js";
 import { exemptLoopbackFromProxy, isWrapped, projectRecord, projectToken, readSidecar, } from "../config/generate.js";
@@ -177,10 +178,18 @@ function buildReplayOptions(keeper, policy, key) {
             ? parseAllowList(policy.allowServers.join(","))
             : undefined;
     const minSimilarity = Number.isFinite(envMin) ? envMin : (policy?.minSimilarity ?? 0.92);
+    // Which built-ins the runner may execute itself (replay/builtins.ts):
+    // read-only by default, `BIR_BUILTIN_TOOLS` to change, `BIR_BASH_ALLOW`
+    // before a `Bash` step may run at all. Environment-only knobs, like
+    // `BIR_REPLAY_RECORDED_OUTPUTS`.
+    const builtinTools = parseBuiltinTools(process.env.BIR_BUILTIN_TOOLS);
+    const bashAllow = parseBashAllow(process.env.BIR_BASH_ALLOW);
     const opts = {
         enabled,
         minSimilarity,
         allowServers,
+        builtinTools,
+        bashAllow,
         budgets: {
             // What a prompt may wait for its match (K5). Past it the prompt goes on
             // without one; a service slower than this must not cost every prompt.
@@ -237,6 +246,10 @@ function buildReplayOptions(keeper, policy, key) {
         logLine("replay.enabled", {
             minSimilarity: opts.minSimilarity,
             allowServers: allowServers ? [...allowServers].join(",") : "(all wrapped)",
+            // Which built-ins may run on the runner itself, and whether Bash may at
+            // all — loud for the same reason as the rest of this line.
+            builtins: builtinTools.size > 0 ? [...builtinTools].join(",") : "(none)",
+            bashAllow: builtinTools.has("Bash") ? (bashAllow ? bashAllow.join(",") : "(unset — Bash never runs here)") : undefined,
             // Who reads what this turn acts on (segmented.md R-PARAM-5). Named at
             // startup because the third state is a replay that silently never runs.
             derive: key.source ??

package/dist/control/server.js

@@ -1546,6 +1546,10 @@ export class ControlServer {
             return undefined;
         }
         state.sessionId = session.sessionId;
+        // The project directory an allow-listed built-in step executes in, and
+        // the jail it may not leave (replay/builtins.ts). The session's own cwd
+        // from the hook payloads, never the daemon's.
+        state.sessionCwd = session.cwd ?? this.opts.cwd;
         this.declineWithoutDeliveryTool(state);
         // A steer plan with a shell or file-write step can only be followed if the
         // directive shows its computed arguments (the pin guard holds those steps
@@ -1643,6 +1647,10 @@ export class ControlServer {
             return undefined;
         }
         state.sessionId = session.sessionId;
+        // The project directory an allow-listed built-in step executes in, and
+        // the jail it may not leave (replay/builtins.ts). The session's own cwd
+        // from the hook payloads, never the daemon's.
+        state.sessionCwd = session.cwd ?? this.opts.cwd;
         run.replay = state;
         run.replays.push(state);
         return undefined;
@@ -3014,6 +3022,10 @@ export class ControlServer {
             return undefined;
         }
         state.sessionId = session.sessionId;
+        // The project directory an allow-listed built-in step executes in, and
+        // the jail it may not leave (replay/builtins.ts). The session's own cwd
+        // from the hook payloads, never the daemon's.
+        state.sessionCwd = session.cwd ?? this.opts.cwd;
         this.declineWithoutDeliveryTool(state);
         if (!state.plan) {
             // A declined intent hit reports nothing: the turn's cost is not a

package/dist/replay/builtins.d.ts

@@ -0,0 +1,135 @@
+/**
+ * builtins — running a scenario's built-in steps (`Read`, `Glob`, `Grep`,
+ * `Edit`, `Write`, `Bash`) on the runner itself (docs/calculatedReplay.md §5).
+ *
+ * A built-in lives inside the host session, not behind any MCP server, so there
+ * is no proxy to relay it to: historically every built-in step threw `not_run`
+ * and the plan handed the task back to the model. This module is the other
+ * option: execute the step here, against the *session's own project directory*,
+ * so a chain that starts with a `Read` no longer costs a hand-over.
+ *
+ * THE RULES, because this bypasses the host's permission prompts entirely:
+ *
+ *   - **Default deny beyond read-only.** Which built-ins may run at all is
+ *     `BIR_BUILTIN_TOOLS` ({@link parseBuiltinTools}), and its default is the
+ *     read-only set (`Read,Glob,Grep`). `Edit`, `Write` and `Bash` are an
+ *     explicit, per-environment opt-in — a recorded `rm` must never run
+ *     because a prompt looked similar.
+ *   - **Path jail.** Every path is resolved against, and confined to, the
+ *     session's project directory ({@link jailed}), symlinks included. The
+ *     daemon's own cwd is never used: it is `~/.baseinstrunner`, not the
+ *     project (§5.1 of the change plan).
+ *   - **Bash runs nothing unless `BIR_BASH_ALLOW` says so.** A command must
+ *     match one of its prefixes ({@link bashAllowed}); unset means `Bash`
+ *     never executes here, even when allow-listed.
+ *   - **Same failure contract as an MCP step.** A step that *cannot* run here
+ *     throws {@link BuiltinNotRunnable} (→ `not_run`: the session can still do
+ *     it, or a recorded output may stand in under
+ *     `BIR_REPLAY_RECORDED_OUTPUTS=1`). One that ran out of time throws
+ *     {@link BuiltinTimeout} (→ `uncertain`). Any other throw is a step that
+ *     ran and failed (→ `failed`), never silently threaded as a success.
+ *
+ * Outputs mimic the **hook view** of each tool — Claude Code's `tool_response`
+ * as `PostToolUse` reports it — because that is exactly what the recorder
+ * stored for built-in steps (control/server.ts, `onToolPost`) and therefore
+ * what each step's `toolOutputLogic` was authored against. The shapes are a
+ * best effort and may drift from a future host's, the same caveat the
+ * hook-view threading fallback already carries ("shapes may differ").
+ */
+/**
+ * The built-ins bir may stand in for or execute when `BIR_BUILTIN_TOOLS` is
+ * unset: the read-only set. Reading a file the session itself would read
+ * without a prompt is the risk floor; anything that writes or runs is not.
+ */
+export declare const DEFAULT_BUILTIN_TOOLS: readonly string[];
+/** The built-ins {@link runBuiltin} actually implements. */
+export declare const EXECUTABLE_BUILTINS: ReadonlySet<string>;
+/**
+ * Parse `BIR_BUILTIN_TOOLS`. Unset means {@link DEFAULT_BUILTIN_TOOLS}; set,
+ * it is the whole list — `none` (or an empty value) turns built-ins off
+ * entirely. Unlike `BIR_REPLAY_ALLOW_SERVERS`, an explicit empty list is
+ * honoured: there is a non-empty default to fall back from, so emptiness here
+ * is a choice, not an accident.
+ */
+export declare function parseBuiltinTools(value: string | undefined): ReadonlySet<string>;
+/**
+ * Parse `BIR_BASH_ALLOW`: comma-separated command prefixes, `*` for
+ * everything. Undefined (unset or blank) means `Bash` never executes on the
+ * runner — the flag is the opt-in, exactly like the tool list itself.
+ */
+export declare function parseBashAllow(value: string | undefined): readonly string[] | undefined;
+/**
+ * Whether `command` matches the `BIR_BASH_ALLOW` prefixes. A prefix that ends
+ * mid-word must end the command's word too: `git` allows `git status` and
+ * `git`, never `gitk` — an operator who wrote `git` meant git, and the
+ * trimming in {@link parseBashAllow} must not widen that.
+ */
+export declare function bashAllowed(command: string, allow: readonly string[] | undefined): boolean;
+/**
+ * The step cannot run here — policy, not breakage: the tool is not
+ * implemented, its path leaves the project, `Bash` is not allowed, or the
+ * input is not even the right shape. Maps to `not_run`: nothing happened, the
+ * session may still do it, a recorded output may stand in.
+ */
+export declare class BuiltinNotRunnable extends Error {
+    constructor(message: string);
+}
+/**
+ * The step started and was cut off by its clock. For `Bash` the command may
+ * have done part of its work; for a walk there is simply no result. Either
+ * way nothing may be asserted, which is `uncertain` — the same word an MCP
+ * step's timeout gets.
+ */
+export declare class BuiltinTimeout extends Error {
+    constructor(message: string);
+}
+export interface BuiltinContext {
+    /**
+     * The session's project directory — the jail every path resolves against.
+     * The caller (controller.ts) refuses to execute at all without one; the
+     * daemon's own cwd is never a substitute.
+     */
+    cwd: string;
+    /** The step's clock, the same budget an MCP dispatch would get. */
+    timeoutMs?: number;
+    /** Parsed `BIR_BASH_ALLOW` ({@link parseBashAllow}). */
+    bashAllow?: readonly string[];
+    /**
+     * Where this plan's *previous* `Bash` step left its shell — the host's own
+     * semantics, which a recorded chain was written against: the working
+     * directory persists between Bash calls, while variables and functions do
+     * not (each call is a fresh shell off the profile). Absent, or pointing at
+     * a directory that no longer exists, the step starts in {@link cwd}.
+     */
+    bashCwd?: string;
+    /**
+     * Told where a `Bash` step's shell ended up (`$PWD`, as a path the next
+     * spawn can use), so the caller can carry it into the plan's next Bash
+     * step. Best effort: a command that `exit`s explicitly, or is cut off by
+     * its clock, reports nothing and the previous directory stands.
+     */
+    onBashCwd?: (pwd: string) => void;
+}
+/**
+ * Execute one built-in step and return its hook-shaped result (an object; the
+ * caller serializes). Throws per the failure contract above.
+ */
+export declare function runBuiltin(toolName: string, input: Record<string, unknown>, ctx: BuiltinContext): Promise<unknown>;
+/**
+ * Which `bash` a runner-side step uses. On Windows the host's own Bash tool
+ * is Git Bash, which is rarely on the daemon's PATH — so the standard
+ * Git-for-Windows locations are preferred over PATH, where `bash.exe` may
+ * even be the WSL stub (a different filesystem view entirely). Resolved once.
+ */
+export declare function bashExecutable(): string;
+/**
+ * A glob pattern as a RegExp over `/`-separated relative paths: `**` crosses
+ * directories, `*` and `?` stay inside one, `{a,b}` alternates, `[…]` passes
+ * through as a character class. Matched against the whole relative path, as
+ * the host's Glob does — a bare `*.ts` is the top level only (Grep's filter
+ * widens a bare pattern itself, ripgrep-style). Enough for the patterns
+ * Claude Code writes; a pattern beyond it simply matches nothing it should
+ * not.
+ */
+export declare function globToRegExp(pattern: string): RegExp;
+//# sourceMappingURL=builtins.d.ts.map