@jaypie/llm 1.3.13 → 1.3.14

package/dist/esm/index.js

@@ -475,233 +475,90 @@ 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;
     }
-}
-
-/**
- * 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));
-}
-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" };
-    }
-    // `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" };
+    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;
     }
-    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];
+    return totals;
 }
-// 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];
+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;
 }
-// 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] };
-}
-
-// 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
+// Main
 //
-var LlmStreamChunkType;
-(function (LlmStreamChunkType) {
-    LlmStreamChunkType["Done"] = "done";
-    LlmStreamChunkType["Error"] = "error";
-    LlmStreamChunkType["Text"] = "text";
-    LlmStreamChunkType["ToolCall"] = "tool_call";
-    LlmStreamChunkType["ToolResult"] = "tool_result";
-})(LlmStreamChunkType || (LlmStreamChunkType = {}));
+/**
+ * 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.
+ */
+function buildExchangeEnvelope({ duration, initialHistoryLength, input, options, response, startedAt, state, }) {
+    const historyDelta = response.history.slice(initialHistoryLength);
+    return {
+        ids: extractResponseIds(response.responses),
+        request: {
+            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,
+        },
+    };
+}
 
 /**
  * Type guard to check if an item is a dedicated reasoning item (OpenAI)
@@ -921,6 +778,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
@@ -1518,61 +1414,357 @@ function tallyOperate({ toolCallNames = [], turns, usage = [], }) {
         }
         llm.usage = usageByModel;
     }
-    log$2.tally({ llm });
+    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
+    }
+}
+/**
+ * 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
+//
+// CJS/ESM compatible require - handles bundling to CJS where import.meta.url
+// becomes undefined (mirrors observability/llmobs.ts).
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore - __filename exists in CJS context when ESM is bundled to CJS
+const requireModule$1 = typeof __filename !== "undefined"
+    ? createRequire(pathToFileURL(__filename).href)
+    : createRequire(import.meta.url);
+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.
+ */
+function resolveExchangeStore() {
+    if (resolved$1) {
+        return cachedSdk$2;
+    }
+    resolved$1 = true;
+    try {
+        const dynamodb = requireModule$1(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 = 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;
+    }
 }
 
 /**
- * Helper function to safely call a function that might throw
- * @param fn Function to call safely
+ * 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.
  */
-function callSafely(fn) {
-    try {
-        fn();
-    }
-    catch {
-        // Silently catch any errors from the function
-    }
+/** 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}'`;
 }
-/**
- * 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;
+// 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 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
@@ -8074,10 +8266,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 +8285,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 +8439,7 @@ class OperateLoop {
             formattedTools,
             maxTurns,
             responseBuilder,
+            retries: 0,
             toolCallNames: [],
             toolkit,
         };
@@ -8261,26 +8501,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 +8579,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
@@ -10841,12 +11085,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 +11104,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 +11135,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`);