@stackfactor/agent-utils 1.2.6 → 1.2.7

package/README.md

@@ -27,7 +27,7 @@ import {
 
 Unified interface for running LLM prompts, managing LangChain agents, and generating images across OpenAI, Anthropic, Google, DeepSeek, Kimi (Moonshot), and GLM (Zhipu) providers.
 
-### `langChain.runPromptWithModel(modelName, config, prompt, onProgressReport?, minPercent?, maxPercent?, expectsJsonResponse?, schema?, agentName?, tools?)`
+### `langChain.runPromptWithModel(modelName, config, prompt, onProgressReport?, minPercent?, maxPercent?, expectsJsonResponse?, schema?, agentName?, tools?, usageTracker?)`
 
 Sends a prompt to an LLM and returns the response. Supports three execution modes:
 
@@ -49,15 +49,33 @@ When `expectsJsonResponse` is `true` (the default), JSON escape instructions are
 | `schema`              | `ZodSchema \| null`  | `null`          | Zod schema for response validation                                                                       |
 | `agentName`           | `string`             | `"StackFactor"` | Display name for the agent (agentic mode)                                                                |
 | `tools`               | `any[]`              | `[]`            | LangChain tools available to the agent (agentic mode)                                                    |
+| `usageTracker`        | `UsageTracker \| null` | `null`        | Optional accumulator updated on every successful LLM call with `cost` (USD) and per-model token counts.  |
 
 **Returns:** JSON string (when `expectsJsonResponse` is `true`) or raw content string.
 
 ```typescript
+const usageTracker = {};
 const result = await langChain.runPromptWithModel(
   "gpt-4o",
   { openAIAPIKey: "sk-..." },
   "Generate a summary of this document.",
+  null,
+  0,
+  100,
+  true,
+  null,
+  "StackFactor",
+  [],
+  usageTracker,
 );
+// usageTracker is now:
+// {
+//   cost: 0.00123,
+//   tokens: {
+//     "gpt-4o_inputTokens": 412,
+//     "gpt-4o_outputTokens": 87,
+//   }
+// }
 ```
 
 ---

package/dist/cjs/index.d.ts

@@ -9,6 +9,7 @@ export { constants };
 export { errorHandling, AppError };
 export type { ParsedError } from "./errorHandling.js";
 export { langChain };
+export type { UsageTracker } from "./langChain.js";
 export { logger };
 export { serve };
 export { callAgent };

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;AAEnC,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;AAEnC,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/cjs/langChain.d.ts

@@ -1,8 +1,20 @@
+/**
+ * Accumulated usage and cost for a single agent run. Callers initialize an
+ * empty object (`{}`) and pass it through `runPromptWithModel`; helpers
+ * populate `cost` (USD total across all models) and per-model
+ * `<model>_inputTokens` / `<model>_outputTokens` counters under `tokens`.
+ */
+export type UsageTracker = {
+    cost: number;
+    tokens: {
+        [tokenKey: string]: number;
+    };
+};
 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>;
-    runPromptWithModel: (modelName: string, config: any, prompt: any, onProgressReport: any, minPercent?: number, maxPercent?: number, expectsJsonResponse?: boolean, schema?: any, agentName?: string, tools?: any[]) => Promise<any>;
+    runAgent: (agent: any, prompt: string, config: any, onProgress?: Function | null, usageTracker?: UsageTracker | null) => Promise<any>;
+    runPromptWithModel: (modelName: string, config: any, prompt: any, onProgressReport: any, minPercent?: number, maxPercent?: number, expectsJsonResponse?: boolean, schema?: any, agentName?: string, tools?: any[], usageTracker?: UsageTracker | null) => Promise<any>;
     runPromptWithModelForImageGeneration: (modelName: string, config: any, prompt: string, options?: any) => Promise<any>;
     throwErrorIfNotSuccessful: (response: any) => string;
     validateModel: (selectedModel: string, supportedModels: string[]) => string;

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

@@ -1 +1 @@
-{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":";0CAiD6C,GAAG,KAAG,IAAI;wBA0hB/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;oCAqXF,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;sDAosBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,KACX,OAAO,CAAC,GAAG,CAAC;0CAn+B8B,GAAG,KAAG,MAAM;mCAoBxC,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AAwgCT,wBAQE"}
+{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AA2BA;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CACxC,CAAC;;0CAE2C,GAAG,KAAG,IAAI;wBAkd/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,KACV,GAAG;sBA0BG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,iBACb,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;oCA4XF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDAmsBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,KACX,OAAO,CAAC,GAAG,CAAC;0CAt+B8B,GAAG,KAAG,MAAM;mCAoBxC,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AA2gCT,wBAQE"}

package/dist/cjs/langChain.js

@@ -23,20 +23,6 @@ CRITICAL - Your response must be valid JSON. Escape ALL special characters in st
 - Backslashes → \\\\
 Do NOT include raw newlines, tabs, or unescaped quotes inside JSON string values.
 `.trim();
-/**
- * Reads `global.quota` (set by the StackFactor host before invoking `main()`) and
- * throws a `PAYMENT_REQUIRED` error when the session has no remaining budget. No-op
- * when `global.quota` is absent (e.g. local tests) or `remaining` is not a number,
- * which keeps the library usable outside the StackFactor runtime.
- */
-const assertQuotaAvailable = () => {
-    const quota = globalThis.quota;
-    if (!quota || typeof quota.remaining !== "number")
-        return;
-    if (quota.remaining <= 0) {
-        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 ||
@@ -45,104 +31,42 @@ const checkIfAIProviderConfigured = (config) => {
         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
- * present so callers do not need to branch. Negative, zero, or non-finite costs
- * are ignored to keep counters monotonic.
- */
-const recordCost = (cost) => {
-    if (!cost || cost <= 0 || !Number.isFinite(cost))
-        return;
-    const quota = globalThis.quota;
-    if (!quota)
-        return;
-    if (typeof quota.remaining === "number") {
-        quota.remaining -= cost;
-    }
-    if (typeof quota.usedThisSession === "number") {
-        quota.usedThisSession += cost;
-    }
-    else {
-        quota.usedThisSession = cost;
-    }
-};
 /**
  * Reads a per-model rate from the flat cost constants the integration defines
  * in its `config.yaml` (exposed on the config object), e.g.
- * `claude-opus-4-7-input-token-costs`. Returns `null` when the constant is
- * absent or not numeric, in which case cost recording becomes a no-op (the
- * call still succeeds — pricing is the integration's configuration concern).
+ * `claude-opus-4-7-input-token-costs`. Returns `0` when the constant is
+ * absent or not numeric, which leaves cost contribution zero.
  */
 const getModelRate = (modelName, config, kind) => {
     if (!config || !modelName)
-        return null;
+        return 0;
     const rate = Number(config[`${modelName}-${kind}-costs`]);
-    return Number.isFinite(rate) ? rate : null;
+    return Number.isFinite(rate) ? rate : 0;
 };
 /**
- * Accumulates the per-model usage breakdown on `global.quota.byModel` so the
- * agent can report input/output token counts and image spend per model to the
- * UI. No-ops when the quota global is absent.
+ * Adds a single call's usage to the caller-supplied tracker. Initializes
+ * `cost` and `tokens` lazily so callers can pass `{}`. No-ops when the
+ * tracker is null/undefined.
  */
-const recordModelBreakdown = (modelName, inputCost, outputCost, imageCost, inputTokens = 0, outputTokens = 0) => {
-    const quota = globalThis.quota;
-    if (!quota || !modelName)
+const updateUsageTracker = (tracker, modelName, usage, config) => {
+    if (!tracker || !usage || !modelName)
         return;
-    if (!quota.byModel || typeof quota.byModel !== "object")
-        quota.byModel = {};
-    const entry = (quota.byModel[modelName] ||= {
-        inputCost: 0,
-        outputCost: 0,
-        imageCost: 0,
-        inputTokens: 0,
-        outputTokens: 0,
-    });
-    // Entries created by older versions of this module lack the token counters.
-    if (typeof entry.inputTokens !== "number")
-        entry.inputTokens = 0;
-    if (typeof entry.outputTokens !== "number")
-        entry.outputTokens = 0;
-    if (Number.isFinite(inputCost) && inputCost > 0)
-        entry.inputCost += inputCost;
-    if (Number.isFinite(outputCost) && outputCost > 0)
-        entry.outputCost += outputCost;
-    if (Number.isFinite(imageCost) && imageCost > 0)
-        entry.imageCost += imageCost;
-    if (Number.isFinite(inputTokens) && inputTokens > 0)
-        entry.inputTokens += inputTokens;
-    if (Number.isFinite(outputTokens) && outputTokens > 0)
-        entry.outputTokens += outputTokens;
-};
-/**
- * Computes and records the USD cost of a text LLM call from the
- * `<model>-input-token-costs` / `<model>-output-token-costs` constants
- * (dollars per million tokens). Updates both the session total
- * (`quota.usedThisSession` / `quota.remaining`) and the per-model breakdown
- * (`quota.byModel`).
- */
-const recordTextCost = (modelName, usage, config) => {
-    if (!usage)
-        return;
-    const inputRate = getModelRate(modelName, config, "input-token") || 0;
-    const outputRate = getModelRate(modelName, config, "output-token") || 0;
+    if (typeof tracker.cost !== "number")
+        tracker.cost = 0;
+    if (!tracker.tokens || typeof tracker.tokens !== "object")
+        tracker.tokens = {};
     const inputTokens = usage.input_tokens || 0;
     const outputTokens = usage.output_tokens || 0;
-    const inputCost = (inputTokens / 1_000_000) * inputRate;
-    const outputCost = (outputTokens / 1_000_000) * outputRate;
-    recordCost(inputCost + outputCost);
-    recordModelBreakdown(modelName, inputCost, outputCost, 0, inputTokens, outputTokens);
-};
-/**
- * Computes and records the USD cost of an image generation call from the
- * `<model>-image-costs` constant (dollars per generated image). Updates both
- * the session total and the per-model breakdown.
- */
-const recordImageCost = (modelName, numImages, config) => {
-    const rate = getModelRate(modelName, config, "image") || 0;
-    const imageCost = (numImages || 0) * rate;
-    recordCost(imageCost);
-    recordModelBreakdown(modelName, 0, 0, imageCost);
+    const inputRate = getModelRate(modelName, config, "input-token");
+    const outputRate = getModelRate(modelName, config, "output-token");
+    const addedCost = (inputTokens / 1_000_000) * inputRate +
+        (outputTokens / 1_000_000) * outputRate;
+    if (Number.isFinite(addedCost) && addedCost > 0)
+        tracker.cost += addedCost;
+    const inputKey = `${modelName}_inputTokens`;
+    const outputKey = `${modelName}_outputTokens`;
+    tracker.tokens[inputKey] = (tracker.tokens[inputKey] || 0) + inputTokens;
+    tracker.tokens[outputKey] = (tracker.tokens[outputKey] || 0) + outputTokens;
 };
 /**
  * Extracts a normalized token-usage object from a single LangChain `invoke()`
@@ -541,9 +465,10 @@ const createAgent = (name, modelName, systemPrompt, tools = [], responseFormat,
  *   number of agent steps (defaults to `25` when not specified)
  * @param onProgress - Optional callback invoked with progress event objects throughout
  *   agent execution
+ * @param usageTracker - Optional usage accumulator updated on successful completion
  * @returns The raw response object returned by the agent's `invoke` method
  */
-const runAgent = async (agent, prompt, config, onProgress = null) => {
+const runAgent = async (agent, prompt, config, onProgress = null, usageTracker = null) => {
     const startTime = Date.now();
     const callbacks = onProgress
         ? [
@@ -578,13 +503,12 @@ const runAgent = async (agent, prompt, config, onProgress = null) => {
     // 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
+    // the agent state isn't externally checkpointed. Usage 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 }],
             }, {
@@ -611,7 +535,7 @@ const runAgent = async (agent, prompt, config, onProgress = null) => {
             throw err;
         }
     }
-    recordTextCost(modelName, sumAgentResponseUsage(response), config);
+    updateUsageTracker(usageTracker, modelName, sumAgentResponseUsage(response), config);
     const endTime = Date.now();
     const duration = endTime - startTime;
     logger_js_1.default.log(null, logger_js_1.default.levels.info, `Agent "${agent.options?.name}" completed in ${Math.round(duration / 1000)} seconds.`);
@@ -866,10 +790,13 @@ const buildValidationRetryMessages = (priorMessages, rawContent, validationError
  *   `"StackFactor"`
  * @param tools - Additional LangChain tools available to the agent in agentic mode;
  *   defaults to an empty array
+ * @param usageTracker - Optional accumulator updated with `cost` and per-model token
+ *   counts for every successful LLM call. Callers should initialise as `{}` before
+ *   the run and read the populated values after.
  * @returns The LLM response as a JSON string (when `expectsJsonResponse` is `true`) or
  *   as raw content (when `false`)
  */
-const runPromptWithModel = async (modelName, config, prompt, onProgressReport, minPercent = 0, maxPercent = 100, expectsJsonResponse = true, schema = null, agentName = "StackFactor", tools = []) => {
+const runPromptWithModel = async (modelName, config, prompt, onProgressReport, minPercent = 0, maxPercent = 100, expectsJsonResponse = true, schema = null, agentName = "StackFactor", tools = [], usageTracker = null) => {
     // Agentic mode: use an agent with tools instead of simple LLM invocation
     if (config.agentic === true) {
         // Extract system prompt and user prompt from the prompt parameter
@@ -903,7 +830,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         const agent = createAgent(agentName, modelName, systemPrompt, [...tools], null, // responseFormat
         config);
         // Run the agent with progress callback
-        const response = await runAgent(agent, userPrompt, config, onProgressReport || null);
+        const response = await runAgent(agent, userPrompt, config, onProgressReport || null, usageTracker);
         // Extract content from agent response
         const messages = response?.messages || [];
         if (messages.length === 0) {
@@ -1012,8 +939,8 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         // 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.
+        // server-side schema bug, not a model output issue). Each attempt accumulates
+        // independently into usageTracker so retry usage is still visible.
         const canRetryOnValidation = expectsJsonResponse && !!schema && !useNativeSchema;
         const progressReportInterval = 10; // Report every N chunks
         const overallStartTime = Date.now();
@@ -1034,16 +961,15 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
             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.
+            // Usage is only recorded on a successful stream — partial streams that
+            // error out with a rate limit are not counted. 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();
                     // Honour caller cancellation: passing the signal tears down the
                     // upstream HTTP request so a cancelled call stops billing tokens.
                     const abortSignal = (0, runtimeContext_js_1.getAbortSignal)();
@@ -1086,7 +1012,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                     throw err;
                 }
             }
-            recordTextCost(modelName, streamUsage, config);
+            updateUsageTracker(usageTracker, modelName, streamUsage, config);
             if (!rawContent) {
                 throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, "LLM returned no content");
             }
@@ -1159,7 +1085,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
             messagesToSend = messages;
         }
         // Retry once on schema validation failure (see streaming branch for rationale).
-        // Each attempt is billed independently via recordCost so retry cost is visible.
+        // Each attempt accumulates independently into usageTracker.
         const canRetryOnValidation = expectsJsonResponse && !!schema && !useNativeSchema;
         let activeMessages = messagesToSend;
         let attempt = 0;
@@ -1170,7 +1096,6 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
             let rateLimitAttempt = 0;
             while (true) {
                 try {
-                    assertQuotaAvailable();
                     response = await llm.invoke(activeMessages);
                     break;
                 }
@@ -1186,7 +1111,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                     throw err;
                 }
             }
-            recordTextCost(modelName, extractUsageFromInvoke(response), config);
+            updateUsageTracker(usageTracker, modelName, extractUsageFromInvoke(response), config);
             const rawContent = response?.content || response;
             // If not expecting JSON, return raw content directly
             if (!expectsJsonResponse) {
@@ -1292,9 +1217,7 @@ const generateImageWithOpenAI = async (modelName, config, prompt, options) => {
             requestParams.style = style;
         }
     }
-    assertQuotaAvailable();
     const response = await openai.images.generate(requestParams);
-    recordImageCost(modelName, response.data?.length || n, config);
     // Format response based on number of images
     if (n === 1) {
         const imageData = response.data[0];
@@ -1392,7 +1315,6 @@ const generateImageWithGoogle = async (modelName, config, prompt, options) => {
             safetySettings: safetySettings,
         },
     };
-    assertQuotaAvailable();
     const response = await ai.models.generateContent(req);
     // Extract images from response
     const images = [];
@@ -1411,7 +1333,6 @@ const generateImageWithGoogle = async (modelName, config, prompt, options) => {
     if (images.length === 0) {
         throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, `No images were generated by ${modelName}`);
     }
-    recordImageCost(modelName, images.length, config);
     if (numberOfImages === 1 || images.length === 1) {
         return images[0];
     }

package/dist/esm/index.d.ts

@@ -9,6 +9,7 @@ export { constants };
 export { errorHandling, AppError };
 export type { ParsedError } from "./errorHandling.js";
 export { langChain };
+export type { UsageTracker } from "./langChain.js";
 export { logger };
 export { serve };
 export { callAgent };

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;AAEnC,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;AAEnC,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/esm/langChain.d.ts

@@ -1,8 +1,20 @@
+/**
+ * Accumulated usage and cost for a single agent run. Callers initialize an
+ * empty object (`{}`) and pass it through `runPromptWithModel`; helpers
+ * populate `cost` (USD total across all models) and per-model
+ * `<model>_inputTokens` / `<model>_outputTokens` counters under `tokens`.
+ */
+export type UsageTracker = {
+    cost: number;
+    tokens: {
+        [tokenKey: string]: number;
+    };
+};
 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>;
-    runPromptWithModel: (modelName: string, config: any, prompt: any, onProgressReport: any, minPercent?: number, maxPercent?: number, expectsJsonResponse?: boolean, schema?: any, agentName?: string, tools?: any[]) => Promise<any>;
+    runAgent: (agent: any, prompt: string, config: any, onProgress?: Function | null, usageTracker?: UsageTracker | null) => Promise<any>;
+    runPromptWithModel: (modelName: string, config: any, prompt: any, onProgressReport: any, minPercent?: number, maxPercent?: number, expectsJsonResponse?: boolean, schema?: any, agentName?: string, tools?: any[], usageTracker?: UsageTracker | null) => Promise<any>;
     runPromptWithModelForImageGeneration: (modelName: string, config: any, prompt: string, options?: any) => Promise<any>;
     throwErrorIfNotSuccessful: (response: any) => string;
     validateModel: (selectedModel: string, supportedModels: string[]) => string;

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

@@ -1 +1 @@
-{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":";0CAiD6C,GAAG,KAAG,IAAI;wBA0hB/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;oCAqXF,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;sDAosBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,KACX,OAAO,CAAC,GAAG,CAAC;0CAn+B8B,GAAG,KAAG,MAAM;mCAoBxC,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AAwgCT,wBAQE"}
+{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AA2BA;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CACxC,CAAC;;0CAE2C,GAAG,KAAG,IAAI;wBAkd/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,KACV,GAAG;sBA0BG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,iBACb,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;oCA4XF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDAmsBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,KACX,OAAO,CAAC,GAAG,CAAC;0CAt+B8B,GAAG,KAAG,MAAM;mCAoBxC,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AA2gCT,wBAQE"}

package/dist/esm/langChain.js

@@ -18,20 +18,6 @@ CRITICAL - Your response must be valid JSON. Escape ALL special characters in st
 - Backslashes → \\\\
 Do NOT include raw newlines, tabs, or unescaped quotes inside JSON string values.
 `.trim();
-/**
- * Reads `global.quota` (set by the StackFactor host before invoking `main()`) and
- * throws a `PAYMENT_REQUIRED` error when the session has no remaining budget. No-op
- * when `global.quota` is absent (e.g. local tests) or `remaining` is not a number,
- * which keeps the library usable outside the StackFactor runtime.
- */
-const assertQuotaAvailable = () => {
-    const quota = globalThis.quota;
-    if (!quota || typeof quota.remaining !== "number")
-        return;
-    if (quota.remaining <= 0) {
-        throw errorHandlingHelper.create(constants.HTTP_CODES.PAYMENT_REQUIRED, constants.ERROR.QUOTA_EXHAUSTED);
-    }
-};
 const checkIfAIProviderConfigured = (config) => {
     if (!config ||
         !config.openAIAPIKey ||
@@ -40,104 +26,42 @@ const checkIfAIProviderConfigured = (config) => {
         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
- * present so callers do not need to branch. Negative, zero, or non-finite costs
- * are ignored to keep counters monotonic.
- */
-const recordCost = (cost) => {
-    if (!cost || cost <= 0 || !Number.isFinite(cost))
-        return;
-    const quota = globalThis.quota;
-    if (!quota)
-        return;
-    if (typeof quota.remaining === "number") {
-        quota.remaining -= cost;
-    }
-    if (typeof quota.usedThisSession === "number") {
-        quota.usedThisSession += cost;
-    }
-    else {
-        quota.usedThisSession = cost;
-    }
-};
 /**
  * Reads a per-model rate from the flat cost constants the integration defines
  * in its `config.yaml` (exposed on the config object), e.g.
- * `claude-opus-4-7-input-token-costs`. Returns `null` when the constant is
- * absent or not numeric, in which case cost recording becomes a no-op (the
- * call still succeeds — pricing is the integration's configuration concern).
+ * `claude-opus-4-7-input-token-costs`. Returns `0` when the constant is
+ * absent or not numeric, which leaves cost contribution zero.
  */
 const getModelRate = (modelName, config, kind) => {
     if (!config || !modelName)
-        return null;
+        return 0;
     const rate = Number(config[`${modelName}-${kind}-costs`]);
-    return Number.isFinite(rate) ? rate : null;
+    return Number.isFinite(rate) ? rate : 0;
 };
 /**
- * Accumulates the per-model usage breakdown on `global.quota.byModel` so the
- * agent can report input/output token counts and image spend per model to the
- * UI. No-ops when the quota global is absent.
+ * Adds a single call's usage to the caller-supplied tracker. Initializes
+ * `cost` and `tokens` lazily so callers can pass `{}`. No-ops when the
+ * tracker is null/undefined.
  */
-const recordModelBreakdown = (modelName, inputCost, outputCost, imageCost, inputTokens = 0, outputTokens = 0) => {
-    const quota = globalThis.quota;
-    if (!quota || !modelName)
+const updateUsageTracker = (tracker, modelName, usage, config) => {
+    if (!tracker || !usage || !modelName)
         return;
-    if (!quota.byModel || typeof quota.byModel !== "object")
-        quota.byModel = {};
-    const entry = (quota.byModel[modelName] ||= {
-        inputCost: 0,
-        outputCost: 0,
-        imageCost: 0,
-        inputTokens: 0,
-        outputTokens: 0,
-    });
-    // Entries created by older versions of this module lack the token counters.
-    if (typeof entry.inputTokens !== "number")
-        entry.inputTokens = 0;
-    if (typeof entry.outputTokens !== "number")
-        entry.outputTokens = 0;
-    if (Number.isFinite(inputCost) && inputCost > 0)
-        entry.inputCost += inputCost;
-    if (Number.isFinite(outputCost) && outputCost > 0)
-        entry.outputCost += outputCost;
-    if (Number.isFinite(imageCost) && imageCost > 0)
-        entry.imageCost += imageCost;
-    if (Number.isFinite(inputTokens) && inputTokens > 0)
-        entry.inputTokens += inputTokens;
-    if (Number.isFinite(outputTokens) && outputTokens > 0)
-        entry.outputTokens += outputTokens;
-};
-/**
- * Computes and records the USD cost of a text LLM call from the
- * `<model>-input-token-costs` / `<model>-output-token-costs` constants
- * (dollars per million tokens). Updates both the session total
- * (`quota.usedThisSession` / `quota.remaining`) and the per-model breakdown
- * (`quota.byModel`).
- */
-const recordTextCost = (modelName, usage, config) => {
-    if (!usage)
-        return;
-    const inputRate = getModelRate(modelName, config, "input-token") || 0;
-    const outputRate = getModelRate(modelName, config, "output-token") || 0;
+    if (typeof tracker.cost !== "number")
+        tracker.cost = 0;
+    if (!tracker.tokens || typeof tracker.tokens !== "object")
+        tracker.tokens = {};
     const inputTokens = usage.input_tokens || 0;
     const outputTokens = usage.output_tokens || 0;
-    const inputCost = (inputTokens / 1_000_000) * inputRate;
-    const outputCost = (outputTokens / 1_000_000) * outputRate;
-    recordCost(inputCost + outputCost);
-    recordModelBreakdown(modelName, inputCost, outputCost, 0, inputTokens, outputTokens);
-};
-/**
- * Computes and records the USD cost of an image generation call from the
- * `<model>-image-costs` constant (dollars per generated image). Updates both
- * the session total and the per-model breakdown.
- */
-const recordImageCost = (modelName, numImages, config) => {
-    const rate = getModelRate(modelName, config, "image") || 0;
-    const imageCost = (numImages || 0) * rate;
-    recordCost(imageCost);
-    recordModelBreakdown(modelName, 0, 0, imageCost);
+    const inputRate = getModelRate(modelName, config, "input-token");
+    const outputRate = getModelRate(modelName, config, "output-token");
+    const addedCost = (inputTokens / 1_000_000) * inputRate +
+        (outputTokens / 1_000_000) * outputRate;
+    if (Number.isFinite(addedCost) && addedCost > 0)
+        tracker.cost += addedCost;
+    const inputKey = `${modelName}_inputTokens`;
+    const outputKey = `${modelName}_outputTokens`;
+    tracker.tokens[inputKey] = (tracker.tokens[inputKey] || 0) + inputTokens;
+    tracker.tokens[outputKey] = (tracker.tokens[outputKey] || 0) + outputTokens;
 };
 /**
  * Extracts a normalized token-usage object from a single LangChain `invoke()`
@@ -536,9 +460,10 @@ const createAgent = (name, modelName, systemPrompt, tools = [], responseFormat,
  *   number of agent steps (defaults to `25` when not specified)
  * @param onProgress - Optional callback invoked with progress event objects throughout
  *   agent execution
+ * @param usageTracker - Optional usage accumulator updated on successful completion
  * @returns The raw response object returned by the agent's `invoke` method
  */
-const runAgent = async (agent, prompt, config, onProgress = null) => {
+const runAgent = async (agent, prompt, config, onProgress = null, usageTracker = null) => {
     const startTime = Date.now();
     const callbacks = onProgress
         ? [
@@ -573,13 +498,12 @@ const runAgent = async (agent, prompt, config, onProgress = null) => {
     // 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
+    // the agent state isn't externally checkpointed. Usage 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 }],
             }, {
@@ -606,7 +530,7 @@ const runAgent = async (agent, prompt, config, onProgress = null) => {
             throw err;
         }
     }
-    recordTextCost(modelName, sumAgentResponseUsage(response), config);
+    updateUsageTracker(usageTracker, modelName, sumAgentResponseUsage(response), config);
     const endTime = Date.now();
     const duration = endTime - startTime;
     logger.log(null, logger.levels.info, `Agent "${agent.options?.name}" completed in ${Math.round(duration / 1000)} seconds.`);
@@ -861,10 +785,13 @@ const buildValidationRetryMessages = (priorMessages, rawContent, validationError
  *   `"StackFactor"`
  * @param tools - Additional LangChain tools available to the agent in agentic mode;
  *   defaults to an empty array
+ * @param usageTracker - Optional accumulator updated with `cost` and per-model token
+ *   counts for every successful LLM call. Callers should initialise as `{}` before
+ *   the run and read the populated values after.
  * @returns The LLM response as a JSON string (when `expectsJsonResponse` is `true`) or
  *   as raw content (when `false`)
  */
-const runPromptWithModel = async (modelName, config, prompt, onProgressReport, minPercent = 0, maxPercent = 100, expectsJsonResponse = true, schema = null, agentName = "StackFactor", tools = []) => {
+const runPromptWithModel = async (modelName, config, prompt, onProgressReport, minPercent = 0, maxPercent = 100, expectsJsonResponse = true, schema = null, agentName = "StackFactor", tools = [], usageTracker = null) => {
     // Agentic mode: use an agent with tools instead of simple LLM invocation
     if (config.agentic === true) {
         // Extract system prompt and user prompt from the prompt parameter
@@ -898,7 +825,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         const agent = createAgent(agentName, modelName, systemPrompt, [...tools], null, // responseFormat
         config);
         // Run the agent with progress callback
-        const response = await runAgent(agent, userPrompt, config, onProgressReport || null);
+        const response = await runAgent(agent, userPrompt, config, onProgressReport || null, usageTracker);
         // Extract content from agent response
         const messages = response?.messages || [];
         if (messages.length === 0) {
@@ -1007,8 +934,8 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         // 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.
+        // server-side schema bug, not a model output issue). Each attempt accumulates
+        // independently into usageTracker so retry usage is still visible.
         const canRetryOnValidation = expectsJsonResponse && !!schema && !useNativeSchema;
         const progressReportInterval = 10; // Report every N chunks
         const overallStartTime = Date.now();
@@ -1029,16 +956,15 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
             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.
+            // Usage is only recorded on a successful stream — partial streams that
+            // error out with a rate limit are not counted. 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();
                     // Honour caller cancellation: passing the signal tears down the
                     // upstream HTTP request so a cancelled call stops billing tokens.
                     const abortSignal = getAbortSignal();
@@ -1081,7 +1007,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                     throw err;
                 }
             }
-            recordTextCost(modelName, streamUsage, config);
+            updateUsageTracker(usageTracker, modelName, streamUsage, config);
             if (!rawContent) {
                 throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, "LLM returned no content");
             }
@@ -1154,7 +1080,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
             messagesToSend = messages;
         }
         // Retry once on schema validation failure (see streaming branch for rationale).
-        // Each attempt is billed independently via recordCost so retry cost is visible.
+        // Each attempt accumulates independently into usageTracker.
         const canRetryOnValidation = expectsJsonResponse && !!schema && !useNativeSchema;
         let activeMessages = messagesToSend;
         let attempt = 0;
@@ -1165,7 +1091,6 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
             let rateLimitAttempt = 0;
             while (true) {
                 try {
-                    assertQuotaAvailable();
                     response = await llm.invoke(activeMessages);
                     break;
                 }
@@ -1181,7 +1106,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                     throw err;
                 }
             }
-            recordTextCost(modelName, extractUsageFromInvoke(response), config);
+            updateUsageTracker(usageTracker, modelName, extractUsageFromInvoke(response), config);
             const rawContent = response?.content || response;
             // If not expecting JSON, return raw content directly
             if (!expectsJsonResponse) {
@@ -1287,9 +1212,7 @@ const generateImageWithOpenAI = async (modelName, config, prompt, options) => {
             requestParams.style = style;
         }
     }
-    assertQuotaAvailable();
     const response = await openai.images.generate(requestParams);
-    recordImageCost(modelName, response.data?.length || n, config);
     // Format response based on number of images
     if (n === 1) {
         const imageData = response.data[0];
@@ -1387,7 +1310,6 @@ const generateImageWithGoogle = async (modelName, config, prompt, options) => {
             safetySettings: safetySettings,
         },
     };
-    assertQuotaAvailable();
     const response = await ai.models.generateContent(req);
     // Extract images from response
     const images = [];
@@ -1406,7 +1328,6 @@ const generateImageWithGoogle = async (modelName, config, prompt, options) => {
     if (images.length === 0) {
         throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, `No images were generated by ${modelName}`);
     }
-    recordImageCost(modelName, images.length, config);
     if (numberOfImages === 1 || images.length === 1) {
         return images[0];
     }

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.2.6",
+  "version": "1.2.7",
   "description": "",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",