@basein/runner 0.2.10 → 0.2.12

package/dist/bin/bir.js

@@ -12,6 +12,16 @@
  *   bir login | logout
  *   bir --version
  *
+ *   bir scenario list | show <runId|scnId> [--step <n>] | calc <runId|scnId> [--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> | --step <n>] [--force --note "why"]
+ *   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
@@ -20,7 +30,7 @@
  * from `serverInfo`, which must stay the upstream's (Phase 3).
  */
 import { randomBytes } from "node:crypto";
-import { existsSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ControlClient } from "../control/client.js";
@@ -37,6 +47,7 @@ import { DEFAULT_CONTROL_PORT } from "../control/server.js";
 import { errText } from "../util/log.js";
 import { journalPath, readJournal } from "../util/journal.js";
 import { investigateCommand } from "./investigate.js";
+import { SCENARIO_EDIT_SUBCOMMANDS, scenarioEditCommand } from "./scenario-edit.js";
 import { loadCredentials } from "../auth/client.js";
 import { packageVersion } from "../util/version.js";
 const VERSION = packageVersion();
@@ -59,8 +70,22 @@ Commands:
   logout      revoke this machine's session and forget it
 
   scenario list                     recorded runs and their calculated scenarios
-  scenario show <runId>             a run's scenario: intent, params, steps
-  scenario calc <runId> [--force]   calculate (or re-derive) a run's scenario
+  scenario show <runId|scnId> [--step <n>]
+                                    a scenario: intent, params, steps (--step: just that one)
+  scenario calc <runId|scnId> [--force [--discard-edits]]
+                                    calculate (or re-derive) a run's scenario; a scn_ id
+                                    (a sub-task's too) is recalculated in place, with --force
+  scenario check <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->] [--unfreeze]
+                                    try a change to one step against the recording; saves nothing
+  scenario edit <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->]
+                [--freeze | --unfreeze] [--note "why"] [--force --note "why"] [--revision <n>]
+                                    the same check, and save the change if it passes
+  scenario edits <runId|scnId>      a scenario's hand edits, newest first
+  scenario undo <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "why"]
+                                    take back the newest edit (of step n); run it again to go
+                                    one further back; undo an undo's sedit_ id to redo
+  scenario editing on|off|status    whether this project's bir MCP server offers the tools
+                                    that change a scenario (restart Claude Code after)
   scenario replay <scnId> --prompt "…" [--dry]
   replay --scenario <scnId> --prompt "…" [--dry]
   replay status | on | off | allow <a,b> | allow all
@@ -83,8 +108,21 @@ Options:
   --replay          install/remove the scenario server, enabling calculated replay
   --port <n>        install/setup: control-server port to write into the hook URLs
                     (default: this project's, else the lowest free one from ${DEFAULT_CONTROL_PORT})
-  --json            machine-readable output for status / doctor
+  --json            machine-readable output for status / doctor / scenario / investigate
+                    (scenario check|edit|edits|undo: the service's answer, unchanged)
   --dry             replay against recorded outputs only; run no real tools
+  --force           scenario calc: recalculate in place · scenario edit: save although
+                    the check refused it (needs --note; only for a recording that was wrong)
+                    · scenario undo: undo although a later step or the answer would break
+  --step <n>        scenario show|check|edit|undo: the step, by the stepIndex \`show\` prints
+  --input-logic <file|->   scenario check|edit: the new input logic, from a file or stdin (-)
+  --output-logic <file|->  scenario check|edit: the new output logic, from a file or stdin (-)
+  --freeze          scenario edit: mark the step "needs a judgement" (runs hand over before it)
+  --unfreeze        scenario check|edit: ask to remove that mark; the check decides
+  --note <text>     scenario edit|undo: why, kept in the history (required with --force)
+  --revision <n>    scenario edit|undo: only if the plan is still at this chainRevision
+  --edit <id>       scenario undo: the sedit_ id to undo (default: the newest edit that can be)
+  --discard-edits   scenario calc --force: recalculate a plan with hand edits, replacing them
   --no-browser      login: print the link and code, open nothing (SSH, headless)
   --token <value>   login: redeem a one-time setup token from the console (no browser)
   --password        login: use the old email/password prompt (deprecated)
@@ -118,6 +156,9 @@ function parseArgs(argv) {
         noDaemon: false,
         restart: false,
         portExplicit: false,
+        freeze: false,
+        unfreeze: false,
+        discardEdits: false,
     };
     for (let i = 1; i < argv.length; i += 1) {
         const arg = argv[i];
@@ -214,6 +255,53 @@ function parseArgs(argv) {
                 args.limit = n;
                 break;
             }
+            case "--step": {
+                // Digits only: `Number("")` is 0 and `Number("0x4")` is 4, and a step
+                // index nobody typed is a step nobody meant to change.
+                const raw = argv[++i] ?? "";
+                if (!/^\d+$/.test(raw))
+                    usage(2);
+                args.step = Number(raw);
+                break;
+            }
+            case "--input-logic":
+                // A value flag, so a bare `-` (stdin) is taken here and never reaches
+                // the default branch, which refuses anything that starts with a dash.
+                args.inputLogic = argv[++i];
+                if (!args.inputLogic)
+                    usage(2);
+                break;
+            case "--output-logic":
+                args.outputLogic = argv[++i];
+                if (!args.outputLogic)
+                    usage(2);
+                break;
+            case "--freeze":
+                args.freeze = true;
+                break;
+            case "--unfreeze":
+                args.unfreeze = true;
+                break;
+            case "--note":
+                args.note = argv[++i];
+                if (args.note === undefined)
+                    usage(2);
+                break;
+            case "--edit":
+                args.edit = argv[++i];
+                if (!args.edit)
+                    usage(2);
+                break;
+            case "--revision": {
+                const raw = argv[++i] ?? "";
+                if (!/^\d+$/.test(raw) || Number(raw) <= 0)
+                    usage(2);
+                args.revision = Number(raw);
+                break;
+            }
+            case "--discard-edits":
+                args.discardEdits = true;
+                break;
             default:
                 if (arg.startsWith("-"))
                     usage(2);
@@ -221,6 +309,10 @@ function parseArgs(argv) {
                     args.positionals.push(arg);
         }
     }
+    if (args.freeze && args.unfreeze) {
+        process.stderr.write("[bir] --freeze and --unfreeze are mutually exclusive\n");
+        process.exit(2);
+    }
     return args;
 }
 /** Absolute path to this package's built `bir-proxy.js`, for `--local`. */
@@ -960,51 +1052,59 @@ async function scenarioCommand(args) {
         }
         return 0;
     }
-    if (sub === "show") {
-        if (!target) {
-            out("usage: bir scenario show <runId>");
-            return 2;
-        }
-        const { status, body } = await service("GET", `/recordings/runs/${target}/scenario`);
-        if (status === 404) {
-            out("No scenario for that run yet — `bir scenario calc <runId>` first.");
-            return 1;
-        }
-        if (status !== 200) {
-            out(`Could not read the scenario (HTTP ${status}).`);
-            return 1;
-        }
-        out(JSON.stringify(body, null, 2));
-        return 0;
-    }
-    if (sub === "calc") {
-        if (!target) {
-            out("usage: bir scenario calc <runId> [--force]");
-            return 2;
-        }
-        const { status, body } = await service("POST", `/recordings/runs/${target}/calculate`, args.force ? { force: true } : {});
-        if (status === 202) {
-            const b = body;
-            out(`Calculating ${b.scenarioId ?? ""} — poll with \`bir scenario show ${target}\`.`);
-            return 0;
-        }
-        if (status === 409) {
-            out("That run already has a scenario. Re-derive it in place with --force.");
-            return 1;
-        }
-        if (status === 503) {
-            out("The service has no Anthropic configuration, so it cannot calculate scenarios.");
-            return 1;
-        }
-        out(`Could not start calculation (HTTP ${status}): ${JSON.stringify(body)}`);
-        return 1;
+    // show, calc, and everything that reads or changes one step (editSteps.md).
+    if (SCENARIO_EDIT_SUBCOMMANDS.has(sub)) {
+        return scenarioEditCommand({
+            positionals: args.positionals,
+            json: args.json,
+            force: args.force,
+            step: args.step,
+            inputLogic: args.inputLogic,
+            outputLogic: args.outputLogic,
+            freeze: args.freeze,
+            unfreeze: args.unfreeze,
+            note: args.note,
+            edit: args.edit,
+            revision: args.revision,
+            discardEdits: args.discardEdits,
+        }, {
+            cwd: process.cwd(),
+            out,
+            service: async (method, path, body) => {
+                try {
+                    return await service(method, path, body);
+                }
+                catch (err) {
+                    return { error: errText(err) };
+                }
+            },
+            readFile: (path) => readFileSync(resolvePath(process.cwd(), path)),
+            readStdin,
+        });
     }
     if (sub === "replay") {
         return replayCommand({ ...args, scenarioId: args.scenarioId ?? target });
     }
-    out("usage: bir scenario <list|show|calc|replay> …");
+    out("usage: bir scenario <list|show|calc|check|edit|edits|undo|editing|replay> …");
     return 2;
 }
+/**
+ * All of stdin, for `--input-logic -`. A person at a terminal gets told how to
+ * end it; a pipe never sees the line (it goes to stderr, and only on a TTY).
+ */
+function readStdin() {
+    if (process.stdin.isTTY) {
+        process.stderr.write("[bir] reading the logic from stdin — end it with Ctrl-D (Ctrl-Z, Enter on Windows)\n");
+    }
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        process.stdin.on("data", (chunk) => {
+            chunks.push(typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk);
+        });
+        process.stdin.on("end", () => resolve(Buffer.concat(chunks)));
+        process.stdin.on("error", reject);
+    });
+}
 /**
  * `--dry` evaluates the scenario's stored logic against the **source run's
  * recorded outputs**, server-side: no real tools, no side effects, one Haiku

package/dist/bin/investigate.js

@@ -179,11 +179,11 @@ export const DECLINES = {
     },
     known_bad_first_step: {
         cause: "the chain's first step is parked after repeated failures.",
-        fix: "wait: the service retries it once an hour for a day, then repairs the plan from the next run of the prompt. To repair now: `bir scenario calc <runId> --force`.",
+        fix: "wait: the service retries it once an hour for a day, then repairs the plan from the next run of the prompt — unless the plan has steps edited by hand, or is a sub-task, which it does not repair on its own. To repair now: `bir scenario calc <scnId> --force` (add --discard-edits to drop hand edits), or fix the step: `bir scenario edit <scnId> --step 0 --input-logic <file>`. `bir investigate <scnId>` names the scenario id.",
     },
     nondeterministic_first_step: {
         cause: "the chain's first step needs a judgement the calculation could not write code for, so the plan cannot start.",
-        fix: "the agent does this task itself; a model step for such judgements is planned (plan-services.md W3.1).",
+        fix: "if its code only has a slip, fix the step yourself: read it with `bir scenario show <scnId> --step 0`, write the input logic to a file, and run `bir scenario edit <scnId> --step 0 --input-logic <file>`; the service checks it against the recording before it saves it. A real judgement — a choice with no fixed rule — stays with the agent until a model step exists (plan-services.md W3.1).",
     },
     unusable_first_step: {
         cause: "the first step calls a sub-task that is gone, switched off or stale.",

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

@@ -0,0 +1,200 @@
+/**
+ * scenario-edit — read, check, change and undo one step of a calculated
+ * scenario (editSteps.md in the BaseIn repository; docs/calculatedReplayGuide.md §9.2).
+ *
+ *   bir scenario show  <runId|scnId> [--step <n>]
+ *   bir scenario check <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->] [--unfreeze]
+ *   bir scenario edit  <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->]
+ *                      [--freeze | --unfreeze] [--note "why"] [--force --note "why"] [--revision <n>]
+ *   bir scenario edits <runId|scnId>
+ *   bir scenario undo  <runId|scnId> [--edit <sedit_id> | --step <n>] [--force --note "why"]
+ *   bir scenario calc  <runId|scnId> [--force [--discard-edits]]
+ *   bir scenario editing on|off|status
+ *
+ * WHY THIS IS A CLIENT AND NOTHING MORE. Whether a change may be saved is
+ * decided on the service, against the recording, by the calculation's own
+ * check (D3) — and `check` and `edit` are the same function there (D11). A
+ * runner-side pre-check would be a second opinion that can disagree with the
+ * one that counts, so this module reads logic from files, sends it, and says
+ * in words what the service answered. `--json` prints the answer unchanged,
+ * which is what the `bir` MCP server hands the model.
+ *
+ * Logic never comes from the command line itself. A JavaScript body is full
+ * of quotes, braces and `$`, and every shell mangles a different subset of
+ * them; a file, or stdin with `-`, arrives byte for byte.
+ *
+ * Everything the commands touch is injected ({@link ScenarioEditDeps}), as in
+ * `investigate.ts`, so all of it is tested in-process against a fake service.
+ * The exception is `editing`, which writes the install sidecar — tests point
+ * `BIR_HOME` at a temporary directory for that.
+ */
+export type InputStatus = "reproduces" | "differs" | "throws" | "copy" | "not_checked";
+export interface EditReport {
+    ok: boolean;
+    stepIndex: number;
+    toolName: string | null;
+    /** The recording the change was checked against. */
+    sourceRunId: string;
+    verifiable: boolean;
+    input: {
+        changed: boolean;
+        before: InputStatus;
+        after: InputStatus;
+        computed?: unknown;
+        recorded?: unknown;
+        firstDifference?: {
+            at: number;
+            computed: string;
+            recorded: string;
+        };
+        error?: string;
+    };
+    output: {
+        changed: boolean;
+        status: "runs" | "throws" | "not_object" | "unchanged";
+        emittedKeys?: string[];
+        error?: string;
+    };
+    later: Array<{
+        stepIndex: number;
+        toolName: string | null;
+        before: InputStatus;
+        after: InputStatus;
+        regressed: boolean;
+    }>;
+    answer: {
+        informativeBefore: boolean;
+        informativeAfter: boolean;
+    } | null;
+    mark: {
+        before: MarkState;
+        after: MarkState;
+    };
+    /** The logic and mark asked for are what the step already has (rule 10). */
+    noChange?: boolean;
+    /** The check stopped at the service's sandbox-time budget: *too costly to check* (rule 11). */
+    budgetExceeded?: boolean;
+    problems: string[];
+}
+interface MarkState {
+    marked: boolean;
+    why: string | null;
+}
+export interface StepState {
+    toolInputLogic: string | null;
+    toolOutputLogic: string | null;
+    nondeterministic: boolean;
+    nondeterministicWhy: string | null;
+    editedAt: string | null;
+    editForced: boolean;
+}
+export interface EditEntry {
+    id: string;
+    scenarioId: string;
+    stepIndex: number;
+    kind: "edit" | "freeze" | "revert";
+    revertsEditId: string | null;
+    note: string | null;
+    forced: boolean;
+    chainRevisionBefore: number;
+    chainRevisionAfter: number;
+    before: StepState;
+    after: StepState;
+    report: EditReport | null;
+    createdAt: string;
+    /** A later undo put this one back. */
+    revertedAt: string | null;
+    /** A recalculation replaced the chain; the entry is history now. */
+    replacedAt: string | null;
+}
+export type ServiceReply = {
+    status: number;
+    body: unknown;
+} | {
+    error: string;
+};
+export interface ScenarioEditDeps {
+    cwd: string;
+    out: (line?: string) => void;
+    /** An authenticated call to the service; a failure to reach it is `{ error }`, never a throw. */
+    service: (method: string, path: string, body?: unknown) => Promise<ServiceReply>;
+    /** A logic file's bytes. Relative paths are the caller's to resolve. */
+    readFile: (path: string) => Buffer;
+    /** All of stdin, for `--input-logic -` / `--output-logic -`. */
+    readStdin: () => Promise<Buffer>;
+}
+export interface ScenarioEditArgs {
+    /** The words after `bir scenario`: `[sub, target | on|off|status, …]`. */
+    positionals: string[];
+    json: boolean;
+    force: boolean;
+    step?: number;
+    /** A path, or `-` for stdin. */
+    inputLogic?: string;
+    outputLogic?: string;
+    freeze: boolean;
+    unfreeze: boolean;
+    note?: string;
+    /** `undo --edit`: the `sedit_` id to put back. `undo --step` is {@link step}. */
+    edit?: string;
+    /** `--revision`: save only if the plan is still at this `chainRevision`. */
+    revision?: number;
+    discardEdits: boolean;
+}
+/** The `bir scenario` words this module answers; `list` and `replay` stay in bir.ts. */
+export declare const SCENARIO_EDIT_SUBCOMMANDS: ReadonlySet<string>;
+/** The `bir` MCP server's tools that only read: always offered (D2). */
+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"];
+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
+ * its mark decoded, because that is what `"…" > step.js` writes in Windows
+ * PowerShell 5.1, and a service answering "SyntaxError" to a file that looks
+ * fine in every editor is a riddle nobody should have to solve.
+ */
+export declare function decodeLogic(bytes: Buffer): string;
+/**
+ * The report in the lines editSteps.md "What a person sees" shows:
+ * `input`, `output` (when the output logic changed), `later`, `answer` (when
+ * the final answer read anything before) and `mark`.
+ *
+ * `check` prints every line: it is where a person explores a change, and "step
+ * 5 still reproduces" is an answer there. `edit` and `undo` are acts, and print
+ * `brief`ly — what changed and what went wrong: `input` always, `output` when
+ * it changed, `later` only for a step that broke, `answer` only when it lost its
+ * values, `mark` only when it moves. The report is the same one either way (D11);
+ * only the lines that say "nothing to see" are left out.
+ *
+ * An `undo` does not judge the step itself — its code and mark go back exactly
+ * as they were (editSteps.md, "Undo") — so its report's input status is
+ * `not_checked` by design, and printing the usual reason for that ("the
+ * recorded call is plain text") would be false. It says what happened instead.
+ */
+export declare function renderReport(out: (line?: string) => void, r: EditReport, opts?: {
+    brief?: boolean;
+    undo?: boolean;
+}): void;
+/**
+ * About {@link CONTEXT} characters either side of `at`. A text already that
+ * short — a window the service cut itself, or a small call — is printed whole.
+ */
+export declare function around(text: string, at: number): string;
+/**
+ * What `undo` without `--edit` takes back (D9): the newest **edit** — never an
+ * undo entry — that nothing has put back and no recalculation replaced; of
+ * step `step` when it is given.
+ *
+ * Undo entries are skipped on purpose. They used to be picked like any other,
+ * so a second `undo` redid the first one, and a step edited twice toggled
+ * between its two edits for ever and never got back to the calculation's code
+ * (C12). Now a second `undo` goes one further back; a redo is asked for by
+ * name, `--edit <the undo's id>`, which the undo prints.
+ *
+ * Whether the step is still exactly as that edit left it is the service's
+ * question, not this list's: it answers `not_latest_edit` when it is not.
+ */
+export declare function newestUndoable(edits: EditEntry[], step?: number): EditEntry | undefined;
+export {};
+//# sourceMappingURL=scenario-edit.d.ts.map