@basein/runner 0.2.10 → 0.2.11

package/README.md

@@ -147,7 +147,9 @@ between the two is not guaranteed.
   section.
 - **Change what the model does.** Tool descriptions are never edited. The
   model-visible changes are schema relaxation, below, and — only with
-  `--replay` — one first-party tool.
+  `--replay` — the first-party `bir` server's tools: `run_scenario`, and three
+  that only read a scenario. The three that change one appear only after
+  `bir scenario editing on` in that project.
 
 ---
 
@@ -192,6 +194,25 @@ sequence runs through connections the proxies already hold — **zero model toke
 scenarios steer the live session instead, pinning each step's arguments. Either
 way the turn reports what it cost, so the savings ledger measures something real.
 
+**Fixing a step.** A calculated step is code, and code can be wrong.
+`bir investigate` names such a step; `bir scenario edit` fixes it, and the
+service checks the change against the recording before it saves it. **A change
+is saved only if it reproduces the recording — or on purpose, with
+`--force --note "why"`.** Only the owner can change a scenario. Claude can do it
+too: in its terminal, or with the `bir` server's tools once
+`bir scenario editing on` was run in the project. Built 2026-09-25, not yet
+released: it needs the next `@basein/runner` version and a service deploy. Step
+by step: [the guide's §9.2](docs/calculatedReplayGuide.md).
+
+```bash
+bir scenario show  scn_… --step 3                          # read one step
+bir scenario check scn_… --step 3 --input-logic step3.js   # try a change; nothing is saved
+bir scenario edit  scn_… --step 3 --input-logic step3.js --note "why"   # the same check, then save
+bir scenario edits scn_…                                   # the history
+bir scenario undo  scn_…                                   # undo the newest edit
+bir scenario editing on                                    # let Claude's `bir` tools change scenarios here
+```
+
 ---
 
 ## Two things to know before you turn it on

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.
  */

package/dist/bin/bir-scenario.js

@@ -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,12 +18,33 @@
  * 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.
  */
 import { readFrames, writeFrame } from "../jsonrpc/framing.js";
 import { JsonRpcErrorCode, errorResponse, isRequest, paramsObject, } from "../jsonrpc/types.js";
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
 import { resolveControl } from "../control/discovery.js";
+import { editingEnabled, nodeFlagsToCarry, readSidecar } from "../config/generate.js";
 import { logLine, logDetail, errText } from "../util/log.js";
 /** Must match `DIRECT_TOOL_NAME`'s suffix in the replay controller. */
 const TOOL_NAME = "run_scenario";
@@ -105,6 +127,337 @@ function toolResult(result) {
         isError: false,
     };
 }
+// ── the scenario tools: `bir scenario …`, spawned ─────────────────────────────
+/** How long one `bir` command may take. A check replays the chain on the service. */
+const BIR_TIMEOUT_MS = 120_000;
+class BadArguments extends Error {
+}
+const TARGET = {
+    type: "string",
+    description: "The scenario's scn_ id, or the run_ id of the recording it was calculated from — as investigate and scenario_show print them.",
+};
+const STEP = {
+    type: "integer",
+    minimum: 0,
+    description: "The step's stepIndex, as scenario_show prints it (the first step is 0).",
+};
+const INPUT_LOGIC = {
+    type: "string",
+    description: "The new input logic: the BODY of a JavaScript function of (parameters, intent, respParams) that ends in `return { … }` — the tool's input. Only JavaScript's built-ins exist when the service runs it.",
+};
+const OUTPUT_LOGIC = {
+    type: "string",
+    description: "The new output logic: the BODY of a JavaScript function of (toolOutput, parameters, intent, respParams) — toolOutput is the tool's answer as text — returning the values later steps read.",
+};
+/** A `run_`/`scn_` id: letters, digits, `_` and `-`, so it can never read as a flag. */
+function target(args) {
+    const value = args.target;
+    if (typeof value !== "string" || !/^(run|scn)_[\w-]+$/.test(value)) {
+        throw new BadArguments("`target` must be a scn_… or run_… id");
+    }
+    return value;
+}
+function step(args, required) {
+    const value = typeof args.step === "string" && /^\d+$/.test(args.step) ? Number(args.step) : args.step;
+    if (value === undefined || value === null) {
+        if (required)
+            throw new BadArguments("`step` is required: the stepIndex scenario_show prints");
+        return [];
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new BadArguments("`step` must be a whole number from 0");
+    }
+    return ["--step", String(value)];
+}
+function logic(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string")
+        throw new BadArguments(`\`${key}\` must be a string: a JavaScript function body`);
+    return value;
+}
+function flag(args, key, name) {
+    const value = args[key];
+    if (value === undefined || value === null || value === false)
+        return [];
+    if (value !== true)
+        throw new BadArguments(`\`${key}\` must be true or false`);
+    return [name];
+}
+const SCENARIO_TOOLS = [
+    {
+        name: "scenario_show",
+        changes: false,
+        description: "Read a calculated scenario of this account: the whole plan, or with `step` just that step — its input logic, " +
+            "output logic, whether it is marked *needs a judgement* (nondeterministic) and the recorded input and output " +
+            "it has to reproduce. Read a step here before changing it.",
+        inputSchema: {
+            type: "object",
+            properties: { target: TARGET, step: STEP },
+            required: ["target"],
+            additionalProperties: false,
+        },
+        plan: (a) => ({ argv: ["scenario", "show", target(a), ...step(a, false)] }),
+    },
+    {
+        name: "scenario_edits",
+        changes: false,
+        description: "List the hand edits of a calculated scenario, newest first: which step changed, the note, the revision, " +
+            "and whether it was saved on purpose (forced), undone, or replaced by a recalculation.",
+        inputSchema: {
+            type: "object",
+            properties: { target: TARGET },
+            required: ["target"],
+            additionalProperties: false,
+        },
+        plan: (a) => ({ argv: ["scenario", "edits", target(a)] }),
+    },
+    {
+        name: "investigate",
+        changes: false,
+        description: "Explain why a turn in this project did or did not replay its calculated scenario, what it cost and saved, " +
+            "and what to fix. Without `id`, the newest turn here; with a run_, scn_ or sexec_ id, that one. A finding " +
+            "that names a step can be read with scenario_show and, where editing is on, fixed with scenario_check and scenario_edit.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "A run_, scn_ or sexec_ id. Omit it for the newest turn in this project." },
+            },
+            additionalProperties: false,
+        },
+        plan: (a) => {
+            if (a.id === undefined || a.id === null || a.id === "")
+                return { argv: ["investigate"] };
+            if (typeof a.id !== "string" || !/^(run|scn|sexec)_[\w-]+$/.test(a.id)) {
+                throw new BadArguments("`id` must be a run_…, scn_… or sexec_… id");
+            }
+            return { argv: ["investigate", a.id] };
+        },
+    },
+    {
+        name: "scenario_check",
+        changes: true,
+        description: "Try a change to one step of a calculated scenario without saving anything: the service runs the new " +
+            "`inputLogic` and/or `outputLogic` with the recording's values and reports whether this step and every later " +
+            "step still reproduce the recorded calls, and what happens to the step's *needs a judgement* mark. The workflow " +
+            "is scenario_show → scenario_check until it passes → scenario_edit with the same change and a `note` saying why. " +
+            "A failing check means the code is wrong, not that the check is in the way: fix the code.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                target: TARGET,
+                step: STEP,
+                inputLogic: INPUT_LOGIC,
+                outputLogic: OUTPUT_LOGIC,
+                unfreeze: { type: "boolean", description: "Ask whether the *needs a judgement* mark could be removed." },
+            },
+            required: ["target", "step"],
+            additionalProperties: false,
+        },
+        plan: (a) => ({
+            argv: ["scenario", "check", target(a), ...step(a, true), ...flag(a, "unfreeze", "--unfreeze")],
+            inputLogic: logic(a, "inputLogic"),
+            outputLogic: logic(a, "outputLogic"),
+        }),
+    },
+    {
+        name: "scenario_edit",
+        changes: true,
+        description: "Save a change to one step of a calculated scenario. It runs the same check as scenario_check and saves only " +
+            "if the step reproduces the recording and is not a copy of the recorded call; always give a `note` saying why, " +
+            "and `revision` (the chainRevision scenario_show printed) so a plan that changed meanwhile is not overwritten. " +
+            "`force` saves what the check refused and is only for a recording that was itself wrong — never a way past a " +
+            "failing check. Every save can be undone with scenario_undo.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                target: TARGET,
+                step: STEP,
+                inputLogic: INPUT_LOGIC,
+                outputLogic: OUTPUT_LOGIC,
+                freeze: {
+                    type: "boolean",
+                    description: "Mark the step *needs a judgement*: runs then hand over to the agent in front of it.",
+                },
+                unfreeze: { type: "boolean", description: "Remove that mark, if the check says the step reproduces." },
+                force: {
+                    type: "boolean",
+                    description: "Save although the check refused it. Needs `note`. Only when the recording itself was wrong.",
+                },
+                note: { type: "string", description: "Why the step is changed; kept in the history. Required with `force`." },
+                revision: {
+                    type: "integer",
+                    minimum: 1,
+                    description: "The chainRevision the change was made against; the save is refused if the plan moved on.",
+                },
+            },
+            required: ["target", "step"],
+            additionalProperties: false,
+        },
+        plan: (a) => {
+            if (a.freeze === true && a.unfreeze === true)
+                throw new BadArguments("`freeze` and `unfreeze` ask for opposite things");
+            const argv = [
+                "scenario",
+                "edit",
+                target(a),
+                ...step(a, true),
+                ...flag(a, "freeze", "--freeze"),
+                ...flag(a, "unfreeze", "--unfreeze"),
+                ...flag(a, "force", "--force"),
+            ];
+            if (a.note !== undefined && a.note !== null) {
+                if (typeof a.note !== "string")
+                    throw new BadArguments("`note` must be a string");
+                argv.push("--note", a.note);
+            }
+            if (a.revision !== undefined && a.revision !== null) {
+                if (typeof a.revision !== "number" || !Number.isInteger(a.revision) || a.revision < 1) {
+                    throw new BadArguments("`revision` must be a whole number from 1");
+                }
+                argv.push("--revision", String(a.revision));
+            }
+            return { argv, inputLogic: logic(a, "inputLogic"), outputLogic: logic(a, "outputLogic") };
+        },
+    },
+    {
+        name: "scenario_undo",
+        changes: true,
+        description: "Put one step of a calculated scenario back as it was before its newest hand edit — without `edit`, the newest " +
+            "edit that can be undone. The undo is itself an edit, so undoing it again redoes the change.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                target: TARGET,
+                edit: { type: "string", description: "The sedit_ id to undo, as scenario_edits lists it." },
+            },
+            required: ["target"],
+            additionalProperties: false,
+        },
+        plan: (a) => {
+            const argv = ["scenario", "undo", target(a)];
+            if (a.edit !== undefined && a.edit !== null) {
+                if (typeof a.edit !== "string" || !/^sedit_[\w-]+$/.test(a.edit)) {
+                    throw new BadArguments("`edit` must be a sedit_… id");
+                }
+                argv.push("--edit", a.edit);
+            }
+            return { argv };
+        },
+    },
+];
+/** Whether this project may be offered the tools that change a scenario. Never throws. */
+function editingOn(cwd) {
+    try {
+        return editingEnabled(readSidecar(), cwd);
+    }
+    catch {
+        return false;
+    }
+}
+/** The tools to list for `cwd`, read now: the switch may have moved since the last list. */
+function listTools(cwd) {
+    const editing = editingOn(cwd);
+    return [
+        TOOL,
+        ...SCENARIO_TOOLS.filter((t) => !t.changes || editing).map(({ name, description, inputSchema }) => ({
+            name,
+            description,
+            inputSchema,
+        })),
+    ];
+}
+/** This package's own `bir`, beside this file — never whatever `bir` is first on PATH. */
+function birPath() {
+    return resolvePath(dirname(fileURLToPath(import.meta.url)), "bir.js");
+}
+function runBir(argv, cwd) {
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, [...nodeFlagsToCarry(), birPath(), ...argv], {
+            cwd,
+            env: process.env,
+            // Nothing is ever read from stdin: logic arrives as files.
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (c) => {
+            stdout += c;
+        });
+        child.stderr.on("data", (c) => {
+            stderr += c;
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill();
+        }, BIR_TIMEOUT_MS);
+        timer.unref?.();
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            resolve({ code: null, stdout, stderr: `${stderr}${errText(err)}`, timedOut });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({ code, stdout, stderr, timedOut });
+        });
+    });
+}
+const failed = (text) => ({ content: [{ type: "text", text }], isError: true });
+/**
+ * Run one scenario tool. Never throws. The logic bodies are written to a
+ * directory of their own under the OS temp directory, owner-only, and the
+ * directory is removed whatever happens — the code may carry a table name or a
+ * host the person would not want left lying around.
+ */
+async function callScenarioTool(tool, args, cwd) {
+    let plan;
+    try {
+        plan = tool.plan(args);
+    }
+    catch (err) {
+        return failed(`invalid arguments for ${tool.name}: ${errText(err)}`);
+    }
+    let dir;
+    try {
+        const argv = [...plan.argv];
+        if (plan.inputLogic !== undefined || plan.outputLogic !== undefined) {
+            dir = mkdtempSync(join(tmpdir(), "bir-logic-"));
+            if (plan.inputLogic !== undefined) {
+                const file = join(dir, "input.js");
+                writeFileSync(file, plan.inputLogic, { encoding: "utf8", mode: 0o600 });
+                argv.push("--input-logic", file);
+            }
+            if (plan.outputLogic !== undefined) {
+                const file = join(dir, "output.js");
+                writeFileSync(file, plan.outputLogic, { encoding: "utf8", mode: 0o600 });
+                argv.push("--output-logic", file);
+            }
+        }
+        argv.push("--json");
+        const run = await runBir(argv, cwd);
+        if (run.timedOut)
+            return failed(`bir did not finish in ${BIR_TIMEOUT_MS / 1000} s`);
+        const stdout = run.stdout.trim();
+        if (run.code === 0)
+            return { content: [{ type: "text", text: stdout || "(no output)" }], isError: false };
+        // The refusal and its report are on stdout; why bir itself failed, if it
+        // did (not signed in, no service address), is on stderr. The model needs both.
+        const text = [stdout, run.stderr.trim()].filter(Boolean).join("\n");
+        return failed(text || `bir exited with code ${run.code ?? "?"}`);
+    }
+    catch (err) {
+        return failed(`could not run bir: ${errText(err)}`);
+    }
+    finally {
+        if (dir)
+            rmSync(dir, { recursive: true, force: true });
+    }
+}
 function main() {
     const cwd = process.cwd();
     let closing = false;
@@ -130,7 +483,7 @@ function main() {
                 return;
             }
             if (method === "tools/list") {
-                reply({ jsonrpc: "2.0", id, result: { tools: [TOOL] } });
+                reply({ jsonrpc: "2.0", id, result: { tools: listTools(cwd) } });
                 return;
             }
             if (method === "ping") {
@@ -139,7 +492,24 @@ function main() {
             }
             if (method === "tools/call") {
                 const params = paramsObject(msg.params);
-                if (String(params.name ?? "") !== TOOL_NAME) {
+                const name = String(params.name ?? "");
+                const scenarioTool = SCENARIO_TOOLS.find((t) => t.name === name);
+                if (scenarioTool) {
+                    // Asked again, not remembered from tools/list: a host may call a tool
+                    // it listed before the switch went off, or one it was never offered.
+                    if (scenarioTool.changes && !editingOn(cwd)) {
+                        reply(errorResponse(id, JsonRpcErrorCode.MethodNotFound, `${name} is not offered in this project: scenario editing is off. ` +
+                            "A person turns it on with `bir scenario editing on` in this directory, then restarts the session."));
+                        return;
+                    }
+                    logDetail("scenario.tool", { cwd, tool: name });
+                    void callScenarioTool(scenarioTool, paramsObject(params.arguments), cwd).then((result) => {
+                        logLine("scenario.tool_answered", { tool: name, isError: result.isError === true });
+                        reply({ jsonrpc: "2.0", id, result });
+                    });
+                    return;
+                }
+                if (name !== TOOL_NAME) {
                     reply(errorResponse(id, JsonRpcErrorCode.MethodNotFound, `unknown tool: ${params.name}`));
                     return;
                 }

package/dist/bin/bir.d.ts

@@ -12,6 +12,16 @@
  *   bir login | logout
  *   bir --version
  *
+ *   bir scenario list | show <runId|scnId> [--step <n>] | calc <runId> [--force [--discard-edits]]
+ *   bir scenario check|edit <runId|scnId> --step <n> --input-logic <file|-> …   ← fix one step
+ *   bir scenario edits | undo <runId|scnId> [--edit <sedit_id>]
+ *   bir scenario editing on|off|status   ← may this project's `bir` MCP server change a scenario?
+ *   bir scenario replay <scnId> --prompt "…" [--dry]  |  bir replay status|on|off|allow …
+ *   bir investigate [<id>] | list | executions
+ *
+ * The `scenario` words that read or change one step live in scenario-edit.ts
+ * (editSteps.md in the BaseIn repository); `investigate` in investigate.ts.
+ *
  * `bir install` is reversible by construction: every file it edits is stashed
  * verbatim first, so `bir uninstall` restores it byte-for-byte unless somebody
  * else edited it in the meantime (in which case it repairs the entries and says