@stackfactor/agent-utils 1.0.20 → 1.0.22

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

@@ -1 +1 @@
-{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":";wBAogBQ,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,KACV,GAAG;sBAyBG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,KAC1B,OAAO,CAAC,GAAG,CAAC;wCAmgBF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,KACpB,GAAG;oCAhZO,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,KACX,OAAO,CAAC,GAAG,CAAC;sDA4sBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,KACX,OAAO,CAAC,GAAG,CAAC;0CA5wB8B,GAAG,KAAG,MAAM;;AAu0BzD,wBAOE"}
+{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":";wBAogBQ,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,KACV,GAAG;sBAyBG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,KAC1B,OAAO,CAAC,GAAG,CAAC;wCA2xBF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,KACpB,GAAG;oCA1bO,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,KACX,OAAO,CAAC,GAAG,CAAC;sDAsvBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,KACX,OAAO,CAAC,GAAG,CAAC;0CAngC8B,GAAG,KAAG,MAAM;;AA8jCzD,wBAOE"}

package/dist/cjs/langChain.js

@@ -522,14 +522,44 @@ const runAgent = async (agent, prompt, config, onProgress = null) => {
             },
         ]
         : undefined;
-    assertQuotaAvailable();
-    const response = await agent.invoke({
-        messages: [{ role: "user", content: prompt }],
-    }, {
-        recursionLimit: config.recursionLimit || 25,
-        ...(callbacks ? { callbacks } : {}),
-    });
     const modelName = agent.options?.model?.modelName || agent.options?.model?.model || "";
+    // Wait + retry on 429 around the full agent run. The agent loop may issue
+    // many internal LLM calls, but a rate limit surfaces as a thrown error from
+    // the wrapping invoke. On retry we restart the agent run from scratch — any
+    // partial progress (tool calls, intermediate messages) is discarded, since
+    // the agent state isn't externally checkpointed. Cost is only recorded on a
+    // successful completion. Matches the behavior of the non-agentic paths.
+    let response;
+    let rateLimitAttempt = 0;
+    while (true) {
+        try {
+            assertQuotaAvailable();
+            response = await agent.invoke({
+                messages: [{ role: "user", content: prompt }],
+            }, {
+                recursionLimit: config.recursionLimit || 25,
+                ...(callbacks ? { callbacks } : {}),
+            });
+            break;
+        }
+        catch (err) {
+            if (isRateLimitError(err) && rateLimitAttempt < MAX_RATE_LIMIT_RETRIES) {
+                rateLimitAttempt++;
+                const { waitMs, source } = getRateLimitWaitMs(err);
+                const waitSeconds = Math.round(waitMs / 1000);
+                logger_js_1.default.log(null, logger_js_1.default.levels.warn, `Rate limited by "${modelName}" (agent), waiting ${waitSeconds}s before retry (${rateLimitAttempt}/${MAX_RATE_LIMIT_RETRIES}, source=${source}): ${err?.message ?? err}`);
+                if (onProgress) {
+                    onProgress({
+                        type: "rate_limit",
+                        message: `AI service is busy. Retrying in ${waitSeconds}s...`,
+                    });
+                }
+                await sleep(waitMs);
+                continue;
+            }
+            throw err;
+        }
+    }
     recordCost(calculateTextCost(modelName, sumAgentResponseUsage(response), config));
     const endTime = Date.now();
     const duration = endTime - startTime;
@@ -551,6 +581,191 @@ const throwErrorIfNotSuccessful = (response) => {
         throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, const_js_1.default.ERROR.UNABLE_TO_GENERATE_CONTENT);
     }
 };
+const MAX_VALIDATION_RETRIES = 3;
+const MAX_RATE_LIMIT_RETRIES = 2;
+const RATE_LIMIT_MIN_WAIT_MS = 30_000;
+const RATE_LIMIT_MAX_WAIT_MS = 60_000;
+// Cap on how long we'll honor a provider Retry-After hint. If a provider asks
+// for longer than this, treat it as a signal that the request shouldn't be
+// retried in-flight and fail fast instead of holding the caller open.
+const RATE_LIMIT_MAX_HONORED_WAIT_MS = 5 * 60 * 1000;
+// Small jitter added on top of an honored Retry-After so concurrent callers
+// that all received the same hint don't wake at exactly the same instant.
+const RATE_LIMIT_HONORED_JITTER_MS = 2_000;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Extracts a Retry-After hint (in milliseconds) from a provider 429 error.
+ * Different SDKs put headers in different places (top-level `headers`, nested
+ * `response.headers`, `responseHeaders`, or under `cause`), and some include a
+ * millisecond-precision `retry-after-ms` variant. Also checks the response body
+ * for `retry_after` / `retry_after_ms` fields (some providers put it there
+ * instead of headers). Standard `Retry-After` may be seconds or an HTTP date.
+ * Returns `null` when no usable hint is present.
+ */
+const parseRetryAfterFromError = (err) => {
+    const headerSources = [
+        err?.headers,
+        err?.response?.headers,
+        err?.responseHeaders,
+        err?.cause?.headers,
+        err?.cause?.response?.headers,
+    ];
+    for (const headers of headerSources) {
+        if (!headers || typeof headers !== "object")
+            continue;
+        const retryAfterMs = headers["retry-after-ms"] ?? headers["Retry-After-Ms"];
+        if (retryAfterMs != null) {
+            const ms = Number(retryAfterMs);
+            if (Number.isFinite(ms) && ms > 0)
+                return ms;
+        }
+        const retryAfter = headers["retry-after"] ?? headers["Retry-After"];
+        if (retryAfter != null) {
+            const asNumber = Number(retryAfter);
+            if (Number.isFinite(asNumber) && asNumber > 0) {
+                return asNumber * 1000;
+            }
+            const dateMs = Date.parse(String(retryAfter));
+            if (!Number.isNaN(dateMs)) {
+                const delta = dateMs - Date.now();
+                if (delta > 0)
+                    return delta;
+            }
+        }
+    }
+    const bodySources = [err?.error, err?.response?.data, err?.body];
+    for (const body of bodySources) {
+        if (!body || typeof body !== "object")
+            continue;
+        const retryAfterMs = body.retry_after_ms ?? body.retryAfterMs;
+        if (typeof retryAfterMs === "number" && retryAfterMs > 0) {
+            return retryAfterMs;
+        }
+        const retryAfterS = body.retry_after ?? body.retryAfter;
+        if (typeof retryAfterS === "number" && retryAfterS > 0) {
+            return retryAfterS * 1000;
+        }
+    }
+    return null;
+};
+/**
+ * Picks the back-off duration before retrying a 429. When the provider supplied
+ * a Retry-After hint, that value is honored (capped at
+ * RATE_LIMIT_MAX_HONORED_WAIT_MS, with small jitter added to avoid thundering
+ * herd on the same wake instant). When no hint is present, falls back to a
+ * uniform random wait in [RATE_LIMIT_MIN_WAIT_MS, RATE_LIMIT_MAX_WAIT_MS] —
+ * which is the right default for "we don't know how long this will last."
+ * Returns both the chosen ms and the source so callers can log it.
+ */
+const getRateLimitWaitMs = (err) => {
+    const hint = parseRetryAfterFromError(err);
+    if (hint != null) {
+        const honored = Math.min(hint, RATE_LIMIT_MAX_HONORED_WAIT_MS);
+        const jitter = Math.floor(Math.random() * RATE_LIMIT_HONORED_JITTER_MS);
+        return {
+            waitMs: Math.max(honored + jitter, 1_000),
+            source: "retry-after",
+        };
+    }
+    const waitMs = RATE_LIMIT_MIN_WAIT_MS +
+        Math.floor(Math.random() * (RATE_LIMIT_MAX_WAIT_MS - RATE_LIMIT_MIN_WAIT_MS + 1));
+    return { waitMs, source: "random" };
+};
+/**
+ * Detects rate-limit (HTTP 429) errors across LangChain and provider SDK shapes.
+ * Different SDKs surface the status in different places (status, statusCode,
+ * response.status, code) and sometimes only in the message text, so this checks
+ * each known shape rather than assuming a single field.
+ */
+const isRateLimitError = (err) => {
+    if (!err)
+        return false;
+    const statusCandidates = [
+        err.status,
+        err.statusCode,
+        err.response?.status,
+        err.response?.statusCode,
+        err.cause?.status,
+        err.cause?.statusCode,
+        err.code,
+    ];
+    if (statusCandidates.some((c) => c === 429 || c === "429"))
+        return true;
+    if (typeof err.code === "string" && /rate.?limit/i.test(err.code))
+        return true;
+    const message = typeof err.message === "string" ? err.message : "";
+    return (/\b429\b/.test(message) ||
+        /rate.?limit/i.test(message) ||
+        /too many requests/i.test(message));
+};
+/**
+ * Parses raw LLM content as JSON and validates against an optional Zod schema,
+ * returning the canonical JSON string. Tries a direct parse of the trimmed text
+ * first, then falls back to `extractJSONFromResponse` for markdown-wrapped output.
+ * Throws `UNPROCESSABLE_ENTITY` when the parsed value fails schema validation, or
+ * `INTERNAL_SERVER_ERROR` when no JSON can be extracted from the response at all.
+ */
+const parseAndValidateJSONResponse = (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 === const_js_1.default.HTTP_CODES.UNPROCESSABLE_ENTITY) {
+                    throw parseError;
+                }
+                // JSON.parse failed (not a validation error) — fall through to extraction.
+            }
+        }
+        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 errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, `LLM returned non-JSON response when JSON was expected: ${preview}...`);
+};
+/**
+ * Appends the model's failed output as an assistant turn followed by a user turn
+ * containing the Zod validation errors. Including the bad assistant turn (not just
+ * the critique) lets the model see what it actually produced — without it,
+ * self-correction is guesswork. Callers pass the *current* message list (not the
+ * original base) so that across multiple retries the full failure history
+ * accumulates and the model can avoid oscillating between previous broken outputs.
+ */
+const buildValidationRetryMessages = (priorMessages, rawContent, validationError) => {
+    const assistantContent = typeof rawContent === "string" ? rawContent : JSON.stringify(rawContent);
+    return [
+        ...priorMessages,
+        { role: "assistant", content: assistantContent },
+        {
+            role: "user",
+            content: `The previous response failed schema validation with the following errors. Return a corrected JSON response that fixes ALL of these issues:\n\n${validationError.message}`,
+        },
+    ];
+};
 /**
  * Sends a prompt to an LLM and returns the response, with support for streaming,
  * agentic execution, progress reporting, JSON extraction, and Zod schema validation.
@@ -728,84 +943,109 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         else {
             messagesToSend = messages;
         }
-        // Stream and report server-side progress based on time elapsed
-        let rawContent = "";
-        let chunkCount = 0;
+        // Retry once 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 is billed
+        // independently via recordCost so retry cost is still visible in telemetry.
+        const canRetryOnValidation = expectsJsonResponse && !!schema && !useNativeSchema;
         const progressReportInterval = 10; // Report every N chunks
-        const startTime = Date.now();
+        const overallStartTime = Date.now();
         // Use a time-based asymptotic curve: progress approaches maxPercent but never
         // overshoots. This avoids the magic "expected length" constant — longer responses
         // simply slow the curve down rather than exceeding the range.
         const expectedDurationMs = 15_000; // Tune: expected typical response time
-        const streamUsage = { input_tokens: 0, output_tokens: 0 };
-        assertQuotaAvailable();
-        const stream = await llm.stream(messagesToSend);
-        for await (const chunk of stream) {
-            accumulateChunkUsage(streamUsage, chunk);
-            const content = chunk?.content || chunk;
-            if (typeof content === "string") {
-                rawContent += content;
-                chunkCount++;
-                if (chunkCount % progressReportInterval === 0) {
-                    const elapsed = Date.now() - startTime;
-                    // Asymptotic curve: fast early progress that slows as it approaches max
-                    const progress = Math.round(minPercent +
-                        (maxPercent - minPercent - 5) *
-                            (1 - Math.exp(-elapsed / expectedDurationMs)));
-                    await onProgressReport({
-                        message: "Generating content...",
-                        progress: Math.min(progress, maxPercent - 5),
-                    });
+        let activeMessages = messagesToSend;
+        let attempt = 0;
+        const calcCurrentProgress = () => {
+            const elapsed = Date.now() - overallStartTime;
+            return Math.round(minPercent +
+                (maxPercent - minPercent - 5) *
+                    (1 - Math.exp(-elapsed / expectedDurationMs)));
+        };
+        while (true) {
+            let rawContent = "";
+            let chunkCount = 0;
+            let streamUsage = { input_tokens: 0, output_tokens: 0 };
+            // Inner loop: wait + retry on 429 around stream setup and consumption.
+            // Cost is only recorded on a successful stream — partial streams that error
+            // out with a rate limit are not billed. A 429 fired mid-stream simply
+            // discards the partial output and restarts cleanly.
+            let rateLimitAttempt = 0;
+            while (true) {
+                rawContent = "";
+                chunkCount = 0;
+                streamUsage = { input_tokens: 0, output_tokens: 0 };
+                try {
+                    assertQuotaAvailable();
+                    const stream = await llm.stream(activeMessages);
+                    for await (const chunk of stream) {
+                        accumulateChunkUsage(streamUsage, chunk);
+                        const content = chunk?.content || chunk;
+                        if (typeof content === "string") {
+                            rawContent += content;
+                            chunkCount++;
+                            if (chunkCount % progressReportInterval === 0) {
+                                await onProgressReport({
+                                    message: "Generating content...",
+                                    progress: Math.min(calcCurrentProgress(), maxPercent - 5),
+                                });
+                            }
+                        }
+                    }
+                    break; // stream completed without 429
+                }
+                catch (err) {
+                    if (isRateLimitError(err) &&
+                        rateLimitAttempt < MAX_RATE_LIMIT_RETRIES) {
+                        rateLimitAttempt++;
+                        const { waitMs, source } = getRateLimitWaitMs(err);
+                        const waitSeconds = Math.round(waitMs / 1000);
+                        logger_js_1.default.log(null, logger_js_1.default.levels.warn, `Rate limited by "${modelName}", waiting ${waitSeconds}s before retry (${rateLimitAttempt}/${MAX_RATE_LIMIT_RETRIES}, source=${source}): ${err?.message ?? err}`);
+                        await onProgressReport({
+                            message: `AI service is busy. Retrying in ${waitSeconds}s...`,
+                            progress: Math.min(calcCurrentProgress(), maxPercent - 5),
+                        });
+                        await sleep(waitMs);
+                        continue;
+                    }
+                    throw err;
                 }
             }
-        }
-        recordCost(calculateTextCost(modelName, streamUsage, config));
-        await onProgressReport({
-            message: "Processing complete",
-            progress: maxPercent,
-        });
-        if (!rawContent) {
-            throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, "LLM returned no content");
-        }
-        // If not expecting JSON, return raw content directly
-        if (!expectsJsonResponse) {
-            return rawContent;
-        }
-        // Parse and validate JSON response
-        const trimmed = rawContent.trim();
-        if ((trimmed.startsWith("{") && trimmed.endsWith("}")) ||
-            (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
+            recordCost(calculateTextCost(modelName, streamUsage, config));
+            if (!rawContent) {
+                throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, "LLM returned no content");
+            }
+            // If not expecting JSON, return raw content directly
+            if (!expectsJsonResponse) {
+                await onProgressReport({
+                    message: "Processing complete",
+                    progress: maxPercent,
+                });
+                return rawContent;
+            }
             try {
-                const parsed = JSON.parse(trimmed);
-                if (schema) {
-                    validateWithSchema(parsed, schema);
-                }
-                return JSON.stringify(parsed);
+                const result = parseAndValidateJSONResponse(rawContent, schema);
+                await onProgressReport({
+                    message: "Processing complete",
+                    progress: maxPercent,
+                });
+                return result;
             }
-            catch (parseError) {
-                if (parseError?.code === const_js_1.default.HTTP_CODES.UNPROCESSABLE_ENTITY) {
-                    throw parseError;
+            catch (err) {
+                const isValidationFailure = err?.code === const_js_1.default.HTTP_CODES.UNPROCESSABLE_ENTITY;
+                if (isValidationFailure &&
+                    canRetryOnValidation &&
+                    attempt < MAX_VALIDATION_RETRIES) {
+                    attempt++;
+                    logger_js_1.default.log(null, logger_js_1.default.levels.warn, `Schema validation failed for "${modelName}", retrying (${attempt}/${MAX_VALIDATION_RETRIES}): ${err.message}`);
+                    activeMessages = buildValidationRetryMessages(activeMessages, rawContent, err);
+                    continue;
                 }
+                throw err;
             }
         }
-        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 {
-            preview = "[empty response]";
-        }
-        throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, `LLM returned non-JSON response when JSON was expected: ${preview}...`);
     }
     else {
         // Non-streaming mode: use native response_format for OpenAI when schema is provided
@@ -845,67 +1085,56 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         else {
             messagesToSend = messages;
         }
-        // Simply invoke without streaming
-        assertQuotaAvailable();
-        const response = await llm.invoke(messagesToSend);
-        recordCost(calculateTextCost(modelName, extractUsageFromInvoke(response), config));
-        const rawContent = response?.content || response;
-        // If not expecting JSON, return raw content directly
-        if (!expectsJsonResponse) {
-            return rawContent;
-        }
-        // If the response is already a string that looks like JSON, return it
-        // Otherwise, try to extract JSON from potential markdown wrapping
-        if (typeof rawContent === "string") {
-            const trimmed = rawContent.trim();
-            // Check if it's already clean JSON
-            if ((trimmed.startsWith("{") && trimmed.endsWith("}")) ||
-                (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
+        // Retry once on schema validation failure (see streaming branch for rationale).
+        // Each attempt is billed independently via recordCost so retry cost is visible.
+        const canRetryOnValidation = expectsJsonResponse && !!schema && !useNativeSchema;
+        let activeMessages = messagesToSend;
+        let attempt = 0;
+        while (true) {
+            // Inner loop: wait + retry on 429. No progress callback in this branch, so
+            // the wait is silent to the caller — only the warn log is emitted.
+            let response;
+            let rateLimitAttempt = 0;
+            while (true) {
                 try {
-                    // Parse and re-stringify
-                    const parsed = JSON.parse(trimmed);
-                    // Validate against schema if provided
-                    if (schema) {
-                        validateWithSchema(parsed, schema);
-                    }
-                    return JSON.stringify(parsed);
+                    assertQuotaAvailable();
+                    response = await llm.invoke(activeMessages);
+                    break;
                 }
-                catch (parseError) {
-                    // If it's a validation error, re-throw it
-                    if (parseError?.code === const_js_1.default.HTTP_CODES.UNPROCESSABLE_ENTITY) {
-                        throw parseError;
+                catch (err) {
+                    if (isRateLimitError(err) &&
+                        rateLimitAttempt < MAX_RATE_LIMIT_RETRIES) {
+                        rateLimitAttempt++;
+                        const { waitMs, source } = getRateLimitWaitMs(err);
+                        logger_js_1.default.log(null, logger_js_1.default.levels.warn, `Rate limited by "${modelName}", waiting ${Math.round(waitMs / 1000)}s before retry (${rateLimitAttempt}/${MAX_RATE_LIMIT_RETRIES}, source=${source}): ${err?.message ?? err}`);
+                        await sleep(waitMs);
+                        continue;
                     }
-                    // Not valid JSON, try extraction
+                    throw err;
                 }
             }
-            // Try to extract JSON from markdown or other wrapping
-            const extracted = extractJSONFromResponse(rawContent);
-            if (extracted) {
-                // Validate against schema if provided
-                if (schema) {
-                    validateWithSchema(extracted, schema);
-                }
-                return JSON.stringify(extracted);
-            }
-        }
-        // Return raw content as last resort - but throw if JSON was expected
-        if (expectsJsonResponse) {
-            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);
+            recordCost(calculateTextCost(modelName, extractUsageFromInvoke(response), config));
+            const rawContent = response?.content || response;
+            // 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 parseAndValidateJSONResponse(rawContent, schema);
             }
-            else {
-                preview = "[empty response]";
+            catch (err) {
+                const isValidationFailure = err?.code === const_js_1.default.HTTP_CODES.UNPROCESSABLE_ENTITY;
+                if (isValidationFailure &&
+                    canRetryOnValidation &&
+                    attempt < MAX_VALIDATION_RETRIES) {
+                    attempt++;
+                    logger_js_1.default.log(null, logger_js_1.default.levels.warn, `Schema validation failed for "${modelName}", retrying (${attempt}/${MAX_VALIDATION_RETRIES}): ${err.message}`);
+                    activeMessages = buildValidationRetryMessages(activeMessages, rawContent, err);
+                    continue;
+                }
+                throw err;
             }
-            throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, `LLM returned non-JSON response when JSON was expected: ${preview}...`);
         }
-        return rawContent;
     }
 };
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":";wBAogBQ,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,KACV,GAAG;sBAyBG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,KAC1B,OAAO,CAAC,GAAG,CAAC;wCAmgBF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,KACpB,GAAG;oCAhZO,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,KACX,OAAO,CAAC,GAAG,CAAC;sDA4sBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,KACX,OAAO,CAAC,GAAG,CAAC;0CA5wB8B,GAAG,KAAG,MAAM;;AAu0BzD,wBAOE"}
+{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":";wBAogBQ,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,KACV,GAAG;sBAyBG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,KAC1B,OAAO,CAAC,GAAG,CAAC;wCA2xBF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,KACpB,GAAG;oCA1bO,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,KACX,OAAO,CAAC,GAAG,CAAC;sDAsvBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,KACX,OAAO,CAAC,GAAG,CAAC;0CAngC8B,GAAG,KAAG,MAAM;;AA8jCzD,wBAOE"}

package/dist/esm/langChain.js

@@ -517,14 +517,44 @@ const runAgent = async (agent, prompt, config, onProgress = null) => {
             },
         ]
         : undefined;
-    assertQuotaAvailable();
-    const response = await agent.invoke({
-        messages: [{ role: "user", content: prompt }],
-    }, {
-        recursionLimit: config.recursionLimit || 25,
-        ...(callbacks ? { callbacks } : {}),
-    });
     const modelName = agent.options?.model?.modelName || agent.options?.model?.model || "";
+    // Wait + retry on 429 around the full agent run. The agent loop may issue
+    // many internal LLM calls, but a rate limit surfaces as a thrown error from
+    // the wrapping invoke. On retry we restart the agent run from scratch — any
+    // partial progress (tool calls, intermediate messages) is discarded, since
+    // the agent state isn't externally checkpointed. Cost is only recorded on a
+    // successful completion. Matches the behavior of the non-agentic paths.
+    let response;
+    let rateLimitAttempt = 0;
+    while (true) {
+        try {
+            assertQuotaAvailable();
+            response = await agent.invoke({
+                messages: [{ role: "user", content: prompt }],
+            }, {
+                recursionLimit: config.recursionLimit || 25,
+                ...(callbacks ? { callbacks } : {}),
+            });
+            break;
+        }
+        catch (err) {
+            if (isRateLimitError(err) && rateLimitAttempt < MAX_RATE_LIMIT_RETRIES) {
+                rateLimitAttempt++;
+                const { waitMs, source } = getRateLimitWaitMs(err);
+                const waitSeconds = Math.round(waitMs / 1000);
+                logger.log(null, logger.levels.warn, `Rate limited by "${modelName}" (agent), waiting ${waitSeconds}s before retry (${rateLimitAttempt}/${MAX_RATE_LIMIT_RETRIES}, source=${source}): ${err?.message ?? err}`);
+                if (onProgress) {
+                    onProgress({
+                        type: "rate_limit",
+                        message: `AI service is busy. Retrying in ${waitSeconds}s...`,
+                    });
+                }
+                await sleep(waitMs);
+                continue;
+            }
+            throw err;
+        }
+    }
     recordCost(calculateTextCost(modelName, sumAgentResponseUsage(response), config));
     const endTime = Date.now();
     const duration = endTime - startTime;
@@ -546,6 +576,191 @@ const throwErrorIfNotSuccessful = (response) => {
         throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, constants.ERROR.UNABLE_TO_GENERATE_CONTENT);
     }
 };
+const MAX_VALIDATION_RETRIES = 3;
+const MAX_RATE_LIMIT_RETRIES = 2;
+const RATE_LIMIT_MIN_WAIT_MS = 30_000;
+const RATE_LIMIT_MAX_WAIT_MS = 60_000;
+// Cap on how long we'll honor a provider Retry-After hint. If a provider asks
+// for longer than this, treat it as a signal that the request shouldn't be
+// retried in-flight and fail fast instead of holding the caller open.
+const RATE_LIMIT_MAX_HONORED_WAIT_MS = 5 * 60 * 1000;
+// Small jitter added on top of an honored Retry-After so concurrent callers
+// that all received the same hint don't wake at exactly the same instant.
+const RATE_LIMIT_HONORED_JITTER_MS = 2_000;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Extracts a Retry-After hint (in milliseconds) from a provider 429 error.
+ * Different SDKs put headers in different places (top-level `headers`, nested
+ * `response.headers`, `responseHeaders`, or under `cause`), and some include a
+ * millisecond-precision `retry-after-ms` variant. Also checks the response body
+ * for `retry_after` / `retry_after_ms` fields (some providers put it there
+ * instead of headers). Standard `Retry-After` may be seconds or an HTTP date.
+ * Returns `null` when no usable hint is present.
+ */
+const parseRetryAfterFromError = (err) => {
+    const headerSources = [
+        err?.headers,
+        err?.response?.headers,
+        err?.responseHeaders,
+        err?.cause?.headers,
+        err?.cause?.response?.headers,
+    ];
+    for (const headers of headerSources) {
+        if (!headers || typeof headers !== "object")
+            continue;
+        const retryAfterMs = headers["retry-after-ms"] ?? headers["Retry-After-Ms"];
+        if (retryAfterMs != null) {
+            const ms = Number(retryAfterMs);
+            if (Number.isFinite(ms) && ms > 0)
+                return ms;
+        }
+        const retryAfter = headers["retry-after"] ?? headers["Retry-After"];
+        if (retryAfter != null) {
+            const asNumber = Number(retryAfter);
+            if (Number.isFinite(asNumber) && asNumber > 0) {
+                return asNumber * 1000;
+            }
+            const dateMs = Date.parse(String(retryAfter));
+            if (!Number.isNaN(dateMs)) {
+                const delta = dateMs - Date.now();
+                if (delta > 0)
+                    return delta;
+            }
+        }
+    }
+    const bodySources = [err?.error, err?.response?.data, err?.body];
+    for (const body of bodySources) {
+        if (!body || typeof body !== "object")
+            continue;
+        const retryAfterMs = body.retry_after_ms ?? body.retryAfterMs;
+        if (typeof retryAfterMs === "number" && retryAfterMs > 0) {
+            return retryAfterMs;
+        }
+        const retryAfterS = body.retry_after ?? body.retryAfter;
+        if (typeof retryAfterS === "number" && retryAfterS > 0) {
+            return retryAfterS * 1000;
+        }
+    }
+    return null;
+};
+/**
+ * Picks the back-off duration before retrying a 429. When the provider supplied
+ * a Retry-After hint, that value is honored (capped at
+ * RATE_LIMIT_MAX_HONORED_WAIT_MS, with small jitter added to avoid thundering
+ * herd on the same wake instant). When no hint is present, falls back to a
+ * uniform random wait in [RATE_LIMIT_MIN_WAIT_MS, RATE_LIMIT_MAX_WAIT_MS] —
+ * which is the right default for "we don't know how long this will last."
+ * Returns both the chosen ms and the source so callers can log it.
+ */
+const getRateLimitWaitMs = (err) => {
+    const hint = parseRetryAfterFromError(err);
+    if (hint != null) {
+        const honored = Math.min(hint, RATE_LIMIT_MAX_HONORED_WAIT_MS);
+        const jitter = Math.floor(Math.random() * RATE_LIMIT_HONORED_JITTER_MS);
+        return {
+            waitMs: Math.max(honored + jitter, 1_000),
+            source: "retry-after",
+        };
+    }
+    const waitMs = RATE_LIMIT_MIN_WAIT_MS +
+        Math.floor(Math.random() * (RATE_LIMIT_MAX_WAIT_MS - RATE_LIMIT_MIN_WAIT_MS + 1));
+    return { waitMs, source: "random" };
+};
+/**
+ * Detects rate-limit (HTTP 429) errors across LangChain and provider SDK shapes.
+ * Different SDKs surface the status in different places (status, statusCode,
+ * response.status, code) and sometimes only in the message text, so this checks
+ * each known shape rather than assuming a single field.
+ */
+const isRateLimitError = (err) => {
+    if (!err)
+        return false;
+    const statusCandidates = [
+        err.status,
+        err.statusCode,
+        err.response?.status,
+        err.response?.statusCode,
+        err.cause?.status,
+        err.cause?.statusCode,
+        err.code,
+    ];
+    if (statusCandidates.some((c) => c === 429 || c === "429"))
+        return true;
+    if (typeof err.code === "string" && /rate.?limit/i.test(err.code))
+        return true;
+    const message = typeof err.message === "string" ? err.message : "";
+    return (/\b429\b/.test(message) ||
+        /rate.?limit/i.test(message) ||
+        /too many requests/i.test(message));
+};
+/**
+ * Parses raw LLM content as JSON and validates against an optional Zod schema,
+ * returning the canonical JSON string. Tries a direct parse of the trimmed text
+ * first, then falls back to `extractJSONFromResponse` for markdown-wrapped output.
+ * Throws `UNPROCESSABLE_ENTITY` when the parsed value fails schema validation, or
+ * `INTERNAL_SERVER_ERROR` when no JSON can be extracted from the response at all.
+ */
+const parseAndValidateJSONResponse = (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;
+                }
+                // JSON.parse failed (not a validation error) — fall through to extraction.
+            }
+        }
+        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, `LLM returned non-JSON response when JSON was expected: ${preview}...`);
+};
+/**
+ * Appends the model's failed output as an assistant turn followed by a user turn
+ * containing the Zod validation errors. Including the bad assistant turn (not just
+ * the critique) lets the model see what it actually produced — without it,
+ * self-correction is guesswork. Callers pass the *current* message list (not the
+ * original base) so that across multiple retries the full failure history
+ * accumulates and the model can avoid oscillating between previous broken outputs.
+ */
+const buildValidationRetryMessages = (priorMessages, rawContent, validationError) => {
+    const assistantContent = typeof rawContent === "string" ? rawContent : JSON.stringify(rawContent);
+    return [
+        ...priorMessages,
+        { role: "assistant", content: assistantContent },
+        {
+            role: "user",
+            content: `The previous response failed schema validation with the following errors. Return a corrected JSON response that fixes ALL of these issues:\n\n${validationError.message}`,
+        },
+    ];
+};
 /**
  * Sends a prompt to an LLM and returns the response, with support for streaming,
  * agentic execution, progress reporting, JSON extraction, and Zod schema validation.
@@ -723,84 +938,109 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         else {
             messagesToSend = messages;
         }
-        // Stream and report server-side progress based on time elapsed
-        let rawContent = "";
-        let chunkCount = 0;
+        // Retry once 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 is billed
+        // independently via recordCost so retry cost is still visible in telemetry.
+        const canRetryOnValidation = expectsJsonResponse && !!schema && !useNativeSchema;
         const progressReportInterval = 10; // Report every N chunks
-        const startTime = Date.now();
+        const overallStartTime = Date.now();
         // Use a time-based asymptotic curve: progress approaches maxPercent but never
         // overshoots. This avoids the magic "expected length" constant — longer responses
         // simply slow the curve down rather than exceeding the range.
         const expectedDurationMs = 15_000; // Tune: expected typical response time
-        const streamUsage = { input_tokens: 0, output_tokens: 0 };
-        assertQuotaAvailable();
-        const stream = await llm.stream(messagesToSend);
-        for await (const chunk of stream) {
-            accumulateChunkUsage(streamUsage, chunk);
-            const content = chunk?.content || chunk;
-            if (typeof content === "string") {
-                rawContent += content;
-                chunkCount++;
-                if (chunkCount % progressReportInterval === 0) {
-                    const elapsed = Date.now() - startTime;
-                    // Asymptotic curve: fast early progress that slows as it approaches max
-                    const progress = Math.round(minPercent +
-                        (maxPercent - minPercent - 5) *
-                            (1 - Math.exp(-elapsed / expectedDurationMs)));
-                    await onProgressReport({
-                        message: "Generating content...",
-                        progress: Math.min(progress, maxPercent - 5),
-                    });
+        let activeMessages = messagesToSend;
+        let attempt = 0;
+        const calcCurrentProgress = () => {
+            const elapsed = Date.now() - overallStartTime;
+            return Math.round(minPercent +
+                (maxPercent - minPercent - 5) *
+                    (1 - Math.exp(-elapsed / expectedDurationMs)));
+        };
+        while (true) {
+            let rawContent = "";
+            let chunkCount = 0;
+            let streamUsage = { input_tokens: 0, output_tokens: 0 };
+            // Inner loop: wait + retry on 429 around stream setup and consumption.
+            // Cost is only recorded on a successful stream — partial streams that error
+            // out with a rate limit are not billed. A 429 fired mid-stream simply
+            // discards the partial output and restarts cleanly.
+            let rateLimitAttempt = 0;
+            while (true) {
+                rawContent = "";
+                chunkCount = 0;
+                streamUsage = { input_tokens: 0, output_tokens: 0 };
+                try {
+                    assertQuotaAvailable();
+                    const stream = await llm.stream(activeMessages);
+                    for await (const chunk of stream) {
+                        accumulateChunkUsage(streamUsage, chunk);
+                        const content = chunk?.content || chunk;
+                        if (typeof content === "string") {
+                            rawContent += content;
+                            chunkCount++;
+                            if (chunkCount % progressReportInterval === 0) {
+                                await onProgressReport({
+                                    message: "Generating content...",
+                                    progress: Math.min(calcCurrentProgress(), maxPercent - 5),
+                                });
+                            }
+                        }
+                    }
+                    break; // stream completed without 429
+                }
+                catch (err) {
+                    if (isRateLimitError(err) &&
+                        rateLimitAttempt < MAX_RATE_LIMIT_RETRIES) {
+                        rateLimitAttempt++;
+                        const { waitMs, source } = getRateLimitWaitMs(err);
+                        const waitSeconds = Math.round(waitMs / 1000);
+                        logger.log(null, logger.levels.warn, `Rate limited by "${modelName}", waiting ${waitSeconds}s before retry (${rateLimitAttempt}/${MAX_RATE_LIMIT_RETRIES}, source=${source}): ${err?.message ?? err}`);
+                        await onProgressReport({
+                            message: `AI service is busy. Retrying in ${waitSeconds}s...`,
+                            progress: Math.min(calcCurrentProgress(), maxPercent - 5),
+                        });
+                        await sleep(waitMs);
+                        continue;
+                    }
+                    throw err;
                 }
             }
-        }
-        recordCost(calculateTextCost(modelName, streamUsage, config));
-        await onProgressReport({
-            message: "Processing complete",
-            progress: maxPercent,
-        });
-        if (!rawContent) {
-            throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, "LLM returned no content");
-        }
-        // If not expecting JSON, return raw content directly
-        if (!expectsJsonResponse) {
-            return rawContent;
-        }
-        // Parse and validate JSON response
-        const trimmed = rawContent.trim();
-        if ((trimmed.startsWith("{") && trimmed.endsWith("}")) ||
-            (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
+            recordCost(calculateTextCost(modelName, streamUsage, config));
+            if (!rawContent) {
+                throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, "LLM returned no content");
+            }
+            // If not expecting JSON, return raw content directly
+            if (!expectsJsonResponse) {
+                await onProgressReport({
+                    message: "Processing complete",
+                    progress: maxPercent,
+                });
+                return rawContent;
+            }
             try {
-                const parsed = JSON.parse(trimmed);
-                if (schema) {
-                    validateWithSchema(parsed, schema);
-                }
-                return JSON.stringify(parsed);
+                const result = parseAndValidateJSONResponse(rawContent, schema);
+                await onProgressReport({
+                    message: "Processing complete",
+                    progress: maxPercent,
+                });
+                return result;
             }
-            catch (parseError) {
-                if (parseError?.code === constants.HTTP_CODES.UNPROCESSABLE_ENTITY) {
-                    throw parseError;
+            catch (err) {
+                const isValidationFailure = err?.code === constants.HTTP_CODES.UNPROCESSABLE_ENTITY;
+                if (isValidationFailure &&
+                    canRetryOnValidation &&
+                    attempt < MAX_VALIDATION_RETRIES) {
+                    attempt++;
+                    logger.log(null, logger.levels.warn, `Schema validation failed for "${modelName}", retrying (${attempt}/${MAX_VALIDATION_RETRIES}): ${err.message}`);
+                    activeMessages = buildValidationRetryMessages(activeMessages, rawContent, err);
+                    continue;
                 }
+                throw err;
             }
         }
-        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 {
-            preview = "[empty response]";
-        }
-        throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, `LLM returned non-JSON response when JSON was expected: ${preview}...`);
     }
     else {
         // Non-streaming mode: use native response_format for OpenAI when schema is provided
@@ -840,67 +1080,56 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         else {
             messagesToSend = messages;
         }
-        // Simply invoke without streaming
-        assertQuotaAvailable();
-        const response = await llm.invoke(messagesToSend);
-        recordCost(calculateTextCost(modelName, extractUsageFromInvoke(response), config));
-        const rawContent = response?.content || response;
-        // If not expecting JSON, return raw content directly
-        if (!expectsJsonResponse) {
-            return rawContent;
-        }
-        // If the response is already a string that looks like JSON, return it
-        // Otherwise, try to extract JSON from potential markdown wrapping
-        if (typeof rawContent === "string") {
-            const trimmed = rawContent.trim();
-            // Check if it's already clean JSON
-            if ((trimmed.startsWith("{") && trimmed.endsWith("}")) ||
-                (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
+        // Retry once on schema validation failure (see streaming branch for rationale).
+        // Each attempt is billed independently via recordCost so retry cost is visible.
+        const canRetryOnValidation = expectsJsonResponse && !!schema && !useNativeSchema;
+        let activeMessages = messagesToSend;
+        let attempt = 0;
+        while (true) {
+            // Inner loop: wait + retry on 429. No progress callback in this branch, so
+            // the wait is silent to the caller — only the warn log is emitted.
+            let response;
+            let rateLimitAttempt = 0;
+            while (true) {
                 try {
-                    // Parse and re-stringify
-                    const parsed = JSON.parse(trimmed);
-                    // Validate against schema if provided
-                    if (schema) {
-                        validateWithSchema(parsed, schema);
-                    }
-                    return JSON.stringify(parsed);
+                    assertQuotaAvailable();
+                    response = await llm.invoke(activeMessages);
+                    break;
                 }
-                catch (parseError) {
-                    // If it's a validation error, re-throw it
-                    if (parseError?.code === constants.HTTP_CODES.UNPROCESSABLE_ENTITY) {
-                        throw parseError;
+                catch (err) {
+                    if (isRateLimitError(err) &&
+                        rateLimitAttempt < MAX_RATE_LIMIT_RETRIES) {
+                        rateLimitAttempt++;
+                        const { waitMs, source } = getRateLimitWaitMs(err);
+                        logger.log(null, logger.levels.warn, `Rate limited by "${modelName}", waiting ${Math.round(waitMs / 1000)}s before retry (${rateLimitAttempt}/${MAX_RATE_LIMIT_RETRIES}, source=${source}): ${err?.message ?? err}`);
+                        await sleep(waitMs);
+                        continue;
                     }
-                    // Not valid JSON, try extraction
+                    throw err;
                 }
             }
-            // Try to extract JSON from markdown or other wrapping
-            const extracted = extractJSONFromResponse(rawContent);
-            if (extracted) {
-                // Validate against schema if provided
-                if (schema) {
-                    validateWithSchema(extracted, schema);
-                }
-                return JSON.stringify(extracted);
-            }
-        }
-        // Return raw content as last resort - but throw if JSON was expected
-        if (expectsJsonResponse) {
-            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);
+            recordCost(calculateTextCost(modelName, extractUsageFromInvoke(response), config));
+            const rawContent = response?.content || response;
+            // 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 parseAndValidateJSONResponse(rawContent, schema);
             }
-            else {
-                preview = "[empty response]";
+            catch (err) {
+                const isValidationFailure = err?.code === constants.HTTP_CODES.UNPROCESSABLE_ENTITY;
+                if (isValidationFailure &&
+                    canRetryOnValidation &&
+                    attempt < MAX_VALIDATION_RETRIES) {
+                    attempt++;
+                    logger.log(null, logger.levels.warn, `Schema validation failed for "${modelName}", retrying (${attempt}/${MAX_VALIDATION_RETRIES}): ${err.message}`);
+                    activeMessages = buildValidationRetryMessages(activeMessages, rawContent, err);
+                    continue;
+                }
+                throw err;
             }
-            throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, `LLM returned non-JSON response when JSON was expected: ${preview}...`);
         }
-        return rawContent;
     }
 };
 /**

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "restricted"
   },
-  "version": "1.0.20",
+  "version": "1.0.22",
   "description": "",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",