@stackfactor/agent-utils 1.4.3 → 1.7.0

package/dist/esm/index.js

@@ -2,14 +2,16 @@ import constants from "./const.js";
 import errorHandling, { AppError } from "./errorHandling.js";
 import langChain from "./langChain.js";
 import logger from "./logger.js";
-import { serve } from "./serve.js";
+import { serve, runOnce, isRunOnceExecution, EXECUTION_ENV } from "./serve.js";
 import { callAgent, checkAgent } from "./client.js";
 import * as runtimeContext from "./runtimeContext.js";
+import { recordUsage, USAGE_UNITS } from "./usage.js";
 export { constants };
 export { errorHandling, AppError };
 export { langChain };
 export { logger };
-export { serve };
+export { serve, runOnce, isRunOnceExecution, EXECUTION_ENV };
 export { callAgent };
 export { checkAgent };
 export { runtimeContext };
+export { recordUsage, USAGE_UNITS };

package/dist/esm/langChain.d.ts

@@ -1,8 +1,20 @@
+type TokenUsage = {
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+};
 /**
- * Accumulated usage and cost for a single agent run. Callers initialize an
+ * What a run used, by model, for the agent's own use: callers initialize an
  * empty object (`{}`) and pass it through `runPromptWithModel`; helpers
- * populate `cost` (USD total across all models) and per-model
- * `<model>_inputTokens` / `<model>_outputTokens` counters under `tokens`.
+ * populate per-model counters under `tokens` (`<model>_inputTokens`,
+ * `<model>_outputTokens`, ...).
+ *
+ * It is not how the platform learns what was used, and not what that costs:
+ * every call made through this module is counted into the request's usage
+ * ledger, with or without a tracker, and reported to the platform, which
+ * prices it (see `usage.ts`). `cost` stays 0 for that reason. A handler
+ * answers its data alone: a tracker it returned would reach the caller as
+ * part of the content.
  */
 export type UsageTracker = {
     cost: number;
@@ -43,6 +55,11 @@ export type UsageTracker = {
  */
 export declare const getLLMModel: (modelName: string, config: any, schema?: any) => any;
 declare const _default: {
+    canRetryValidation: (expectsJsonResponse: boolean, schema: any) => boolean;
+    isRetryableJsonFailure: (error: any) => boolean;
+    buildAgenticRetryPrompt: (userPrompt: string, rawContent: any, error: any) => string;
+    parseAgenticJsonResponse: (rawContent: any, schema: any) => string;
+    supportsNativeSchema: (modelName: string) => boolean;
     checkIfAIProviderConfigured: (config: any) => void;
     createAgent: (name: string, modelName: string, systemPrompt: string, tools: any[], responseFormat: any, config: any, usageTracker?: UsageTracker | null) => any;
     runAgent: (agent: any, prompt: string, config: any, onProgress?: Function | null, usageTracker?: UsageTracker | null) => Promise<any>;
@@ -50,7 +67,10 @@ declare const _default: {
     runPromptWithModelForImageGeneration: (modelName: string, config: any, prompt: string, options?: any, usageTracker?: UsageTracker | null) => Promise<any>;
     runPromptWithModelForVideoGeneration: (modelName: string, config: any, prompt: string, options?: any, usageTracker?: UsageTracker | null) => Promise<any>;
     throwErrorIfNotSuccessful: (response: any) => string;
-    updateUsageTrackerForCharacters: (tracker: UsageTracker | null | undefined, modelName: string, characterCount: number, config: any) => void;
+    updateImageUsageTracker: (tracker: UsageTracker | null | undefined, modelName: string, response: any, _config: any, provider: "openai" | "google") => void;
+    updateUsageTracker: (tracker: UsageTracker | null | undefined, modelName: string, usage: TokenUsage | null, _config?: any) => void;
+    updateUsageTrackerForCharacters: (tracker: UsageTracker | null | undefined, modelName: string, characterCount: number, _config?: any) => void;
+    updateVideoUsageTracker: (tracker: UsageTracker | null | undefined, modelName: string, seconds: number, _config?: any) => void;
     validateModel: (selectedModel: string, supportedModels: string[]) => string;
 };
 export default _default;

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

@@ -1 +1 @@
-{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AA6GA;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACvC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACtD,CAAC;AA0lBF;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,eAAO,MAAM,WAAW,GACtB,WAAW,MAAM,EACjB,QAAQ,GAAG,EACX,SAAQ,GAAU,KACjB,GAwHF,CAAC;;0CA3uB2C,GAAG,KAAG,IAAI;wBA8vB/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,iBACG,YAAY,GAAG,IAAI,KAChC,GAAG;sBAoCG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,iBACb,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;oCAkYF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDA2tBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDAmTF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CA7zC8B,GAAG,KAAG,MAAM;+CA1uB9C,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,kBACD,MAAM,UACd,GAAG,KACV,IAAI;mCA0vBU,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AAg2CT,wBAUE"}
+{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AAoGA,KAAK,UAAU,GAAG;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IAKtB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACvC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACtD,CAAC;AAmiBF;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,eAAO,MAAM,WAAW,GACtB,WAAW,MAAM,EACjB,QAAQ,GAAG,EACX,SAAQ,GAAU,KACjB,GAwHF,CAAC;;8CA4Z+C,OAAO,UAAU,GAAG,KAAG,OAAO;oCAWxC,GAAG,KAAG,OAAO;0CAgBtC,MAAM,cACN,GAAG,SACR,GAAG,KACT,MAAM;2CA0CqC,GAAG,UAAU,GAAG,KAAG,MAAM;sCAvvC9B,MAAM,KAAG,OAAO;0CA+FZ,GAAG,KAAG,IAAI;wBAusB/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,iBACG,YAAY,GAAG,IAAI,KAChC,GAAG;sBAoCG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,iBACb,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;oCA6fF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDA0sBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDAmTF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CAv6C8B,GAAG,KAAG,MAAM;uCA3wB9C,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,YACP,GAAG,WACJ,GAAG,YACF,QAAQ,GAAG,QAAQ,KAC5B,IAAI;kCA5CI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,SACV,UAAU,GAAG,IAAI,YACd,GAAG,KACZ,IAAI;+CA0FI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,kBACD,MAAM,YACZ,GAAG,KACZ,IAAI;uCAoBI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,WACR,MAAM,YACL,GAAG,KACZ,IAAI;mCA4sBU,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AA08CT,wBAkBE"}

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()`
@@ -1093,6 +1042,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 +1112,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 +1246,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);
+            // 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 +1327,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 +1485,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 +1996,11 @@ const runPromptWithModelForVideoGeneration = async (modelName, config, prompt, o
     }
 };
 export default {
+    canRetryValidation,
+    isRetryableJsonFailure,
+    buildAgenticRetryPrompt,
+    parseAgenticJsonResponse,
+    supportsNativeSchema,
     checkIfAIProviderConfigured,
     createAgent,
     runAgent,
@@ -1965,6 +2008,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"}