@basein/runner 0.3.0 → 0.3.2

package/README.md

@@ -413,11 +413,13 @@ 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. |
 | `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. |
 | `BIR_DERIVE_MODEL` | Derivation model, when you set a key of your own (default `claude-haiku-4-5-20251001`). |
-| `BIR_MATCH_BUDGET_MS` | How long the prompt hook waits for a match (default `1500`). After a match slower than `BIR_MATCH_SLOW_MS` (default `800`), or one that timed out, prompts stop waiting for 5 min, doubling up to 30 min; a fast match ends that. |
+| `BIR_MATCH_BUDGET_MS` | How long the prompt hook waits for a match (default `3000`). After a match slower than `BIR_MATCH_SLOW_MS` (default `2000`), or one that timed out, prompts stop waiting for 5 min, doubling up to 30 min; a fast match ends that. |
 | `BIR_DERIVE_BUDGET_MS` / `BIR_HOOK_DERIVE_BUDGET_MS` | How long a direct run, and a hook, waits for parameters (default `8000` / `4000`; a hook waits the smaller). |
 | `BIR_PRETOOL_REPLAY_BUDGET_MS` | Everything replay does inside one `PreToolUse` (default `9000`, at most `10000`). |
 | `BIR_REPLAY_BUDGET_MS` / `BIR_STEP_TIMEOUT_MS` | Whole-plan and per-step ceilings for direct execution (default `100000` / `60000`; `BIR_REPLAY_PLAN_BUDGET_MS` also sets the first). A direct run's parameter wait plus its plan are held under 270 s. |

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
@@ -77,7 +89,7 @@
  *                             `bir-hooks` run by hand in a terminal uses that
  *                             terminal's ANTHROPIC_API_KEY as it always did
  *   BIR_DERIVE_MODEL          derivation model (default claude-haiku-4-5-…)
- *   BIR_MATCH_BUDGET_MS       prompt-hook match wait (default 1500)
+ *   BIR_MATCH_BUDGET_MS       prompt-hook match wait (default 3000)
  *   BIR_DERIVE_BUDGET_MS      derivation wait before a direct run (default 8000);
  *                             inside a hook it is at most BIR_HOOK_DERIVE_BUDGET_MS
  *                             (default 4000)

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
@@ -77,7 +89,7 @@
  *                             `bir-hooks` run by hand in a terminal uses that
  *                             terminal's ANTHROPIC_API_KEY as it always did
  *   BIR_DERIVE_MODEL          derivation model (default claude-haiku-4-5-…)
- *   BIR_MATCH_BUDGET_MS       prompt-hook match wait (default 1500)
+ *   BIR_MATCH_BUDGET_MS       prompt-hook match wait (default 3000)
  *   BIR_DERIVE_BUDGET_MS      derivation wait before a direct run (default 8000);
  *                             inside a hook it is at most BIR_HOOK_DERIVE_BUDGET_MS
  *                             (default 4000)

package/dist/control/recorder-main.d.ts

@@ -23,10 +23,10 @@
 import { ControlServer } from "./server.js";
 /**
  * What a prompt waits for its scenario match by default (`BIR_MATCH_BUDGET_MS`).
- * Past it the prompt goes on without one (K5): the service answering in 1-2 s
- * must not add that to every prompt.
+ * Past it the prompt goes on without one (K5): a service slower than 3 s must
+ * not add that to every prompt.
  */
-export declare const DEFAULT_MATCH_BUDGET_MS = 1500;
+export declare const DEFAULT_MATCH_BUDGET_MS = 3000;
 /**
  * `BIR_CORRELATION_DECISION`, passed on only when it was set to `allow` or
  * `ask`. Unset, nothing is passed and the control server decides — and by

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";
@@ -40,10 +41,10 @@ const SHUTDOWN_CLOSE_MS = 3_000;
 const SHUTDOWN_HARD_MS = 5_000;
 /**
  * What a prompt waits for its scenario match by default (`BIR_MATCH_BUDGET_MS`).
- * Past it the prompt goes on without one (K5): the service answering in 1-2 s
- * must not add that to every prompt.
+ * Past it the prompt goes on without one (K5): a service slower than 3 s must
+ * not add that to every prompt.
  */
-export const DEFAULT_MATCH_BUDGET_MS = 1_500;
+export const DEFAULT_MATCH_BUDGET_MS = 3_000;
 /** How often records of dead recorders are swept from the control directory. */
 const SWEEP_EVERY_MS = 24 * 60 * 60 * 1000;
 /**
@@ -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

@@ -140,13 +140,14 @@ const DELIVERY_HELLO_TTL_MS = 30 * 60_000;
 /** At most this many `bir-scenario` processes are remembered, newest kept. */
 const DELIVERY_HELLO_MAX = 256;
 /*
- * `slowMs` is 800: a healthy service answers the create-and-match in about
- * 300-450 ms (a cold TLS connection adds ~250 ms), so an answer past 800 ms is
- * a degraded service, and waiting on it would add that much to every prompt.
+ * `slowMs` is 2000: a healthy service answers the create-and-match in about
+ * 300-450 ms (a cold TLS connection adds ~250 ms), but a service that is only
+ * somewhat slow should keep replay on, so only an answer past 2 s counts as a
+ * degraded one, and waiting on it would add that much to every prompt.
  * A false trip costs only replay for one hold, never latency.
  */
 const DEFAULT_MATCH_GATE = {
-    slowMs: 800,
+    slowMs: 2_000,
     holdMs: 5 * 60_000,
     maxHoldMs: 30 * 60_000,
 };
@@ -1545,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
@@ -1642,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;
@@ -3013,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,120 @@
+/**
+ * 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[];
+}
+/**
+ * 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