@stackfactor/agent-utils 1.2.7 → 1.2.10

package/dist/cjs/langChain.d.ts

@@ -15,8 +15,9 @@ declare const _default: {
     createAgent: (name: string, modelName: string, systemPrompt: string, tools: any[], responseFormat: any, config: any) => 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>;
+    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":"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"}
+{"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;sDAktBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CAt/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;;AA6hCT,wBASE"}

package/dist/cjs/langChain.js

@@ -68,6 +68,101 @@ const updateUsageTracker = (tracker, modelName, usage, config) => {
     tracker.tokens[inputKey] = (tracker.tokens[inputKey] || 0) + inputTokens;
     tracker.tokens[outputKey] = (tracker.tokens[outputKey] || 0) + outputTokens;
 };
+/**
+ * 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 updateImageUsageTracker = (tracker, modelName, response, config, provider) => {
+    if (!tracker || !modelName || !response)
+        return;
+    if (typeof tracker.cost !== "number")
+        tracker.cost = 0;
+    if (!tracker.tokens || typeof tracker.tokens !== "object")
+        tracker.tokens = {};
+    let textInputTokens = 0;
+    let imageInputTokens = 0;
+    let imageOutputTokens = 0;
+    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;
+    }
+};
+/**
+ * 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 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()`
  * response. Reads from `usage_metadata` first (standardized in LangChain v1),
@@ -1170,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");
@@ -1218,6 +1313,7 @@ const generateImageWithOpenAI = async (modelName, config, prompt, options) => {
         }
     }
     const response = await openai.images.generate(requestParams);
+    updateImageUsageTracker(usageTracker, modelName, response, config, "openai");
     // Format response based on number of images
     if (n === 1) {
         const imageData = response.data[0];
@@ -1243,20 +1339,21 @@ const generateImageWithOpenAI = async (modelName, config, prompt, options) => {
  * Google models do not support alpha channels. Validates the `aspectRatio` against
  * allowed values (`"1:1"`, `"3:4"`, `"4:3"`, `"9:16"`, `"16:9"`). Applies model-
  * specific generation config: Imagen models receive `numberOfImages`, `aspectRatio`,
- * `outputMimeType`, and optional `negativePrompt`; Gemini models receive `temperature`
- * and `topP`. Safety settings are disabled for image generation. Throws an error if no
- * images are returned.
+ * `outputMimeType`, and optional `negativePrompt`; Gemini models receive `temperature`,
+ * `topP`, and an `imageConfig` carrying `aspectRatio` plus an optional `imageSize`
+ * resolution tier (e.g. "1K"/"2K"/"4K", honoured by gemini-3-pro-image). Safety
+ * settings are disabled for image generation. Throws an error if no images are returned.
  * @param modelName - The Google model identifier (e.g. `"imagen-4.0-generate-001"`,
  *   `"gemini-3.0-pro-image"`)
  * @param config - Configuration object; must include `googleAPIKey`
  * @param prompt - The text prompt describing the image to generate
- * @param options - Generation options including `aspectRatio`, `numberOfImages`, and
- *   optional `negativePrompt` (Imagen only)
+ * @param options - Generation options including `aspectRatio`, optional `imageSize`
+ *   (Gemini resolution tier), `numberOfImages`, and optional `negativePrompt` (Imagen only)
  * @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 { aspectRatio = "1:1", numberOfImages = 1, negativePrompt = "", } = options;
+const generateImageWithGoogle = async (modelName, config, prompt, options, usageTracker = null) => {
+    const { aspectRatio = "1:1", imageSize, 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");
     }
@@ -1293,6 +1390,15 @@ const generateImageWithGoogle = async (modelName, config, prompt, options) => {
                 // Gemini-specific config
                 temperature: 1,
                 topP: 0.95,
+                // Gemini controls output dimensions through `imageConfig`, not the
+                // top-level `aspectRatio` field that Imagen uses. `imageSize`
+                // (e.g. "1K"/"2K"/"4K") is only honoured by resolution-capable
+                // models such as gemini-3-pro-image, so it is passed through only
+                // when the caller explicitly requests it.
+                imageConfig: {
+                    aspectRatio: aspectRatio,
+                    ...(imageSize ? { imageSize: imageSize } : {}),
+                },
             }),
     };
     // Safety settings (disable for image generation)
@@ -1316,6 +1422,7 @@ const generateImageWithGoogle = async (modelName, config, prompt, options) => {
         },
     };
     const response = await ai.models.generateContent(req);
+    updateImageUsageTracker(usageTracker, modelName, response, config, "google");
     // Extract images from response
     const images = [];
     const candidates = response.candidates || [];
@@ -1358,7 +1465,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-'.`);
@@ -1367,10 +1474,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;
@@ -1398,5 +1505,6 @@ exports.default = {
     runPromptWithModel,
     runPromptWithModelForImageGeneration,
     throwErrorIfNotSuccessful,
+    updateUsageTrackerForCharacters,
     validateModel,
 };

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

@@ -1 +1 @@
-{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AA8LtC;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,GAAG,KACT,OAAO,CAAC;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC,CAAC;AAEzC,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,YAAY,CAAC,EAAE,aAAa,CAAC;CAC9B;AAkDD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAChB,MAAM,SAAS,EACf,UAAS,YAAiB,KACzB,IAAI,CAAC,MAuKP,CAAC"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AA8LtC;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,GAAG,KACT,OAAO,CAAC;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC,CAAC;AAEzC,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,YAAY,CAAC,EAAE,aAAa,CAAC;CAC9B;AAyHD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAChB,MAAM,SAAS,EACf,UAAS,YAAiB,KACzB,IAAI,CAAC,MA4KP,CAAC"}

package/dist/cjs/serve.js

@@ -199,23 +199,78 @@ const runSelfCheck = async (checkCode, config, session) => {
 /** Marks an auth failure so the handler can map it to gRPC UNAUTHENTICATED. */
 class UnauthenticatedError extends Error {
 }
+/**
+ * Marks a *transient* failure to reach the StackFactor session-validation
+ * endpoint (5xx / request timeout / transport error). Unlike
+ * {@link UnauthenticatedError} the token was never actually rejected — the
+ * backend was momentarily unreachable — so the handler maps this to the
+ * retryable gRPC UNAVAILABLE instead of UNAUTHENTICATED, and the message no
+ * longer slanders a perfectly valid token.
+ */
+class BackendUnavailableError extends Error {
+}
+/**
+ * Session-validation retry policy. A GKE front-door blip (a backend pod briefly
+ * refusing connections during a restart or an event-loop stall) surfaces here as
+ * a 502/503 or a transport error, not a 401 — and retrying on a fresh connection
+ * almost always lands on a healthy replica. Env-overridable for prod tuning.
+ */
+const AUTH_MAX_ATTEMPTS = Math.max(1, Number(process.env.STACKFACTOR_AUTH_MAX_ATTEMPTS) || 4);
+const AUTH_RETRY_BASE_MS = Math.max(0, Number(process.env.STACKFACTOR_AUTH_RETRY_BASE_MS) || 500);
+const delay = (ms) => new Promise((res) => setTimeout(res, ms));
+/** A 401/403 is the backend genuinely rejecting the token. */
+const isAuthRejection = (error) => {
+    const status = error?.response?.status;
+    return status === 401 || status === 403;
+};
+/**
+ * True when the failure is the validation endpoint being unreachable rather than
+ * the token being bad: a 5xx/408/429 HTTP response, or a transport-level error
+ * (no HTTP response but an axios/errno signature). Plain programming errors
+ * (no response and no axios/errno marker) are NOT treated as transient.
+ */
+const isTransient = (error) => {
+    const status = error?.response?.status;
+    if (status)
+        return status >= 500 || status === 408 || status === 429;
+    return Boolean(error?.isAxiosError || error?.code);
+};
 /**
  * Default authenticator: require a token on the request and resolve it to a
  * session via the StackFactor API. Requires `BACKEND_URL` (or `REACT_APP_NODE_ENV`)
- * to point client-api at the right backend. Throws {@link UnauthenticatedError}
- * when the token is missing or rejected.
+ * to point client-api at the right backend.
+ *
+ * A 401/403 (or any non-transient error) throws {@link UnauthenticatedError}
+ * immediately. A transient failure (5xx / timeout / network) is retried with
+ * exponential backoff; if every attempt fails it throws
+ * {@link BackendUnavailableError} so the caller sees a retryable UNAVAILABLE
+ * rather than a misleading "invalid token".
  */
 const defaultAuthenticate = async (request) => {
     const token = request?.authToken ?? request?.authorization;
     if (!token) {
         throw new UnauthenticatedError("Missing StackFactor auth token");
     }
-    try {
-        return await client_api_1.session.getSession(token);
-    }
-    catch (error) {
-        throw new UnauthenticatedError(`Invalid StackFactor auth token: ${error?.message ?? error}`);
+    let lastError;
+    for (let attempt = 1; attempt <= AUTH_MAX_ATTEMPTS; attempt++) {
+        try {
+            return await client_api_1.session.getSession(token);
+        }
+        catch (error) {
+            lastError = error;
+            // Real rejection, or an unexpected non-transient error: fail fast.
+            if (isAuthRejection(error) || !isTransient(error)) {
+                throw new UnauthenticatedError(`Invalid StackFactor auth token: ${error?.message ?? error}`);
+            }
+            // Transient: the endpoint is momentarily unreachable, not the token bad.
+            if (attempt < AUTH_MAX_ATTEMPTS) {
+                const backoff = AUTH_RETRY_BASE_MS * 2 ** (attempt - 1);
+                logger_js_1.default.log(null, logger_js_1.default.levels.warn, `session validation transient failure (attempt ${attempt}/${AUTH_MAX_ATTEMPTS}); retrying in ${backoff}ms: ${error?.message ?? error}`);
+                await delay(backoff);
+            }
+        }
     }
+    throw new BackendUnavailableError(`StackFactor session validation unavailable after ${AUTH_MAX_ATTEMPTS} attempts: ${lastError?.message ?? lastError}`);
 };
 const safeParse = (value, fallback) => {
     if (!value)
@@ -283,9 +338,12 @@ const serve = (main, options = {}) => {
             }
             catch (error) {
                 const message = error?.message ?? "Unauthenticated";
-                logger_js_1.default.log(null, logger_js_1.default.levels.warn, `agent Execute refused: ${message}`);
+                const unavailable = error instanceof BackendUnavailableError;
+                logger_js_1.default.log(null, logger_js_1.default.levels.warn, `agent Execute refused (${unavailable ? "unavailable" : "unauthenticated"}): ${message}`);
                 call.emit("error", {
-                    code: grpc.status.UNAUTHENTICATED,
+                    code: unavailable
+                        ? grpc.status.UNAVAILABLE
+                        : grpc.status.UNAUTHENTICATED,
                     details: message,
                 });
                 return;

package/dist/esm/langChain.d.ts

@@ -15,8 +15,9 @@ declare const _default: {
     createAgent: (name: string, modelName: string, systemPrompt: string, tools: any[], responseFormat: any, config: any) => 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>;
+    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":"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"}
+{"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;sDAktBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CAt/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;;AA6hCT,wBASE"}

package/dist/esm/langChain.js

@@ -63,6 +63,101 @@ const updateUsageTracker = (tracker, modelName, usage, config) => {
     tracker.tokens[inputKey] = (tracker.tokens[inputKey] || 0) + inputTokens;
     tracker.tokens[outputKey] = (tracker.tokens[outputKey] || 0) + outputTokens;
 };
+/**
+ * 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 updateImageUsageTracker = (tracker, modelName, response, config, provider) => {
+    if (!tracker || !modelName || !response)
+        return;
+    if (typeof tracker.cost !== "number")
+        tracker.cost = 0;
+    if (!tracker.tokens || typeof tracker.tokens !== "object")
+        tracker.tokens = {};
+    let textInputTokens = 0;
+    let imageInputTokens = 0;
+    let imageOutputTokens = 0;
+    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;
+    }
+};
+/**
+ * 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 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()`
  * response. Reads from `usage_metadata` first (standardized in LangChain v1),
@@ -1165,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");
@@ -1213,6 +1308,7 @@ const generateImageWithOpenAI = async (modelName, config, prompt, options) => {
         }
     }
     const response = await openai.images.generate(requestParams);
+    updateImageUsageTracker(usageTracker, modelName, response, config, "openai");
     // Format response based on number of images
     if (n === 1) {
         const imageData = response.data[0];
@@ -1238,20 +1334,21 @@ const generateImageWithOpenAI = async (modelName, config, prompt, options) => {
  * Google models do not support alpha channels. Validates the `aspectRatio` against
  * allowed values (`"1:1"`, `"3:4"`, `"4:3"`, `"9:16"`, `"16:9"`). Applies model-
  * specific generation config: Imagen models receive `numberOfImages`, `aspectRatio`,
- * `outputMimeType`, and optional `negativePrompt`; Gemini models receive `temperature`
- * and `topP`. Safety settings are disabled for image generation. Throws an error if no
- * images are returned.
+ * `outputMimeType`, and optional `negativePrompt`; Gemini models receive `temperature`,
+ * `topP`, and an `imageConfig` carrying `aspectRatio` plus an optional `imageSize`
+ * resolution tier (e.g. "1K"/"2K"/"4K", honoured by gemini-3-pro-image). Safety
+ * settings are disabled for image generation. Throws an error if no images are returned.
  * @param modelName - The Google model identifier (e.g. `"imagen-4.0-generate-001"`,
  *   `"gemini-3.0-pro-image"`)
  * @param config - Configuration object; must include `googleAPIKey`
  * @param prompt - The text prompt describing the image to generate
- * @param options - Generation options including `aspectRatio`, `numberOfImages`, and
- *   optional `negativePrompt` (Imagen only)
+ * @param options - Generation options including `aspectRatio`, optional `imageSize`
+ *   (Gemini resolution tier), `numberOfImages`, and optional `negativePrompt` (Imagen only)
  * @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 { aspectRatio = "1:1", numberOfImages = 1, negativePrompt = "", } = options;
+const generateImageWithGoogle = async (modelName, config, prompt, options, usageTracker = null) => {
+    const { aspectRatio = "1:1", imageSize, numberOfImages = 1, negativePrompt = "", } = options;
     if (!config.googleAPIKey) {
         throw errorHandlingHelper.create(constants.HTTP_CODES.BAD_REQUEST, "Google API key is required for Google image generation");
     }
@@ -1288,6 +1385,15 @@ const generateImageWithGoogle = async (modelName, config, prompt, options) => {
                 // Gemini-specific config
                 temperature: 1,
                 topP: 0.95,
+                // Gemini controls output dimensions through `imageConfig`, not the
+                // top-level `aspectRatio` field that Imagen uses. `imageSize`
+                // (e.g. "1K"/"2K"/"4K") is only honoured by resolution-capable
+                // models such as gemini-3-pro-image, so it is passed through only
+                // when the caller explicitly requests it.
+                imageConfig: {
+                    aspectRatio: aspectRatio,
+                    ...(imageSize ? { imageSize: imageSize } : {}),
+                },
             }),
     };
     // Safety settings (disable for image generation)
@@ -1311,6 +1417,7 @@ const generateImageWithGoogle = async (modelName, config, prompt, options) => {
         },
     };
     const response = await ai.models.generateContent(req);
+    updateImageUsageTracker(usageTracker, modelName, response, config, "google");
     // Extract images from response
     const images = [];
     const candidates = response.candidates || [];
@@ -1353,7 +1460,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-'.`);
@@ -1362,10 +1469,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;
@@ -1393,5 +1500,6 @@ export default {
     runPromptWithModel,
     runPromptWithModelForImageGeneration,
     throwErrorIfNotSuccessful,
+    updateUsageTrackerForCharacters,
     validateModel,
 };

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

@@ -1 +1 @@
-{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AA8LtC;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,GAAG,KACT,OAAO,CAAC;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC,CAAC;AAEzC,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,YAAY,CAAC,EAAE,aAAa,CAAC;CAC9B;AAkDD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAChB,MAAM,SAAS,EACf,UAAS,YAAiB,KACzB,IAAI,CAAC,MAuKP,CAAC"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AA8LtC;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,GAAG,KACT,OAAO,CAAC;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC,CAAC;AAEzC,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,YAAY,CAAC,EAAE,aAAa,CAAC;CAC9B;AAyHD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAChB,MAAM,SAAS,EACf,UAAS,YAAiB,KACzB,IAAI,CAAC,MA4KP,CAAC"}

package/dist/esm/serve.js

@@ -160,23 +160,78 @@ const runSelfCheck = async (checkCode, config, session) => {
 /** Marks an auth failure so the handler can map it to gRPC UNAUTHENTICATED. */
 class UnauthenticatedError extends Error {
 }
+/**
+ * Marks a *transient* failure to reach the StackFactor session-validation
+ * endpoint (5xx / request timeout / transport error). Unlike
+ * {@link UnauthenticatedError} the token was never actually rejected — the
+ * backend was momentarily unreachable — so the handler maps this to the
+ * retryable gRPC UNAVAILABLE instead of UNAUTHENTICATED, and the message no
+ * longer slanders a perfectly valid token.
+ */
+class BackendUnavailableError extends Error {
+}
+/**
+ * Session-validation retry policy. A GKE front-door blip (a backend pod briefly
+ * refusing connections during a restart or an event-loop stall) surfaces here as
+ * a 502/503 or a transport error, not a 401 — and retrying on a fresh connection
+ * almost always lands on a healthy replica. Env-overridable for prod tuning.
+ */
+const AUTH_MAX_ATTEMPTS = Math.max(1, Number(process.env.STACKFACTOR_AUTH_MAX_ATTEMPTS) || 4);
+const AUTH_RETRY_BASE_MS = Math.max(0, Number(process.env.STACKFACTOR_AUTH_RETRY_BASE_MS) || 500);
+const delay = (ms) => new Promise((res) => setTimeout(res, ms));
+/** A 401/403 is the backend genuinely rejecting the token. */
+const isAuthRejection = (error) => {
+    const status = error?.response?.status;
+    return status === 401 || status === 403;
+};
+/**
+ * True when the failure is the validation endpoint being unreachable rather than
+ * the token being bad: a 5xx/408/429 HTTP response, or a transport-level error
+ * (no HTTP response but an axios/errno signature). Plain programming errors
+ * (no response and no axios/errno marker) are NOT treated as transient.
+ */
+const isTransient = (error) => {
+    const status = error?.response?.status;
+    if (status)
+        return status >= 500 || status === 408 || status === 429;
+    return Boolean(error?.isAxiosError || error?.code);
+};
 /**
  * Default authenticator: require a token on the request and resolve it to a
  * session via the StackFactor API. Requires `BACKEND_URL` (or `REACT_APP_NODE_ENV`)
- * to point client-api at the right backend. Throws {@link UnauthenticatedError}
- * when the token is missing or rejected.
+ * to point client-api at the right backend.
+ *
+ * A 401/403 (or any non-transient error) throws {@link UnauthenticatedError}
+ * immediately. A transient failure (5xx / timeout / network) is retried with
+ * exponential backoff; if every attempt fails it throws
+ * {@link BackendUnavailableError} so the caller sees a retryable UNAVAILABLE
+ * rather than a misleading "invalid token".
  */
 const defaultAuthenticate = async (request) => {
     const token = request?.authToken ?? request?.authorization;
     if (!token) {
         throw new UnauthenticatedError("Missing StackFactor auth token");
     }
-    try {
-        return await clientSession.getSession(token);
-    }
-    catch (error) {
-        throw new UnauthenticatedError(`Invalid StackFactor auth token: ${error?.message ?? error}`);
+    let lastError;
+    for (let attempt = 1; attempt <= AUTH_MAX_ATTEMPTS; attempt++) {
+        try {
+            return await clientSession.getSession(token);
+        }
+        catch (error) {
+            lastError = error;
+            // Real rejection, or an unexpected non-transient error: fail fast.
+            if (isAuthRejection(error) || !isTransient(error)) {
+                throw new UnauthenticatedError(`Invalid StackFactor auth token: ${error?.message ?? error}`);
+            }
+            // Transient: the endpoint is momentarily unreachable, not the token bad.
+            if (attempt < AUTH_MAX_ATTEMPTS) {
+                const backoff = AUTH_RETRY_BASE_MS * 2 ** (attempt - 1);
+                logger.log(null, logger.levels.warn, `session validation transient failure (attempt ${attempt}/${AUTH_MAX_ATTEMPTS}); retrying in ${backoff}ms: ${error?.message ?? error}`);
+                await delay(backoff);
+            }
+        }
     }
+    throw new BackendUnavailableError(`StackFactor session validation unavailable after ${AUTH_MAX_ATTEMPTS} attempts: ${lastError?.message ?? lastError}`);
 };
 const safeParse = (value, fallback) => {
     if (!value)
@@ -244,9 +299,12 @@ export const serve = (main, options = {}) => {
             }
             catch (error) {
                 const message = error?.message ?? "Unauthenticated";
-                logger.log(null, logger.levels.warn, `agent Execute refused: ${message}`);
+                const unavailable = error instanceof BackendUnavailableError;
+                logger.log(null, logger.levels.warn, `agent Execute refused (${unavailable ? "unavailable" : "unauthenticated"}): ${message}`);
                 call.emit("error", {
-                    code: grpc.status.UNAUTHENTICATED,
+                    code: unavailable
+                        ? grpc.status.UNAVAILABLE
+                        : grpc.status.UNAUTHENTICATED,
                     details: message,
                 });
                 return;

package/package.json

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