@basein/runner 0.3.17 → 0.3.18

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
@@ -311,6 +328,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 +603,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 +709,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 +732,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 +759,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 +819,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 +921,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 +965,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:
@@ -1353,7 +1507,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;
 }
 /**