@pentoshi/clai 4.1.0 → 4.2.0

package/dist/llm/router.js

@@ -3,10 +3,12 @@ import { getProviderKeys, getProviderSecret, markProviderKeySuccess, } from "../
 import { anthropicProvider } from "./anthropic.js";
 import { geminiProvider } from "./gemini.js";
 import { groqProvider } from "./groq.js";
-import { ProviderError, bodyAddsInformation, collapseWhitespace, isImageInputUnsupportedError, isReasoningUnsupportedError, stripImagesFromMessages, MAX_ERROR_BODY_IN_MESSAGE_CHARS, STREAM_STALL_MARKER, } from "./http.js";
-import { learnModelVisionCapability, markModelUnavailable, markReasoningUnsupported, modelAcceptsImages, modelSupportsVision, visionSubstitutionOrigin, } from "./capabilities.js";
+import { ProviderError, bodyAddsInformation, buildReasoningPayload, collapseWhitespace, isImageInputUnsupportedError, isReasoningUnsupportedError, stripImagesFromMessages, MAX_ERROR_BODY_IN_MESSAGE_CHARS, STREAM_STALL_MARKER, } from "./http.js";
+import { isReasoningUnsupported, learnModelVisionCapability, markModelUnavailable, markReasoningUnsupported, modelAcceptsImages, modelSupportsVision, visionSubstitutionOrigin, } from "./capabilities.js";
 import { applyImageViewAvailability } from "../prompts/index.js";
+import { fallbackEffortsFor } from "./effort-fallback.js";
 import { markStreamEmittedBytes, streamAlreadyEmitted, streamEmittedBytes, } from "./stream-progress.js";
+import { createStreamEventGuard, isSemanticStreamOutputEvent, } from "./stream-events.js";
 import { attemptsPerKey, buildKeyAttemptPlan, formatKeyEventStatus, isImmediateKeySwitchError, isKeyCircleStopError, isKeyRotatableError, isQuotaKeyError, } from "./key-rotation.js";
 import { freeProvider } from "./free.js";
 import { nvidiaProvider } from "./nvidia.js";
@@ -24,6 +26,9 @@ import { tokenrouterProvider } from "./tokenrouter.js";
 import { metaProvider } from "./meta.js";
 import { fireworksProvider } from "./fireworks.js";
 import { hetznerProvider } from "./hetzner.js";
+import { orcarouterProvider } from "./orcarouter.js";
+import { OperationUsageRecorder, runGenerationAttempt, } from "./operation-usage.js";
+import { isOperationPolicyError, OperationLedger, operationTerminalOutcome, turnOperationPolicy, } from "./operation-ledger.js";
 import { maskSecretTail } from "./provider.js";
 import { getCustomProviderSync } from "./custom-providers.js";
 import { isToolsUnsupportedError, markTextOnlyModel, } from "./tool-protocol.js";
@@ -32,6 +37,36 @@ const MAX_RETRIES = 6;
 const MAX_RETRY_WAIT_MS = 120_000;
 /** Toast replace-key so key rotation never stacks notifications. */
 export const API_KEY_TOAST_KEY = "api-key-rotation";
+/**
+ * A budget/policy error raised while recovering from a real failure describes
+ * the guard, not the cause. Surface the failure the caller actually needs.
+ */
+function successfulRequestSnapshot(provider, model, request) {
+    return structuredClone({
+        provider,
+        model,
+        messages: request.messages,
+        ...(request.temperature !== undefined
+            ? { temperature: request.temperature }
+            : {}),
+        ...(request.thinking ? { thinking: request.thinking } : {}),
+        ...(request.tools ? { tools: request.tools } : {}),
+        ...(request.toolChoice !== undefined
+            ? { toolChoice: request.toolChoice }
+            : {}),
+        ...(request.parallelToolCalls !== undefined
+            ? { parallelToolCalls: request.parallelToolCalls }
+            : {}),
+    });
+}
+function preservedFailure(recoveryError, originalError) {
+    return isOperationPolicyError(recoveryError) ? originalError : recoveryError;
+}
+function resolveOperationLedger(options) {
+    if (options.operation)
+        return options.operation;
+    return new OperationLedger(turnOperationPolicy(), options.attemptUsage ?? new OperationUsageRecorder());
+}
 async function sleep(ms, signal) {
     if (signal?.aborted)
         throw signal.reason ?? new Error("Aborted");
@@ -56,6 +91,47 @@ async function sleep(ms, signal) {
 function isRateLimited(error) {
     return error instanceof ProviderError && error.status === 429;
 }
+function isServerUnavailable(error) {
+    if (!(error instanceof ProviderError))
+        return false;
+    const status = error.status ?? 0;
+    return status === 502 || status === 503 || status === 504;
+}
+function isServerError(error) {
+    if (!(error instanceof ProviderError))
+        return false;
+    const status = error.status ?? 0;
+    return status >= 500 && status <= 504;
+}
+function isReasoningRelatedServerError(error, providerId) {
+    if (!isServerError(error))
+        return false;
+    if (providerId === "tokenrouter")
+        return true;
+    const message = error instanceof Error ? error.message : String(error);
+    const body = error instanceof ProviderError ? (error.body ?? "") : "";
+    return /reasoning|effort|thinking/i.test(`${message} ${body}`);
+}
+function shouldContinueEffortLadder(error, providerId) {
+    return (isReasoningUnsupportedError(error) ||
+        isReasoningRelatedServerError(error, providerId));
+}
+function shouldEnterEffortLadder(error, thinking, providerId, model, singleDispatch) {
+    if (isReasoningUnsupportedError(error))
+        return true;
+    if (singleDispatch)
+        return false;
+    if (!thinking?.enabled)
+        return false;
+    if (isReasoningUnsupported(providerId, model))
+        return false;
+    return isReasoningRelatedServerError(error, providerId);
+}
+function isCacheOnlyColdError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const body = error instanceof ProviderError ? (error.body ?? "") : "";
+    return /cache_only_cold|cache-only admission/i.test(`${message} ${body}`);
+}
 function isTransientNetworkError(error) {
     const message = error instanceof Error ? error.message : String(error);
     const msg = message.toLowerCase();
@@ -166,6 +242,9 @@ export function formatProviderFailureForUser(error) {
             return withFullBody(withExactError("Provider rejected the request body (422). Model name or parameters may be incompatible — try another model."));
         }
         if (status === 503 || status === 502 || status === 504) {
+            if (isCacheOnlyColdError(error)) {
+                return withFullBody(withExactError(`Gateway cache admission rejected (${status}; cache_only_cold): the route is cold or overloaded and retried automatically with backoff. If it persists, retry shortly or switch provider/model.`));
+            }
             return withFullBody(withExactError(`Upstream provider unavailable (${status}). Retry shortly or switch provider/model; free-tier models are often capacity-constrained.`));
         }
         if (status >= 500 && status < 600) {
@@ -290,6 +369,7 @@ export const providers = {
     meta: metaProvider,
     fireworks: fireworksProvider,
     hetzner: hetznerProvider,
+    orcarouter: orcarouterProvider,
 };
 const fallbackOrder = [
     "free",
@@ -311,6 +391,7 @@ const fallbackOrder = [
     "meta",
     "fireworks",
     "hetzner",
+    "orcarouter",
 ];
 /**
  * Built-in provider ids in fallback preference order. Custom (user-defined)
@@ -387,6 +468,9 @@ function authForSlot(providerId, value) {
 function withoutReasoning(request) {
     return { ...request, thinking: undefined };
 }
+function reasoningWireKey(thinking, style, model, providerId) {
+    return JSON.stringify(buildReasoningPayload(thinking, style, model, providerId));
+}
 function makeKeyEmitter(onStatus, onKeyEvent) {
     return (event) => {
         onKeyEvent?.(event);
@@ -400,39 +484,102 @@ function makeKeyEmitter(onStatus, onKeyEvent) {
         }
     };
 }
-async function tryCompleteOnce(provider, providerId, request, model, auth) {
+const SELF_RECORDED_PROVIDERS = new Set([
+    "agentrouter",
+    "bynara",
+    "meta",
+]);
+async function runRecordedProviderAttempt(input) {
+    if (SELF_RECORDED_PROVIDERS.has(input.providerId))
+        return input.run();
+    return runGenerationAttempt(input.request, {
+        provider: input.providerId,
+        model: input.model,
+        mode: input.mode,
+        reason: input.reason,
+    }, input.run);
+}
+async function tryCompleteOnce(provider, providerId, request, model, auth, reason, onStatus, singleDispatch = false) {
     const activeRequest = { ...request, provider: providerId, model };
+    const runAttempt = (candidate, attemptReason) => {
+        const attemptRequest = { ...candidate, attemptReason };
+        return runRecordedProviderAttempt({
+            providerId,
+            model: attemptRequest.model ?? model,
+            mode: "complete",
+            reason: attemptReason,
+            request: attemptRequest,
+            run: () => provider.complete(attemptRequest, auth),
+        });
+    };
     try {
-        const result = await provider.complete(activeRequest, auth);
+        const result = await runAttempt(activeRequest, reason);
         if (hasImageInput(activeRequest)) {
             learnModelVisionCapability(providerId, model, true);
         }
         return result;
     }
     catch (error) {
+        // A pinned single-dispatch operation records the capability verdict for the
+        // next operation but never spends a second physical request on it.
         if (activeRequest.tools?.length && isToolsUnsupportedError(error)) {
             markTextOnlyModel(providerId, model);
+            if (singleDispatch)
+                throw error;
             const textRequest = {
                 ...activeRequest,
                 tools: undefined,
                 toolChoice: undefined,
                 parallelToolCalls: undefined,
             };
-            return await provider.complete(textRequest, auth);
+            return await runAttempt(textRequest, "adaptation");
         }
-        // Model rejected a reasoning/thinking knob — mark it and retry once
-        // without reasoning so an unsupported option never fails the request.
-        if (isReasoningUnsupportedError(error)) {
+        if (shouldEnterEffortLadder(error, activeRequest.thinking, providerId, model, singleDispatch)) {
+            if (singleDispatch) {
+                markReasoningUnsupported(providerId, model);
+                throw error;
+            }
+            const thinking = activeRequest.thinking;
+            if (thinking?.enabled) {
+                const style = provider.reasoningStyle ?? "none";
+                const seen = new Set([
+                    reasoningWireKey(thinking, style, model, providerId),
+                ]);
+                for (const effort of fallbackEffortsFor(thinking.effort)) {
+                    const candidate = { ...thinking, effort };
+                    const key = reasoningWireKey(candidate, style, model, providerId);
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    onStatus?.(`ℹ ${providerId}/${model} rejected reasoning effort — retrying with ${effort}`);
+                    const retryRequest = {
+                        ...activeRequest,
+                        thinking: candidate,
+                    };
+                    try {
+                        return await runAttempt(retryRequest, "adaptation");
+                    }
+                    catch (retryError) {
+                        if (!shouldContinueEffortLadder(retryError, providerId))
+                            throw retryError;
+                    }
+                }
+            }
             markReasoningUnsupported(providerId, model);
-            return await provider.complete(withoutReasoning(activeRequest), auth);
+            onStatus?.(`ℹ ${providerId}/${model} rejected reasoning options — retrying without them`);
+            return await runAttempt(withoutReasoning(activeRequest), "adaptation");
         }
         if (hasImageInput(activeRequest) && isImageInputUnsupportedError(error)) {
             learnModelVisionCapability(providerId, model, false);
-            return await provider.complete(withoutImages(activeRequest), auth);
+            if (singleDispatch)
+                throw error;
+            return await runAttempt(withoutImages(activeRequest), "adaptation");
         }
-        const restored = revertVisionSubstitution(providerId, model, activeRequest, error);
-        if (restored) {
-            return await provider.complete(restored.request, auth);
+        if (!singleDispatch) {
+            const restored = revertVisionSubstitution(providerId, model, activeRequest, error);
+            if (restored) {
+                return await runAttempt(restored.request, "adaptation");
+            }
         }
         throw error;
     }
@@ -502,27 +649,57 @@ function revertVisionSubstitution(providerId, model, request, error) {
         request: requestForRoute(restoredRequest, providerId, original),
     };
 }
-async function tryStreamOnce(provider, providerId, request, model, auth, onToken, onStatus) {
+async function tryStreamOnce(provider, providerId, request, model, auth, onToken, onStatus, reason, singleDispatch = false, onSuccessfulRequest) {
     let emittedBytes = 0;
     let emittedToolArgumentBytes = 0;
     const onToolCallDelta = request.onToolCallDelta;
+    const downstreamEvents = request.onStreamEvent;
+    let guard = createStreamEventGuard();
+    const startedToolCallIndexes = new Set();
+    const emitEvent = (event) => {
+        guard.accept(event);
+        if (event.type === "reasoning_delta" || event.type === "commentary_delta") {
+            emittedBytes += event.text.length;
+        }
+        downstreamEvents?.(event);
+    };
     const activeRequest = {
         ...request,
         provider: providerId,
         model,
-        ...(onToolCallDelta
+        ...(onToolCallDelta || downstreamEvents
             ? {
                 onToolCallDelta: (delta) => {
                     const argumentBytes = delta.argumentsBytes ?? 0;
                     emittedBytes += Math.max(delta.name?.length ?? 0, argumentBytes - emittedToolArgumentBytes, 1);
                     emittedToolArgumentBytes = Math.max(emittedToolArgumentBytes, argumentBytes);
-                    onToolCallDelta(delta);
+                    if (delta.name !== undefined &&
+                        !startedToolCallIndexes.has(delta.index)) {
+                        startedToolCallIndexes.add(delta.index);
+                        emitEvent({
+                            type: "tool_call_started",
+                            index: delta.index,
+                            ...(delta.id ? { id: delta.id } : {}),
+                            name: delta.name,
+                        });
+                    }
+                    emitEvent({
+                        type: "tool_arguments_delta",
+                        index: delta.index,
+                        ...(delta.id ? { id: delta.id } : {}),
+                        argumentsBytes: argumentBytes,
+                    });
+                    onToolCallDelta?.(delta);
                 },
             }
             : {}),
+        ...(downstreamEvents ? { onStreamEvent: emitEvent } : {}),
     };
     const emit = (token) => {
+        if (!token)
+            return;
         emittedBytes += token.length;
+        emitEvent({ type: "answer_delta", text: token });
         onToken(token);
     };
     const learnVisionOnSuccess = () => {
@@ -530,14 +707,62 @@ async function tryStreamOnce(provider, providerId, request, model, auth, onToken
             learnModelVisionCapability(providerId, model, true);
         }
     };
-    try {
-        if (provider.stream) {
-            const streamed = await provider.stream(activeRequest, auth, emit);
-            learnVisionOnSuccess();
-            return streamed;
+    const runAttempt = async (candidate, attemptReason) => {
+        guard = createStreamEventGuard();
+        startedToolCallIndexes.clear();
+        const attemptRequest = { ...candidate, attemptReason };
+        const result = await runRecordedProviderAttempt({
+            providerId,
+            model: attemptRequest.model ?? model,
+            mode: "stream",
+            reason: attemptReason,
+            request: attemptRequest,
+            run: async () => {
+                let result;
+                if (provider.stream) {
+                    result = await provider.stream(attemptRequest, auth, emit);
+                }
+                else {
+                    result = await provider.complete(attemptRequest, auth);
+                    emit(result.text);
+                }
+                for (const [index, call] of (result.toolCalls ?? []).entries()) {
+                    if (!startedToolCallIndexes.has(index)) {
+                        startedToolCallIndexes.add(index);
+                        emitEvent({
+                            type: "tool_call_started",
+                            index,
+                            ...(call.id ? { id: call.id } : {}),
+                            name: call.name,
+                        });
+                    }
+                    emitEvent({
+                        type: "tool_call_completed",
+                        index,
+                        ...(call.id ? { id: call.id } : {}),
+                        name: call.name,
+                    });
+                }
+                if (result.usage) {
+                    emitEvent({ type: "usage_observed", usage: result.usage });
+                }
+                emitEvent({
+                    type: "provider_terminal",
+                    ...(result.finishReason
+                        ? { finishReason: result.finishReason }
+                        : {}),
+                });
+                return result;
+            },
+        });
+        try {
+            onSuccessfulRequest?.(successfulRequestSnapshot(result.provider || providerId, result.model || attemptRequest.model || model, attemptRequest));
         }
-        const result = await provider.complete(activeRequest, auth);
-        emit(result.text);
+        catch { }
+        return result;
+    };
+    try {
+        const result = await runAttempt(activeRequest, reason);
         learnVisionOnSuccess();
         return result;
     }
@@ -546,6 +771,8 @@ async function tryStreamOnce(provider, providerId, request, model, auth, onToken
             activeRequest.tools?.length &&
             isToolsUnsupportedError(error)) {
             markTextOnlyModel(providerId, model);
+            if (singleDispatch)
+                throw markStreamEmittedBytes(error, emittedBytes);
             onStatus?.(`ℹ ${providerId}/${model} does not support native tools — falling back to text protocol`);
             const textRequest = {
                 ...activeRequest,
@@ -554,69 +781,84 @@ async function tryStreamOnce(provider, providerId, request, model, auth, onToken
                 parallelToolCalls: undefined,
             };
             try {
-                if (provider.stream) {
-                    return await provider.stream(textRequest, auth, emit);
-                }
-                const result = await provider.complete(textRequest, auth);
-                emit(result.text);
-                return result;
+                return await runAttempt(textRequest, "adaptation");
             }
             catch (retryError) {
-                throw markStreamEmittedBytes(retryError, emittedBytes);
+                throw markStreamEmittedBytes(preservedFailure(retryError, error), emittedBytes);
             }
         }
         // Model rejected a reasoning/thinking knob (e.g. chat_template_kwargs on a
-        // NIM chat template that does not accept it). Mark it so buildChatBody stops
-        // sending reasoning, then retry once without it. A parameter rejection is a
-        // request-time 4xx, so no tokens have streamed yet — the retry is clean.
-        if (emittedBytes === 0 && isReasoningUnsupportedError(error)) {
+        // NIM chat template that does not accept it). A parameter rejection is a
+        // request-time 4xx, so no tokens have streamed yet — retries are clean.
+        // Walk down the effort ladder first (max → xhigh → high → medium → low) so
+        // a model that merely rejects the highest requested depth keeps reasoning;
+        // only strip reasoning entirely once every candidate has been rejected.
+        if (emittedBytes === 0 && shouldEnterEffortLadder(error, activeRequest.thinking, providerId, model, singleDispatch)) {
+            if (singleDispatch) {
+                markReasoningUnsupported(providerId, model);
+                throw markStreamEmittedBytes(error, emittedBytes);
+            }
+            const thinking = activeRequest.thinking;
+            if (thinking?.enabled) {
+                const style = provider.reasoningStyle ?? "none";
+                const seen = new Set([
+                    reasoningWireKey(thinking, style, model, providerId),
+                ]);
+                for (const effort of fallbackEffortsFor(thinking.effort)) {
+                    const candidate = { ...thinking, effort };
+                    const key = reasoningWireKey(candidate, style, model, providerId);
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    onStatus?.(`ℹ ${providerId}/${model} rejected reasoning effort — retrying with ${effort}`);
+                    const retryRequest = {
+                        ...activeRequest,
+                        thinking: candidate,
+                    };
+                    try {
+                        return await runAttempt(retryRequest, "adaptation");
+                    }
+                    catch (retryError) {
+                        if (!shouldContinueEffortLadder(retryError, providerId)) {
+                            throw markStreamEmittedBytes(preservedFailure(retryError, error), emittedBytes);
+                        }
+                    }
+                }
+            }
             markReasoningUnsupported(providerId, model);
             onStatus?.(`ℹ ${providerId}/${model} rejected reasoning options — retrying without them`);
             const retryRequest = withoutReasoning(activeRequest);
             try {
-                if (provider.stream) {
-                    return await provider.stream(retryRequest, auth, emit);
-                }
-                const result = await provider.complete(retryRequest, auth);
-                emit(result.text);
-                return result;
+                return await runAttempt(retryRequest, "adaptation");
             }
             catch (retryError) {
-                throw markStreamEmittedBytes(retryError, emittedBytes);
+                throw markStreamEmittedBytes(preservedFailure(retryError, error), emittedBytes);
             }
         }
         if (emittedBytes === 0 &&
             hasImageInput(activeRequest) &&
             isImageInputUnsupportedError(error)) {
             learnModelVisionCapability(providerId, model, false);
+            if (singleDispatch)
+                throw markStreamEmittedBytes(error, emittedBytes);
             onStatus?.(`ℹ ${providerId}/${model} rejected image input — retrying without the attached image(s)`);
             const textOnlyRequest = withoutImages(activeRequest);
             try {
-                if (provider.stream) {
-                    return await provider.stream(textOnlyRequest, auth, emit);
-                }
-                const result = await provider.complete(textOnlyRequest, auth);
-                emit(result.text);
-                return result;
+                return await runAttempt(textOnlyRequest, "adaptation");
             }
             catch (retryError) {
-                throw markStreamEmittedBytes(retryError, emittedBytes);
+                throw markStreamEmittedBytes(preservedFailure(retryError, error), emittedBytes);
             }
         }
-        if (emittedBytes === 0) {
+        if (emittedBytes === 0 && !singleDispatch) {
             const restored = revertVisionSubstitution(providerId, model, activeRequest, error);
             if (restored) {
                 onStatus?.(`ℹ ${providerId}/${model} is not available on this account — falling back to ${restored.original}`);
                 try {
-                    if (provider.stream) {
-                        return await provider.stream(restored.request, auth, emit);
-                    }
-                    const result = await provider.complete(restored.request, auth);
-                    emit(result.text);
-                    return result;
+                    return await runAttempt(restored.request, "adaptation");
                 }
                 catch (retryError) {
-                    throw markStreamEmittedBytes(retryError, emittedBytes);
+                    throw markStreamEmittedBytes(preservedFailure(retryError, error), emittedBytes);
                 }
             }
         }
@@ -630,12 +872,16 @@ async function tryStreamOnce(provider, providerId, request, model, auth, onToken
  */
 async function runWithKeyRotation(opts) {
     const { providerId, provider, request, model, emitKey } = opts;
+    const singleDispatch = opts.singleDispatch === true;
     const multi = await getProviderKeys(providerId);
     const slots = multi.keys;
     if (slots.length === 0) {
         throw new Error("no API key configured");
     }
-    const plan = buildKeyAttemptPlan(slots.length, multi.activeIndex).filter((index) => !slots[index].disabled);
+    const fullPlan = buildKeyAttemptPlan(slots.length, multi.activeIndex).filter((index) => !slots[index].disabled);
+    // A pinned operation uses the sticky key only: rotating would send the same
+    // large prompt again under a different credential.
+    const plan = singleDispatch ? fullPlan.slice(0, 1) : fullPlan;
     if (plan.length === 0) {
         throw new Error(`all ${slots.length} API key${slots.length === 1 ? "" : "s"} for ${providerId} are disabled — re-enable one to use this provider`);
     }
@@ -643,12 +889,14 @@ async function runWithKeyRotation(opts) {
     const multiKey = enabledCount > 1;
     // Single key: time-increasing retries (MAX_RETRIES+1 attempts).
     // Multi key: 2 attempts per key (initial + one retry), then next key.
-    const maxPerKey = attemptsPerKey(enabledCount, (opts.maxRetries ?? MAX_RETRIES) + 1);
+    const maxPerKey = singleDispatch
+        ? 1
+        : attemptsPerKey(enabledCount, (opts.maxRetries ?? MAX_RETRIES) + 1);
     let lastError;
     // Endpoint failover: a provider can carry several base URLs (e.g. Modal
     // workspaces). On an auth/quota error the active endpoint may simply be the
     // wrong workspace for the key, so rotate the endpoint too before giving up.
-    const storedEndpoints = providerUsesEndpoints(providerId)
+    const storedEndpoints = providerUsesEndpoints(providerId) && !singleDispatch
         ? getProviderEndpoints(providerId)
         : undefined;
     const endpointUrls = (storedEndpoints?.urls ?? []).filter((url) => !(storedEndpoints?.disabledUrls ?? []).includes(url));
@@ -684,13 +932,14 @@ async function runWithKeyRotation(opts) {
         }
         for (let attempt = 0; attempt < maxPerKey; attempt++) {
             request.signal?.throwIfAborted();
+            const attemptReason = planIdx === 0 && attempt === 0 ? opts.initialAttemptReason : "retry";
             try {
                 let result;
                 if (opts.mode === "stream") {
-                    result = await tryStreamOnce(provider, providerId, request, model, auth, opts.onToken ?? (() => { }), opts.onStatus);
+                    result = await tryStreamOnce(provider, providerId, request, model, auth, opts.onToken ?? (() => { }), opts.onStatus, attemptReason, singleDispatch, opts.onSuccessfulRequest);
                 }
                 else {
-                    result = await tryCompleteOnce(provider, providerId, request, model, auth);
+                    result = await tryCompleteOnce(provider, providerId, request, model, auth, attemptReason, opts.onStatus, singleDispatch);
                 }
                 // Sticky success only for stored multi-key (not env-only synthetic).
                 if (multi.source !== "env" && multi.source !== "local") {
@@ -712,7 +961,13 @@ async function runWithKeyRotation(opts) {
                 return result;
             }
             catch (error) {
+                const previousError = lastError;
                 lastError = error;
+                // An admission guard that fires while recovering from a real failure
+                // hides that failure. Report the cause the user can act on.
+                if (isOperationPolicyError(error) && previousError !== undefined) {
+                    throw previousError;
+                }
                 // 404/422: other keys for the same model will not help.
                 if (isKeyCircleStopError(error)) {
                     throw error;
@@ -746,7 +1001,7 @@ async function runWithKeyRotation(opts) {
                 }
                 const canRetrySame = attempt + 1 < maxPerKey;
                 if (canRetrySame) {
-                    const wait = isRateLimited(error)
+                    const wait = isRateLimited(error) || isServerUnavailable(error)
                         ? retryWaitMs(error, attempt)
                         : networkRetryWaitMs(attempt);
                     if (wait > MAX_RETRY_WAIT_MS) {
@@ -807,15 +1062,19 @@ async function runWithKeyRotation(opts) {
     const err = lastError ?? new Error("all API keys failed");
     throw err;
 }
-export async function completeWithProvider(request, options) {
+async function completeWithProviderOperation(request, options, ledger) {
     const config = getConfig();
+    const singleDispatch = options.singleDispatch === true;
     const requested = request.provider ?? config.defaultProvider;
     const providerImpl = getProvider(requested);
     const isDefaultModel = !request.model || request.model === providerImpl.defaultModel;
-    const fallbackEnabled = config.providerFallback &&
+    const fallbackEnabled = !singleDispatch &&
+        config.providerFallback &&
         (await requestedRealKeyCount(requested)) !== 1 &&
         (isDefaultModel || request.allowModelFallback === true);
-    const order = buildFallbackChain(requested, config.freeOnly, fallbackEnabled, request.preferModelFallback === true);
+    const order = singleDispatch
+        ? [requested]
+        : buildFallbackChain(requested, config.freeOnly, fallbackEnabled, request.preferModelFallback === true);
     const failures = [];
     const emitKey = makeKeyEmitter(options?.onStatus, options?.onKeyEvent);
     for (const providerId of order) {
@@ -830,7 +1089,10 @@ export async function completeWithProvider(request, options) {
         const model = providerId === requested
             ? (request.model ?? provider.defaultModel)
             : provider.defaultModel;
-        const routeRequest = requestForRoute(request, providerId, model);
+        const routeRequest = {
+            ...requestForRoute(request, providerId, model),
+            attemptUsage: ledger,
+        };
         try {
             const result = await runWithKeyRotation({
                 providerId,
@@ -839,17 +1101,26 @@ export async function completeWithProvider(request, options) {
                 model,
                 emitKey,
                 mode: "complete",
+                initialAttemptReason: providerId === requested ? "initial" : "fallback",
                 ...(options?.onStatus ? { onStatus: options.onStatus } : {}),
                 ...(options?.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),
+                ...(singleDispatch ? { singleDispatch: true } : {}),
             });
             if (providerId !== requested) {
-                setDefaultProvider(providerId);
-                setProviderModel(providerId, result.model || model);
+                if (options?.adoptFallback === true) {
+                    setDefaultProvider(providerId);
+                    setProviderModel(providerId, result.model || model);
+                }
                 options?.onStatus?.(`switching to ${providerId}/${result.model || model} after ${requested} failed`);
             }
             return result;
         }
         catch (error) {
+            if (isOperationPolicyError(error)) {
+                if (failures.length === 0)
+                    throw error;
+                throw aggregateProviderError(`No provider could complete the request.${formatFailures(failures)}`, failures);
+            }
             failures.push({
                 provider: providerId,
                 message: failureMessageFor(providerId, error),
@@ -863,18 +1134,68 @@ export async function completeWithProvider(request, options) {
     }
     throw aggregateProviderError(`No provider could complete the request.${formatFailures(failures)}`, failures);
 }
-export async function streamWithProvider(request, onToken, onStatusOrOptions) {
+function attachOperationUsageToError(error, snapshot) {
+    if (error && typeof error === "object" && Object.isExtensible(error)) {
+        try {
+            Object.defineProperty(error, "operationUsage", {
+                configurable: true,
+                enumerable: false,
+                value: snapshot,
+            });
+            return error;
+        }
+        catch { }
+    }
+    const message = error instanceof Error
+        ? error.message
+        : typeof error === "string" && error.trim()
+            ? error
+            : "Provider operation failed";
+    const wrapped = new Error(message, { cause: error });
+    Object.defineProperty(wrapped, "operationUsage", {
+        configurable: true,
+        enumerable: false,
+        value: snapshot,
+    });
+    return wrapped;
+}
+export async function completeWithProvider(request, options = {}) {
+    const ledger = resolveOperationLedger(options);
+    try {
+        const result = await completeWithProviderOperation(request, options, ledger);
+        ledger.settle("completed");
+        return { ...result, operationUsage: ledger.snapshot() };
+    }
+    catch (error) {
+        ledger.settle(operationTerminalOutcome(error, request.signal));
+        throw attachOperationUsageToError(error, ledger.snapshot());
+    }
+    finally {
+        options.onOperationUsage?.(ledger.snapshot());
+    }
+}
+async function streamWithProviderOperation(request, onToken, onStatusOrOptions, ledger) {
     const options = typeof onStatusOrOptions === "function"
         ? { onStatus: onStatusOrOptions }
         : onStatusOrOptions ?? {};
+    const operation = ledger ?? resolveOperationLedger(options);
+    const relayToken = (token) => {
+        operation.noteSemanticOutput();
+        onToken(token);
+    };
+    const downstreamToolDelta = request.onToolCallDelta;
     const config = getConfig();
+    const singleDispatch = options.singleDispatch === true;
     const requested = request.provider ?? config.defaultProvider;
     const providerImpl = getProvider(requested);
     const isDefaultModel = !request.model || request.model === providerImpl.defaultModel;
-    const fallbackEnabled = config.providerFallback &&
+    const fallbackEnabled = !singleDispatch &&
+        config.providerFallback &&
         (await requestedRealKeyCount(requested)) !== 1 &&
         (isDefaultModel || request.allowModelFallback === true);
-    const order = buildFallbackChain(requested, config.freeOnly, fallbackEnabled, request.preferModelFallback === true);
+    const order = singleDispatch
+        ? [requested]
+        : buildFallbackChain(requested, config.freeOnly, fallbackEnabled, request.preferModelFallback === true);
     const failures = [];
     const emitStatus = options.onStatus ?? ((message) => onToken(message));
     const emitKey = makeKeyEmitter(emitStatus, options.onKeyEvent);
@@ -889,7 +1210,28 @@ export async function streamWithProvider(request, onToken, onStatusOrOptions) {
         const model = providerId === requested
             ? (request.model ?? provider.defaultModel)
             : provider.defaultModel;
-        const routeRequest = requestForRoute(request, providerId, model);
+        const routeRequest = {
+            ...requestForRoute(request, providerId, model),
+            attemptUsage: operation,
+            ...(downstreamToolDelta
+                ? {
+                    onToolCallDelta: (delta) => {
+                        operation.noteSemanticOutput();
+                        downstreamToolDelta(delta);
+                    },
+                }
+                : {}),
+            ...(options.onStreamEvent
+                ? {
+                    onStreamEvent: (event) => {
+                        if (isSemanticStreamOutputEvent(event)) {
+                            operation.noteSemanticOutput();
+                        }
+                        options.onStreamEvent(event);
+                    },
+                }
+                : {}),
+        };
         try {
             const result = await runWithKeyRotation({
                 providerId,
@@ -898,18 +1240,30 @@ export async function streamWithProvider(request, onToken, onStatusOrOptions) {
                 model,
                 emitKey,
                 mode: "stream",
-                onToken,
+                initialAttemptReason: providerId === requested ? "initial" : "fallback",
+                onToken: relayToken,
                 onStatus: emitStatus,
                 ...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),
+                ...(singleDispatch ? { singleDispatch: true } : {}),
+                ...(options.onSuccessfulRequest
+                    ? { onSuccessfulRequest: options.onSuccessfulRequest }
+                    : {}),
             });
             if (providerId !== requested) {
-                setDefaultProvider(providerId);
-                setProviderModel(providerId, result.model || model);
+                if (options.adoptFallback === true) {
+                    setDefaultProvider(providerId);
+                    setProviderModel(providerId, result.model || model);
+                }
                 options.onStatus?.(`switching to ${providerId}/${result.model || model} after ${requested} failed`);
             }
             return result;
         }
         catch (error) {
+            if (isOperationPolicyError(error)) {
+                if (failures.length === 0)
+                    throw error;
+                throw aggregateProviderError(`No provider could stream the request.${formatFailures(failures)}`, failures, streamEmittedBytes(error));
+            }
             failures.push({
                 provider: providerId,
                 message: failureMessageFor(providerId, error),
@@ -927,6 +1281,24 @@ export async function streamWithProvider(request, onToken, onStatusOrOptions) {
     }
     throw aggregateProviderError(`No provider could stream the request.${formatFailures(failures)}`, failures);
 }
+export async function streamWithProvider(request, onToken, onStatusOrOptions) {
+    const options = typeof onStatusOrOptions === "function"
+        ? { onStatus: onStatusOrOptions }
+        : onStatusOrOptions ?? {};
+    const ledger = resolveOperationLedger(options);
+    try {
+        const result = await streamWithProviderOperation(request, onToken, options, ledger);
+        ledger.settle("completed");
+        return { ...result, operationUsage: ledger.snapshot() };
+    }
+    catch (error) {
+        ledger.settle(operationTerminalOutcome(error, request.signal));
+        throw attachOperationUsageToError(error, ledger.snapshot());
+    }
+    finally {
+        options.onOperationUsage?.(ledger.snapshot());
+    }
+}
 export async function pingProvider(providerId, secretOverride) {
     const provider = getProvider(providerId);
     const resolved = await providerAuth(providerId);