@basein/runner 0.3.26 → 0.3.28

package/dist/control/server.js

@@ -31,8 +31,9 @@ import { BIR_CALL_ID, fingerprint, newCallId, parseQualifiedName, qualifyToolNam
 import { StepIndexAllocator } from "./ordering.js";
 import { pidAlive } from "./discovery.js";
 import { pinCompatible } from "./pin-guard.js";
-import { agentDayOf, answerBeforePrompt, contextForToolUse, intentForToolUse, markTranscriptUsage, promptCount, recentToolResults, sessionTranscriptPath, settledLastAssistantText, settledTextAfterToolUse, settledTurnEnd, thinkingForToolUse, usageBetween, usageSince, } from "./transcript.js";
+import { agentDayOf, answerBeforePrompt, callsBetween, contextForToolUse, intentForToolUse, markTranscriptUsage, promptCount, recentToolResults, sessionTranscriptPath, settledLastAssistantText, settledTextAfterToolUse, settledTurnEnd, thinkingForToolUse, usageBetween, usageSince, } from "./transcript.js";
 import { isHousekeepingCall } from "../record/housekeeping.js";
+import { readsOnlyCall } from "../replay/reads-only.js";
 import { asSent, userText } from "../record/prompt-text.js";
 import { redact, redactText } from "../record/redact.js";
 import { DEFAULT_MAX_STRING_BYTES, serializeCapped, truncateString, truncateStrings, } from "../record/truncate.js";
@@ -458,6 +459,24 @@ const HEALTH_SESSIONS_MAX = 50;
 const HANDBACK_NOTE = "[BaseInstRunner calculated replay] The recorded sequence is no longer being supplied: carry on with the task yourself, choosing each tool call's arguments from what you have seen so far.";
 /** What the model hears once a direct plan it never asked to run is retired. */
 const DIRECT_SKIPPED_NOTE = "[BaseInstRunner calculated replay] The recorded scenario is not being run for this request: carry on with the task yourself.";
+/**
+ * What the model hears, once, after its first call that only looks while a
+ * direct plan waits for `run_scenario` (B2 is11.md): the call did not cancel
+ * the plan, the steps take this request's values — named, where the reading
+ * named them — and a change made first would. In is11 the model had checked
+ * its notes because the note named the recording's person.
+ */
+function directWaitingNote(values) {
+    return [
+        "[BaseInstRunner calculated replay] The recorded sequence is still ready for this request:",
+        "a call that only reads does not cancel it.",
+        values
+            ? `Its steps take this request's values, not the recording's: ${values}.`
+            : "Its steps take this request's values, not the recording's.",
+        "Call mcp__bir__run_scenario next, before any call that changes something:",
+        "after a change of your own it is not run.",
+    ].join("\n");
+}
 /** What a second `run_scenario` for a plan that is already running is told. */
 const ALREADY_RUNNING = "this scenario is already running for this turn — its results come back on the first run_scenario call; do not call it again or repeat its steps";
 /** Request bodies past this are read and discarded, never buffered. */
@@ -690,6 +709,22 @@ function priceUsage(usage) {
         ...(rateUnknown.length > 0 ? { rateUnknown } : {}),
     };
 }
+/**
+ * The tokens of a usage list — the one its cost was priced from — under the
+ * names an execution report's `turn` gives them (the service's
+ * learningPhase.md LP11): every cache write, the 1-hour ones among them, in
+ * `cacheWriteTokens`.
+ */
+function turnTokens(usage) {
+    const sum = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 };
+    for (const u of usage) {
+        sum.inputTokens += u.inputTokens;
+        sum.outputTokens += u.outputTokens;
+        sum.cacheReadTokens += u.cacheReadTokens;
+        sum.cacheWriteTokens += u.cacheCreationTokens;
+    }
+    return sum;
+}
 /**
  * What `/health` answers as `hostFields`: how much of another host's protocol
  * this recorder understands. An adapter reads it to know which fields it may
@@ -2511,6 +2546,13 @@ export class ControlServer {
      * whether the service took it (null while the send is on its way).
      */
     toolListsSent = new Map();
+    /**
+     * What each wrapped server says of its tools (MCP `annotations`), by the
+     * name the agent calls them: whether a call only looks, for a direct plan
+     * waiting through it (B2 is11.md). A server's word beats any guess from the
+     * name (replay/reads-only.ts). Kept from the lists proxies report.
+     */
+    toolHints = new Map();
     /**
      * `POST /proxy/tools` — a proxy's server listed its tools (`tools/list`;
      * the service's autocorrect.md AC12). Its names, descriptions, input
@@ -2530,12 +2572,26 @@ export class ControlServer {
         if (this.isSessionOff(boundTo))
             return { ok: true, off: true };
         const serverName = typeof body.serverName === "string" ? body.serverName.trim().slice(0, 200) : "";
-        if (!serverName || !Array.isArray(body.tools) || !isToolListReporter(this.recorder))
+        if (!serverName || !Array.isArray(body.tools))
             return { ok: true };
         const tools = toolListForService(serverName, body.tools);
         // A server still starting may list nothing: that replaces no list.
         if (tools.length === 0)
             return { ok: true };
+        for (const t of tools) {
+            if (t.annotations)
+                this.toolHints.set(t.qualifiedName, t.annotations);
+            else
+                this.toolHints.delete(t.qualifiedName);
+        }
+        while (this.toolHints.size > 4_096) {
+            const oldest = this.toolHints.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.toolHints.delete(oldest);
+        }
+        if (!isToolListReporter(this.recorder))
+            return { ok: true };
         const project = this.projectKeyHere();
         const key = `${accountOf(this.recorder) ?? ""}\u0000${project}\u0000${serverName}`;
         const hash = createHash("sha256").update(JSON.stringify(tools)).digest("hex");
@@ -3240,6 +3296,51 @@ export class ControlServer {
             return { usd: 0, measured: false };
         return priceUsage(until ? usageBetween(mark, until) : usageSince(session.transcriptPath, mark));
     }
+    /**
+     * Where a turn's tokens end, for its reports' `turn` (the service's
+     * learningPhase.md LP11): `until`, the next turn's mark, when that turn has
+     * begun; a mark taken now otherwise, as {@link costSince} reads the
+     * transcript now. Undefined for another host, which has no transcript, and
+     * when the transcript cannot be read. Never throws.
+     */
+    tokensEnd(session, until) {
+        if (otherHost(session))
+            return undefined;
+        if (until)
+            return until;
+        try {
+            return markTranscriptUsage(session.transcriptPath);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * The model calls and tokens of one report's window, for its `turn` (the
+     * service's learningPhase.md LP11): the window its cost is read for, from
+     * `from` to `end` — the plan's own retire, or the next plan's arm — and
+     * otherwise to `to` ({@link tokensEnd}). Another host's run has the tokens
+     * it handed over and no count of its calls, and only `whole`: for the
+     * report that bills the run, when one report does. Undefined when nothing
+     * can be said — no mark, no transcript — and then the report's `turn` says
+     * null. Never throws.
+     */
+    turnUsage(session, run, from, end, to, whole) {
+        try {
+            if (otherHost(session)) {
+                if (!whole || !run.hostUsage?.length)
+                    return undefined;
+                return { modelCalls: null, ...turnTokens(run.hostUsage) };
+            }
+            const last = end ?? to;
+            if (from === undefined || last === undefined)
+                return undefined;
+            return { modelCalls: callsBetween(from, last) ?? null, ...turnTokens(usageBetween(from, last)) };
+        }
+        catch {
+            return undefined;
+        }
+    }
     reportExecution(session, run, durationMs, cost, 
     /** The run was closed before its task ended for the caller (another host only). */
     cutShort = false, 
@@ -3256,6 +3357,11 @@ export class ControlServer {
         // Another host hands over one number for the whole run. It cannot be
         // split between two plans, so with more than one neither is measured.
         const unsplit = otherHost(session) && states.length > 1;
+        // Where the turn's tokens end, read once for every report's `turn` (LP11):
+        // the next turn's mark when that turn has begun, the transcript as it is
+        // now otherwise — as the cost was read a moment ago. Only for a turn that
+        // has a report to send it with.
+        const tokensTo = states.length > 0 || run.lateMatch ? this.tokensEnd(session, until) : undefined;
         // The plan ran to its end and the agent redid the task in a repeat the
         // service took (newestRun.md N7): the prompt plan's report says so, with
         // the repeat's id and the agent's own calls in it (autocorrect.md AC1).
@@ -3342,6 +3448,8 @@ export class ControlServer {
                 redoneBy: state === prompt && state.ranToEnd === true ? redoneBy : undefined,
                 chainDeriveUsd,
                 booksOwnSaving: booksOwn(state),
+                // The model calls and tokens of the same window as the cost above.
+                usage: this.turnUsage(session, run, state.armedBy === "intent" ? state.usageMark : run.usageMark, end, tokensTo, state.armedBy !== "intent" && !unsplit),
             });
             if (!report)
                 return;
@@ -3376,7 +3484,15 @@ export class ControlServer {
                     .catch(() => "")
                     .then((answer) => {
                     const calls = answer ? this.answerCallsOf(state.scenarioId, kept) : [];
-                    this.queue.push(() => recorder.reportExecution(answer ? { ...report, answer, ...(calls.length > 0 ? { answerCalls: calls } : {}) } : report));
+                    this.queue.push(() => recorder.reportExecution(answer
+                        ? {
+                            ...report,
+                            answer,
+                            ...(calls.length > 0 ? { answerCalls: calls } : {}),
+                            // How long the answer is, whole: the report carries 8 KiB of it (LP11).
+                            ...(report.turn ? { turn: { ...report.turn, answerChars: answer.length } } : {}),
+                        }
+                        : report));
                 });
                 this.holdSeal(run, sent);
                 return;
@@ -3398,6 +3514,8 @@ export class ControlServer {
                 siblings: [...states, late],
                 runId: run.runId,
                 cutShort: cutShort || undefined,
+                // The turn's own tokens only when its cost is this report's too.
+                usage: alone ? this.turnUsage(session, run, run.usageMark, undefined, tokensTo, !unsplit) : undefined,
             });
             if (report)
                 this.queue.push(() => recorder.reportExecution(report));
@@ -3837,6 +3955,8 @@ export class ControlServer {
         const live = this.livePlan(run);
         /** `run_scenario` for this session's own announced direct plan: allowed, see below. */
         let allowDirect = false;
+        /** A call that only looks, which a direct plan waits through (B2 is11.md): it runs as written. */
+        let waitedRead = false;
         if (this.replay.isDirectTool(toolName)) {
             // `run_scenario` with no live plan does nothing but answer "no scenario
             // is armed". Recorded, that answer is a failed tool call, and a recording
@@ -3865,19 +3985,43 @@ export class ControlServer {
             // refused (the user said no, or a rule denied it) or it failed on the way.
             // Refused means refused. The plan retires without running anything — it
             // must not come back as a divergence that runs every step unattended.
-            this.vetoPlan(run, live, "run_scenario was called but never reached the runner — refused or failed");
+            this.vetoPlan(run, live, "run_scenario was called but never reached the runner — refused or failed", "run_refused");
         }
         else if (live?.mode === "direct" && !live.directRequested && !live.running && !this.runningPlans.has(live)) {
-            // A direct plan whose first call is not `run_scenario`, and which never
-            // asked for it. The likeliest reason is that the model has no such tool
-            // — the bir server failed to start, was disabled in /mcp, or lists
-            // nothing — and a divergence would then execute every step, writes
-            // included, inside this hook with no permission prompt, and deny the
+            // A direct plan whose next call is not `run_scenario`, and which never
+            // asked for it. Nothing of the plan ever runs in this hook in its place:
+            // when the model has no such tool — the bir server failed to start, was
+            // disabled in /mcp, or lists nothing — a divergence would execute every
+            // step, writes included, with no permission prompt, and deny the
             // model's call: a broken delivery tool turned into an unattended run.
-            // The plan retires running nothing; this call runs as written, and the
-            // model hears on its PostToolUse that the task is its own.
-            this.vetoPlan(run, live, `the model's first call was ${toolName}, not run_scenario`);
-            run.handback = DIRECT_SKIPPED_NOTE;
+            //
+            // A call that only looks does not retire the plan (B2 is11.md): it runs
+            // as written, and the plan waits for `run_scenario`, told to the model
+            // once on this call's PostToolUse. In is11 the model checked its own
+            // notes first, because the note named the recording's person, and
+            // losing the plan there cost a whole agent run for a value the steps
+            // take from the request anyway. The first call that may change
+            // something retires it, running nothing: run after the model's own
+            // change, the plan could do the same work twice. That call runs as
+            // written, and the model hears on its PostToolUse that the task is its
+            // own.
+            if (readsOnlyCall(toolName, modelArgs, this.toolHints.get(toolName))) {
+                waitedRead = true;
+                live.readsWaited = (live.readsWaited ?? 0) + 1;
+                if (live.readsWaited === 1) {
+                    run.handback = directWaitingNote(live.plan?.requestValues());
+                    logLine("replay.direct_waits", {
+                        run: run.runId,
+                        scenario: live.scenarioId ?? undefined,
+                        tool: toolName,
+                        why: "the model's first call only reads — it runs as written, and the plan waits for run_scenario",
+                    });
+                }
+            }
+            else {
+                this.vetoPlan(run, live, `the model's first call that may change something was ${toolName}, not run_scenario${live.readsWaited ? ` (after ${live.readsWaited} that only read)` : ""}`, "changed_first");
+                run.handback = DIRECT_SKIPPED_NOTE;
+            }
         }
         const agentId = payload.agent_id ?? session.agentId;
         // The real intent, read from every line sharing this message's id
@@ -3928,6 +4072,7 @@ export class ControlServer {
             });
             const action = await this.replay.preTool(steering, toolName, toolUseId, modelArgs, {
                 signal: answeredLate.signal,
+                readsOnly: waitedRead && steering === live,
             });
             if (overran) {
                 // The host already has its answer. A divergence was answered with its
@@ -4469,20 +4614,28 @@ export class ControlServer {
     }
     /**
      * Retire `state` without running anything: the model's `run_scenario` was
-     * refused or failed. Books a baseline sample (`not_steered`) — the agent did
-     * the task — never a divergence.
+     * refused or failed, or the model changed something itself first. Books a
+     * baseline sample (`not_steered`) — the agent did the task — never a
+     * divergence. `code` goes with the report, so the recording page can say
+     * why the plan did not run (B2 is11.md: it said "the runner did not say
+     * why", and guessed wrong).
      */
-    vetoPlan(run, state, why) {
+    vetoPlan(run, state, why, code) {
         if (state.retired)
             return;
         state.retired = true;
         state.retiredAt = Date.now();
         state.pinned.clear();
         state.skipNote = undefined;
+        // A continuation has a reason of its own for this, `not_taken`, which the
+        // page words for a plan that follows a hand-over (restoreParkedFragment).
+        if (code && !state.declined && !state.continuation)
+            state.declined = code;
         this.directCalls = this.directCalls.filter((c) => c.state !== state);
         logLine("replay.vetoed", {
             run: run.runId,
             scenario: state.scenarioId ?? undefined,
+            code,
             why: `${why} — the plan is retired without running any step`,
         });
     }
@@ -5643,7 +5796,7 @@ export class ControlServer {
                 if (!this.runningPlans.has(waiting.state)) {
                     this.vetoPlan(waiting.run, waiting.state, failed
                         ? "run_scenario failed before it reached the runner"
-                        : "run_scenario answered without ever reaching the runner");
+                        : "run_scenario answered without ever reaching the runner", "run_refused");
                 }
             }
         }

package/dist/control/transcript.d.ts

@@ -217,6 +217,15 @@ export interface ModelUsage extends RateFlags {
  * of pricing, under the model's name with its rate key after it.
  */
 export type UsageMark = Map<string, ModelUsage>;
+/**
+ * The model calls between two marks of one transcript, `from` the earlier:
+ * assistant messages, each counted once by its `message.id` as its tokens are
+ * ({@link totalUsage}), the sub-agents' files included — the calls behind the
+ * tokens {@link usageBetween} gives for the same two marks. No `mark` counts
+ * from the start, as there. Clamped at 0, as the tokens are, for a transcript
+ * rewritten between the two. Undefined when either mark was not made here.
+ */
+export declare function callsBetween(mark: UsageMark | undefined, now: UsageMark): number | undefined;
 /**
  * Snapshot cumulative usage at the moment a run starts.
  *

package/dist/control/transcript.js

@@ -126,7 +126,8 @@ const indexes = new Map();
  * ({@link subagentUsage}): transcript path → the main index they were read
  * beside, one usage-only index per file, and `gone`: what the files whose
  * index was let go of had used (one past {@link MAX_SUBAGENT_FILES}, one read
- * again from its start after a rewrite). Dropped with the main index.
+ * again from its start after a rewrite), and `goneCalls`: their model calls.
+ * Dropped with the main index.
  */
 const subagentIndexes = new Map();
 /** Sub-agent files read per transcript, at most. */
@@ -150,6 +151,7 @@ function freshIndex(st, usageOnly) {
         // A sub-agent's file shares its transcript's set: a message that a host
         // writes into both files is counted once, whichever is read first.
         usageSeen: usageOnly?.seen ?? new Set(),
+        calls: 0,
         lastAssistantText: "",
         firstUserPrompt: "",
         sawPrompt: false,
@@ -388,6 +390,8 @@ function subagentFiles(transcriptPath) {
  * read beside the transcript's set of counted messages, so nothing counts
  * twice. A total that fell made the turn across the fall cost $0 for that
  * model, the main transcript's own tokens with it, and the file $0 for good.
+ *
+ * `calls` is the same files' model calls, on the same terms.
  */
 function subagentUsage(transcriptPath, main) {
     const files = subagentFiles(transcriptPath);
@@ -397,16 +401,26 @@ function subagentUsage(transcriptPath, main) {
         known = undefined;
     }
     if (files.length === 0 && !known)
-        return [];
+        return { usage: [], calls: 0 };
     if (!known) {
-        known = { beside: main, files: new Map(), gone: new Map() };
+        known = { beside: main, files: new Map(), gone: new Map(), goneCalls: 0 };
         subagentIndexes.set(transcriptPath, known);
     }
-    const gone = known.gone;
-    const usageOnly = { seen: main.usageSeen, retire: (old) => addUsage(gone, old.usage) };
+    const store = known;
+    const usageOnly = {
+        seen: main.usageSeen,
+        retire: (old) => {
+            addUsage(store.gone, old.usage);
+            store.goneCalls += old.calls;
+        },
+    };
     for (const file of files)
-        indexIn(known.files, file, MAX_SUBAGENT_FILES, usageOnly);
-    return [gone, ...[...known.files.values()].map((idx) => idx.usage)];
+        indexIn(store.files, file, MAX_SUBAGENT_FILES, usageOnly);
+    const read = [...store.files.values()];
+    return {
+        usage: [store.gone, ...read.map((idx) => idx.usage)],
+        calls: read.reduce((n, idx) => n + idx.calls, store.goneCalls),
+    };
 }
 /** `from`'s tokens added into `into`, key by key. */
 function addUsage(into, from) {
@@ -478,6 +492,9 @@ function foldUsage(idx, message) {
         return;
     if (id)
         idx.usageSeen.add(id);
+    // One message is one request: a model call (LP11), on the very terms its
+    // tokens are counted.
+    idx.calls += 1;
     const model = message?.model ?? "unknown";
     const input = count(usage.input_tokens);
     const read = count(usage.cache_read_input_tokens);
@@ -938,19 +955,49 @@ const count = (value) => typeof value === "number" && Number.isFinite(value) &&
  *
  * The running totals live in the index ({@link foldLine}); this returns a copy,
  * because a mark is kept and compared long after the index has moved on.
+ *
+ * The model calls those totals were counted from ride beside the copy, in
+ * {@link MARK_CALLS}: a key of the map would be read as a model, and priced.
  */
 function totalUsage(transcriptPath) {
     const totals = new Map();
     const idx = indexFor(transcriptPath);
-    if (!idx)
+    if (!idx) {
+        MARK_CALLS.set(totals, 0);
         return totals;
+    }
     for (const [model, u] of idx.usage)
         totals.set(model, { ...u });
     // And what the session's sub-agents used, each in a file of its own.
-    for (const usage of subagentUsage(transcriptPath, idx))
+    const subagents = subagentUsage(transcriptPath, idx);
+    for (const usage of subagents.usage)
         addUsage(totals, usage);
+    MARK_CALLS.set(totals, idx.calls + subagents.calls);
     return totals;
 }
+/**
+ * Model calls counted into a mark, by the mark: every mark this module makes
+ * has its entry, and a map made anywhere else has none ({@link callsBetween}).
+ * Weak, so a mark nobody holds any more takes its count with it.
+ */
+const MARK_CALLS = new WeakMap();
+/**
+ * The model calls between two marks of one transcript, `from` the earlier:
+ * assistant messages, each counted once by its `message.id` as its tokens are
+ * ({@link totalUsage}), the sub-agents' files included — the calls behind the
+ * tokens {@link usageBetween} gives for the same two marks. No `mark` counts
+ * from the start, as there. Clamped at 0, as the tokens are, for a transcript
+ * rewritten between the two. Undefined when either mark was not made here.
+ */
+export function callsBetween(mark, now) {
+    const to = MARK_CALLS.get(now);
+    if (to === undefined)
+        return undefined;
+    if (mark === undefined)
+        return to;
+    const from = MARK_CALLS.get(mark);
+    return from === undefined ? undefined : Math.max(0, to - from);
+}
 /**
  * Snapshot cumulative usage at the moment a run starts.
  *

package/dist/record/recorder.d.ts

@@ -471,7 +471,57 @@ export interface ExecutionReport {
      * (record/remote-recorder.ts, `answerCallsBody`).
      */
     answerCalls?: AnswerCall[];
+    /**
+     * What the runner can say of the turn beyond its cost (the service's
+     * learningPhase.md LP11): how the plan ran, the model calls and tokens of
+     * the window its cost was read for, how much the plan handed the agent to
+     * read, and why it handed over. The learning phase's rules about cost and
+     * time read it (P7, P8). Additive: an older service drops it, and a report
+     * without it is the body it always was.
+     */
+    turn?: ExecutionTurn;
+}
+/**
+ * {@link ExecutionReport.turn}. Every key is always there, `null` when the
+ * runner does not know it: no transcript mark, another host's run, nothing
+ * handed to the agent, no answer read.
+ */
+export interface ExecutionTurn {
+    /** How the plan ran, as coverage.ts decided it when it armed; null for a plan that never armed. */
+    mode: "direct" | "steer" | null;
+    /** The window's model calls: assistant messages, counted once per `message.id`, sub-agents' files included. */
+    modelCalls: number | null;
+    inputTokens: number | null;
+    outputTokens: number | null;
+    cacheReadTokens: number | null;
+    /** Every cache write, the 1-hour ones among them. */
+    cacheWriteTokens: number | null;
+    /**
+     * Characters of what the plan handed the agent to read: `run_scenario`'s
+     * answer (the bundle, or the hand-over note), a divergence's bundle, and
+     * the notes told in place of a call or beside its result. The announcement
+     * the prompt carries is not counted. Null for a plan that never armed.
+     */
+    bundleChars: number | null;
+    /** The brief bundle (0.3.25) was handed; false for a full one; null when no bundle was. */
+    brief: boolean | null;
+    /** Characters of the agent's final answer, when the runner read it (AC11); else null. */
+    answerChars: number | null;
+    /**
+     * On a hand-over: where the stopped step stood (`stop`, as a fragment's
+     * create call sends it — `not_run`, `failed`, `ran`, `uncertain`, …; null
+     * for a stop in front of a parked step or the other half) and why it
+     * stopped (`reason`: `budget`, `cancelled`, `test_failed`, `concurrent`,
+     * `failed`, … for a step that stopped, else the hand-over's kind). Null
+     * when the plan did not hand over.
+     */
+    handover: {
+        stop: string | null;
+        reason: string | null;
+    } | null;
 }
+/** The part of {@link ExecutionTurn} that only the transcript can say: the control server reads it. */
+export type TurnUsage = Pick<ExecutionTurn, "modelCalls" | "inputTokens" | "outputTokens" | "cacheReadTokens" | "cacheWriteTokens">;
 /** One call of a plan, whole, as {@link ExecutionReport.answerCalls} carries it. */
 export interface AnswerCall {
     /** The step's own `stepIndex`. */

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

@@ -61,7 +61,7 @@
  */
 import { type AuthSession } from "../auth/client.js";
 import { type ServiceHealth } from "../util/service-health.js";
-import type { AnswerCall, AttentionPlan, DisputeAnswer, ExecutionReport, FlushOptions, IntentMatchAnswer, IntentMatchOptions, IntentMatchRequest, Recorder, RecorderHealth, RecorderHealthReporter, RunCreation, RunMatch, RunMetrics, StartRunOptions, StepMetadata, ToolListEntry } from "./recorder.js";
+import type { AnswerCall, AttentionPlan, DisputeAnswer, ExecutionReport, ExecutionTurn, 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,
@@ -129,6 +129,14 @@ export interface RemoteRecorderOptions {
     /** The longest one queued send waits for a failing service ({@link COOLDOWN_WAIT_MAX_MS}). Tests shorten it. */
     cooldownWaitMaxMs?: number;
 }
+/**
+ * A report's `turn` as it is sent (the service's learningPhase.md LP11): its
+ * ten keys and no other, each a whole count of at least 0, a short code or
+ * null — so that no value a service's schema could refuse costs the report
+ * that carries it, and with it the turn's cost. Undefined, and so left out of
+ * the body, when the report has none.
+ */
+export declare function turnBody(turn: ExecutionTurn | undefined): ExecutionTurn | undefined;
 /** 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. */

package/dist/record/remote-recorder.js

@@ -274,6 +274,39 @@ function reportBody(fields, steps, extra = {}) {
         add(i, "toolOutput");
     return JSON.stringify({ ...fields, steps: sent, ...extra });
 }
+/** Longest `stop` or `reason` a report's `turn` carries: they are codes. */
+const TURN_CODE_MAX = 64;
+/**
+ * A report's `turn` as it is sent (the service's learningPhase.md LP11): its
+ * ten keys and no other, each a whole count of at least 0, a short code or
+ * null — so that no value a service's schema could refuse costs the report
+ * that carries it, and with it the turn's cost. Undefined, and so left out of
+ * the body, when the report has none.
+ */
+export function turnBody(turn) {
+    if (!turn || typeof turn !== "object")
+        return undefined;
+    const count = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0 ? Math.round(n) : null;
+    const code = (s) => (typeof s === "string" && s !== "" ? s.slice(0, TURN_CODE_MAX) : null);
+    try {
+        const h = turn.handover;
+        return {
+            mode: turn.mode === "direct" || turn.mode === "steer" ? turn.mode : null,
+            modelCalls: count(turn.modelCalls),
+            inputTokens: count(turn.inputTokens),
+            outputTokens: count(turn.outputTokens),
+            cacheReadTokens: count(turn.cacheReadTokens),
+            cacheWriteTokens: count(turn.cacheWriteTokens),
+            bundleChars: count(turn.bundleChars),
+            brief: typeof turn.brief === "boolean" ? turn.brief : null,
+            answerChars: count(turn.answerChars),
+            handover: h && typeof h === "object" ? { stop: code(h.stop), reason: code(h.reason) } : null,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
 /** What one answered turn's call may carry of its output, in UTF-8 bytes (review item 12). */
 export const ANSWER_CALL_OUTPUT_MAX_BYTES = 64 * 1024;
 /** All of one report's answer calls together, serialized, in UTF-8 bytes. */
@@ -1139,6 +1172,11 @@ export class RemoteRecorder {
                     // ...or only answered: its answer, capped and redacted like any
                     // text (AC11). Additive, like `redoneBy`.
                     answer: out(answer),
+                    // How the plan ran, its model calls and tokens, what the agent
+                    // read and why it handed over (the service's learningPhase.md
+                    // LP11). A few hundred bytes, inside the budget the payloads give
+                    // way to. Additive: an older service drops it.
+                    turn: turnBody(report.turn),
                 }, steps, 
                 // Beside the answer, the plan's calls whole (review item 12),
                 // outside the steps' budget. Additive: an older service drops them.