@basein/runner 0.2.6 → 0.2.8

package/dist/util/journal.js

@@ -0,0 +1,97 @@
+/**
+ * journal — the audit lines that explain a turn, kept on disk for
+ * `bir investigate` (docs/calculatedReplayGuide.md §9.1).
+ *
+ * `logLine` prints to stderr and is gone when the terminal scrolls. The
+ * questions people ask afterwards — why did this prompt not run its scenario,
+ * which gate declined, what mode did the plan arm in, what did the execution
+ * report — are answered by exactly those lines. So `bir-hooks` opens a journal
+ * for its directory and every audit line whose event is in {@link isJournaled}
+ * lands in it too, as one JSON object per line with the same fields.
+ *
+ * One file per directory, keyed like the discovery file, so two projects on
+ * one machine never mix. Rotated at {@link JOURNAL_MAX_BYTES} by keeping the
+ * newest half. Written best-effort and synchronously: a full disk must never be
+ * the reason a hook fails (design §1, rule 4), and a hook's answer must not
+ * race the line that explains it.
+ */
+import { appendFileSync, existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { controlDir, controlKey, ensureDir } from "../control/paths.js";
+/** Events worth keeping: the run boundaries, every replay decision, the money. */
+const JOURNALED_PREFIXES = ["run.", "replay.", "plan.", "execution."];
+const JOURNALED_EVENTS = new Set(["session.start", "control.listening", "proxy.registered"]);
+export function isJournaled(event) {
+    return JOURNALED_EVENTS.has(event) || JOURNALED_PREFIXES.some((p) => event.startsWith(p));
+}
+export const JOURNAL_MAX_BYTES = 4 * 1024 * 1024;
+export function journalPath(cwd) {
+    return join(controlDir(), "journal", `${controlKey(cwd)}.jsonl`);
+}
+let current;
+/** Start journaling this directory's audit lines. Returns the file, for the startup log. */
+export function openJournal(cwd) {
+    const path = journalPath(cwd);
+    ensureDir(dirname(path));
+    current = path;
+    return path;
+}
+export function closeJournal() {
+    current = undefined;
+}
+/**
+ * Append one entry, if a journal is open and the event is one we keep.
+ * Called by `logLine` for every audit line, and directly for the few facts
+ * that belong in the journal but not on stderr (a prompt preview).
+ */
+export function journal(event, fields = {}) {
+    if (!current || !isJournaled(event))
+        return;
+    const entry = { at: new Date().toISOString(), event };
+    for (const [key, value] of Object.entries(fields)) {
+        if (value === undefined || value === null)
+            continue;
+        entry[key] = value;
+    }
+    try {
+        appendFileSync(current, `${JSON.stringify(entry)}\n`);
+        rotate(current);
+    }
+    catch {
+        /* best effort — never the reason a hook fails */
+    }
+}
+function rotate(path) {
+    let size = 0;
+    try {
+        size = statSync(path).size;
+    }
+    catch {
+        return;
+    }
+    if (size <= JOURNAL_MAX_BYTES)
+        return;
+    const lines = readFileSync(path, "utf8").split("\n").filter(Boolean);
+    const keep = lines.slice(Math.floor(lines.length / 2));
+    writeFileSync(path, keep.length ? `${keep.join("\n")}\n` : "");
+}
+/** Every entry in a journal file, oldest first. A malformed line is skipped, not fatal. */
+export function readJournal(path) {
+    if (!existsSync(path))
+        return [];
+    const out = [];
+    for (const line of readFileSync(path, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed.event === "string" && typeof parsed.at === "string")
+                out.push(parsed);
+        }
+        catch {
+            /* a torn last line from a crash, or a hand edit — ignore it */
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=journal.js.map

package/dist/util/log.js

@@ -18,8 +18,12 @@ export const VERBOSE = process.env.BIR_VERBOSE === "1";
  * session: the audit log is the only record of what the recorder decided.
  */
 export const QUIET = process.env.BIR_QUIET === "1";
+import { journal } from "./journal.js";
 /** Print one audit line: `[bir] <iso ts> <event> key=value …`. */
 export function logLine(event, fields = {}) {
+    // The journal keeps the decision lines for `bir investigate` (journal.ts).
+    // Before the QUIET check on purpose: silence is for the terminal, not the record.
+    journal(event, fields);
     if (QUIET)
         return;
     const pairs = [];

package/docs/calculatedReplayGuide.md

@@ -390,11 +390,45 @@ first prompt that states the task plainly.
 | `run_scenario` returns "no scenario is armed" | The model called it on a turn with no plan | Harmless. It happens when the model remembers the tool from an earlier turn |
 | `execution.reported … 409 invalid_ticket` | The ticket was already redeemed, or belongs to another scenario | Harmless if `duplicate: true`. Otherwise a rollover raced `SessionEnd`; the server books once |
 | `savedUsd` looks impossible | Pricing drift between the runner's table and the server's | Compare `PRICING_VERSION` on both sides. Design §11.3 documents a known live drift between two existing copies |
+| The hand-over note says a step "did not run: its input needs a judgement" | The service marked the step non-deterministic when it calculated the plan: the generated logic could not compute its input from the prompt or from earlier outputs, so the recorded value was a copy (plan-services.md D8, kind 3) | Nothing on the runner. The agent makes that choice and finishes the task; a model step for such judgements is planned (W3.1). The journal's `plan.armed` line lists it under `stops=` |
+| A parked step ran again after an hour, or a plan was recalculated by itself | The service's grace period (D8): a parked step is served with `stop: null` once an hour for a day and a success clears its count; if it keeps failing, or its tool is gone, the next repeat of the prompt is recorded in full and the plan is calculated again from it | Nothing: that is the repair. `bir investigate` names the kind (`step_retrying`, `step_parked … repair due`, `scenario_repairing`). To repair now by hand: `bir scenario calc <runId> --force` |
 | `sessionCostUsd` grows every prompt in a session | The per-run usage watermark is missing or not taken | Design §11.4. Reports without a mark must carry `measured: false` |
 | Everything works, nothing is saved | A replayed turn is deliberately not recorded (design §12) | Correct. The matched run stays canonical and its `iterations` is bumped |
 
 ---
 
+### 9.1 `bir investigate` — the table above, applied for you
+
+Every audit line that explains a turn is also kept in a **journal**, one JSON
+object per line, under `~/.baseinstrunner/control/journal/` (one file per
+directory, rotated at 4 MB). `bir-hooks` prints its path at start. Ask the
+journal and the service together:
+
+```
+bir investigate                       # the newest turn in this directory
+bir investigate <run_|scn_|sexec_ id> # that run, scenario or execution
+bir investigate list [--limit n]      # recent turns and their verdicts
+bir investigate executions [--limit n] [--user <email|id>]   # the ledger
+```
+
+The output is the turn as the journal tells it (matched what, which gate
+declined and why, what mode armed with which coverage, what the execution
+reported), then **runner findings**, then the service's view (the recording,
+the scenario, the baseline and its sample count, the executions with their
+saved $ and %) and **service findings**. Every finding is *problem → cause →
+fix*. The three questions it answers:
+
+| Question | Where the answer comes from |
+|---|---|
+| Why did this turn not run its calculated scenario? | `replay.decision code=…` in the journal, mapped to the cause and the fix; and the service: is the run a recording, is it embedded, how many hits, is the scenario ready / failed / switched off, which step is parked |
+| Why did it save so little, or cost more? | the execution's cost breakdown (derive, session, fallback) against the baseline; steer mode with built-in steps is the usual answer, a single-sample baseline the second |
+| What happened, step by step? | the turn's lines in order, the per-step verdicts on the execution, and `replay.*_failed`, `replay.diverge`, `replay.handover` as incidents |
+
+You see your own data. An admin of the service sees everyone's and may pass
+`--user` to `executions`. `--json` on any form prints the raw merge.
+
+---
+
 ## 10. What is built
 
 All of it. Phases R0–R7 of [calculatedReplay.md](calculatedReplay.md) §17 are implemented and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basein/runner",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "A recording MCP proxy: sits between any MCP client and its MCP servers, executes each call on the client's behalf, and records the run as a reusable BaseIn scenario.",
   "type": "module",
   "license": "MIT",