@stackfactor/agent-utils 1.4.3 → 1.8.0

package/dist/cjs/stackfactorKnowledge.js

@@ -0,0 +1,274 @@
+"use strict";
+//
+// 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.
+//
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.referencesFor = exports.passagesForPrompt = exports.retrievePassages = exports.sourcesFromCoverage = exports.sourcesFromReferences = exports.DEFAULT_TOP_K = exports.QUERY_MAX_LENGTH = exports.SEARCH_DOCUMENT_IDS_MAX = exports.STACKFACTOR_REFERENCE = void 0;
+/** What a STACKFACTOR reference to a knowledge base document carries (backend-core REFERENCE). */
+exports.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. */
+exports.SEARCH_DOCUMENT_IDS_MAX = 500;
+/** How long a query may be (the backend's bound); longer ones are cut. */
+exports.QUERY_MAX_LENGTH = 4000;
+/** How many passages one search asks for when the caller does not say. */
+exports.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
+ */
+const sourcesFromReferences = (references) => {
+    const byBase = new Map();
+    for (const reference of Array.isArray(references) ? references : []) {
+        if (reference?.kind !== exports.STACKFACTOR_REFERENCE.KIND)
+            continue;
+        const target = reference.target ?? {};
+        const isDocumentTarget = target.elementType === exports.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],
+    }));
+};
+exports.sourcesFromReferences = sourcesFromReferences;
+/**
+ * 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
+ */
+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;
+};
+exports.sourcesFromCoverage = sourcesFromCoverage;
+/** 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 += exports.SEARCH_DOCUMENT_IDS_MAX) {
+        batches.push(source.documentIds.slice(at, at + exports.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 }`
+ */
+const retrievePassages = async (options) => {
+    const queries = [
+        ...new Set((Array.isArray(options.queries) ? options.queries : [])
+            .map((query) => text(query).slice(0, exports.QUERY_MAX_LENGTH))
+            .filter(Boolean)),
+    ];
+    const sources = Array.isArray(options.sources) ? options.sources : [];
+    const topK = options.topK ?? exports.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()] };
+};
+exports.retrievePassages = retrievePassages;
+/**
+ * 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
+ */
+const passagesForPrompt = (passages) => (Array.isArray(passages) ? passages : []).map((passage) => ({
+    document: passage.documentName,
+    section: passage.sectionTitle,
+    tag: passage.tag,
+    text: passage.text,
+}));
+exports.passagesForPrompt = passagesForPrompt;
+/**
+ * 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`
+ */
+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: exports.STACKFACTOR_REFERENCE.KIND,
+        knowledgeBase: {
+            chunkId: passage.chunkId,
+            documentId: passage.documentId,
+            knowledgeBaseId: passage.knowledgeBaseId,
+            sectionTitle: passage.sectionTitle,
+        },
+        origin: exports.STACKFACTOR_REFERENCE.ORIGIN,
+        target: {
+            elementId: passage.documentId,
+            elementType: exports.STACKFACTOR_REFERENCE.TARGET_ELEMENT_TYPE,
+            parentId: passage.knowledgeBaseId,
+        },
+        title: passage.documentName || passage.sectionTitle || "Knowledge base document",
+        visibility: exports.STACKFACTOR_REFERENCE.VISIBILITY,
+    }));
+};
+exports.referencesFor = referencesFor;
+exports.default = {
+    DEFAULT_TOP_K: exports.DEFAULT_TOP_K,
+    QUERY_MAX_LENGTH: exports.QUERY_MAX_LENGTH,
+    SEARCH_DOCUMENT_IDS_MAX: exports.SEARCH_DOCUMENT_IDS_MAX,
+    STACKFACTOR_REFERENCE: exports.STACKFACTOR_REFERENCE,
+    passagesForPrompt: exports.passagesForPrompt,
+    referencesFor: exports.referencesFor,
+    retrievePassages: exports.retrievePassages,
+    sourcesFromCoverage: exports.sourcesFromCoverage,
+    sourcesFromReferences: exports.sourcesFromReferences,
+};

package/dist/cjs/tavily.d.ts

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

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

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

package/dist/cjs/tavily.js

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

package/dist/cjs/usage.d.ts

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

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

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

package/dist/cjs/usage.js

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

package/dist/esm/errorHandling.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errorHandling.d.ts","sourceRoot":"","sources":["../../src/errorHandling.ts"],"names":[],"mappings":"AAGA,gEAAgE;AAChE,KAAK,QAAQ,GACT,OAAO,GACP,MAAM,GACN,MAAM,GACN,MAAM,GACN,SAAS,GACT,OAAO,GACP,OAAO,CAAC;AAEZ;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,GAAG,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA8GD;;;;;;;;;;;;GAYG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;gBAElB,MAAM,GAAE,WAAgB;IAUpC;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ;IAKrC;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW;IAIzC;;;;OAIG;IACH,OAAO,IAAI,WAAW,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAS1D,MAAM,IAAI,WAAW;IAIrB;;;;OAIG;IACH,WAAW,IAAI,KAAK;IAIpB;;;;;;;;OAQG;IACH,GAAG,CAAC,OAAO,GAAE,GAAU,EAAE,KAAK,GAAE,QAAkB,EAAE,OAAO,GAAE,GAAQ,GAAG,IAAI;CAU7E;;IAkBC;;;;;;;;;OASG;wBACiB,MAAM,gBAAgB,MAAM,YAAW,GAAG;;;;;;IAU9D,6EAA6E;mBApOpD,GAAG,KAAG,WAAW;IAsO1C,0EAA0E;;IAE1E,gFAAgF;oBA9BzE,OAAO,YACL,GAAG,YACH,GAAG,KACX,QAAQ;IA6BT,wDAAwD;uBArPhC,GAAG,KAAG,IAAI,IAAI,MAAM;IAuP5C,kCAAkC;;;AA7BpC,wBA+BE"}
+{"version":3,"file":"errorHandling.d.ts","sourceRoot":"","sources":["../../src/errorHandling.ts"],"names":[],"mappings":"AAGA,gEAAgE;AAChE,KAAK,QAAQ,GACT,OAAO,GACP,MAAM,GACN,MAAM,GACN,MAAM,GACN,SAAS,GACT,OAAO,GACP,OAAO,CAAC;AAEZ;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,GAAG,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAmHD;;;;;;;;;;;;GAYG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;gBAElB,MAAM,GAAE,WAAgB;IAUpC;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ;IAKrC;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW;IAIzC;;;;OAIG;IACH,OAAO,IAAI,WAAW,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAS1D,MAAM,IAAI,WAAW;IAIrB;;;;OAIG;IACH,WAAW,IAAI,KAAK;IAIpB;;;;;;;;OAQG;IACH,GAAG,CAAC,OAAO,GAAE,GAAU,EAAE,KAAK,GAAE,QAAkB,EAAE,OAAO,GAAE,GAAQ,GAAG,IAAI;CAU7E;;IAkBC;;;;;;;;;OASG;wBACiB,MAAM,gBAAgB,MAAM,YAAW,GAAG;;;;;;IAU9D,6EAA6E;mBAzOpD,GAAG,KAAG,WAAW;IA2O1C,0EAA0E;;IAE1E,gFAAgF;oBA9BzE,OAAO,YACL,GAAG,YACH,GAAG,KACX,QAAQ;IA6BT,wDAAwD;uBA1PhC,GAAG,KAAG,IAAI,IAAI,MAAM;IA4P5C,kCAAkC;;;AA7BpC,wBA+BE"}

package/dist/esm/errorHandling.js

@@ -81,11 +81,16 @@ const parseError = (error) => {
             // A JSON-encoded error string, or just a plain message.
             try {
                 const parsed = JSON.parse(error);
-                return {
-                    code: isHttpCode(parsed.code) ? parsed.code : undefined,
-                    message: parsed.message,
-                    integration: parsed.integration,
-                };
+                // Only an object is an encoded error; "404" or "true" also parse as
+                // JSON but are just the message text.
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                    return {
+                        code: isHttpCode(parsed.code) ? parsed.code : undefined,
+                        message: parsed.message,
+                        integration: parsed.integration,
+                    };
+                }
+                return { message: error };
             }
             catch {
                 return { message: error };

package/dist/esm/index.d.ts

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