@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/loop/run-loop.js

@@ -0,0 +1,770 @@
+/**
+ * The agent loop: one conversation of one agent with a model and its tools.
+ *
+ * The AI SDK drives each request series with `streamText`. Inside a DBOS
+ * workflow, `durableCalls` makes each model call a step, and the tool adapter
+ * makes each tool call a step, thus a recovery replays each completed call
+ * from its checkpoint. Outside a workflow, each call runs directly. The same
+ * loop serves a chat turn, a workflow step, and a sub-agent.
+ *
+ * The loop keeps the transcript itself, and each request sends its view of
+ * the transcript. This gives the loop the work that the SDK does not do: the
+ * append-only record of each round, the round sink, the compaction, the
+ * follow-up request, the salvage, the not-run answer of each unanswered call
+ * at an exit, and the finish record.
+ */
+import { randomUUID } from "node:crypto";
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { durableCalls } from "@dbos-inc/vercel-ai";
+import { streamText, wrapLanguageModel, } from "ai";
+import { forSubAgent } from "../auth/types.js";
+import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
+import { createNoopLogger } from "../lib/console-logger.js";
+import { toThrowable } from "../lib/result.js";
+import { errorNameOf } from "../lib/thrown.js";
+import { contextRecordOf, markCompactionExchange, markInterruptedMessage, summaryMarkerMessage, syntheticUserMessage, withRequestInputTokens, } from "../memory/ai-sdk-message-storage.js";
+import { conversationView, lastRequestInputTokens, withoutReasoning } from "../memory/conversation-view.js";
+import { answerUnansweredToolCalls } from "../memory/tool-call-integrity.js";
+import { fallbackModelOf } from "../providers/ai-sdk.js";
+import { extractStatus, findProviderError } from "../providers/errors.js";
+import { DEFAULT_PROMPT_CACHE, withPromptCacheBreakpoint, withSystemPromptBreakpoint } from "../providers/prompt-cache.js";
+import { accountingMiddleware, rollupMiddleware } from "./accounting.js";
+import { createCallPolicy } from "./call-policy.js";
+import { COMPACTION_MAX_REQUESTS } from "./compaction.js";
+import { addChatUsage, hasReportedUsage, recordAgentRun } from "./metrics.js";
+import { adaptTools, deniedReason, foldCallRecords, isFatalToolError, modelViewOf, recordedInputOf, ToolCallOutputSchema, } from "./tool-adapter.js";
+import { READ_TOOL_OUTPUT_TOOL_ID } from "./tool-output.js";
+/** The reason of a call that asks for approval in a loop where no surface can answer. */
+const NO_APPROVER_REASON = "This action needs the approval of the user, and no one can answer here. Thus it did not run.";
+/** The harness request after a reply that a failed request cut. The model reads its partial reply, and continues it. */
+export const CONTINUE_REQUEST = "[The model request failed during your reply above. Continue the reply from where it stopped.]";
+/** A run that receives no turn accumulator is the turn's root. See `LoopOptions.turnUsage`. */
+export const isTurnRoot = (opts) => opts.turnUsage === undefined;
+/** The name of the durable step of each model call. It holds no model id, thus a change of the model never breaks a replay. */
+function modelStepName(agentId) {
+    return `${agentId}.model`;
+}
+/** Run an agent over `initial` until its reply ends the run. */
+export async function runLoop(agent, initial, session, opts) {
+    const conversation = openConversation(agent, initial, session, opts, agent.id);
+    return conversation.guard(async () => {
+        if (opts.turnInput !== undefined) {
+            const ended = await conversation.startTurn(opts.turnInput);
+            if (ended !== undefined)
+                return ended;
+        }
+        return conversation.run({ mask: opts.policy?.mask, maxRequests: agent.maxIterations, checksBudget: true });
+    });
+}
+/**
+ * Continue a finished conversation with one harness request. `agent` and `opts`
+ * must match the conversation's own, since each request extends its cached
+ * prefix. `conversation` itself is never changed. The result holds only the new
+ * messages, starting with the request.
+ */
+export async function continueLoop(agent, conversation, request, session, opts) {
+    const accountingAgentId = request.accountingAgentId;
+    const runSession = accountingAgentId === undefined ? session : forSubAgent(session, accountingAgentId);
+    const { onRound: _onRound, compaction: _compaction, turnInput: _turnInput, stopWhen: _stopWhen, capWhen: _capWhen, ...followUp } = opts;
+    const open = openConversation(agent, conversation, runSession, followUp, accountingAgentId ?? agent.id);
+    const result = await open.guard(() => open.run({
+        mask: request.mask,
+        maxRequests: request.maxRequests,
+        requestText: request.text,
+        endsOnRequestRefusal: request.endOnRequestRefusal === true,
+    }));
+    return { ...result, messages: result.messages.slice(conversation.length) };
+}
+/** Default salvage budget: one submit plus a fix of a refused submission or two. */
+export const DEFAULT_SALVAGE_REQUESTS = 3;
+/**
+ * Run an agent that has an outcome, and send one salvage request when the run
+ * ends with none and was not aborted. The salvage request lets only the
+ * terminal tools of the agent run. A salvaged result carries both runs'
+ * messages and steps and the summed rollups, with the finish of the salvage.
+ */
+export async function runWithSalvage(agent, initial, session, opts, salvage) {
+    const undeclared = salvage.tools.find((id) => !agent.tools.some((tool) => tool.id === id));
+    if (undeclared !== undefined) {
+        throw new Error(`The terminal tool "${undeclared}" is not a declared tool of the agent "${agent.id}", thus the salvage mask cannot let it run.`);
+    }
+    const first = await runLoop(agent, initial, session, opts);
+    if (salvage.hasOutcome(first.steps) || first.finish.reason === "aborted" || opts.signal.aborted)
+        return { ...first, salvage: null };
+    const maxRequests = salvage.maxRequests ?? DEFAULT_SALVAGE_REQUESTS;
+    (opts.logger ?? createNoopLogger()).named("loop").warn("salvaging a run that ended with no outcome", {
+        agentId: agent.id,
+        callPath: session.provenance.callPath,
+        firstFinishReason: first.finish.reason,
+        firstCappedOut: first.finish.cappedOut,
+        salvageTools: salvage.tools,
+        salvageMaxRequests: maxRequests,
+    });
+    const salvaged = await continueLoop(agent, first.messages, { text: salvage.nudge, mask: { allow: salvage.tools }, maxRequests }, session, opts);
+    return {
+        messages: [...first.messages, ...salvaged.messages],
+        steps: [...first.steps, ...salvaged.steps],
+        finish: {
+            ...salvaged.finish,
+            ...sumUsage("usage", first.finish, salvaged.finish),
+            ...sumUsage("turnUsage", first.finish, salvaged.finish),
+        },
+        salvage: { firstFinish: first.finish, finish: salvaged.finish },
+    };
+}
+function sumUsage(field, first, second) {
+    const a = first[field];
+    const b = second[field];
+    if (a === undefined && b === undefined)
+        return {};
+    const total = {};
+    addChatUsage(total, a);
+    addChatUsage(total, b);
+    return { [field]: total };
+}
+export function finalText(messages) {
+    const last = messages.at(-1);
+    if (last === undefined || last.role !== "assistant")
+        return "";
+    if (typeof last.content === "string")
+        return last.content;
+    return last.content
+        .filter((block) => block.type === "text")
+        .map((block) => block.text)
+        .join("");
+}
+/**
+ * Open the loop over one conversation. `metricAgentId` is the id that usage
+ * and run metrics count under, which is not always `agent.id`.
+ */
+function openConversation(agent, initial, session, opts, metricAgentId) {
+    const { provider, emit } = opts;
+    if (agent.tools.length > 0 && !provider.capabilities.toolCalling) {
+        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 log = (opts.logger ?? createNoopLogger()).named("loop").with({ agentId: session.provenance.agentId, callPath: session.provenance.callPath });
+    const policy = opts.compaction;
+    const viewOptions = { keepFirstTurn: policy?.keepFirstTurn === true };
+    const viewOf = (from) => (policy === undefined ? [...from] : conversationView(from, viewOptions).messages);
+    // A run handed no accumulator is the turn's root: it creates the one every
+    // descendant loop folds into, and it is the only loop entitled to report a
+    // turn total. Descendants receive the root's object and mutate it in place.
+    const turnUsage = opts.turnUsage ?? {};
+    const turnRoot = isTurnRoot(opts);
+    const usage = {};
+    const steps = [];
+    const calls = createCallPolicy(opts.policy ?? {});
+    let compactionStopped = false;
+    // The first request after a summary shows if the summary brought the conversation under the budget.
+    let summarizedLast = false;
+    /**
+     * Run one series, and wait out a failure that pauses. After the wait, the series runs again with the requests
+     * that it did not use. A partial reply of the failed request stays as an interrupted reply, and one harness
+     * request asks the model to continue it. A failure with no partial reply changes no message, thus the next
+     * request sends the same view.
+     */
+    const series = async (target, spec) => {
+        let current = spec;
+        let attempt = 0;
+        for (;;) {
+            const stepsBefore = target.steps.length;
+            const ended = await runSeries(agent, opts, calls, log, target, current);
+            if (ended.kind !== "failed")
+                return ended;
+            const used = target.steps.length - stepsBefore;
+            // A request that completed ends the outage, thus the timer of the next pause starts again.
+            if (used > 0)
+                attempt = 0;
+            const pauseEnd = opts.pause === undefined ? undefined : await opts.pause(ended.failure, attempt, opts.signal);
+            if (pauseEnd === undefined)
+                throw toThrowable(ended.failure);
+            const [reply, ...results] = ended.partial;
+            if (reply !== undefined) {
+                const from = target.messages.length;
+                target.messages.push(markInterruptedMessage(reply), ...results);
+                answerUnansweredToolCalls(target.messages, from);
+            }
+            if (pauseEnd === "abort")
+                return { kind: "aborted" };
+            attempt = pauseEnd === "retry" ? attempt + 1 : 0;
+            current = { ...current, maxRequests: current.maxRequests - used, requestText: reply === undefined ? undefined : CONTINUE_REQUEST };
+        }
+    };
+    const finishUsage = () => {
+        const rollups = {};
+        if (hasReportedUsage(usage))
+            rollups.usage = { ...usage };
+        if (turnRoot && hasReportedUsage(turnUsage))
+            rollups.turnUsage = { ...turnUsage };
+        return rollups;
+    };
+    /**
+     * Settle the transcript on the way out. A reply can carry a complete tool
+     * call beside any finish reason, and a call this run never ran 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.
+     */
+    const settleTranscript = () => {
+        const answered = answerUnansweredToolCalls(messages, initial.length);
+        if (answered.length === 0)
+            return;
+        log.warn("unanswered tool calls answered at run exit", { toolCallIds: answered.map((d) => d.toolCallId), tools: answered.map((d) => d.toolName) });
+    };
+    const end = async (seriesEnd) => {
+        settleTranscript();
+        const toolCalls = steps.reduce((n, step) => n + step.calls.length, 0);
+        const toolErrors = steps.reduce((n, step) => n + step.calls.filter((call) => call.refused || (call.output !== undefined && call.output.outcome !== "ok")).length, 0);
+        const finish = finishOf(seriesEnd, finishUsage());
+        recordAgentRun({ agentId: metricAgentId, iterations: steps.length, cappedOut: finish.cappedOut });
+        const level = finish.cappedOut || finish.reason === "denied" || seriesEnd.kind === "refused" ? "warn" : "info";
+        log[level]("run finished", { iterations: steps.length, reason: finish.reason, cappedOut: finish.cappedOut, toolCalls, toolErrors, usage });
+        await giveRound();
+        return { messages, finish, steps, refusal: seriesEnd.kind === "refused" ? seriesEnd.refusal : undefined };
+    };
+    const mainTarget = (beforeRequest) => ({
+        messages,
+        session,
+        metricAgentId,
+        rollups: [usage, turnUsage],
+        viewOf,
+        beforeRequest,
+        onText: opts.onText,
+        textStream: opts.chatStream,
+        steps,
+        stopWhen: opts.stopWhen,
+        capWhen: opts.capWhen,
+    });
+    /** The result of the run when an abort ends the exchange, or `undefined` when the run continues. */
+    const compact = async (active, tokensBefore, trigger) => {
+        // The body of a workflow records the id, thus a replay of the exchange gives the same id.
+        const id = DBOS.isInWorkflow() ? await DBOS.randomUUID() : randomUUID();
+        const startedAt = performance.now();
+        const source = sourceOf(session, opts.invocationId);
+        const emitPart = (data) => emit({ type: "data-compaction", source, data: { ...data, trigger } });
+        await emitPart({ id, status: "running", tokensBefore });
+        let settled = false;
+        try {
+            const exchangeAgentId = `${agent.id}-compaction`;
+            const view = viewOf(messages);
+            const exchange = [...view];
+            const exchangeEnd = await series({
+                messages: exchange,
+                session: forSubAgent(session, exchangeAgentId),
+                metricAgentId: exchangeAgentId,
+                rollups: [turnUsage],
+                viewOf: (from) => [...from],
+                steps: [],
+            }, { mask: active.mask, maxRequests: COMPACTION_MAX_REQUESTS, requestText: active.request, endsOnRequestRefusal: true });
+            const exchangeMessages = exchange.slice(view.length);
+            answerUnansweredToolCalls(exchangeMessages);
+            messages.push(...exchangeMessages.map((message) => markCompactionExchange(message, id)));
+            await giveRound();
+            if (exchangeEnd.kind === "aborted") {
+                settled = true;
+                await emitPart({ id, status: "failed", tokensBefore, durationMs: Math.round(performance.now() - startedAt) });
+                return "aborted";
+            }
+            const summary = exchangeEnd.kind === "reply" && exchangeEnd.finishReason === "stop" ? finalText(exchangeMessages).trim() : "";
+            if (summary.length === 0) {
+                settled = true;
+                const durationMs = Math.round(performance.now() - startedAt);
+                await emitPart({ id, status: "failed", tokensBefore, durationMs });
+                const refusal = exchangeEnd.kind === "refused" ? { status: exchangeEnd.refusal.status, providerError: exchangeEnd.refusal.message } : {};
+                log.error("compaction gave no summary, thus the run compacts no more", { compactionId: id, trigger, tokensBefore, durationMs, ...refusal });
+                compactionStopped = true;
+                return undefined;
+            }
+            const markerOf = (durationMs) => summaryMarkerMessage(summary, { kind: "summary", id, tokensBefore, durationMs, trigger });
+            // The figures of a marker do not change the view, thus a draft marker gives the view of the real one.
+            const records = await active.recordsAfter(conversationView([...messages, markerOf(0)], viewOptions).messages);
+            const durationMs = Math.round(performance.now() - startedAt);
+            messages.push(markerOf(durationMs), ...records);
+            settled = true;
+            // The `done` part goes out before the marker round: a chat turn gives the rounds after a marker a new
+            // assistant message, and the `running` and `done` parts of one compaction must stream into the same message.
+            await emitPart({ id, status: "done", tokensBefore, durationMs });
+            await giveRound();
+            log.info("conversation compacted", { compactionId: id, trigger, tokensBefore, durationMs });
+            summarizedLast = true;
+            return undefined;
+        }
+        finally {
+            if (!settled)
+                await emitPart({ id, status: "failed", tokensBefore, durationMs: Math.round(performance.now() - startedAt) });
+        }
+    };
+    const compactOverBudget = async () => {
+        if (policy === undefined || compactionStopped)
+            return;
+        const tokens = lastRequestInputTokens(messages);
+        if (tokens === undefined)
+            return;
+        const afterSummary = summarizedLast;
+        summarizedLast = false;
+        if (tokens <= policy.budget)
+            return;
+        if (afterSummary) {
+            log.warn("the first request after the summary still exceeds the budget, thus the run compacts no more", { tokens, budget: policy.budget });
+            compactionStopped = true;
+            return;
+        }
+        // An abort during the exchange aborts the request that follows it, thus the run ends as aborted.
+        await compact(policy, tokens, "mid-turn");
+    };
+    return {
+        async startTurn(input) {
+            const budget = policy?.turnStartBudget;
+            const tokens = lastRequestInputTokens(messages);
+            if (policy === undefined || budget === undefined || tokens === undefined || tokens <= budget) {
+                messages.push(...input);
+                return undefined;
+            }
+            const ended = await compact(policy, tokens, "turn-start");
+            if (ended === "aborted")
+                return end({ kind: "aborted" });
+            // The records after a summary give the current context, thus a record of the input would only repeat one.
+            messages.push(...(summarizedLast ? input.filter((message) => contextRecordOf(message) === undefined) : input));
+            return undefined;
+        },
+        async run(spec) {
+            const beforeRequest = async () => {
+                await giveRound();
+                if (spec.checksBudget === true)
+                    await compactOverBudget();
+            };
+            return end(await series(mainTarget(beforeRequest), spec));
+        },
+        // A throw keeps the open round, and the not-run results keep that stored round valid on the wire.
+        async guard(body) {
+            try {
+                return await body();
+            }
+            catch (err) {
+                log.error("run failed", { iterations: steps.length, ...log.errorFields(err) });
+                if (opts.onRound === undefined || 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;
+            }
+        },
+    };
+}
+function finishOf(seriesEnd, rollups) {
+    switch (seriesEnd.kind) {
+        case "reply":
+            return { reason: seriesEnd.finishReason, rawFinishReason: seriesEnd.rawFinishReason, cappedOut: false, ...rollups };
+        case "capped":
+        case "early-cap":
+            return { reason: "max_iterations", cappedOut: true, ...rollups };
+        case "stopped":
+            return { reason: "stop", cappedOut: false, ...rollups };
+        case "denied":
+            return { reason: "denied", cappedOut: false, ...rollups };
+        case "aborted":
+            return { reason: "aborted", cappedOut: false, ...rollups };
+        case "refused":
+            return { reason: "error", cappedOut: false, ...rollups };
+    }
+}
+function sourceOf(session, invocationId) {
+    const source = {
+        agentId: session.provenance.agentId,
+        callPath: session.provenance.callPath,
+    };
+    if (invocationId !== undefined)
+        source.invocationId = invocationId;
+    return source;
+}
+/** 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(failure) {
+    const error = findProviderError(failure);
+    if (error?.type !== "provider")
+        return undefined;
+    const status = extractStatus(error);
+    return status !== undefined && REFUSAL_STATUSES.has(status) ? { status, message: error.message } : undefined;
+}
+/** Whether the loop asks the model again after this step: each call of the reply has a result. */
+function continuesAfter(step) {
+    return step.calls.length > 0 && step.calls.every((call) => call.answered);
+}
+function deniedByUser(step) {
+    return step.calls.some((call) => call.output?.outcome === "denied");
+}
+/**
+ * Run one series of model requests with `streamText`, and say how it ended.
+ * A failed request ends the series as `failed`, and a fatal tool error leaves as a throw.
+ */
+async function runSeries(agent, opts, calls, log, target, spec) {
+    const { messages, session } = target;
+    const startIndex = messages.length;
+    if (spec.requestText !== undefined)
+        messages.push(syntheticUserMessage(spec.requestText));
+    const promptCache = opts.promptCache ?? DEFAULT_PROMPT_CACHE;
+    const source = sourceOf(session, opts.invocationId);
+    const bound = opts.provider.bind({
+        session,
+        reasoning: opts.reasoning,
+        live: target.onText !== undefined,
+        // A reader sees the retries of a request, thus a wait of the envelope is no silence. The part is transient,
+        // and a failed write of it changes nothing of the request.
+        onRetry: (retry) => {
+            const part = {
+                id: retry.requestId,
+                attempt: retry.attempt,
+                maxRetries: retry.maxRetries,
+                retryAt: new Date(Date.now() + retry.delayMs).toISOString(),
+                status: retry.status,
+            };
+            void Promise.resolve(opts.emit({ type: "data-model-retry", source, data: part })).catch(() => undefined);
+        },
+    });
+    const model = wrapLanguageModel({
+        model: bound.model,
+        middleware: [
+            rollupMiddleware(target.rollups),
+            durableCalls({ name: modelStepName(agent.id), retriesAllowed: false, durableStream: target.textStream }),
+            accountingMiddleware({
+                session,
+                agentId: target.metricAgentId,
+                invocationId: opts.invocationId,
+                usageRecorder: opts.usageRecorder ?? createNoopUsageRecorder(),
+                logger: log,
+            }),
+            ...(opts.modelMiddleware ?? []),
+        ],
+    });
+    // The work before the current request, which an abort of the stream does not wait for.
+    let preparing;
+    // The first fatal error of a tool call or of an approval ends the series, and the series throws it.
+    let fatal;
+    const fatalController = new AbortController();
+    const failRun = (err) => {
+        if (fatal !== undefined)
+            return;
+        fatal = err;
+        fatalController.abort(err);
+    };
+    const tools = adaptTools(agent.tools, {
+        session,
+        source,
+        emit: opts.emit,
+        turnUsage: target.rollups.at(-1) ?? {},
+        capabilities: opts.provider.capabilities,
+        // Only the read tool of the agent can read a kept text, thus an agent without it keeps nothing.
+        store: agent.tools.some((tool) => tool.id === READ_TOOL_OUTPUT_TOOL_ID) ? opts.toolOutputStore : undefined,
+        invocationId: opts.invocationId,
+        log,
+        writer: opts.toolWriter,
+        fail: failRun,
+    });
+    const toolsById = new Map(agent.tools.map((tool) => [tool.id, tool]));
+    // The calls that the user denied, with the reason that the model reads. A replay asks again, and the same answer
+    // comes back from the checkpoints of the turn.
+    const deniedByTheUser = new Map();
+    /** The reason of a denial of the user, or `undefined` for a call that runs. */
+    const userDenialOf = async (toolCall) => {
+        const tool = toolsById.get(toolCall.toolName);
+        if (tool?.approval === undefined)
+            return undefined;
+        // An input that does not parse needs no approval: `execute` gives the model its error.
+        const input = recordedInputOf(tool.inputSchema, toolCall.input);
+        if (input === undefined)
+            return undefined;
+        const request = await tool.approval(input, { invocationId: toolCall.toolCallId, session });
+        if (request === undefined)
+            return undefined;
+        if (opts.approve === undefined)
+            return NO_APPROVER_REASON;
+        const decision = await opts.approve(request, { toolCallId: toolCall.toolCallId, toolName: toolCall.toolName });
+        return decision.kind === "approved" ? undefined : deniedReason(decision.feedback);
+    };
+    const seriesSteps = [];
+    let open = openStep();
+    let failure;
+    const requestView = () => [...withPromptCacheBreakpoint(sanitizeMessages(target.viewOf(messages)), promptCache)];
+    const stops = () => seriesSteps.length >= spec.maxRequests ||
+        deniedByUser(seriesSteps.at(-1) ?? { finishReason: "", calls: [] }) ||
+        target.stopWhen?.(target.steps) === true ||
+        target.capWhen?.() === true;
+    const result = streamText({
+        model,
+        instructions: withSystemPromptBreakpoint(agent.systemPrompt, promptCache),
+        messages: requestView(),
+        tools,
+        toolChoice: "auto",
+        maxOutputTokens: bound.settings.maxOutputTokens,
+        reasoning: bound.settings.reasoning,
+        providerOptions: mergeProviderOptions(bound.settings.providerOptions, agent.providerOptions),
+        // The retry envelope of the provider owns the retries, inside the step of the call.
+        maxRetries: 0,
+        abortSignal: AbortSignal.any([opts.signal, fatalController.signal]),
+        telemetry: bound.telemetry,
+        toolApproval: async ({ toolCall }) => {
+            const refusal = calls.refusalOf({ toolName: toolCall.toolName, input: toolCall.input }, spec.mask);
+            if (refusal !== undefined) {
+                // A refused call does not run, thus its two events come from here.
+                await opts.emit({ type: "tool-started", source, toolUseId: toolCall.toolCallId, name: toolCall.toolName, input: toolCall.input });
+                await opts.emit({ type: "tool-finished", source, toolUseId: toolCall.toolCallId, name: toolCall.toolName, outcome: "error" });
+                return { type: "denied", reason: refusal };
+            }
+            let denial;
+            try {
+                denial = await userDenialOf(toolCall);
+            }
+            catch (err) {
+                // The SDK keeps a failed approval to itself, thus a cancel or an abort reaches the series here.
+                if (isFatalToolError(err))
+                    failRun(err);
+                throw err;
+            }
+            if (denial === undefined)
+                return undefined;
+            deniedByTheUser.set(toolCall.toolCallId, denial);
+            await opts.emit({ type: "tool-started", source, toolUseId: toolCall.toolCallId, name: toolCall.toolName, input: toolCall.input });
+            await opts.emit({ type: "tool-finished", source, toolUseId: toolCall.toolCallId, name: toolCall.toolName, outcome: "denied" });
+            return { type: "denied", reason: denial };
+        },
+        stopWhen: () => stops(),
+        prepareStep: async () => {
+            open = openStep();
+            const before = target.beforeRequest?.();
+            preparing = before;
+            await before;
+            return { messages: requestView() };
+        },
+        onChunk: async ({ chunk }) => {
+            switch (chunk.type) {
+                case "text-delta":
+                    open.text += chunk.text;
+                    await target.onText?.(chunk.text);
+                    return;
+                case "tool-call":
+                    if (chunk.providerExecuted !== true)
+                        open.calls.push({ type: "tool-call", toolCallId: chunk.toolCallId, toolName: chunk.toolName, input: chunk.input });
+                    return;
+                case "tool-result": {
+                    const output = ToolCallOutputSchema.safeParse(chunk.output);
+                    if (output.success)
+                        open.results.push({ type: "tool-result", toolCallId: chunk.toolCallId, toolName: chunk.toolName, output: modelViewOf(output.data) });
+                    return;
+                }
+                default:
+                    return;
+            }
+        },
+        onError: ({ error }) => {
+            failure ??= error;
+        },
+        onStepEnd: async (step) => {
+            open = openStep();
+            const loopStep = loopStepOf(step, deniedByTheUser);
+            messages.push(...recordedMessagesOf(step, loopStep));
+            foldCallRecords(agent.tools, loopStep.calls, log);
+            seriesSteps.push(loopStep);
+            target.steps.push(loopStep);
+            if (loopStep.calls.length > 0)
+                log.debug("iteration", { iteration: seriesSteps.length - 1, tools: loopStep.calls.map((call) => call.toolName) });
+            await opts.emit({ type: "iteration", source, index: seriesSteps.length - 1, final: !continuesAfter(loopStep) || stops() });
+        },
+    });
+    await result.consumeStream({
+        onError: (error) => {
+            failure ??= error;
+        },
+    });
+    // An abort ends the stream while the work before a request can still run, for example a compaction that
+    // writes its round. The series ends after that work, thus the run never writes a round beside it.
+    await preparing?.catch(() => undefined);
+    const callerAborted = opts.signal.aborted;
+    if (fatal !== undefined && !(callerAborted && errorNameOf(fatal) === "AbortError")) {
+        messages.push(...openStepMessages(open));
+        answerUnansweredToolCalls(messages, startIndex);
+        throw toThrowable(fatal);
+    }
+    if (callerAborted) {
+        // An interrupted turn keeps whatever the model wrote before the cut, but never an empty shell.
+        const [reply, ...results] = openStepMessages(open);
+        if (reply !== undefined)
+            messages.push(markInterruptedMessage(reply), ...results);
+        answerUnansweredToolCalls(messages, startIndex);
+        return { kind: "aborted" };
+    }
+    if (failure !== undefined && !isFatalToolError(failure)) {
+        const refusal = spec.endsOnRequestRefusal === true ? requestRefusalOf(failure) : undefined;
+        answerUnansweredToolCalls(messages, startIndex);
+        if (refusal !== undefined)
+            return { kind: "refused", refusal };
+        return { kind: "failed", failure, partial: openStepMessages(open) };
+    }
+    const last = seriesSteps.at(-1);
+    if (last === undefined)
+        throw new Error(`The run of the agent "${agent.id}" ended with no completed request.`);
+    if (!continuesAfter(last))
+        return { kind: "reply", finishReason: last.finishReason, rawFinishReason: last.rawFinishReason };
+    if (deniedByUser(last))
+        return { kind: "denied" };
+    if (target.stopWhen?.(target.steps) === true)
+        return { kind: "stopped" };
+    if (target.capWhen?.() === true) {
+        log.warn("run stopped early by the host policy", { iterations: seriesSteps.length });
+        return { kind: "early-cap" };
+    }
+    return { kind: "capped" };
+}
+function openStep() {
+    return { text: "", calls: [], results: [] };
+}
+/** The reply of a cut step and the results of its calls that completed. A step with no text and no call gives nothing. */
+function openStepMessages(open) {
+    if (open.text.length === 0 && open.calls.length === 0)
+        return [];
+    if (open.calls.length === 0)
+        return [{ role: "assistant", content: open.text }];
+    const text = open.text.length > 0 ? [{ type: "text", text: open.text }] : [];
+    const messages = [{ role: "assistant", content: [...text, ...open.calls] }];
+    const results = open.results.filter((result) => open.calls.some((call) => call.toolCallId === result.toolCallId));
+    if (results.length > 0)
+        messages.push({ role: "tool", content: results });
+    return messages;
+}
+/** The harness view of one completed step: each tool call of the reply, with its output when it ran. */
+function loopStepOf(step, deniedByTheUser) {
+    const outputs = new Map();
+    for (const result of step.toolResults)
+        outputs.set(result.toolCallId, result.output);
+    const answered = new Set(outputs.keys());
+    const refused = new Set();
+    for (const part of step.content) {
+        if (part.type === "tool-error")
+            answered.add(part.toolCallId);
+        if (part.type === "tool-approval-response" && !part.approved) {
+            answered.add(part.toolCall.toolCallId);
+            if (!deniedByTheUser.has(part.toolCall.toolCallId))
+                refused.add(part.toolCall.toolCallId);
+        }
+    }
+    const calls = step.toolCalls
+        .filter((call) => call.providerExecuted !== true)
+        .map((call) => {
+        const parsed = outputs.has(call.toolCallId) ? ToolCallOutputSchema.safeParse(outputs.get(call.toolCallId)) : undefined;
+        const denial = deniedByTheUser.get(call.toolCallId);
+        return {
+            toolCallId: call.toolCallId,
+            toolName: call.toolName,
+            input: call.input,
+            output: denial === undefined ? (parsed?.success === true ? parsed.data : undefined) : { outcome: "denied", reason: denial },
+            refused: refused.has(call.toolCallId),
+            answered: answered.has(call.toolCallId),
+        };
+    });
+    return { finishReason: step.finishReason, rawFinishReason: step.rawFinishReason, calls };
+}
+/**
+ * The messages of one step as the transcript records them. The request after
+ * them sends them as they are recorded, thus the record is the prefix of the
+ * next request.
+ *
+ * - The assistant message holds the input tokens of its request, which the
+ *   budget checks read, and it holds no thinking after a fallback hop.
+ * - A refusal of the policy reads as the error result of the call. A denial
+ *   reads as a decision of the user, and the reload of a thread reports the
+ *   outcome of each call from its result.
+ * - The approval parts go: they describe the approval, and the wire drops them.
+ */
+function recordedMessagesOf(step, loopStep) {
+    const refused = new Set(loopStep.calls.filter((call) => call.refused).map((call) => call.toolCallId));
+    const servedByFallback = fallbackModelOf(step.providerMetadata) !== undefined;
+    const inputTokens = step.usage.inputTokens;
+    const recorded = [];
+    for (const message of step.response.messages) {
+        if (message.role === "assistant") {
+            const content = typeof message.content === "string" ? message.content : message.content.filter((part) => part.type !== "tool-approval-request");
+            let assistant = { ...message, content };
+            if (servedByFallback) {
+                const stripped = withoutReasoning(assistant);
+                assistant = stripped?.role === "assistant" ? stripped : undefined;
+            }
+            if (assistant === undefined)
+                continue;
+            recorded.push(inputTokens === undefined ? assistant : withRequestInputTokens(assistant, inputTokens));
+            continue;
+        }
+        const content = message.content.flatMap((part) => {
+            if (part.type === "tool-approval-response")
+                return [];
+            if (part.output.type === "execution-denied" && refused.has(part.toolCallId)) {
+                return [{ ...part, output: { type: "error-text", value: part.output.reason ?? "" } }];
+            }
+            return [part];
+        });
+        if (content.length > 0)
+            recorded.push({ role: "tool", content });
+    }
+    return recorded;
+}
+function mergeProviderOptions(base, extra) {
+    if (extra === undefined)
+        return base;
+    if (base === undefined)
+        return extra;
+    const merged = { ...base };
+    for (const [namespace, options] of Object.entries(extra))
+        merged[namespace] = { ...base[namespace], ...options };
+    return merged;
+}
+/**
+ * Drop empty text parts — and messages left with no content at all — before
+ * the request. The Anthropic Messages API rejects any request containing an
+ * empty text block, and a stored thread can hold one.
+ */
+function sanitizeMessages(messages) {
+    const out = [];
+    for (const m of messages) {
+        if (typeof m.content === "string") {
+            if (m.content !== "")
+                out.push(m);
+            continue;
+        }
+        // The filtered parts are a subset of this message's own content, so the
+        // switch recovers the role-to-content correlation that `filter` loses.
+        switch (m.role) {
+            case "assistant": {
+                const parts = m.content.filter((p) => p.type !== "text" || p.text !== "");
+                if (parts.length > 0)
+                    out.push({ ...m, content: parts });
+                break;
+            }
+            case "user": {
+                const parts = m.content.filter((p) => p.type !== "text" || p.text !== "");
+                if (parts.length > 0)
+                    out.push({ ...m, content: parts });
+                break;
+            }
+            case "tool": {
+                if (m.content.length > 0)
+                    out.push(m);
+                break;
+            }
+            case "system":
+                break;
+        }
+    }
+    return out;
+}