@stackfactor/agent-utils 1.2.6 → 1.2.8

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,10 +1,23 @@
+/**
+ * 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>;
-    runPromptWithModelForImageGeneration: (modelName: string, config: any, prompt: string, options?: 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, usageTracker?: UsageTracker | null) => Promise<any>;
     throwErrorIfNotSuccessful: (response: any) => string;
+    updateUsageTrackerForCharacters: (tracker: UsageTracker | null | undefined, modelName: string, characterCount: number, config: any) => void;
     validateModel: (selectedModel: string, supportedModels: string[]) => string;
 };
 export default _default;

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;wBA+jB/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;sDAusBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CA3+B8B,GAAG,KAAG,MAAM;+CApjB9C,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,kBACD,MAAM,UACd,GAAG,KACV,IAAI;mCAokBU,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AAkhCT,wBASE"}

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,137 @@ 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;
+    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 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;
 };
 /**
- * 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`).
+ * Adds a single image-generation call's usage to the caller-supplied tracker.
+ * Extracts token counts from provider-specific response shapes: OpenAI returns
+ * `response.usage` with `input_tokens_details.{text_tokens,image_tokens}` and
+ * `output_tokens`; Google returns `response.usageMetadata` with
+ * `promptTokensDetails` (modality-keyed) and `candidatesTokenCount` for the
+ * generated image. Reads rates from `<model>-input-token-costs`,
+ * `<model>-image-input-token-costs`, and `<model>-image-output-token-costs`.
+ * No-ops when the tracker or response usage info is absent.
  */
-const recordTextCost = (modelName, usage, config) => {
-    if (!usage)
+const updateImageUsageTracker = (tracker, modelName, response, config, provider) => {
+    if (!tracker || !modelName || !response)
         return;
-    const inputRate = getModelRate(modelName, config, "input-token") || 0;
-    const outputRate = getModelRate(modelName, config, "output-token") || 0;
-    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);
+    if (typeof tracker.cost !== "number")
+        tracker.cost = 0;
+    if (!tracker.tokens || typeof tracker.tokens !== "object")
+        tracker.tokens = {};
+    let textInputTokens = 0;
+    let imageInputTokens = 0;
+    let imageOutputTokens = 0;
+    if (provider === "openai") {
+        const usage = response.usage;
+        if (!usage)
+            return;
+        const details = usage.input_tokens_details || {};
+        textInputTokens = details.text_tokens || 0;
+        imageInputTokens = details.image_tokens || 0;
+        // Older shapes report a single input_tokens without modality breakdown.
+        if (!textInputTokens && !imageInputTokens && usage.input_tokens) {
+            textInputTokens = usage.input_tokens;
+        }
+        imageOutputTokens = usage.output_tokens || 0;
+    }
+    else {
+        const um = response.usageMetadata;
+        if (!um)
+            return;
+        const promptDetails = Array.isArray(um.promptTokensDetails)
+            ? um.promptTokensDetails
+            : [];
+        for (const d of promptDetails) {
+            const modality = String(d?.modality || "").toUpperCase();
+            const count = Number(d?.tokenCount) || 0;
+            if (modality === "IMAGE")
+                imageInputTokens += count;
+            else
+                textInputTokens += count;
+        }
+        if (!textInputTokens && !imageInputTokens) {
+            textInputTokens = Number(um.promptTokenCount) || 0;
+        }
+        imageOutputTokens = Number(um.candidatesTokenCount) || 0;
+    }
+    const textInputRate = getModelRate(modelName, config, "input-token");
+    const imageInputRate = getModelRate(modelName, config, "image-input-token");
+    const imageOutputRate = getModelRate(modelName, config, "image-output-token");
+    const addedCost = (textInputTokens / 1_000_000) * textInputRate +
+        (imageInputTokens / 1_000_000) * imageInputRate +
+        (imageOutputTokens / 1_000_000) * imageOutputRate;
+    if (Number.isFinite(addedCost) && addedCost > 0)
+        tracker.cost += addedCost;
+    if (textInputTokens > 0) {
+        const key = `${modelName}_inputTokens`;
+        tracker.tokens[key] = (tracker.tokens[key] || 0) + textInputTokens;
+    }
+    if (imageInputTokens > 0) {
+        const key = `${modelName}_imageInputTokens`;
+        tracker.tokens[key] = (tracker.tokens[key] || 0) + imageInputTokens;
+    }
+    if (imageOutputTokens > 0) {
+        const key = `${modelName}_imageOutputTokens`;
+        tracker.tokens[key] = (tracker.tokens[key] || 0) + imageOutputTokens;
+    }
 };
 /**
- * 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.
+ * Adds character-billed usage (e.g. ElevenLabs TTS) to the caller-supplied
+ * tracker. There is no provider response to parse — billing is deterministic
+ * from the input character count. Reads the rate from
+ * `<model>-character-costs` (USD per million characters) and accumulates
+ * under `<model>_characters`. No-ops on missing tracker / model / count.
  */
-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 updateUsageTrackerForCharacters = (tracker, modelName, characterCount, config) => {
+    if (!tracker || !modelName || !characterCount)
+        return;
+    if (typeof tracker.cost !== "number")
+        tracker.cost = 0;
+    if (!tracker.tokens || typeof tracker.tokens !== "object")
+        tracker.tokens = {};
+    const rate = getModelRate(modelName, config, "character");
+    const addedCost = (characterCount / 1_000_000) * rate;
+    if (Number.isFinite(addedCost) && addedCost > 0)
+        tracker.cost += addedCost;
+    const key = `${modelName}_characters`;
+    tracker.tokens[key] = (tracker.tokens[key] || 0) + characterCount;
 };
 /**
  * Extracts a normalized token-usage object from a single LangChain `invoke()`
@@ -541,9 +560,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 +598,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 +630,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 +885,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 +925,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 +1034,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 +1056,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 +1107,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 +1180,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 +1191,6 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
             let rateLimitAttempt = 0;
             while (true) {
                 try {
-                    assertQuotaAvailable();
                     response = await llm.invoke(activeMessages);
                     break;
                 }
@@ -1186,7 +1206,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) {
@@ -1245,7 +1265,7 @@ const getImageModelProvider = (modelName) => {
  * @returns An object with `url`, `b64_json`, and `revisedPrompt` for a single image,
  *   or `{ images: [...] }` for multiple images
  */
-const generateImageWithOpenAI = async (modelName, config, prompt, options) => {
+const generateImageWithOpenAI = async (modelName, config, prompt, options, usageTracker = null) => {
     const { size = "1024x1024", style = "vivid", responseFormat = "url", n = 1, } = options;
     if (!config.openAIAPIKey) {
         throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.BAD_REQUEST, "OpenAI API key is required for OpenAI image generation");
@@ -1292,9 +1312,8 @@ 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);
+    updateImageUsageTracker(usageTracker, modelName, response, config, "openai");
     // Format response based on number of images
     if (n === 1) {
         const imageData = response.data[0];
@@ -1332,7 +1351,7 @@ const generateImageWithOpenAI = async (modelName, config, prompt, options) => {
  * @returns A single image descriptor `{ b64_json, mimeType }` when one image is
  *   requested, or `{ images: [...] }` for multiple images
  */
-const generateImageWithGoogle = async (modelName, config, prompt, options) => {
+const generateImageWithGoogle = async (modelName, config, prompt, options, usageTracker = null) => {
     const { aspectRatio = "1:1", numberOfImages = 1, negativePrompt = "", } = options;
     if (!config.googleAPIKey) {
         throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.BAD_REQUEST, "Google API key is required for Google image generation");
@@ -1392,8 +1411,8 @@ const generateImageWithGoogle = async (modelName, config, prompt, options) => {
             safetySettings: safetySettings,
         },
     };
-    assertQuotaAvailable();
     const response = await ai.models.generateContent(req);
+    updateImageUsageTracker(usageTracker, modelName, response, config, "google");
     // Extract images from response
     const images = [];
     const candidates = response.candidates || [];
@@ -1411,7 +1430,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];
     }
@@ -1437,7 +1455,7 @@ const generateImageWithGoogle = async (modelName, config, prompt, options) => {
  *   and `generateImageWithGoogle` for full option sets); defaults to `{}`
  * @returns The generated image data object returned by the provider-specific function
  */
-const runPromptWithModelForImageGeneration = async (modelName, config, prompt, options = {}) => {
+const runPromptWithModelForImageGeneration = async (modelName, config, prompt, options = {}, usageTracker = null) => {
     const provider = getImageModelProvider(modelName);
     if (!provider) {
         throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.BAD_REQUEST, `Unable to determine provider for model: ${modelName}. Model name should start with 'gpt-image-', 'gemini-', or 'imagen-'.`);
@@ -1446,10 +1464,10 @@ const runPromptWithModelForImageGeneration = async (modelName, config, prompt, o
     try {
         let result;
         if (provider === "openai") {
-            result = await generateImageWithOpenAI(modelName, config, prompt, options);
+            result = await generateImageWithOpenAI(modelName, config, prompt, options, usageTracker);
         }
         else if (provider === "google") {
-            result = await generateImageWithGoogle(modelName, config, prompt, options);
+            result = await generateImageWithGoogle(modelName, config, prompt, options, usageTracker);
         }
         const endTime = Date.now();
         const duration = endTime - startTime;
@@ -1477,5 +1495,6 @@ exports.default = {
     runPromptWithModel,
     runPromptWithModelForImageGeneration,
     throwErrorIfNotSuccessful,
+    updateUsageTrackerForCharacters,
     validateModel,
 };

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,10 +1,23 @@
+/**
+ * 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>;
-    runPromptWithModelForImageGeneration: (modelName: string, config: any, prompt: string, options?: 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, usageTracker?: UsageTracker | null) => Promise<any>;
     throwErrorIfNotSuccessful: (response: any) => string;
+    updateUsageTrackerForCharacters: (tracker: UsageTracker | null | undefined, modelName: string, characterCount: number, config: any) => void;
     validateModel: (selectedModel: string, supportedModels: string[]) => string;
 };
 export default _default;

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

@@ -1 +1 @@
-{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":";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;wBA+jB/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;sDAusBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CA3+B8B,GAAG,KAAG,MAAM;+CApjB9C,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,kBACD,MAAM,UACd,GAAG,KACV,IAAI;mCAokBU,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AAkhCT,wBASE"}

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,137 @@ 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;
+    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 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;
 };
 /**
- * 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`).
+ * Adds a single image-generation call's usage to the caller-supplied tracker.
+ * Extracts token counts from provider-specific response shapes: OpenAI returns
+ * `response.usage` with `input_tokens_details.{text_tokens,image_tokens}` and
+ * `output_tokens`; Google returns `response.usageMetadata` with
+ * `promptTokensDetails` (modality-keyed) and `candidatesTokenCount` for the
+ * generated image. Reads rates from `<model>-input-token-costs`,
+ * `<model>-image-input-token-costs`, and `<model>-image-output-token-costs`.
+ * No-ops when the tracker or response usage info is absent.
  */
-const recordTextCost = (modelName, usage, config) => {
-    if (!usage)
+const updateImageUsageTracker = (tracker, modelName, response, config, provider) => {
+    if (!tracker || !modelName || !response)
         return;
-    const inputRate = getModelRate(modelName, config, "input-token") || 0;
-    const outputRate = getModelRate(modelName, config, "output-token") || 0;
-    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);
+    if (typeof tracker.cost !== "number")
+        tracker.cost = 0;
+    if (!tracker.tokens || typeof tracker.tokens !== "object")
+        tracker.tokens = {};
+    let textInputTokens = 0;
+    let imageInputTokens = 0;
+    let imageOutputTokens = 0;
+    if (provider === "openai") {
+        const usage = response.usage;
+        if (!usage)
+            return;
+        const details = usage.input_tokens_details || {};
+        textInputTokens = details.text_tokens || 0;
+        imageInputTokens = details.image_tokens || 0;
+        // Older shapes report a single input_tokens without modality breakdown.
+        if (!textInputTokens && !imageInputTokens && usage.input_tokens) {
+            textInputTokens = usage.input_tokens;
+        }
+        imageOutputTokens = usage.output_tokens || 0;
+    }
+    else {
+        const um = response.usageMetadata;
+        if (!um)
+            return;
+        const promptDetails = Array.isArray(um.promptTokensDetails)
+            ? um.promptTokensDetails
+            : [];
+        for (const d of promptDetails) {
+            const modality = String(d?.modality || "").toUpperCase();
+            const count = Number(d?.tokenCount) || 0;
+            if (modality === "IMAGE")
+                imageInputTokens += count;
+            else
+                textInputTokens += count;
+        }
+        if (!textInputTokens && !imageInputTokens) {
+            textInputTokens = Number(um.promptTokenCount) || 0;
+        }
+        imageOutputTokens = Number(um.candidatesTokenCount) || 0;
+    }
+    const textInputRate = getModelRate(modelName, config, "input-token");
+    const imageInputRate = getModelRate(modelName, config, "image-input-token");
+    const imageOutputRate = getModelRate(modelName, config, "image-output-token");
+    const addedCost = (textInputTokens / 1_000_000) * textInputRate +
+        (imageInputTokens / 1_000_000) * imageInputRate +
+        (imageOutputTokens / 1_000_000) * imageOutputRate;
+    if (Number.isFinite(addedCost) && addedCost > 0)
+        tracker.cost += addedCost;
+    if (textInputTokens > 0) {
+        const key = `${modelName}_inputTokens`;
+        tracker.tokens[key] = (tracker.tokens[key] || 0) + textInputTokens;
+    }
+    if (imageInputTokens > 0) {
+        const key = `${modelName}_imageInputTokens`;
+        tracker.tokens[key] = (tracker.tokens[key] || 0) + imageInputTokens;
+    }
+    if (imageOutputTokens > 0) {
+        const key = `${modelName}_imageOutputTokens`;
+        tracker.tokens[key] = (tracker.tokens[key] || 0) + imageOutputTokens;
+    }
 };
 /**
- * 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.
+ * Adds character-billed usage (e.g. ElevenLabs TTS) to the caller-supplied
+ * tracker. There is no provider response to parse — billing is deterministic
+ * from the input character count. Reads the rate from
+ * `<model>-character-costs` (USD per million characters) and accumulates
+ * under `<model>_characters`. No-ops on missing tracker / model / count.
  */
-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 updateUsageTrackerForCharacters = (tracker, modelName, characterCount, config) => {
+    if (!tracker || !modelName || !characterCount)
+        return;
+    if (typeof tracker.cost !== "number")
+        tracker.cost = 0;
+    if (!tracker.tokens || typeof tracker.tokens !== "object")
+        tracker.tokens = {};
+    const rate = getModelRate(modelName, config, "character");
+    const addedCost = (characterCount / 1_000_000) * rate;
+    if (Number.isFinite(addedCost) && addedCost > 0)
+        tracker.cost += addedCost;
+    const key = `${modelName}_characters`;
+    tracker.tokens[key] = (tracker.tokens[key] || 0) + characterCount;
 };
 /**
  * Extracts a normalized token-usage object from a single LangChain `invoke()`
@@ -536,9 +555,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 +593,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 +625,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 +880,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 +920,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 +1029,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 +1051,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 +1102,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 +1175,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 +1186,6 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
             let rateLimitAttempt = 0;
             while (true) {
                 try {
-                    assertQuotaAvailable();
                     response = await llm.invoke(activeMessages);
                     break;
                 }
@@ -1181,7 +1201,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) {
@@ -1240,7 +1260,7 @@ const getImageModelProvider = (modelName) => {
  * @returns An object with `url`, `b64_json`, and `revisedPrompt` for a single image,
  *   or `{ images: [...] }` for multiple images
  */
-const generateImageWithOpenAI = async (modelName, config, prompt, options) => {
+const generateImageWithOpenAI = async (modelName, config, prompt, options, usageTracker = null) => {
     const { size = "1024x1024", style = "vivid", responseFormat = "url", n = 1, } = options;
     if (!config.openAIAPIKey) {
         throw errorHandlingHelper.create(constants.HTTP_CODES.BAD_REQUEST, "OpenAI API key is required for OpenAI image generation");
@@ -1287,9 +1307,8 @@ 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);
+    updateImageUsageTracker(usageTracker, modelName, response, config, "openai");
     // Format response based on number of images
     if (n === 1) {
         const imageData = response.data[0];
@@ -1327,7 +1346,7 @@ const generateImageWithOpenAI = async (modelName, config, prompt, options) => {
  * @returns A single image descriptor `{ b64_json, mimeType }` when one image is
  *   requested, or `{ images: [...] }` for multiple images
  */
-const generateImageWithGoogle = async (modelName, config, prompt, options) => {
+const generateImageWithGoogle = async (modelName, config, prompt, options, usageTracker = null) => {
     const { aspectRatio = "1:1", numberOfImages = 1, negativePrompt = "", } = options;
     if (!config.googleAPIKey) {
         throw errorHandlingHelper.create(constants.HTTP_CODES.BAD_REQUEST, "Google API key is required for Google image generation");
@@ -1387,8 +1406,8 @@ const generateImageWithGoogle = async (modelName, config, prompt, options) => {
             safetySettings: safetySettings,
         },
     };
-    assertQuotaAvailable();
     const response = await ai.models.generateContent(req);
+    updateImageUsageTracker(usageTracker, modelName, response, config, "google");
     // Extract images from response
     const images = [];
     const candidates = response.candidates || [];
@@ -1406,7 +1425,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];
     }
@@ -1432,7 +1450,7 @@ const generateImageWithGoogle = async (modelName, config, prompt, options) => {
  *   and `generateImageWithGoogle` for full option sets); defaults to `{}`
  * @returns The generated image data object returned by the provider-specific function
  */
-const runPromptWithModelForImageGeneration = async (modelName, config, prompt, options = {}) => {
+const runPromptWithModelForImageGeneration = async (modelName, config, prompt, options = {}, usageTracker = null) => {
     const provider = getImageModelProvider(modelName);
     if (!provider) {
         throw errorHandlingHelper.create(constants.HTTP_CODES.BAD_REQUEST, `Unable to determine provider for model: ${modelName}. Model name should start with 'gpt-image-', 'gemini-', or 'imagen-'.`);
@@ -1441,10 +1459,10 @@ const runPromptWithModelForImageGeneration = async (modelName, config, prompt, o
     try {
         let result;
         if (provider === "openai") {
-            result = await generateImageWithOpenAI(modelName, config, prompt, options);
+            result = await generateImageWithOpenAI(modelName, config, prompt, options, usageTracker);
         }
         else if (provider === "google") {
-            result = await generateImageWithGoogle(modelName, config, prompt, options);
+            result = await generateImageWithGoogle(modelName, config, prompt, options, usageTracker);
         }
         const endTime = Date.now();
         const duration = endTime - startTime;
@@ -1472,5 +1490,6 @@ export default {
     runPromptWithModel,
     runPromptWithModelForImageGeneration,
     throwErrorIfNotSuccessful,
+    updateUsageTrackerForCharacters,
     validateModel,
 };

package/package.json

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