@stackfactor/agent-utils 1.0.21 → 1.0.23

package/README.md

@@ -62,32 +62,6 @@ const result = await langChain.runPromptWithModel(
 
 ---
 
-### `langChain.runChatPromptWithModel(modelName, config, prompt, onProgressReport?)`
-
-Sends a conversational chat prompt to an LLM and returns a plain HTML response. Built for the StackFactor Mentor chat feature — system messages are wrapped with topic-constraint instructions that decline off-topic questions.
-
-| Parameter          | Type                 | Default | Description                                           |
-| ------------------ | -------------------- | ------- | ----------------------------------------------------- |
-| `modelName`        | `string`             | —       | Model identifier                                      |
-| `config`           | `object`             | —       | API keys and optional `temperature`                   |
-| `prompt`           | `string \| object[]` | —       | Plain string or array of `{ role, content }` messages |
-| `onProgressReport` | `function \| null`   | `null`  | Streaming progress callback                           |
-
-**Returns:** Raw HTML string.
-
-```typescript
-const html = await langChain.runChatPromptWithModel(
-  "claude-3-5-sonnet",
-  { anthropicAPIKey: "sk-ant-..." },
-  [
-    { role: "system", content: "Topic: JavaScript closures" },
-    { role: "user", content: "Explain closures with an example" },
-  ],
-);
-```
-
----
-
 ### `langChain.createAIAgent(name, modelName, systemPrompt, tools?, responseFormat?, config, onReportProgress?, minPercent?, maxPercent?)`
 
 Constructs a LangChain agent with a model, system prompt, and tools. When `onReportProgress` is provided, a `report_progress` tool is automatically added.

package/dist/cjs/langChain.d.ts

@@ -1,7 +1,7 @@
 declare const _default: {
+    checkIfAIProviderConfigured: (config: any) => void;
     createAgent: (name: string, modelName: string, systemPrompt: string, tools: any[], responseFormat: any, config: any) => any;
     runAgent: (agent: any, prompt: string, config: any, onProgress?: Function | null) => Promise<any>;
-    runChatPromptWithModel: (modelName: string, config: any, prompt: any, onProgressReport: any) => any;
     runPromptWithModel: (modelName: string, config: any, prompt: any, onProgressReport: any, minPercent?: number, maxPercent?: number, expectsJsonResponse?: boolean, schema?: any, agentName?: string, tools?: any[]) => Promise<any>;
     runPromptWithModelForImageGeneration: (modelName: string, config: any, prompt: string, options?: any) => Promise<any>;
     throwErrorIfNotSuccessful: (response: any) => string;

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;wCAkkBF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,KACpB,GAAG;oCA7XO,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;sDAyrBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,KACX,OAAO,CAAC,GAAG,CAAC;0CA30B8B,GAAG,KAAG,MAAM;;AAs4BzD,wBAOE"}
+{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":";0CAgD6C,GAAG,KAAG,IAAI;wBAke/C,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;oCAqWF,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;sDA6rBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,KACX,OAAO,CAAC,GAAG,CAAC;0CA18B8B,GAAG,KAAG,MAAM;;AAqgCzD,wBAOE"}

package/dist/cjs/langChain.js

@@ -36,6 +36,14 @@ const assertQuotaAvailable = () => {
         throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.PAYMENT_REQUIRED, const_js_1.default.ERROR.QUOTA_EXHAUSTED);
     }
 };
+const checkIfAIProviderConfigured = (config) => {
+    if (!config ||
+        !config.openAIAPIKey ||
+        !config.googleAPIKey ||
+        !config.anthropicAPIKey) {
+        throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, "The integration is not properly configured with all AI providers.");
+    }
+};
 /**
  * Subtracts the given USD cost from `global.quota.remaining` and adds it to
  * `global.quota.usedThisSession`. Silently no-ops when the quota globals are not
@@ -522,14 +530,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;
@@ -552,6 +590,122 @@ const throwErrorIfNotSuccessful = (response) => {
     }
 };
 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
@@ -812,29 +966,59 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         const expectedDurationMs = 15_000; // Tune: expected typical response time
         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;
-            const streamUsage = { input_tokens: 0, output_tokens: 0 };
-            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) {
-                        const elapsed = Date.now() - overallStartTime;
-                        // Asymptotic curve: fast early progress that slows as it approaches max
-                        const progress = Math.round(minPercent +
-                            (maxPercent - minPercent - 5) *
-                                (1 - Math.exp(-elapsed / expectedDurationMs)));
+            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: "Generating content...",
-                            progress: Math.min(progress, maxPercent - 5),
+                            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));
@@ -915,8 +1099,28 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         let activeMessages = messagesToSend;
         let attempt = 0;
         while (true) {
-            assertQuotaAvailable();
-            const response = await llm.invoke(activeMessages);
+            // 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 {
+                    assertQuotaAvailable();
+                    response = await llm.invoke(activeMessages);
+                    break;
+                }
+                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;
+                    }
+                    throw err;
+                }
+            }
             recordCost(calculateTextCost(modelName, extractUsageFromInvoke(response), config));
             const rawContent = response?.content || response;
             // If not expecting JSON, return raw content directly
@@ -941,47 +1145,6 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         }
     }
 };
-/**
- * Sends a conversational chat prompt to an LLM and returns a plain HTML response
- * intended for end-user display. This function is purpose-built for the StackFactor
- * Mentor chat feature: when the prompt is an array of messages, each `system` message
- * is wrapped in an enhanced system prompt that instructs the model to answer only
- * questions related to the provided topic, decline off-topic questions, and return
- * results as simple HTML without markdown code-block notation. The call is delegated to
- * `runPromptWithModel` with `expectsJsonResponse` set to `false`.
- * @param modelName - The model identifier, e.g. `"gpt-4o"`, `"claude-3-5-sonnet"`
- * @param config - Configuration object with API keys and optional `temperature`
- * @param prompt - A plain string user message, or an array of `{ role, content }`
- *   message objects; `system` messages have the topic-constraint wrapper applied
- * @param onProgressReport - Optional callback for streaming progress updates passed
- *   through to `runPromptWithModel`
- * @returns The model's response as a raw HTML string
- */
-const runChatPromptWithModel = (modelName, config, prompt, onProgressReport) => {
-    let messages = prompt;
-    // If prompt is an array, check for system message and enhance it
-    if (Array.isArray(prompt)) {
-        messages = prompt.map((msg) => {
-            if (msg.role === "system") {
-                return {
-                    ...msg,
-                    content: `You are StackFactor Mentor, an AI assistant that helps users by providing information related to the specified topic.
-          
-          ### Objective:
-          Respond to the user question considering just related to the selected topic and all previous interactions:
-          - If the question is unrelated decline to respond.
-          - Return the results as a simple HMTL but don't include notations for formatting blocks.
-          
-          ### TOPIC INFORMATION:\n
-          ${msg.content}
-          `,
-                };
-            }
-            return msg;
-        });
-    }
-    return runPromptWithModel(modelName, config, messages, onProgressReport, 0, 100, false);
-};
 /**
  * Determines the image generation provider for a given model name based on its prefix.
  * `dall-e-` and `gpt-image-` prefixes map to `"openai"`. `gemini-` and `imagen-`
@@ -1243,9 +1406,9 @@ const runPromptWithModelForImageGeneration = async (modelName, config, prompt, o
     }
 };
 exports.default = {
+    checkIfAIProviderConfigured,
     createAgent,
     runAgent,
-    runChatPromptWithModel,
     runPromptWithModel,
     runPromptWithModelForImageGeneration,
     throwErrorIfNotSuccessful,

package/dist/esm/langChain.d.ts

@@ -1,7 +1,7 @@
 declare const _default: {
+    checkIfAIProviderConfigured: (config: any) => void;
     createAgent: (name: string, modelName: string, systemPrompt: string, tools: any[], responseFormat: any, config: any) => any;
     runAgent: (agent: any, prompt: string, config: any, onProgress?: Function | null) => Promise<any>;
-    runChatPromptWithModel: (modelName: string, config: any, prompt: any, onProgressReport: any) => any;
     runPromptWithModel: (modelName: string, config: any, prompt: any, onProgressReport: any, minPercent?: number, maxPercent?: number, expectsJsonResponse?: boolean, schema?: any, agentName?: string, tools?: any[]) => Promise<any>;
     runPromptWithModelForImageGeneration: (modelName: string, config: any, prompt: string, options?: any) => Promise<any>;
     throwErrorIfNotSuccessful: (response: any) => string;

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;wCAkkBF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,KACpB,GAAG;oCA7XO,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;sDAyrBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,KACX,OAAO,CAAC,GAAG,CAAC;0CA30B8B,GAAG,KAAG,MAAM;;AAs4BzD,wBAOE"}
+{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":";0CAgD6C,GAAG,KAAG,IAAI;wBAke/C,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;oCAqWF,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;sDA6rBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,KACX,OAAO,CAAC,GAAG,CAAC;0CA18B8B,GAAG,KAAG,MAAM;;AAqgCzD,wBAOE"}

package/dist/esm/langChain.js

@@ -31,6 +31,14 @@ const assertQuotaAvailable = () => {
         throw errorHandlingHelper.create(constants.HTTP_CODES.PAYMENT_REQUIRED, constants.ERROR.QUOTA_EXHAUSTED);
     }
 };
+const checkIfAIProviderConfigured = (config) => {
+    if (!config ||
+        !config.openAIAPIKey ||
+        !config.googleAPIKey ||
+        !config.anthropicAPIKey) {
+        throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, "The integration is not properly configured with all AI providers.");
+    }
+};
 /**
  * Subtracts the given USD cost from `global.quota.remaining` and adds it to
  * `global.quota.usedThisSession`. Silently no-ops when the quota globals are not
@@ -517,14 +525,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;
@@ -547,6 +585,122 @@ const throwErrorIfNotSuccessful = (response) => {
     }
 };
 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
@@ -807,29 +961,59 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         const expectedDurationMs = 15_000; // Tune: expected typical response time
         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;
-            const streamUsage = { input_tokens: 0, output_tokens: 0 };
-            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) {
-                        const elapsed = Date.now() - overallStartTime;
-                        // Asymptotic curve: fast early progress that slows as it approaches max
-                        const progress = Math.round(minPercent +
-                            (maxPercent - minPercent - 5) *
-                                (1 - Math.exp(-elapsed / expectedDurationMs)));
+            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: "Generating content...",
-                            progress: Math.min(progress, maxPercent - 5),
+                            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));
@@ -910,8 +1094,28 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         let activeMessages = messagesToSend;
         let attempt = 0;
         while (true) {
-            assertQuotaAvailable();
-            const response = await llm.invoke(activeMessages);
+            // 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 {
+                    assertQuotaAvailable();
+                    response = await llm.invoke(activeMessages);
+                    break;
+                }
+                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;
+                    }
+                    throw err;
+                }
+            }
             recordCost(calculateTextCost(modelName, extractUsageFromInvoke(response), config));
             const rawContent = response?.content || response;
             // If not expecting JSON, return raw content directly
@@ -936,47 +1140,6 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         }
     }
 };
-/**
- * Sends a conversational chat prompt to an LLM and returns a plain HTML response
- * intended for end-user display. This function is purpose-built for the StackFactor
- * Mentor chat feature: when the prompt is an array of messages, each `system` message
- * is wrapped in an enhanced system prompt that instructs the model to answer only
- * questions related to the provided topic, decline off-topic questions, and return
- * results as simple HTML without markdown code-block notation. The call is delegated to
- * `runPromptWithModel` with `expectsJsonResponse` set to `false`.
- * @param modelName - The model identifier, e.g. `"gpt-4o"`, `"claude-3-5-sonnet"`
- * @param config - Configuration object with API keys and optional `temperature`
- * @param prompt - A plain string user message, or an array of `{ role, content }`
- *   message objects; `system` messages have the topic-constraint wrapper applied
- * @param onProgressReport - Optional callback for streaming progress updates passed
- *   through to `runPromptWithModel`
- * @returns The model's response as a raw HTML string
- */
-const runChatPromptWithModel = (modelName, config, prompt, onProgressReport) => {
-    let messages = prompt;
-    // If prompt is an array, check for system message and enhance it
-    if (Array.isArray(prompt)) {
-        messages = prompt.map((msg) => {
-            if (msg.role === "system") {
-                return {
-                    ...msg,
-                    content: `You are StackFactor Mentor, an AI assistant that helps users by providing information related to the specified topic.
-          
-          ### Objective:
-          Respond to the user question considering just related to the selected topic and all previous interactions:
-          - If the question is unrelated decline to respond.
-          - Return the results as a simple HMTL but don't include notations for formatting blocks.
-          
-          ### TOPIC INFORMATION:\n
-          ${msg.content}
-          `,
-                };
-            }
-            return msg;
-        });
-    }
-    return runPromptWithModel(modelName, config, messages, onProgressReport, 0, 100, false);
-};
 /**
  * Determines the image generation provider for a given model name based on its prefix.
  * `dall-e-` and `gpt-image-` prefixes map to `"openai"`. `gemini-` and `imagen-`
@@ -1238,9 +1401,9 @@ const runPromptWithModelForImageGeneration = async (modelName, config, prompt, o
     }
 };
 export default {
+    checkIfAIProviderConfigured,
     createAgent,
     runAgent,
-    runChatPromptWithModel,
     runPromptWithModel,
     runPromptWithModelForImageGeneration,
     throwErrorIfNotSuccessful,

package/package.json

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