@inflexa-ai/harness 0.45.1 → 0.46.0

package/dist/loop/run-agent.js

@@ -1,1124 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { jsonSchema, tool as aiTool, } from "ai";
-import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
-import { stripNulCharacters } from "../input-sanitization.js";
-import { createNoopLogger } from "../lib/console-logger.js";
-import { deliverNotice } from "../lib/hooks.js";
-import { passThroughSpan } from "../lib/otel-spans.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 { contextRecordOf, markCompactionExchange, markInterruptedMessage, summaryMarkerMessage, syntheticUserMessage, withRequestInputTokens, } from "../memory/ai-sdk-message-storage.js";
-import { conversationView, lastRequestInputTokens } 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, readToolCallRecord, readToolResultImages, } from "../tools/define-tool.js";
-import { labelToolFailure, labelToolValidationFailure, recordToolException, traceAgentRun, traceToolCall } from "./genai-spans.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 = {
-    llm: (i) => `llm-${i}`,
-    tool: (name, id) => `tool-${name}-${id}`,
-};
-/** A run that receives no turn accumulator is the turn's root. See `RunAgentOptions.turnUsage`. */
-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);
-    if (opts.turnInput !== undefined) {
-        const ended = await loop.startTurn(opts.turnInput);
-        if (ended !== undefined)
-            return ended;
-    }
-    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 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
-    // model-visible error result and retried by the loop.
-    const isFatalLoopError = (err) => ((err instanceof Error || err instanceof DOMException) && err.name === "AbortError") || configuredFatalLoopError(err);
-    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 source = {
-        agentId: session.provenance.agentId ?? agent.id,
-        callPath: session.provenance.callPath,
-        ...(opts.invocationId === undefined ? {} : { invocationId: opts.invocationId }),
-    };
-    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;
-    // The first request after a summary shows if the summary brought the conversation under the budget.
-    let summarizedLast = false;
-    // 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;
-    // rendering `parent > child` is the sink's choice, not a published package's.
-    const log = (opts.logger ?? createNoopLogger()).named("loop").with({ agentId: source.agentId, callPath: source.callPath });
-    // The picture of a tool result rides where the wire renders it. Absent flags
-    // mean "cannot carry", thus the loop degrades to text and records the drop.
-    // 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({
-            description: t.description,
-            inputSchema: jsonSchema(t.jsonSchema),
-        }),
-    ]));
-    // Approval resolves once to the caller's seam, or the deny-by-default one
-    // when it wires none: a tool that pauses for a user decision where no
-    // interactive surface is present is denied rather than left waiting on an
-    // answer that cannot come.
-    const unavailableAsk = new UnavailableAsk();
-    const ask = opts.ask ?? ((request) => unavailableAsk.ask(request));
-    // 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 toolCtx = (tu) => ({
-        invocationId: tu.toolCallId,
-        session,
-        signal,
-        emit,
-        ask,
-        turnUsage,
-    });
-    let iterations = 0;
-    let truncationRecoveries = 0;
-    let stoppedEarly = false;
-    // Counted rather than listed: the finish record stays one bounded line for a run of
-    // any length, and "50 iterations, 49 tool calls, 47 of them errored" already separates
-    // a productive long run from a loop stuck retrying one failing call. The per-iteration
-    // `debug` records name the tools when that distinction is not enough.
-    let toolCallCount = 0;
-    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 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;
-    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
-    // per-iteration detail lives at `debug`, where paying per iteration is the point.
-    const logFinish = (level, reason, cappedOut) => {
-        log[level]("run finished", { iterations, reason, cappedOut, truncationRecoveries, toolCalls: toolCallCount, toolErrors: toolErrorCount, usage });
-    };
-    /**
-     * Settle the transcript on the way out — called at every return. A reply can
-     * 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 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 answeredCalls = answerUnansweredToolCalls(messages, initial.length);
-        if (answeredCalls.length === 0)
-            return;
-        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();
-    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 withRequestAnchor(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 withRequestAnchor(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 (index) => {
-        settleTranscript();
-        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() } };
-    };
-    /**
-     * The call details for one dispatch round, positionally aligned with `calls`.
-     *
-     * Computed once per round and carried onto both the `tool-started` and the
-     * `tool-finished` event, so the pair a host renders as one chip cannot show
-     * two different descriptions of the same call. A tool that describes its own
-     * result replaces the second half of that pair with the outcome it produced.
-     */
-    const roundDetails = (calls) => calls.map((tu) => {
-        const tool = toolsById.get(tu.toolName);
-        return tool === undefined ? undefined : computeDetail(tool, tu.input, log);
-    });
-    /**
-     * Fold one dispatch round into the run's counters and the event sink, returning the
-     * tools whose results the model will read as errors.
-     *
-     * Shared by both dispatch paths so a truncated round and a normal one cannot drift
-     * in what they count. An error tool result is otherwise invisible to every sink —
-     * it is not a thrown failure, so nothing reports it and the loop simply feeds it
-     * back — and a run that ends badly is usually a run whose tool calls were failing.
-     *
-     * `details`, `resultDetails` and `durations` are positionally aligned with `calls`.
-     * `dispatchTools` measures a duration around the call itself, because this sink emits
-     * every finish event only after the whole round settles.
-     */
-    const settleRound = async (calls, results, details, resultDetails, durations) => {
-        const errored = [];
-        for (let idx = 0; idx < calls.length; idx++) {
-            const tu = calls[idx];
-            const outcome = outcomeOf(results[idx]);
-            toolCallCount++;
-            // A denial counts here with the errors: the model reads it as a result
-            // it did not get to act on, which is what these counters describe. The
-            // event keeps the two apart for the user-facing surface.
-            if (outcome !== "ok") {
-                toolErrorCount++;
-                errored.push(tu.toolName);
-            }
-            await emit({
-                type: "tool-finished",
-                source,
-                toolUseId: tu.toolCallId,
-                name: tu.toolName,
-                outcome,
-                // The result detail wins where there is one, and the call detail
-                // stands otherwise. Only the ok branch of a dispatch computes a
-                // result detail, thus an error and a denial reach here with none
-                // and keep the line the `tool-started` carried.
-                ...detailField(resultDetails[idx] ?? details[idx]),
-                ...durationField(durations[idx]),
-            });
-        }
-        return errored;
-    };
-    // 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, toolCtx, isFatalLoopError, callStep, names.tool, encoding, cut);
-    };
-    const stopOnResolved = async (index) => {
-        settleTranscript();
-        await emit({ type: "iteration", source, index, final: true });
-        recordAgentRun({ agentId: metricAgentId, iterations, cappedOut: false });
-        await giveRound();
-        return { messages, finish: { reason: "stop", cappedOut: false, truncationRecoveries } };
-    };
-    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, trigger) => {
-        const id = randomUUID();
-        const stepNamespace = `compaction-${compactions++}`;
-        const startedAt = performance.now();
-        const emitPart = (data) => emit({ type: "data-compaction", source, data: { ...data, trigger } });
-        await emitPart({ id, status: "running", tokensBefore });
-        const { onRound: _onRound, compaction: _compaction, turnInput: _turnInput, ...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);
-            if (summary === undefined) {
-                settled = true;
-                const durationMs = Math.round(performance.now() - startedAt);
-                await emitPart({ id, status: "failed", tokensBefore, durationMs });
-                const refusal = exchange.refusal === undefined ? {} : { status: exchange.refusal.status, providerError: exchange.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 startTurn = async (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, 0, "turn-start");
-        if (ended !== undefined)
-            return ended;
-        // 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;
-    };
-    const compactOverBudget = async (index) => {
-        if (policy === undefined || continuesTruncation || compactionStopped)
-            return undefined;
-        const tokens = lastRequestInputTokens(messages);
-        if (tokens === undefined)
-            return undefined;
-        const afterSummary = summarizedLast;
-        summarizedLast = false;
-        if (tokens <= policy.budget)
-            return undefined;
-        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 undefined;
-        }
-        return compact(policy, tokens, index, "mid-turn");
-    };
-    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++) {
-            // The early cap ends a segment before the cap as if the cap were reached, thus a run takes its
-            // tool-less wrap-up. The segment that closes a capped run is that wrap-up, and it runs to its end.
-            if (segment.closesCappedRun !== true && opts.stopWhen?.()) {
-                stoppedEarly = true;
-                log.warn("run stopped early by the host policy, taking the wrap-up path", { iterations });
-                return "capped";
-            }
-            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;
-            }
-            // 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 });
-                    if (stoppedEarly)
-                        log.warn("run finished on the early cap", { iterations });
-                    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(),
-                    },
-                };
-            }
-            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(index);
-            if (opts.resolved?.())
-                return stopOnResolved(index);
-        }
-        return "capped";
-    };
-    const endCapped = async () => {
-        settleTranscript();
-        recordAgentRun({ agentId: metricAgentId, iterations, cappedOut: true });
-        if (stoppedEarly)
-            log.warn("run finished on the early cap", { iterations });
-        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();
-        }
-        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;
-        }
-    };
-    return {
-        startTurn: (input) => giveRoundBeforeThrow(() => startTurn(input)),
-        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;
-}
-/** The reply whose message holds the input tokens of its request, which the budget checks read. */
-function withRequestAnchor(reply) {
-    const tokens = reply.usage?.inputTokens;
-    return tokens === undefined ? reply : { ...reply, message: withRequestInputTokens(reply.message, tokens) };
-}
-/**
- * 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.
- *
- * Deliberately not the `:` that separates the key's segments, so a call path
- * can never be read as one: agent ids are kebab-case identifiers, run ids are
- * 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, a profile attempt's workflow id is
- * `dataprofile:{analysisId}:{nonce}`, and the loop's step names are `llm-{n}`
- * / `tool-{name}-{id}` 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, 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
- * re-executed body re-fires `record` with the byte-identical key and an
- * upserting sink counts the call once. Each earns its place by a collision it
- * alone resolves:
- *
- * - `stepId` — `executeAnalysis` runs one child workflow per step under a
- *   single shared `runId`, and each step's loop names its first call `llm-0`.
- * - `callPath` — a step name is unique only within ONE loop invocation (every
- *   `runAgent` restarts its names at `llm-0`), and several loops routinely run
- *   under one frame: a step's post-step describer and its summary writer share
- *   `{runId, stepId}`, and the run-synthesis loop shares a bare `{runId}` with
- *   the sub-agents its tools run. The provenance path is what separates those
- *   agent chains.
- * - `invocationId` — the same sub-agent dispatched twice in one round has an
- *   identical call path, so only the dispatching tool-call id tells the two
- *   child loops apart. It is replay-stable by the harness-tools contract: a
- *   redelivered call carries the id it was issued under. Each data profile
- *   runs under the same constant frame, thus the workflow id of its attempt
- *   takes this place, and a replay of the attempt keeps that id.
- * - `stepName` — the loop's own deterministic name, reused rather than
- *   re-derived. Minting a second *naming* scheme here would create two things
- *   that must agree about what "the same call" is, and they would drift.
- *
- * Outside a `RunFrame` there is no replay to be safe against (the HTTP chat
- * path runs a call exactly once), so a fresh id is enough and is what keeps two
- * calls in one turn distinct.
- */
-function recordKeyFor(session, invocationId, stepName) {
-    const frame = session.runFrame;
-    if (frame === undefined)
-        return randomUUID();
-    return [
-        frame.runId,
-        ...(frame.stepId === undefined ? [] : [frame.stepId]),
-        session.provenance.callPath.join(CALL_PATH_DELIMITER),
-        ...(invocationId === undefined ? [] : [invocationId]),
-        stepName,
-    ].join(":");
-}
-function toolCallParts(message) {
-    if (typeof message.content === "string")
-        return [];
-    return message.content.filter((part) => part.type === "tool-call");
-}
-/** Whether an aborted partial carries any content worth persisting — an empty partial contributes no message. */
-function assistantHasContent(message) {
-    return message.content.length > 0;
-}
-/**
- * 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, roundStart) {
-    for (let idx = messages.length - 1; idx >= roundStart; idx--) {
-        const message = messages[idx];
-        if (message.role === "assistant") {
-            messages[idx] = markInterruptedMessage(message);
-            return;
-        }
-    }
-}
-/**
- * Where a tool picture goes for this wire. The tool result wins, because it is
- * the native place and the correlation to the tool call stays implicit. The user
- * message is the fallback. When the wire renders neither, the loop drops the
- * picture.
- */
-function imagePlacementFor(capabilities) {
-    if (capabilities.imageToolResults === true)
-        return "tool-result";
-    if (capabilities.imageUserMessages === true)
-        return "user-message";
-    return "drop";
-}
-/**
- * The text part that names one deferred picture. The wire holds no structural
- * link between a user message and a tool call, thus the line names the call. A
- * result with several pictures numbers each one, thus the model reads which
- * slice it looks at.
- */
-function deferredImageLabel(deferred, index) {
-    const call = `the tool result ${deferred.toolCallId} of ${deferred.toolName}`;
-    return deferred.images.length === 1 ? `The picture of ${call}.` : `The picture ${index + 1} of ${deferred.images.length} of ${call}.`;
-}
-/**
- * Append one user message that carries each deferred picture of the round, then
- * empty the collector.
- *
- * The tool message must come directly after the assistant message with the
- * tool calls. Thus a picture rides a separate message after the whole tool
- * message, and one message batches the round. The parts obey the order of
- * `results`, which is the order of the tool calls, and the pictures of one
- * result keep the order that the tool gave. Each deferred picture has a result
- * of this round, because the collector fills during the dispatch and it empties
- * here. A text part names the tool call of each picture, because the wire holds
- * no structural link between a user message and a tool call.
- *
- * The message carries the synthetic marker, because a `user` message opens a
- * conversation turn. An unmarked one is loop machinery that reads as a turn
- * boundary, and it splits one stored turn in two.
- */
-function appendDeferredImages(messages, results, deferredImages) {
-    if (deferredImages.length === 0)
-        return;
-    const byToolCallId = new Map(deferredImages.map((deferred) => [deferred.toolCallId, deferred]));
-    const content = [];
-    for (const result of results) {
-        const deferred = byToolCallId.get(result.toolCallId);
-        if (deferred === undefined)
-            continue;
-        for (const [index, image] of deferred.images.entries()) {
-            content.push({ type: "text", text: deferredImageLabel(deferred, index) });
-            content.push({ type: "file", mediaType: image.mediaType, data: { type: "data", data: image.base64 } });
-        }
-    }
-    messages.push(syntheticUserMessage(content));
-    deferredImages.length = 0;
-}
-/**
- * Dispatch one round of tool calls, measure the time of each call, and fold the
- * call record of each call in call order.
- *
- * `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, 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
-    // 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,
-    // and `settleRound` then reads the call detail.
-    const resultDetails = new Array(toolUses.length);
-    const records = new Array(toolUses.length);
-    const stepTools = [];
-    const inlineTools = [];
-    for (const [idx, tu] of toolUses.entries()) {
-        const mode = toolsById.get(tu.toolName)?.executionMode ?? "step";
-        if (mode === "inline")
-            inlineTools.push({ tu, idx });
-        else
-            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, 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;
-            records[idx] = dispatched.record;
-        });
-    }));
-    for (const { tu, idx } of inlineTools) {
-        const refusal = refusals[idx];
-        const startedAt = performance.now();
-        const dispatched = await dispatch(tu, refusal);
-        results[idx] = dispatched.result;
-        if (dispatched.detail !== undefined)
-            resultDetails[idx] = dispatched.detail;
-        records[idx] = dispatched.record;
-        if (refusal === undefined)
-            durations[idx] = elapsedMs(startedAt);
-    }
-    // After the whole round, in call order: the parallel step calls settle in any
-    // order, and a replay must fold the same records in the same sequence.
-    for (const [idx, tu] of toolUses.entries()) {
-        const record = records[idx];
-        if (record !== undefined)
-            foldCallRecord(toolsById.get(tu.toolName), tu, record, encoding.log);
-    }
-    return { results, durations, resultDetails };
-}
-/** Hand one call record to the tool that made it. A throw is logged, because the call has settled already. */
-function foldCallRecord(tool, tu, record, log) {
-    if (tool?.foldCallRecord === undefined)
-        return;
-    try {
-        tool.foldCallRecord(record);
-    }
-    catch (err) {
-        log.error("a tool call record did not fold", { tool: tool.id, toolCallId: tu.toolCallId, ...log.errorFields(err) });
-    }
-}
-/** Whole milliseconds since `startedAt`, on the monotonic clock that took that mark. */
-function elapsedMs(startedAt) {
-    return Math.round(performance.now() - startedAt);
-}
-/**
- * Read one settled step-mode dispatch, tolerating the bare result beside the pair.
- *
- * A step-mode call goes through `runStep`, which caches what the body returned and hands
- * that cached value back on a replay. The durable step store therefore holds values that
- * a DIFFERENT build of this file wrote: a workflow in flight when the shape of the return
- * widened replays the bare `ToolResultPart` its own run cached, and it never re-enters the
- * body that would produce the pair. The replay boundary is the whole reason for the test:
- * a bare value carries no detail, thus the call keeps the line its `tool-started` showed.
- */
-function readDispatchedStep(settled) {
-    return "result" in settled ? settled : { result: settled };
-}
-/** 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");
-        return { result: errorResult(tu, `unknown tool: ${tu.toolName}`) };
-    }
-    const parsed = tool.inputSchema.safeParse(tu.input);
-    if (parsed.success)
-        return execute(tu, tool, parsed.data, ctx, isFatalLoopError, encoding);
-    // A complete JSON argument can arrive as a string behind function-call
-    // markup or a code fence. Repair only makes the schema reachable — the
-    // repaired value is validated in full, and the tool's own semantic checks
-    // still run, so nothing here weakens validation.
-    const repairedInput = repairToolInput(tu.input, parsed.error);
-    const repaired = repairedInput === undefined ? undefined : tool.inputSchema.safeParse(repairedInput);
-    if (repaired?.success === true)
-        return execute(tu, tool, repaired.data, ctx, isFatalLoopError, encoding);
-    // The Zod text can quote the input, thus the span and the log get only the shape of the failure.
-    const issues = describeZodIssueShapes(parsed.error, tool.inputSchema);
-    labelToolValidationFailure(issues);
-    encoding.log.warn("tool call rejected", { tool: tool.id, toolCallId: tu.toolCallId, issues });
-    return { result: errorResult(tu, `input validation failed: ${formatZodIssues(parsed.error, tu.input)}`) };
-}
-async function execute(tu, tool, input, ctx, isFatalLoopError, encoding) {
-    try {
-        const output = await tool.execute(input, ctx);
-        if (output.isErr()) {
-            markToolFailure(tu, tool, output.error, encoding.log);
-            return { result: errorResult(tu, toolErrorContent(output.error)) };
-        }
-        // The one place a result description runs: the ok value in hand, the
-        // input already validated, and the guard inside the compute.
-        const detail = computeResultDetail(tool, input, output.value, encoding.log);
-        const record = readToolCallRecord(output.value);
-        const result = successResult(tu, output.value, encoding);
-        return { result, ...(detail === undefined ? {} : { detail }), ...(record === undefined ? {} : { record }) };
-    }
-    catch (err) {
-        if (isFatalLoopError(err))
-            throw err;
-        if (isAskRejected(err))
-            return { result: deniedResult(tu, err.feedback) };
-        markToolFailure(tu, tool, err, encoding.log);
-        return { result: errorResult(tu, toolErrorContent(err)) };
-    }
-}
-/**
- * Label the span of a tool call that our tool code failed. A `ToolError` is a
- * failure that the tool modeled, thus its own text is the account, with no
- * exception and no log. Any other `Error` is a fault that the tool did not
- * model: the span records the exception, and the log gets one warn.
- */
-function markToolFailure(tu, tool, failure, log) {
-    const toolError = modeledToolError(failure);
-    if (toolError !== undefined) {
-        labelToolFailure("tool_error", toolError.error);
-    }
-    else if (failure instanceof Error) {
-        recordToolException(failure);
-        log.warn("tool call threw", { tool: tool.id, toolCallId: tu.toolCallId, ...log.errorFields(failure) });
-    }
-    else {
-        labelToolFailure("_OTHER");
-    }
-}
-/** The `ToolError` of a failure: the value itself, or the value that `unwrapOrThrow` wrapped in a `ResultError`. */
-function modeledToolError(failure) {
-    if (isToolError(failure))
-        return failure;
-    return failure instanceof ResultError && isToolError(failure.value) ? failure.value : undefined;
-}
-/**
- * Normalize a tool's return value to plain JSON, stripping NUL from every string
- * it holds ({@link stripNulCharacters}). The reviver sees values, not keys — a
- * NUL in an object KEY would still reach the row, but keys come from tool result
- * types rather than scanned bytes, so nothing produces one.
- */
-function jsonValue(value) {
-    return JSON.parse(JSON.stringify(value ?? null), (_key, v) => (typeof v === "string" ? stripNulCharacters(v) : v));
-}
-/**
- * Encode a tool ok value onto a tool-result message. A value with no picture
- * stays a plain JSON result, byte-identical to a value that never carried one.
- *
- * A value that carries pictures splits: the JSON data goes to a text part, and
- * the bytes ride as image content blocks after it, in the order that the tool
- * gave. Thus the model sees each picture, and the JSON text holds no bytes. When
- * the wire carries no picture, the blocks drop and the text stays, because
- * base64 text floods the context and the model cannot see it. One warn with the
- * count rides the log, thus an operator sees how many pictures did not reach the
- * model.
- *
- * A wire that renders a picture on a user message only gets the fallback: the
- * result keeps its JSON text, and the pictures go to the collector of the round.
- * The round then sends the bytes after the tool message.
- */
-function successResult(toolCall, value, encoding) {
-    const jsonData = jsonValue(value);
-    const jsonOnly = {
-        type: "tool-result",
-        toolCallId: toolCall.toolCallId,
-        toolName: toolCall.toolName,
-        output: { type: "json", value: jsonData },
-    };
-    const images = readToolResultImages(value);
-    if (images.length === 0)
-        return jsonOnly;
-    if (encoding.placement === "drop") {
-        encoding.log.warn("the wired provider carries no picture in a tool result, thus the pictures are dropped", {
-            toolName: toolCall.toolName,
-            imageCount: images.length,
-        });
-        return jsonOnly;
-    }
-    if (encoding.placement === "user-message") {
-        encoding.deferredImages.push({ toolCallId: toolCall.toolCallId, toolName: toolCall.toolName, images });
-        return jsonOnly;
-    }
-    return {
-        type: "tool-result",
-        toolCallId: toolCall.toolCallId,
-        toolName: toolCall.toolName,
-        output: {
-            type: "content",
-            value: [
-                { type: "text", text: JSON.stringify(jsonData) },
-                ...images.map((image) => ({ type: "file", mediaType: image.mediaType, data: { type: "data", data: image.base64 } })),
-            ],
-        },
-    };
-}
-// NUL is stripped from the prose BEFORE it is serialized: past the stringify it
-// is the six-character escape \u0000 — legitimate JSON text, and no longer
-// distinguishable from an error that happens to quote that escape.
-function toolErrorContent(value) {
-    const toolError = modeledToolError(value);
-    if (toolError !== undefined) {
-        return JSON.stringify({ error: stripNulCharacters(toolError.error), retryable: toolError.retryable });
-    }
-    const { retryable } = classifyProviderError(value);
-    const error = stripNulCharacters(value instanceof Error ? value.message : String(value));
-    return JSON.stringify({ error, retryable });
-}
-function errorResult(toolCall, content) {
-    return {
-        type: "tool-result",
-        toolCallId: toolCall.toolCallId,
-        toolName: toolCall.toolName,
-        // A thrown tool error routinely quotes stderr verbatim — as exposed to NUL as a success payload.
-        output: { type: "error-text", value: stripNulCharacters(content) },
-    };
-}
-function isAskRejected(err) {
-    // Name-based fallback recognizes a rejection thrown from a different module
-    // realm, where `instanceof` against this file's class reference would miss it.
-    return err instanceof AskRejectedError || (err instanceof Error && err.name === "AskRejectedError");
-}
-/**
- * Map a rejected approval to a model-visible `execution-denied` tool result. The
- * prose is the model's only account of the denial; `outcomeOf` reports it as
- * `denied`, distinct from a fault.
- */
-function deniedResult(toolCall, feedback) {
-    const reason = feedback === undefined || feedback.length === 0
-        ? "The user rejected this action."
-        : `The user rejected this action with the following feedback: ${feedback}`;
-    return {
-        type: "tool-result",
-        toolCallId: toolCall.toolCallId,
-        toolName: toolCall.toolName,
-        output: { type: "execution-denied", reason },
-    };
-}
-function outcomeOf(result) {
-    return toolOutcomeForOutputType(result.output.type);
-}
-/**
- * The optional `detail` field, present only when there is one. Spread rather
- * than assigned so an undescribed call emits an event with no `detail` key at
- * all, which is what the contract promises: absent, never empty.
- */
-function detailField(detail) {
-    return detail === undefined ? {} : { detail };
-}
-/**
- * The optional `durationMs` field, present only for a call that the loop measured.
- *
- * Spread rather than assigned, for the same reason as {@link detailField}: an
- * unmeasured call emits no `durationMs` key. A zero here is a real measurement of a
- * call that took under half a millisecond, and it is never a stand-in for no figure.
- */
-function durationField(durationMs) {
-    return durationMs === undefined ? {} : { durationMs };
-}
-function hasDenial(results) {
-    return results.some((r) => r.output.type === "execution-denied");
-}
-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("");
-}
-function formatZodIssues(error, input) {
-    return error.issues
-        .map((issue) => {
-        const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
-        const hint = hintForZodIssue(issue, input);
-        return hint === undefined ? `${path}: ${issue.message}` : `${path}: ${issue.message} — ${hint}`;
-    })
-        .join("; ");
-}