@basein/runner 0.2.11 → 0.3.0

package/dist/bin/investigate.js

@@ -17,6 +17,7 @@
  * 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 { ReadClock, jsonText, readWithin, serviceProblem, underMcp, unreachable } from "./service-read.js";
 const num = (v) => {
     if (v === undefined || v === null || v === "")
         return undefined;
@@ -170,8 +171,8 @@ export const DECLINES = {
         fix: "wait for the calculation, or start one with `bir scenario calc <runId>`, then run the prompt again.",
     },
     similarity: {
-        cause: "the prompt was a hit on the recording but below the steering threshold (BIR_REPLAY_MIN_SIMILARITY, default 0.92).",
-        fix: "phrase the prompt closer to the recorded one, or lower BIR_REPLAY_MIN_SIMILARITY.",
+        cause: "the prompt was a hit on the recording but below the steering threshold (BIR_MIN_STEER_SIMILARITY, default 0.92).",
+        fix: "phrase the prompt closer to the recorded one, or lower BIR_MIN_STEER_SIMILARITY.",
     },
     coverage: {
         cause: "no step of the scenario could run anywhere: its tools are neither wrapped MCP servers registered in this session nor built-ins.",
@@ -179,7 +180,7 @@ 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.",
@@ -435,16 +436,22 @@ export function renderService(out, s, viewerIsOwner) {
     renderFindings(out, s.findings ?? [], "Service findings");
 }
 // ── the command ───────────────────────────────────────────────────────────────
-async function fetchInvestigation(deps, id, limit) {
-    const reply = await deps.service(`/investigate/${id}${limit ? `?limit=${limit}` : ""}`);
-    if ("error" in reply)
-        return { note: `service not consulted: ${reply.error}` };
+async function fetchInvestigation(deps, id, limit, clock) {
+    const reply = await clock.within(deps.service(`/investigate/${id}${limit ? `?limit=${limit}` : ""}`));
+    if ("error" in reply) {
+        return { note: `service not consulted: ${serviceProblem(reply.error)}`, unreachable: unreachable(reply.error) };
+    }
     if (reply.status === 404)
         return { note: `the service has nothing for ${id} (not yours, or never reached it)` };
     if (reply.status !== 200)
         return { note: `service answered HTTP ${reply.status}` };
     return { data: reply.body };
 }
+/** A turn without its raw journal lines, which only a person reading the whole record wants. */
+function withoutEvents(turn) {
+    const { events, ...rest } = turn;
+    return { ...rest, eventCount: events.length };
+}
 /** Which id the service should be asked about for a turn. */
 function serviceIdFor(turn) {
     return (turn.reported?.ticket ??
@@ -463,9 +470,10 @@ export async function investigateCommand(args, deps) {
             params.set("limit", String(args.limit));
         if (args.user)
             params.set("user", args.user);
-        const reply = await deps.service(`/investigate/executions${params.size ? `?${params}` : ""}`);
+        const reply = await readWithin(deps.service(`/investigate/executions${params.size ? `?${params}` : ""}`));
         if ("error" in reply) {
-            out(`Could not reach the service: ${reply.error}`);
+            const words = serviceProblem(reply.error);
+            out(`Could not reach the service: ${words}${words === reply.error ? "" : ` (${reply.error})`}`);
             return 1;
         }
         if (reply.status === 403) {
@@ -482,7 +490,7 @@ export async function investigateCommand(args, deps) {
         }
         const body = reply.body;
         if (args.json) {
-            out(JSON.stringify(body, null, 2));
+            out(jsonText(body));
             return 0;
         }
         const rows = body.executions ?? [];
@@ -503,7 +511,7 @@ export async function investigateCommand(args, deps) {
         const limit = args.limit ?? 20;
         const recent = turns.slice(-limit).reverse();
         if (args.json) {
-            out(JSON.stringify(recent, null, 2));
+            out(jsonText(underMcp() ? recent.map(withoutEvents) : recent));
             return 0;
         }
         if (recent.length === 0) {
@@ -550,14 +558,31 @@ export async function investigateCommand(args, deps) {
     }
     const findings = turn ? localFindings(turn) : [];
     const serviceId = turn ? serviceIdFor(turn) : id;
-    const service = await fetchInvestigation(deps, serviceId, args.limit);
+    // Both reads below share one bound, so a slow "no" followed by a held
+    // second try still ends inside the time the `bir` MCP server allows a
+    // reading tool — with the journal half, which needed no service at all.
+    const clock = new ReadClock();
+    const service = await fetchInvestigation(deps, serviceId, args.limit, clock);
     // A matched turn's own run id is unknown to the service; when the scenario
-    // lookup fails, the matched run is still worth a try.
-    const fallbackId = turn && service.note && turn.matched?.runId && serviceId !== turn.matched.runId ? turn.matched.runId : undefined;
-    const second = fallbackId ? await fetchInvestigation(deps, fallbackId, args.limit) : undefined;
+    // lookup fails, the matched run is still worth a try — unless the service
+    // could not be reached at all, when a second try only doubles the wait, or
+    // the bound is spent.
+    const fallbackId = turn &&
+        service.note &&
+        !service.unreachable &&
+        turn.matched?.runId &&
+        serviceId !== turn.matched.runId &&
+        clock.remaining() > 0
+        ? turn.matched.runId
+        : undefined;
+    const second = fallbackId ? await fetchInvestigation(deps, fallbackId, args.limit, clock) : undefined;
     const chosen = service.data ? service : second?.data ? second : service;
     if (args.json) {
-        out(JSON.stringify({ turn: turn ?? null, findings, service: chosen.data ?? null, note: chosen.note ?? null }, null, 2));
+        // For a model (the `bir` MCP server), the turn goes without its raw
+        // journal lines: every field they carry is already parsed into the turn,
+        // and a long turn's lines are most of the output.
+        const shown = turn ? (underMcp() ? withoutEvents(turn) : turn) : null;
+        out(jsonText({ turn: shown, findings, service: chosen.data ?? null, note: chosen.note ?? null }));
         return 0;
     }
     if (turn) {

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

@@ -7,8 +7,8 @@
  *   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>]
- *   bir scenario calc  <runId> [--force [--discard-edits]]
+ *   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
@@ -70,6 +70,10 @@ export interface EditReport {
         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 {
@@ -131,7 +135,7 @@ export interface ScenarioEditArgs {
     freeze: boolean;
     unfreeze: boolean;
     note?: string;
-    /** `undo --edit`: the `sedit_` id to put back. */
+    /** `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;
@@ -139,7 +143,13 @@ export interface ScenarioEditArgs {
 }
 /** 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). */
+/**
+ * The `bir` MCP server's tools that only read. Offered with scenario editing
+ * on, or where the server's environment has `BIR_SCENARIO_TOOLS=read` — no
+ * longer in every session: their definitions ride along with every request a
+ * session makes, and only somebody working on a scenario ever calls them (the
+ * same answers are `bir scenario show` and `bir investigate` in a terminal).
+ */
 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"];
@@ -155,19 +165,42 @@ 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): void;
+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;
 /**
- * Undo puts one step back as it was before its newest edit (D9). Without
- * `--edit`, that is the newest entry nothing has put back and no
- * recalculation replaced — which is by construction the newest of its step.
- * An undo is itself such an entry, so a second `undo` redoes.
+ * 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[]): EditEntry | undefined;
+export declare function newestUndoable(edits: EditEntry[], step?: number): EditEntry | undefined;
 export {};
 //# sourceMappingURL=scenario-edit.d.ts.map