@inflexa-ai/harness 0.39.2 → 0.41.0

package/dist/loop/run-agent.js

@@ -5,21 +5,25 @@ import { stripNulCharacters } from "../input-sanitization.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { deliverNotice } from "../lib/hooks.js";
 import { ATTR_INFLEXA_TOOL_USE_ID, passThroughSpan, stableSpan } from "../lib/otel-spans.js";
-import { ResultError } from "../lib/result.js";
+import { ResultError, unwrapOrThrow } from "../lib/result.js";
 import { describeZodIssueShapes } from "../lib/zod-issue-shape.js";
 import { hintForZodIssue, repairToolInput } from "../lib/zod-issues.js";
-import { markInterruptedMessage, syntheticUserMessage } from "../memory/ai-sdk-message-storage.js";
-import { stripUnansweredToolCalls } from "../memory/tool-call-integrity.js";
-import { classifyProviderError } from "../providers/errors.js";
-import { DEFAULT_PROMPT_CACHE, withPromptCacheBreakpoint } from "../providers/prompt-cache.js";
-import { DEFAULT_REASONING } from "../providers/reasoning.js";
+import { dropMarkerMessage, markCompactionExchange, markInterruptedMessage, summaryMarkerMessage, syntheticUserMessage, } from "../memory/ai-sdk-message-storage.js";
+import { conversationView, keptTurnsForDrop, viewTokens } from "../memory/conversation-view.js";
+import { answerUnansweredToolCalls } from "../memory/tool-call-integrity.js";
+import { classifyProviderError, extractStatus } from "../providers/errors.js";
+import { DEFAULT_PROMPT_CACHE, withPromptCacheBreakpoint, withSystemPromptBreakpoint } from "../providers/prompt-cache.js";
+import { COMPACTION_MAX_REQUESTS } from "./compaction.js";
+import { continueAgent } from "./continue-agent.js";
 import { resultStep } from "./run-step.js";
 import { AskRejectedError, UnavailableAsk } from "../tools/approval/contract.js";
 import { isToolError, readToolResultImages } from "../tools/define-tool.js";
 import { labelToolFailure, labelToolValidationFailure, recordToolException, traceAgentRun, traceToolCall } from "./genai-spans.js";
-import { addChatUsage, hasReportedUsage, recordAgentRun } from "./metrics.js";
+import { addChatUsage, countChatTokens, hasReportedUsage, recordAgentRun } from "./metrics.js";
 import { computeDetail, computeResultDetail } from "./tool-detail.js";
+import { refusalsFor } from "./tool-mask.js";
 import { toolOutcomeForOutputType } from "./tool-outcome.js";
+import { excerptOf, keptTextOf, READ_TOOL_OUTPUT_TOOL_ID, resultTextOf, TOOL_RESULT_CAP, toolOutputRef, withExcerpt, } from "./tool-output.js";
 const TRUNCATED_PROSE_STEER = "Your previous reply was cut off at the output-token limit; continue concisely, or finish via your terminal tool.";
 const TRUNCATED_TOOL_USE_ERROR = "Your previous tool call was cut off at the output-token limit and was not executed. Retry with a smaller payload, writing in incremental pieces.";
 export const DEFAULT_STEP_NAME_FORMATTER = {
@@ -27,17 +31,43 @@ export const DEFAULT_STEP_NAME_FORMATTER = {
     tool: (name, id) => `tool-${name}-${id}`,
 };
 /** A run that receives no turn accumulator is the turn's root. See `RunAgentOptions.turnUsage`. */
-const isTurnRoot = (opts) => opts.turnUsage === undefined;
+export const isTurnRoot = (opts) => opts.turnUsage === undefined;
 export function runAgent(agent, initial, session, opts) {
     return traceAgentRun(agent.id, session, isTurnRoot(opts), () => runAgentLoop(agent, initial, session, opts));
 }
+/** The harness request of the wrap-up at the iteration cap. */
+export const WRAP_UP_REQUEST = "You reached the limit of tool rounds for this run, thus no tool can run now. Answer in text with the results that you have.";
+/** The cap of wrap-up requests: one answer, and one more request after a refused call. */
+export const WRAP_UP_MAX_REQUESTS = 2;
 async function runAgentLoop(agent, initial, session, opts) {
+    const formatStepName = opts.formatStepName ?? DEFAULT_STEP_NAME_FORMATTER;
+    const loop = openLoop(agent, initial, session, opts, agent.id);
+    const task = await loop.runSegment({ mask: opts.toolMask, maxRequests: agent.maxIterations, stepNames: formatStepName, firstIndex: 0, checksBudget: true });
+    if (task !== "capped")
+        return task;
+    // The wrap-up refuses calls through the mask, not `toolChoice` (see its
+    // CAUTION), and keeps step name `llm(maxIterations + k)` so replay finds the
+    // reply an earlier, single-call wrap-up stored under the same name.
+    const wrapUp = await loop.runSegment({
+        mask: "none",
+        maxRequests: WRAP_UP_MAX_REQUESTS,
+        stepNames: { llm: (k) => formatStepName.llm(agent.maxIterations + k), tool: formatStepName.tool },
+        firstIndex: agent.maxIterations,
+        requestText: WRAP_UP_REQUEST,
+        closesCappedRun: true,
+    });
+    return wrapUp === "capped" ? loop.endCapped() : wrapUp;
+}
+/**
+ * Open the loop over one conversation. `metricAgentId` is the id that usage
+ * and run metrics count under, which is not always `agent.id`.
+ */
+export function openLoop(agent, initial, session, opts, metricAgentId) {
     const { provider, signal, emit, runStep } = opts;
     // The step of a model call or a tool call writes no span. The `chat` span and
     // the `execute_tool` span under it describe the call already, and they attach
     // to the `invoke_agent` span of this run.
     const callStep = (name, fn) => passThroughSpan(name, () => runStep(name, fn));
-    const formatStepName = opts.formatStepName ?? DEFAULT_STEP_NAME_FORMATTER;
     const configuredFatalLoopError = opts.isFatalLoopError ?? (() => false);
     // AbortError is control flow, not a tool failure. Always compose it with the
     // host's fatal predicate so request cancellation cannot be converted into a
@@ -47,10 +77,29 @@ async function runAgentLoop(agent, initial, session, opts) {
         throw new Error(`Provider/model cannot run tool-required agent "${agent.id}"`);
     }
     const messages = [...initial];
+    // The loop never changes a message before `givenCount`, because the sink can hold it already.
+    let givenCount = initial.length;
+    // Stays true when the sink rejects, thus the throw path does not call the sink again.
+    let sinkPending = false;
+    const giveRound = async () => {
+        if (opts.onRound === undefined || messages.length === givenCount)
+            return;
+        sinkPending = true;
+        await opts.onRound({ messages: messages.slice(givenCount) });
+        sinkPending = false;
+        givenCount = messages.length;
+    };
     const source = {
         agentId: session.provenance.agentId ?? agent.id,
         callPath: session.provenance.callPath,
     };
+    const policy = opts.compaction;
+    const viewOptions = { keepFirstTurn: policy?.keepFirstTurn === true };
+    const viewOf = () => (policy === undefined ? messages : conversationView(messages, viewOptions).messages);
+    // The steer of a truncated prose reply and the reply after it complete one reply, thus no exchange goes between them.
+    let continuesTruncation = false;
+    let compactionStopped = false;
+    let compactions = 0;
     // Bound from the same `source` the emitted events carry: one derivation feeding
     // both sinks, so a record and an event cannot disagree about who produced them.
     // `callPath` rides as an array rather than a joined string — the queryable form;
@@ -61,6 +110,13 @@ async function runAgentLoop(agent, initial, session, opts) {
     // The collector belongs to this run, thus two loops never share one.
     const encoding = { placement: imagePlacementFor(provider.capabilities), deferredImages: [], log };
     const toolsById = new Map(agent.tools.map((t) => [t.id, t]));
+    // Only the read tool of the agent can read a kept text, thus an agent without it keeps nothing.
+    const cut = {
+        store: toolsById.has(READ_TOOL_OUTPUT_TOOL_ID) ? opts.toolOutputStore : undefined,
+        session,
+        invocationId: opts.invocationId,
+        log,
+    };
     const toolDefs = Object.fromEntries(agent.tools.map((t) => [
         t.id,
         aiTool({
@@ -79,13 +135,13 @@ async function runAgentLoop(agent, initial, session, opts) {
     // turn total. Descendants receive the root's object and mutate it in place.
     const turnUsage = opts.turnUsage ?? {};
     const turnRoot = isTurnRoot(opts);
-    const toolCtx = (tu) => ({
+    const toolCtx = (tu, names) => ({
         invocationId: tu.toolCallId,
         session,
         signal,
         emit,
         runStep: (name, fn) => {
-            const stepName = `${formatStepName.tool(tu.toolName, tu.toolCallId)}:${name}`;
+            const stepName = `${names.tool(tu.toolName, tu.toolCallId)}:${name}`;
             return runStep(stepName, () => {
                 stableSpan(stepName, `tool:${tu.toolName}:${name}`, { [ATTR_INFLEXA_TOOL_USE_ID]: tu.toolCallId });
                 return fn();
@@ -104,12 +160,12 @@ async function runAgentLoop(agent, initial, session, opts) {
     let toolErrorCount = 0;
     // Resolved once, not per iteration: an identical policy across every call is
     // itself part of the cache contract — the request prefix has to be
-    // byte-identical to be read back. The breakpoint it places is re-derived per
-    // call, because it rides the last message and the transcript grows.
+    // byte-identical to be read back. The message breakpoint is re-derived per
+    // call because it rides the transcript. The system prompt depends only on
+    // the agent type, so it is computed once.
     const promptCache = opts.promptCache ?? DEFAULT_PROMPT_CACHE;
-    // The depth is a neutral name, and the provider package resolves it for the
-    // model. A vendor key here would turn that resolution off.
-    const reasoning = opts.reasoning ?? DEFAULT_REASONING;
+    const system = withSystemPromptBreakpoint(agent.systemPrompt, promptCache);
+    const reasoningField = opts.reasoning === undefined ? {} : { reasoning: opts.reasoning };
     const usage = {};
     // Exactly one record per completed run — never one per iteration. That bound is
     // what keeps the default level affordable for an agent that runs long; the
@@ -122,71 +178,74 @@ async function runAgentLoop(agent, initial, session, opts) {
      * carry a complete tool call beside ANY finish reason, because the call
      * streams before the stop reason arrives, and only the dispatching branches
      * (`tool-calls`, a call-carrying `stop`, and `length`) run one. A call this
-     * run never dispatched is stripped
-     * rather than executed (a filtered or aborted reply must not act) or answered
-     * with an invented result (the model would read a fabrication as ground
-     * truth). Without the strip, the unanswered call violates the wire contract —
-     * every tool call carries a result — and the provider boundary then refuses
-     * the whole transcript on every later turn of the thread. Scoped past
+     * run never dispatched gets a not-run result instead of being executed or
+     * dropped: every tool call needs a result, or the provider refuses the
+     * transcript on the next turn. The fix only appends; it never edits or
+     * removes a message. Scoped past
      * `initial`: the caller's prefix is not this run's to repair.
      */
     const settleTranscript = () => {
-        const droppedCalls = stripUnansweredToolCalls(messages, initial.length);
-        if (droppedCalls.length === 0)
+        const answeredCalls = answerUnansweredToolCalls(messages, initial.length);
+        if (answeredCalls.length === 0)
             return;
-        log.warn("undispatched tool calls stripped at run exit", {
-            toolCallIds: droppedCalls.map((d) => d.toolCallId),
-            tools: droppedCalls.map((d) => d.toolName),
+        log.warn("unanswered tool calls answered at run exit", {
+            toolCallIds: answeredCalls.map((d) => d.toolCallId),
+            tools: answeredCalls.map((d) => d.toolName),
         });
     };
     const usageRecorder = opts.usageRecorder ?? createNoopUsageRecorder();
-    /**
-     * Fold one completed call into both rollups and hand it to the recorder.
-     * Called at the fold point, with the reply in hand — before any branch that
-     * can end the run — so a call that completed is accounted for even when the
-     * run later aborts or dies.
-     *
-     * A call that reported nothing produces no record. Model ids are identity,
-     * not usage: a reply carrying only `requestedModelId`/`servedModelId` still
-     * reported nothing to account for, so it is folded (to no effect) and left
-     * out of the ledger rather than entered as an all-absent record.
-     *
-     * `record` is a notice. The loop does not wait for its result, thus a
-     * recorder that blocks does not make the run slower.
-     */
-    const accountForCall = (reply, stepName) => {
-        addChatUsage(usage, reply.usage);
-        addChatUsage(turnUsage, reply.usage);
-        const reported = reply.usage;
-        if (reported === undefined || !hasReportedUsage(reported))
-            return;
-        void deliverNotice(log, "UsageRecorder.record", usageRecorder.record({
-            recordKey: recordKeyFor(session, opts.invocationId, stepName),
-            agentId: source.agentId,
-            callPath: source.callPath,
-            scope: session.scope,
-            ...(session.runFrame?.runId === undefined ? {} : { runId: session.runFrame.runId }),
-            ...(session.runFrame?.stepId === undefined ? {} : { stepId: session.runFrame.stepId }),
-            ...(reply.requestedModelId === undefined ? {} : { requestedModelId: reply.requestedModelId }),
-            ...(reply.servedModelId === undefined ? {} : { servedModelId: reply.servedModelId }),
-            usage: reported,
-        }));
+    const accounting = {
+        session,
+        agentId: source.agentId,
+        callPath: source.callPath,
+        ...(opts.invocationId === undefined ? {} : { invocationId: opts.invocationId }),
+        usageRecorder,
+        logger: log,
+        rollups: [usage, turnUsage],
     };
     /** The rollups this loop stamps on its finish — each absent when nothing reported. */
     const finishUsage = () => ({
         ...(hasReportedUsage(usage) ? { usage: { ...usage } } : {}),
         ...(turnRoot && hasReportedUsage(turnUsage) ? { turnUsage: { ...turnUsage } } : {}),
     });
+    /**
+     * One model request over the view of the transcript. Token counters grow inside
+     * the step body, so a replayed step (a stored reply) does not double-count.
+     */
+    const callModel = async (stepName, endsOnRequestRefusal) => {
+        const request = {
+            system,
+            messages: withPromptCacheBreakpoint(viewOf(), promptCache),
+            tools: toolDefs,
+            ...(opts.toolChoice !== undefined ? { toolChoice: opts.toolChoice } : {}),
+            ...reasoningField,
+        };
+        const chat = () => provider.chat(request, session, signal).map(countChatTokens(metricAgentId));
+        if (!endsOnRequestRefusal) {
+            const reply = await resultStep(callStep)(stepName, chat);
+            accountForChatCall(reply, { ...accounting, stepName });
+            return reply;
+        }
+        // The step gives the `Result` as its value, thus a refusal ends the segment and no step throws for it.
+        const result = await callStep(stepName, async () => await chat());
+        const refusal = result.isErr() ? requestRefusalOf(result.error) : undefined;
+        if (refusal !== undefined)
+            return { refusal };
+        const reply = unwrapOrThrow(result);
+        accountForChatCall(reply, { ...accounting, stepName });
+        return reply;
+    };
     // The user said no. A subsequent model call would only let the agent argue
     // with the decision, or spend a call acknowledging it; the denial tool result
     // is itself what the surface renders, so the turn ends the moment a denial
     // lands in a dispatch round — after the concurrent siblings in that same round
     // have completed and been appended. Mirrors the clean-stop terminal path.
-    const stopOnDenial = async (i) => {
+    const stopOnDenial = async (index) => {
         settleTranscript();
-        await emit({ type: "iteration", source, index: i, final: true });
-        recordAgentRun({ agentId: agent.id, iterations, cappedOut: false, usage });
+        await emit({ type: "iteration", source, index, final: true });
+        recordAgentRun({ agentId: metricAgentId, iterations, cappedOut: false });
         logFinish("warn", "denied", false);
+        await giveRound();
         return { messages, finish: { reason: "denied", cappedOut: false, truncationRecoveries, ...finishUsage() } };
     };
     /**
@@ -243,152 +302,306 @@ async function runAgentLoop(agent, initial, session, opts) {
         }
         return errored;
     };
-    const stopOnResolved = async (i) => {
+    // The calls of each tool that passed the mask and the budget in this run.
+    const used = new Map();
+    /**
+     * Dispatch one round under the run's mask and budget. A refused call still
+     * gets its own step slot, with an error result instead of running.
+     */
+    const dispatchRound = (calls, mask, names) => {
+        const refusals = refusalsFor(calls, mask, opts.toolBudget, used);
+        return dispatchTools(calls, refusals, toolsById, (tu) => toolCtx(tu, names), isFatalLoopError, callStep, names.tool, encoding, cut);
+    };
+    const stopOnResolved = async (index) => {
         settleTranscript();
-        await emit({ type: "iteration", source, index: i, final: true });
-        recordAgentRun({ agentId: agent.id, iterations, cappedOut: false, usage });
+        await emit({ type: "iteration", source, index, final: true });
+        recordAgentRun({ agentId: metricAgentId, iterations, cappedOut: false });
+        await giveRound();
         return { messages, finish: { reason: "stop", cappedOut: false, truncationRecoveries } };
     };
-    for (let i = 0; i < agent.maxIterations; i++) {
-        iterations = i + 1;
-        const request = {
-            system: agent.systemPrompt,
-            messages: withPromptCacheBreakpoint(messages, promptCache),
-            tools: toolDefs,
-            ...(opts.toolChoice !== undefined ? { toolChoice: opts.toolChoice } : {}),
-            reasoning,
-        };
-        const llmStepName = formatStepName.llm(i);
-        const reply = await resultStep(callStep)(llmStepName, () => provider.chat(request, session, signal));
-        accountForCall(reply, llmStepName);
-        if (reply.finishReason === "aborted") {
-            // An interrupted turn keeps whatever the model produced before the cut, but
-            // never an empty shell: a partial with no content adds no message, so a
-            // no-output abort leaves the transcript at the initial prefix. The marker
-            // then rides the last assistant message this run produced — the partial when
-            // it has content, or the tool-calling step when the abort landed mid-dispatch
-            // — an assistant role no turn-boundary reader observes. "aborted" is not
-            // "tool-calls", so this falls into the terminal return below.
-            if (assistantHasContent(reply.message))
-                messages.push(reply.message);
-            markLastLoopAssistant(messages, initial.length);
+    const endOnRefusal = async (refusal) => {
+        settleTranscript();
+        recordAgentRun({ agentId: metricAgentId, iterations, cappedOut: false });
+        logFinish("warn", "error", false);
+        await giveRound();
+        return { messages, finish: { reason: "error", cappedOut: false, truncationRecoveries, ...finishUsage() }, refusal };
+    };
+    /** The result of the run when an abort ends the exchange, or `undefined` when the run continues. */
+    const compact = async (active, tokensBefore, index) => {
+        const id = randomUUID();
+        const stepNamespace = `compaction-${compactions++}`;
+        const startedAt = performance.now();
+        const emitPart = (data) => emit({ type: "data-compaction", source, data });
+        await emitPart({ id, status: "running", tokensBefore });
+        const { onRound: _onRound, compaction: _compaction, ...conversationOptions } = opts;
+        let settled = false;
+        try {
+            const exchange = await continueAgent(agent, viewOf(), {
+                text: active.request,
+                mask: active.mask,
+                maxRequests: COMPACTION_MAX_REQUESTS,
+                stepNamespace,
+                accountingAgentId: `${agent.id}-compaction`,
+                endOnRequestRefusal: true,
+            }, session, { ...conversationOptions, provider: active.provider, turnUsage });
+            messages.push(...exchange.messages.map((message) => markCompactionExchange(message, id)));
+            await giveRound();
+            if (exchange.finish.reason === "aborted") {
+                settled = true;
+                await emitPart({ id, status: "failed", tokensBefore, durationMs: Math.round(performance.now() - startedAt) });
+                settleTranscript();
+                await emit({ type: "iteration", source, index, final: true });
+                recordAgentRun({ agentId: metricAgentId, iterations, cappedOut: false });
+                logFinish("info", "aborted", false);
+                await giveRound();
+                return { messages, finish: { reason: "aborted", cappedOut: false, truncationRecoveries, ...finishUsage() } };
+            }
+            const summary = summaryOf(exchange);
+            const keptTurns = summary === undefined ? keptTurnsForDrop(messages, viewOptions, active.budget) : 0;
+            const markerOf = (tokensAfter, durationMs) => summary === undefined
+                ? dropMarkerMessage({ kind: "drop", id, tokensBefore, tokensAfter, durationMs, keptTurns })
+                : summaryMarkerMessage(summary, { kind: "summary", id, tokensBefore, tokensAfter, durationMs });
+            // The figures of a marker do not change the view, thus a draft marker gives the view of the real one.
+            const view = conversationView([...messages, markerOf(0, 0)], viewOptions).messages;
+            const records = await active.recordsAfter(view);
+            const tokensAfter = viewTokens([...view, ...records]);
+            const durationMs = Math.round(performance.now() - startedAt);
+            messages.push(markerOf(tokensAfter, durationMs), ...records);
+            await giveRound();
+            settled = true;
+            await emitPart({ id, status: summary === undefined ? "failed" : "done", tokensBefore, tokensAfter, durationMs });
+            const fields = { compactionId: id, tokensBefore, tokensAfter, durationMs };
+            if (summary === undefined) {
+                const refusal = exchange.refusal === undefined ? {} : { status: exchange.refusal.status, providerError: exchange.refusal.message };
+                log.warn("compaction gave no summary, thus the oldest turns left the view", { ...fields, keptTurns, ...refusal });
+            }
+            else {
+                log.info("conversation compacted", fields);
+            }
+            if (summary !== undefined && tokensAfter > active.budget) {
+                log.warn("the compacted view still exceeds the budget, thus the run compacts no more", {
+                    compactionId: id,
+                    tokensAfter,
+                    budget: active.budget,
+                });
+            }
+            if (summary === undefined || tokensAfter > active.budget)
+                compactionStopped = true;
+            return undefined;
         }
-        else {
-            messages.push(reply.message);
+        finally {
+            if (!settled)
+                await emitPart({ id, status: "failed", tokensBefore, durationMs: Math.round(performance.now() - startedAt) });
         }
-        const toolCalls = toolCallParts(reply.message);
-        if (reply.finishReason === "length") {
-            truncationRecoveries++;
-            await emit({ type: "iteration", source, index: i, final: false });
-            // `tools` is what the model asked for; the trailing call was cut off at the
-            // output limit and is never dispatched, which the distinct message records.
-            log.debug("iteration truncated at output limit", { iteration: i, tools: toolCalls.map((t) => t.toolName), truncationRecoveries });
-            if (toolCalls.length === 0) {
-                // Stamped synthetic, not left as a bare `user` message: the wire format needs a user turn
-                // after a truncated assistant message, but this one is the loop's own nudge, and thread
-                // storage treats a genuine `user` message as the start of a conversation turn. Unmarked, it
-                // would split this turn in two everywhere that boundary is read.
-                messages.push(syntheticUserMessage(TRUNCATED_PROSE_STEER));
+    };
+    const compactOverBudget = async (index) => {
+        if (policy === undefined || continuesTruncation || compactionStopped)
+            return undefined;
+        const tokensBefore = viewTokens(viewOf());
+        return tokensBefore > policy.budget ? compact(policy, tokensBefore, index) : undefined;
+    };
+    const runSegment = async (segment) => {
+        const names = segment.stepNames;
+        if (segment.requestText !== undefined)
+            messages.push(syntheticUserMessage(segment.requestText));
+        for (let k = 0; k < segment.maxRequests; k++) {
+            const index = segment.firstIndex + k;
+            // The last request of a segment that closes a capped run ends the run,
+            // whatever its reply, thus its `iteration` event is the final one.
+            const endsRun = segment.closesCappedRun === true && k === segment.maxRequests - 1;
+            await giveRound();
+            if (segment.checksBudget === true) {
+                const ended = await compactOverBudget(index);
+                if (ended !== undefined)
+                    return ended;
+            }
+            if (segment.closesCappedRun !== true)
+                iterations++;
+            const roundStart = messages.length;
+            const called = await callModel(names.llm(k), segment.endsOnRequestRefusal === true);
+            continuesTruncation = false;
+            if ("refusal" in called)
+                return endOnRefusal(called.refusal);
+            const reply = called;
+            if (reply.finishReason === "aborted") {
+                // An interrupted turn keeps whatever the model produced before the cut, but
+                // never an empty shell: a partial with no content adds no message. Only the
+                // partial carries the marker, because the sink can hold each earlier message.
+                // "aborted" is not "tool-calls", so this falls into the terminal return below.
+                if (assistantHasContent(reply.message))
+                    messages.push(reply.message);
+                markLastLoopAssistant(messages, roundStart);
+            }
+            else {
+                messages.push(reply.message);
+            }
+            const toolCalls = toolCallParts(reply.message);
+            if (reply.finishReason === "length") {
+                truncationRecoveries++;
+                await emit({ type: "iteration", source, index, final: endsRun });
+                // `tools` is what the model asked for; the trailing call was cut off at the
+                // output limit and is never dispatched, which the distinct message records.
+                log.debug("iteration truncated at output limit", { iteration: index, tools: toolCalls.map((t) => t.toolName), truncationRecoveries });
+                if (toolCalls.length === 0) {
+                    // Stamped synthetic, not left as a bare `user` message: the wire format needs a user turn
+                    // after a truncated assistant message, but this one is the loop's own nudge, and thread
+                    // storage treats a genuine `user` message as the start of a conversation turn. Unmarked, it
+                    // would split this turn in two everywhere that boundary is read.
+                    messages.push(syntheticUserMessage(TRUNCATED_PROSE_STEER));
+                    continuesTruncation = true;
+                    continue;
+                }
+                const trailing = toolCalls[toolCalls.length - 1];
+                const earlier = toolCalls.slice(0, -1);
+                const earlierDetails = roundDetails(earlier);
+                for (const [idx, tu] of earlier.entries()) {
+                    await emit({
+                        type: "tool-started",
+                        source,
+                        toolUseId: tu.toolCallId,
+                        name: tu.toolName,
+                        input: tu.input,
+                        ...detailField(earlierDetails[idx]),
+                    });
+                }
+                const { results, durations, resultDetails } = await dispatchRound(earlier, segment.mask, names);
+                const errored = await settleRound(earlier, results, earlierDetails, resultDetails, durations);
+                results.push(errorResult(trailing, TRUNCATED_TOOL_USE_ERROR));
+                // The trailing call was never dispatched, but it reaches the model as an error
+                // result like any other — so it counts, or `toolErrors` reports a cleaner run
+                // than the model actually read. It gets no `tool-finished` event: no
+                // `tool-started` was emitted for it either, and the pair must stay balanced.
+                toolCallCount++;
+                toolErrorCount++;
+                errored.push(trailing.toolName);
+                log.debug("tool results returned errors", { iteration: index, tools: errored });
+                messages.push({ role: "tool", content: results });
+                appendDeferredImages(messages, results, encoding.deferredImages);
+                if (hasDenial(results))
+                    return stopOnDenial(index);
+                if (opts.resolved?.())
+                    return stopOnResolved(index);
                 continue;
             }
-            const trailing = toolCalls[toolCalls.length - 1];
-            const earlier = toolCalls.slice(0, -1);
-            const earlierDetails = roundDetails(earlier);
-            for (const [idx, tu] of earlier.entries()) {
-                await emit({ type: "tool-started", source, toolUseId: tu.toolCallId, name: tu.toolName, input: tu.input, ...detailField(earlierDetails[idx]) });
+            // A local model behind an OpenAI-compatible server routinely labels a
+            // tool-calling reply `stop`. The calls are complete and the model waits
+            // on their results, thus the mislabeled round dispatches like a
+            // `tool-calls` one. Every other terminal answers its calls with the
+            // not-run result: a filtered or aborted reply must not act.
+            const dispatchesRound = reply.finishReason === "tool-calls" || (reply.finishReason === "stop" && toolCalls.length > 0);
+            if (!dispatchesRound) {
+                settleTranscript();
+                await emit({ type: "iteration", source, index, final: true });
+                if (segment.closesCappedRun === true) {
+                    // The cap was already reached; `reason` still distinguishes an
+                    // abort (user cut the turn) from a plain `max_iterations` cap-out.
+                    const reason = reply.finishReason === "aborted" ? "aborted" : "max_iterations";
+                    recordAgentRun({ agentId: metricAgentId, iterations, cappedOut: true });
+                    logFinish("warn", reason, true);
+                    await giveRound();
+                    return { messages, finish: { reason, cappedOut: true, truncationRecoveries, ...finishUsage() } };
+                }
+                recordAgentRun({ agentId: metricAgentId, iterations, cappedOut: false });
+                logFinish("info", reply.finishReason, false);
+                await giveRound();
+                return {
+                    messages,
+                    finish: {
+                        reason: reply.finishReason,
+                        ...(reply.rawFinishReason === undefined ? {} : { rawFinishReason: reply.rawFinishReason }),
+                        cappedOut: false,
+                        truncationRecoveries,
+                        ...finishUsage(),
+                    },
+                };
             }
-            const { results, durations, resultDetails } = await dispatchTools(earlier, toolsById, toolCtx, isFatalLoopError, callStep, formatStepName.tool, encoding);
-            const errored = await settleRound(earlier, results, earlierDetails, resultDetails, durations);
-            results.push(errorResult(trailing, TRUNCATED_TOOL_USE_ERROR));
-            // The trailing call was never dispatched, but it reaches the model as an error
-            // result like any other — so it counts, or `toolErrors` reports a cleaner run
-            // than the model actually read. It gets no `tool-finished` event: no
-            // `tool-started` was emitted for it either, and the pair must stay balanced.
-            toolCallCount++;
-            toolErrorCount++;
-            errored.push(trailing.toolName);
-            log.debug("tool results returned errors", { iteration: i, tools: errored });
+            await emit({ type: "iteration", source, index, final: endsRun });
+            log.debug("iteration", { iteration: index, tools: toolCalls.map((t) => t.toolName) });
+            const details = roundDetails(toolCalls);
+            for (const [idx, tu] of toolCalls.entries()) {
+                await emit({ type: "tool-started", source, toolUseId: tu.toolCallId, name: tu.toolName, input: tu.input, ...detailField(details[idx]) });
+            }
+            const { results, durations, resultDetails } = await dispatchRound(toolCalls, segment.mask, names);
+            const errored = await settleRound(toolCalls, results, details, resultDetails, durations);
+            if (errored.length > 0)
+                log.debug("tool results returned errors", { iteration: index, tools: errored });
             messages.push({ role: "tool", content: results });
             appendDeferredImages(messages, results, encoding.deferredImages);
             if (hasDenial(results))
-                return stopOnDenial(i);
+                return stopOnDenial(index);
             if (opts.resolved?.())
-                return stopOnResolved(i);
-            continue;
+                return stopOnResolved(index);
         }
-        // A local model behind an OpenAI-compatible server routinely labels a
-        // tool-calling reply `stop`. The calls are complete and the model waits
-        // on their results, thus the mislabeled round dispatches like a
-        // `tool-calls` one. Every other terminal keeps the strip: a filtered or
-        // aborted reply must not act.
-        const dispatchesRound = reply.finishReason === "tool-calls" || (reply.finishReason === "stop" && toolCalls.length > 0);
-        if (!dispatchesRound) {
-            settleTranscript();
-            // The settle can remove a call-only aborted partial whole; the
-            // interruption marker then rides the last assistant that survived,
-            // matching the no-output abort contract above.
-            if (reply.finishReason === "aborted")
-                markLastLoopAssistant(messages, initial.length);
-            await emit({ type: "iteration", source, index: i, final: true });
-            recordAgentRun({ agentId: agent.id, iterations, cappedOut: false, usage });
-            logFinish("info", reply.finishReason, false);
-            return {
-                messages,
-                finish: {
-                    reason: reply.finishReason,
-                    ...(reply.rawFinishReason === undefined ? {} : { rawFinishReason: reply.rawFinishReason }),
-                    cappedOut: false,
-                    truncationRecoveries,
-                    ...finishUsage(),
-                },
-            };
+        return "capped";
+    };
+    const endCapped = async () => {
+        settleTranscript();
+        recordAgentRun({ agentId: metricAgentId, iterations, cappedOut: true });
+        logFinish("warn", "max_iterations", true);
+        await giveRound();
+        return { messages, finish: { reason: "max_iterations", cappedOut: true, truncationRecoveries, ...finishUsage() } };
+    };
+    // A throw keeps the open round, and the not-run results keep that stored round valid on the wire.
+    const giveRoundBeforeThrow = async (body) => {
+        if (opts.onRound === undefined)
+            return body();
+        try {
+            return await body();
         }
-        await emit({ type: "iteration", source, index: i, final: false });
-        log.debug("iteration", { iteration: i, tools: toolCalls.map((t) => t.toolName) });
-        const details = roundDetails(toolCalls);
-        for (const [idx, tu] of toolCalls.entries()) {
-            await emit({ type: "tool-started", source, toolUseId: tu.toolCallId, name: tu.toolName, input: tu.input, ...detailField(details[idx]) });
+        catch (err) {
+            if (sinkPending)
+                throw err;
+            answerUnansweredToolCalls(messages, givenCount);
+            // A rejection of this call must not hide the error of the run.
+            await giveRound().catch(() => undefined);
+            throw err;
         }
-        const { results, durations, resultDetails } = await dispatchTools(toolCalls, toolsById, toolCtx, isFatalLoopError, callStep, formatStepName.tool, encoding);
-        const errored = await settleRound(toolCalls, results, details, resultDetails, durations);
-        if (errored.length > 0)
-            log.debug("tool results returned errors", { iteration: i, tools: errored });
-        messages.push({ role: "tool", content: results });
-        appendDeferredImages(messages, results, encoding.deferredImages);
-        if (hasDenial(results))
-            return stopOnDenial(i);
-        if (opts.resolved?.())
-            return stopOnResolved(i);
-    }
-    // The wrap-up keeps the tool set of the loop and forbids a call through
-    // `toolChoice`. A changed tool set rewrites the cached prefix, and a model
-    // that binds its signed thinking blocks to the prefix can reject the
-    // transcript.
-    const wrapUpStepName = formatStepName.llm(agent.maxIterations);
-    const wrapUp = await resultStep(callStep)(wrapUpStepName, () => provider.chat({ system: agent.systemPrompt, messages: withPromptCacheBreakpoint(messages, promptCache), tools: toolDefs, toolChoice: "none", reasoning }, session, signal));
-    accountForCall(wrapUp, wrapUpStepName);
-    if (wrapUp.finishReason === "aborted") {
-        // An abort during the wrap-up is still the user cutting the turn — the
-        // same event the in-loop path handles — so it gets the identical treatment: keep a
-        // partial only when it carries content, and stamp the marker on the last assistant
-        // this run produced. Reporting it as a plain cap-out would hide the interruption
-        // from every downstream reader; `cappedOut` stays true because the loop genuinely
-        // exhausted its iterations, while the reason carries the abort.
-        if (assistantHasContent(wrapUp.message))
-            messages.push(wrapUp.message);
-        settleTranscript();
-        markLastLoopAssistant(messages, initial.length);
-        await emit({ type: "iteration", source, index: agent.maxIterations, final: true });
-        recordAgentRun({ agentId: agent.id, iterations, cappedOut: true, usage });
-        logFinish("warn", "aborted", true);
-        return { messages, finish: { reason: "aborted", cappedOut: true, truncationRecoveries, ...finishUsage() } };
-    }
-    messages.push(wrapUp.message);
-    settleTranscript();
-    await emit({ type: "iteration", source, index: agent.maxIterations, final: true });
-    recordAgentRun({ agentId: agent.id, iterations, cappedOut: true, usage });
-    logFinish("warn", "max_iterations", true);
-    return { messages, finish: { reason: "max_iterations", cappedOut: true, truncationRecoveries, ...finishUsage() } };
+    };
+    return {
+        runSegment: (segment) => giveRoundBeforeThrow(() => runSegment(segment)),
+        endCapped: () => giveRoundBeforeThrow(endCapped),
+    };
+}
+/** The statuses of a request that the provider refuses for its content, for example a request past the context window. */
+const REFUSAL_STATUSES = new Set([400, 413]);
+function requestRefusalOf(error) {
+    if (error.type !== "provider")
+        return undefined;
+    const status = extractStatus(error);
+    return status !== undefined && REFUSAL_STATUSES.has(status) ? { status, message: error.message } : undefined;
+}
+/** The text of the last reply of an exchange, when that reply ends the exchange with the finish reason `stop`. */
+function summaryOf(exchange) {
+    if (exchange.finish.reason !== "stop")
+        return undefined;
+    const text = finalText(exchange.messages).trim();
+    return text.length > 0 ? text : undefined;
+}
+/**
+ * Called at the fold point, before any run-ending branch, so an aborted or
+ * dead run is still accounted. Token counters grow inside the call's step
+ * body, not here, because a replay re-delivers the stored reply to this
+ * function too; the record re-sends under the same idempotency key, which an
+ * upserting sink counts once.
+ */
+export function accountForChatCall(reply, call) {
+    for (const rollup of call.rollups)
+        addChatUsage(rollup, reply.usage);
+    const reported = reply.usage;
+    if (reported === undefined || !hasReportedUsage(reported))
+        return;
+    const { session } = call;
+    void deliverNotice(call.logger, "UsageRecorder.record", call.usageRecorder.record({
+        recordKey: recordKeyFor(session, call.invocationId, call.stepName),
+        agentId: call.agentId,
+        callPath: call.callPath,
+        scope: session.scope,
+        ...(session.runFrame?.runId === undefined ? {} : { runId: session.runFrame.runId }),
+        ...(session.runFrame?.stepId === undefined ? {} : { stepId: session.runFrame.stepId }),
+        ...(reply.requestedModelId === undefined ? {} : { requestedModelId: reply.requestedModelId }),
+        ...(reply.servedModelId === undefined ? {} : { servedModelId: reply.servedModelId }),
+        usage: reported,
+    }));
 }
 /**
  * Delimiter joining the call path into one key segment.
@@ -398,11 +611,13 @@ async function runAgentLoop(agent, initial, session, opts) {
  * UUIDs or the profiler's `data-profile` literal, step ids are path-safe plan
  * ids (`T1S1`, `synthesis`, `profile`), tool-call ids are provider-issued
  * opaque tokens, and the loop's step names are `llm-{n}` / `tool-{name}-{id}`
- * with an optional `salvage:` prefix — none of them can contain `>`.
+ * with an optional continuation namespace (`salvage:`, `file-metadata:`,
+ * `step-summary:`) — none of them can contain `>`.
  */
 const CALL_PATH_DELIMITER = ">";
 /**
- * Idempotency key for one call's usage record:
+ * Idempotency key for one call's usage record, and for the kept text of one cut
+ * tool result under the tool step name of its call:
  * `{runId}[:{stepId}]:{callPath}[:{invocationId}]:{stepName}`.
  *
  * Every component is a fact the same call carries again on every replay, so a
@@ -452,14 +667,11 @@ function assistantHasContent(message) {
     return message.content.length > 0;
 }
 /**
- * Stamp the interruption marker on the last assistant message the loop produced
- * this run — an index at or beyond the `initial` prefix — replacing the slot with
- * a marked copy so the mark rides into `appendTurn` and the stored row. When the
- * turn produced no assistant message beyond `initial` (a no-output abort on a
- * fresh turn), there is nothing to mark and the transcript is left untouched.
+ * Mark the aborted partial of the last request. A message before `roundStart` stays unmarked,
+ * because the round sink can hold it already.
  */
-function markLastLoopAssistant(messages, initialCount) {
-    for (let idx = messages.length - 1; idx >= initialCount; idx--) {
+function markLastLoopAssistant(messages, roundStart) {
+    for (let idx = messages.length - 1; idx >= roundStart; idx--) {
         const message = messages[idx];
         if (message.role === "assistant") {
             messages[idx] = markInterruptedMessage(message);
@@ -527,19 +739,27 @@ function appendDeferredImages(messages, results, deferredImages) {
 /**
  * Dispatch one round of tool calls, and measure the time of each call.
  *
- * `results`, `durations` and `resultDetails` are positionally aligned with `toolUses`.
+ * `refusals`, `results`, `durations` and `resultDetails` are positionally aligned
+ * with `toolUses`; `refusals[i]` is the refusal text, or `undefined` if the call runs.
+ *
+ * A refused call still runs inside the same step wrapper and step name as a
+ * dispatched one, keeping a round's step sequence identical for replay.
  *
  * Each measurement brackets the same unit that the loop awaits for that call. For a
  * step-mode call that unit is `runStep`, thus the figure includes the durable-step
  * wrapper. The wrapper is part of what the call cost, and a cached replay of a step
  * is genuinely fast. A bracket inside the step would report a body that did not run.
  */
-async function dispatchTools(toolUses, toolsById, toolCtx, isFatalLoopError, runStep, toolStepName, encoding) {
-    const dispatch = (tu) => traceToolCall(tu, () => dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError, encoding), (dispatched) => outcomeOf(dispatched.result));
+async function dispatchTools(toolUses, refusals, toolsById, toolCtx, isFatalLoopError, runStep, toolStepName, encoding, cut) {
+    // A refusal writes no tool span, because the tool does not run.
+    const dispatch = (tu, refusal) => refusal !== undefined
+        ? Promise.resolve({ result: errorResult(tu, refusal) })
+        : traceToolCall(tu, () => dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError, encoding, cut, toolStepName(tu.toolName, tu.toolCallId)), (dispatched) => outcomeOf(dispatched.result));
     const results = new Array(toolUses.length);
     // The array starts with holes, which read as `undefined`. The element type
-    // says so, thus it agrees with what `settleRound` accepts. Every index is in
-    // fact assigned, because the mode partition below covers each call.
+    // says so, thus it agrees with what `settleRound` accepts. Every index is
+    // assigned except the index of a refused call, because the mode partition
+    // below covers each call.
     const durations = new Array(toolUses.length);
     // A hole stays a hole for a call that described no result: an error, a
     // denial, and a tool with no result hook each leave the index unassigned,
@@ -558,30 +778,27 @@ async function dispatchTools(toolUses, toolsById, toolCtx, isFatalLoopError, run
             stepTools.push({ tu, idx });
     }
     await Promise.all(stepTools.map(({ tu, idx }) => {
+        const refusal = refusals[idx];
         const startedAt = performance.now();
-        return runStep(toolStepName(tu.toolName, tu.toolCallId), () => dispatch(tu)).then((settled) => {
-            durations[idx] = elapsedMs(startedAt);
+        return runStep(toolStepName(tu.toolName, tu.toolCallId), () => dispatch(tu, refusal)).then((settled) => {
+            if (refusal === undefined)
+                durations[idx] = elapsedMs(startedAt);
             const dispatched = readDispatchedStep(settled);
             results[idx] = dispatched.result;
             if (dispatched.detail !== undefined)
                 resultDetails[idx] = dispatched.detail;
         });
     }));
-    for (const { tu, idx } of workflowTools) {
+    // A workflow-mode and an inline-mode call run unwrapped, one after another.
+    for (const { tu, idx } of [...workflowTools, ...inlineTools]) {
+        const refusal = refusals[idx];
         const startedAt = performance.now();
-        const dispatched = await dispatch(tu);
+        const dispatched = await dispatch(tu, refusal);
         results[idx] = dispatched.result;
         if (dispatched.detail !== undefined)
             resultDetails[idx] = dispatched.detail;
-        durations[idx] = elapsedMs(startedAt);
-    }
-    for (const { tu, idx } of inlineTools) {
-        const startedAt = performance.now();
-        const dispatched = await dispatch(tu);
-        results[idx] = dispatched.result;
-        if (dispatched.detail !== undefined)
-            resultDetails[idx] = dispatched.detail;
-        durations[idx] = elapsedMs(startedAt);
+        if (refusal === undefined)
+            durations[idx] = elapsedMs(startedAt);
     }
     return { results, durations, resultDetails };
 }
@@ -602,7 +819,37 @@ function elapsedMs(startedAt) {
 function readDispatchedStep(settled) {
     return "result" in settled ? settled : { result: settled };
 }
-async function dispatchTool(tu, toolsById, ctx, isFatalLoopError, encoding) {
+/** For a step-mode tool this runs inside the durable step of the call, thus a replay gives the stored excerpt. */
+async function dispatchTool(tu, toolsById, ctx, isFatalLoopError, encoding, cut, stepName) {
+    const dispatched = await callTool(tu, toolsById, ctx, isFatalLoopError, encoding);
+    return { ...dispatched, result: await cutLongResult(dispatched.result, cut, stepName) };
+}
+/** The excerpt does not depend on the outcome of the put, thus a replay gives the same bytes. */
+async function cutLongResult(result, cut, stepName) {
+    const text = resultTextOf(result.output);
+    if (text === undefined || text.length <= TOOL_RESULT_CAP)
+        return result;
+    if (cut.store === undefined)
+        return withExcerpt(result, excerptOf(text, undefined));
+    const { session } = cut;
+    const ref = toolOutputRef(recordKeyFor(session, cut.invocationId, stepName));
+    const content = keptTextOf(text);
+    const put = await cut.store.put({
+        analysisId: session.scope.analysisId,
+        ref,
+        toolName: result.toolName,
+        toolCallId: result.toolCallId,
+        // A run session carries the thread of the chat that started the run, but a run belongs to its analysis.
+        ...(session.runFrame === undefined && session.scope.threadId !== undefined ? { threadId: session.scope.threadId } : {}),
+        content,
+        totalLength: text.length,
+    });
+    if (put.isErr()) {
+        cut.log.warn("tool output not kept", { toolName: result.toolName, toolCallId: result.toolCallId, ref, errorType: put.error.type });
+    }
+    return withExcerpt(result, excerptOf(text, { ref, keptLength: content.length }));
+}
+async function callTool(tu, toolsById, ctx, isFatalLoopError, encoding) {
     const tool = toolsById.get(tu.toolName);
     if (tool === undefined) {
         labelToolFailure("unknown_tool");