@basein/runner 0.2.6 → 0.2.8

package/dist/bin/bir-hooks.js

@@ -71,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;
@@ -207,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,
@@ -234,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);
@@ -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