@basein/runner 0.2.5 → 0.2.7

package/README.md

@@ -110,10 +110,11 @@ between the two is not guaranteed.
   is a structural fact, not a limitation of this implementation.
 - **`claude-in-chrome`.** It is `scope: "dynamic"`, present in no config file, so
   there is no entry to rewrite.
-- **Replay, unless you turn it on.** Recording is the default and the whole of
-  what runs out of the box. Calculated replay — running a matched prompt's
-  scenario instead of rediscovering it — ships, but needs `bir install --replay`
-  *and* `BIR_REPLAY=1`, for the reason in the next section.
+- **Replay, unless you install it.** Recording is the whole of what runs out of
+  the box. Calculated replay — running a matched prompt's scenario instead of
+  rediscovering it — ships, but needs `bir install --replay`. Once installed it
+  is on by default; `BIR_REPLAY=0` turns it off, for the reason in the next
+  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.
@@ -134,7 +135,7 @@ record, calculate, check, enable, read the audit lines — is
 
 ```bash
 bir install --replay      # adds the `bir` MCP server; raises the prompt-hook timeout
-BIR_REPLAY=1 bir-hooks    # and this is the switch
+bir-hooks                 # replay is on by default; BIR_REPLAY=0 bir-hooks turns it off
 ```
 
 Two switches, not one, because of what replay is: **a scenario is a pre-approved
@@ -198,7 +199,7 @@ what to do when they register, so there is one switch and no second copy of it:
 
 | Variable | Effect |
 |---|---|
-| `BIR_REPLAY=1` | Enable replay. Nothing below matters until it is set. |
+| `BIR_REPLAY=0` | Disable replay. It is on by default; nothing below matters while this is `0`. |
 | `BIR_REPLAY_ALLOW_SERVERS` | Server keys eligible for **direct** execution. Unset means every wrapped server; setting it is the recommendation. |
 | `BIR_MIN_STEER_SIMILARITY` | Minimum match similarity to replay (default `0.92`, above the service's own `0.9` detection threshold). |
 | `ANTHROPIC_API_KEY` | **Optional.** Working out what a new request is about — which fleet, which file, which date — is done for you by the service on its own key, as long as you are signed in. Set this only to keep that reading on your machine, on your key. Signed out *and* unset, a scenario whose values change between requests is declined rather than replayed on stale ones. |

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

@@ -19,11 +19,12 @@
  *   BIR_NO_CORRELATION=1      never inject a call id; join on fingerprints
  *   BIR_VERBOSE=1             per-step detail lines
  *
- *   BIR_REPLAY=1              run a calculated scenario on a similar-meaning
- *                             match (docs/calculatedReplay.md). OFF by default,
- *                             and read §13.2 before turning it on: a replayed
- *                             step is auto-approved, and a directly executed one
- *                             never reaches the permission system at all.
+ *   BIR_REPLAY=0              turn OFF calculated replay — running a scenario on
+ *                             a similar-meaning match (docs/calculatedReplay.md).
+ *                             ON by default; unset or any value other than "0"
+ *                             keeps it on. Read §13.2: a replayed step is
+ *                             auto-approved, and a directly executed one never
+ *                             reaches the permission system at all.
  *   BIR_REPLAY_ALLOW_SERVERS  comma-separated server keys eligible for *direct*
  *                             execution. Unset means every wrapped server
  *   BIR_MIN_STEER_SIMILARITY  minimum match similarity to replay (default 0.92)

package/dist/bin/bir-hooks.js

@@ -19,11 +19,12 @@
  *   BIR_NO_CORRELATION=1      never inject a call id; join on fingerprints
  *   BIR_VERBOSE=1             per-step detail lines
  *
- *   BIR_REPLAY=1              run a calculated scenario on a similar-meaning
- *                             match (docs/calculatedReplay.md). OFF by default,
- *                             and read §13.2 before turning it on: a replayed
- *                             step is auto-approved, and a directly executed one
- *                             never reaches the permission system at all.
+ *   BIR_REPLAY=0              turn OFF calculated replay — running a scenario on
+ *                             a similar-meaning match (docs/calculatedReplay.md).
+ *                             ON by default; unset or any value other than "0"
+ *                             keeps it on. Read §13.2: a replayed step is
+ *                             auto-approved, and a directly executed one never
+ *                             reaches the permission system at all.
  *   BIR_REPLAY_ALLOW_SERVERS  comma-separated server keys eligible for *direct*
  *                             execution. Unset means every wrapped server
  *   BIR_MIN_STEER_SIMILARITY  minimum match similarity to replay (default 0.92)
@@ -70,6 +71,7 @@ import { readSidecar } from "../config/generate.js";
 import { resolveServers } from "../config/resolve.js";
 import { isWrapped } from "../config/generate.js";
 import { logLine, errText } from "../util/log.js";
+import { openJournal } from "../util/journal.js";
 function parsePort(value) {
     const n = Number(value);
     return Number.isInteger(n) && n > 0 && n < 65536 ? n : DEFAULT_CONTROL_PORT;
@@ -141,7 +143,7 @@ function parseIntentSources(value) {
  * part of the live task.
  */
 function buildReplayOptions(auth) {
-    const enabled = process.env.BIR_REPLAY === "1";
+    const enabled = process.env.BIR_REPLAY !== "0";
     const allowServers = parseAllowList(process.env.BIR_REPLAY_ALLOW_SERVERS);
     const minSimilarity = Number(process.env.BIR_MIN_STEER_SIMILARITY);
     const opts = {
@@ -206,6 +208,9 @@ async function main() {
     }
     const cwd = process.cwd();
     const sidecar = readSidecar();
+    // Open before anything logs: the journal is what `bir investigate` reads
+    // later, and the startup lines are part of the story.
+    const journalFile = openJournal(cwd);
     const auth = await buildRecorder();
     const server = new ControlServer({
         recorder: auth.recorder,
@@ -233,6 +238,7 @@ async function main() {
         url: address.url,
         cwd,
         discovery: discoveryFile,
+        journal: journalFile,
         machine: hostname(),
         wrapped: wrappedServersFor(cwd).join(",") || "(none)",
     });

package/dist/bin/bir.js

@@ -31,6 +31,9 @@ import { readGenericServers, setGenericServerEntry } from "../config/adapters/ge
 import { AUTH_URL_HINT, DeviceFlowAborted, DeviceFlowUnsupported, authenticate, deviceLogin, describeAuthService, legacyPasswordLogin, tokenLogin, logout, normalizeAuthUrl, resolveAuthUrl, } from "../auth/client.js";
 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 { loadCredentials } from "../auth/client.js";
 import { packageVersion } from "../util/version.js";
 const VERSION = packageVersion();
 const out = (line = "") => {
@@ -54,6 +57,12 @@ Commands:
   scenario replay <scnId> --prompt "…" [--dry]
   replay --scenario <scnId> --prompt "…" [--dry]
 
+  investigate [<id>]                why the newest turn here (or run_/scn_/sexec_ <id>) did what
+                                    it did, what it cost, what to fix — journal + service
+  investigate list [--limit <n>]    recent turns in this directory and their verdicts
+  investigate executions [--limit <n>] [--user <email|id>]
+                                    the ledger, newest first (--user: admins only)
+
 Options:
   --config <path>   an explicit { "mcpServers": … } file, for clients with no adapter
   --server <name>   restrict install/uninstall to one server (repeatable)
@@ -68,7 +77,9 @@ Options:
   --dry             replay against recorded outputs only; run no real tools
   --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)`);
+  --password        login: use the old email/password prompt (deprecated)
+  --user <ref>      investigate executions: another account, by email or id (admin)
+  --limit <n>       investigate: how many turns / executions to show`);
     process.exit(code);
 }
 function parseArgs(argv) {
@@ -146,6 +157,18 @@ function parseArgs(argv) {
             case "--json":
                 args.json = true;
                 break;
+            case "--user":
+                args.user = argv[++i];
+                if (!args.user)
+                    usage(2);
+                break;
+            case "--limit": {
+                const n = Number(argv[++i]);
+                if (!Number.isInteger(n) || n <= 0)
+                    usage(2);
+                args.limit = n;
+                break;
+            }
             default:
                 if (arg.startsWith("-"))
                     usage(2);
@@ -369,10 +392,10 @@ function install(args) {
     }
     if (args.replay) {
         out();
-        out("Calculated replay is INSTALLED but not ON. Set BIR_REPLAY=1 where you run");
-        out("`bir-hooks` to enable it — and read docs/calculatedReplayGuide.md §5.1 first:");
-        out("a replayed step is auto-approved, and a directly executed one never reaches");
-        out("the permission system at all.");
+        out("Calculated replay is INSTALLED and ON by default once `bir-hooks` runs. Set");
+        out("BIR_REPLAY=0 where you run `bir-hooks` to turn it off — and read");
+        out("docs/calculatedReplayGuide.md §5.1 first: a replayed step is auto-approved,");
+        out("and a directly executed one never reaches the permission system at all.");
     }
     return 0;
 }
@@ -933,6 +956,22 @@ async function main() {
             return scenarioCommand(args);
         case "replay":
             return replayCommand(args);
+        case "investigate":
+            return investigateCommand({ positionals: args.positionals, json: args.json, user: args.user, limit: args.limit }, {
+                cwd: process.cwd(),
+                out,
+                journal: (cwd) => readJournal(journalPath(cwd)),
+                journalPath,
+                viewerEmail: loadCredentials()?.user?.email,
+                service: async (path) => {
+                    try {
+                        return await service("GET", path);
+                    }
+                    catch (err) {
+                        return { error: errText(err) };
+                    }
+                },
+            });
         case "login": {
             // Settle the URL the way every other command does, then refuse to go on
             // when what is there is not the service. "Signed in" must mean the service

package/dist/bin/investigate.d.ts

@@ -0,0 +1,195 @@
+/**
+ * `bir investigate` — why did this turn do what it did, and what did it cost?
+ * (docs/calculatedReplayGuide.md §9.1)
+ *
+ * Two sources, merged:
+ *
+ *   1. The **journal** this directory's `bir-hooks` keeps (util/journal.ts):
+ *      the run boundaries, the match, every gate decision, the plan's mode and
+ *      coverage, the replay outcome and the execution report. This is the only
+ *      record of a *matched* turn, because the service deliberately keeps no
+ *      run for one.
+ *   2. The **service**'s `GET /investigate/:id`: the recording, its scenario,
+ *      the baseline, the execution ledger and the service's own findings.
+ *      Owner-only; an admin may look at anyone's.
+ *
+ * Each side diagnoses what only it can see. The journal knows which gate
+ * declined and what mode armed; the service knows the baseline, the ledger and
+ * whether a run ever became a recording. Both lists are printed, worst first.
+ */
+import type { JournalEntry } from "../util/journal.js";
+export interface Turn {
+    runId: string;
+    sessionId?: string;
+    startedAt: string;
+    finishedAt?: string;
+    prompt?: string;
+    matched?: {
+        runId: string;
+        scenarioId?: string;
+        similarity?: number;
+    };
+    decision?: {
+        verdict: string;
+        code?: string;
+        why?: string;
+        threshold?: number;
+    };
+    plan?: {
+        mode: string;
+        steps?: number;
+        coverage?: string[];
+        tools?: string[];
+        scenarioId?: string;
+        by?: string;
+    };
+    derived?: {
+        params?: number;
+        costUsd?: number;
+        source?: string;
+    };
+    done?: {
+        outcome: string;
+        steps?: string;
+        ms?: number;
+    };
+    reported?: {
+        outcome: string;
+        derive: number;
+        session: number;
+        fallback: number;
+        savedUsd?: number;
+        measured?: boolean;
+        ticket?: string;
+        scenarioId?: string;
+        declined?: string;
+    };
+    finish?: {
+        steps?: number;
+        durationMs?: number;
+        costUsd?: number;
+        measured?: boolean;
+        recorded?: boolean;
+    };
+    /** `replay.*_failed`, `replay.arm_failed`, `replay.diverge`, `replay.handover` … */
+    incidents: JournalEntry[];
+    events: JournalEntry[];
+}
+/**
+ * Group journal entries into turns. A turn opens at `run.start` and closes at
+ * `run.finish`; an entry joins the turn whose local run id it names, else the
+ * turn whose *matched* run id it names (the replay lines log the service's run),
+ * else the latest turn — which is where an older build's `execution.reported`,
+ * arriving after `run.finish` with no run id, belongs.
+ */
+export declare function turnsFromJournal(entries: readonly JournalEntry[]): Turn[];
+/** The turn an id names: its own run, the run it matched, its scenario or its ticket. */
+export declare function findTurn(turns: readonly Turn[], id: string): Turn | undefined;
+export interface Finding {
+    code: string;
+    severity: "problem" | "warn" | "info";
+    title: string;
+    cause: string;
+    fix: string;
+    evidence?: Record<string, unknown>;
+}
+/** The runner's own gate vocabulary, with the cause and the fix (guide §9). */
+export declare const DECLINES: Record<string, {
+    cause: string;
+    fix: string;
+}>;
+export declare const LOW_SAVING_PCT = 0.3;
+export declare function localFindings(turn: Turn): Finding[];
+/** `saved ÷ (saved + cost)`: the baseline is recoverable from the report alone. */
+export declare function savedPct(turn: Turn): number | null;
+export type ServiceReply = {
+    status: number;
+    body: unknown;
+} | {
+    error: string;
+};
+export interface InvestigateDeps {
+    cwd: string;
+    out: (line?: string) => void;
+    service: (path: string) => Promise<ServiceReply>;
+    journal: (cwd: string) => JournalEntry[];
+    journalPath: (cwd: string) => string;
+    /** The signed-in account, so "owner you" can be told from "owner <email>". */
+    viewerEmail?: string;
+}
+export interface InvestigateArgs {
+    positionals: string[];
+    json: boolean;
+    user?: string;
+    limit?: number;
+}
+interface ServiceInvestigation {
+    subject?: {
+        kind: string;
+        id: string;
+    };
+    owner?: {
+        id: string;
+        email: string | null;
+    };
+    run?: {
+        id: string;
+        input: string;
+        title: string | null;
+        finishedAt: string | null;
+        actionCount: number;
+        tools: string[];
+        originalCostUsd: number | null;
+        iterations: number;
+        isRecording: boolean;
+        embedded: boolean;
+        duplicateOf: string | null;
+    } | null;
+    scenario?: {
+        id: string;
+        state: string;
+        steps: Array<{
+            stepIndex: number;
+            toolName: string | null;
+            failureCount: number;
+        }>;
+        baseline: {
+            costUsd: number | null;
+            samples: number;
+            method: string | null;
+        };
+        lastDecline: {
+            reason: string;
+            at: string | null;
+        } | null;
+        hitCount: number | null;
+        disabledAt: string | null;
+        error: string | null;
+    } | null;
+    executions?: Array<{
+        id: string;
+        createdAt: string;
+        outcome: string;
+        costUsd: number;
+        deriveCostUsd: number | null;
+        sessionCostUsd: number | null;
+        fallbackCostUsd: number | null;
+        baselineCostUsd: number | null;
+        savedUsd: number | null;
+        savedPct: number | null;
+        measured: boolean;
+        durationMs: number | null;
+        steps: Array<{
+            stepIndex: number;
+            toolName?: string;
+            status: string;
+            error?: string;
+        }> | null;
+    }>;
+    findings?: Finding[];
+}
+export declare function renderTurn(out: (l?: string) => void, turn: Turn): void;
+export declare function renderService(out: (l?: string) => void, s: ServiceInvestigation, viewerIsOwner: boolean): void;
+export declare function investigateCommand(args: InvestigateArgs, deps: InvestigateDeps): Promise<number>;
+export {};
+//# sourceMappingURL=investigate.d.ts.map