@stackfactor/agent-utils 1.4.3 → 1.8.0

package/dist/esm/stackfactorKnowledge.js

@@ -0,0 +1,266 @@
+//
+// StackFactor knowledge — grounding generated content in the knowledge bases
+//
+// A generation agent grounded in StackFactor (the Additional Information data
+// source "StackFactor", `dataSource: "RAG"`) writes from knowledge-base
+// passages instead of a web search, and cites every passage it used as a
+// STACKFACTOR reference. A later agent generating for the same skill (its
+// assessments, its learning content) reads those references and searches the
+// documents they cite. Designed with Candin, 2026-10-08:
+//
+//   - which knowledge bases: every one the person can open that holds the
+//     skill (skill coverage), never a fixed number of them;
+//   - which references: one per passage used, with no cap per document or per
+//     microskill;
+//   - access: the platform's search judges the person the run acts for, so a
+//     run reads only what that person may open. A knowledge base the person
+//     cannot read is skipped and reported, never an error: the agent
+//     generates without it.
+//
+// A reference points at the content and never copies it: the passage is
+// searched again, under the reader's own access, whenever it is used. It is
+// EDIT-only (`visibility: "EDIT"`): the platform strips it from what is
+// published, so a knowledge base's titles never reach a learner; agents read
+// it from the draft.
+//
+// The search itself is the caller's (`search`: client-api
+// `knowledgeBaseAgent.search`, 1.11 or later for `documentIds`), so this
+// module needs no particular client-api.
+//
+/** What a STACKFACTOR reference to a knowledge base document carries (backend-core REFERENCE). */
+export const STACKFACTOR_REFERENCE = Object.freeze({
+    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 const SEARCH_DOCUMENT_IDS_MAX = 500;
+/** How long a query may be (the backend's bound); longer ones are cut. */
+export const QUERY_MAX_LENGTH = 4000;
+/** How many passages one search asks for when the caller does not say. */
+export const DEFAULT_TOP_K = 8;
+/** How many searches run at once. */
+const CONCURRENCY = 4;
+/** Statuses that mean the person may not read the knowledge base, or it is gone. */
+const NO_ACCESS = new Set([401, 403, 404]);
+const text = (value) => (typeof value === "string" ? value.trim() : "");
+const id = (value) => typeof value === "string" ? value.trim() : value != null && typeof value === "object" ? String(value) : "";
+/**
+ * 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 const sourcesFromReferences = (references) => {
+    const byBase = new Map();
+    for (const reference of Array.isArray(references) ? references : []) {
+        if (reference?.kind !== STACKFACTOR_REFERENCE.KIND)
+            continue;
+        const target = reference.target ?? {};
+        const isDocumentTarget = target.elementType === STACKFACTOR_REFERENCE.TARGET_ELEMENT_TYPE;
+        const knowledgeBaseId = id(reference.knowledgeBase?.knowledgeBaseId) || (isDocumentTarget ? id(target.parentId) : "");
+        const documentId = id(reference.knowledgeBase?.documentId) || (isDocumentTarget ? id(target.elementId) : "");
+        if (!knowledgeBaseId || !documentId)
+            continue;
+        const documents = byBase.get(knowledgeBaseId) ?? new Set();
+        documents.add(documentId);
+        byBase.set(knowledgeBaseId, documents);
+    }
+    return [...byBase.entries()].map(([knowledgeBaseId, documents]) => ({
+        knowledgeBaseId,
+        documentIds: [...documents],
+    }));
+};
+/**
+ * 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 const sourcesFromCoverage = (coverage) => {
+    const bases = coverage?.knowledgeBases;
+    const seen = new Set();
+    const sources = [];
+    for (const base of Array.isArray(bases) ? bases : []) {
+        const knowledgeBaseId = id(base?._id);
+        if (!knowledgeBaseId || seen.has(knowledgeBaseId))
+            continue;
+        seen.add(knowledgeBaseId);
+        sources.push({ knowledgeBaseId });
+    }
+    return sources;
+};
+/** The documents of a source in batches the backend accepts; one batch of none for a whole knowledge base. */
+const batchesOf = (source) => {
+    if (!Array.isArray(source.documentIds))
+        return [undefined];
+    const batches = [];
+    for (let at = 0; at < source.documentIds.length; at += SEARCH_DOCUMENT_IDS_MAX) {
+        batches.push(source.documentIds.slice(at, at + SEARCH_DOCUMENT_IDS_MAX));
+    }
+    return batches;
+};
+/** Runs `worker` over `items`, at most `limit` at a time. */
+const inPool = async (items, limit, worker) => {
+    let next = 0;
+    const run = async () => {
+        while (next < items.length) {
+            const index = next++;
+            await worker(items[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, run));
+};
+/** The status of a failed platform call, from an axios error or one shaped like it. */
+const statusOf = (error) => {
+    const status = error?.response?.status ?? error?.status;
+    return typeof status === "number" ? status : null;
+};
+/**
+ * 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 const retrievePassages = async (options) => {
+    const queries = [
+        ...new Set((Array.isArray(options.queries) ? options.queries : [])
+            .map((query) => text(query).slice(0, QUERY_MAX_LENGTH))
+            .filter(Boolean)),
+    ];
+    const sources = Array.isArray(options.sources) ? options.sources : [];
+    const topK = options.topK ?? DEFAULT_TOP_K;
+    const searches = [];
+    for (const source of sources) {
+        for (const documentIds of batchesOf(source)) {
+            if (documentIds && documentIds.length === 0)
+                continue;
+            for (const query of queries) {
+                searches.push({ source, query, documentIds, order: searches.length });
+            }
+        }
+    }
+    const found = new Map();
+    const skipped = new Map();
+    await inPool(searches, CONCURRENCY, async ({ source, query, documentIds, order }) => {
+        if (skipped.get(source.knowledgeBaseId)?.noAccess)
+            return;
+        try {
+            const answer = await options.search(source.knowledgeBaseId, query, documentIds ? { topK, documentIds } : { topK }, options.token);
+            (Array.isArray(answer?.chunks) ? answer.chunks : []).forEach((chunk, rank) => {
+                const chunkId = id(chunk?._id);
+                if (!chunkId || !id(chunk?.documentId))
+                    return;
+                const known = found.get(chunkId);
+                const better = !known || (chunk.score ?? 0) > (known.chunk.score ?? 0);
+                // Ties keep the first search's rank, so the order is the searches' own.
+                found.set(chunkId, {
+                    chunk: better ? chunk : known.chunk,
+                    knowledgeBaseId: source.knowledgeBaseId,
+                    order: known ? Math.min(known.order, order * 1000 + rank) : order * 1000 + rank,
+                });
+            });
+        }
+        catch (error) {
+            const status = statusOf(error);
+            const noAccess = status !== null && NO_ACCESS.has(status);
+            // A refusal outranks a failure reported before it.
+            if (skipped.has(source.knowledgeBaseId) && !noAccess)
+                return;
+            skipped.set(source.knowledgeBaseId, {
+                knowledgeBaseId: source.knowledgeBaseId,
+                message: typeof error?.message === "string" ? error.message : String(error),
+                noAccess,
+                status,
+            });
+        }
+    });
+    const passages = [...found.entries()]
+        .filter(([, entry]) => !skipped.get(entry.knowledgeBaseId)?.noAccess)
+        .sort(([, a], [, b]) => (b.chunk.score ?? 0) - (a.chunk.score ?? 0) || a.order - b.order)
+        .map(([chunkId, { chunk, knowledgeBaseId }], index) => ({
+        chunkId,
+        documentId: id(chunk.documentId),
+        documentName: text(chunk.documentName) || null,
+        knowledgeBaseId: id(chunk.knowledgeBaseId) || knowledgeBaseId,
+        pageNumber: typeof chunk.pageNumber === "number" ? chunk.pageNumber : null,
+        score: typeof chunk.score === "number" ? chunk.score : null,
+        sectionTitle: text(chunk.sectionTitle) || null,
+        skills: (Array.isArray(chunk.skills) ? chunk.skills : []).map((skill) => ({
+            microSkills: (Array.isArray(skill?.microSkills) ? skill.microSkills : []).filter((name) => typeof name === "string"),
+            name: typeof skill?.name === "string" ? skill.name : null,
+        })),
+        tag: `k${index + 1}`,
+        text: typeof chunk.text === "string" ? chunk.text : "",
+    }));
+    return { passages, skipped: [...skipped.values()] };
+};
+/**
+ * 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 const passagesForPrompt = (passages) => (Array.isArray(passages) ? passages : []).map((passage) => ({
+    document: passage.documentName,
+    section: passage.sectionTitle,
+    tag: passage.tag,
+    text: passage.text,
+}));
+/**
+ * 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 const referencesFor = (passages, tags) => {
+    const list = Array.isArray(passages) ? passages : [];
+    const cited = Array.isArray(tags)
+        ? new Set(tags.map((tag) => text(tag).toLowerCase()).filter(Boolean))
+        : null;
+    return list
+        .filter((passage) => !cited || cited.has(passage.tag.toLowerCase()))
+        .map((passage) => ({
+        description: passage.sectionTitle,
+        kind: STACKFACTOR_REFERENCE.KIND,
+        knowledgeBase: {
+            chunkId: passage.chunkId,
+            documentId: passage.documentId,
+            knowledgeBaseId: passage.knowledgeBaseId,
+            sectionTitle: passage.sectionTitle,
+        },
+        origin: STACKFACTOR_REFERENCE.ORIGIN,
+        target: {
+            elementId: passage.documentId,
+            elementType: STACKFACTOR_REFERENCE.TARGET_ELEMENT_TYPE,
+            parentId: passage.knowledgeBaseId,
+        },
+        title: passage.documentName || passage.sectionTitle || "Knowledge base document",
+        visibility: STACKFACTOR_REFERENCE.VISIBILITY,
+    }));
+};
+export default {
+    DEFAULT_TOP_K,
+    QUERY_MAX_LENGTH,
+    SEARCH_DOCUMENT_IDS_MAX,
+    STACKFACTOR_REFERENCE,
+    passagesForPrompt,
+    referencesFor,
+    retrievePassages,
+    sourcesFromCoverage,
+    sourcesFromReferences,
+};

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

package/dist/esm/usage.js

@@ -0,0 +1,150 @@
+import { randomUUID } from "node:crypto";
+import { integration as clientIntegration } from "@stackfactor/client-api";
+import logger from "./logger.js";
+import { getContext } 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 const 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. */
+export const 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.
+ */
+export 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 ||
+            !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;
+    }
+}
+/**
+ * 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 const recordUsage = (model, unit, amount) => {
+    getContext()?.usage?.add(model, unit, amount);
+};
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const defaultReport = (usage, reportId, token) => clientIntegration.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 = 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
+ */
+export 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.log(null, logger.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.log(null, logger.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.log(null, logger.levels.warn, `usage could not be reported, it is kept for the next report: ${error?.message ?? error}`);
+            }
+        }
+    }
+};
+/**
+ * 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 const reportUsageWhileRunning = (context, options = {}) => {
+    const timer = setInterval(() => {
+        void reportUsage(context, { report: options.report, retryBaseMs: options.retryBaseMs });
+    }, options.intervalMs ?? USAGE_REPORT_INTERVAL_MS);
+    timer.unref?.();
+    return () => clearInterval(timer);
+};

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.4.3",
+  "version": "1.8.0",
   "description": "",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -14,14 +14,15 @@
   "scripts": {
     "clean": "rm -rf dist",
     "build": "npm run clean && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json && echo '{\"type\":\"module\"}' > dist/esm/package.json",
-    "test": "npm run build && node --test \"test/**/*.test.js\"",
+    "test": "npm run build && node --test test/*.test.js",
     "work:start": "bash scripts/work-start.sh",
     "work:commit": "bash scripts/work-commit.sh",
     "work:release": "bash scripts/release.sh",
     "release": "bash scripts/release.sh",
     "release:fanout": "bash scripts/release-fanout.sh",
-    "ar-auth": "npm config set @stackfactor:registry https://us-central1-npm.pkg.dev/virtual-development-team/sf-devenv-npm-private/; TOKEN=$(gcloud auth print-access-token 2>/dev/null || curl -sfH 'Metadata-Flavor: Google' http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token | sed -n 's/.*\"access_token\":\"\\([^\"]*\\)\".*/\\1/p'); test -n \"$TOKEN\" || { echo 'ar-auth: no credential — run: gcloud auth login' >&2; exit 1; }; npm config set //us-central1-npm.pkg.dev/virtual-development-team/sf-devenv-npm-private/:_authToken \"$TOKEN\"; npm config set //us-central1-npm.pkg.dev/virtual-development-team/:_authToken \"$TOKEN\"; echo 'ar-auth: Artifact Registry scope + token configured'",
-    "reinstall": "npm run ar-auth && npm ci"
+    "ar-auth": "npm config set @stackfactor:registry https://us-central1-npm.pkg.dev/virtual-development-team/sf-devenv-npm-private/; TOKEN=$(gcloud auth print-access-token 2>/dev/null || curl -sfH 'Metadata-Flavor: Google' http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token | sed -n 's/.*\"access_token\":\"\\([^\"]*\\)\".*/\\1/p'); test -n \"$TOKEN\" || { echo 'ar-auth: no credential \u2014 run: gcloud auth login' >&2; exit 1; }; npm config set //us-central1-npm.pkg.dev/virtual-development-team/sf-devenv-npm-private/:_authToken \"$TOKEN\"; npm config set //us-central1-npm.pkg.dev/virtual-development-team/:_authToken \"$TOKEN\"; echo 'ar-auth: Artifact Registry scope + token configured'",
+    "reinstall": "npm run ar-auth && npm ci",
+    "test:coverage": "npm run build && node --experimental-test-coverage --test --test-reporter=tap test/*.test.js"
   },
   "repository": {
     "type": "git",
@@ -49,21 +50,26 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.74.0",
     "@google/genai": "^1.46.0",
-    "@grpc/grpc-js": "^1.14.4",
+    "@grpc/grpc-js": "^1.14.5",
     "@grpc/proto-loader": "^0.7.15",
     "@langchain/anthropic": "^1.3.25",
+    "@langchain/core": "^1.2.9",
     "@langchain/google-genai": "^2.1.26",
     "@langchain/openai": "^1.3.0",
     "@opentelemetry/api": "^1.9.0",
-    "@stackfactor/client-api": "^1.2.1",
+    "@stackfactor/client-api": "^1.6.0",
     "langchain": "^1.2.35",
-    "mongoose": "^9.3.1",
+    "mongoose": "^9.10.4",
     "openai": "^6.32.0",
     "winston": "^3.19.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@langchain/core": "^1.2.9",
     "typescript": "^5.9.3"
+  },
+  "overrides": {
+    "mongodb": {
+      "gcp-metadata": ">=7.0.1"
+    }
   }
 }