@basein/runner 0.3.17 → 0.3.19

package/dist/control/transcript.d.ts

@@ -34,6 +34,25 @@
  * birth time, mtime, and the bytes at its head and at the offset) and read
  * again from the start, which is exactly what the old code did every time.
  */
+/** The day the agent was told it is, and the words that told it (issue 1212). */
+export interface AgentDay {
+    /** "Today's date is Thursday, 2023-11-30 and the current time is 00:00:00." */
+    line: string;
+    /** The `YYYY-MM-DD` in the line, when it has one. */
+    day?: string;
+    /** `system`: a system prompt the host sent. `host`: the host's own date reminder. */
+    source: "system" | "host";
+}
+/**
+ * The day the agent of this session was told it is (issue 1212), as its host
+ * wrote it into the transcript: a system prompt's own "Today's date is …"
+ * first — a benchmark's "Thursday, 2023-11-30", which the agent goes by —
+ * and else the host's date reminder, this machine's day. Undefined when the
+ * transcript has neither yet: its host writes both just after the prompt
+ * hook, so the first prompt of a session finds them only when its plan
+ * starts.
+ */
+export declare function agentDayOf(transcriptPath: string | undefined): AgentDay | undefined;
 /**
  * The model's text after the message that made the tool call `toolUseId`: its
  * answer, once that call's result came back (the service's autocorrect.md

package/dist/control/transcript.js

@@ -135,6 +135,8 @@ function freshIndex(st) {
         results: [],
         messages: new Map(),
         toolUses: new Map(),
+        systemDayLine: "",
+        hostDay: "",
     };
 }
 /** Whether `idx` can be continued for a file that now looks like `st`. */
@@ -303,9 +305,35 @@ function ingest(idx, bytes) {
     if (line)
         foldLine(idx, line);
 }
+/** The line that tells the agent the day, out of a system prompt's text: "Today's date is …", "Today is …". */
+const DAY_LINE = /Today(?:['’]s date)? is [^\n]{4,200}/i;
+function dayLineIn(text) {
+    const whole = Array.isArray(text)
+        ? text.map((t) => (typeof t === "string" ? t : t && typeof t === "object" ? String(t.text ?? "") : "")).join("\n")
+        : typeof text === "string"
+            ? text
+            : "";
+    // The whole line, never cut at a full stop: "Nov. 30, 2023" has one inside.
+    return redactText(DAY_LINE.exec(whole)?.[0] ?? "").slice(0, 200);
+}
 /** What one line contributes to every answer this module gives. */
 function foldLine(idx, line) {
     idx.lineNo += 1;
+    // The day the agent was told it is (issue 1212): a system prompt's
+    // "Today's date is …", and the host's own date reminder beside it.
+    if (line.type === "attachment" && line.attachment?.type === "prompt_snapshot") {
+        const said = dayLineIn(line.attachment.systemPrompt);
+        if (said)
+            idx.systemDayLine = said;
+    }
+    else if (line.type === "api-request-shape") {
+        const said = dayLineIn(line.shape?.system);
+        if (said)
+            idx.systemDayLine = said;
+    }
+    else if (line.type === "attachment" && line.attachment?.type === "date" && typeof line.attachment.date === "string") {
+        idx.hostDay = line.attachment.date.slice(0, 10);
+    }
     const message = line.message;
     const role = message?.role ?? line.type;
     const blocks = blocksOf(line);
@@ -397,6 +425,35 @@ function foldLine(idx, line) {
         }
     }
 }
+function isoDayIn(text) {
+    const m = /(?<!\d)(\d{4})-(\d{2})-(\d{2})(?!\d)/.exec(text);
+    if (!m)
+        return undefined;
+    const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    const at = new Date(Date.UTC(y, mo - 1, d));
+    return at.getUTCFullYear() === y && at.getUTCMonth() === mo - 1 && at.getUTCDate() === d ? m[0] : undefined;
+}
+/**
+ * The day the agent of this session was told it is (issue 1212), as its host
+ * wrote it into the transcript: a system prompt's own "Today's date is …"
+ * first — a benchmark's "Thursday, 2023-11-30", which the agent goes by —
+ * and else the host's date reminder, this machine's day. Undefined when the
+ * transcript has neither yet: its host writes both just after the prompt
+ * hook, so the first prompt of a session finds them only when its plan
+ * starts.
+ */
+export function agentDayOf(transcriptPath) {
+    if (!transcriptPath)
+        return undefined;
+    const idx = indexFor(transcriptPath);
+    if (!idx)
+        return undefined;
+    if (idx.systemDayLine)
+        return { line: idx.systemDayLine, day: isoDayIn(idx.systemDayLine), source: "system" };
+    if (idx.hostDay)
+        return { line: `Today's date is ${idx.hostDay}.`, day: isoDayIn(idx.hostDay), source: "host" };
+    return undefined;
+}
 /**
  * The model's text after the message that made the tool call `toolUseId`: its
  * answer, once that call's result came back (the service's autocorrect.md

package/dist/proxy/intercept.js

@@ -140,6 +140,19 @@ export class RecordingInterceptor {
     }
     onUpstreamResponse(pending, response) {
         if (pending.method === "tools/list") {
+            // The server's tools, as it listed them (the service's autocorrect.md
+            // AC12): what a correction from an agent's answer may write a step with.
+            // Its own answer, never the rewrite below, and on a later tick.
+            if (!response.error) {
+                const result = response.result;
+                const listed = result?.tools;
+                if (Array.isArray(listed)) {
+                    const cursor = pending.params?.cursor;
+                    const next = result?.nextCursor;
+                    const page = { first: cursor === undefined || cursor === null || cursor === "", last: !(typeof next === "string" && next.length > 0) };
+                    setImmediate(() => this.session.reportTools(listed, page));
+                }
+            }
             // The only rewrite in the whole proxy, and only when a control server may
             // inject call ids into this server's calls (Phase 6). Decided by the
             // session so it does not depend on whether registration happened to beat

package/dist/proxy/session.d.ts

@@ -148,6 +148,16 @@ export declare class ProxySession {
     private queue;
     /** Steps that arrived before the tier was known. */
     private buffer;
+    /**
+     * The newest tool list the server gave (`tools/list`, every page of it;
+     * the service's autocorrect.md AC12), kept to send once bound, and the
+     * control server it went to.
+     */
+    private toolList?;
+    private toolPages;
+    private toolListSentTo?;
+    /** One later try of a tool list whose post to the control server failed. */
+    private toolRetry?;
     private lossyValue;
     private negotiation?;
     private downgrading?;
@@ -306,6 +316,19 @@ export declare class ProxySession {
      */
     private becomePassthrough;
     private buildRecorder;
+    /**
+     * One page of the server's `tools/list` answer (the service's
+     * autocorrect.md AC12): the whole list goes to the control server once its
+     * last page is in, which sends the names, descriptions and input schemas to
+     * the service when they changed. Only where this proxy records: a server
+     * nothing is recorded of sends nothing of its tools either.
+     */
+    reportTools(tools: readonly unknown[], page: {
+        first: boolean;
+        last: boolean;
+    }): void;
+    /** Send the kept tool list to the control server this proxy is bound to, once. */
+    private sendTools;
     /**
      * Record one completed `tools/call`. Fire-and-forget by contract: it is called
      * *after* the result is already on its way to the host, and it never awaits.

package/dist/proxy/session.js

@@ -47,7 +47,7 @@ import { readFile } from "node:fs/promises";
 import { resolve as resolvePath } from "node:path";
 import { ControlClient } from "../control/client.js";
 import { readDiscovery } from "../control/discovery.js";
-import { qualifyToolName } from "../control/correlation.js";
+import { newCallId, qualifyToolName } from "../control/correlation.js";
 import { projectRecord } from "../config/generate.js";
 import { installedPath, normalizePath } from "../control/paths.js";
 import { authenticate, loadCredentials, normalizeAuthUrl, resolveAuthUrl } from "../auth/client.js";
@@ -241,6 +241,16 @@ export class ProxySession {
     });
     /** Steps that arrived before the tier was known. */
     buffer = [];
+    /**
+     * The newest tool list the server gave (`tools/list`, every page of it;
+     * the service's autocorrect.md AC12), kept to send once bound, and the
+     * control server it went to.
+     */
+    toolList;
+    toolPages = [];
+    toolListSentTo;
+    /** One later try of a tool list whose post to the control server failed. */
+    toolRetry;
     lossyValue = false;
     negotiation;
     downgrading;
@@ -484,6 +494,11 @@ export class ProxySession {
         else
             logLine("tier.rebound", { ...fields, was });
         this.flushBuffer();
+        // Every (re)registration hands the list over again, also to a recorder
+        // that restarted on the same address: the control server says whether
+        // the service still needs it.
+        this.toolListSentTo = undefined;
+        this.sendTools();
         this.replayOn = registered.replay === true;
         this.pollHoldMs = registered.pollHoldMs ?? 25_000;
         // A bound proxy always has a work loop — paced to one poll every
@@ -785,6 +800,50 @@ export class ProxySession {
         }
         return new RemoteRecorder({ baseUrl, session });
     }
+    /**
+     * One page of the server's `tools/list` answer (the service's
+     * autocorrect.md AC12): the whole list goes to the control server once its
+     * last page is in, which sends the names, descriptions and input schemas to
+     * the service when they changed. Only where this proxy records: a server
+     * nothing is recorded of sends nothing of its tools either.
+     */
+    reportTools(tools, page) {
+        if (page.first)
+            this.toolPages = [];
+        this.toolPages.push(...tools.slice(0, 1_000 - this.toolPages.length));
+        if (!page.last)
+            return;
+        const list = this.toolPages;
+        this.toolPages = [];
+        // A server still starting may list nothing: the list before it stands.
+        if (list.length === 0)
+            return;
+        this.toolList = list;
+        this.toolListSentTo = undefined;
+        this.sendTools();
+    }
+    /** Send the kept tool list to the control server this proxy is bound to, once. */
+    sendTools() {
+        if (this.closing || !this.toolList || !this.recording || this.tierValue !== "bound" || !this.control)
+            return;
+        if (this.toolListSentTo === this.control)
+            return;
+        const control = this.control;
+        this.toolListSentTo = control;
+        void control.tools(this.serverName, this.toolList).then((ok) => {
+            if (ok || this.toolListSentTo !== control)
+                return;
+            this.toolListSentTo = undefined;
+            // Tried once more a little later; after that, at the next bind or list.
+            if (!this.toolRetry && !this.closing) {
+                this.toolRetry = setTimeout(() => {
+                    this.toolRetry = undefined;
+                    this.sendTools();
+                }, 30_000);
+                this.toolRetry.unref?.();
+            }
+        });
+    }
     /**
      * Record one completed `tools/call`. Fire-and-forget by contract: it is called
      * *after* the result is already on its way to the host, and it never awaits.
@@ -867,9 +926,18 @@ export class ProxySession {
         const toolError = step.isError
             ? (step.errorMessage ?? serializeCapped(redact(step.result)))
             : undefined;
+        // One id on both rows, and the failure marked (the service's review of
+        // calcscenarioautocorrect.md, item 7): the service pairs a call with its
+        // answer by it, not by the order they came in.
+        const callId = step.callId ?? newCallId();
         this.queue.push(async () => {
-            recorder.recordToolSelected(runId, pair.selected, { toolName, toolInput });
-            recorder.recordToolResponse(runId, pair.response, { toolName, toolOutput, toolError });
+            recorder.recordToolSelected(runId, pair.selected, { toolName, toolInput, metadata: { callId } });
+            recorder.recordToolResponse(runId, pair.response, {
+                toolName,
+                toolOutput,
+                toolError,
+                metadata: step.isError ? { callId, isError: true } : { callId },
+            });
             // Wait for the service to take them before the next step goes. The
             // recorder's own per-run chain is unbounded; waiting here is what makes
             // the step queue's bound apply to what is actually waiting on the

package/dist/record/recorder.d.ts

@@ -49,6 +49,29 @@ export interface RunMetrics {
     incomplete?: {
         lossy: boolean;
     };
+    /**
+     * The day the agent of this run was told it is (the service's review of
+     * calcscenarioautocorrect.md, item 1). The service checks a corrected plan
+     * against this very run, and reads its prompt with this day — not the day
+     * the run reached the service, which is years off for a benchmark and a day
+     * off around midnight. See {@link RunAgentDay}.
+     */
+    agentDay?: RunAgentDay;
+}
+/**
+ * What a run's finish says of the agent's day. Each field is left out when it
+ * is not known, and the whole object when neither is.
+ */
+export interface RunAgentDay {
+    /**
+     * The line of the agent's own system prompt that gives the date ("Today's
+     * date is Thursday, 2023-11-30 …"), as its host wrote it into the session.
+     * Never Claude Code's date reminder: that is only this machine's day. At
+     * most 400 characters.
+     */
+    said?: string;
+    /** This machine's calendar day, `YYYY-MM-DD` in its own time zone, when the run's prompt came. */
+    local?: string;
 }
 /** How long a caller is prepared to wait for {@link Recorder.flush}. */
 export interface FlushOptions {
@@ -77,10 +100,21 @@ export interface PlanCallMark {
  * the turn (R-INTENT-7). `byPlan`: the plan made this call before the agent
  * redid the task, and it is recorded first into the agent's repeat so the
  * repeat holds the whole turn (AC2). The service stores neither with a vector.
+ *
+ * `callId` is on both rows of one tool call, its `tool_selected` and its
+ * `tool_response`, and ties the two together (the service's review of
+ * calcscenarioautocorrect.md, item 7): Claude Code's `tool_use_id`, or the id
+ * the runner made for a call no hook named. Paired by tool name in the order
+ * they came, two calls of one tool made at once and answered out of order
+ * would take each other's answers. `isError` is on a `tool_response` row whose
+ * call failed — its MCP result said `isError`, or the host reported the call
+ * as failed — so a failed call is never read as one that worked.
  */
 export type StepMetadata = {
     pinnedBy?: string;
     byPlan?: PlanCallMark;
+    callId?: string;
+    isError?: boolean;
 };
 export interface Recorder {
     /**
@@ -301,13 +335,21 @@ export interface IntentMatchRequest {
     stepPosition?: number;
     /** Recordings this turn must not count hits against (R-HIT-7). */
     excludeRuns?: string[];
-    /** Per recording a plan of this turn came from, the largest position (R-OUT-6). */
+    /**
+     * Per plan of this turn: its recording, and how far it got in its own chain
+     * — the step it handed over at (a decision included), or its last step when
+     * it ran to its end (R-OUT-6). One entry per plan; the service maps each onto
+     * the recording and keeps the largest (its segmentsbreakdown.md D18).
+     */
     ranThrough?: Array<{
         runId: string;
         position: number;
         scenarioId?: string;
     }>;
-    /** Present only with `BIR_SEGMENT_ARM` (R-OUT-9, R-OUT-10). */
+    /**
+     * Present only while segment arming is on (R-OUT-9, R-OUT-10): the
+     * recorder's default from 0.3.19, absent with `BIR_SEGMENT_ARM=0`.
+     */
     acceptSegments?: boolean;
     /** Always true from this runner (R-CALL-28). */
     supportsCalls?: boolean;
@@ -460,12 +502,124 @@ export interface ExecutionReport {
      * ends; an older service drops the field.
      */
     answer?: string;
+    /**
+     * The plan's own calls of the turn, whole, sent only beside {@link answer}
+     * (the service's review of calcscenarioautocorrect.md, item 12). A step's
+     * payloads in {@link steps} are cut to 3,800 bytes, and a correction made
+     * from the answer cannot test a condition on what a long output says — a
+     * CRM list, a long series. Each output here is cut at 64 KiB, and all of
+     * them together are held to 600,000 bytes, the largest cut first
+     * (record/remote-recorder.ts, `answerCallsBody`).
+     */
+    answerCalls?: AnswerCall[];
+}
+/** One call of a plan, whole, as {@link ExecutionReport.answerCalls} carries it. */
+export interface AnswerCall {
+    /** The step's own `stepIndex`. */
+    stepIndex: number;
+    toolName: string;
+    /** What the step sent: redacted, at most 64 KiB serialized. */
+    input: Record<string, unknown>;
+    /** What came back — the tool's whole answer, as recorded — or its error. */
+    output: string;
+    /** The call failed: `output` is what it reported instead. */
+    isError?: boolean;
+}
+/**
+ * What a wrapped server says of one of its tools (MCP `annotations`), as the
+ * service takes it (the service's review of calcscenarioautocorrect.md, items
+ * 4 and 16): whether it only reads, whether it can destroy something. The
+ * service judges "is this call a change?" by these first, and by the tool's
+ * name only when its server says nothing. Only these five keys; the hints are
+ * hints, as MCP says, and a server's word only.
+ */
+export interface ToolAnnotations {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+/** One tool of a wrapped MCP server, as the service keeps it (its autocorrect.md AC12). */
+export interface ToolListEntry {
+    /** The server's own name for it. */
+    name: string;
+    /** As the agent calls it: `mcp__<server>__<tool>`. */
+    qualifiedName: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    /** What its server says of it, when it says anything. */
+    annotations?: ToolAnnotations;
 }
+/** Optional capability: a server's tool list goes to the service (AC12). A NullRecorder has none. */
+export interface ToolListReporter {
+    /**
+     * Resolves true when the service took the list. Never throws. `project` is
+     * the list's project: the first 16 hex characters of the sha256 of its
+     * folder (control/server.ts, `projectKey`), the same value every run of
+     * that project carries as `metadata.project`. Left out of the body when
+     * absent, as an older caller sends it.
+     */
+    reportTools(serverName: string, tools: readonly ToolListEntry[], project?: string): Promise<boolean>;
+}
+export declare function isToolListReporter(r: Recorder): r is Recorder & ToolListReporter;
 /** Optional capability: reporting needs a service, and a NullRecorder has none. */
 export interface ScenarioReporter {
     reportExecution(report: ExecutionReport): void;
 }
 export declare function isScenarioReporter(r: Recorder): r is Recorder & ScenarioReporter;
+/**
+ * One plan that waits for its owner (`GET /scenarios/attention`; the service's
+ * review of calcscenarioautocorrect.md, item 8): held, and not handed out, so
+ * every prompt of its task is a full agent run until somebody looks.
+ */
+export interface AttentionPlan {
+    scenarioId: string;
+    title: string;
+    /** When the hold began, ISO 8601. Null for a plan that is not held: only a correction waits. */
+    heldSince: string | null;
+    /** Why it is held; null when it is not. */
+    reason: "checking" | "rejected" | "rejected_again" | "verifying" | "verify_failed" | "verify_stale" | null;
+    /** `proposed`: a correction waits for the owner's word. */
+    correction: "proposed" | null;
+    /** The plan's recording page. */
+    url: string;
+}
+/**
+ * Optional capability: the plans of this account that need their owner, for
+ * the line a session start shows. Null whenever nothing can be said — no
+ * service, an older one (404), a slow or failing one. Never throws.
+ */
+export interface AttentionReader {
+    scenarioAttention(opts?: {
+        timeoutMs?: number;
+    }): Promise<AttentionPlan[] | null>;
+}
+export declare function isAttentionReader(r: Recorder): r is Recorder & AttentionReader;
+/** What the service answered a report that a replay was wrong. */
+export interface DisputeAnswer {
+    /** The service took the report. */
+    ok: boolean;
+    /** The plan is held now: not handed out until it is checked. */
+    held?: boolean;
+    /** Why not, in the service's own short words, or the runner's own code. */
+    why?: string;
+}
+/**
+ * Optional capability: the agent said a replay's results do not answer the
+ * request (`mcp__bir__report_wrong_result`; the service's review of
+ * calcscenarioautocorrect.md, item 19). `POST /scenarios/:id/dispute`.
+ * Never throws: every failure is an answer with `ok: false`.
+ */
+export interface ScenarioDisputer {
+    disputeScenario(scenarioId: string, report: {
+        reason: string;
+        executionId?: string;
+    }, opts?: {
+        timeoutMs?: number;
+    }): Promise<DisputeAnswer>;
+}
+export declare function isScenarioDisputer(r: Recorder): r is Recorder & ScenarioDisputer;
 /**
  * A recorder that drops everything. Used when auth is unavailable: recording is
  * best-effort, and a session must never fail because BaseIn is unreachable (§10).

package/dist/record/recorder.js

@@ -20,9 +20,18 @@ export function isServiceProber(r) {
 export function isIntentMatcher(r) {
     return typeof r.matchIntent === "function";
 }
+export function isToolListReporter(r) {
+    return typeof r.reportTools === "function";
+}
 export function isScenarioReporter(r) {
     return typeof r.reportExecution === "function";
 }
+export function isAttentionReader(r) {
+    return typeof r.scenarioAttention === "function";
+}
+export function isScenarioDisputer(r) {
+    return typeof r.disputeScenario === "function";
+}
 /**
  * A recorder that drops everything. Used when auth is unavailable: recording is
  * best-effort, and a session must never fail because BaseIn is unreachable (§10).

package/dist/record/remote-recorder.d.ts

@@ -50,7 +50,7 @@
  */
 import { type AuthSession } from "../auth/client.js";
 import { type ServiceHealth } from "../util/service-health.js";
-import type { ExecutionReport, FlushOptions, IntentMatchAnswer, IntentMatchOptions, IntentMatchRequest, Recorder, RecorderHealth, RecorderHealthReporter, RunCreation, RunMatch, RunMetrics, StartRunOptions, StepMetadata } from "./recorder.js";
+import type { AnswerCall, AttentionPlan, DisputeAnswer, ExecutionReport, FlushOptions, IntentMatchAnswer, IntentMatchOptions, IntentMatchRequest, Recorder, RecorderHealth, RecorderHealthReporter, RunCreation, RunMatch, RunMetrics, StartRunOptions, StepMetadata, ToolListEntry } from "./recorder.js";
 /**
  * Caps for the free text this recorder sends, in UTF-8 bytes. Tool payloads
  * arrive capped at 64 KiB by their producers; text never passed through one,
@@ -118,6 +118,23 @@ export interface RemoteRecorderOptions {
     /** The longest one queued send waits for a failing service ({@link COOLDOWN_WAIT_MAX_MS}). Tests shorten it. */
     cooldownWaitMaxMs?: number;
 }
+/** What one answered turn's call may carry of its output, in UTF-8 bytes (review item 12). */
+export declare const ANSWER_CALL_OUTPUT_MAX_BYTES: number;
+/** All of one report's answer calls together, serialized, in UTF-8 bytes. */
+export declare const ANSWER_CALLS_MAX_BYTES = 600000;
+/**
+ * An answered turn's calls as they are sent (the service's review of
+ * calcscenarioautocorrect.md, item 12): each input redacted again, each output
+ * redacted and cut at {@link ANSWER_CALL_OUTPUT_MAX_BYTES}, and all of them
+ * held to `maxBytes` serialized by cutting the largest outputs first — every
+ * output above one common length is cut to it, the longest length that fits.
+ * The cut is the recordings' own, "… [truncated N of M bytes]", so a reader
+ * can tell a short answer from a cut one. Undefined when there is nothing to
+ * send, or when even outputs of {@link ANSWER_CALL_OUTPUT_MIN_BYTES} would not
+ * fit (inputs that large): the service then reads the report's cut copies,
+ * as it did before, rather than half a list.
+ */
+export declare function answerCallsBody(calls: readonly AnswerCall[] | undefined, maxBytes?: number): AnswerCall[] | undefined;
 export declare class RemoteRecorder implements Recorder, RecorderHealthReporter {
     private readonly baseUrl;
     private readonly framework;
@@ -247,6 +264,47 @@ export declare class RemoteRecorder implements Recorder, RecorderHealthReporter
      * or refused in between is as lost as one before.
      */
     private incompleteOf;
+    /**
+     * One wrapped server's tool list (the service's autocorrect.md AC12): the
+     * names, descriptions and input schemas a correction from an agent's answer
+     * writes a step with. On its own lane, and never counted as a recording's
+     * lost send. Quiet towards the service's health: a list the service refuses
+     * (an older one's 404, the route's own rate limit, a fault of that route)
+     * opens no breaker the hooks wait on. Resolves true when the service took it.
+     *
+     * `project` is the list's project (review item 16): two projects with a
+     * server of one name keep a list each. An older service drops the field.
+     */
+    reportTools(serverName: string, tools: readonly ToolListEntry[], project?: string): Promise<boolean>;
+    /** The account this recorder sends for, as signed in now. */
+    accountId(): string | undefined;
+    /**
+     * The plans of this account that wait for their owner (`GET
+     * /scenarios/attention`; the service's review of calcscenarioautocorrect.md,
+     * item 8): what the line a session start shows is made of. Asked on a
+     * session start's path, so it is bounded (1.5 s by default), asked only
+     * while the service is known to answer, and quiet towards its health: a
+     * slow or refusing answer here opens no breaker the hooks wait on. Null on
+     * any failure — an older service's 404 included — and never a throw.
+     */
+    scenarioAttention(opts?: {
+        timeoutMs?: number;
+    }): Promise<AttentionPlan[] | null>;
+    /**
+     * The agent said a replay's results do not answer its request (`POST
+     * /scenarios/:scenarioId/dispute`; the service's review of
+     * calcscenarioautocorrect.md, item 19). `executionId` is the turn's
+     * execution ticket — the id its report books under at the end of the turn,
+     * so while the turn runs the service has the ticket and not yet the row.
+     * Awaited — the agent waits for one sentence back — bounded (10 s by
+     * default), and quiet towards the service's health. Never throws.
+     */
+    disputeScenario(scenarioId: string, report: {
+        reason: string;
+        executionId?: string;
+    }, opts?: {
+        timeoutMs?: number;
+    }): Promise<DisputeAnswer>;
     /**
      * Report what a matched turn cost (docs/calculatedReplay.md §11.2).
      *