@stackfactor/agent-utils 1.4.3 → 1.7.0

package/dist/esm/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/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;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"}

package/dist/esm/serve.js

@@ -2,10 +2,11 @@ import * as grpc from "@grpc/grpc-js";
 import { existsSync } from "node:fs";
 import { resolve, relative, isAbsolute } from "node:path";
 import { pathToFileURL } from "node:url";
-import { session as clientSession } from "@stackfactor/client-api";
+import { integration as clientIntegration, session as clientSession, } from "@stackfactor/client-api";
 import logger from "./logger.js";
 import { loadAgentService } from "./agentProto.js";
 import { runWithContext, installGlobals } from "./runtimeContext.js";
+import { UsageLedger, reportUsage, reportUsageWhileRunning, } from "./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.
@@ -195,6 +196,60 @@ 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.
+ */
+export const 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. */
+export const isRunOnceExecution = (env = process.env) => Boolean(env[EXECUTION_ENV.BATCH_JOB_ID] && env[EXECUTION_ENV.TOKEN]);
+/** `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.
+ */
+export const isAnonymousWebhookRun = (event, request) => Number(event) === WEBHOOK_RECEIVED &&
+    !(request?.authToken ?? request?.authorization);
+/** `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.
+ */
+export const isAnonymousRun = (event, request) => isAnonymousWebhookRun(event, request) ||
+    (Number(event) === SCHEDULED_RUN &&
+        !(request?.authToken ?? request?.authorization));
 /** Marks an auth failure so the handler can map it to gRPC UNAUTHENTICATED. */
 class UnauthenticatedError extends Error {
 }
@@ -297,6 +352,149 @@ 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.log(null, logger.levels.warn, `run-once execution for event record ${batchJobId}: the run was no longer running, so its outcome was not recorded`);
+        }
+    }
+    catch (error) {
+        logger.log(null, logger.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.
+ */
+export const runOnce = async (main, options = {}) => {
+    installGlobals();
+    const exit = options.exit ?? ((code) => process.exit(code));
+    const batchJobId = process.env[EXECUTION_ENV.BATCH_JOB_ID] ?? "";
+    const token = process.env[EXECUTION_ENV.TOKEN] ?? "";
+    const fetchEnvelope = options.fetchEnvelope ??
+        ((id, tok) => clientIntegration.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: clientIntegration.claimExecution,
+        heartbeat: clientIntegration.heartbeatExecution,
+        settle: clientIntegration.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 = 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.log(null, logger.levels.info, `progress ${Math.round(update?.progress ?? 0)}%: ${update?.message ?? ""}`);
+            },
+            signal: abort.signal,
+            session,
+            usage: new UsageLedger(),
+        };
+        reportWhatWasUsed = () => 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.log(null, logger.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.log(null, logger.levels.warn, `run-once execution for event record ${batchJobId}: heartbeat failed: ${error?.message ?? error}`));
+        }, HEARTBEAT_MS);
+        heartbeat.unref?.();
+        stopReporting = reportUsageWhileRunning(context, {
+            report: options.reportUsage,
+            intervalMs: options.usageReportIntervalMs,
+        });
+        logger.log(null, logger.levels.info, `run-once execution for event record ${batchJobId} (${req?.content_type ?? ""}) starting`);
+        const result = await runWithContext(context, () => entry(abort.signal));
+        logger.log(null, logger.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.log(null, logger.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);
+    }
+};
 /**
  * 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
@@ -309,6 +507,12 @@ const toErrorFrame = (error) => {
  *   serve(require("./src/main"));
  */
 export 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 (isRunOnceExecution()) {
+        void runOnce(main, options);
+        return new grpc.Server();
+    }
     installGlobals();
     const port = options.port ?? (Number(process.env.PORT) || 8080);
     const host = options.host ?? "0.0.0.0";
@@ -331,9 +535,13 @@ export 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 (!isAnonymousRun(req.event, request)) {
+                    session = await authenticate(request);
+                }
             }
             catch (error) {
                 const message = error?.message ?? "Unauthenticated";
@@ -358,6 +566,7 @@ export const serve = (main, options = {}) => {
                 onProgress,
                 signal: abort.signal,
                 session,
+                usage: new 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
@@ -388,8 +597,21 @@ export 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 = reportUsageWhileRunning(context, {
+                report: options.reportUsage,
+                intervalMs: options.usageReportIntervalMs,
+            });
+            const reportWhatWasUsed = async () => {
+                stopReporting();
+                await reportUsage(context, { report: options.reportUsage, last: true });
+            };
             try {
                 const result = await runWithContext(context, () => entry(abort.signal));
+                await reportWhatWasUsed();
                 if (!abort.signal.aborted) {
                     call.write({
                         result: { result_json: JSON.stringify(result ?? null) },
@@ -397,6 +619,7 @@ export const serve = (main, options = {}) => {
                 }
             }
             catch (error) {
+                await reportWhatWasUsed();
                 if (!abort.signal.aborted) {
                     logger.log(null, logger.levels.error, `agent Execute failed: ${error?.message ?? error}`);
                     call.write({ error: toErrorFrame(error) });

package/dist/esm/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/esm/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/esm/tavily.js

@@ -4,9 +4,8 @@ import constants from "./const.js";
 import errorHandlingHelper from "./errorHandling.js";
 import logger from "./logger.js";
 import { getAbortSignal } from "./runtimeContext.js";
+import { recordUsage } from "./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
@@ -121,19 +120,25 @@ const callTavily = async (endpoint, body, apiKey, timeoutSeconds) => {
         throw errorHandlingHelper.create(constants.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) {
+        recordUsage(TAVILY_MODEL, "credits", credits);
+    }
     if (!tracker)
         return;
     if (typeof tracker.cost !== "number")
@@ -141,13 +146,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;
     }
@@ -392,4 +390,5 @@ export default {
     assertTavilyUsable,
     buildTavilyTools,
     getTavilyOptions,
+    recordTavilyUsage,
 };

package/dist/esm/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/esm/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"}