@broberg/ai-sdk 0.62.1 → 0.63.0

package/README.md

@@ -221,8 +221,15 @@ You don't have to wire a sink. If `UPMETRICS_API_KEY` is in the env, a bare
 call-sites passed no sink, leaving ~91% of Mistral spend invisible. No key in
 the env → no sink, no crash (ship-dark).
 
+**Every client needs a name (0.63+, F034.4).** `createAI()` throws at startup unless
+`UPMETRICS_AGENT_NAME` is set or you pass `agentName` — even when no key is present, so
+your tests catch it before production does. Owner order 2026-10-15: «Ingen må være
+anonyme» — measured over 30 days, 8 repos had sent their spend as `unknown`. Not needed
+with an explicit `costSink` or `costSink: null`.
+
 ```ts
-createAI();                      // key in env → tracked; no key → nothing happens
+createAI({ agentName: "my-app" }); // key in env → tracked; no key → nothing happens
+createAI();                      // same, if UPMETRICS_AGENT_NAME is set — else throws
 createAI({ costSink: mySink });  // explicit sink wins
 createAI({ costSink: null });    // explicit OPT-OUT — see below
 ```
@@ -230,7 +237,7 @@ createAI({ costSink: null });    // explicit OPT-OUT — see below
 | Env var | Effect |
 |---|---|
 | `UPMETRICS_API_KEY` | **The only switch.** Present → tracking on. |
-| `UPMETRICS_AGENT_NAME` | Row label. Set it — the fallback is `npm_package_name`, which is empty for a process not started via an npm/bun script (a `node dist/…` or Docker service logs as `unknown`). |
+| `UPMETRICS_AGENT_NAME` | Row label, **required** (or `agentName`) since 0.63.0 — set it in production AND in your test env. Up to 0.62 the fallback was `npm_package_name`, empty outside an npm/bun script, so `node dist/…` and Docker services logged as `unknown`. |
 | `UPMETRICS_BASE_URL` | Ingest host. Defaults to `https://upmetrics.org`. |
 | `UPMETRICS_COMPLIANCE` | `1` sets compliance mode. `Usage` carries no prompt/response text either way. |
 

package/dist/index.d.ts

@@ -1864,6 +1864,9 @@ declare const aiConfigSchema: z.ZodObject<{
      *  to opt OUT explicitly — for a consumer that already reports its own costs
      *  and would otherwise be counted twice (F034.3). An object is used as-is. */
     costSink: z.ZodOptional<z.ZodNullable<z.ZodType<CostSink, z.ZodTypeDef, CostSink>>>;
+    /** F034.4 — who is calling, as Upmetrics groups it (e.g. "cms"). Required when
+     *  `costSink` is omitted, unless UPMETRICS_AGENT_NAME is set. */
+    agentName: z.ZodOptional<z.ZodString>;
     budget: z.ZodOptional<z.ZodObject<{
         perCallUsd: z.ZodOptional<z.ZodNumber>;
         rollingUsd: z.ZodOptional<z.ZodNumber>;
@@ -1896,6 +1899,7 @@ declare const aiConfigSchema: z.ZodObject<{
         transport: "http" | "subprocess";
     }>> | undefined;
     providers?: Record<string, ProviderAdapter> | undefined;
+    agentName?: string | undefined;
     budget?: {
         perCallUsd?: number | undefined;
         rollingUsd?: number | undefined;
@@ -1916,6 +1920,7 @@ declare const aiConfigSchema: z.ZodObject<{
         transport: "http" | "subprocess";
     }>> | undefined;
     providers?: Record<string, ProviderAdapter> | undefined;
+    agentName?: string | undefined;
     budget?: {
         perCallUsd?: number | undefined;
         rollingUsd?: number | undefined;
@@ -2334,8 +2339,8 @@ declare const falStubAdapter: ProviderAdapter;
  *  wires the live adapters. */
 declare const stubProviders: Record<string, ProviderAdapter>;
 
-declare const VERSION: "0.62.1";
-declare const SDK_TAG: "@broberg/ai-sdk@0.62.1";
+declare const VERSION: "0.63.0";
+declare const SDK_TAG: "@broberg/ai-sdk@0.63.0";
 
 /** Built-in defaults. Every entry is overridable via AiConfig.defaults or a
  *  per-call override.

package/dist/index.js

@@ -340,11 +340,13 @@ async function search(req, opts = {}) {
   const nowMs = () => (opts.now ?? (() => /* @__PURE__ */ new Date()))().getTime();
   let lastErr;
   for (const [i, provider] of chain.entries()) {
-    const coolKey = cooldownKey(provider, opts);
-    if (i < chain.length - 1 && (coolingUntil.get(coolKey) ?? 0) > nowMs()) continue;
     const key = searchCacheKey(provider, req);
     const hit = cache?.get(key);
     if (hit) return { items: hit.items, meta: { ...hit.meta, cached: true, costUsd: 0, latencyMs: 0 } };
+    const coolKey = cooldownKey(provider, opts);
+    const until = coolingUntil.get(coolKey);
+    if (until !== void 0 && until <= nowMs()) coolingUntil.delete(coolKey);
+    else if (until !== void 0 && i < chain.length - 1) continue;
     const price = SEARCH_PRICE_USD[provider];
     const cap = opts.dailyCapUsd ?? Infinity;
     if (!await capStore.reserve(capKey, price, cap)) {
@@ -3908,6 +3910,9 @@ var aiConfigSchema = z.object({
    *  to opt OUT explicitly — for a consumer that already reports its own costs
    *  and would otherwise be counted twice (F034.3). An object is used as-is. */
   costSink: z.custom().nullable().optional(),
+  /** F034.4 — who is calling, as Upmetrics groups it (e.g. "cms"). Required when
+   *  `costSink` is omitted, unless UPMETRICS_AGENT_NAME is set. */
+  agentName: z.string().optional(),
   budget: budgetSchema.optional(),
   availability: availabilitySchema.optional()
 });
@@ -3916,8 +3921,8 @@ var aiConfigSchema = z.object({
 import { randomUUID } from "crypto";
 
 // src/version.ts
-var VERSION = "0.62.1";
-var SDK_TAG = "@broberg/ai-sdk@0.62.1";
+var VERSION = "0.63.0";
+var SDK_TAG = "@broberg/ai-sdk@0.63.0";
 
 // src/cost/sinks/upmetrics.ts
 function isRetryableStatus(status) {
@@ -3927,6 +3932,7 @@ var MAX_QUEUE = 30;
 var MAX_ATTEMPTS = 5;
 var MAX_BACKOFF_MS = 3e4;
 function upmetricsSink(config) {
+  if (!config.agentName?.trim()) throw new Error("upmetricsSink(): agentName is required (e.g. your repo name) \u2014 anonymous cost rows are not allowed");
   const doFetch = config.fetch ?? fetch;
   const url = `${config.baseUrl.replace(/\/$/, "")}/api/agent`;
   const retry = config.retry ?? true;
@@ -4256,21 +4262,28 @@ var ROUTED_SPECS = [
   DEFAULT_BATCH_SPEC,
   DEFAULT_TRANSCRIBE_SPEC
 ];
-function defaultCostSink() {
+function defaultCostSink(agentName) {
   const apiKey = process.env.UPMETRICS_API_KEY;
   if (!apiKey) return void 0;
   return upmetricsSink({
     baseUrl: process.env.UPMETRICS_BASE_URL ?? "https://upmetrics.org",
     apiKey,
-    agentName: process.env.UPMETRICS_AGENT_NAME ?? process.env.npm_package_name ?? "unknown",
+    agentName,
     complianceMode: process.env.UPMETRICS_COMPLIANCE === "1"
   });
 }
+function requireAgentName(configured) {
+  const name = (configured ?? process.env.UPMETRICS_AGENT_NAME ?? "").trim();
+  if (name) return name;
+  throw new Error(
+    'createAI(): no agent name \u2014 every AI call must say who made it (owner order 2026-10-15). Set UPMETRICS_AGENT_NAME=<your repo> (production AND test env), or pass createAI({ agentName: "<your repo>" }). Not needed with an explicit costSink, or costSink: null.'
+  );
+}
 function createAI(config = {}) {
   const cfg = aiConfigSchema.parse(config);
   if (cfg.byok) assertByokProviders(cfg.providers);
   const providers = cfg.providers ?? defaultProviders;
-  const costSink = cfg.costSink === void 0 ? defaultCostSink() : cfg.costSink ?? void 0;
+  const costSink = cfg.costSink === void 0 ? defaultCostSink(requireAgentName(cfg.agentName)) : cfg.costSink ?? void 0;
   const budget = cfg.budget ? new BudgetGuard(cfg.budget) : void 0;
   const estTokens = (s) => Math.ceil(s.length / 4);
   async function preflight(spec, estInTokens, estOutTokens) {