@stackfactor/agent-utils 1.4.3 → 1.8.0

package/dist/esm/langChain.js

@@ -10,6 +10,7 @@ import logger from "./logger.js";
 import { z } from "zod";
 import { transformJSONSchema } from "@anthropic-ai/sdk/lib/transform-json-schema";
 import { getAbortSignal } from "./runtimeContext.js";
+import { recordUsage } from "./usage.js";
 import { assertTavilyUsable, buildTavilyTools, getTavilyOptions, } from "./tavily.js";
 const JSON_ESCAPE_INSTRUCTION = `
 CRITICAL - Your response must be valid JSON. Escape ALL special characters in string values:
@@ -98,29 +99,36 @@ const checkIfAIProviderConfigured = (config) => {
     }
 };
 /**
- * Reads a per-model rate from the flat cost constants the integration defines
- * in its `config.yaml` (exposed on the config object), e.g.
- * `claude-opus-4-7-input-token-costs`. Returns `0` when the constant is
- * absent or not numeric, which leaves cost contribution zero.
+ * Counts `amount` of `unit` for `modelName`: into the request's usage ledger,
+ * which is reported to the platform, and into the caller's tracker when it
+ * passed one. Nothing is counted for an amount that is not positive.
  */
-const getModelRate = (modelName, config, kind) => {
-    if (!config || !modelName)
-        return 0;
-    const rate = Number(config[`${modelName}-${kind}-costs`]);
-    return Number.isFinite(rate) ? rate : 0;
+const countUsage = (tracker, modelName, unit, amount) => {
+    if (!Number.isFinite(amount) || amount <= 0)
+        return;
+    recordUsage(modelName, unit, amount);
+    if (!tracker)
+        return;
+    const key = `${modelName}_${unit}`;
+    tracker.tokens[key] = (tracker.tokens[key] || 0) + amount;
 };
-/**
- * Adds a single call's usage to the caller-supplied tracker. Initializes
- * `cost` and `tokens` lazily so callers can pass `{}`. No-ops when the
- * tracker is null/undefined.
- */
-const updateUsageTracker = (tracker, modelName, usage, config) => {
-    if (!tracker || !usage || !modelName)
+/** Makes `{}` a tracker. `cost` stays 0: the platform prices what was used. */
+const prepareTracker = (tracker) => {
+    if (!tracker)
         return;
     if (typeof tracker.cost !== "number")
         tracker.cost = 0;
     if (!tracker.tokens || typeof tracker.tokens !== "object")
         tracker.tokens = {};
+};
+/**
+ * Counts a single call's token usage. `config` is no longer read: it carried
+ * the rates, and what usage costs is the platform's to say.
+ */
+const updateUsageTracker = (tracker, modelName, usage, _config) => {
+    if (!usage || !modelName)
+        return;
+    prepareTracker(tracker);
     const inputTokens = usage.input_tokens || 0;
     const visibleOutputTokens = usage.output_tokens || 0;
     const totalTokens = usage.total_tokens || 0;
@@ -129,40 +137,24 @@ const updateUsageTracker = (tracker, modelName, usage, config) => {
     // `total - input - visibleOutput` is the thinking output the caller was still
     // billed for. Providers that already fold reasoning into `output_tokens`
     // (Anthropic, OpenAI) report `total == input + output`, so this adds 0.
-    // Reasoning is charged at the output rate, so we treat it as output for both
-    // the token counters and the cost.
+    // Reasoning is charged at the output rate, so it is counted as output.
     const reasoningTokens = totalTokens > 0
         ? Math.max(0, totalTokens - inputTokens - visibleOutputTokens)
         : 0;
-    const outputTokens = visibleOutputTokens + reasoningTokens;
-    const inputRate = getModelRate(modelName, config, "input-token");
-    const outputRate = getModelRate(modelName, config, "output-token");
-    const addedCost = (inputTokens / 1_000_000) * inputRate +
-        (outputTokens / 1_000_000) * outputRate;
-    if (Number.isFinite(addedCost) && addedCost > 0)
-        tracker.cost += addedCost;
-    const inputKey = `${modelName}_inputTokens`;
-    const outputKey = `${modelName}_outputTokens`;
-    tracker.tokens[inputKey] = (tracker.tokens[inputKey] || 0) + inputTokens;
-    tracker.tokens[outputKey] = (tracker.tokens[outputKey] || 0) + outputTokens;
+    countUsage(tracker, modelName, "inputTokens", inputTokens);
+    countUsage(tracker, modelName, "outputTokens", visibleOutputTokens + reasoningTokens);
 };
 /**
- * Adds a single image-generation call's usage to the caller-supplied tracker.
- * Extracts token counts from provider-specific response shapes: OpenAI returns
- * `response.usage` with `input_tokens_details.{text_tokens,image_tokens}` and
- * `output_tokens`; Google returns `response.usageMetadata` with
- * `promptTokensDetails` (modality-keyed) and `candidatesTokenCount` for the
- * generated image. Reads rates from `<model>-input-token-costs`,
- * `<model>-image-input-token-costs`, and `<model>-image-output-token-costs`.
- * No-ops when the tracker or response usage info is absent.
+ * Counts a single image-generation call's usage. Extracts token counts from
+ * provider-specific response shapes: OpenAI returns `response.usage` with
+ * `input_tokens_details.{text_tokens,image_tokens}` and `output_tokens`;
+ * Google returns `response.usageMetadata` with `promptTokensDetails`
+ * (modality-keyed) and `candidatesTokenCount` for the generated image.
+ * No-ops when the response carries no usage.
  */
-const updateImageUsageTracker = (tracker, modelName, response, config, provider) => {
-    if (!tracker || !modelName || !response)
+const updateImageUsageTracker = (tracker, modelName, response, _config, provider) => {
+    if (!modelName || !response)
         return;
-    if (typeof tracker.cost !== "number")
-        tracker.cost = 0;
-    if (!tracker.tokens || typeof tracker.tokens !== "object")
-        tracker.tokens = {};
     let textInputTokens = 0;
     let imageInputTokens = 0;
     let imageOutputTokens = 0;
@@ -199,85 +191,42 @@ const updateImageUsageTracker = (tracker, modelName, response, config, provider)
         }
         imageOutputTokens = Number(um.candidatesTokenCount) || 0;
     }
-    const textInputRate = getModelRate(modelName, config, "input-token");
-    // Reference-image input tokens are billed at the model's input rate. Configs
-    // that don't define a dedicated `<model>-image-input-token-costs` (the common
-    // case — image models charge all input at one rate and only differ on output)
-    // fall back to the text input rate rather than silently billing image input
-    // at $0.
-    const imageInputRate = getModelRate(modelName, config, "image-input-token") || textInputRate;
-    const imageOutputRate = getModelRate(modelName, config, "image-output-token");
-    const addedCost = (textInputTokens / 1_000_000) * textInputRate +
-        (imageInputTokens / 1_000_000) * imageInputRate +
-        (imageOutputTokens / 1_000_000) * imageOutputRate;
-    if (Number.isFinite(addedCost) && addedCost > 0)
-        tracker.cost += addedCost;
-    if (textInputTokens > 0) {
-        const key = `${modelName}_inputTokens`;
-        tracker.tokens[key] = (tracker.tokens[key] || 0) + textInputTokens;
-    }
-    if (imageInputTokens > 0) {
-        const key = `${modelName}_imageInputTokens`;
-        tracker.tokens[key] = (tracker.tokens[key] || 0) + imageInputTokens;
-    }
-    if (imageOutputTokens > 0) {
-        const key = `${modelName}_imageOutputTokens`;
-        tracker.tokens[key] = (tracker.tokens[key] || 0) + imageOutputTokens;
-    }
+    prepareTracker(tracker);
+    countUsage(tracker, modelName, "inputTokens", textInputTokens);
+    // The platform prices an image a model is given as its other input, unless
+    // the model has a rate of its own for it.
+    countUsage(tracker, modelName, "imageInputTokens", imageInputTokens);
+    countUsage(tracker, modelName, "imageOutputTokens", imageOutputTokens);
 };
 /**
- * Adds character-billed usage (e.g. ElevenLabs TTS) to the caller-supplied
- * tracker. There is no provider response to parse — billing is deterministic
- * from the input character count. Reads the rate from
- * `<model>-character-costs` (USD per million characters) and accumulates
- * under `<model>_characters`. No-ops on missing tracker / model / count.
+ * Counts character-billed usage (e.g. ElevenLabs TTS). There is no provider
+ * response to parse — billing is deterministic from the input character
+ * count. No-ops on a missing model or count.
  */
-const updateUsageTrackerForCharacters = (tracker, modelName, characterCount, config) => {
-    if (!tracker || !modelName || !characterCount)
+const updateUsageTrackerForCharacters = (tracker, modelName, characterCount, _config) => {
+    if (!modelName || !characterCount)
         return;
-    if (typeof tracker.cost !== "number")
-        tracker.cost = 0;
-    if (!tracker.tokens || typeof tracker.tokens !== "object")
-        tracker.tokens = {};
-    const rate = getModelRate(modelName, config, "character");
-    const addedCost = (characterCount / 1_000_000) * rate;
-    if (Number.isFinite(addedCost) && addedCost > 0)
-        tracker.cost += addedCost;
-    const key = `${modelName}_characters`;
-    tracker.tokens[key] = (tracker.tokens[key] || 0) + characterCount;
+    prepareTracker(tracker);
+    countUsage(tracker, modelName, "characters", characterCount);
 };
 /**
- * Adds second-billed usage (video generation) to the caller-supplied tracker.
- *
- * Video is the first output here that providers bill by DURATION rather than by
- * tokens or characters, so the rate constant `<model>-second-costs` is read as
- * USD PER SECOND — not per million, as the `input-token` and `character` rates
- * are. A Veo or Sora second costs cents, and a per-million reading would bill
- * it as effectively free.
+ * Counts second-billed usage (video generation): providers bill video by
+ * DURATION rather than by tokens or characters.
  *
- * The rate is per model, not per model-and-resolution, so a caller that lets a
- * tenant change resolution on a model whose price varies by it (sora-2-pro is
- * $0.30/$0.50/$0.70 at 720p/1024p/1080p) must pin the resolution its constant
- * describes, or it will bill the wrong number.
+ * The platform's rate is per model, not per model-and-resolution, so a caller
+ * that lets a tenant change resolution on a model whose price varies by it
+ * (sora-2-pro is $0.30/$0.50/$0.70 at 720p/1024p/1080p) must pin the
+ * resolution the rate describes, or the wrong number is charged.
  *
- * @param tracker - The accumulator to add to; no-ops when null
- * @param modelName - The video model id, used for both the rate and the counter key
+ * @param tracker - The caller's accumulator, when it passed one
+ * @param modelName - The video model id
  * @param seconds - Billed duration of the generated clip
- * @param config - Integration config carrying `<model>-second-costs`
  */
-const updateVideoUsageTracker = (tracker, modelName, seconds, config) => {
-    if (!tracker || !modelName || !seconds)
+const updateVideoUsageTracker = (tracker, modelName, seconds, _config) => {
+    if (!modelName || !seconds)
         return;
-    if (typeof tracker.cost !== "number")
-        tracker.cost = 0;
-    if (!tracker.tokens || typeof tracker.tokens !== "object")
-        tracker.tokens = {};
-    const rate = getModelRate(modelName, config, "second");
-    const addedCost = seconds * rate;
-    if (Number.isFinite(addedCost) && addedCost > 0)
-        tracker.cost += addedCost;
-    const key = `${modelName}_seconds`;
-    tracker.tokens[key] = (tracker.tokens[key] || 0) + seconds;
+    prepareTracker(tracker);
+    countUsage(tracker, modelName, "seconds", seconds);
 };
 /**
  * Extracts a normalized token-usage object from a single LangChain `invoke()`
@@ -378,8 +327,14 @@ const formatZodErrors = (zodError) => {
                 const path = err.path.length > 0 ? err.path.join(".") : "root";
                 // Provide more context based on error type
                 switch (err.code) {
-                    case "invalid_type":
-                        return `Field "${path}": Expected ${err.expected}, but received ${err.received}`;
+                    case "invalid_type": {
+                        // zod v3 sets `received`; zod v4 names it only in the message
+                        // ("Invalid input: expected string, received number").
+                        const received = err.received ??
+                            /received (\w+)/.exec(String(err.message ?? ""))?.[1] ??
+                            "a different type";
+                        return `Field "${path}": Expected ${err.expected}, but received ${received}`;
+                    }
                     case "invalid_literal":
                         return `Field "${path}": Expected literal value ${JSON.stringify(err.expected)}, but received ${JSON.stringify(err.received)}`;
                     case "unrecognized_keys":
@@ -815,19 +770,30 @@ const createAgent = (name, modelName, systemPrompt, tools = [], responseFormat,
  * @param onProgress - Optional callback invoked with progress event objects throughout
  *   agent execution
  * @param usageTracker - Optional usage accumulator updated on successful completion
+ * @param progress - The percentage every progress event reports (the stage's
+ *   current one; the agent loop has no percentage of its own). Defaults to 0.
  * @returns The raw response object returned by the agent's `invoke` method
  */
-const runAgent = async (agent, prompt, config, onProgress = null, usageTracker = null) => {
+const runAgent = async (agent, prompt, config, onProgress = null, usageTracker = null, progress = 0) => {
     const startTime = Date.now();
+    // Every event carries `progress`: callers forward these to the platform's
+    // `{ progress, message }` progress bar, where a missing value would read as
+    // 0% and make the bar jump back during a tool call. The agent loop reports
+    // no percentage of its own, so the stage's current one is repeated.
     const callbacks = onProgress
         ? [
             {
-                handleToolStart: (toolInfo) => {
-                    if (toolInfo.name)
+                // LangChain calls handleToolStart(serializedTool, input, runId,
+                // parentRunId, tags, metadata, runName): the serialized tool
+                // ({ lc, type, id }) has no name; the tool's name is runName.
+                handleToolStart: (toolInfo, _input, _runId, _parentRunId, _tags, _metadata, runName) => {
+                    const name = runName || toolInfo?.name || toolInfo?.kwargs?.name;
+                    if (name)
                         onProgress({
                             type: "tool_start",
-                            message: `Using "${toolInfo.name}" tool`,
-                            tool: toolInfo.name,
+                            message: `Using "${name}" tool`,
+                            tool: name,
+                            progress,
                         });
                 },
                 handleAgentAction: (action) => {
@@ -836,12 +802,14 @@ const runAgent = async (agent, prompt, config, onProgress = null, usageTracker =
                         message: action.log || `Calling "${action.tool}" action`,
                         tool: action.tool,
                         input: action.toolInput,
+                        progress,
                     });
                 },
                 handleChainError: (err) => {
                     onProgress({
                         type: "error",
                         message: `Error: ${err?.message || String(err)}`,
+                        progress,
                     });
                 },
             },
@@ -1093,6 +1061,65 @@ const parseAndValidateJSONResponse = (rawContent, schema) => {
  * original base) so that across multiple retries the full failure history
  * accumulates and the model can avoid oscillating between previous broken outputs.
  */
+/**
+ * Whether a response that fails schema validation is retried with the errors
+ * appended (buildValidationRetryMessages), up to MAX_VALIDATION_RETRIES.
+ *
+ * This used to be skipped whenever the model supports native structured
+ * output, on the reasoning that a natively constrained response cannot be
+ * invalid, so a failure had to be a schema bug worth surfacing at once. It
+ * can be invalid, and routinely is: constrained decoding enforces the JSON
+ * *shape*, not the Zod schema. Anthropic's SDK strips `enum` into a
+ * description before sending, Gemini ignores `additionalProperties`, and no
+ * provider runs a refine or a superRefine. Production, 2026-09-23/24: one
+ * agent failed one call in six on extra keys the strict schema refused, and
+ * another was rejected three runs in a row at its last stage on a value off
+ * an enumerated list — every one on a native-schema model, every one reported
+ * straight to the user, and every one restarted from zero by the caller
+ * because the stage that failed was never asked again.
+ *
+ * So the retry now applies whenever a schema is in play. A genuine schema bug
+ * still surfaces: it fails the same way three times and the last error is
+ * thrown as before, at the cost of two extra calls.
+ * @param expectsJsonResponse - Whether the call expects JSON at all
+ * @param schema - The Zod schema the response is validated against, if any
+ * @returns Whether a validation failure is retried
+ */
+const canRetryValidation = (expectsJsonResponse, schema) => !!expectsJsonResponse && !!schema;
+/**
+ * Whether a failure of the JSON stage is one the model can fix if asked again:
+ * a response that failed schema validation, or one that was not JSON at all
+ * (prose, or JSON with a preamble the extractor could not recover). Everything
+ * else — no messages, a provider error, a transport error — is not.
+ * @param error - The failure
+ * @returns Whether a retry with the errors appended makes sense
+ */
+const isRetryableJsonFailure = (error) => error?.code === constants.HTTP_CODES.UNPROCESSABLE_ENTITY ||
+    /non-JSON response when JSON was expected/.test(String(error?.message ?? ""));
+/**
+ * The agentic run takes one user prompt rather than a message list, so a retry
+ * carries the failed output and the errors inside that prompt: the model sees
+ * what it produced and what was wrong with it, the same information
+ * buildValidationRetryMessages gives the non-agentic paths. Previous attempts
+ * accumulate so the model does not oscillate between earlier broken outputs.
+ * @param userPrompt - The prompt of the attempt that failed
+ * @param rawContent - What the model answered
+ * @param error - Why it was refused
+ * @returns The user prompt for the next attempt
+ */
+const buildAgenticRetryPrompt = (userPrompt, rawContent, error) => {
+    const previous = typeof rawContent === "string" ? rawContent : JSON.stringify(rawContent);
+    return `${userPrompt}
+
+---
+Your previous response was rejected:
+${String(error?.message ?? error)}
+
+Your previous response was:
+${previous}
+
+Return a corrected JSON response that fixes ALL of these issues. Respond with the JSON only.`;
+};
 const buildValidationRetryMessages = (priorMessages, rawContent, validationError) => {
     const assistantContent = typeof rawContent === "string" ? rawContent : JSON.stringify(rawContent);
     return [
@@ -1104,6 +1131,58 @@ const buildValidationRetryMessages = (priorMessages, rawContent, validationError
         },
     ];
 };
+/**
+ * The agentic path's JSON stage: the agent's final text as validated JSON.
+ * Direct parse when it looks like JSON, the markdown/preamble extractor
+ * otherwise; a schema failure throws UNPROCESSABLE_ENTITY (validateWithSchema),
+ * anything the extractor cannot recover throws the "non-JSON response" error.
+ * Both are what runPromptWithModel's agentic retry loop asks the model to fix.
+ * @param rawContent - The agent's final message text
+ * @param schema - The Zod schema to validate against, if any
+ * @returns The JSON, re-serialised
+ */
+const parseAgenticJsonResponse = (rawContent, schema) => {
+    if (typeof rawContent === "string") {
+        const trimmed = rawContent.trim();
+        if ((trimmed.startsWith("{") && trimmed.endsWith("}")) ||
+            (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (schema) {
+                    validateWithSchema(parsed, schema);
+                }
+                return JSON.stringify(parsed);
+            }
+            catch (parseError) {
+                if (parseError?.code === constants.HTTP_CODES.UNPROCESSABLE_ENTITY) {
+                    throw parseError;
+                }
+            }
+        }
+        // Try to extract JSON from markdown or other wrapping
+        const extracted = extractJSONFromResponse(rawContent);
+        if (extracted) {
+            if (schema) {
+                validateWithSchema(extracted, schema);
+            }
+            return JSON.stringify(extracted);
+        }
+    }
+    let preview = "";
+    if (typeof rawContent === "string") {
+        preview = rawContent.substring(0, 100);
+    }
+    else if (typeof rawContent === "object" && rawContent !== null) {
+        preview = JSON.stringify(rawContent).substring(0, 100);
+    }
+    else if (rawContent !== undefined && rawContent !== null) {
+        preview = String(rawContent).substring(0, 100);
+    }
+    else {
+        preview = "[empty response]";
+    }
+    throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, `Agent returned non-JSON response when JSON was expected: ${preview}...`);
+};
 /**
  * Sends a prompt to an LLM and returns the response, with support for streaming,
  * agentic execution, progress reporting, JSON extraction, and Zod schema validation.
@@ -1186,65 +1265,43 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         // being reconciled from the response afterwards.
         const agent = createAgent(agentName, modelName, systemPrompt, [...tools], null, // responseFormat
         config, usageTracker);
-        // Run the agent with progress callback
-        const response = await runAgent(agent, userPrompt, config, onProgressReport || null, usageTracker);
-        // Extract content from agent response
-        const messages = response?.messages || [];
-        if (messages.length === 0) {
-            throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, "Agent returned no messages");
-        }
-        const lastMessage = messages[messages.length - 1];
-        // Flattens the array content blocks that Gemini/Claude agent responses and
-        // any server-tool turn (e.g. web search) return.
-        const rawContent = extractTextContent(lastMessage?.content);
-        // If not expecting JSON, return raw content directly
-        if (!expectsJsonResponse) {
-            return rawContent;
-        }
-        // Process JSON response similar to non-agentic path
-        if (typeof rawContent === "string") {
-            const trimmed = rawContent.trim();
-            if ((trimmed.startsWith("{") && trimmed.endsWith("}")) ||
-                (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
-                try {
-                    const parsed = JSON.parse(trimmed);
-                    if (schema) {
-                        validateWithSchema(parsed, schema);
-                    }
-                    return JSON.stringify(parsed);
-                }
-                catch (parseError) {
-                    if (parseError?.code === constants.HTTP_CODES.UNPROCESSABLE_ENTITY) {
-                        throw parseError;
-                    }
-                }
-            }
-            // Try to extract JSON from markdown or other wrapping
-            const extracted = extractJSONFromResponse(rawContent);
-            if (extracted) {
-                if (schema) {
-                    validateWithSchema(extracted, schema);
-                }
-                return JSON.stringify(extracted);
-            }
-        }
-        if (expectsJsonResponse) {
-            let preview = "";
-            if (typeof rawContent === "string") {
-                preview = rawContent.substring(0, 100);
+        // The JSON stage is retried like the non-agentic paths (canRetryValidation):
+        // the agent is run again with its rejected output and the errors appended
+        // to the user prompt, up to MAX_VALIDATION_RETRIES. Until now this path
+        // had no retry at all, and it is the one every tool-using generation takes.
+        let activeUserPrompt = userPrompt;
+        let attempt = 0;
+        for (;;) {
+            // Run the agent with progress callback
+            const response = await runAgent(agent, activeUserPrompt, config, onProgressReport || null, usageTracker, minPercent);
+            // Extract content from agent response
+            const messages = response?.messages || [];
+            if (messages.length === 0) {
+                throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, "Agent returned no messages");
             }
-            else if (typeof rawContent === "object" && rawContent !== null) {
-                preview = JSON.stringify(rawContent).substring(0, 100);
+            const lastMessage = messages[messages.length - 1];
+            // Flattens the array content blocks that Gemini/Claude agent responses and
+            // any server-tool turn (e.g. web search) return.
+            const rawContent = extractTextContent(lastMessage?.content);
+            // If not expecting JSON, return raw content directly
+            if (!expectsJsonResponse) {
+                return rawContent;
             }
-            else if (rawContent !== undefined && rawContent !== null) {
-                preview = String(rawContent).substring(0, 100);
+            try {
+                return parseAgenticJsonResponse(rawContent, schema);
             }
-            else {
-                preview = "[empty response]";
+            catch (err) {
+                if (canRetryValidation(expectsJsonResponse, schema) &&
+                    isRetryableJsonFailure(err) &&
+                    attempt < MAX_VALIDATION_RETRIES) {
+                    attempt++;
+                    logger.log(null, logger.levels.warn, `Schema validation failed for "${modelName}", retrying (${attempt}/${MAX_VALIDATION_RETRIES}): ${err.message}`);
+                    activeUserPrompt = buildAgenticRetryPrompt(activeUserPrompt, rawContent, err);
+                    continue;
+                }
+                throw err;
             }
-            throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, `Agent returned non-JSON response when JSON was expected: ${preview}...`);
         }
-        return rawContent;
     }
     let messages;
     if (typeof prompt === "string") {
@@ -1289,13 +1346,13 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         else {
             messagesToSend = messages;
         }
-        // Retry once on schema validation failure. The retry is silent to the progress
+        // Retry on schema validation failure. The retry is silent to the progress
         // callback — same "Generating content..." message and the progress curve
         // continues from the original startTime so the bar doesn't visibly reset.
-        // Skipped when OpenAI native response_format is in use (a 422 there is a
-        // server-side schema bug, not a model output issue). Each attempt accumulates
-        // independently into usageTracker so retry usage is still visible.
-        const canRetryOnValidation = expectsJsonResponse && !!schema && !useNativeSchema;
+        // Each attempt accumulates independently into usageTracker so retry usage
+        // is still visible. Native structured output no longer exempts a model:
+        // see canRetryValidation.
+        const canRetryOnValidation = canRetryValidation(expectsJsonResponse, schema);
         const progressReportInterval = 10; // Report every N chunks
         const overallStartTime = Date.now();
         // Use a time-based asymptotic curve: progress approaches maxPercent but never
@@ -1447,9 +1504,9 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         else {
             messagesToSend = messages;
         }
-        // Retry once on schema validation failure (see streaming branch for rationale).
+        // Retry on schema validation failure (see streaming branch for rationale).
         // Each attempt accumulates independently into usageTracker.
-        const canRetryOnValidation = expectsJsonResponse && !!schema && !useNativeSchema;
+        const canRetryOnValidation = canRetryValidation(expectsJsonResponse, schema);
         let activeMessages = messagesToSend;
         let attempt = 0;
         while (true) {
@@ -1958,6 +2015,11 @@ const runPromptWithModelForVideoGeneration = async (modelName, config, prompt, o
     }
 };
 export default {
+    canRetryValidation,
+    isRetryableJsonFailure,
+    buildAgenticRetryPrompt,
+    parseAgenticJsonResponse,
+    supportsNativeSchema,
     checkIfAIProviderConfigured,
     createAgent,
     runAgent,
@@ -1965,6 +2027,9 @@ export default {
     runPromptWithModelForImageGeneration,
     runPromptWithModelForVideoGeneration,
     throwErrorIfNotSuccessful,
+    updateImageUsageTracker,
+    updateUsageTracker,
     updateUsageTrackerForCharacters,
+    updateVideoUsageTracker,
     validateModel,
 };

package/dist/esm/runtimeContext.d.ts

@@ -1,3 +1,4 @@
+import type { UsageLedger } from "./usage.js";
 /**
  * Per-request execution context for an agent invocation.
  *
@@ -25,6 +26,8 @@ export interface RequestContext {
         user: any;
         tenant: any;
     } | null;
+    /** What the request used and has not reported to the platform yet (see usage). */
+    usage?: UsageLedger;
 }
 /** Run `fn` with `ctx` bound as the active request context. */
 export declare const runWithContext: <T>(ctx: RequestContext, fn: () => Promise<T>) => Promise<T>;

package/dist/esm/runtimeContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtimeContext.d.ts","sourceRoot":"","sources":["../../src/runtimeContext.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,GAAG,CAAC;IACZ,MAAM,EAAE,GAAG,CAAC;IACZ,OAAO,EAAE,GAAG,CAAC;IACb,KAAK,EAAE,GAAG,CAAC;IACX,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7E,0EAA0E;IAC1E,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,4EAA4E;IAC5E,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,GAAG,CAAC;QAAC,MAAM,EAAE,GAAG,CAAA;KAAE,GAAG,IAAI,CAAC;CAC7C;AAID,+DAA+D;AAC/D,eAAO,MAAM,cAAc,GAAI,CAAC,EAC9B,KAAK,cAAc,EACnB,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAyB,CAAC;AAEtC,oEAAoE;AACpE,eAAO,MAAM,UAAU,QAAO,cAAc,GAAG,SAA+B,CAAC;AAE/E,oDAAoD;AACpD,eAAO,MAAM,cAAc,QAAO,WAAW,GAAG,IACZ,CAAC;AAIrC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAO,IAUjC,CAAC"}
+{"version":3,"file":"runtimeContext.d.ts","sourceRoot":"","sources":["../../src/runtimeContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,GAAG,CAAC;IACZ,MAAM,EAAE,GAAG,CAAC;IACZ,OAAO,EAAE,GAAG,CAAC;IACb,KAAK,EAAE,GAAG,CAAC;IACX,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7E,0EAA0E;IAC1E,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,4EAA4E;IAC5E,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,GAAG,CAAC;QAAC,MAAM,EAAE,GAAG,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5C,kFAAkF;IAClF,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAID,+DAA+D;AAC/D,eAAO,MAAM,cAAc,GAAI,CAAC,EAC9B,KAAK,cAAc,EACnB,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAyB,CAAC;AAEtC,oEAAoE;AACpE,eAAO,MAAM,UAAU,QAAO,cAAc,GAAG,SAA+B,CAAC;AAE/E,oDAAoD;AACpD,eAAO,MAAM,cAAc,QAAO,WAAW,GAAG,IACZ,CAAC;AAIrC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAO,IAUjC,CAAC"}