@stackfactor/agent-utils 1.4.3 → 1.7.0

package/dist/cjs/serve.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.serve = void 0;
+exports.serve = exports.runOnce = exports.isAnonymousRun = exports.isAnonymousWebhookRun = exports.isRunOnceExecution = exports.EXECUTION_ENV = void 0;
 const grpc = __importStar(require("@grpc/grpc-js"));
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -45,6 +45,7 @@ const client_api_1 = require("@stackfactor/client-api");
 const logger_js_1 = __importDefault(require("./logger.js"));
 const agentProto_js_1 = require("./agentProto.js");
 const runtimeContext_js_1 = require("./runtimeContext.js");
+const usage_js_1 = require("./usage.js");
 // Genuine dynamic `import()` that survives TypeScript's CJS downlevelling (which
 // would otherwise turn `import()` into `require()` and break file:// URLs and
 // ESM check modules). Built once; see the call site in runSelfCheck.
@@ -234,6 +235,63 @@ const runSelfCheck = async (checkCode, config, session) => {
         clearTimeout(timer);
     }
 };
+/** How often a running execution says it is still alive. */
+const HEARTBEAT_MS = 30_000;
+/**
+ * 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.
+ */
+exports.EXECUTION_ENV = {
+    BATCH_JOB_ID: "SF_EXECUTION_BATCH_JOB_ID",
+    INTEGRATION_ID: "SF_EXECUTION_INTEGRATION_ID",
+    TENANT_ID: "SF_EXECUTION_TENANT_ID",
+    TOKEN: "SF_EXECUTION_TOKEN",
+};
+/** True when this process was started as a job execution rather than a service. */
+const isRunOnceExecution = (env = process.env) => Boolean(env[exports.EXECUTION_ENV.BATCH_JOB_ID] && env[exports.EXECUTION_ENV.TOKEN]);
+exports.isRunOnceExecution = isRunOnceExecution;
+/** `ExecuteRequest.event` of an inbound webhook delivery (backend-core EVENT_TYPE.WEBHOOK_RECEIVED). */
+const WEBHOOK_RECEIVED = 350;
+/**
+ * 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.
+ */
+const isAnonymousWebhookRun = (event, request) => Number(event) === WEBHOOK_RECEIVED &&
+    !(request?.authToken ?? request?.authorization);
+exports.isAnonymousWebhookRun = isAnonymousWebhookRun;
+/** `ExecuteRequest.event` of a scheduled run (backend-core EVENT_TYPE.SCHEDULED_RUN). */
+const SCHEDULED_RUN = 510;
+/**
+ * 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.
+ */
+const isAnonymousRun = (event, request) => (0, exports.isAnonymousWebhookRun)(event, request) ||
+    (Number(event) === SCHEDULED_RUN &&
+        !(request?.authToken ?? request?.authorization));
+exports.isAnonymousRun = isAnonymousRun;
 /** Marks an auth failure so the handler can map it to gRPC UNAUTHENTICATED. */
 class UnauthenticatedError extends Error {
 }
@@ -336,6 +394,150 @@ const toErrorFrame = (error) => {
     }
     return { code: 500, message: String(error?.message ?? error) };
 };
+/** How the platform records a settled run (backend-core BATCH_JOB.STATUS). */
+const RUN_STATUS = { COMPLETED: 2, FAILED: 3 };
+/**
+ * Settles the run this execution claimed, if it claimed one. Never throws and
+ * never changes the execution's own outcome: the work either happened or it
+ * did not, and a platform that cannot be told so right now will time the run
+ * out on its own. `settled: false` means it already did.
+ */
+const settleRun = async (claimed, lifecycle, status, outcome, batchJobId) => {
+    if (!claimed)
+        return;
+    try {
+        const answer = await lifecycle.settle(status, outcome ?? null, claimed.token);
+        if (!answer?.settled) {
+            logger_js_1.default.log(null, logger_js_1.default.levels.warn, `run-once execution for event record ${batchJobId}: the run was no longer running, so its outcome was not recorded`);
+        }
+    }
+    catch (error) {
+        logger_js_1.default.log(null, logger_js_1.default.levels.warn, `run-once execution for event record ${batchJobId}: settling the run failed: ${error?.message ?? error}`);
+    }
+};
+/**
+ * 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.
+ */
+const runOnce = async (main, options = {}) => {
+    (0, runtimeContext_js_1.installGlobals)();
+    const exit = options.exit ?? ((code) => process.exit(code));
+    const batchJobId = process.env[exports.EXECUTION_ENV.BATCH_JOB_ID] ?? "";
+    const token = process.env[exports.EXECUTION_ENV.TOKEN] ?? "";
+    const fetchEnvelope = options.fetchEnvelope ??
+        ((id, tok) => client_api_1.integration.getExecutionEnvelope(id, tok));
+    const authenticate = options.authenticate ?? defaultAuthenticate;
+    const abort = new AbortController();
+    const onSignal = () => abort.abort();
+    process.once("SIGTERM", onSignal);
+    process.once("SIGINT", onSignal);
+    const lifecycle = options.lifecycle ?? {
+        claim: client_api_1.integration.claimExecution,
+        heartbeat: client_api_1.integration.heartbeatExecution,
+        settle: client_api_1.integration.settleExecution,
+    };
+    // Set once the run is ours: only an execution that claimed a run settles it.
+    let claimed = null;
+    let heartbeat = null;
+    // What the run used is reported before it is settled, however it ended:
+    // settling revokes the token the report is made with.
+    let reportWhatWasUsed = async () => { };
+    let stopReporting = () => { };
+    try {
+        const req = await fetchEnvelope(batchJobId, token);
+        const request = safeParse(req?.request_json, {});
+        // A scheduled run carries no identity by design: see isAnonymousRun.
+        const session = (0, exports.isAnonymousRun)(req?.event, request)
+            ? null
+            : await authenticate(request);
+        const context = {
+            config: safeParse(req?.config_json, {}),
+            params: {
+                contentType: req?.content_type,
+                data: safeParse(req?.data_json, {}),
+            },
+            request: { ...request, session },
+            event: req?.event ?? 0,
+            onProgress: (update) => {
+                logger_js_1.default.log(null, logger_js_1.default.levels.info, `progress ${Math.round(update?.progress ?? 0)}%: ${update?.message ?? ""}`);
+            },
+            signal: abort.signal,
+            session,
+            usage: new usage_js_1.UsageLedger(),
+        };
+        reportWhatWasUsed = () => (0, usage_js_1.reportUsage)(context, { report: options.reportUsage, last: true });
+        let entry = main;
+        const entryPath = String(req?.code ?? "").trim();
+        if (entryPath) {
+            const loaded = await loadAgentModule(entryPath, "handler");
+            if (loaded.reason) {
+                throw new Error(`entry module "${entryPath}" could not be loaded (${loaded.reason}): ${loaded.detail}`);
+            }
+            entry = loaded.fn;
+        }
+        // Claim before doing anything. Of however many executions the platform may
+        // start for one run — a retried task, a redelivered message — exactly one
+        // wins; the others exit 0 without repeating the work, which is not a
+        // failure and must not be retried. The execution's token names its run
+        // (every run, scheduled ones included, is started with one), so nothing
+        // else is sent.
+        const answer = await lifecycle.claim(token);
+        if (!answer?.claimed) {
+            logger_js_1.default.log(null, logger_js_1.default.levels.info, `run-once execution for event record ${batchJobId}: another execution already claimed this run, nothing to do`);
+            exit(0);
+            return;
+        }
+        claimed = { token };
+        heartbeat = setInterval(() => {
+            void lifecycle
+                .heartbeat(token)
+                .catch((error) => logger_js_1.default.log(null, logger_js_1.default.levels.warn, `run-once execution for event record ${batchJobId}: heartbeat failed: ${error?.message ?? error}`));
+        }, HEARTBEAT_MS);
+        heartbeat.unref?.();
+        stopReporting = (0, usage_js_1.reportUsageWhileRunning)(context, {
+            report: options.reportUsage,
+            intervalMs: options.usageReportIntervalMs,
+        });
+        logger_js_1.default.log(null, logger_js_1.default.levels.info, `run-once execution for event record ${batchJobId} (${req?.content_type ?? ""}) starting`);
+        const result = await (0, runtimeContext_js_1.runWithContext)(context, () => entry(abort.signal));
+        logger_js_1.default.log(null, logger_js_1.default.levels.info, `run-once execution for event record ${batchJobId} completed: ${JSON.stringify(result ?? null).slice(0, 500)}`);
+        stopReporting();
+        await reportWhatWasUsed();
+        await settleRun(claimed, lifecycle, RUN_STATUS.COMPLETED, result, batchJobId);
+        exit(0);
+    }
+    catch (error) {
+        const frame = toErrorFrame(error);
+        logger_js_1.default.log(null, logger_js_1.default.levels.error, `run-once execution for event record ${batchJobId} failed${abort.signal.aborted ? " (aborted)" : ""}: ${frame.code} ${frame.message}`);
+        // Work that failed still used what it used.
+        stopReporting();
+        await reportWhatWasUsed();
+        // The run is ours to close whether it went well or not: a run left
+        // running is one the platform has to time out, and its credential lives
+        // until it does.
+        await settleRun(claimed, lifecycle, RUN_STATUS.FAILED, frame, batchJobId);
+        exit(1);
+    }
+    finally {
+        stopReporting();
+        if (heartbeat)
+            clearInterval(heartbeat);
+        process.off("SIGTERM", onSignal);
+        process.off("SIGINT", onSignal);
+    }
+};
+exports.runOnce = runOnce;
 /**
  * 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
@@ -348,6 +550,12 @@ const toErrorFrame = (error) => {
  *   serve(require("./src/main"));
  */
 const serve = (main, options = {}) => {
+    // Started as a job execution: run the handler once and exit instead of
+    // serving. Same image, same entrypoint; the environment decides.
+    if ((0, exports.isRunOnceExecution)()) {
+        void (0, exports.runOnce)(main, options);
+        return new grpc.Server();
+    }
     (0, runtimeContext_js_1.installGlobals)();
     const port = options.port ?? (Number(process.env.PORT) || 8080);
     const host = options.host ?? "0.0.0.0";
@@ -370,9 +578,13 @@ const serve = (main, options = {}) => {
         };
         const handle = async () => {
             // Authenticate first — refuse the call when the token is missing/invalid.
-            let session;
+            // The exceptions carry no token by design and run with no session: see
+            // isAnonymousRun.
+            let session = null;
             try {
-                session = await authenticate(request);
+                if (!(0, exports.isAnonymousRun)(req.event, request)) {
+                    session = await authenticate(request);
+                }
             }
             catch (error) {
                 const message = error?.message ?? "Unauthenticated";
@@ -397,6 +609,7 @@ const serve = (main, options = {}) => {
                 onProgress,
                 signal: abort.signal,
                 session,
+                usage: new usage_js_1.UsageLedger(),
             };
             // Which function actually runs. Default is the agent's own `main` — the
             // path every caller took before `code` existed, and still the path taken
@@ -427,8 +640,21 @@ const serve = (main, options = {}) => {
                 }
                 entry = loaded.fn;
             }
+            // What the call used is reported before it is answered, however it
+            // ended — a call that failed, or that its caller gave up on, still used
+            // what it used — because the platform revokes the call's token as soon
+            // as it has the answer.
+            const stopReporting = (0, usage_js_1.reportUsageWhileRunning)(context, {
+                report: options.reportUsage,
+                intervalMs: options.usageReportIntervalMs,
+            });
+            const reportWhatWasUsed = async () => {
+                stopReporting();
+                await (0, usage_js_1.reportUsage)(context, { report: options.reportUsage, last: true });
+            };
             try {
                 const result = await (0, runtimeContext_js_1.runWithContext)(context, () => entry(abort.signal));
+                await reportWhatWasUsed();
                 if (!abort.signal.aborted) {
                     call.write({
                         result: { result_json: JSON.stringify(result ?? null) },
@@ -436,6 +662,7 @@ const serve = (main, options = {}) => {
                 }
             }
             catch (error) {
+                await reportWhatWasUsed();
                 if (!abort.signal.aborted) {
                     logger_js_1.default.log(null, logger_js_1.default.levels.error, `agent Execute failed: ${error?.message ?? error}`);
                     call.write({ error: toErrorFrame(error) });

package/dist/cjs/tavily.d.ts

@@ -86,6 +86,10 @@ declare const _default: {
     assertTavilyUsable: (config: any, options: TavilyConfig) => void;
     buildTavilyTools: (config: any, options: TavilyConfig, usageTracker?: UsageTracker | null) => any[];
     getTavilyOptions: (config: any) => TavilyConfig | null;
+    recordTavilyUsage: (tracker: UsageTracker | null | undefined, _config: any, credits: number, sources: {
+        url: string;
+        title?: string;
+    }[]) => void;
 };
 export default _default;
 //# sourceMappingURL=tavily.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tavily.d.ts","sourceRoot":"","sources":["../../src/tavily.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AA6BnD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,CAAC;AAEpE;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,iEAAiE;IACjE,WAAW,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,YAAY,CAAC;IAC3D,kFAAkF;IAClF,YAAY,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IACpC,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;CAC9B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,GAAG,KAAG,YAAY,GAAG,IAI7D,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,GAAG,EAAE,SAAS,YAAY,KAAG,IAsBvE,CAAC;AAqLF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,GAAG,EACX,SAAS,YAAY,EACrB,eAAc,YAAY,GAAG,IAAW,KACvC,GAAG,EA2PL,CAAC;;iCA3dyC,GAAG,WAAW,YAAY,KAAG,IAAI;+BA6NlE,GAAG,WACF,YAAY,iBACP,YAAY,GAAG,IAAI,KAChC,GAAG,EAAE;+BA/OiC,GAAG,KAAG,YAAY,GAAG,IAAI;;AA4elE,wBAIE"}
+{"version":3,"file":"tavily.d.ts","sourceRoot":"","sources":["../../src/tavily.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AA0BnD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,CAAC;AAEpE;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,iEAAiE;IACjE,WAAW,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,YAAY,CAAC;IAC3D,kFAAkF;IAClF,YAAY,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IACpC,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;CAC9B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,GAAG,KAAG,YAAY,GAAG,IAI7D,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,GAAG,EAAE,SAAS,YAAY,KAAG,IAsBvE,CAAC;AAsLF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,GAAG,EACX,SAAS,YAAY,EACrB,eAAc,YAAY,GAAG,IAAW,KACvC,GAAG,EA2PL,CAAC;;iCA5dyC,GAAG,WAAW,YAAY,KAAG,IAAI;+BA8NlE,GAAG,WACF,YAAY,iBACP,YAAY,GAAG,IAAI,KAChC,GAAG,EAAE;+BAhPiC,GAAG,KAAG,YAAY,GAAG,IAAI;iCAsIvD,YAAY,GAAG,IAAI,GAAG,SAAS,WAC/B,GAAG,WACH,MAAM,WACN;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,KACzC,IAAI;;AAmWP,wBAKE"}

package/dist/cjs/tavily.js

@@ -10,9 +10,8 @@ const const_js_1 = __importDefault(require("./const.js"));
 const errorHandling_js_1 = __importDefault(require("./errorHandling.js"));
 const logger_js_1 = __importDefault(require("./logger.js"));
 const runtimeContext_js_1 = require("./runtimeContext.js");
+const usage_js_1 = require("./usage.js");
 const TAVILY_API_BASE = "https://api.tavily.com";
-/** Tavily list price per credit, used when the integration defines no rate. */
-const DEFAULT_CREDIT_COST_USD = 0.008;
 /**
  * Context budgets, in characters, applied to everything a tool hands back to
  * the model. Tavily returns whatever the page holds, and unlike a provider's
@@ -129,19 +128,25 @@ const callTavily = async (endpoint, body, apiKey, timeoutSeconds) => {
         throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, `Tavily ${endpoint} returned ${response.status}: ${detail.slice(0, 500)}`);
     }
 };
+/** The name Tavily's credits are counted and priced under. */
+const TAVILY_MODEL = "tavily";
 /**
- * Adds one Tavily call's credits to the tracker and records the URLs it
- * returned. Credits come from the response's own `usage` block, priced with the
- * `tavily-credit-costs` constant (USD per credit) and accumulated under
- * `tavilyCredits`. Sources land on `tracker.webSearchSources`, deduplicated by
- * URL across the whole run, so callers have the citation list Tavily's terms
- * require when this output is shown to end users.
- * @param tracker - The caller's usage accumulator; no-ops when absent
- * @param config - Config object carrying the `tavily-credit-costs` constant
+ * Counts one Tavily call's credits and records the URLs it returned. Credits
+ * come from the response's own `usage` block; they are counted into the
+ * request's usage ledger, which is reported to the platform, and into the
+ * caller's tracker under `tavilyCredits`. Sources land on
+ * `tracker.webSearchSources`, deduplicated by URL across the whole run, so
+ * callers have the citation list Tavily's terms require when this output is
+ * shown to end users.
+ * @param tracker - The caller's usage accumulator, when it passed one
+ * @param _config - No longer read: it carried the rate, which is the platform's to say
  * @param credits - Credits reported by the Tavily response
  * @param sources - URLs (and titles where known) the call returned
  */
-const recordTavilyUsage = (tracker, config, credits, sources) => {
+const recordTavilyUsage = (tracker, _config, credits, sources) => {
+    if (Number.isFinite(credits) && credits > 0) {
+        (0, usage_js_1.recordUsage)(TAVILY_MODEL, "credits", credits);
+    }
     if (!tracker)
         return;
     if (typeof tracker.cost !== "number")
@@ -149,13 +154,6 @@ const recordTavilyUsage = (tracker, config, credits, sources) => {
     if (!tracker.tokens || typeof tracker.tokens !== "object")
         tracker.tokens = {};
     if (Number.isFinite(credits) && credits > 0) {
-        const configured = Number(config?.["tavily-credit-costs"]);
-        const rate = Number.isFinite(configured)
-            ? configured
-            : DEFAULT_CREDIT_COST_USD;
-        const addedCost = credits * rate;
-        if (Number.isFinite(addedCost) && addedCost > 0)
-            tracker.cost += addedCost;
         tracker.tokens.tavilyCredits =
             (tracker.tokens.tavilyCredits || 0) + credits;
     }
@@ -401,4 +399,5 @@ exports.default = {
     assertTavilyUsable: exports.assertTavilyUsable,
     buildTavilyTools: exports.buildTavilyTools,
     getTavilyOptions: exports.getTavilyOptions,
+    recordTavilyUsage,
 };

package/dist/cjs/usage.d.ts

@@ -0,0 +1,74 @@
+import { type RequestContext } from "./runtimeContext.js";
+/**
+ * What an agent used, and how the platform gets to know.
+ *
+ * An agent says WHAT it used — a model, a unit, an amount — and the platform
+ * says what that costs, who is charged and what it was for. Everything that
+ * calls a model through this package counts what the call used into the
+ * request's {@link UsageLedger}; {@link serve} and {@link runOnce} report the
+ * ledger to the platform while the work runs and when it ends, whether it
+ * ended well or not. An agent does nothing for this to happen.
+ *
+ * An agent that calls a provider itself — its own SDK, an HTTP request —
+ * counts what that used with {@link recordUsage}.
+ */
+/** What usage is counted in; the units the platform has rates for. */
+export declare const USAGE_UNITS: readonly ["inputTokens", "outputTokens", "imageInputTokens", "imageOutputTokens", "characters", "seconds", "credits"];
+export type UsageUnit = (typeof USAGE_UNITS)[number];
+export interface UsageEntry {
+    model: string;
+    unit: UsageUnit;
+    amount: number;
+}
+/** Sends one report to the platform. Rejects when the platform did not take it. */
+export type ReportUsage = (usage: UsageEntry[], reportId: string, token: string) => Promise<unknown>;
+/** How often work that is still running reports what it used so far. */
+export declare const USAGE_REPORT_INTERVAL_MS = 60000;
+/**
+ * What one request used and has not reported yet, summed by model and unit.
+ */
+export declare class UsageLedger {
+    private pending;
+    /** Adds to what is pending. Anything that is not a positive amount of a known unit is ignored. */
+    add(model: string, unit: UsageUnit, amount: number): void;
+    /** What is pending, which then no longer is. */
+    take(): UsageEntry[];
+    /** True when there is nothing to report. */
+    get isEmpty(): boolean;
+}
+/**
+ * Counts what the running request used. For an agent that calls a provider
+ * itself; what is called through `langChain` is counted already. Outside a
+ * request there is nothing to count into, and nothing happens.
+ * @param model - The model's id, as its provider names it
+ * @param unit - What the amount is counted in
+ * @param amount - How much
+ */
+export declare const recordUsage: (model: string, unit: UsageUnit, amount: number) => void;
+/**
+ * Reports what the request used and has not reported yet. Never throws, and
+ * never changes what the work answers: the work happened, and a platform that
+ * cannot be told what it used right now is told by the next report, or not at
+ * all — which is logged as an error, with what was used.
+ *
+ * @param context - The request whose ledger is reported
+ * @param options - `report` sends a report (default: the platform's route);
+ *   `last` says no other report follows, so what cannot be sent is given up on
+ *   rather than kept for the next one
+ */
+export declare const reportUsage: (context: Pick<RequestContext, "usage" | "request"> | undefined, options?: {
+    report?: ReportUsage;
+    last?: boolean;
+    retryBaseMs?: number;
+}) => Promise<void>;
+/**
+ * Reports what the request used so far every {@link USAGE_REPORT_INTERVAL_MS}
+ * while the work runs, so work that dies has reported most of what it used.
+ * @returns Stops it
+ */
+export declare const reportUsageWhileRunning: (context: Pick<RequestContext, "usage" | "request">, options?: {
+    report?: ReportUsage;
+    intervalMs?: number;
+    retryBaseMs?: number;
+}) => (() => void);
+//# sourceMappingURL=usage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/usage.ts"],"names":[],"mappings":"AAGA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEtE;;;;;;;;;;;;GAYG;AAEH,sEAAsE;AACtE,eAAO,MAAM,WAAW,uHAQd,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,mFAAmF;AACnF,MAAM,MAAM,WAAW,GAAG,CACxB,KAAK,EAAE,UAAU,EAAE,EACnB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,KACV,OAAO,CAAC,OAAO,CAAC,CAAC;AAOtB,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAI/C;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAiC;IAEhD,kGAAkG;IAClG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAkBzD,gDAAgD;IAChD,IAAI,IAAI,UAAU,EAAE;IAMpB,4CAA4C;IAC5C,IAAI,OAAO,IAAI,OAAO,CAErB;CACF;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,EAAE,MAAM,SAAS,EAAE,QAAQ,MAAM,KAAG,IAE5E,CAAC;AA8BF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,GACtB,SAAS,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,SAAS,CAAC,GAAG,SAAS,EAC9D,UAAS;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,KAC3E,OAAO,CAAC,IAAI,CAuCd,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GAClC,SAAS,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,SAAS,CAAC,EAClD,UAAS;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,KAChF,CAAC,MAAM,IAAI,CAMb,CAAC"}

package/dist/cjs/usage.js

@@ -0,0 +1,160 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reportUsageWhileRunning = exports.reportUsage = exports.recordUsage = exports.UsageLedger = exports.USAGE_REPORT_INTERVAL_MS = exports.USAGE_UNITS = void 0;
+const node_crypto_1 = require("node:crypto");
+const client_api_1 = require("@stackfactor/client-api");
+const logger_js_1 = __importDefault(require("./logger.js"));
+const runtimeContext_js_1 = require("./runtimeContext.js");
+/**
+ * What an agent used, and how the platform gets to know.
+ *
+ * An agent says WHAT it used — a model, a unit, an amount — and the platform
+ * says what that costs, who is charged and what it was for. Everything that
+ * calls a model through this package counts what the call used into the
+ * request's {@link UsageLedger}; {@link serve} and {@link runOnce} report the
+ * ledger to the platform while the work runs and when it ends, whether it
+ * ended well or not. An agent does nothing for this to happen.
+ *
+ * An agent that calls a provider itself — its own SDK, an HTTP request —
+ * counts what that used with {@link recordUsage}.
+ */
+/** What usage is counted in; the units the platform has rates for. */
+exports.USAGE_UNITS = [
+    "inputTokens",
+    "outputTokens",
+    "imageInputTokens",
+    "imageOutputTokens",
+    "characters",
+    "seconds",
+    "credits",
+];
+/** Entries one report may carry (the platform's limit). */
+const REPORT_ENTRIES_MAX = 100;
+/** How often a report is tried before it is given up on, and the first wait between tries. */
+const REPORT_ATTEMPTS = 3;
+const REPORT_RETRY_BASE_MS = 500;
+/** How often work that is still running reports what it used so far. */
+exports.USAGE_REPORT_INTERVAL_MS = 60_000;
+const keyOf = (model, unit) => `${model}\n${unit}`;
+/**
+ * What one request used and has not reported yet, summed by model and unit.
+ */
+class UsageLedger {
+    pending = new Map();
+    /** Adds to what is pending. Anything that is not a positive amount of a known unit is ignored. */
+    add(model, unit, amount) {
+        if (typeof model !== "string" ||
+            model.trim().length === 0 ||
+            !exports.USAGE_UNITS.includes(unit) ||
+            typeof amount !== "number" ||
+            !Number.isFinite(amount) ||
+            amount <= 0) {
+            return;
+        }
+        const name = model.trim();
+        const key = keyOf(name, unit);
+        const entry = this.pending.get(key);
+        if (entry)
+            entry.amount += amount;
+        else
+            this.pending.set(key, { model: name, unit, amount });
+    }
+    /** What is pending, which then no longer is. */
+    take() {
+        const entries = [...this.pending.values()];
+        this.pending = new Map();
+        return entries;
+    }
+    /** True when there is nothing to report. */
+    get isEmpty() {
+        return this.pending.size === 0;
+    }
+}
+exports.UsageLedger = UsageLedger;
+/**
+ * Counts what the running request used. For an agent that calls a provider
+ * itself; what is called through `langChain` is counted already. Outside a
+ * request there is nothing to count into, and nothing happens.
+ * @param model - The model's id, as its provider names it
+ * @param unit - What the amount is counted in
+ * @param amount - How much
+ */
+const recordUsage = (model, unit, amount) => {
+    (0, runtimeContext_js_1.getContext)()?.usage?.add(model, unit, amount);
+};
+exports.recordUsage = recordUsage;
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const defaultReport = (usage, reportId, token) => client_api_1.integration.reportRunUsage(usage, reportId, token);
+/**
+ * Sends one report, again when it fails, under the same name every time: the
+ * platform charges a report it has seen only once.
+ */
+const send = async (entries, token, report, retryBaseMs) => {
+    const reportId = (0, node_crypto_1.randomUUID)();
+    for (let attempt = 1;; attempt++) {
+        try {
+            await report(entries, reportId, token);
+            return;
+        }
+        catch (error) {
+            if (attempt >= REPORT_ATTEMPTS)
+                throw error;
+            await delay(retryBaseMs * 2 ** (attempt - 1));
+        }
+    }
+};
+/**
+ * Reports what the request used and has not reported yet. Never throws, and
+ * never changes what the work answers: the work happened, and a platform that
+ * cannot be told what it used right now is told by the next report, or not at
+ * all — which is logged as an error, with what was used.
+ *
+ * @param context - The request whose ledger is reported
+ * @param options - `report` sends a report (default: the platform's route);
+ *   `last` says no other report follows, so what cannot be sent is given up on
+ *   rather than kept for the next one
+ */
+const reportUsage = async (context, options = {}) => {
+    const ledger = context?.usage;
+    if (!ledger || ledger.isEmpty)
+        return;
+    const token = context.request?.authToken ?? context.request?.authorization;
+    const entries = ledger.take();
+    if (!token) {
+        logger_js_1.default.log(null, logger_js_1.default.levels.error, `usage was not reported, the request carries no token: ${JSON.stringify(entries)}`);
+        return;
+    }
+    for (let start = 0; start < entries.length; start += REPORT_ENTRIES_MAX) {
+        const chunk = entries.slice(start, start + REPORT_ENTRIES_MAX);
+        try {
+            await send(chunk, token, options.report ?? defaultReport, options.retryBaseMs ?? REPORT_RETRY_BASE_MS);
+        }
+        catch (error) {
+            if (options.last) {
+                logger_js_1.default.log(null, logger_js_1.default.levels.error, `usage could not be reported (${error?.message ?? error}): ${JSON.stringify(chunk)}`);
+            }
+            else {
+                for (const entry of chunk)
+                    ledger.add(entry.model, entry.unit, entry.amount);
+                logger_js_1.default.log(null, logger_js_1.default.levels.warn, `usage could not be reported, it is kept for the next report: ${error?.message ?? error}`);
+            }
+        }
+    }
+};
+exports.reportUsage = reportUsage;
+/**
+ * Reports what the request used so far every {@link USAGE_REPORT_INTERVAL_MS}
+ * while the work runs, so work that dies has reported most of what it used.
+ * @returns Stops it
+ */
+const reportUsageWhileRunning = (context, options = {}) => {
+    const timer = setInterval(() => {
+        void (0, exports.reportUsage)(context, { report: options.report, retryBaseMs: options.retryBaseMs });
+    }, options.intervalMs ?? exports.USAGE_REPORT_INTERVAL_MS);
+    timer.unref?.();
+    return () => clearInterval(timer);
+};
+exports.reportUsageWhileRunning = reportUsageWhileRunning;

package/dist/esm/index.d.ts

@@ -2,9 +2,10 @@ import constants from "./const.js";
 import errorHandling, { AppError } from "./errorHandling.js";
 import langChain from "./langChain.js";
 import logger from "./logger.js";
-import { serve } from "./serve.js";
+import { serve, runOnce, isRunOnceExecution, EXECUTION_ENV } from "./serve.js";
 import { callAgent, checkAgent } from "./client.js";
 import * as runtimeContext from "./runtimeContext.js";
+import { recordUsage, USAGE_UNITS } from "./usage.js";
 export { constants };
 export { errorHandling, AppError };
 export type { ParsedError } from "./errorHandling.js";
@@ -12,9 +13,11 @@ export { langChain };
 export type { UsageTracker } from "./langChain.js";
 export type { TavilyConfig, TavilyToolName } from "./tavily.js";
 export { logger };
-export { serve };
+export { serve, runOnce, isRunOnceExecution, EXECUTION_ENV };
 export { callAgent };
 export { checkAgent };
 export type { AgentExecuteRequest, CallAgentOptions, CheckAgentOptions, AgentHealth, } from "./client.js";
 export { runtimeContext };
+export { recordUsage, USAGE_UNITS };
+export type { UsageEntry, UsageUnit } from "./usage.js";
 //# sourceMappingURL=index.d.ts.map

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,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,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,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,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,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,CAAC;AAE7D,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;AAE1B,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;AAEpC,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}