@basein/runner 0.2.11 → 0.2.12

package/dist/record/housekeeping.js

@@ -27,13 +27,430 @@
  * possibly be the user's task. `Read`, `Bash` and `Grep` are NOT here: they do
  * real work, they belong in a recording, and reaching for one mid-replay
  * usually *is* the model doing the task another way.
+ *
+ * THE RUNNER'S OWN `bir` IS HOUSEKEEPING TOO (editSteps.md D13), and that is
+ * the one reason this file now looks at a call's input and not only its name.
+ * A session that fixes a plan — `bir investigate`, then `bir scenario edit`, or
+ * the same through the `bir` MCP server's `scenario_*` tools — is exactly the
+ * kind of session that gets recorded and calculated. Recorded, it becomes a
+ * scenario whose steps *edit plans*, and a steered or direct replay of it would
+ * then change a plan unattended, on a prompt nobody meant as "change the plan":
+ * the very thing D2 keeps the editing tools switched off in a fleet to prevent.
+ * And mid-replay, a model that stops to read `bir investigate` has not left the
+ * plan; it is reading about it.
+ *
+ * So two more kinds of call are housekeeping, and both are still narrow:
+ *
+ *   - every tool of the `bir` MCP server **except `run_scenario`**, which is
+ *     the direct plan's delivery vehicle and keeps its own handling (it is
+ *     recorded, tagged `pinnedBy`, while its plan is live);
+ *   - a `Bash` call whose command is **nothing but** `bir` invocations
+ *     ({@link isBirOnlyCommand}), and the same for a `PowerShell` call
+ *     ({@link isBirOnlyPowerShell}) — Claude Code on Windows reaches for its
+ *     PowerShell tool as readily as for Bash, and a `bir scenario edit` run
+ *     there is the same act. `npm test && bir investigate` is not: the
+ *     `npm test` half is real work, and hiding it from the recording would be
+ *     hiding the task. When in doubt the answer is "not housekeeping", because
+ *     a `bir` call recorded by mistake costs a noisy step, while real work
+ *     skipped by mistake is a plan with a hole in it.
  */
+import { SCENARIO_SERVER_KEY } from "../config/generate.js";
 /** Host tools that are never recorded as steps and never count as divergence. */
 export const HOUSEKEEPING_TOOLS = new Set([
     "ToolSearch",
     "TodoWrite",
 ]);
+/** By name alone — the host's own bookkeeping tools. See {@link isHousekeepingCall} for the full rule. */
 export function isHousekeeping(toolName) {
     return HOUSEKEEPING_TOOLS.has(toolName);
 }
+/** `mcp__bir__`: every tool the first-party `bir` MCP server offers is named under it. */
+const SCENARIO_SERVER_PREFIX = `mcp__${SCENARIO_SERVER_KEY}__`;
+/**
+ * The direct plan's delivery vehicle. Must equal `DIRECT_TOOL_NAME` in the
+ * replay controller (a test holds them together); spelled out here because
+ * the controller imports this file.
+ */
+export const RUN_SCENARIO_TOOL = `${SCENARIO_SERVER_PREFIX}run_scenario`;
+/**
+ * Whether one call is host housekeeping: never recorded as a step, never a
+ * divergence from a plan. `toolInput` is what the hook saw (`tool_input`); only
+ * a `Bash` call's `command` is read from it.
+ */
+export function isHousekeepingCall(toolName, toolInput) {
+    if (HOUSEKEEPING_TOOLS.has(toolName))
+        return true;
+    if (toolName.startsWith(SCENARIO_SERVER_PREFIX))
+        return toolName !== RUN_SCENARIO_TOOL;
+    if (toolName === "Bash" || toolName === "PowerShell") {
+        const command = toolInput?.command;
+        if (typeof command !== "string")
+            return false;
+        return toolName === "Bash" ? isBirOnlyCommand(command) : isBirOnlyPowerShell(command);
+    }
+    return false;
+}
+/**
+ * {@link isBirOnlyCommand} for PowerShell, whose rules differ enough that the
+ * Bash reader would get it wrong: a backslash is a path separator, not an
+ * escape; the escape is the backtick; `$(…)` runs code even inside double
+ * quotes; `&` at the start of a part is the call operator. Deliberately
+ * narrower than the Bash reader: parts split on `;`, `&&`, `||` and newlines
+ * (outside quotes); each is `bir …` (as {@link isBirInvocation} reads it, also
+ * after a leading `&`) or a plain `cd`/`Set-Location`/`Push-Location <dir>`.
+ * A pipe, a backtick, `$(` or `@(` anywhere, a brace or parenthesis outside
+ * quotes, an `@` starting a word, or a quote left open makes the answer false — for the same
+ * reason as there: when unsure, record it.
+ */
+export function isBirOnlyPowerShell(command) {
+    if (command.includes("`") || command.includes("$(") || command.includes("@("))
+        return false;
+    const segments = [];
+    let words = [];
+    let word = "";
+    let inWord = false;
+    const endWord = () => {
+        if (inWord)
+            words.push(word);
+        word = "";
+        inWord = false;
+    };
+    const endSegment = () => {
+        endWord();
+        segments.push(words);
+        words = [];
+    };
+    for (let i = 0; i < command.length; i += 1) {
+        const c = command[i];
+        if (c === "'" || c === '"') {
+            const close = command.indexOf(c, i + 1);
+            if (close < 0)
+                return false;
+            word += command.slice(i + 1, close);
+            inWord = true;
+            i = close;
+            continue;
+        }
+        if (c === "\n" || c === "\r" || c === ";") {
+            endSegment();
+            continue;
+        }
+        if ((c === "&" || c === "|") && command[i + 1] === c) {
+            endSegment();
+            i += 1;
+            continue;
+        }
+        if (c === "|" || c === "{" || c === "}" || c === "(" || c === ")")
+            return false;
+        // `@` opens an array, a hash or a splat only at the start of a word; inside
+        // one (`…\node_modules\@basein\runner\…`) it is a plain character.
+        if (c === "@" && !inWord)
+            return false;
+        if (c === "&") {
+            // The call operator, as a word of its own at the start of a part; a
+            // redirection's `2>&1` keeps its `&` inside the word.
+            if (inWord && /\d?>$/.test(word)) {
+                word += c;
+                continue;
+            }
+            if (inWord || words.length > 0)
+                return false;
+            words.push("&");
+            continue;
+        }
+        if (c === " " || c === "\t") {
+            endWord();
+            continue;
+        }
+        word += c;
+        inWord = true;
+    }
+    endSegment();
+    let bir = false;
+    for (const raw of segments) {
+        const parts = raw[0] === "&" ? raw.slice(1) : raw;
+        if (parts.length === 0) {
+            if (raw.length > 0)
+                return false;
+            continue;
+        }
+        if (raw[0] !== "&" && /^(cd|chdir|sl|set-location|pushd|push-location)$/i.test(parts[0])) {
+            if (parts.length > 2 || parts.slice(1).some(isRedirect))
+                return false;
+            continue;
+        }
+        if (!isBirInvocation(parts.filter((w) => !isRedirect(w))))
+            return false;
+        bir = true;
+    }
+    return bir;
+}
+/**
+ * True when a shell command runs `bir` and nothing else: split on `&&`, `||`,
+ * `;`, `|`, `&` and newlines (outside quotes), every part is a `bir`
+ * invocation or a plain `cd <dir>`, and at least one is `bir`.
+ *
+ * A `bir` invocation is `bir` / `bir.cmd` / a path ending in `bir`, `bir.cmd`,
+ * `bir.js` or `bir.ps1`; `npx [-y] [-p @basein/runner…] [@basein/runner…] bir …`;
+ * or `node <path>/bir.js …` — each optionally after `NAME=value` assignments,
+ * which only set `bir`'s own environment. A heredoc is read as the data it is,
+ * because `bir scenario check … --input-logic - <<'EOF'` is the natural way to
+ * hand `bir` a logic body, and its lines are JavaScript, not commands.
+ *
+ * Anything that could run other code while looking like `bir` makes the answer
+ * false: a command substitution (`$(…)`, backticks) outside single quotes and
+ * quoted heredocs, and a subshell, group or process substitution (`(`, `{`).
+ * So does a quote or heredoc left open — a parse this side is not sure of is
+ * not one to hide a step on.
+ */
+export function isBirOnlyCommand(command) {
+    const segments = splitCommand(command);
+    if (!segments)
+        return false;
+    let bir = false;
+    for (const words of segments) {
+        if (words.length === 0)
+            continue;
+        if (isPlainCd(words))
+            continue;
+        if (!isBirInvocation(words))
+            return false;
+        bir = true;
+    }
+    return bir;
+}
+/**
+ * The command's parts, each as its words (quotes removed, as the shell would),
+ * or null when it cannot be read with confidence. Redirections stay words:
+ * `bir … < step.js` and `bir … > out.json 2>&1` are still only `bir`.
+ */
+function splitCommand(command) {
+    const n = command.length;
+    const segments = [];
+    const heredocs = [];
+    let words = [];
+    let word = "";
+    let inWord = false;
+    const endWord = () => {
+        if (inWord)
+            words.push(word);
+        word = "";
+        inWord = false;
+    };
+    const endSegment = () => {
+        endWord();
+        segments.push(words);
+        words = [];
+    };
+    for (let i = 0; i < n; i += 1) {
+        const c = command[i];
+        if (c === "'") {
+            const close = command.indexOf("'", i + 1);
+            if (close === -1)
+                return null;
+            word += command.slice(i + 1, close);
+            inWord = true;
+            i = close;
+        }
+        else if (c === '"') {
+            let j = i + 1;
+            for (; j < n && command[j] !== '"'; j += 1) {
+                const d = command[j];
+                if (d === "`" || (d === "$" && command[j + 1] === "("))
+                    return null;
+                if (d === "\\" && j + 1 < n) {
+                    j += 1;
+                    // Inside double quotes a backslash escapes only these; before anything else it stays.
+                    if (!'"\$`\n'.includes(command[j]))
+                        word += "\\";
+                }
+                word += command[j];
+            }
+            if (j >= n)
+                return null;
+            inWord = true;
+            i = j;
+        }
+        else if (c === "`" || (c === "$" && command[i + 1] === "(")) {
+            return null;
+        }
+        else if (c === "$" && command[i + 1] === "{") {
+            // `${NAME}` only reads a variable; a substitution inside it was refused above.
+            const close = command.indexOf("}", i + 2);
+            if (close === -1)
+                return null;
+            const inner = command.slice(i + 2, close);
+            if (/`|\$\(/.test(inner))
+                return null;
+            word += command.slice(i, close + 1);
+            inWord = true;
+            i = close;
+        }
+        else if (c === "\\") {
+            // A backslash-newline joins lines; any other escaped character is itself.
+            if (command[i + 1] === "\n") {
+                i += 1;
+            }
+            else if (command[i + 1] === "\r" && command[i + 2] === "\n") {
+                i += 2;
+            }
+            else if (i + 1 < n) {
+                word += command[i + 1];
+                inWord = true;
+                i += 1;
+            }
+        }
+        else if (c === "<" && command[i + 1] === "<" && command[i + 2] === "<") {
+            // A here-string: one word of data, read as the words that follow.
+            word += "<<<";
+            inWord = true;
+            i += 2;
+        }
+        else if (c === "<" && command[i + 1] === "<") {
+            endWord();
+            let j = i + 2;
+            const stripTabs = command[j] === "-";
+            if (stripTabs)
+                j += 1;
+            while (command[j] === " " || command[j] === "\t")
+                j += 1;
+            let delimiter = "";
+            let literal = false;
+            for (; j < n; j += 1) {
+                const d = command[j];
+                if (d === "'" || d === '"') {
+                    const close = command.indexOf(d, j + 1);
+                    if (close === -1)
+                        return null;
+                    delimiter += command.slice(j + 1, close);
+                    literal = true;
+                    j = close;
+                }
+                else if (d === "\\" && j + 1 < n) {
+                    delimiter += command[j + 1];
+                    literal = true;
+                    j += 1;
+                }
+                else if (/[\s;&|<>(){}]/.test(d)) {
+                    break;
+                }
+                else {
+                    delimiter += d;
+                }
+            }
+            if (!delimiter)
+                return null;
+            heredocs.push({ delimiter, literal, stripTabs });
+            words.push("<<", delimiter);
+            i = j - 1;
+        }
+        else if (c === "\n") {
+            endSegment();
+            // The bodies of the heredocs this line opened come next, in order.
+            while (heredocs.length > 0) {
+                const h = heredocs.shift();
+                let closed = false;
+                for (let pos = i + 1; pos <= n;) {
+                    let eol = command.indexOf("\n", pos);
+                    if (eol === -1)
+                        eol = n;
+                    let line = command.slice(pos, eol);
+                    if (line.endsWith("\r"))
+                        line = line.slice(0, -1);
+                    if ((h.stripTabs ? line.replace(/^\t+/, "") : line) === h.delimiter) {
+                        i = eol;
+                        closed = true;
+                        break;
+                    }
+                    if (!h.literal && /`|\$\(/.test(line))
+                        return null;
+                    pos = eol + 1;
+                }
+                if (!closed)
+                    return null;
+            }
+        }
+        else if (c === ";" || c === "|") {
+            endSegment();
+        }
+        else if (c === "&") {
+            // `2>&1` and `&>file` redirect; every other `&` ends a command.
+            if (command[i - 1] === ">" || command[i - 1] === "<" || command[i + 1] === ">") {
+                word += c;
+                inWord = true;
+            }
+            else {
+                endSegment();
+            }
+        }
+        else if (c === "(" || c === ")" || c === "{" || c === "}") {
+            // A subshell, a group or a process substitution: not something this reads.
+            return null;
+        }
+        else if (c === " " || c === "\t" || c === "\r") {
+            endWord();
+        }
+        else {
+            word += c;
+            inWord = true;
+        }
+    }
+    // A heredoc whose body never came.
+    if (heredocs.length > 0)
+        return null;
+    endSegment();
+    return segments;
+}
+/** `cd` or `cd <dir>`, and nothing more. */
+function isPlainCd(words) {
+    return words[0] === "cd" && words.length <= 2 && !words.slice(1).some(isRedirect);
+}
+const isRedirect = (w) => /^\d*[<>]|^&>/.test(w);
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+/** The last path component, on either separator. */
+const basename = (w) => w.slice(Math.max(w.lastIndexOf("/"), w.lastIndexOf("\\")) + 1);
+/** `bir`, `bir.cmd`, `bir.ps1`, or any path to one of those or to `bir.js`. */
+function isBirProgram(w) {
+    const base = basename(w);
+    if (/^bir(\.cmd|\.ps1)?$/i.test(base))
+        return true;
+    return /^bir\.js$/i.test(base) && base !== w;
+}
+const isNode = (w) => /^node(\.exe)?$/i.test(basename(w));
+/** `@basein/runner`, `@basein/runner@0.2.11`, `@basein/runner@latest`. */
+const isRunnerPackage = (w) => /^@basein\/runner(@[\w.+-]+)?$/.test(w);
+function isBirInvocation(input) {
+    let words = input;
+    while (words.length > 0 && ASSIGNMENT.test(words[0]))
+        words = words.slice(1);
+    const first = words[0];
+    if (first === undefined)
+        return false;
+    if (isBirProgram(first))
+        return true;
+    if (isNode(first)) {
+        // Exactly `node <path>/bir.js …`: a node flag could load other code first.
+        const script = words[1];
+        return script !== undefined && /^bir\.js$/i.test(basename(script));
+    }
+    if (first === "npx") {
+        let i = 1;
+        for (; i < words.length; i += 1) {
+            const w = words[i];
+            if (w === "-y" || w === "--yes")
+                continue;
+            if ((w === "-p" || w === "--package") && isRunnerPackage(words[i + 1] ?? "")) {
+                i += 1;
+                continue;
+            }
+            if (w.startsWith("--package=") && isRunnerPackage(w.slice("--package=".length)))
+                continue;
+            break;
+        }
+        if (isRunnerPackage(words[i] ?? ""))
+            i += 1;
+        return words[i] === "bir";
+    }
+    return false;
+}
 //# sourceMappingURL=housekeeping.js.map

package/dist/replay/controller.d.ts

@@ -299,7 +299,9 @@ export declare class ReplayController {
      * and hand it back through the best channel available; if even that fails,
      * abort to an ordinary turn.
      */
-    preTool(state: ReplayState, toolName: string, toolUseId: string): Promise<PreToolAction>;
+    preTool(state: ReplayState, toolName: string, toolUseId: string, 
+    /** The call's `tool_input`: whether a `Bash` call is only `bir` is read from it (D13). */
+    toolInput?: unknown): Promise<PreToolAction>;
     /**
      * `PostToolUse` for a call this plan pinned.
      *

package/dist/replay/controller.js

@@ -12,7 +12,7 @@
  * ignore. Nothing throws at a hook.
  */
 import { parseQualifiedName } from "../control/correlation.js";
-import { isHousekeeping } from "../record/housekeeping.js";
+import { isHousekeepingCall } from "../record/housekeeping.js";
 import { redact } from "../record/redact.js";
 import { serializeCapped } from "../record/truncate.js";
 import { logDetail, logLine, errText } from "../util/log.js";
@@ -392,7 +392,9 @@ export class ReplayController {
      * and hand it back through the best channel available; if even that fails,
      * abort to an ordinary turn.
      */
-    async preTool(state, toolName, toolUseId) {
+    async preTool(state, toolName, toolUseId, 
+    /** The call's `tool_input`: whether a `Bash` call is only `bir` is read from it (D13). */
+    toolInput) {
         const plan = state.plan;
         if (!plan || state.retired)
             return { kind: "passthrough" };
@@ -409,9 +411,21 @@ export class ReplayController {
                 error: errText(err),
             });
         }
+        // HOUSEKEEPING IS NOT DIVERGENCE. See `record/housekeeping.ts`. Asked
+        // before the pin, not after it: a `Bash` step is pinned by name, and a
+        // `bir scenario show` the model runs while a Bash step is expected must
+        // run as `bir`, never be swapped for the plan's command (D13).
+        const expected = plan.expectedTool();
+        if (isHousekeepingCall(toolName, toolInput)) {
+            logDetail("replay.housekeeping", {
+                tool: toolName,
+                step: `${plan.currentStepIndex}/${plan.stepCount}`,
+                why: "host bookkeeping, not task work — plan stays armed",
+            });
+            return { kind: "passthrough" };
+        }
         // A direct plan does not steer individual calls: the model was asked for one
         // tool call and made a different one. That is divergence.
-        const expected = plan.expectedTool();
         if (state.mode === "steer" && toolName === expected && toolUseId) {
             try {
                 const step = plan.currentStep();
@@ -460,15 +474,6 @@ export class ReplayController {
                 return { kind: "abort" };
             }
         }
-        // HOUSEKEEPING IS NOT DIVERGENCE. See `record/housekeeping.ts`.
-        if (isHousekeeping(toolName)) {
-            logDetail("replay.housekeeping", {
-                tool: toolName,
-                step: `${plan.currentStepIndex}/${plan.stepCount}`,
-                why: "host bookkeeping, not task work — plan stays armed",
-            });
-            return { kind: "passthrough" };
-        }
         return await this.diverge(state, toolName, `expected ${expected ?? "no more tools"}, model called ${toolName}`);
     }
     /**