@stackfactor/agent-utils 1.4.3 → 1.8.0

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"}

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/stackfactorKnowledge.d.ts

@@ -0,0 +1,182 @@
+/** What a STACKFACTOR reference to a knowledge base document carries (backend-core REFERENCE). */
+export declare const STACKFACTOR_REFERENCE: Readonly<{
+    KIND: "STACKFACTOR";
+    TARGET_ELEMENT_TYPE: "KNOWLEDGE_BASE_DOCUMENT";
+    ORIGIN: "KB_EXTRACTION";
+    VISIBILITY: "EDIT";
+}>;
+/** How many documents one search may be kept to (the backend's bound); more are split. */
+export declare const SEARCH_DOCUMENT_IDS_MAX = 500;
+/** How long a query may be (the backend's bound); longer ones are cut. */
+export declare const QUERY_MAX_LENGTH = 4000;
+/** How many passages one search asks for when the caller does not say. */
+export declare const DEFAULT_TOP_K = 8;
+/** A chunk as the platform's search answers it (client-api `RetrievedChunk`). */
+export interface KnowledgeChunk {
+    _id: string;
+    knowledgeBaseId?: string;
+    documentId: string;
+    documentName?: string | null;
+    sectionTitle?: string | null;
+    pageNumber?: number | null;
+    text?: string;
+    skills?: {
+        name: string | null;
+        microSkills?: string[];
+    }[];
+    score?: number | null;
+    [field: string]: unknown;
+}
+/** The platform's search, as client-api's `knowledgeBaseAgent.search` is called. */
+export type KnowledgeSearch = (knowledgeBaseId: string, query: string, options: {
+    topK?: number;
+    documentIds?: string[];
+}, token: string) => Promise<{
+    chunks: KnowledgeChunk[];
+}>;
+/** Where to search: a whole knowledge base, or only some of its documents. */
+export interface KnowledgeSource {
+    knowledgeBaseId: string;
+    /** Only these documents; omitted, the whole knowledge base. */
+    documentIds?: string[];
+}
+/** A passage handed to the model, tagged so it can cite it. */
+export interface GroundingPassage {
+    /** "k1", "k2"… in the order they rank. */
+    tag: string;
+    chunkId: string;
+    knowledgeBaseId: string;
+    documentId: string;
+    documentName: string | null;
+    sectionTitle: string | null;
+    pageNumber: number | null;
+    text: string;
+    /** The skills its passage teaches, as labelling named them. */
+    skills: {
+        name: string | null;
+        microSkills: string[];
+    }[];
+    score: number | null;
+}
+/** A knowledge base that could not be searched, and why. */
+export interface SkippedSource {
+    knowledgeBaseId: string;
+    /** The HTTP status, when the platform answered one. */
+    status: number | null;
+    /** True when the person may not read it (or it is gone): expected, not a fault. */
+    noAccess: boolean;
+    message: string;
+}
+/** A STACKFACTOR reference to the knowledge base document a passage came from. */
+export interface StackFactorReference {
+    kind: "STACKFACTOR";
+    title: string;
+    description: string | null;
+    target: {
+        elementType: "KNOWLEDGE_BASE_DOCUMENT";
+        elementId: string;
+        parentId: string;
+    };
+    knowledgeBase: {
+        knowledgeBaseId: string;
+        documentId: string;
+        chunkId: string;
+        sectionTitle: string | null;
+    };
+    origin: "KB_EXTRACTION";
+    visibility: "EDIT";
+}
+/**
+ * The knowledge bases, and the documents in them, that a list of references
+ * cites: its STACKFACTOR references to knowledge base documents, by their
+ * `knowledgeBase` ids, or by their `target` when only that is there. Any other
+ * reference is passed over. Each knowledge base once, its documents once each,
+ * in the order they first appear.
+ * @param references A skill's (or a microskill's) references
+ * @returns The sources to search
+ */
+export declare const sourcesFromReferences: (references: unknown) => KnowledgeSource[];
+/**
+ * The knowledge bases skill coverage found (client-api
+ * `knowledgeBase.getSkillCoverage`): every one the person can open that holds
+ * the skill, each searched whole.
+ * @param coverage The coverage answer, `{ knowledgeBases: [{ _id }] }`
+ * @returns The sources to search
+ */
+export declare const sourcesFromCoverage: (coverage: unknown) => KnowledgeSource[];
+/**
+ * Searches every source for every query, under the person's access, and hands
+ * back the passages found, best first, each once, tagged "k1", "k2"… for the
+ * model to cite. A source with documents is searched within them (in batches of
+ * SEARCH_DOCUMENT_IDS_MAX); one without, whole. A source the person may not
+ * read (401, 403, 404) is skipped: none of its passages are used and no more of
+ * its searches are made. A search that fails otherwise is reported and the
+ * passages its other searches found stand. Either way it is in `skipped`, once
+ * per knowledge base, and the passages of the others stand.
+ * @param options `sources`, `queries`, `search` (client-api
+ *   `knowledgeBaseAgent.search`), `token` (the run's AGENT token), `topK`
+ *   per search (default DEFAULT_TOP_K)
+ * @returns `{ passages, skipped }`
+ */
+export declare const retrievePassages: (options: {
+    sources: KnowledgeSource[];
+    queries: string[];
+    search: KnowledgeSearch;
+    token: string;
+    topK?: number;
+}) => Promise<{
+    passages: GroundingPassage[];
+    skipped: SkippedSource[];
+}>;
+/**
+ * The passages as a prompt shows them: tag, where each came from, and its text.
+ * @param passages From `retrievePassages`
+ * @returns `[{ tag, document, section, text }]`, for the model's input
+ */
+export declare const passagesForPrompt: (passages: GroundingPassage[]) => {
+    tag: string;
+    document: string | null;
+    section: string | null;
+    text: string;
+}[];
+/**
+ * STACKFACTOR references for passages: one per passage, in their order, with no
+ * cap. With `tags`, only the passages the model cited by tag (any tag it made
+ * up is passed over); without, every passage.
+ * @param passages From `retrievePassages`
+ * @param tags The tags the model cited ("k3", "K3" and " k3 " alike)
+ * @returns The references, ready for a skill's, a microskill's or a question's `references`
+ */
+export declare const referencesFor: (passages: GroundingPassage[], tags?: unknown[]) => StackFactorReference[];
+declare const _default: {
+    DEFAULT_TOP_K: number;
+    QUERY_MAX_LENGTH: number;
+    SEARCH_DOCUMENT_IDS_MAX: number;
+    STACKFACTOR_REFERENCE: Readonly<{
+        KIND: "STACKFACTOR";
+        TARGET_ELEMENT_TYPE: "KNOWLEDGE_BASE_DOCUMENT";
+        ORIGIN: "KB_EXTRACTION";
+        VISIBILITY: "EDIT";
+    }>;
+    passagesForPrompt: (passages: GroundingPassage[]) => {
+        tag: string;
+        document: string | null;
+        section: string | null;
+        text: string;
+    }[];
+    referencesFor: (passages: GroundingPassage[], tags?: unknown[]) => StackFactorReference[];
+    retrievePassages: (options: {
+        sources: KnowledgeSource[];
+        queries: string[];
+        search: KnowledgeSearch;
+        token: string;
+        topK?: number;
+    }) => Promise<{
+        passages: GroundingPassage[];
+        skipped: SkippedSource[];
+    }>;
+    sourcesFromCoverage: (coverage: unknown) => KnowledgeSource[];
+    sourcesFromReferences: (references: unknown) => KnowledgeSource[];
+};
+export default _default;
+//# sourceMappingURL=stackfactorKnowledge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stackfactorKnowledge.d.ts","sourceRoot":"","sources":["../../src/stackfactorKnowledge.ts"],"names":[],"mappings":"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"}