@jaypie/llm 1.3.13 → 1.3.15

package/dist/esm/index.js

@@ -475,234 +475,130 @@ function resolveModelChain(model) {
 
 //
 //
-// Abstract Base Adapter
+// Helpers
 //
-/**
- * BaseProviderAdapter provides default implementations for common adapter methods.
- * Providers can extend this class to reduce boilerplate.
- */
-class BaseProviderAdapter {
-    constructor() {
-        /**
-         * Whether OperateLoop may take a corrective turn when a `format` request
-         * completes with prose instead of structured output. Providers whose
-         * structured output rides a tool emulation (where compliance is a model
-         * decision) opt in; native grammar-constrained providers do not need it.
-         */
-        this.supportsStructuredOutputRetry = false;
-    }
-    /**
-     * Default implementation checks if error is retryable via classifyError
-     */
-    isRetryableError(error) {
-        const classified = this.classifyError(error);
-        return classified.shouldRetry;
-    }
-    /**
-     * Default implementation checks error category via classifyError
-     */
-    isRateLimitError(error) {
-        const classified = this.classifyError(error);
-        return classified.category === "rate_limit";
-    }
-    /**
-     * Default implementation returns false - override for providers with native structured output
-     */
-    hasStructuredOutput(_response) {
-        return false;
-    }
-    /**
-     * Default implementation returns undefined - override for providers with native structured output
-     */
-    extractStructuredOutput(_response) {
+function sumUsageByProviderModel(usage) {
+    if (!usage.length) {
         return undefined;
     }
+    const totals = {};
+    for (const item of usage) {
+        const key = `${item.provider ?? "unknown"}:${item.model ?? "unknown"}`;
+        if (!totals[key]) {
+            totals[key] = {
+                input: 0,
+                model: item.model,
+                output: 0,
+                provider: item.provider,
+                reasoning: 0,
+                total: 0,
+            };
+        }
+        totals[key].input += item.input;
+        totals[key].output += item.output;
+        totals[key].reasoning += item.reasoning;
+        totals[key].total += item.total;
+        if (item.cacheRead !== undefined) {
+            totals[key].cacheRead = (totals[key].cacheRead ?? 0) + item.cacheRead;
+        }
+        if (item.cacheWrite !== undefined) {
+            totals[key].cacheWrite = (totals[key].cacheWrite ?? 0) + item.cacheWrite;
+        }
+    }
+    return totals;
 }
-
+function extractResponseIds(responses) {
+    const ids = responses
+        .map((response) => response && typeof response === "object"
+        ? response.id
+        : undefined)
+        .filter((id) => typeof id === "string");
+    return ids.length ? ids : undefined;
+}
+//
+//
+// Main
+//
 /**
- * Per-provider translation of the provider-neutral {@link LlmEffort} scale.
- *
- * The neutral enum (lowest → low → medium → high → highest) is a relative
- * five-point scale. Each table below maps it onto the target provider's native
- * effort control, keeping `medium`/`high` semantically aligned across providers
- * and using each provider's extra bottom (`minimal`) or top (`xhigh`/`max`)
- * rung where one exists. Providers with fewer levels collapse the ends and mark
- * the result `papered`. A single `effort` value is therefore safe to reuse
- * across providers and fallback chains.
+ * Assemble the serializable exchange envelope for one operate() settlement.
+ * The `resolution` block is stamped by the Llm facade, which is the layer
+ * that knows fallback outcome; the loop fills provider/model best-effort.
  */
-/** Consistent debug message for a papered-over effort level. */
-function paperedEffortMessage({ model, provider, requested, value, }) {
-    return `[llm] effort '${requested}' has no distinct tier on ${provider} model '${model}'; using '${value}'`;
-}
-// OpenAI Responses API `reasoning.effort`.
-// Full ladder: minimal | low | medium | high | xhigh (plus `none`). Availability
-// is not uniform across the gpt-5 line:
-//   - `xhigh` was introduced at gpt-5.2 and has been continuous since, so it is
-//     safe for our gpt-5.4 default and everything newer.
-//   - `minimal` shipped on gpt-5/5.1, was dropped at gpt-5.2, and returned on
-//     the current line; because that history is non-monotonic we only trust it
-//     from gpt-5.4 (our default floor) onward.
-// Outside those windows (older gpt-5, o-series) the extreme rung is clamped and
-// the mapping reports `papered: true`.
-const OPENAI_EFFORT = {
-    [EFFORT.LOWEST]: "minimal",
-    [EFFORT.LOW]: "low",
-    [EFFORT.MEDIUM]: "medium",
-    [EFFORT.HIGH]: "high",
-    [EFFORT.HIGHEST]: "xhigh",
-};
-function openAiGptVersion(model) {
-    const match = model.match(/^gpt-(\d+)(?:\.(\d+))?/);
-    if (!match)
-        return null;
-    return { major: Number(match[1]), minor: match[2] ? Number(match[2]) : 0 };
-}
-function atLeast(version, major, minor) {
-    if (!version)
-        return false;
-    return (version.major > major || (version.major === major && version.minor >= minor));
+function buildExchangeEnvelope({ duration, initialHistoryLength, input, options, response, startedAt, state, }) {
+    const historyDelta = response.history.slice(initialHistoryLength);
+    return {
+        ids: extractResponseIds(response.responses),
+        request: {
+            cache: options.cache,
+            data: options.data,
+            effort: options.effort,
+            explain: options.explain,
+            format: state.formattedFormat,
+            input,
+            instructions: options.instructions,
+            model: options.model,
+            placeholders: options.placeholders,
+            providerOptions: options.providerOptions,
+            system: options.system,
+            temperature: options.temperature,
+            tools: state.formattedTools?.map(({ name }) => name),
+            turns: options.turns,
+            user: options.user,
+        },
+        resolution: {
+            model: response.model,
+            provider: response.provider,
+            retries: state.retries,
+        },
+        response: {
+            content: response.content,
+            error: response.error,
+            historyDelta,
+            reasoning: response.reasoning,
+            status: response.status,
+            stopReason: state.lastStopReason,
+            usage: response.usage,
+            usageTotals: sumUsageByProviderModel(response.usage),
+        },
+        timing: {
+            duration,
+            startedAt,
+        },
+    };
 }
-function toOpenAiEffort(effort, { model }) {
-    const native = OPENAI_EFFORT[effort];
-    const version = openAiGptVersion(model);
-    // `minimal` only from gpt-5.4 (non-monotonic history; absent on o-series)
-    if (native === "minimal" && !atLeast(version, 5, 4)) {
-        return { papered: true, value: "low" };
+
+const CACHE_TTL_DEFAULT = "5m";
+/**
+ * Normalize the caller-facing `cache` option into a concrete decision.
+ * - `undefined` / `true` → enabled at the default TTL
+ * - `false` / `0` → disabled
+ * - `"5m"` / `"1h"` → enabled at that TTL
+ */
+function resolveCache(cache) {
+    if (cache === false || cache === 0) {
+        return { enabled: false, ttl: CACHE_TTL_DEFAULT };
     }
-    // `xhigh` from gpt-5.2 onward (absent on older gpt-5 and o-series)
-    if (native === "xhigh" && !atLeast(version, 5, 2)) {
-        return { papered: true, value: "high" };
+    if (cache === "5m" || cache === "1h") {
+        return { enabled: true, ttl: cache };
     }
-    return { papered: false, value: native };
-}
-// xAI Grok `reasoning_effort` — low | medium | high. No sub-low or top rung, so
-// `lowest` collapses onto `low` and `highest` onto `high`.
-const XAI_EFFORT = {
-    [EFFORT.LOWEST]: { papered: true, value: "low" },
-    [EFFORT.LOW]: { papered: false, value: "low" },
-    [EFFORT.MEDIUM]: { papered: false, value: "medium" },
-    [EFFORT.HIGH]: { papered: false, value: "high" },
-    [EFFORT.HIGHEST]: { papered: true, value: "high" },
-};
-function toXaiEffort(effort) {
-    return XAI_EFFORT[effort];
-}
-// Anthropic `output_config.effort` — low | medium | high | xhigh | max. No
-// sub-low rung, so `lowest` collapses onto `low`; `highest` reaches `max`.
-const ANTHROPIC_EFFORT = {
-    [EFFORT.LOWEST]: { papered: true, value: "low" },
-    [EFFORT.LOW]: { papered: false, value: "low" },
-    [EFFORT.MEDIUM]: { papered: false, value: "medium" },
-    [EFFORT.HIGH]: { papered: false, value: "high" },
-    [EFFORT.HIGHEST]: { papered: false, value: "max" },
-};
-function toAnthropicEffort(effort) {
-    return ANTHROPIC_EFFORT[effort];
-}
-// Gemini 3.x `thinkingConfig.thinkingLevel` — MINIMAL | LOW | MEDIUM | HIGH. No
-// top rung above HIGH, so `highest` collapses onto HIGH.
-const GEMINI_THINKING_LEVEL = {
-    [EFFORT.LOWEST]: { papered: false, value: "MINIMAL" },
-    [EFFORT.LOW]: { papered: false, value: "LOW" },
-    [EFFORT.MEDIUM]: { papered: false, value: "MEDIUM" },
-    [EFFORT.HIGH]: { papered: false, value: "HIGH" },
-    [EFFORT.HIGHEST]: { papered: true, value: "HIGH" },
-};
-function toGeminiThinkingLevel(effort) {
-    return GEMINI_THINKING_LEVEL[effort];
-}
-// Gemini 2.5 `thinkingConfig.thinkingBudget` — every tier is a distinct token
-// budget, so nothing is papered over. Floor (512) clears every 2.5 minimum;
-// ceiling (24,576) is valid across 2.5 Pro (max 32,768) and Flash (max 24,576).
-const GEMINI_THINKING_BUDGET = {
-    [EFFORT.LOWEST]: 512,
-    [EFFORT.LOW]: 4096,
-    [EFFORT.MEDIUM]: 8192,
-    [EFFORT.HIGH]: 16384,
-    [EFFORT.HIGHEST]: 24576,
-};
-function toGeminiThinkingBudget(effort) {
-    return { papered: false, value: GEMINI_THINKING_BUDGET[effort] };
-}
-// Fireworks `reasoning_effort` — low | medium | high. Accepted on every model
-// (the API no-ops where unsupported). No sub-low or top rung, so `lowest`
-// collapses onto `low` and `highest` onto `high`.
-const FIREWORKS_EFFORT = {
-    [EFFORT.LOWEST]: { papered: true, value: "low" },
-    [EFFORT.LOW]: { papered: false, value: "low" },
-    [EFFORT.MEDIUM]: { papered: false, value: "medium" },
-    [EFFORT.HIGH]: { papered: false, value: "high" },
-    [EFFORT.HIGHEST]: { papered: true, value: "high" },
-};
-function toFireworksEffort(effort) {
-    return FIREWORKS_EFFORT[effort];
+    // undefined or true
+    return { enabled: true, ttl: CACHE_TTL_DEFAULT };
 }
-// OpenRouter `reasoning.effort` — accepts the full minimal..xhigh ladder and
-// maps to the routed provider's nearest supported level itself, so nothing is
-// papered here.
-const OPENROUTER_EFFORT = {
-    [EFFORT.LOWEST]: "minimal",
-    [EFFORT.LOW]: "low",
-    [EFFORT.MEDIUM]: "medium",
-    [EFFORT.HIGH]: "high",
-    [EFFORT.HIGHEST]: "xhigh",
-};
-function toOpenRouterEffort(effort) {
-    return { papered: false, value: OPENROUTER_EFFORT[effort] };
+/**
+ * Deterministic short key for providers with automatic, prefix-based caching
+ * (e.g. OpenAI `prompt_cache_key`). Derived from the stable prefix so the same
+ * system prompt + tools + model always routes to the same cache. Dependency-
+ * free FNV-1a; not cryptographic.
+ */
+function promptCacheKey(seed) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < seed.length; i += 1) {
+        hash ^= seed.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return `jaypie-${(hash >>> 0).toString(16)}`;
 }
 
-// Enums
-var LlmMessageRole;
-(function (LlmMessageRole) {
-    LlmMessageRole["Assistant"] = "assistant";
-    LlmMessageRole["Developer"] = "developer";
-    LlmMessageRole["System"] = "system";
-    LlmMessageRole["User"] = "user";
-})(LlmMessageRole || (LlmMessageRole = {}));
-var LlmMessageType;
-(function (LlmMessageType) {
-    LlmMessageType["FunctionCall"] = "function_call";
-    LlmMessageType["FunctionCallOutput"] = "function_call_output";
-    LlmMessageType["InputFile"] = "input_file";
-    LlmMessageType["InputImage"] = "input_image";
-    LlmMessageType["InputText"] = "input_text";
-    LlmMessageType["ItemReference"] = "item_reference";
-    LlmMessageType["Message"] = "message";
-    LlmMessageType["OutputText"] = "output_text";
-    LlmMessageType["Refusal"] = "refusal";
-})(LlmMessageType || (LlmMessageType = {}));
-var LlmResponseStatus;
-(function (LlmResponseStatus) {
-    LlmResponseStatus["Completed"] = "completed";
-    LlmResponseStatus["Incomplete"] = "incomplete";
-    LlmResponseStatus["InProgress"] = "in_progress";
-})(LlmResponseStatus || (LlmResponseStatus = {}));
-// Progress
-var LlmProgressEventType;
-(function (LlmProgressEventType) {
-    LlmProgressEventType["Done"] = "done";
-    LlmProgressEventType["ModelRequest"] = "model_request";
-    LlmProgressEventType["ModelResponse"] = "model_response";
-    LlmProgressEventType["Retry"] = "retry";
-    LlmProgressEventType["Start"] = "start";
-    LlmProgressEventType["ToolCall"] = "tool_call";
-    LlmProgressEventType["ToolError"] = "tool_error";
-    LlmProgressEventType["ToolResult"] = "tool_result";
-})(LlmProgressEventType || (LlmProgressEventType = {}));
-
-//
-//
-// Types
-//
-var LlmStreamChunkType;
-(function (LlmStreamChunkType) {
-    LlmStreamChunkType["Done"] = "done";
-    LlmStreamChunkType["Error"] = "error";
-    LlmStreamChunkType["Text"] = "text";
-    LlmStreamChunkType["ToolCall"] = "tool_call";
-    LlmStreamChunkType["ToolResult"] = "tool_result";
-})(LlmStreamChunkType || (LlmStreamChunkType = {}));
-
 /**
  * Type guard to check if an item is a dedicated reasoning item (OpenAI)
  */
@@ -921,6 +817,45 @@ function fillFormatArrays({ content, format, }) {
     return fillFromSchema(schema, structuredClone(content));
 }
 
+// Enums
+var LlmMessageRole;
+(function (LlmMessageRole) {
+    LlmMessageRole["Assistant"] = "assistant";
+    LlmMessageRole["Developer"] = "developer";
+    LlmMessageRole["System"] = "system";
+    LlmMessageRole["User"] = "user";
+})(LlmMessageRole || (LlmMessageRole = {}));
+var LlmMessageType;
+(function (LlmMessageType) {
+    LlmMessageType["FunctionCall"] = "function_call";
+    LlmMessageType["FunctionCallOutput"] = "function_call_output";
+    LlmMessageType["InputFile"] = "input_file";
+    LlmMessageType["InputImage"] = "input_image";
+    LlmMessageType["InputText"] = "input_text";
+    LlmMessageType["ItemReference"] = "item_reference";
+    LlmMessageType["Message"] = "message";
+    LlmMessageType["OutputText"] = "output_text";
+    LlmMessageType["Refusal"] = "refusal";
+})(LlmMessageType || (LlmMessageType = {}));
+var LlmResponseStatus;
+(function (LlmResponseStatus) {
+    LlmResponseStatus["Completed"] = "completed";
+    LlmResponseStatus["Incomplete"] = "incomplete";
+    LlmResponseStatus["InProgress"] = "in_progress";
+})(LlmResponseStatus || (LlmResponseStatus = {}));
+// Progress
+var LlmProgressEventType;
+(function (LlmProgressEventType) {
+    LlmProgressEventType["Done"] = "done";
+    LlmProgressEventType["ModelRequest"] = "model_request";
+    LlmProgressEventType["ModelResponse"] = "model_response";
+    LlmProgressEventType["Retry"] = "retry";
+    LlmProgressEventType["Start"] = "start";
+    LlmProgressEventType["ToolCall"] = "tool_call";
+    LlmProgressEventType["ToolError"] = "tool_error";
+    LlmProgressEventType["ToolResult"] = "tool_result";
+})(LlmProgressEventType || (LlmProgressEventType = {}));
+
 /**
  * Converts a string to a standardized LlmInputMessage
  * @param input - String to format
@@ -1515,64 +1450,367 @@ function tallyOperate({ toolCallNames = [], turns, usage = [], }) {
             usageByModel[key].output += item.output;
             usageByModel[key].reasoning += item.reasoning;
             usageByModel[key].total += item.total;
+            if (item.cacheRead !== undefined) {
+                usageByModel[key].cacheRead =
+                    (usageByModel[key].cacheRead ?? 0) + item.cacheRead;
+            }
+            if (item.cacheWrite !== undefined) {
+                usageByModel[key].cacheWrite =
+                    (usageByModel[key].cacheWrite ?? 0) + item.cacheWrite;
+            }
         }
         llm.usage = usageByModel;
     }
     log$2.tally({ llm });
 }
-
-/**
- * Helper function to safely call a function that might throw
- * @param fn Function to call safely
- */
-function callSafely(fn) {
-    try {
-        fn();
-    }
-    catch {
-        // Silently catch any errors from the function
-    }
+
+/**
+ * Helper function to safely call a function that might throw
+ * @param fn Function to call safely
+ */
+function callSafely(fn) {
+    try {
+        fn();
+    }
+    catch {
+        // Silently catch any errors from the function
+    }
+}
+/**
+ * Attempts to parse a value as a number. Returns the original input if parsing fails or results in NaN.
+ * @param input - The value to attempt to parse as a number
+ * @param options - Optional configuration
+ * @param options.defaultValue - Default value to return if parsing fails or results in NaN
+ * @param options.warnFunction - Function to call with warning message if parsing fails or results in NaN
+ * @returns The parsed number, defaultValue (if specified and parsing fails), or the original input
+ */
+function tryParseNumber(input, options) {
+    if (input === null || input === undefined) {
+        return input;
+    }
+    try {
+        const parsed = Number(input);
+        if (Number.isNaN(parsed)) {
+            if (options?.warnFunction) {
+                const warningMessage = `Failed to parse "${String(input)}" as number`;
+                callSafely(() => options.warnFunction(warningMessage));
+            }
+            return typeof options?.defaultValue === "number"
+                ? options.defaultValue
+                : input;
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (options?.warnFunction) {
+            let errorMessage = "";
+            if (error instanceof Error) {
+                errorMessage = error.message;
+            }
+            const warningMessage = `Error parsing "${String(input)}" as number${errorMessage ? "; " + errorMessage : ""}`;
+            callSafely(() => options.warnFunction(warningMessage));
+        }
+        return typeof options?.defaultValue === "number"
+            ? options.defaultValue
+            : input;
+    }
+}
+
+/**
+ * Truthy-except-"false"/"0" gate on LLM_EXCHANGE_ENABLED, matching the
+ * DD_LLMOBS_ENABLED convention in observability/llmobs.ts.
+ */
+function isExchangeStoreEnabled() {
+    const flag = process.env.LLM_EXCHANGE_ENABLED;
+    if (!flag) {
+        return false;
+    }
+    return flag.toLowerCase() !== "false" && flag !== "0";
+}
+/**
+ * Whether the loop should assemble an exchange envelope at settlement.
+ */
+function isExchangeRequested({ onExchange, }) {
+    return Boolean(onExchange) || isExchangeStoreEnabled();
+}
+/**
+ * Deliver an exchange envelope to a callback. Errors thrown by the callback
+ * are logged and swallowed — exchange capture must never interrupt the call.
+ */
+async function emitExchange({ envelope, onExchange, }) {
+    if (!onExchange) {
+        return;
+    }
+    try {
+        await onExchange(envelope);
+    }
+    catch (error) {
+        const log = getLogger$7();
+        log.warn("[operate] onExchange callback threw");
+        log.var({ error });
+    }
+}
+
+//
+//
+// Constants
+//
+const MODULE$1 = {
+    // Computed at runtime so bundlers (esbuild) do not attempt to include
+    // @jaypie/dynamodb, which is an optional peer dependency.
+    JAYPIE_DYNAMODB: ["@jaypie", "dynamodb"].join("/"),
+};
+//
+//
+// Helpers
+//
+// Native dynamic import that neither rollup nor tsc rewrites to require(), so
+// a CJS-bundled build still loads @jaypie/dynamodb's ESM entry and shares the
+// host's initialized module instance. A require()-based resolution would load
+// the CJS build, whose module-level client state is separate from the ESM
+// instance an ESM host initializes (dual-package hazard, issue #429).
+const dynamicImport = new Function("s", "return import(s)");
+let resolved$1 = false;
+let cachedSdk$2 = null;
+/**
+ * Lazily resolve @jaypie/dynamodb's storeExchange. Returns null (and never
+ * throws) when the peer is absent. Cached after the first attempt.
+ */
+async function resolveExchangeStore() {
+    if (resolved$1) {
+        return cachedSdk$2;
+    }
+    resolved$1 = true;
+    try {
+        const dynamodb = await dynamicImport(MODULE$1.JAYPIE_DYNAMODB);
+        const sdk = (dynamodb?.default ?? dynamodb);
+        if (sdk && typeof sdk.storeExchange === "function") {
+            cachedSdk$2 = sdk;
+        }
+    }
+    catch {
+        cachedSdk$2 = null;
+    }
+    return cachedSdk$2;
+}
+//
+//
+// Main
+//
+/**
+ * Persist an exchange envelope via @jaypie/dynamodb when
+ * LLM_EXCHANGE_ENABLED is set. Silent no-op when the flag is unset or the
+ * peer is absent; persister failures are logged and never thrown.
+ */
+async function persistExchange(envelope) {
+    if (!isExchangeStoreEnabled()) {
+        return;
+    }
+    const sdk = (await resolveExchangeStore());
+    if (!sdk) {
+        return;
+    }
+    try {
+        await sdk.storeExchange(envelope);
+    }
+    catch (error) {
+        const log = getLogger$7();
+        log.warn("[operate] Exchange persistence failed");
+        log.var({ error });
+    }
+}
+
+//
+//
+// Abstract Base Adapter
+//
+/**
+ * BaseProviderAdapter provides default implementations for common adapter methods.
+ * Providers can extend this class to reduce boilerplate.
+ */
+class BaseProviderAdapter {
+    constructor() {
+        /**
+         * Whether OperateLoop may take a corrective turn when a `format` request
+         * completes with prose instead of structured output. Providers whose
+         * structured output rides a tool emulation (where compliance is a model
+         * decision) opt in; native grammar-constrained providers do not need it.
+         */
+        this.supportsStructuredOutputRetry = false;
+    }
+    /**
+     * Default implementation checks if error is retryable via classifyError
+     */
+    isRetryableError(error) {
+        const classified = this.classifyError(error);
+        return classified.shouldRetry;
+    }
+    /**
+     * Default implementation checks error category via classifyError
+     */
+    isRateLimitError(error) {
+        const classified = this.classifyError(error);
+        return classified.category === "rate_limit";
+    }
+    /**
+     * Default implementation returns false - override for providers with native structured output
+     */
+    hasStructuredOutput(_response) {
+        return false;
+    }
+    /**
+     * Default implementation returns undefined - override for providers with native structured output
+     */
+    extractStructuredOutput(_response) {
+        return undefined;
+    }
+}
+
+/**
+ * Per-provider translation of the provider-neutral {@link LlmEffort} scale.
+ *
+ * The neutral enum (lowest → low → medium → high → highest) is a relative
+ * five-point scale. Each table below maps it onto the target provider's native
+ * effort control, keeping `medium`/`high` semantically aligned across providers
+ * and using each provider's extra bottom (`minimal`) or top (`xhigh`/`max`)
+ * rung where one exists. Providers with fewer levels collapse the ends and mark
+ * the result `papered`. A single `effort` value is therefore safe to reuse
+ * across providers and fallback chains.
+ */
+/** Consistent debug message for a papered-over effort level. */
+function paperedEffortMessage({ model, provider, requested, value, }) {
+    return `[llm] effort '${requested}' has no distinct tier on ${provider} model '${model}'; using '${value}'`;
+}
+// OpenAI Responses API `reasoning.effort`.
+// Full ladder: minimal | low | medium | high | xhigh (plus `none`). Availability
+// is not uniform across the gpt-5 line:
+//   - `xhigh` was introduced at gpt-5.2 and has been continuous since, so it is
+//     safe for our gpt-5.4 default and everything newer.
+//   - `minimal` shipped on gpt-5/5.1, was dropped at gpt-5.2, and returned on
+//     the current line; because that history is non-monotonic we only trust it
+//     from gpt-5.4 (our default floor) onward.
+// Outside those windows (older gpt-5, o-series) the extreme rung is clamped and
+// the mapping reports `papered: true`.
+const OPENAI_EFFORT = {
+    [EFFORT.LOWEST]: "minimal",
+    [EFFORT.LOW]: "low",
+    [EFFORT.MEDIUM]: "medium",
+    [EFFORT.HIGH]: "high",
+    [EFFORT.HIGHEST]: "xhigh",
+};
+function openAiGptVersion(model) {
+    const match = model.match(/^gpt-(\d+)(?:\.(\d+))?/);
+    if (!match)
+        return null;
+    return { major: Number(match[1]), minor: match[2] ? Number(match[2]) : 0 };
+}
+function atLeast(version, major, minor) {
+    if (!version)
+        return false;
+    return (version.major > major || (version.major === major && version.minor >= minor));
 }
-/**
- * Attempts to parse a value as a number. Returns the original input if parsing fails or results in NaN.
- * @param input - The value to attempt to parse as a number
- * @param options - Optional configuration
- * @param options.defaultValue - Default value to return if parsing fails or results in NaN
- * @param options.warnFunction - Function to call with warning message if parsing fails or results in NaN
- * @returns The parsed number, defaultValue (if specified and parsing fails), or the original input
- */
-function tryParseNumber(input, options) {
-    if (input === null || input === undefined) {
-        return input;
-    }
-    try {
-        const parsed = Number(input);
-        if (Number.isNaN(parsed)) {
-            if (options?.warnFunction) {
-                const warningMessage = `Failed to parse "${String(input)}" as number`;
-                callSafely(() => options.warnFunction(warningMessage));
-            }
-            return typeof options?.defaultValue === "number"
-                ? options.defaultValue
-                : input;
-        }
-        return parsed;
+function toOpenAiEffort(effort, { model }) {
+    const native = OPENAI_EFFORT[effort];
+    const version = openAiGptVersion(model);
+    // `minimal` only from gpt-5.4 (non-monotonic history; absent on o-series)
+    if (native === "minimal" && !atLeast(version, 5, 4)) {
+        return { papered: true, value: "low" };
     }
-    catch (error) {
-        if (options?.warnFunction) {
-            let errorMessage = "";
-            if (error instanceof Error) {
-                errorMessage = error.message;
-            }
-            const warningMessage = `Error parsing "${String(input)}" as number${errorMessage ? "; " + errorMessage : ""}`;
-            callSafely(() => options.warnFunction(warningMessage));
-        }
-        return typeof options?.defaultValue === "number"
-            ? options.defaultValue
-            : input;
+    // `xhigh` from gpt-5.2 onward (absent on older gpt-5 and o-series)
+    if (native === "xhigh" && !atLeast(version, 5, 2)) {
+        return { papered: true, value: "high" };
     }
+    return { papered: false, value: native };
+}
+// xAI Grok `reasoning_effort` — low | medium | high. No sub-low or top rung, so
+// `lowest` collapses onto `low` and `highest` onto `high`.
+const XAI_EFFORT = {
+    [EFFORT.LOWEST]: { papered: true, value: "low" },
+    [EFFORT.LOW]: { papered: false, value: "low" },
+    [EFFORT.MEDIUM]: { papered: false, value: "medium" },
+    [EFFORT.HIGH]: { papered: false, value: "high" },
+    [EFFORT.HIGHEST]: { papered: true, value: "high" },
+};
+function toXaiEffort(effort) {
+    return XAI_EFFORT[effort];
+}
+// Anthropic `output_config.effort` — low | medium | high | xhigh | max. No
+// sub-low rung, so `lowest` collapses onto `low`; `highest` reaches `max`.
+const ANTHROPIC_EFFORT = {
+    [EFFORT.LOWEST]: { papered: true, value: "low" },
+    [EFFORT.LOW]: { papered: false, value: "low" },
+    [EFFORT.MEDIUM]: { papered: false, value: "medium" },
+    [EFFORT.HIGH]: { papered: false, value: "high" },
+    [EFFORT.HIGHEST]: { papered: false, value: "max" },
+};
+function toAnthropicEffort(effort) {
+    return ANTHROPIC_EFFORT[effort];
+}
+// Gemini 3.x `thinkingConfig.thinkingLevel` — MINIMAL | LOW | MEDIUM | HIGH. No
+// top rung above HIGH, so `highest` collapses onto HIGH.
+const GEMINI_THINKING_LEVEL = {
+    [EFFORT.LOWEST]: { papered: false, value: "MINIMAL" },
+    [EFFORT.LOW]: { papered: false, value: "LOW" },
+    [EFFORT.MEDIUM]: { papered: false, value: "MEDIUM" },
+    [EFFORT.HIGH]: { papered: false, value: "HIGH" },
+    [EFFORT.HIGHEST]: { papered: true, value: "HIGH" },
+};
+function toGeminiThinkingLevel(effort) {
+    return GEMINI_THINKING_LEVEL[effort];
+}
+// Gemini 2.5 `thinkingConfig.thinkingBudget` — every tier is a distinct token
+// budget, so nothing is papered over. Floor (512) clears every 2.5 minimum;
+// ceiling (24,576) is valid across 2.5 Pro (max 32,768) and Flash (max 24,576).
+const GEMINI_THINKING_BUDGET = {
+    [EFFORT.LOWEST]: 512,
+    [EFFORT.LOW]: 4096,
+    [EFFORT.MEDIUM]: 8192,
+    [EFFORT.HIGH]: 16384,
+    [EFFORT.HIGHEST]: 24576,
+};
+function toGeminiThinkingBudget(effort) {
+    return { papered: false, value: GEMINI_THINKING_BUDGET[effort] };
+}
+// Fireworks `reasoning_effort` — low | medium | high. Accepted on every model
+// (the API no-ops where unsupported). No sub-low or top rung, so `lowest`
+// collapses onto `low` and `highest` onto `high`.
+const FIREWORKS_EFFORT = {
+    [EFFORT.LOWEST]: { papered: true, value: "low" },
+    [EFFORT.LOW]: { papered: false, value: "low" },
+    [EFFORT.MEDIUM]: { papered: false, value: "medium" },
+    [EFFORT.HIGH]: { papered: false, value: "high" },
+    [EFFORT.HIGHEST]: { papered: true, value: "high" },
+};
+function toFireworksEffort(effort) {
+    return FIREWORKS_EFFORT[effort];
+}
+// OpenRouter `reasoning.effort` — accepts the full minimal..xhigh ladder and
+// maps to the routed provider's nearest supported level itself, so nothing is
+// papered here.
+const OPENROUTER_EFFORT = {
+    [EFFORT.LOWEST]: "minimal",
+    [EFFORT.LOW]: "low",
+    [EFFORT.MEDIUM]: "medium",
+    [EFFORT.HIGH]: "high",
+    [EFFORT.HIGHEST]: "xhigh",
+};
+function toOpenRouterEffort(effort) {
+    return { papered: false, value: OPENROUTER_EFFORT[effort] };
 }
 
+//
+//
+// Types
+//
+var LlmStreamChunkType;
+(function (LlmStreamChunkType) {
+    LlmStreamChunkType["Done"] = "done";
+    LlmStreamChunkType["Error"] = "error";
+    LlmStreamChunkType["Text"] = "text";
+    LlmStreamChunkType["ToolCall"] = "tool_call";
+    LlmStreamChunkType["ToolResult"] = "tool_result";
+})(LlmStreamChunkType || (LlmStreamChunkType = {}));
+
 //
 //
 // Error Classification Types
@@ -2156,8 +2394,19 @@ class AnthropicAdapter extends BaseProviderAdapter {
                 PROVIDER.ANTHROPIC.MAX_TOKENS.DEFAULT,
             stream: false,
         };
+        const cache = resolveCache(request.cache);
+        const cacheControl = cache.enabled
+            ? {
+                type: "ephemeral",
+                ...(cache.ttl === "1h" ? { ttl: "1h" } : {}),
+            }
+            : undefined;
         if (request.system) {
-            anthropicRequest.system = request.system;
+            // A cache breakpoint on the system block caches tools+system together
+            // (render order is tools -> system -> messages).
+            anthropicRequest.system = cacheControl
+                ? [{ type: "text", text: request.system, cache_control: cacheControl }]
+                : request.system;
         }
         const useFallbackStructuredOutput = Boolean(request.format) &&
             !this.supportsStructuredOutput(anthropicRequest.model);
@@ -2174,7 +2423,7 @@ class AnthropicAdapter extends BaseProviderAdapter {
             });
         }
         if (allTools.length > 0) {
-            anthropicRequest.tools = allTools.map((tool) => ({
+            anthropicRequest.tools = allTools.map((tool, index) => ({
                 name: tool.name,
                 description: tool.description,
                 input_schema: {
@@ -2182,6 +2431,11 @@ class AnthropicAdapter extends BaseProviderAdapter {
                     type: "object",
                 },
                 type: "custom",
+                // Breakpoint on the last tool caches the tool list (which renders
+                // before system) when there is no system prompt to anchor it.
+                ...(cacheControl && index === allTools.length - 1
+                    ? { cache_control: cacheControl }
+                    : {}),
             }));
             anthropicRequest.tool_choice = useFallbackStructuredOutput
                 ? { type: "any" }
@@ -2484,6 +2738,12 @@ class AnthropicAdapter extends BaseProviderAdapter {
             output: usage.output_tokens,
             reasoning: usage.thinking_tokens || 0,
             total: usage.input_tokens + usage.output_tokens,
+            ...(usage.cache_read_input_tokens !== undefined
+                ? { cacheRead: usage.cache_read_input_tokens }
+                : {}),
+            ...(usage.cache_creation_input_tokens !== undefined
+                ? { cacheWrite: usage.cache_creation_input_tokens }
+                : {}),
             provider: this.name,
             model,
         };
@@ -2736,6 +2996,14 @@ function isTemperatureDeprecationError$3(error) {
     const msg = error?.message ?? "";
     return /temperature.*deprecated|deprecated.*temperature/i.test(msg);
 }
+function isCachePointUnsupportedError(error) {
+    const name = error?.constructor?.name ?? "";
+    const msg = error?.message ?? "";
+    // A model that cannot cache rejects the cachePoint block with a
+    // ValidationException naming caching / cachePoint.
+    return (/ValidationException|invalid|not support/i.test(name + " " + msg) &&
+        /cachePoint|cache_point|prompt caching|caching/i.test(msg));
+}
 function extractJson(text) {
     // Try direct parse first
     try {
@@ -2771,6 +3039,13 @@ class BedrockAdapter extends BaseProviderAdapter {
         this.defaultModel = PROVIDER.BEDROCK.DEFAULT;
         this._modelsFallbackToStructuredOutputTool = new Set();
         this._modelsWithoutTemperature = new Set();
+        this._modelsWithoutCachePoint = new Set();
+    }
+    rememberModelRejectsCachePoint(model) {
+        this._modelsWithoutCachePoint.add(model);
+    }
+    supportsCachePoint(model) {
+        return !this._modelsWithoutCachePoint.has(model);
     }
     rememberModelRejectsOutputConfig(model) {
         this._modelsFallbackToStructuredOutputTool.add(model);
@@ -2907,11 +3182,51 @@ class BedrockAdapter extends BaseProviderAdapter {
                 };
             }
         }
+        // Prompt caching via Converse cachePoint blocks (5-min default TTL; the
+        // `ttl` option does not apply). Gated per model — cachePoint 400s on
+        // unsupported models, which executeRequest catches and denylists.
+        if (resolveCache(request.cache).enabled && this.supportsCachePoint(model)) {
+            const cachePoint = { cachePoint: { type: "default" } };
+            if (bedrockRequest.system && bedrockRequest.system.length > 0) {
+                bedrockRequest.system = [
+                    ...bedrockRequest.system,
+                    cachePoint,
+                ];
+            }
+            if (bedrockRequest.toolConfig?.tools?.length) {
+                bedrockRequest.toolConfig = {
+                    ...bedrockRequest.toolConfig,
+                    tools: [
+                        ...bedrockRequest.toolConfig.tools,
+                        cachePoint,
+                    ],
+                };
+            }
+        }
         if (request.providerOptions) {
             Object.assign(bedrockRequest, request.providerOptions);
         }
         return bedrockRequest;
     }
+    /** Remove any cachePoint blocks so the request can be retried unsupported. */
+    stripCachePoints(request) {
+        const stripped = { ...request };
+        if (stripped.system) {
+            stripped.system = stripped.system.filter((block) => !("cachePoint" in block));
+        }
+        if (stripped.toolConfig?.tools) {
+            stripped.toolConfig = {
+                ...stripped.toolConfig,
+                tools: stripped.toolConfig.tools.filter((tool) => !("cachePoint" in tool)),
+            };
+        }
+        return stripped;
+    }
+    requestHasCachePoints(request) {
+        const inSystem = (request.system ?? []).some((block) => "cachePoint" in block);
+        const inTools = (request.toolConfig?.tools ?? []).some((tool) => "cachePoint" in tool);
+        return inSystem || inTools;
+    }
     formatTools(toolkit) {
         return toolkit.tools.map((tool) => ({
             name: tool.name,
@@ -2966,6 +3281,15 @@ class BedrockAdapter extends BaseProviderAdapter {
                 const fallbackRequest = this.toFallbackStructuredOutputRequest(bedrockRequest);
                 return (await bedrockClient.send(new ConverseCommand(fallbackRequest), signal ? { abortSignal: signal } : undefined));
             }
+            if (this.requestHasCachePoints(bedrockRequest) &&
+                isCachePointUnsupportedError(error)) {
+                this.rememberModelRejectsCachePoint(bedrockRequest.modelId || this.defaultModel);
+                const retryRequest = this.stripCachePoints(bedrockRequest);
+                const response = (await bedrockClient.send(new ConverseCommand(retryRequest), signal ? { abortSignal: signal } : undefined));
+                if (wantsStructuredOutput)
+                    response.__jaypieStructuredOutput = true;
+                return response;
+            }
             throw error;
         }
     }
@@ -3109,6 +3433,12 @@ class BedrockAdapter extends BaseProviderAdapter {
             reasoning: 0,
             total: usage?.totalTokens ??
                 (usage?.inputTokens ?? 0) + (usage?.outputTokens ?? 0),
+            ...(usage?.cacheReadInputTokens !== undefined
+                ? { cacheRead: usage.cacheReadInputTokens }
+                : {}),
+            ...(usage?.cacheWriteInputTokens !== undefined
+                ? { cacheWrite: usage.cacheWriteInputTokens }
+                : {}),
             provider: this.name,
             model,
         };
@@ -5280,6 +5610,13 @@ class OpenAiAdapter extends BaseProviderAdapter {
     supportsReasoningEffort(model) {
         return isReasoningModel(model);
     }
+    /**
+     * Whether to emit `prompt_cache_key` (OpenAI Responses API). Overridable by
+     * OpenAI-compatible subclasses whose backend rejects the field.
+     */
+    supportsPromptCacheKey() {
+        return true;
+    }
     /** Translate a normalized effort to this provider's `reasoning.effort` value. */
     mapReasoningEffort(effort, model) {
         return toOpenAiEffort(effort, { model });
@@ -5319,6 +5656,18 @@ class OpenAiAdapter extends BaseProviderAdapter {
                 summary: "auto",
             };
         }
+        // OpenAI prompt caching is automatic (prefix-based). Setting a stable
+        // prompt_cache_key routes repeat traffic to the same cache across
+        // instances. Keyed on the stable prefix only (system + instructions +
+        // tools + model), never the volatile user turn.
+        if (this.supportsPromptCacheKey() && resolveCache(request.cache).enabled) {
+            openaiRequest.prompt_cache_key = promptCacheKey(JSON.stringify([
+                model,
+                request.system ?? "",
+                request.instructions ?? "",
+                request.tools ?? [],
+            ]));
+        }
         if (request.providerOptions) {
             Object.assign(openaiRequest, request.providerOptions);
         }
@@ -5577,11 +5926,13 @@ class OpenAiAdapter extends BaseProviderAdapter {
                 model,
             };
         }
+        const cachedTokens = openaiResponse.usage.input_tokens_details?.cached_tokens;
         return {
             input: openaiResponse.usage.input_tokens || 0,
             output: openaiResponse.usage.output_tokens || 0,
             reasoning: openaiResponse.usage.output_tokens_details?.reasoning_tokens || 0,
             total: openaiResponse.usage.total_tokens || 0,
+            ...(cachedTokens !== undefined ? { cacheRead: cachedTokens } : {}),
             provider: this.name,
             model,
         };
@@ -5973,7 +6324,13 @@ class OpenRouterAdapter extends BaseProviderAdapter {
     //
     buildRequest(request) {
         // Convert messages to OpenRouter format (OpenAI-compatible)
-        const messages = this.convertMessagesToOpenRouter(request.messages, request.system);
+        const cache = resolveCache(request.cache);
+        const messages = this.convertMessagesToOpenRouter(request.messages, request.system, cache.enabled
+            ? {
+                type: "ephemeral",
+                ...(cache.ttl === "1h" ? { ttl: "1h" } : {}),
+            }
+            : undefined);
         // Append instructions to last message if provided
         if (request.instructions && messages.length > 0) {
             const lastMsg = messages[messages.length - 1];
@@ -6337,11 +6694,15 @@ class OpenRouterAdapter extends BaseProviderAdapter {
         }
         // SDK returns camelCase, but support snake_case as fallback
         const usage = openRouterResponse.usage;
+        const cachedTokens = usage.promptTokensDetails?.cachedTokens ??
+            usage.promptTokensDetails?.cached_tokens ??
+            usage.prompt_tokens_details?.cached_tokens;
         return {
             input: usage.promptTokens || usage.prompt_tokens || 0,
             output: usage.completionTokens || usage.completion_tokens || 0,
             reasoning: usage.completionTokensDetails?.reasoningTokens || 0,
             total: usage.totalTokens || usage.total_tokens || 0,
+            ...(cachedTokens !== undefined ? { cacheRead: cachedTokens } : {}),
             provider: this.name,
             model,
         };
@@ -6542,13 +6903,17 @@ class OpenRouterAdapter extends BaseProviderAdapter {
         const choice = response.choices[0];
         return choice?.message?.content ?? undefined;
     }
-    convertMessagesToOpenRouter(messages, system) {
+    convertMessagesToOpenRouter(messages, system, cacheControl) {
         const openRouterMessages = [];
-        // Add system message if provided
+        // Add system message if provided. A cache_control breakpoint on the system
+        // content is forwarded by OpenRouter to Anthropic/Gemini backends (and
+        // ignored by others), caching the stable system prefix.
         if (system) {
             openRouterMessages.push({
                 role: "system",
-                content: system,
+                content: cacheControl
+                    ? [{ type: "text", text: system, cache_control: cacheControl }]
+                    : system,
             });
         }
         for (const msg of messages) {
@@ -8074,10 +8439,14 @@ class OperateLoop {
         log.trace("[operate] Starting operate loop");
         log.trace.var({ "operate.input": input });
         log.trace.var({ "operate.options": options });
+        const startedAt = new Date().toISOString();
+        const startMs = Date.now();
         // Initialize state
         const state = await this.initializeState(input, options);
         const context = this.createContext(options);
         const modelName = options.model ?? this.adapter.defaultModel;
+        const exchangeRequested = isExchangeRequested(options);
+        const initialHistoryLength = state.responseBuilder.getHistory().length;
         await emitProgress({
             event: {
                 maxTurns: state.maxTurns,
@@ -8089,59 +8458,102 @@ class OperateLoop {
         });
         // Enclosing LLM Observability span (no-op when DD_LLMOBS_ENABLED is unset).
         // Child llm/tool spans nest under it via the SDK's active-span context.
-        return withLlmObsSpan({
-            kind: state.toolkit ? "agent" : "llm",
-            modelName,
-            modelProvider: this.adapter.name,
-            name: "jaypie.llm.operate",
-        }, async () => {
-            // Build initial request
-            let request = this.buildInitialRequest(state, options);
-            // Multi-turn loop
-            while (state.currentTurn < state.maxTurns) {
-                state.currentTurn++;
-                // Execute one turn with retry logic
-                const shouldContinue = await this.executeOneTurn(request, state, context, options);
-                if (!shouldContinue) {
-                    break;
+        try {
+            return await withLlmObsSpan({
+                kind: state.toolkit ? "agent" : "llm",
+                modelName,
+                modelProvider: this.adapter.name,
+                name: "jaypie.llm.operate",
+            }, async () => {
+                // Build initial request
+                let request = this.buildInitialRequest(state, options);
+                // Multi-turn loop
+                while (state.currentTurn < state.maxTurns) {
+                    state.currentTurn++;
+                    // Execute one turn with retry logic
+                    const shouldContinue = await this.executeOneTurn(request, state, context, options);
+                    if (!shouldContinue) {
+                        break;
+                    }
+                    // Rebuild request with updated history for next turn
+                    request = {
+                        effort: options.effort,
+                        format: state.formattedFormat,
+                        instructions: options.instructions,
+                        messages: state.currentInput,
+                        model: modelName,
+                        providerOptions: options.providerOptions,
+                        structuredOutputRetry: state.structuredOutputRetry,
+                        system: options.system,
+                        temperature: options.temperature,
+                        tools: state.formattedTools,
+                        user: options.user,
+                    };
                 }
-                // Rebuild request with updated history for next turn
-                request = {
-                    effort: options.effort,
-                    format: state.formattedFormat,
-                    instructions: options.instructions,
-                    messages: state.currentInput,
-                    model: modelName,
-                    providerOptions: options.providerOptions,
-                    structuredOutputRetry: state.structuredOutputRetry,
-                    system: options.system,
-                    temperature: options.temperature,
-                    tools: state.formattedTools,
-                    user: options.user,
-                };
-            }
-            const response = state.responseBuilder.build();
-            annotateLlmObs({
-                inputData: input,
-                metrics: usageToLlmObsMetrics(response.usage),
-                outputData: response.content,
-            });
-            tallyOperate({
-                toolCallNames: state.toolCallNames,
-                turns: state.currentTurn,
-                usage: response.usage,
-            });
-            await emitProgress({
-                event: {
-                    content: response.content,
-                    turn: state.currentTurn,
-                    type: LlmProgressEventType.Done,
+                const response = state.responseBuilder.build();
+                if (exchangeRequested) {
+                    response.exchange = buildExchangeEnvelope({
+                        duration: Date.now() - startMs,
+                        initialHistoryLength,
+                        input,
+                        options,
+                        response,
+                        startedAt,
+                        state,
+                    });
+                }
+                annotateLlmObs({
+                    inputData: input,
+                    metrics: usageToLlmObsMetrics(response.usage),
+                    outputData: response.content,
+                });
+                tallyOperate({
+                    toolCallNames: state.toolCallNames,
+                    turns: state.currentTurn,
                     usage: response.usage,
-                },
-                onProgress: options.onProgress,
+                });
+                await emitProgress({
+                    event: {
+                        content: response.content,
+                        turn: state.currentTurn,
+                        type: LlmProgressEventType.Done,
+                        usage: response.usage,
+                    },
+                    onProgress: options.onProgress,
+                });
+                return response;
             });
-            return response;
-        });
+        }
+        catch (error) {
+            // A hard failure (retry budget exhausted, unrecoverable) still settles
+            // the exchange: attach the envelope to the thrown error so the facade
+            // can emit it before rethrowing to the caller.
+            if (exchangeRequested) {
+                const response = state.responseBuilder.build();
+                if (!response.error) {
+                    const thrown = error;
+                    response.error = {
+                        detail: thrown.detail ?? thrown.message,
+                        status: thrown.status ?? 500,
+                        title: thrown.title ?? thrown.name ?? "Error",
+                    };
+                }
+                if (response.status === LlmResponseStatus.InProgress) {
+                    response.status = LlmResponseStatus.Incomplete;
+                }
+                error.exchange =
+                    buildExchangeEnvelope({
+                        duration: Date.now() - startMs,
+                        initialHistoryLength,
+                        input,
+                        options,
+                        response,
+                        startedAt,
+                        state,
+                    });
+            }
+            throw error;
+        }
     }
     //
     // Private Methods
@@ -8200,6 +8612,7 @@ class OperateLoop {
             formattedTools,
             maxTurns,
             responseBuilder,
+            retries: 0,
             toolCallNames: [],
             toolkit,
         };
@@ -8212,6 +8625,7 @@ class OperateLoop {
     }
     buildInitialRequest(state, options) {
         return {
+            cache: options.cache,
             effort: options.effort,
             format: state.formattedFormat,
             instructions: options.instructions,
@@ -8261,26 +8675,26 @@ class OperateLoop {
             options,
             providerRequest,
         });
-        // Emit retry progress alongside the caller's onRetryableModelError hook
+        // Count retries for the exchange envelope and emit retry progress
+        // alongside the caller's onRetryableModelError hook
         const hooks = context.hooks;
-        const hooksWithProgress = options.onProgress
-            ? {
-                ...hooks,
-                onRetryableModelError: async (retryContext) => {
-                    await emitProgress({
-                        event: {
-                            error: retryContext.error instanceof Error
-                                ? retryContext.error.message
-                                : String(retryContext.error),
-                            turn: state.currentTurn,
-                            type: LlmProgressEventType.Retry,
-                        },
-                        onProgress: options.onProgress,
-                    });
-                    return hooks?.onRetryableModelError?.(retryContext);
-                },
-            }
-            : hooks;
+        const hooksWithProgress = {
+            ...hooks,
+            onRetryableModelError: async (retryContext) => {
+                state.retries++;
+                await emitProgress({
+                    event: {
+                        error: retryContext.error instanceof Error
+                            ? retryContext.error.message
+                            : String(retryContext.error),
+                        turn: state.currentTurn,
+                        type: LlmProgressEventType.Retry,
+                    },
+                    onProgress: options.onProgress,
+                });
+                return hooks?.onRetryableModelError?.(retryContext);
+            },
+        };
         // Execute with retry inside a child llm span (no-op when llmobs disabled).
         // RetryExecutor handles error hooks and throws appropriate errors.
         const { parsed, response, toolCalls } = await withLlmObsSpan({
@@ -8339,6 +8753,10 @@ class OperateLoop {
         if (parsed.usage) {
             state.responseBuilder.addUsage(parsed.usage);
         }
+        // Track stop reason for the exchange envelope
+        if (parsed.stopReason) {
+            state.lastStopReason = parsed.stopReason;
+        }
         // Add raw response
         state.responseBuilder.addResponse(parsed.raw);
         // Execute afterEachModelResponse hook
@@ -8841,6 +9259,7 @@ class StreamLoop {
     }
     buildInitialRequest(state, options) {
         return {
+            cache: options.cache,
             effort: options.effort,
             format: state.formattedFormat,
             instructions: options.instructions,
@@ -10841,12 +11260,17 @@ class Llm {
         attempts++;
         try {
             const response = await this._llm.operate(input, optionsWithoutFallback);
-            return {
+            const settled = {
                 ...response,
                 fallbackAttempts: attempts,
                 fallbackUsed: false,
                 provider: response.provider || this._provider,
             };
+            await this.settleExchange({
+                onExchange: resolvedOptions.onExchange,
+                response: settled,
+            });
+            return settled;
         }
         catch (error) {
             lastError = error;
@@ -10855,18 +11279,28 @@ class Llm {
                 fallbacksRemaining: fallbackChain.length,
             });
         }
-        // Try fallback providers
+        // Try fallback providers. The fallback instance's underlying provider is
+        // called directly so the nested facade does not settle the exchange —
+        // exactly one settlement per operate() happens here.
         for (const fallbackConfig of fallbackChain) {
             attempts++;
             try {
                 const fallbackInstance = this.createFallbackInstance(fallbackConfig);
-                const response = await fallbackInstance.operate(input, optionsWithoutFallback);
-                return {
+                if (!fallbackInstance._llm.operate) {
+                    throw new NotImplementedError(`Provider ${fallbackConfig.provider} does not support operate method`);
+                }
+                const response = await fallbackInstance._llm.operate(input, optionsWithoutFallback);
+                const settled = {
                     ...response,
                     fallbackAttempts: attempts,
                     fallbackUsed: true,
                     provider: response.provider || fallbackConfig.provider,
                 };
+                await this.settleExchange({
+                    onExchange: resolvedOptions.onExchange,
+                    response: settled,
+                });
+                return settled;
             }
             catch (error) {
                 lastError = error;
@@ -10876,9 +11310,44 @@ class Llm {
                 });
             }
         }
-        // All providers failed, throw the last error
+        // All providers failed: settle the exchange from the envelope the loop
+        // attached to the last error, then throw
+        const failureEnvelope = lastError
+            ?.exchange;
+        if (failureEnvelope) {
+            failureEnvelope.resolution = {
+                ...failureEnvelope.resolution,
+                fallbackAttempts: attempts,
+                fallbackUsed: attempts > 1,
+            };
+            await emitExchange({
+                envelope: failureEnvelope,
+                onExchange: resolvedOptions.onExchange,
+            });
+            await persistExchange(failureEnvelope);
+        }
         throw lastError;
     }
+    /**
+     * Stamp fallback resolution onto the envelope the operate loop attached to
+     * the response and deliver it to the caller's onExchange. Fires once per
+     * operate() settlement; callback errors are logged and never thrown.
+     */
+    async settleExchange({ onExchange, response, }) {
+        const envelope = response.exchange;
+        if (!envelope) {
+            return;
+        }
+        envelope.resolution = {
+            ...envelope.resolution,
+            fallbackAttempts: response.fallbackAttempts,
+            fallbackUsed: response.fallbackUsed,
+            model: response.model,
+            provider: response.provider,
+        };
+        await emitExchange({ envelope, onExchange });
+        await persistExchange(envelope);
+    }
     async *stream(input, options = {}) {
         if (!this._llm.stream) {
             throw new NotImplementedError(`Provider ${this._provider} does not support stream method`);