@stackfactor/agent-utils 1.4.3 → 1.7.0

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.7.0",
   "description": "",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -14,7 +14,7 @@
   "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",
@@ -52,10 +52,11 @@
     "@grpc/grpc-js": "^1.14.4",
     "@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",
     "openai": "^6.32.0",
@@ -63,7 +64,11 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@langchain/core": "^1.2.9",
     "typescript": "^5.9.3"
+  },
+  "overrides": {
+    "mongodb": {
+      "gcp-metadata": ">=7.0.1"
+    }
   }
 }