@stackfactor/agent-utils 1.4.3 → 1.7.0

package/dist/cjs/langChain.js

@@ -16,6 +16,7 @@ const logger_js_1 = __importDefault(require("./logger.js"));
 const zod_1 = require("zod");
 const transform_json_schema_1 = require("@anthropic-ai/sdk/lib/transform-json-schema");
 const runtimeContext_js_1 = require("./runtimeContext.js");
+const usage_js_1 = require("./usage.js");
 const tavily_js_1 = require("./tavily.js");
 const JSON_ESCAPE_INSTRUCTION = `
 CRITICAL - Your response must be valid JSON. Escape ALL special characters in string values:
@@ -104,29 +105,36 @@ const checkIfAIProviderConfigured = (config) => {
     }
 };
 /**
- * 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 `0` when the constant is
- * absent or not numeric, which leaves cost contribution zero.
+ * Counts `amount` of `unit` for `modelName`: into the request's usage ledger,
+ * which is reported to the platform, and into the caller's tracker when it
+ * passed one. Nothing is counted for an amount that is not positive.
  */
-const getModelRate = (modelName, config, kind) => {
-    if (!config || !modelName)
-        return 0;
-    const rate = Number(config[`${modelName}-${kind}-costs`]);
-    return Number.isFinite(rate) ? rate : 0;
+const countUsage = (tracker, modelName, unit, amount) => {
+    if (!Number.isFinite(amount) || amount <= 0)
+        return;
+    (0, usage_js_1.recordUsage)(modelName, unit, amount);
+    if (!tracker)
+        return;
+    const key = `${modelName}_${unit}`;
+    tracker.tokens[key] = (tracker.tokens[key] || 0) + amount;
 };
-/**
- * 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 updateUsageTracker = (tracker, modelName, usage, config) => {
-    if (!tracker || !usage || !modelName)
+/** Makes `{}` a tracker. `cost` stays 0: the platform prices what was used. */
+const prepareTracker = (tracker) => {
+    if (!tracker)
         return;
     if (typeof tracker.cost !== "number")
         tracker.cost = 0;
     if (!tracker.tokens || typeof tracker.tokens !== "object")
         tracker.tokens = {};
+};
+/**
+ * Counts a single call's token usage. `config` is no longer read: it carried
+ * the rates, and what usage costs is the platform's to say.
+ */
+const updateUsageTracker = (tracker, modelName, usage, _config) => {
+    if (!usage || !modelName)
+        return;
+    prepareTracker(tracker);
     const inputTokens = usage.input_tokens || 0;
     const visibleOutputTokens = usage.output_tokens || 0;
     const totalTokens = usage.total_tokens || 0;
@@ -135,40 +143,24 @@ const updateUsageTracker = (tracker, modelName, usage, config) => {
     // `total - input - visibleOutput` is the thinking output the caller was still
     // billed for. Providers that already fold reasoning into `output_tokens`
     // (Anthropic, OpenAI) report `total == input + output`, so this adds 0.
-    // Reasoning is charged at the output rate, so we treat it as output for both
-    // the token counters and the cost.
+    // Reasoning is charged at the output rate, so it is counted as output.
     const reasoningTokens = totalTokens > 0
         ? Math.max(0, totalTokens - inputTokens - visibleOutputTokens)
         : 0;
-    const outputTokens = visibleOutputTokens + reasoningTokens;
-    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;
+    countUsage(tracker, modelName, "inputTokens", inputTokens);
+    countUsage(tracker, modelName, "outputTokens", visibleOutputTokens + reasoningTokens);
 };
 /**
- * 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.
+ * Counts a single image-generation call's usage. 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.
+ * No-ops when the response carries no usage.
  */
-const updateImageUsageTracker = (tracker, modelName, response, config, provider) => {
-    if (!tracker || !modelName || !response)
+const updateImageUsageTracker = (tracker, modelName, response, _config, provider) => {
+    if (!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;
@@ -205,85 +197,42 @@ const updateImageUsageTracker = (tracker, modelName, response, config, provider)
         }
         imageOutputTokens = Number(um.candidatesTokenCount) || 0;
     }
-    const textInputRate = getModelRate(modelName, config, "input-token");
-    // Reference-image input tokens are billed at the model's input rate. Configs
-    // that don't define a dedicated `<model>-image-input-token-costs` (the common
-    // case — image models charge all input at one rate and only differ on output)
-    // fall back to the text input rate rather than silently billing image input
-    // at $0.
-    const imageInputRate = getModelRate(modelName, config, "image-input-token") || textInputRate;
-    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;
-    }
+    prepareTracker(tracker);
+    countUsage(tracker, modelName, "inputTokens", textInputTokens);
+    // The platform prices an image a model is given as its other input, unless
+    // the model has a rate of its own for it.
+    countUsage(tracker, modelName, "imageInputTokens", imageInputTokens);
+    countUsage(tracker, modelName, "imageOutputTokens", 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.
+ * Counts character-billed usage (e.g. ElevenLabs TTS). There is no provider
+ * response to parse — billing is deterministic from the input character
+ * count. No-ops on a missing model or count.
  */
-const updateUsageTrackerForCharacters = (tracker, modelName, characterCount, config) => {
-    if (!tracker || !modelName || !characterCount)
+const updateUsageTrackerForCharacters = (tracker, modelName, characterCount, _config) => {
+    if (!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;
+    prepareTracker(tracker);
+    countUsage(tracker, modelName, "characters", characterCount);
 };
 /**
- * Adds second-billed usage (video generation) to the caller-supplied tracker.
- *
- * Video is the first output here that providers bill by DURATION rather than by
- * tokens or characters, so the rate constant `<model>-second-costs` is read as
- * USD PER SECOND — not per million, as the `input-token` and `character` rates
- * are. A Veo or Sora second costs cents, and a per-million reading would bill
- * it as effectively free.
+ * Counts second-billed usage (video generation): providers bill video by
+ * DURATION rather than by tokens or characters.
  *
- * The rate is per model, not per model-and-resolution, so a caller that lets a
- * tenant change resolution on a model whose price varies by it (sora-2-pro is
- * $0.30/$0.50/$0.70 at 720p/1024p/1080p) must pin the resolution its constant
- * describes, or it will bill the wrong number.
+ * The platform's rate is per model, not per model-and-resolution, so a caller
+ * that lets a tenant change resolution on a model whose price varies by it
+ * (sora-2-pro is $0.30/$0.50/$0.70 at 720p/1024p/1080p) must pin the
+ * resolution the rate describes, or the wrong number is charged.
  *
- * @param tracker - The accumulator to add to; no-ops when null
- * @param modelName - The video model id, used for both the rate and the counter key
+ * @param tracker - The caller's accumulator, when it passed one
+ * @param modelName - The video model id
  * @param seconds - Billed duration of the generated clip
- * @param config - Integration config carrying `<model>-second-costs`
  */
-const updateVideoUsageTracker = (tracker, modelName, seconds, config) => {
-    if (!tracker || !modelName || !seconds)
+const updateVideoUsageTracker = (tracker, modelName, seconds, _config) => {
+    if (!modelName || !seconds)
         return;
-    if (typeof tracker.cost !== "number")
-        tracker.cost = 0;
-    if (!tracker.tokens || typeof tracker.tokens !== "object")
-        tracker.tokens = {};
-    const rate = getModelRate(modelName, config, "second");
-    const addedCost = seconds * rate;
-    if (Number.isFinite(addedCost) && addedCost > 0)
-        tracker.cost += addedCost;
-    const key = `${modelName}_seconds`;
-    tracker.tokens[key] = (tracker.tokens[key] || 0) + seconds;
+    prepareTracker(tracker);
+    countUsage(tracker, modelName, "seconds", seconds);
 };
 /**
  * Extracts a normalized token-usage object from a single LangChain `invoke()`
@@ -1100,6 +1049,65 @@ const parseAndValidateJSONResponse = (rawContent, schema) => {
  * original base) so that across multiple retries the full failure history
  * accumulates and the model can avoid oscillating between previous broken outputs.
  */
+/**
+ * Whether a response that fails schema validation is retried with the errors
+ * appended (buildValidationRetryMessages), up to MAX_VALIDATION_RETRIES.
+ *
+ * This used to be skipped whenever the model supports native structured
+ * output, on the reasoning that a natively constrained response cannot be
+ * invalid, so a failure had to be a schema bug worth surfacing at once. It
+ * can be invalid, and routinely is: constrained decoding enforces the JSON
+ * *shape*, not the Zod schema. Anthropic's SDK strips `enum` into a
+ * description before sending, Gemini ignores `additionalProperties`, and no
+ * provider runs a refine or a superRefine. Production, 2026-09-23/24: one
+ * agent failed one call in six on extra keys the strict schema refused, and
+ * another was rejected three runs in a row at its last stage on a value off
+ * an enumerated list — every one on a native-schema model, every one reported
+ * straight to the user, and every one restarted from zero by the caller
+ * because the stage that failed was never asked again.
+ *
+ * So the retry now applies whenever a schema is in play. A genuine schema bug
+ * still surfaces: it fails the same way three times and the last error is
+ * thrown as before, at the cost of two extra calls.
+ * @param expectsJsonResponse - Whether the call expects JSON at all
+ * @param schema - The Zod schema the response is validated against, if any
+ * @returns Whether a validation failure is retried
+ */
+const canRetryValidation = (expectsJsonResponse, schema) => !!expectsJsonResponse && !!schema;
+/**
+ * Whether a failure of the JSON stage is one the model can fix if asked again:
+ * a response that failed schema validation, or one that was not JSON at all
+ * (prose, or JSON with a preamble the extractor could not recover). Everything
+ * else — no messages, a provider error, a transport error — is not.
+ * @param error - The failure
+ * @returns Whether a retry with the errors appended makes sense
+ */
+const isRetryableJsonFailure = (error) => error?.code === const_js_1.default.HTTP_CODES.UNPROCESSABLE_ENTITY ||
+    /non-JSON response when JSON was expected/.test(String(error?.message ?? ""));
+/**
+ * The agentic run takes one user prompt rather than a message list, so a retry
+ * carries the failed output and the errors inside that prompt: the model sees
+ * what it produced and what was wrong with it, the same information
+ * buildValidationRetryMessages gives the non-agentic paths. Previous attempts
+ * accumulate so the model does not oscillate between earlier broken outputs.
+ * @param userPrompt - The prompt of the attempt that failed
+ * @param rawContent - What the model answered
+ * @param error - Why it was refused
+ * @returns The user prompt for the next attempt
+ */
+const buildAgenticRetryPrompt = (userPrompt, rawContent, error) => {
+    const previous = typeof rawContent === "string" ? rawContent : JSON.stringify(rawContent);
+    return `${userPrompt}
+
+---
+Your previous response was rejected:
+${String(error?.message ?? error)}
+
+Your previous response was:
+${previous}
+
+Return a corrected JSON response that fixes ALL of these issues. Respond with the JSON only.`;
+};
 const buildValidationRetryMessages = (priorMessages, rawContent, validationError) => {
     const assistantContent = typeof rawContent === "string" ? rawContent : JSON.stringify(rawContent);
     return [
@@ -1111,6 +1119,58 @@ const buildValidationRetryMessages = (priorMessages, rawContent, validationError
         },
     ];
 };
+/**
+ * The agentic path's JSON stage: the agent's final text as validated JSON.
+ * Direct parse when it looks like JSON, the markdown/preamble extractor
+ * otherwise; a schema failure throws UNPROCESSABLE_ENTITY (validateWithSchema),
+ * anything the extractor cannot recover throws the "non-JSON response" error.
+ * Both are what runPromptWithModel's agentic retry loop asks the model to fix.
+ * @param rawContent - The agent's final message text
+ * @param schema - The Zod schema to validate against, if any
+ * @returns The JSON, re-serialised
+ */
+const parseAgenticJsonResponse = (rawContent, schema) => {
+    if (typeof rawContent === "string") {
+        const trimmed = rawContent.trim();
+        if ((trimmed.startsWith("{") && trimmed.endsWith("}")) ||
+            (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (schema) {
+                    validateWithSchema(parsed, schema);
+                }
+                return JSON.stringify(parsed);
+            }
+            catch (parseError) {
+                if (parseError?.code === const_js_1.default.HTTP_CODES.UNPROCESSABLE_ENTITY) {
+                    throw parseError;
+                }
+            }
+        }
+        // Try to extract JSON from markdown or other wrapping
+        const extracted = extractJSONFromResponse(rawContent);
+        if (extracted) {
+            if (schema) {
+                validateWithSchema(extracted, schema);
+            }
+            return JSON.stringify(extracted);
+        }
+    }
+    let preview = "";
+    if (typeof rawContent === "string") {
+        preview = rawContent.substring(0, 100);
+    }
+    else if (typeof rawContent === "object" && rawContent !== null) {
+        preview = JSON.stringify(rawContent).substring(0, 100);
+    }
+    else if (rawContent !== undefined && rawContent !== null) {
+        preview = String(rawContent).substring(0, 100);
+    }
+    else {
+        preview = "[empty response]";
+    }
+    throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, `Agent returned non-JSON response when JSON was expected: ${preview}...`);
+};
 /**
  * Sends a prompt to an LLM and returns the response, with support for streaming,
  * agentic execution, progress reporting, JSON extraction, and Zod schema validation.
@@ -1193,65 +1253,43 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         // being reconciled from the response afterwards.
         const agent = createAgent(agentName, modelName, systemPrompt, [...tools], null, // responseFormat
         config, usageTracker);
-        // Run the agent with progress callback
-        const response = await runAgent(agent, userPrompt, config, onProgressReport || null, usageTracker);
-        // Extract content from agent response
-        const messages = response?.messages || [];
-        if (messages.length === 0) {
-            throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, "Agent returned no messages");
-        }
-        const lastMessage = messages[messages.length - 1];
-        // Flattens the array content blocks that Gemini/Claude agent responses and
-        // any server-tool turn (e.g. web search) return.
-        const rawContent = extractTextContent(lastMessage?.content);
-        // If not expecting JSON, return raw content directly
-        if (!expectsJsonResponse) {
-            return rawContent;
-        }
-        // Process JSON response similar to non-agentic path
-        if (typeof rawContent === "string") {
-            const trimmed = rawContent.trim();
-            if ((trimmed.startsWith("{") && trimmed.endsWith("}")) ||
-                (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
-                try {
-                    const parsed = JSON.parse(trimmed);
-                    if (schema) {
-                        validateWithSchema(parsed, schema);
-                    }
-                    return JSON.stringify(parsed);
-                }
-                catch (parseError) {
-                    if (parseError?.code === const_js_1.default.HTTP_CODES.UNPROCESSABLE_ENTITY) {
-                        throw parseError;
-                    }
-                }
-            }
-            // Try to extract JSON from markdown or other wrapping
-            const extracted = extractJSONFromResponse(rawContent);
-            if (extracted) {
-                if (schema) {
-                    validateWithSchema(extracted, schema);
-                }
-                return JSON.stringify(extracted);
-            }
-        }
-        if (expectsJsonResponse) {
-            let preview = "";
-            if (typeof rawContent === "string") {
-                preview = rawContent.substring(0, 100);
+        // The JSON stage is retried like the non-agentic paths (canRetryValidation):
+        // the agent is run again with its rejected output and the errors appended
+        // to the user prompt, up to MAX_VALIDATION_RETRIES. Until now this path
+        // had no retry at all, and it is the one every tool-using generation takes.
+        let activeUserPrompt = userPrompt;
+        let attempt = 0;
+        for (;;) {
+            // Run the agent with progress callback
+            const response = await runAgent(agent, activeUserPrompt, config, onProgressReport || null, usageTracker);
+            // Extract content from agent response
+            const messages = response?.messages || [];
+            if (messages.length === 0) {
+                throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, "Agent returned no messages");
             }
-            else if (typeof rawContent === "object" && rawContent !== null) {
-                preview = JSON.stringify(rawContent).substring(0, 100);
+            const lastMessage = messages[messages.length - 1];
+            // Flattens the array content blocks that Gemini/Claude agent responses and
+            // any server-tool turn (e.g. web search) return.
+            const rawContent = extractTextContent(lastMessage?.content);
+            // If not expecting JSON, return raw content directly
+            if (!expectsJsonResponse) {
+                return rawContent;
             }
-            else if (rawContent !== undefined && rawContent !== null) {
-                preview = String(rawContent).substring(0, 100);
+            try {
+                return parseAgenticJsonResponse(rawContent, schema);
             }
-            else {
-                preview = "[empty response]";
+            catch (err) {
+                if (canRetryValidation(expectsJsonResponse, schema) &&
+                    isRetryableJsonFailure(err) &&
+                    attempt < MAX_VALIDATION_RETRIES) {
+                    attempt++;
+                    logger_js_1.default.log(null, logger_js_1.default.levels.warn, `Schema validation failed for "${modelName}", retrying (${attempt}/${MAX_VALIDATION_RETRIES}): ${err.message}`);
+                    activeUserPrompt = buildAgenticRetryPrompt(activeUserPrompt, rawContent, err);
+                    continue;
+                }
+                throw err;
             }
-            throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, `Agent returned non-JSON response when JSON was expected: ${preview}...`);
         }
-        return rawContent;
     }
     let messages;
     if (typeof prompt === "string") {
@@ -1296,13 +1334,13 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         else {
             messagesToSend = messages;
         }
-        // Retry once on schema validation failure. The retry is silent to the progress
+        // Retry on schema validation failure. The retry is silent to the progress
         // callback — same "Generating content..." message and the progress curve
         // continues from the original startTime so the bar doesn't visibly reset.
-        // Skipped when OpenAI native response_format is in use (a 422 there is a
-        // server-side schema bug, not a model output issue). Each attempt accumulates
-        // independently into usageTracker so retry usage is still visible.
-        const canRetryOnValidation = expectsJsonResponse && !!schema && !useNativeSchema;
+        // Each attempt accumulates independently into usageTracker so retry usage
+        // is still visible. Native structured output no longer exempts a model:
+        // see canRetryValidation.
+        const canRetryOnValidation = canRetryValidation(expectsJsonResponse, schema);
         const progressReportInterval = 10; // Report every N chunks
         const overallStartTime = Date.now();
         // Use a time-based asymptotic curve: progress approaches maxPercent but never
@@ -1454,9 +1492,9 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         else {
             messagesToSend = messages;
         }
-        // Retry once on schema validation failure (see streaming branch for rationale).
+        // Retry on schema validation failure (see streaming branch for rationale).
         // Each attempt accumulates independently into usageTracker.
-        const canRetryOnValidation = expectsJsonResponse && !!schema && !useNativeSchema;
+        const canRetryOnValidation = canRetryValidation(expectsJsonResponse, schema);
         let activeMessages = messagesToSend;
         let attempt = 0;
         while (true) {
@@ -1965,6 +2003,11 @@ const runPromptWithModelForVideoGeneration = async (modelName, config, prompt, o
     }
 };
 exports.default = {
+    canRetryValidation,
+    isRetryableJsonFailure,
+    buildAgenticRetryPrompt,
+    parseAgenticJsonResponse,
+    supportsNativeSchema,
     checkIfAIProviderConfigured,
     createAgent,
     runAgent,
@@ -1972,6 +2015,9 @@ exports.default = {
     runPromptWithModelForImageGeneration,
     runPromptWithModelForVideoGeneration,
     throwErrorIfNotSuccessful,
+    updateImageUsageTracker,
+    updateUsageTracker,
     updateUsageTrackerForCharacters,
+    updateVideoUsageTracker,
     validateModel,
 };

package/dist/cjs/runtimeContext.d.ts

@@ -1,3 +1,4 @@
+import type { UsageLedger } from "./usage.js";
 /**
  * Per-request execution context for an agent invocation.
  *
@@ -25,6 +26,8 @@ export interface RequestContext {
         user: any;
         tenant: any;
     } | null;
+    /** What the request used and has not reported to the platform yet (see usage). */
+    usage?: UsageLedger;
 }
 /** Run `fn` with `ctx` bound as the active request context. */
 export declare const runWithContext: <T>(ctx: RequestContext, fn: () => Promise<T>) => Promise<T>;

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

@@ -1 +1 @@
-{"version":3,"file":"runtimeContext.d.ts","sourceRoot":"","sources":["../../src/runtimeContext.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,GAAG,CAAC;IACZ,MAAM,EAAE,GAAG,CAAC;IACZ,OAAO,EAAE,GAAG,CAAC;IACb,KAAK,EAAE,GAAG,CAAC;IACX,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7E,0EAA0E;IAC1E,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,4EAA4E;IAC5E,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,GAAG,CAAC;QAAC,MAAM,EAAE,GAAG,CAAA;KAAE,GAAG,IAAI,CAAC;CAC7C;AAID,+DAA+D;AAC/D,eAAO,MAAM,cAAc,GAAI,CAAC,EAC9B,KAAK,cAAc,EACnB,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAyB,CAAC;AAEtC,oEAAoE;AACpE,eAAO,MAAM,UAAU,QAAO,cAAc,GAAG,SAA+B,CAAC;AAE/E,oDAAoD;AACpD,eAAO,MAAM,cAAc,QAAO,WAAW,GAAG,IACZ,CAAC;AAIrC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAO,IAUjC,CAAC"}
+{"version":3,"file":"runtimeContext.d.ts","sourceRoot":"","sources":["../../src/runtimeContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,GAAG,CAAC;IACZ,MAAM,EAAE,GAAG,CAAC;IACZ,OAAO,EAAE,GAAG,CAAC;IACb,KAAK,EAAE,GAAG,CAAC;IACX,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7E,0EAA0E;IAC1E,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,4EAA4E;IAC5E,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,GAAG,CAAC;QAAC,MAAM,EAAE,GAAG,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5C,kFAAkF;IAClF,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAID,+DAA+D;AAC/D,eAAO,MAAM,cAAc,GAAI,CAAC,EAC9B,KAAK,cAAc,EACnB,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAyB,CAAC;AAEtC,oEAAoE;AACpE,eAAO,MAAM,UAAU,QAAO,cAAc,GAAG,SAA+B,CAAC;AAE/E,oDAAoD;AACpD,eAAO,MAAM,cAAc,QAAO,WAAW,GAAG,IACZ,CAAC;AAIrC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAO,IAUjC,CAAC"}

package/dist/cjs/serve.d.ts

@@ -1,4 +1,5 @@
 import * as grpc from "@grpc/grpc-js";
+import { type ReportUsage } from "./usage.js";
 /**
  * The agent entry point. Reads `params` / `config` / `onProgress` from globals
  * (populated per-request by {@link serve}) and returns the structured result.
@@ -22,7 +23,94 @@ export interface ServeOptions {
     host?: string;
     /** Override the auth check (e.g. in tests). Defaults to {@link defaultAuthenticate}. */
     authenticate?: Authenticator;
+    /** Run-once mode only: override the envelope fetch (e.g. in tests). */
+    fetchEnvelope?: (batchJobId: string, token: string) => Promise<any>;
+    /** Run-once mode only: override the run lifecycle (e.g. in tests). */
+    lifecycle?: RunLifecycle;
+    /** Run-once mode only: override process exit (e.g. in tests). */
+    exit?: (code: number) => void;
+    /** Override how what the work used is reported to the platform (e.g. in tests). */
+    reportUsage?: ReportUsage;
+    /** Override how often running work reports what it used so far (e.g. in tests). */
+    usageReportIntervalMs?: number;
 }
+/**
+ * How an execution reports its own run to the platform: it claims the run
+ * before doing the work, says it is alive while it does, and settles it with
+ * the outcome. Every call carries the execution's AGENT token, which the
+ * platform minted for this run and which names it — which run is never the
+ * execution's to assert.
+ */
+export interface RunLifecycle {
+    claim: (token: string) => Promise<{
+        claimed: boolean;
+    }>;
+    heartbeat: (token: string) => Promise<void>;
+    settle: (status: number, outcome: unknown, token: string) => Promise<{
+        settled: boolean;
+    }>;
+}
+/**
+ * Environment a Cloud Run JOB execution is started with by the platform
+ * (stackfactor-batch-jobs, agentJobExecutions.ts): references only — the
+ * event record, the integration, the tenant, and a token minted for this
+ * execution alone. Their presence is what switches {@link serve} into run-once
+ * mode; the payload and the tenant's configuration are fetched, never passed.
+ */
+export declare const EXECUTION_ENV: {
+    readonly BATCH_JOB_ID: "SF_EXECUTION_BATCH_JOB_ID";
+    readonly INTEGRATION_ID: "SF_EXECUTION_INTEGRATION_ID";
+    readonly TENANT_ID: "SF_EXECUTION_TENANT_ID";
+    readonly TOKEN: "SF_EXECUTION_TOKEN";
+};
+/** True when this process was started as a job execution rather than a service. */
+export declare const isRunOnceExecution: (env?: NodeJS.ProcessEnv) => boolean;
+/**
+ * True for the one kind of run that is ALLOWED to carry no StackFactor token: a
+ * delivery to a webhook declared `requireToken: false`. There the platform
+ * authenticates nobody and passes the provider's request to the integration as
+ * it arrived, so there is no token to validate and no session to build — the
+ * handler verifies its provider itself, and brings its own API key (from its
+ * configuration) if it has to act on the platform.
+ *
+ * This does not open the agent up. The Execute RPC is reachable only by callers
+ * holding Cloud Run's invoker role — the backend and the batch worker — so a
+ * request with no token means the platform CHOSE to send none, and it only ever
+ * does that for such a webhook. A token that IS present is always validated,
+ * whatever the event, and every other event still requires one.
+ */
+export declare const isAnonymousWebhookRun: (event: any, request: any) => boolean;
+/**
+ * True for the runs that are ALLOWED to carry no StackFactor token, because
+ * the platform starts them with no identity on purpose:
+ *  - a delivery to a `requireToken: false` webhook (isAnonymousWebhookRun);
+ *  - a scheduled run: the clock is nobody.
+ * Both run with `session: null`. Since backend-core's decision record §11 the
+ * platform starts both with a token of their own (the integration's managed
+ * account in the tenant), so against a current platform neither is ever
+ * tokenless and this answers false; it stays for a platform that predates
+ * that, and can go once none does. The reasoning of isAnonymousWebhookRun holds
+ * for both: only the platform can reach Execute or start an execution, so no
+ * token means the platform chose to send none. A token that IS present is
+ * always validated, and every other event still requires one.
+ */
+export declare const isAnonymousRun: (event: any, request: any) => boolean;
+/**
+ * Run-once mode: the same agent, started as one Cloud Run JOB execution for
+ * one platform event (`runAs: job`). Fetches the execution's envelope from the
+ * backend with the execution's token — exactly what a service call would have
+ * received in its Execute request — binds the same {@link RequestContext} the
+ * gRPC path binds, runs the handler once, and exits: 0 on success, 1 on any
+ * failure so Cloud Run retries the task. SIGTERM (Cloud Run cancelling the
+ * execution or its task timeout) aborts the in-flight work.
+ *
+ * The execution reports its own run: it claims it before doing the work (an
+ * execution that loses the claim exits 0 without repeating it), says it is
+ * alive while it runs, and settles it with the outcome. The handler is
+ * written once and does not know which runtime it is on, nor that any of this
+ * is happening.
+ */
+export declare const runOnce: (main: AgentMain, options?: ServeOptions) => Promise<void>;
 /**
  * Start a gRPC server that exposes `main` as the fleet-standard `Agent.Execute`
  * RPC. Per request it binds a {@link RequestContext} (so the agent's globals are

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;AA+PtC;;;;;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,MA8MP,CAAC"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AAWtC,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AAwPpB;;;;;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;IAC7B,uEAAuE;IACvE,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IACpE,sEAAsE;IACtE,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,iEAAiE;IACjE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,mFAAmF;IACnF,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,mFAAmF;IACnF,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACxD,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,EAAE,CACN,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,KACV,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACpC;AAKD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX,mFAAmF;AACnF,eAAO,MAAM,kBAAkB,GAAI,MAAK,MAAM,CAAC,UAAwB,KAAG,OACJ,CAAC;AAKvE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,GAAI,OAAO,GAAG,EAAE,SAAS,GAAG,KAAG,OAEhB,CAAC;AAKlD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,GAAG,EAAE,SAAS,GAAG,KAAG,OAGN,CAAC;AA4JrD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,OAAO,GAClB,MAAM,SAAS,EACf,UAAS,YAAiB,KACzB,OAAO,CAAC,IAAI,CA8Id,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAChB,MAAM,SAAS,EACf,UAAS,YAAiB,KACzB,IAAI,CAAC,MAyOP,CAAC"}