@basein/runner 0.2.10 → 0.2.12

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}`);
     }
     /**

package/docs/calculatedReplay.md

@@ -176,7 +176,7 @@ Three additions to the v1 topology, and nothing else moves:
 |---|---|---|
 | `bir-hooks` control server | extended | Holds the `ScenarioReplayPlan` on `RunState`. Arms it, pins inputs, threads outputs, dispatches direct steps, redeems the ticket |
 | `bir-proxy` | extended | Long-polls for work; executes a `tools/call` on the upstream it already owns |
-| `bir-scenario` | **new**, ~120 lines | A stdio MCP server exposing one tool, `run_scenario`. The delivery channel for direct mode (§6) |
+| `bir-scenario` | **new**, ~120 lines | A stdio MCP server exposing one tool, `run_scenario`. The delivery channel for direct mode (§6). It later gained the scenario tools of §16.5 |
 
 ---
 
@@ -814,6 +814,49 @@ What actually constrains it:
 If that is not enough for a deployment, the mitigation is a real one and is out of scope here:
 evaluate the logic in a `node:vm` context with a frozen, minimal global. Filed as §20 question 3.
 
+**A hand-edited step is the same code, and runs the same way.** Since 2026-09-25 (the service's
+`editSteps.md`; built, not yet released) the owner — or Claude working for them — can change a step's
+logic with `bir scenario edit`. The service checks the change against the recording before it saves
+it, but that check is about *what the code computes*. Once saved, the step arrives in the same
+payload and runs here unattended, with `new Function`, next to the same credentials, exactly like
+calculated code. The provenance argument still holds: only the owner can edit, over their own token,
+and anyone else — an admin included — gets `404`. What changes is that *"the model wrote it"* is no
+longer always true.
+
+The service sandboxes its own evaluation of every logic body (built with the same service change;
+not yet released). It had to: there, one account's code runs next to every account's data and the
+service's secrets. How it is built:
+
+- **A fresh `node:vm` context for each evaluation**, with a time limit (`LOGIC_TIMEOUT_MS`). Only
+  JavaScript's own built-ins are in it, less `ArrayBuffer`, `SharedArrayBuffer`, `DataView`, the
+  typed arrays, `Atomics`, `WebAssembly` and `FinalizationRegistry`; `Symbol.for` and
+  `Symbol.keyFor` are removed too. No `require`, `process`, `fetch`, `Buffer` or timers. Values go
+  in and come out as JSON text only.
+- **That context lives in a separate evaluator process**, not in the service: an empty
+  environment, `--permission` (no files, no child processes), `--disallow-code-generation-from-strings`,
+  `--frozen-intrinsics`, and a heap of `LOGIC_MEMORY_MB`.
+- **A relay worker thread of the service drives that process.** No logic runs in the relay. It
+  kills the evaluator when a body runs too long, and the next job starts a new one; a body that
+  runs out of memory takes down only the evaluator, and is run once more on a fresh one before it
+  is blamed. The relay also replaces the evaluator when its heap stays above half of
+  `LOGIC_MEMORY_MB` after a job, and after 2,000 jobs. A body that overran its time or memory, or
+  took the evaluator down twice, is refused at once, with the same message, for the next 10
+  minutes.
+- **The hand-edit check runs in a check worker thread of its own**, with its own relay and
+  evaluator process, under a sandbox-time budget
+  (`EDIT_CHECK_BUDGET_MS`, 5000 ms by default; past it, *too costly to check*), so a slow check
+  never holds up the service's other requests.
+
+**The runner still does not sandbox.** Here the code runs on the owner's machine, for the owner's
+account, with `new Function`. One consequence to know: **the service's check only judges what a
+body returns for the recording's values.** Code that calls `fetch`, `process` or a timer on that
+path, and does not catch the error, throws in the check, so it cannot be saved without `--force`.
+But a call behind a `typeof` guard (`if (typeof fetch === "function") …`), or on a branch the
+recording's values never take, is never reached in the check; one inside a `try` fails there
+quietly. Such code passes, it is saved like any other change, and here it runs with `fetch`,
+`process` and timers all present. The service's sandbox protects the service; it proves
+nothing about what a body does on the runner. Read every hand edit before it is saved.
+
 ### 13.2 Replay bypasses permission prompts
 
 This is the sharpest edge in the whole design, and it must not be buried.
@@ -884,7 +927,7 @@ src/
 │  ├─ source-run.ts              # lazy GET /recordings/runs/:id → recorded outputs by tool (§8.1)
 │  └─ types.ts                   # SerializedScenario, SerializedScenarioStep
 ├─ bin/
-│  ├─ bir-scenario.ts            ← new: the one-tool MCP server (§6.3)
+│  ├─ bir-scenario.ts            ← new: the `bir` MCP server — `run_scenario` (§6.3), later the scenario tools (§16.5)
 │  └─ bir.ts                     # + `--replay`, `bir scenario …`, `bir replay` (§16.5)
 ├─ control/
 │  ├─ server.ts                  # + arm / pin / thread / dispatch / report
@@ -1029,8 +1072,8 @@ and a session with no BaseIn credentials still replays (it just books nothing).
 
 ### 16.5 CLI surface
 
-`bir` gains one flag and one command group. Everything here is a thin client over endpoints that
-already exist server-side, except `bir replay`, which drives §16.2's executor directly.
+`bir` gains one flag and one command group. Everything here is a thin client over service
+endpoints, except `bir replay`, which drives §16.2's executor directly.
 
 ```
 bir install --replay          register the `bir` MCP server; raise the prompt-hook timeout to 15 s
@@ -1038,12 +1081,80 @@ bir uninstall --replay        reverse exactly that, leaving the rest of the inst
 
 bir scenario list             GET  /recordings/runs               runs, iterations, scenario state
 bir scenario show <runId>     GET  /recordings/runs/:id/scenario  intent, params, steps, logic
+bir scenario show <scnId>     GET  /scenarios/:id                 the same, by scenario id (segments too)
+                                   [--step <n>: one step, with scenarioId and chainRevision first]
 bir scenario calc <runId>     POST /recordings/runs/:id/calculate     [--force to re-derive in place]
+                                   [--force --discard-edits: re-derive a plan with hand edits]
+bir scenario calc <scnId> --force
+                              POST /scenarios/:id/recalculate    recalculate in place (segments too)
+                                   [--discard-edits: sends {discardEdits: true}]
 bir scenario replay <scnId> --prompt "…" [--dry]
 
+bir scenario check <id> --step <n>    POST  /scenarios/:id/steps/:n/check        try a change; writes nothing
+bir scenario edit  <id> --step <n>    PATCH /scenarios/:id/steps/:n              the same check, then save
+bir scenario edits <id>               GET   /scenarios/:id/edits                 the history, newest first
+bir scenario undo  <id> [--edit <e> | --step <n>]
+                                      POST  /scenarios/:id/edits/:e/revert       take back the newest edit (of step n)
+bir scenario editing on|off|status    (no route) ~/.baseinstrunner/installed.json  which `bir` MCP tools are offered
+
 bir replay --scenario <scnId> --prompt "…" [--dry]     alias; the Tier 2 / debugging path (§12.1)
 ```
 
+The second group, and `show <scnId>`, `--step`, `calc <scnId>` and `--discard-edits`, were added
+on 2026-09-25 by the service's `editSteps.md`. They are built and tested, and not yet released in
+the form described here (version 0.2.11 on npm has an early form): they need the next
+`@basein/runner` version and a service deploy, because their routes are new on the service. They
+are where `bir` changes a scenario by hand, so the rules are strict:
+
+- **Owner only.** Anyone else, an admin included, gets `404`, never `403`.
+- **A change is saved only if it reproduces the recording and is not a copy**, or on purpose with
+  `--force --note "<why>"`. `check` and `edit` run the same check; `check` never writes. When the
+  check had any problem, a forced save is recorded as forced, and `bir investigate` keeps saying so.
+- `<id>` is a `run_` id, resolved to its whole-run scenario with `GET /recordings/runs/:id/scenario`,
+  or a `scn_` id, used as it is. A sub-task scenario has only its `scn_` id; for a run with only
+  sub-task scenarios, `bir` lists their `scn_` ids. Logic goes in with `--input-logic` /
+  `--output-logic` from a file, or `-` for stdin — never inline, because shell quoting mangles
+  JavaScript. `edit` also takes `--freeze`, `--unfreeze`, `--note` and `--revision <n>` (the
+  `expectedRevision` of the body).
+- `show --step <n>` prints the step object with `scenarioId` and `chainRevision` first. The revision
+  is the scenario's, and is what `--revision` takes.
+- **`undo` walks back.** Without `--edit` it takes back the newest edit (never an undo entry) that
+  can be undone; with `--step <n>`, the newest edit of step `n`. Run again, it goes one further
+  back. `--edit` and `--step` cannot be given together. To redo, undo the undo entry by its
+  `sedit_` id; the undo prints that command. The service checks an undo like a save, for the later
+  steps and the final answer (so only when it changes output logic), and answers
+  `422 undo_refused` when it would break them, unless `--force --note "<why>"` is given. Every
+  save and every undo bumps the scenario's `chainRevision`.
+- A save lifts a mark made by hand (`--freeze`, `by_hand`) only with `--unfreeze`; undoing the
+  freeze, or `calc --force --discard-edits`, also removes it. A forced save lifts only a mark the
+  calculation set.
+- `calc --force` answers `409 scenario_has_edits` on a plan with hand edits, unless
+  `--discard-edits` is given. `calc <scnId>` without `--force` is a usage error: nothing is sent.
+- Answers `bir` puts in words: `400 nothing_to_change` (the code and mark asked for are the step's
+  already), `413 payload_too_large`, `503 logic_sandbox_unavailable` (nothing was checked, saved or
+  undone), and a check report with `noChange: true` (`check` then says nothing would change, and
+  exits `0`).
+- Exit codes: `0` checked OK, saved or undone; `1` refused, not found, or a service error; `2`
+  usage. `--json` prints the service's body unchanged.
+
+The same commands are tools on the `bir` MCP server. `scenario_show` (`target`, `step`),
+`scenario_edits` (`target`) and `investigate` (`id`) only read, and are always offered.
+`scenario_check` (`target`, `step`, `inputLogic`, `outputLogic`, `unfreeze`), `scenario_edit` (the
+same, plus `freeze`, `force`, `note`, `revision`) and `scenario_undo` (`target`, `edit` or `step`,
+`force`, `note`) are offered only in a project where `bir scenario editing on` was run, because that
+server runs in every session of every installed project. Each tool runs this package's own
+`bir … --json`, with logic bodies passed through temporary files; a refusal comes back as an MCP
+error result carrying the report. A call the host cancels, or leaves behind when it exits, has its
+`bir` stopped and its files removed.
+
+**`bir`'s own calls are never recorded** (the service's `editSteps.md` D13; not yet released). The
+`bir` server's tools other than `run_scenario`, and a `Bash` or `PowerShell` command made only of
+`bir` invocations (and a plain `cd`), are host housekeeping, like `ToolSearch`
+([housekeeping.ts](../src/record/housekeeping.ts)). They are never recorded as steps, and never
+count as divergence from a plan. A session that fixes a plan must not become a plan that edits
+plans when it is replayed. The operator's walk-through is
+[calculatedReplayGuide.md](calculatedReplayGuide.md) §9.2.
+
 `--dry` maps to BaseIn's `POST /scenarios/:id/replay`, which evaluates the stored logic against the
 source run's *recorded* outputs — no real tools, no side effects, one Haiku call. Without `--dry`,
 `bir replay` runs the same plan through the same executor against the live proxies. `bir doctor`