@basein/runner 0.3.17 → 0.3.19

package/dist/control/ensure-hook.d.ts

@@ -49,9 +49,14 @@
  * only with enough of the budget left.
  *
  * STDOUT IS CONTEXT. For SessionStart, Claude Code adds whatever a command hook
- * prints on stdout to the model's context. So nothing is printed unless the
- * control server answered with something (today it answers `{}`), and then it
- * is the answer, verbatim, as JSON.
+ * prints on stdout to the model's context — unless it is one JSON object, which
+ * it reads as the hook's answer instead. So nothing is printed unless the
+ * control server answered with something, and then it is the answer, as one
+ * line of JSON and nothing else. The control server answers `{}`, or — when
+ * plans of the account wait for their owner (the service's review of
+ * calcscenarioautocorrect.md, item 8) — `{ "systemMessage": "bir: …" }`, a
+ * line Claude Code shows the person and never the model. Characters past ASCII
+ * are written as `\u` escapes, so a console code page cannot garble the line.
  */
 import { type EnsureOptions } from "./daemon.js";
 /**
@@ -93,6 +98,12 @@ export interface EnsureHookOptions extends EnsureOptions {
      */
     overrideCheck?: ((projectCwd: string) => StaleOverrides) | false;
 }
+/**
+ * `value` as one line of JSON whose every character past ASCII is a `\u`
+ * escape: the same JSON to any reader, and nothing a console's code page can
+ * turn into something else on the way to Claude Code.
+ */
+export declare function asciiJson(value: unknown): string;
 /**
  * Run the hook for `cwd`. Resolves the exit code, which is always 0.
  */

package/dist/control/ensure-hook.js

@@ -49,9 +49,14 @@
  * only with enough of the budget left.
  *
  * STDOUT IS CONTEXT. For SessionStart, Claude Code adds whatever a command hook
- * prints on stdout to the model's context. So nothing is printed unless the
- * control server answered with something (today it answers `{}`), and then it
- * is the answer, verbatim, as JSON.
+ * prints on stdout to the model's context — unless it is one JSON object, which
+ * it reads as the hook's answer instead. So nothing is printed unless the
+ * control server answered with something, and then it is the answer, as one
+ * line of JSON and nothing else. The control server answers `{}`, or — when
+ * plans of the account wait for their owner (the service's review of
+ * calcscenarioautocorrect.md, item 8) — `{ "systemMessage": "bir: …" }`, a
+ * line Claude Code shows the person and never the model. Characters past ASCII
+ * are written as `\u` escapes, so a console code page cannot garble the line.
  */
 import { appendFileSync } from "node:fs";
 import { Console } from "node:console";
@@ -152,6 +157,14 @@ function reportStaleOverrides(projectCwd, logFile, msLeft, check) {
         /* a check that failed leaves things as they were; `bir doctor` names what is stale */
     }
 }
+/**
+ * `value` as one line of JSON whose every character past ASCII is a `\u`
+ * escape: the same JSON to any reader, and nothing a console's code page can
+ * turn into something else on the way to Claude Code.
+ */
+export function asciiJson(value) {
+    return JSON.stringify(value).replace(/[\u007f-￿]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
 /** True when this process's own environment switches the runner off (`BIR_OFF=1` or `true`). */
 function offInThisEnvironment() {
     const value = (process.env.BIR_OFF ?? "").trim().toLowerCase();
@@ -228,8 +241,8 @@ export async function runEnsureHook(cwd, opts = {}) {
             signal: timeoutSignal(Math.max(300, Math.min(RELAY_TIMEOUT_MS, left()))),
         });
         const answer = (await res.json().catch(() => ({})));
-        if (res.ok && answer && typeof answer === "object" && Object.keys(answer).length > 0) {
-            stdout.write(JSON.stringify(answer));
+        if (res.ok && answer && typeof answer === "object" && !Array.isArray(answer) && Object.keys(answer).length > 0) {
+            stdout.write(asciiJson(answer));
         }
     }
     catch (err) {

package/dist/control/recorder-main.d.ts

@@ -52,6 +52,21 @@ export declare function derivationKey(daemon?: boolean): {
     apiKey?: string;
     source?: string;
 };
+/**
+ * `BIR_SEGMENT_ARM`: whether a segment the service hands out may run mid-task.
+ * On unless it is `0`, from runner 0.3.19 (the service's segmentsbreakdown.md
+ * SB-21): segments found by repeated work, and the halves after a plan's
+ * decision. `0` is observe-only: what would have armed is logged, and nothing
+ * is replaced. While it is on, whole plans may start mid-task by intent too:
+ * `BIR_INTENT_ARM` follows it unless that is set.
+ */
+export declare function segmentArmFromEnv(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * What the `replay.enabled` startup line says segments do. A segment starts
+ * only where the probe is waited on, so `BIR_INTENT_ARM=0` starts nothing
+ * mid-task, segments included — the rule `bir doctor` words from /health.
+ */
+export declare function segmentsAtStartup(segmentArm: boolean, env?: NodeJS.ProcessEnv): string;
 /** Where the two replay switches came from, for `/health` and `bir doctor`. */
 export type ReplaySource = "env" | "sidecar" | "default";
 /** What a recorder still serves (K4, `ControlServer.activity()`). */

package/dist/control/recorder-main.js

@@ -152,6 +152,27 @@ export function derivationKey(daemon = process.env[DAEMON_ENV] === "1") {
     }
     return {};
 }
+/**
+ * `BIR_SEGMENT_ARM`: whether a segment the service hands out may run mid-task.
+ * On unless it is `0`, from runner 0.3.19 (the service's segmentsbreakdown.md
+ * SB-21): segments found by repeated work, and the halves after a plan's
+ * decision. `0` is observe-only: what would have armed is logged, and nothing
+ * is replaced. While it is on, whole plans may start mid-task by intent too:
+ * `BIR_INTENT_ARM` follows it unless that is set.
+ */
+export function segmentArmFromEnv(env = process.env) {
+    return env.BIR_SEGMENT_ARM !== "0";
+}
+/**
+ * What the `replay.enabled` startup line says segments do. A segment starts
+ * only where the probe is waited on, so `BIR_INTENT_ARM=0` starts nothing
+ * mid-task, segments included — the rule `bir doctor` words from /health.
+ */
+export function segmentsAtStartup(segmentArm, env = process.env) {
+    if (!segmentArm)
+        return "observed only (BIR_SEGMENT_ARM=0)";
+    return env.BIR_INTENT_ARM === "0" ? "observed only (BIR_INTENT_ARM=0)" : "run mid-task";
+}
 /**
  * Assemble the replay configuration (docs/calculatedReplay.md §5.3 of the guide).
  *
@@ -204,19 +225,21 @@ function buildReplayOptions(keeper, policy, key) {
         intentMatch: {
             enabled: process.env.BIR_INTENT_MATCH !== "0",
             // The probe's own ceiling, not a wait on the hook's path: `PreToolUse`
-            // sends it and answers without it (hit counting only) unless arming is
-            // on (BIR_SEGMENT_ARM=1 or BIR_INTENT_ARM=1), and then waits at most
+            // waits for it only while arming is on — the default, unless
+            // BIR_SEGMENT_ARM=0 or BIR_INTENT_ARM=0 — and then at most
             // BIR_INTENT_ARM_BUDGET_MS (500 ms), never while the service is failing
-            // (control/server.ts). 4 000 leaves a request whose best segment lands
-            // in the not-clear band its one live question under the service's own
-            // 2 500 ms attempt (segmented.md R-HIT-11).
+            // (control/server.ts); otherwise it answers without it (hit counting
+            // only). 4 000 leaves a request whose best segment lands in the
+            // not-clear band its one live question under the service's own 2 500 ms
+            // attempt (segmented.md R-HIT-11).
             budgetMs: positiveInt(process.env.BIR_INTENT_MATCH_BUDGET_MS, 4_000),
             maxPerTurn: positiveInt(process.env.BIR_INTENT_MATCHES_PER_TURN, 3),
             maxRequestsPerTurn: positiveInt(process.env.BIR_INTENT_REQUESTS_PER_TURN, 40),
         },
-        // Observe-only until an operator has read the logs and turned it on
-        // (segmented.md R-OUT-10, R-LIFE-7). Arming is never the way to find out.
-        segmentArm: process.env.BIR_SEGMENT_ARM === "1",
+        // On by default from 0.3.19 (the service's segmentsbreakdown.md SB-21): a
+        // plan that stops at its decision hands the rest to segments of each half,
+        // and they run only mid-task. BIR_SEGMENT_ARM=0 brings back observe-only.
+        segmentArm: segmentArmFromEnv(),
         // Both read live, never captured (C5). The recorder signs in after it
         // listens, refreshes the token as the session outlives it, and may sign
         // in or out while it runs; replay reads whatever holds *now*. The old
@@ -247,6 +270,8 @@ function buildReplayOptions(keeper, policy, key) {
                     ? "the service"
                     : "recorded sample values — sign in, or a scenario with a target will not run"),
             intentMatch: opts.intentMatch?.enabled ? "on" : "off",
+            // Whether a segment the service hands out runs, or is only logged.
+            segments: segmentsAtStartup(opts.segmentArm === true),
             source,
             why: "a prompt that matches a calculated scenario runs it: the scenario's own steps run without a " +
                 "permission prompt of their own (never in plan mode); every other tool call is asked about as " +

package/dist/control/server.d.ts

@@ -24,9 +24,26 @@
  * accepts unauthenticated step reports is a local exfiltration channel.
  */
 import { type IntentSource } from "./transcript.js";
-import { type Recorder } from "../record/recorder.js";
+import { type AttentionPlan, type Recorder } from "../record/recorder.js";
 import { type ReplayOptions } from "../replay/controller.js";
 import { type ServiceHealth } from "../util/service-health.js";
+/**
+ * The project a run or a tool list belongs to (the service's review of
+ * calcscenarioautocorrect.md, item 16): the first 16 hex characters of the
+ * sha256 of its folder, made absolute and — on Windows — lower-cased with
+ * forward slashes, as the discovery file's key is (paths.ts, `controlKey`).
+ * The service only compares it, so a plan's recording finds its own
+ * project's tools and never another project's server of the same name.
+ */
+export declare function projectKey(dir: string): string;
+/**
+ * The one line a session start shows the person (review item 8): which plan
+ * waits, for how long, why, and where to look —
+ * `bir: a plan needs you — "Check engaged users and reassign leads" held for 3 days, a correction is waiting: <url>`
+ * — and with more than one, how many, and the first one's page. A plan that
+ * is not held, whose correction waits, says only that.
+ */
+export declare function attentionText(plans: readonly AttentionPlan[], now?: number): string | undefined;
 /**
  * The prompt match gate (see {@link ControlServer.armFromMatch}). A match that
  * answered slower than `slowMs` (`BIR_MATCH_SLOW_MS`), or not inside its
@@ -259,12 +276,13 @@ export interface ControlServerOptions {
      * (fallbk.md §Runner 4).
      *
      * Arming there means *waiting* there, on every unsteered tool call, for a
-     * service round trip — so by default the probe is sent without waiting, for
-     * hit counting only, and nothing arms mid-turn. It waits (at most
-     * `BIR_INTENT_ARM_BUDGET_MS`, 500 ms, and never while the service is failing)
-     * when segment arming is on (`BIR_SEGMENT_ARM=1`), or when `BIR_INTENT_ARM=1`
-     * asks for whole-scenario intent arming as before. `BIR_INTENT_ARM=0` never
-     * waits.
+     * service round trip. It waits (at most `BIR_INTENT_ARM_BUDGET_MS`, 500 ms,
+     * and never while the service is failing) when segment arming is on — the
+     * recorder's default from 0.3.19, `BIR_SEGMENT_ARM` unset or `1` — or when
+     * `BIR_INTENT_ARM=1` asks for whole-scenario intent arming. `BIR_INTENT_ARM=0`
+     * never waits. Otherwise, as in a server built with neither (a test, an
+     * embedder), the probe is sent without waiting, for hit counting only, and
+     * nothing arms mid-turn.
      */
     intentArm?: boolean;
     /**
@@ -311,6 +329,20 @@ export declare class ControlServer {
     private readonly proxySessions;
     /** `run_scenario` pres not yet consumed by a `/scenario/run`, oldest first. */
     private directCalls;
+    /**
+     * `report_wrong_result` pres not yet consumed by a `/scenario/dispute`,
+     * oldest first (review item 19): how a report from `bir-scenario`, which is
+     * never told its session, finds the session — and so the plan — it is about.
+     */
+    private reportCalls;
+    /** Plans the agent said were wrong, and the service's answer — on its way, or in. */
+    private readonly disputed;
+    /**
+     * The plans that need their owner, by account, as the service last listed
+     * them (`GET /scenarios/attention`, review item 8), and the ask still on its
+     * way. Null is "nothing can be said": no service, an older one, a failure.
+     */
+    private readonly attention;
     /** Plans a `/scenario/run` is executing right now: one run per plan. */
     private readonly runningPlans;
     /**
@@ -572,6 +604,16 @@ export declare class ControlServer {
      */
     private ensureRun;
     private runMetadata;
+    /**
+     * The project key of everything this recorder sends (review item 16): its
+     * runs and its tool lists. The folder this recorder serves — the one its
+     * discovery file is keyed by and its hooks are installed in — and not a
+     * session's `cwd`: that follows the agent's `cd` from turn to turn, and a
+     * tool list is sent when its proxy starts, before any of its calls ties it
+     * to a session. The service matches a plan's recording to its tools by
+     * equality, so both sides must hash the same folder.
+     */
+    private projectKeyHere;
     /**
      * A similar-prompt hit means the service created no run, so every later step
      * post would 404. Stop recording it — that half is v1 and is mandatory, and
@@ -668,6 +710,16 @@ export declare class ControlServer {
      * is none, and a `bir-scenario` must have proved it serves the tool.
      */
     private deliveryToolAvailable;
+    /**
+     * Whether a running `bir-scenario` here serves `report_wrong_result` right
+     * now (review item 19): one that is not off said so in its hello. What a
+     * bundle delivered beside a call of the agent's own (a divergence) is laid
+     * out by: such a bundle forbids every tool call but this one. A direct
+     * plan's bundle goes by its own `bir-scenario`'s word instead, which came
+     * with its `/scenario/run` (see {@link onScenarioRun}). Configured is not
+     * connected, as for the delivery tool.
+     */
+    private reportToolServed;
     /**
      * Whether this project's configuration has the `bir` server, as far as
      * anything here knows: a hook that named one of its tools, the caller's
@@ -681,6 +733,25 @@ export declare class ControlServer {
      * only — no other I/O.
      */
     private liveHellos;
+    /**
+     * The tool list of each wrapped server last sent to the service, by
+     * account, project and server (AC12; review item 16): its hash, when, and
+     * whether the service took it (null while the send is on its way).
+     */
+    private readonly toolListsSent;
+    /**
+     * `POST /proxy/tools` — a proxy's server listed its tools (`tools/list`;
+     * the service's autocorrect.md AC12). Its names, descriptions, input
+     * schemas and what it says of each tool (`annotations`) go to the service —
+     * secret-shaped text taken out, and within what the service keeps — with
+     * the project they are of ({@link projectKeyHere}, the key every run here
+     * carries). Sent when the list changed since that server's last one for
+     * this account and project, when the last send failed ten minutes ago, or
+     * six hours after the last one the service took. `bir off`, and a session
+     * started with BIR_OFF=1, send nothing, as for a step. Always `{ ok: true }`;
+     * never slow.
+     */
+    private onProxyTools;
     /**
      * `POST /scenario/hello` — a running `bir-scenario` saying what it serves
      * (K3): on `initialize`, on `tools/list`, when its off state flips and every
@@ -689,6 +760,42 @@ export declare class ControlServer {
      * and is not off still runs. Always `{ ok: true }`; never slow.
      */
     private onScenarioHello;
+    /** Remember a `report_wrong_result` pre (see {@link reportCalls}): a few, and only for a while. */
+    private noteReportCall;
+    /**
+     * `POST /scenario/dispute` — the agent said, through `bir`'s
+     * `report_wrong_result`, that a replay's results do not answer its request
+     * (the service's review of calcscenarioautocorrect.md, item 19): the plan
+     * took the wrong half of an "if … otherwise", or acted on the wrong item. A
+     * wrong half is caught only when the agent says so, and until now there was
+     * no way to say it but in an answer nobody might read.
+     *
+     * WHOSE PLAN. The session is the one whose `PreToolUse` for the tool carried
+     * the request's `toolUseId` (`bir-scenario` forwards the host's id for the
+     * call, as for `run_scenario`); without one, the one session where such a
+     * call is waiting; without that either, the one session whose plan ran in
+     * the last half hour. Never a guess between two. The plan is the newest one
+     * that ran in that session's latest turn with a plan: this turn's, or the
+     * one before it.
+     *
+     * WHAT GOES. `POST /scenarios/:scenarioId/dispute` with the reason, `by:
+     * "agent"`, and the turn's execution ticket as `executionId` — the id its
+     * report books under when the turn ends, so the service may well have the
+     * ticket and not yet the row. Once per plan and turn: a second report of the
+     * same plan is answered from the first. Nothing here undoes anything.
+     *
+     * Answers `{ ok, held?, why? }` for `bir-scenario` to put in one sentence.
+     * Never throws, and is never slow beyond the service's own bound.
+     */
+    private onScenarioDispute;
+    /** The session a `/scenario/dispute` is about (see {@link onScenarioDispute}), or undefined. */
+    private sessionForDispute;
+    /**
+     * The plan a report of a wrong replay is about: the newest that ran — a
+     * step of it did its work — in the session's latest turn with one, this
+     * turn or the one before it.
+     */
+    private disputedPlan;
     /**
      * Re-read whether this project configures the `bir` server — only when
      * ~/.claude.json or .mcp.json changed since the last read. A file the host is
@@ -713,6 +820,20 @@ export declare class ControlServer {
      * not Claude Code, and undefined when it is.
      */
     private hostContext;
+    /**
+     * The day this session's agent was told it is (issue 1212), read from its
+     * transcript each time it is asked. A session of another host has none.
+     */
+    private agentDayFor;
+    /**
+     * What a run's finish says of its agent's day (the service's review of
+     * calcscenarioautocorrect.md, item 1): the line of the session's system
+     * prompt that gives the date — never Claude Code's own date reminder, which
+     * is only this machine's day — and this machine's day when the turn's prompt
+     * came. The service checks a corrected plan against this run, and reads its
+     * prompt with this day, as a replay would have. Undefined with neither.
+     */
+    private runAgentDay;
     /**
      * The earlier tool results the reading of new values may look at: this
      * prompt's own, from the transcript — and so none for a plan that is
@@ -801,6 +922,20 @@ export declare class ControlServer {
     /** Transcript cost since `mark`; unmeasured (and zero) without one, or with a model that has no price. */
     private costSince;
     private reportExecution;
+    /**
+     * The plan's own calls of the turn, whole, as an answered turn's report
+     * carries them (the service's review of calcscenarioautocorrect.md, item
+     * 12): what each step sent and what came back, as they were kept for the
+     * turn (replay/controller.ts, `TurnCall`) — in a recording's own form,
+     * redacted and capped at 64 KiB apiece, as a redo's copies are (AC2) —
+     * where the report's own copies have 3,800 bytes. The calls of a called sub-task are
+     * left out: their step numbers are the sub-task's own, and would read as the
+     * plan's steps of the same number. `kept` is what the turn kept, taken while
+     * the seal still had it; this runs after the answer's wait, off the hook's
+     * path. The recorder cuts them to what one report may carry when it sends
+     * them.
+     */
+    private answerCallsOf;
     /**
      * Seal the session's run now, and drain it to the service in the background.
      *
@@ -831,6 +966,26 @@ export declare class ControlServer {
      */
     private drainRun;
     private onSessionStart;
+    /**
+     * The line a session start shows the person when plans of this account
+     * wait for their owner (`GET /scenarios/attention`; the service's review of
+     * calcscenarioautocorrect.md, item 8), or undefined. A `systemMessage`:
+     * Claude Code shows it to the person and adds nothing to the model's
+     * context. Asked at most once in {@link ATTENTION_CACHE_MS} per account (in
+     * {@link ATTENTION_RETRY_MS} when it could say nothing), waited for at most
+     * {@link ATTENTION_WAIT_MS}, and never while the service is failing; any
+     * failure says nothing. Not after a compaction — the
+     * session is mid-work, and was told at its start — and never in a session
+     * of another host, whose adapter shows a person nothing.
+     */
+    private attentionLine;
+    /**
+     * This account's plans that need their owner: the cached answer while it is
+     * fresh, else the service's, waited for no longer than
+     * {@link ATTENTION_WAIT_MS}. An answer that comes later still fills the
+     * cache for the next session start. One ask at a time per account.
+     */
+    private attentionFor;
     private onPrompt;
     /**
      * `PreToolUse`. Two shapes of answer:
@@ -1000,14 +1155,19 @@ export declare class ControlServer {
      */
     private excludeRunsFor;
     /**
-     * Per recording a plan of this turn came from, how far that plan got
-     * (segmented.md R-OUT-6).
+     * Per plan of this turn, its recording and how far the plan got in its own
+     * chain (segmented.md R-OUT-6).
      *
      * The server uses it to refuse a segment that starts *before* where this turn
      * already is: re-running steps the turn has just done is worse than not
-     * replaying at all. The largest position per recording wins, and a plan
-     * declined for anything but a known-bad first step reports nothing — it ran
-     * none of the recording, so it blocks none of it.
+     * replaying at all. The position is the plan's own: the step it handed over
+     * at (its decision included), or its last step when it ran to its end. The
+     * server maps it onto the recording — a segment's first position, a
+     * decision's step before it — and takes the largest per recording (the
+     * service's segmentsbreakdown.md D18). One entry per plan, so that two plans
+     * of one recording, whose own positions are on different scales, never
+     * hide each other. A plan declined for anything but a known-bad first step
+     * reports nothing — it ran none of the recording, so it blocks none of it.
      *
      * Rebuilt on every probe rather than cached: a plan that hands over between
      * two calls changes the answer.
@@ -1058,6 +1218,16 @@ export declare class ControlServer {
      * whose intent-armed plan handed over is recording the model's work anyway.
      */
     private noteHandover;
+    /**
+     * Drop a fragment scheduled at a decision (the service's
+     * segmentsbreakdown.md SB-16) when a plan the intent check armed takes the
+     * agent's next call: what follows is that plan's half, not the other one,
+     * and recorded as the other half it would become a wrong segment C. Cleared
+     * rather than ended, so a later hand-over of that plan schedules its own
+     * fragment, as any plan's does in a turn with none. Any other fragment is
+     * left as it is.
+     */
+    private dropDecisionFragment;
     /**
      * Open the fragment run and record from this call on (fallbk.md D7).
      *
@@ -1353,7 +1523,16 @@ export declare class ControlServer {
     private soleCandidate;
     /** Record the merged pair for a correlation and latch it against re-entry. */
     private settle;
-    /** The one place a tool step pair is written. Redaction and caps live here. */
+    /**
+     * The one place a tool step pair is written. Redaction and caps live here.
+     *
+     * Both rows carry the call's id (`metadata.callId`, review item 7) — the
+     * caller's, or one minted here for a call no hook named — and the answer
+     * of a call that failed says so (`metadata.isError`). The service pairs a
+     * call with its answer by that id, where it used to pair them by tool name
+     * in the order they came: two calls of one tool at once, answered out of
+     * order, took each other's answers.
+     */
     private record;
 }
 /**