@basein/runner 0.3.17 → 0.3.18

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

@@ -68,7 +68,11 @@
  * WHICH TOOLS ARE OFFERED. `run_scenario`, always — unless the runner is
  * switched off (`bir off`), when nothing is: an inert runner adds nothing to
  * the model's context, and a call from a list taken before the switch starts
- * nothing and asks nobody. The rest come with scenario editing, which
+ * nothing and asks nobody. `report_wrong_result` comes with it: the agent that
+ * reads a replay's results is the one who can tell they do not answer the
+ * request, and says so in one call that holds the plan and undoes nothing
+ * (the service's review of calcscenarioautocorrect.md, item 19); the control
+ * server knows which session asks, and so which plan. The rest come with scenario editing, which
  * `bir setup` turns on (a person's `bir scenario editing off` is kept): the
  * reading tools — also with `BIR_SCENARIO_TOOLS=read` in this server's
  * environment — and the tools that CHANGE a scenario (D2). A project wired by

package/dist/bin/bir-scenario.js

@@ -68,7 +68,11 @@
  * WHICH TOOLS ARE OFFERED. `run_scenario`, always — unless the runner is
  * switched off (`bir off`), when nothing is: an inert runner adds nothing to
  * the model's context, and a call from a list taken before the switch starts
- * nothing and asks nobody. The rest come with scenario editing, which
+ * nothing and asks nobody. `report_wrong_result` comes with it: the agent that
+ * reads a replay's results is the one who can tell they do not answer the
+ * request, and says so in one call that holds the plan and undoes nothing
+ * (the service's review of calcscenarioautocorrect.md, item 19); the control
+ * server knows which session asks, and so which plan. The rest come with scenario editing, which
  * `bir setup` turns on (a person's `bir scenario editing off` is kept): the
  * reading tools — also with `BIR_SCENARIO_TOOLS=read` in this server's
  * environment — and the tools that CHANGE a scenario (D2). A project wired by
@@ -184,6 +188,39 @@ const TOOL = {
         "never otherwise.",
     inputSchema: { type: "object", properties: {}, additionalProperties: false },
 };
+/**
+ * The agent's way to say a replay was wrong (the service's review of
+ * calcscenarioautocorrect.md, item 19). A plan that took the wrong half of an
+ * "if … otherwise" was caught only when the agent said so in its answer, or
+ * did the task again — and the results it was handed told it not to check.
+ * Offered wherever `run_scenario` is: the agent that reads a replay's results
+ * is the one who can tell they are wrong. It holds the plan on the service and
+ * undoes nothing. Must match `REPORT_TOOL_NAME`'s suffix in the replay
+ * controller.
+ */
+const REPORT_TOOL_NAME = "report_wrong_result";
+/** What the agent may say, in characters; the control server and the service cut it there too. */
+const REPORT_REASON_MAX = 2_000;
+/** The whole report's request: the control server waits up to 10 s for the service. */
+const REPORT_TIMEOUT_MS = 15_000;
+const REPORT_TOOL = {
+    name: REPORT_TOOL_NAME,
+    description: "Call this when the results of a replayed scenario (run_scenario, or a plan bir ran for you) do not answer " +
+        "the user's request — for example, the wrong branch of an if/otherwise was taken, or the wrong item was acted " +
+        "on. Say why in one or two sentences. It does not undo anything.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            reason: {
+                type: "string",
+                maxLength: REPORT_REASON_MAX,
+                description: "Why the results do not answer the request, in one or two sentences.",
+            },
+        },
+        required: ["reason"],
+        additionalProperties: false,
+    },
+};
 /**
  * Ask the control server to run the armed plan. Never throws. The reasons it
  * returns are for the audit log; {@link toolResult} decides what the model reads.
@@ -213,8 +250,14 @@ async function runArmedPlan(cwd, flight, toolUseId) {
                 "content-type": "application/json",
                 authorization: `Bearer ${found.token}`,
             },
-            // `ppid`: the host that started this server and the session's proxies (WHOSE PROXIES above).
-            body: JSON.stringify(toolUseId ? { toolUseId, ppid: process.ppid } : { ppid: process.ppid }),
+            // `ppid`: the host that started this server and the session's proxies
+            // (WHOSE PROXIES above). `reports`: this server offers
+            // `report_wrong_result`, so the results may say the agent can use it.
+            body: JSON.stringify({
+                ...(toolUseId ? { toolUseId } : {}),
+                ppid: process.ppid,
+                reports: listTools(cwd).some((t) => t.name === REPORT_TOOL_NAME),
+            }),
             signal: controller.signal,
         });
         const raw = await res.text();
@@ -333,6 +376,60 @@ function toolResult(result) {
         return said(ALREADY_RUNNING_TEXT);
     return said(UNAVAILABLE_TEXT);
 }
+/**
+ * Tell the control server the agent said a replay was wrong (review item 19):
+ * it knows the session — by the host's id for this call, as for
+ * `run_scenario` — and so the plan, and it reports it to the service. Never
+ * throws; every failure is an answer.
+ */
+async function reportWrongResult(cwd, flight, reason, toolUseId) {
+    const found = await resolveControl(cwd, DISCOVERY_GRACE_MS, 50);
+    if (!found?.url || !found.token)
+        return { ok: false, why: "no_plan" };
+    if (flight.cancelled)
+        return { ok: false, why: "cancelled" };
+    const controller = new AbortController();
+    flight.abort = controller;
+    const timer = setTimeout(() => controller.abort(), REPORT_TIMEOUT_MS);
+    timer.unref?.();
+    try {
+        const res = await fetch(`${found.url.replace(/\/+$/, "")}/scenario/dispute`, {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: `Bearer ${found.token}` },
+            body: JSON.stringify({ reason, ...(toolUseId ? { toolUseId } : {}), ppid: process.ppid }),
+            signal: controller.signal,
+        });
+        const raw = await res.text();
+        // An older recorder has no such route (404): it cannot take the report.
+        if (!res.ok)
+            return { ok: false, why: res.status === 404 ? "unsupported" : `HTTP ${res.status}` };
+        const body = JSON.parse(raw);
+        return body && typeof body === "object" && !Array.isArray(body) ? body : { ok: false };
+    }
+    catch (err) {
+        return { ok: false, why: flight.cancelled ? "cancelled" : errText(err) };
+    }
+    finally {
+        clearTimeout(timer);
+        flight.abort = undefined;
+    }
+}
+/**
+ * The one sentence the agent reads back. Never an error: the report is a side
+ * note to its answer, and whatever happened to it, the agent's next move is to
+ * tell the user.
+ */
+function reportAnswer(result) {
+    if (result.ok === true) {
+        return said(result.held === true
+            ? "Reported. bir will not use this plan again until it is checked."
+            : "Reported. Now tell the user what is wrong with these results.");
+    }
+    if (result.why === "no_plan") {
+        return said("Nothing was reported: no scenario was replayed for this session's latest request.");
+    }
+    return said("The report could not be sent right now. Tell the user what is wrong with these results.");
+}
 // ── the scenario tools: `bir scenario …`, spawned ─────────────────────────────
 /** How long a `bir` that may change a scenario may take. A check replays the chain on the service. */
 const BIR_TIMEOUT_MS = 120_000;
@@ -720,7 +817,11 @@ function readToolsOptedIn() {
     const value = (process.env.BIR_SCENARIO_TOOLS ?? "").trim().toLowerCase();
     return value === "read" || value === "1" || value === "on" || value === "true";
 }
-/** The tools to list for `cwd`, read now: the switches may have moved since the last list. */
+/**
+ * The tools to list for `cwd`, read now: the switches may have moved since the
+ * last list. `report_wrong_result` comes with `run_scenario`, editing on or off:
+ * whoever reads a replay's results may need to say they are wrong.
+ */
 function listTools(cwd) {
     if (runnerOff(cwd))
         return [];
@@ -728,6 +829,7 @@ function listTools(cwd) {
     const reading = editing || readToolsOptedIn();
     return [
         TOOL,
+        REPORT_TOOL,
         ...SCENARIO_TOOLS.filter((t) => (t.changes ? editing : reading)).map(({ name, description, inputSchema }) => ({
             name,
             description,
@@ -968,7 +1070,8 @@ function main() {
         cwd,
         state: () => {
             const off = runnerOff(cwd);
-            return { tools: off ? 0 : listTools(cwd).length, off };
+            const tools = off ? [] : listTools(cwd);
+            return { tools: tools.length, off, report: tools.some((t) => t.name === REPORT_TOOL_NAME) };
         },
     });
     /**
@@ -1035,6 +1138,27 @@ function main() {
         }
         reply({ jsonrpc: "2.0", id, result: answer });
     };
+    /** `report_wrong_result`: tell the control server, and answer exactly once — unless cancelled. */
+    const answerReport = async (id, flight, reason, toolUseId) => {
+        let result;
+        try {
+            result = await reportWrongResult(cwd, flight, reason, toolUseId);
+        }
+        catch (err) {
+            result = { ok: false, why: errText(err) };
+        }
+        if (inFlight.get(id) === flight)
+            inFlight.delete(id);
+        if (flight.cancelled || closing)
+            return;
+        logLine("scenario.reported", {
+            ok: result.ok === true,
+            held: result.held === true || undefined,
+            why: typeof result.why === "string" ? result.why.slice(0, 200) : undefined,
+            bound: toolUseId !== undefined || undefined,
+        });
+        reply({ jsonrpc: "2.0", id, result: reportAnswer(result) });
+    };
     /** A scenario tool: run `bir`, and answer exactly once — unless cancelled. */
     const answerTool = async (id, tool, args, flight) => {
         let result;
@@ -1136,6 +1260,32 @@ function main() {
                     void answerTool(id, scenarioTool, paramsObject(params.arguments), flight);
                     return;
                 }
+                if (name === REPORT_TOOL_NAME) {
+                    // Off: nothing ran a plan, so there is nothing to report — said
+                    // plainly, as the reading tools say it.
+                    if (runnerOff(cwd)) {
+                        logLine("scenario.reported", { ok: false, why: "runner is off" });
+                        reply({
+                            jsonrpc: "2.0",
+                            id,
+                            result: said("BaseInstRunner is switched off here, so there is nothing to report."),
+                        });
+                        return;
+                    }
+                    const reason = paramsObject(params.arguments).reason;
+                    if (typeof reason !== "string" || reason.trim() === "") {
+                        reply({
+                            jsonrpc: "2.0",
+                            id,
+                            result: { content: [{ type: "text", text: "`reason` is required: say in a sentence or two why the results are wrong." }], isError: true },
+                        });
+                        return;
+                    }
+                    const flight = { tool: REPORT_TOOL_NAME, cancelled: false };
+                    inFlight.set(id, flight);
+                    void answerReport(id, flight, reason.trim().slice(0, REPORT_REASON_MAX), toolUseIdOf(params));
+                    return;
+                }
                 if (name !== TOOL_NAME) {
                     reply(errorResponse(id, JsonRpcErrorCode.MethodNotFound, `unknown tool: ${params.name}`));
                     return;

package/dist/bin/bir.js

@@ -3269,8 +3269,8 @@ async function doctor(args) {
     // lets Claude Code run them without asking; said only when that is not so.
     if (scenarioEntry && isScenarioServer(scenarioEntry.config)) {
         if (!editingEnabled(sidecar, cwd)) {
-            notes.push("the bir MCP server offers run_scenario only: scenario editing is off here — `bir scenario editing on` " +
-                "adds investigate and the scenario tools (restart Claude Code after)");
+            notes.push("the bir MCP server offers run_scenario and report_wrong_result only: scenario editing is off here — " +
+                "`bir scenario editing on` adds investigate and the scenario tools (restart Claude Code after)");
         }
         else if (![claudeUserSettingsPath(), paths.settings, paths.settingsLocal].some((file) => allowRules(file).some((rule) => rule === BIR_TOOLS_RULE || rule === `${BIR_TOOLS_RULE}__*`))) {
             notes.push("Claude Code asks before investigate and the scenario tools run here — `bir setup` allows every bir tool " +

package/dist/bin/scenario-edit.d.ts

@@ -222,6 +222,13 @@ export declare const SCENARIO_EDIT_SUBCOMMANDS: ReadonlySet<string>;
 export declare const READ_TOOLS: readonly ["scenario_show", "scenario_edits", "investigate"];
 /** The ones that change a scenario: offered only after `bir scenario editing on` (D2). */
 export declare const EDIT_TOOLS: readonly ["scenario_check", "scenario_edit", "scenario_undo"];
+/**
+ * The ones every session with the `bir` server has, editing on or off: the
+ * delivery of a direct plan, and the agent's way to say a replay's results do
+ * not answer the request (the service's review of calcscenarioautocorrect.md,
+ * item 19). `bir setup`'s allow rule, `mcp__bir`, covers every one.
+ */
+export declare const BASE_TOOLS: readonly ["run_scenario", "report_wrong_result"];
 export declare function scenarioEditCommand(args: ScenarioEditArgs, deps: ScenarioEditDeps): Promise<number>;
 /**
  * A logic file's text. UTF-8, with a byte-order mark dropped — and UTF-16 with

package/dist/bin/scenario-edit.js

@@ -59,6 +59,13 @@ export const SCENARIO_EDIT_SUBCOMMANDS = new Set([
 export const READ_TOOLS = ["scenario_show", "scenario_edits", "investigate"];
 /** The ones that change a scenario: offered only after `bir scenario editing on` (D2). */
 export const EDIT_TOOLS = ["scenario_check", "scenario_edit", "scenario_undo"];
+/**
+ * The ones every session with the `bir` server has, editing on or off: the
+ * delivery of a direct plan, and the agent's way to say a replay's results do
+ * not answer the request (the service's review of calcscenarioautocorrect.md,
+ * item 19). `bir setup`'s allow rule, `mcp__bir`, covers every one.
+ */
+export const BASE_TOOLS = ["run_scenario", "report_wrong_result"];
 const USAGE = {
     show: "usage: bir scenario show <runId|scnId> [--step <n>]",
     check: "usage: bir scenario check <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->] [--unfreeze] [--json]",
@@ -1067,11 +1074,11 @@ function describeEditing(out, sidecar, cwd) {
     // working on a scenario, and every other session would pay for their
     // definitions on every request without ever calling them.
     if (on) {
-        out(`  the bir MCP server offers  run_scenario, ${READ_TOOLS.join(", ")}  (they read)`);
+        out(`  the bir MCP server offers  ${[...BASE_TOOLS, ...READ_TOOLS].join(", ")}  (they read)`);
         out(`                        and  ${EDIT_TOOLS.join(", ")}  (they change a scenario)`);
     }
     else {
-        out("  the bir MCP server offers  run_scenario");
+        out(`  the bir MCP server offers  ${BASE_TOOLS.join(", ")}`);
         out(`  \`bir scenario editing on\` adds ${EDIT_TOOLS.join(", ")}  (they change a scenario)`);
         out(`                        and  ${READ_TOOLS.join(", ")}  (they read)`);
         out("  (BIR_SCENARIO_TOOLS=read in the server's environment offers the reading ones alone)");

package/dist/bin/scenario-liveness.d.ts

@@ -75,6 +75,13 @@ export interface HelloBody {
     /** How many tools this server lists now (0 when off). */
     tools: number;
     off: boolean;
+    /**
+     * It lists `report_wrong_result` (runner 0.3.18 on; the service's review of
+     * calcscenarioautocorrect.md, item 19): a replay's results may then tell the
+     * agent it can say they are wrong. Sent only when true; an older recorder
+     * ignores it.
+     */
+    report?: boolean;
 }
 /** A discovery record as written, its pid not yet checked. */
 export interface RecorderRecord {
@@ -100,10 +107,14 @@ export declare function launchRevive(cwd: string): Promise<void>;
 export interface LivenessOptions {
     /** The project this server runs for. */
     cwd: string;
-    /** What this server lists now. Called for every hello. */
+    /**
+     * What this server lists now. Called for every hello. `report`: the list
+     * holds `report_wrong_result` (review item 19).
+     */
     state: () => {
         tools: number;
         off: boolean;
+        report?: boolean;
     };
     now?: () => number;
     random?: () => number;

package/dist/bin/scenario-liveness.js

@@ -314,10 +314,14 @@ export class ScenarioLiveness {
     state() {
         try {
             const s = this.opts.state();
-            return { tools: Number.isInteger(s.tools) && s.tools >= 0 ? s.tools : 0, off: s.off === true };
+            return {
+                tools: Number.isInteger(s.tools) && s.tools >= 0 ? s.tools : 0,
+                off: s.off === true,
+                report: s.report === true && s.off !== true,
+            };
         }
         catch {
-            return { tools: 0, off: false };
+            return { tools: 0, off: false, report: false };
         }
     }
     async sendHello(why) {
@@ -330,8 +334,8 @@ export class ScenarioLiveness {
             const target = this.target();
             if (!target)
                 return;
-            const { tools, off } = this.state();
-            const body = { pid: process.pid, version: packageVersion(), tools, off };
+            const { tools, off, report } = this.state();
+            const body = { pid: process.pid, version: packageVersion(), tools, off, ...(report ? { report } : {}) };
             this.tried = target.identity;
             this.lastHelloAt = this.now();
             let reach;

package/dist/bin/setup.js

@@ -43,7 +43,7 @@ import { normalizePath } from "../control/paths.js";
 import { allowRules, BIR_TOOLS_RULE, claudeCodePaths, claudeCodeSetUp } from "../config/adapters/claude-code.js";
 import { allocateReplacementPort, editingEnabled, isScenarioServer, isWrapped, LOOPBACK_NO_PROXY, probeFreePort, proxyConfigured, projectRecord, readSidecar, SCENARIO_SERVER_KEY, setProjectRecord, settleReplaySwitch, writeSidecar, allocateFreeProjectPort, } from "../config/generate.js";
 import { resolveServers } from "../config/resolve.js";
-import { EDIT_TOOLS, READ_TOOLS } from "./scenario-edit.js";
+import { BASE_TOOLS, EDIT_TOOLS, READ_TOOLS } from "./scenario-edit.js";
 import { errText } from "../util/log.js";
 import { offSource } from "../util/off-switch.js";
 import { packageVersion } from "../util/version.js";
@@ -508,8 +508,8 @@ export async function runSetup(args, deps) {
     if (resolveServers(project).some((s) => s.name === SCENARIO_SERVER_KEY && isScenarioServer(s.config))) {
         const asks = !allowRules(claudeCodePaths(project).settingsLocal).includes(BIR_TOOLS_RULE);
         out(editingEnabled(readSidecar(), project)
-            ? `  tools      ${["run_scenario", ...READ_TOOLS, ...EDIT_TOOLS].join(", ")} — ${asks ? "Claude Code asks before each" : "Claude Code runs them without asking, except a forced change"}`
-            : "  tools      run_scenario only — scenario editing is off here (`bir scenario editing on` adds investigate and the scenario tools)");
+            ? `  tools      ${[...BASE_TOOLS, ...READ_TOOLS, ...EDIT_TOOLS].join(", ")} — ${asks ? "Claude Code asks before each" : "Claude Code runs them without asking, except a forced change"}`
+            : `  tools      ${BASE_TOOLS.join(" and ")} only — scenario editing is off here (\`bir scenario editing on\` adds investigate and the scenario tools)`);
     }
     if (ensured) {
         const { info, health: h } = ensured.status;

package/dist/control/client.d.ts

@@ -68,6 +68,11 @@ export declare class ControlClient {
     }): Promise<RegisterResult | undefined>;
     /** Report one completed MCP call. Resolves false when the send was dropped. */
     report(step: ProxyStepReport): Promise<boolean>;
+    /**
+     * The tool list of the server this proxy wraps, as it answered `tools/list`
+     * (the service's autocorrect.md AC12). Resolves false when the send was dropped.
+     */
+    tools(serverName: string, tools: readonly unknown[]): Promise<boolean>;
     health(): Promise<Record<string, unknown> | undefined>;
     /**
      * Ask the control server to shut down. Resolves true when it agreed; the

package/dist/control/client.js

@@ -26,6 +26,13 @@ export class ControlClient {
         const body = this.identity ? { ...step, proxyId: this.identity.proxyId } : step;
         return (await this.post("/proxy/step", body)) !== undefined;
     }
+    /**
+     * The tool list of the server this proxy wraps, as it answered `tools/list`
+     * (the service's autocorrect.md AC12). Resolves false when the send was dropped.
+     */
+    async tools(serverName, tools) {
+        return (await this.post("/proxy/tools", { ...this.identity, serverName, tools })) !== undefined;
+    }
     async health() {
         return (await this.request("GET", "/health"));
     }

package/dist/control/ensure-hook.d.ts

@@ -49,9 +49,14 @@
  * only with enough of the budget left.
  *
  * STDOUT IS CONTEXT. For SessionStart, Claude Code adds whatever a command hook
- * prints on stdout to the model's context. So nothing is printed unless the
- * control server answered with something (today it answers `{}`), and then it
- * is the answer, verbatim, as JSON.
+ * prints on stdout to the model's context — unless it is one JSON object, which
+ * it reads as the hook's answer instead. So nothing is printed unless the
+ * control server answered with something, and then it is the answer, as one
+ * line of JSON and nothing else. The control server answers `{}`, or — when
+ * plans of the account wait for their owner (the service's review of
+ * calcscenarioautocorrect.md, item 8) — `{ "systemMessage": "bir: …" }`, a
+ * line Claude Code shows the person and never the model. Characters past ASCII
+ * are written as `\u` escapes, so a console code page cannot garble the line.
  */
 import { type EnsureOptions } from "./daemon.js";
 /**
@@ -93,6 +98,12 @@ export interface EnsureHookOptions extends EnsureOptions {
      */
     overrideCheck?: ((projectCwd: string) => StaleOverrides) | false;
 }
+/**
+ * `value` as one line of JSON whose every character past ASCII is a `\u`
+ * escape: the same JSON to any reader, and nothing a console's code page can
+ * turn into something else on the way to Claude Code.
+ */
+export declare function asciiJson(value: unknown): string;
 /**
  * Run the hook for `cwd`. Resolves the exit code, which is always 0.
  */

package/dist/control/ensure-hook.js

@@ -49,9 +49,14 @@
  * only with enough of the budget left.
  *
  * STDOUT IS CONTEXT. For SessionStart, Claude Code adds whatever a command hook
- * prints on stdout to the model's context. So nothing is printed unless the
- * control server answered with something (today it answers `{}`), and then it
- * is the answer, verbatim, as JSON.
+ * prints on stdout to the model's context — unless it is one JSON object, which
+ * it reads as the hook's answer instead. So nothing is printed unless the
+ * control server answered with something, and then it is the answer, as one
+ * line of JSON and nothing else. The control server answers `{}`, or — when
+ * plans of the account wait for their owner (the service's review of
+ * calcscenarioautocorrect.md, item 8) — `{ "systemMessage": "bir: …" }`, a
+ * line Claude Code shows the person and never the model. Characters past ASCII
+ * are written as `\u` escapes, so a console code page cannot garble the line.
  */
 import { appendFileSync } from "node:fs";
 import { Console } from "node:console";
@@ -152,6 +157,14 @@ function reportStaleOverrides(projectCwd, logFile, msLeft, check) {
         /* a check that failed leaves things as they were; `bir doctor` names what is stale */
     }
 }
+/**
+ * `value` as one line of JSON whose every character past ASCII is a `\u`
+ * escape: the same JSON to any reader, and nothing a console's code page can
+ * turn into something else on the way to Claude Code.
+ */
+export function asciiJson(value) {
+    return JSON.stringify(value).replace(/[\u007f-￿]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
 /** True when this process's own environment switches the runner off (`BIR_OFF=1` or `true`). */
 function offInThisEnvironment() {
     const value = (process.env.BIR_OFF ?? "").trim().toLowerCase();
@@ -228,8 +241,8 @@ export async function runEnsureHook(cwd, opts = {}) {
             signal: timeoutSignal(Math.max(300, Math.min(RELAY_TIMEOUT_MS, left()))),
         });
         const answer = (await res.json().catch(() => ({})));
-        if (res.ok && answer && typeof answer === "object" && Object.keys(answer).length > 0) {
-            stdout.write(JSON.stringify(answer));
+        if (res.ok && answer && typeof answer === "object" && !Array.isArray(answer) && Object.keys(answer).length > 0) {
+            stdout.write(asciiJson(answer));
         }
     }
     catch (err) {