@framers/agentos 0.10.22 → 0.10.24

package/dist/api/generateText.js

@@ -17,7 +17,7 @@ import { attachGenAiAttributes, attachUsageAttributes, toTurnMetricUsage } from
 import { fireLlmUsageObserver } from './observers.js';
 import { hostPolicyToRouteParams, mergeRequiredCapabilities, } from './runtime/hostPolicy.js';
 import { adaptTools } from './runtime/toolAdapter.js';
-import { runEmulatedToolLoop } from './runtime/tool-emulation/index.js';
+import { runEmulatedToolLoop, toShimMessages } from './runtime/tool-emulation/index.js';
 import { resolveDynamicToolCalls } from './runtime/dynamicToolCalling.js';
 import { recordAgentOSTurnMetrics, withAgentOSSpan } from '../safety/evaluation/observability/otel.js';
 import { createLogger } from '../core/logging/loggerFactory.js';
@@ -66,6 +66,7 @@ class LLMProviderCircuitOpenError extends Error {
         this.name = 'LLMProviderCircuitOpenError';
     }
 }
+import { toProviderReplayMessage } from './sessionTranscript.js';
 async function recordAgentOSUsageLazy(input) {
     const { recordAgentOSUsage } = await import('./runtime/usageLedger.js');
     return recordAgentOSUsage(input);
@@ -168,6 +169,7 @@ export async function createPlan(provider, modelId, userMessages, toolNames, con
         // Inherited (or planning-specific) cache control: a cache:false root
         // call's planning sub-call must not auto-cache behind the caller's back.
         ...(config?.cache !== undefined ? { cache: config.cache } : {}),
+        ...(config?.thinking === false ? { thinking: false } : {}),
     });
     // Accumulate planning call usage
     if (response.usage) {
@@ -252,6 +254,124 @@ function formatPlanForPrompt(plan) {
  * @internal
  */
 const RETRYABLE_HTTP_STATUSES = new Set([401, 402, 403, 429, 500, 502, 503, 504]);
+/**
+ * Whether the tool round a continuation answers was requested without
+ * thinking blocks, as it is when another provider's model ran it.
+ */
+function toolTurnLacksThinking(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (message.role !== 'assistant' || !Array.isArray(message.tool_calls) || message.tool_calls.length === 0) {
+            continue;
+        }
+        return !Array.isArray(message.thinkingBlocks) || message.thinkingBlocks.length === 0;
+    }
+    return false;
+}
+/** Property key that marks an error thrown after the call's tools ran. */
+const TOOLS_RAN = Symbol.for('agentos.generateText.toolsRan');
+/**
+ * Marks `error` as thrown after the call's tools ran, so a fallback walker
+ * that called this call as a leg stops instead of restarting on another
+ * provider, which would run the tools again. A non-object is wrapped in an
+ * Error first.
+ *
+ * @returns The marked error.
+ */
+function markToolsRan(error) {
+    const target = error !== null && typeof error === 'object' ? error : new Error(String(error));
+    try {
+        Object.defineProperty(target, TOOLS_RAN, { value: true, configurable: true });
+    }
+    catch {
+        // A frozen error cannot carry the mark.
+    }
+    return target;
+}
+/**
+ * Adds a provider's usage report (`ModelUsage`) to a call's running
+ * {@link TokenUsage}, as each completed step is added.
+ *
+ * @internal Shared with streamText.
+ */
+export function addModelUsage(target, usage) {
+    if (!usage || typeof usage !== 'object')
+        return;
+    const u = usage;
+    const num = (value) => typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+    target.promptTokens += num(u.promptTokens) ?? 0;
+    target.completionTokens += num(u.completionTokens) ?? 0;
+    target.totalTokens += num(u.totalTokens) ?? 0;
+    const cost = num(u.costUSD);
+    if (cost !== undefined)
+        target.costUSD = (target.costUSD ?? 0) + cost;
+    const cacheRead = num(u.cacheReadInputTokens);
+    if (cacheRead !== undefined)
+        target.cacheReadTokens = (target.cacheReadTokens ?? 0) + cacheRead;
+    const cacheWrite = num(u.cacheCreationInputTokens);
+    if (cacheWrite !== undefined)
+        target.cacheCreationTokens = (target.cacheCreationTokens ?? 0) + cacheWrite;
+    const inclusive = num(u.inclusiveInputTokens);
+    if (inclusive !== undefined)
+        target.inclusiveInputTokens = (target.inclusiveInputTokens ?? 0) + inclusive;
+}
+/**
+ * The usage a provider error reports for the request it ended, such as the
+ * billed tokens of a refused turn (`details.usage`).
+ *
+ * @internal Shared with streamText.
+ */
+export function usageOfError(error) {
+    return error?.details?.usage;
+}
+/**
+ * Whether a usage report shows billable consumption.
+ *
+ * @internal Shared with streamText.
+ */
+export function hasBillableUsage(usage) {
+    return (usage.promptTokens > 0 ||
+        usage.completionTokens > 0 ||
+        (usage.cacheReadTokens ?? 0) > 0 ||
+        (usage.cacheCreationTokens ?? 0) > 0);
+}
+/** The sum of two usage reports; an optional counter stays absent when neither has it. */
+function sumTokenUsage(a, b) {
+    const optional = (x, y) => x === undefined && y === undefined ? undefined : (x ?? 0) + (y ?? 0);
+    const costUSD = optional(a.costUSD, b.costUSD);
+    const inclusiveInputTokens = optional(a.inclusiveInputTokens, b.inclusiveInputTokens);
+    const cacheReadTokens = optional(a.cacheReadTokens, b.cacheReadTokens);
+    const cacheCreationTokens = optional(a.cacheCreationTokens, b.cacheCreationTokens);
+    return {
+        promptTokens: a.promptTokens + b.promptTokens,
+        completionTokens: a.completionTokens + b.completionTokens,
+        totalTokens: a.totalTokens + b.totalTokens,
+        ...(costUSD !== undefined ? { costUSD } : {}),
+        ...(inclusiveInputTokens !== undefined ? { inclusiveInputTokens } : {}),
+        ...(cacheReadTokens !== undefined ? { cacheReadTokens } : {}),
+        ...(cacheCreationTokens !== undefined ? { cacheCreationTokens } : {}),
+    };
+}
+/** Whether `error` was marked by {@link markToolsRan}. */
+function toolsRanBefore(error) {
+    return (error !== null &&
+        typeof error === 'object' &&
+        error[TOOLS_RAN] === true);
+}
+/**
+ * Provider error codes for request-level failures that another provider may
+ * not share: unreachable endpoints, request timeouts, and retries exhausted
+ * inside the provider. Mid-stream codes (STREAM_IDLE_TIMEOUT,
+ * STREAM_INCOMPLETE) are left out, because a stream that already delivered
+ * text must not be restarted on another provider.
+ */
+const RETRYABLE_PROVIDER_ERROR_CODES = new Set([
+    'NETWORK_ERROR',
+    'REQUEST_TIMEOUT',
+    'REQUEST_HARD_TIMEOUT',
+    'TIMEOUT',
+    'MAX_RETRIES_REACHED',
+]);
 /**
  * Detect content-policy refusals across providers so the fallback chain
  * can route them to a more permissive model (typically uncensored
@@ -325,19 +445,29 @@ export function isContentPolicyRefusal(error) {
 export function isRetryableError(error) {
     if (!(error instanceof Error))
         return false;
+    // A primary that cannot initialize (rejected key, unreachable endpoint)
+    // is unusable for this call whatever the cause; the next provider may not be.
+    if (error.name === 'ProviderInitializationError')
+        return true;
     // Typed provider errors carry the HTTP status as a numeric field. Prefer that
     // over message-grepping, since providers often substitute the body description
     // (e.g. "This request requires more credits...") for the status code.
     const status = error.httpStatus;
     if (typeof status === 'number' && RETRYABLE_HTTP_STATUSES.has(status))
         return true;
+    // Typed provider errors name request-level network failures and timeouts
+    // by code; their messages vary by provider (OpenAIProvider rewrites an
+    // exhausted network failure as "Network error: unable to reach ...").
+    const code = error.code;
+    if (typeof code === 'string' && RETRYABLE_PROVIDER_ERROR_CODES.has(code))
+        return true;
     const msg = error.message;
     // HTTP status codes that warrant a provider switch (string-grepped fallback
     // when the error type is not a typed provider error).
     if (/\b(402|429|500|502|503|504|401|403)\b/.test(msg))
         return true;
     // Network-level failures
-    if (/fetch failed|ECONNREFUSED|ETIMEDOUT|ENOTFOUND/i.test(msg))
+    if (/fetch failed|ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|socket hang up|network error/i.test(msg))
         return true;
     // Provider-specific phrases that always imply a retryable condition.
     // `credit balance` covers Anthropic's billing message ("Your credit
@@ -597,6 +727,19 @@ export async function generateText(opts) {
     let metricUsage;
     let metricProviderId;
     let metricModelId;
+    // What this attempt did that a failover must not repeat. Written inside
+    // the span callback and read by the fallback walk below, so it lives on an
+    // object rather than in narrowed locals.
+    // What this attempt consumed, planning and completed steps included. It
+    // lives outside the span callback so a failed attempt still reports the
+    // tokens it was billed for.
+    const attemptUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+    const toolProgress = { shimRanTool: false };
+    // The tool run this call's tool execution contexts belong to, and the
+    // step it starts at. A fallback leg that continues the call keeps both,
+    // so tools see one session across providers and steps keep counting.
+    const helperToolRunId = opts._continuation?.helperToolRunId ?? randomUUID();
+    const stepOffset = opts._continuation?.stepOffset ?? 0;
     try {
         const successResult = await withAgentOSSpan('agentos.api.generate_text', async (span) => {
             let { providerId, modelId } = resolveModelOption(opts, 'text');
@@ -668,7 +811,6 @@ export async function generateText(opts) {
             const toolMap = new Map();
             for (const t of tools)
                 toolMap.set(t.name, t);
-            const helperToolRunId = randomUUID();
             // Build messages
             const messages = [];
             // --- Chain-of-thought injection ---
@@ -705,15 +847,27 @@ export async function generateText(opts) {
                 }
                 messages.push({ role: 'system', content: parts });
             }
+            // Everything above is built from opts (system prompt, chain-of-thought
+            // instruction); a failover continuation rebuilds it, so it is left out
+            // of the conversation a continuation carries.
+            const generatedSystemCount = messages.length;
             if (opts.messages) {
+                // Session history replays through here, so keep the tool pairing
+                // and thinking fields (see toProviderReplayMessage).
                 for (const m of opts.messages)
-                    messages.push({ role: m.role, content: m.content });
+                    messages.push(toProviderReplayMessage(m));
             }
             // Transcript delta capture (sessions, spec 2026-07-20 §1b): everything
             // from here on is THIS call's contribution. Callers that carry their
             // new user turn inside opts.messages mark how many trailing caller
             // messages belong to the delta.
-            const transcriptDeltaStart = messages.length - (opts._transcriptIncludeTrailingCallerMessages ?? 0);
+            let transcriptDeltaStart = messages.length - (opts._transcriptIncludeTrailingCallerMessages ?? 0);
+            // Caller history (its system messages included) that precedes this
+            // call's contribution.
+            const callerHistoryCount = Math.max(0, transcriptDeltaStart - generatedSystemCount);
+            // The plan's system message, when planning adds one; a continuation
+            // leaves it out (the fallback plans again if planning is on).
+            let planMessage;
             if (opts.prompt)
                 messages.push({ role: 'user', content: opts.prompt });
             span?.setAttribute('agentos.api.tool_count', tools.length);
@@ -724,7 +878,7 @@ export async function generateText(opts) {
                 }))
                 : undefined;
             const allToolCalls = [];
-            const totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+            const totalUsage = attemptUsage;
             // Provider-reported model id of the final step (spec batch-1 C1);
             // additive — the public `model` field keeps the resolved requested id.
             let lastResponseModelId;
@@ -755,6 +909,7 @@ export async function generateText(opts) {
                     ...(planConfig?.cache !== undefined || opts.cache !== undefined
                         ? { cache: planConfig?.cache ?? opts.cache }
                         : {}),
+                    ...(planConfig?.thinking === false || opts.thinking === false ? { thinking: false } : {}),
                 }, totalUsage);
                 if (resolvedPlan) {
                     // Inject the plan as a system message right after any existing
@@ -762,7 +917,12 @@ export async function generateText(opts) {
                     const planPrompt = formatPlanForPrompt(resolvedPlan);
                     const firstNonSystem = messages.findIndex((m) => m.role !== 'system');
                     const insertIdx = firstNonSystem === -1 ? messages.length : firstNonSystem;
-                    messages.splice(insertIdx, 0, { role: 'system', content: planPrompt });
+                    planMessage = { role: 'system', content: planPrompt };
+                    messages.splice(insertIdx, 0, planMessage);
+                    // The plan lands ahead of this call's transcript delta; keep the
+                    // delta starting at the same message.
+                    if (insertIdx <= transcriptDeltaStart)
+                        transcriptDeltaStart += 1;
                     span?.setAttribute('agentos.api.plan_steps', resolvedPlan.steps.length);
                 }
             }
@@ -776,10 +936,12 @@ export async function generateText(opts) {
             const runShim = async () => {
                 const loopResult = await runEmulatedToolLoop({
                     tools: Array.from(toolMap.values()),
-                    messages: messages.map((m) => ({
-                        role: String(m.role),
-                        content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content ?? ''),
-                    })),
+                    onToolExecute: () => {
+                        toolProgress.shimRanTool = true;
+                    },
+                    // Native tool turns (session history, a failover continuation)
+                    // become the shim's own <tool_call> / <tool_response> text.
+                    messages: toShimMessages(messages),
                     maxRoundtrips: shimMaxRoundtrips,
                     callModel: async (msgs) => {
                         const r = await provider.generateCompletion(resolved.modelId, msgs, {
@@ -820,12 +982,13 @@ export async function generateText(opts) {
                             ...(opts.requestTimeout !== undefined ? { requestTimeout: opts.requestTimeout } : {}),
                         });
                         // Aggregate the COMPLETE normalized usage from every shim
-                        // roundtrip (spec batch-1 review fold): the thin {totalTokens}
-                        // loop contract stays for the GMI helper (totalTokens flows via
-                        // loopResult below — NOT accumulated here, or it would double
-                        // count), while all richer counters land on totalUsage and the
-                        // final response identity is captured for telemetry.
+                        // roundtrip (spec batch-1 review fold) as each call returns, so
+                        // an attempt that fails on a later round still reports what its
+                        // earlier rounds consumed. The loop's own {totalTokens} sum is
+                        // left unused, or it would count twice.
                         if (r.usage) {
+                            if (typeof r.usage.totalTokens === 'number')
+                                totalUsage.totalTokens += r.usage.totalTokens;
                             if (typeof r.usage.promptTokens === 'number')
                                 totalUsage.promptTokens += r.usage.promptTokens;
                             if (typeof r.usage.completionTokens === 'number')
@@ -853,10 +1016,7 @@ export async function generateText(opts) {
                         };
                     },
                 });
-                const shimUsage = {
-                    ...totalUsage,
-                    totalTokens: (totalUsage.totalTokens ?? 0) + loopResult.totalTokens,
-                };
+                const shimUsage = { ...totalUsage };
                 metricUsage = shimUsage;
                 // Dual-emit the same root-span attribute pairs as the native
                 // terminals below — the shim early-return is a first-class chat
@@ -917,6 +1077,9 @@ export async function generateText(opts) {
             let lastCacheDiagnostics;
             try {
                 for (let step = 0; step < maxSteps; step++) {
+                    // The step's index in the whole call: a fallback leg that continues
+                    // after completed tool rounds numbers on from them.
+                    const runStep = stepOffset + step;
                     // --- onBeforeGeneration hook ---
                     let effectiveMessages = messages;
                     if (opts.onBeforeGeneration) {
@@ -927,8 +1090,8 @@ export async function generateText(opts) {
                                 tools: Array.from(toolMap.values()),
                                 model: resolved.modelId,
                                 provider: resolved.providerId,
-                                step,
-                                prompt: opts.prompt,
+                                step: runStep,
+                                prompt: opts.prompt ?? opts._continuation?.prompt,
                             };
                             const modified = await opts.onBeforeGeneration(hookCtx);
                             if (modified) {
@@ -942,7 +1105,7 @@ export async function generateText(opts) {
                     const response = await withAgentOSSpan('agentos.api.generate_text.step', async (stepSpan) => {
                         stepSpan?.setAttribute('llm.provider', resolved.providerId);
                         stepSpan?.setAttribute('llm.model', resolved.modelId);
-                        stepSpan?.setAttribute('agentos.api.step', step + 1);
+                        stepSpan?.setAttribute('agentos.api.step', runStep + 1);
                         stepSpan?.setAttribute('agentos.api.tool_count', tools.length);
                         const stepResponse = await provider.generateCompletion(resolved.modelId, effectiveMessages, {
                             tools: toolSchemas,
@@ -1069,7 +1232,7 @@ export async function generateText(opts) {
                     let textContent = typeof content === 'string' ? content : (content?.text ?? '');
                     let toolCallsInChoice = resolveDynamicToolCalls(choice.message?.tool_calls, {
                         text: textContent,
-                        step,
+                        step: runStep,
                         toolsAvailable: tools.length > 0,
                     });
                     // --- onAfterGeneration hook ---
@@ -1091,7 +1254,7 @@ export async function generateText(opts) {
                                 text: textContent,
                                 toolCalls: toolCallRecords,
                                 usage: stepUsage,
-                                step,
+                                step: runStep,
                                 ...(response.cacheDiagnostics !== undefined
                                     ? { cacheDiagnostics: response.cacheDiagnostics }
                                     : {}),
@@ -1139,6 +1302,9 @@ export async function generateText(opts) {
                             ...((choice.message?.thinking) !== undefined
                                 ? { thinking: choice.message.thinking }
                                 : {}),
+                            ...(choice.message?.thinkingBlocks?.length
+                                ? { thinkingBlocks: choice.message.thinkingBlocks }
+                                : {}),
                         });
                         return {
                             transcriptDelta: messages.slice(transcriptDeltaStart),
@@ -1208,7 +1374,7 @@ export async function generateText(opts) {
                                         name: fnName,
                                         args: parsedArgs,
                                         id: tcId || '',
-                                        step,
+                                        step: runStep,
                                     };
                                     const hookResult = await opts.onBeforeToolExecution(hookInfo);
                                     if (hookResult === null) {
@@ -1229,7 +1395,7 @@ export async function generateText(opts) {
                             }
                             if (tool) {
                                 try {
-                                    const result = await tool.execute(parsedArgs, buildHelperToolExecutionContext('generateText', helperToolRunId, step, tcId || undefined));
+                                    const result = await tool.execute(parsedArgs, buildHelperToolExecutionContext('generateText', helperToolRunId, runStep, tcId || undefined));
                                     record.result = result.output;
                                     record.error = result.success ? undefined : result.error;
                                     messages.push({
@@ -1257,6 +1423,12 @@ export async function generateText(opts) {
                             }
                             allToolCalls.push(record);
                         }
+                        toolProgress.completedToolRounds = {
+                            messages: messages.slice(generatedSystemCount).filter((m) => m !== planMessage),
+                            callerHistoryCount,
+                            toolCalls: [...allToolCalls],
+                            steps: step + 1,
+                        };
                         continue;
                     }
                     metricUsage = totalUsage;
@@ -1285,6 +1457,9 @@ export async function generateText(opts) {
                         ...((choice.message?.thinking) !== undefined
                             ? { thinking: choice.message.thinking }
                             : {}),
+                        ...(choice.message?.thinkingBlocks?.length
+                            ? { thinkingBlocks: choice.message.thinkingBlocks }
+                            : {}),
                     });
                     return {
                         transcriptDelta: messages.slice(transcriptDeltaStart),
@@ -1372,8 +1547,25 @@ export async function generateText(opts) {
         if (metricProviderId && !(error instanceof LLMProviderCircuitOpenError)) {
             globalLLMProviderHealth.recordFailure(metricProviderId, error);
         }
-        // Capture the failed primary for the fallback trail before the loop below
-        // reassigns metricProviderId / metricModelId to the winning fallback.
+        // The failed attempt is billed for its completed steps and for a step
+        // the provider ended with usage attached (a refused turn). It is metered
+        // here, once: this call's ledger row and a usage event of its own; a
+        // fallback leg meters itself.
+        addModelUsage(attemptUsage, usageOfError(error));
+        metricUsage = attemptUsage;
+        if (hasBillableUsage(attemptUsage)) {
+            fireLlmUsageObserver({
+                provider: metricProviderId ?? 'unknown',
+                model: metricModelId ?? 'unknown',
+                usage: { ...attemptUsage },
+                source: opts.source,
+                ...(opts.__fallbackDepth ? { fallbackDepth: opts.__fallbackDepth } : {}),
+                finishReason: 'error',
+                surface: 'generateText',
+                durationMs: Date.now() - rootStartedAt,
+            });
+        }
+        // The failed primary heads the fallback trail.
         const primaryProviderId = metricProviderId;
         const primaryModelId = metricModelId;
         const fallbackHops = [
@@ -1390,8 +1582,11 @@ export async function generateText(opts) {
         const effectiveFallbacks = opts.fallbackProviders === undefined
             ? buildPolicyAwareFallbackChain(opts.policyTier, metricProviderId)
             : opts.fallbackProviders;
+        // A call whose prompt-shim tools already ran cannot be continued, and a
+        // restart would run them again; it surfaces the error instead.
         if (effectiveFallbacks.length &&
-            isRetryableError(error)) {
+            isRetryableError(error) &&
+            !toolProgress.shimRanTool) {
             let lastError = error;
             let attempt = 0;
             for (const fb of effectiveFallbacks) {
@@ -1482,6 +1677,34 @@ export async function generateText(opts) {
                         // end-to-end. The final entry passes [] -> explicit opt-out -> throw.
                         fallbackProviders: effectiveFallbacks.slice(attempt),
                         onFallback: undefined,
+                        // Continue after the tool rounds this attempt completed: the leg
+                        // receives the conversation so far (prompt included, so no new
+                        // prompt), counts all of it as this call's transcript delta, and
+                        // keeps the steps that remain.
+                        _continuation: {
+                            helperToolRunId,
+                            stepOffset: stepOffset + (toolProgress.completedToolRounds?.steps ?? 0),
+                            prompt: opts.prompt ?? opts._continuation?.prompt,
+                        },
+                        ...(toolProgress.completedToolRounds
+                            ? {
+                                messages: toolProgress.completedToolRounds.messages,
+                                prompt: undefined,
+                                _transcriptIncludeTrailingCallerMessages: toolProgress.completedToolRounds.messages.length - toolProgress.completedToolRounds.callerHistoryCount,
+                                maxSteps: Math.max(1, (opts.maxSteps ?? 1) - toolProgress.completedToolRounds.steps),
+                                // Claude's budgeted thinking requires the tool turn being
+                                // answered to open with its signed thinking, and a turn
+                                // another model ran has none, so the continuation runs
+                                // without a thinking budget. Adaptive thinking turns itself
+                                // off for such a turn. `thinking: false` stays as asked.
+                                ...(typeof opts.thinking === 'object' &&
+                                    opts.thinking !== null &&
+                                    (fb.provider === 'anthropic' || /claude/i.test(fb.model ?? '')) &&
+                                    toolTurnLacksThinking(toolProgress.completedToolRounds.messages)
+                                    ? { thinking: undefined }
+                                    : {}),
+                            }
+                            : {}),
                     });
                     fallbackLogger.info('provider fallback succeeded', {
                         event: 'fallback_succeeded',
@@ -1492,14 +1715,16 @@ export async function generateText(opts) {
                         attempt,
                     });
                     metricStatus = 'ok';
-                    metricUsage = fallbackResult.usage;
-                    metricProviderId = fallbackResult.provider;
-                    metricModelId = fallbackResult.model;
                     fallbackHops.push(...(fallbackResult.fallback?.hops ?? [
                         { provider: fallbackResult.provider, model: fallbackResult.model, ok: true },
                     ]));
                     return {
                         ...fallbackResult,
+                        // The call's usage covers the failed attempt and the leg.
+                        usage: sumTokenUsage(attemptUsage, fallbackResult.usage),
+                        ...(toolProgress.completedToolRounds
+                            ? { toolCalls: [...toolProgress.completedToolRounds.toolCalls, ...fallbackResult.toolCalls] }
+                            : {}),
                         fallback: {
                             fired: true,
                             finalProvider: fallbackResult.provider,
@@ -1511,6 +1736,10 @@ export async function generateText(opts) {
                 catch (fbError) {
                     lastError = fbError;
                     fallbackHops.push({ provider: fb.provider, model: fb.model, ok: false });
+                    // The leg ran tools before it failed. A later leg would start
+                    // from a conversation that does not show them and run them again.
+                    if (toolsRanBefore(fbError))
+                        break;
                 }
             }
             // All fallbacks exhausted: fall through to throw
@@ -1524,10 +1753,11 @@ export async function generateText(opts) {
                 errorMessage: lastErr.message.slice(0, 200),
             });
             metricStatus = 'error';
-            throw lastError;
+            throw toolProgress.shimRanTool || toolProgress.completedToolRounds ? markToolsRan(lastError) : lastError;
         }
         metricStatus = 'error';
-        throw error;
+        // Marked so a walker that called this one as a fallback leg stops too.
+        throw toolProgress.shimRanTool || toolProgress.completedToolRounds ? markToolsRan(error) : error;
     }
     finally {
         try {