@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/engine/agents/usage.mjs

@@ -0,0 +1,95 @@
+/**
+ * lib/engine/agents/usage.mjs — a run's usage and cost across its subagents (pure).
+ *
+ * Every child run leaves a usage record: the tier that served it, its
+ * normalised usage (design §4.5), its gateway cost in integer micro-USD and its
+ * request ids. The parent's result reports:
+ *
+ *   usage / cohort.usage          parent + every child (what the run consumed)
+ *   total_cost_usd / costMicros   parent + every child, exact or null: one
+ *                                 request without a settled cost nulls the sum,
+ *                                 exactly as a single run does
+ *   cohort.requestIds             parent's, then each child's, in finish order
+ *   modelUsage                    per tier, in the claude result's field names
+ *   cohort.modelUsage             {byTier:{[tier]:{usage, costMicros, requests}}, total:{usage, costMicros}}
+ *
+ * @module lib/engine/agents/usage
+ */
+
+import { addUsage, emptyUsage, toResultUsage } from "../wire/usage.mjs";
+
+/**
+ * @typedef {Object} UsageRecord
+ * @property {string} tier
+ * @property {import('../wire/usage.mjs').NormalisedUsage} usage
+ * @property {string|null} costMicros   null = unknown (may have been billed with no figure)
+ * @property {string[]} requestIds
+ */
+
+/**
+ * A loop outcome as a usage record. A run with no completed turn and an exact
+ * (empty) cost was never billed: its cost is "0", not unknown.
+ * @param {any} outcome  runLoop's result
+ * @param {string} fallbackTier
+ * @returns {UsageRecord}
+ */
+export function recordFromOutcome(outcome, fallbackTier) {
+  const exact = outcome.costComplete !== false;
+  return {
+    tier: outcome.modelTier || fallbackTier,
+    usage: outcome.usage ?? emptyUsage("estimated"),
+    costMicros: outcome.costMicros != null ? outcome.costMicros : exact ? "0" : null,
+    requestIds: [...(outcome.requestIds ?? [])],
+  };
+}
+
+/** @param {Array<string|null>} parts */
+function sumMicros(parts) {
+  let total = 0n;
+  for (const p of parts) {
+    if (p == null) return null;
+    total += BigInt(p);
+  }
+  return total.toString();
+}
+
+/**
+ * Combine the parent's record with its children's.
+ * @param {UsageRecord} parent @param {UsageRecord[]} children
+ */
+export function aggregateUsage(parent, children) {
+  const all = [parent, ...children];
+  /** @type {Record<string, {usage:any, costParts:Array<string|null>, requests:number}>} */
+  const tiers = {};
+  for (const r of all) {
+    const t = (tiers[r.tier] ??= { usage: emptyUsage("provider"), costParts: [], requests: 0 });
+    t.usage = addUsage(t.usage, r.usage);
+    t.costParts.push(r.costMicros);
+    t.requests += r.requestIds.length;
+  }
+  const usage = all.reduce((u, r) => addUsage(u, r.usage), emptyUsage("provider"));
+  const costMicros = sumMicros(all.map((r) => r.costMicros));
+  /** @type {Record<string, any>} */
+  const byTier = {};
+  /** @type {Record<string, any>} */
+  const modelUsage = {};
+  for (const [tier, t] of Object.entries(tiers)) {
+    const micros = sumMicros(t.costParts);
+    byTier[tier] = { usage: t.usage, costMicros: micros, requests: t.requests };
+    const ru = toResultUsage(t.usage);
+    modelUsage[tier] = {
+      inputTokens: ru.input_tokens,
+      outputTokens: ru.output_tokens,
+      cacheReadInputTokens: ru.cache_read_input_tokens,
+      cacheCreationInputTokens: ru.cache_creation_input_tokens,
+      costUSD: micros == null ? null : Number(BigInt(micros)) / 1e6,
+    };
+  }
+  return {
+    usage,
+    costMicros,
+    requestIds: all.flatMap((r) => r.requestIds),
+    modelUsage,
+    cohortModelUsage: { byTier, total: { usage, costMicros } },
+  };
+}

package/lib/engine/auth-status.mjs

@@ -0,0 +1,139 @@
+/**
+ * lib/engine/auth-status.mjs — `cohort auth status [--json] [--base-url <url>]`:
+ * does this process's gateway credential work? (conformance rows 1 and 25)
+ *
+ * Resolves the credential the way a run does (wire/token-provider.mjs: the
+ * token helper, else COHORT_LLM_TOKEN) and makes the cheapest authenticated
+ * call the gateway has, `GET /cohort/v1/quota` — no model request, no spend.
+ * A 401 on a helper credential re-runs the helper once, as the wire does.
+ *
+ *   stdout (--json)  {"ok":true,"baseUrl":"…","principal":{…}|null}
+ *                    {"ok":false,"baseUrl":"…"|null,"principal":null,"error":{"code","message"}}
+ *   exit             0 ok · 1 not authenticated or unreachable · 2 bad arguments
+ *
+ * The token itself is never printed.
+ *
+ * @module lib/engine/auth-status
+ */
+
+import { createTokenProvider } from "./wire/token-provider.mjs";
+import { tokenFailureError } from "./wire/errors.mjs";
+
+export const AUTH_STATUS_TIMEOUT_MS = 10_000;
+
+const USAGE = `Usage: cohort auth status [--json] [--base-url <url>]
+
+Checks the gateway credential (COHORT_LLM_TOKEN_HELPER or COHORT_LLM_TOKEN)
+against GET /cohort/v1/quota. Exit 0 when it is accepted, 1 otherwise.
+`;
+
+/**
+ * @param {string[]} argv  the words after `auth`
+ * @returns {{ok:true, opts:{json:boolean, baseUrl:string|null, help:boolean}}|{ok:false, error:string}}
+ */
+export function parseAuthStatusArgs(argv) {
+  const opts = { json: false, baseUrl: /** @type {string|null} */ (null), help: false };
+  if (argv[0] === "-h" || argv[0] === "--help") return { ok: true, opts: { ...opts, help: true } };
+  if (argv[0] !== "status") return { ok: false, error: `unknown auth subcommand ${JSON.stringify(argv[0] ?? "")}: expected "auth status"` };
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") opts.json = true;
+    else if (a === "-h" || a === "--help") opts.help = true;
+    else if (a === "--base-url") {
+      const v = argv[++i];
+      if (!v) return { ok: false, error: "--base-url needs a value" };
+      opts.baseUrl = v;
+    } else if (a.startsWith("--base-url=")) opts.baseUrl = a.slice("--base-url=".length);
+    else return { ok: false, error: `unknown flag for auth status: ${a}` };
+  }
+  return { ok: true, opts };
+}
+
+/**
+ * The status for a quota answer. Pure.
+ * @param {{baseUrl:string, status:number, body:any}} p
+ */
+export function authStatusFromQuota({ baseUrl, status, body }) {
+  if (status >= 200 && status < 300 && body && typeof body === "object") {
+    return { ok: true, baseUrl, principal: body.principal && typeof body.principal === "object" ? body.principal : null };
+  }
+  const e = body && typeof body === "object" && body.error && typeof body.error === "object" ? body.error : null;
+  const code = typeof e?.code === "string" && e.code ? e.code : status === 401 ? "cohort_invalid_token" : status === 403 ? "cohort_forbidden" : `http_${status}`;
+  const message = typeof e?.message === "string" && e.message ? e.message : `the gateway refused the credential (HTTP ${status})`;
+  return { ok: false, baseUrl, principal: null, error: { code, message } };
+}
+
+/**
+ * @param {string[]} argv  the words after `auth`
+ * @param {{env?:Record<string,string|undefined>, stdout?:{write:(s:string)=>unknown}, stderr?:{write:(s:string)=>unknown}, fetchImpl?:typeof fetch, now?:()=>number, runTokenHelper?:(command:string, o:{env:Record<string,string|undefined>})=>Promise<string>, timeoutMs?:number}} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runAuthStatus(argv, deps = {}) {
+  const env = deps.env ?? process.env;
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+  const parsed = parseAuthStatusArgs(argv);
+  const wantsJson = argv.includes("--json");
+  if (!parsed.ok) {
+    if (wantsJson) stdout.write(`${JSON.stringify({ ok: false, baseUrl: null, principal: null, error: { code: "invalid_arguments", message: parsed.error } })}\n`);
+    else stderr.write(`cohort auth: ${parsed.error}\n\n${USAGE}`);
+    return 2;
+  }
+  const o = parsed.opts;
+  if (o.help) {
+    stdout.write(USAGE);
+    return 0;
+  }
+
+  /** @param {{ok:boolean, baseUrl:string|null, principal:any, error?:{code:string, message:string}}} r */
+  const emit = (r) => {
+    if (o.json) stdout.write(`${JSON.stringify(r)}\n`);
+    else if (r.ok) stdout.write(`Authenticated to ${r.baseUrl}${r.principal ? ` as ${JSON.stringify(r.principal)}` : ""}\n`);
+    else stdout.write(`Not authenticated${r.baseUrl ? ` to ${r.baseUrl}` : ""}: ${r.error?.code}: ${r.error?.message}\n`);
+    return r.ok ? 0 : 1;
+  };
+  const fail = (/** @type {string|null} */ baseUrl, /** @type string */ code, /** @type string */ message) => emit({ ok: false, baseUrl, principal: null, error: { code, message } });
+
+  const baseUrl = String(o.baseUrl ?? env.COHORT_LLM_BASE_URL ?? "").trim().replace(/\/+$/, "");
+  if (!baseUrl) return fail(null, "missing_base_url", "no gateway URL: pass --base-url or set COHORT_LLM_BASE_URL");
+  const provider = createTokenProvider({ env, ...(deps.now ? { now: deps.now } : {}), ...(deps.runTokenHelper ? { runHelper: deps.runTokenHelper } : {}) });
+  if (!provider.ok) return fail(baseUrl, provider.error.code, provider.error.message);
+  const refreshable = typeof provider.token === "function";
+
+  /** @type {string|undefined} */
+  let rejected;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    let token;
+    try {
+      token = typeof provider.token === "function" ? await provider.token(attempt > 0 ? { refresh: true, rejected } : { refresh: false }) : provider.token;
+    } catch (e) {
+      // A down token endpoint is cohort_unavailable (an outage the probe reports
+      // as unknown), not token_unavailable (a credential answer) — CF-143.
+      const te = tokenFailureError(e);
+      return fail(baseUrl, te.code, te.message);
+    }
+    let res;
+    try {
+      res = await fetchImpl(`${baseUrl}/cohort/v1/quota`, {
+        method: "GET",
+        headers: { authorization: `Bearer ${token}`, accept: "application/json" },
+        signal: AbortSignal.timeout(deps.timeoutMs ?? AUTH_STATUS_TIMEOUT_MS),
+      });
+    } catch (e) {
+      return fail(baseUrl, "cohort_unavailable", `the gateway did not answer: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    let body = null;
+    try {
+      body = await res.json();
+    } catch {
+      body = null;
+    }
+    if (res.status === 401 && refreshable && attempt === 0) {
+      rejected = token;
+      continue;
+    }
+    return emit(authStatusFromQuota({ baseUrl, status: res.status, body }));
+  }
+  return fail(baseUrl, "cohort_invalid_token", "unreachable");
+}

package/lib/engine/budget.mjs

@@ -0,0 +1,194 @@
+/**
+ * lib/engine/budget.mjs — the per-run spend cap behind `--max-budget-usd` (W4-E1, conformance row 24).
+ *
+ * One meter per `cohort run`, shared by the run's own loop and every subagent
+ * and workflow child it starts, so the cap is on what the whole run spends:
+ *
+ *   record(res)   folds one gateway request's cost in: the `x-cohort-cost-micros`
+ *                 header or the SSE cohort frame, which the wires normalise to
+ *                 `res.cohort.costMicros` (WebSearch reports the same shape).
+ *   exhausted()   spent >= cap. Every loop asks before each model call (and
+ *                 before a compaction summary); once true no further model call
+ *                 is made — the current batch of tool results is finished first.
+ *
+ * The figure is the gateway's, never a local estimate. A request that failed
+ * after the gateway accepted it may have been billed with no figure: the meter
+ * cannot count what it was not told, so `unknownCost` is set and the cap is
+ * enforced on the known spend (a lower bound).
+ *
+ * ## CF-157 — "nothing spent" and "the server will not tell me" are not the same
+ *
+ * While the gateway runs `COHORT_BILLING_ENFORCE=shadow` it reports
+ * `cost_micros: null` on every frame and header and `{}` from
+ * `/cohort/v1/quota`. Measured again on 2026-09-22
+ * (`req_bf94feaab6405214071532a5`): still null. The old meter folded that into
+ * one boolean, left `spent` at 0 and answered `exhausted() === false` for the
+ * life of the run — so `--max-budget-usd` LOOKED armed and could never fire.
+ * That is the worst of both: an operator believes there is a cap, and there
+ * is not one.
+ *
+ * So cost visibility is now a state, not a flag:
+ *
+ *   exact    every billed request carried a figure — the cap binds exactly.
+ *   partial  some did, some did not — the cap binds on a lower bound.
+ *   blind    requests were billed and NONE carried a figure — THE CAP CANNOT
+ *            BIND. `bindable()` is false and `notice()` says so once per run.
+ *
+ * **The choice: warn, never refuse.** An unbindable budget does not stop a run
+ * and does not refuse to start, deliberately, for two reasons. Blindness is not
+ * knowable at startup — it is only observable after a request has been billed,
+ * so "refuse to start" cannot be implemented honestly. And seats are live: a
+ * gateway that stops pricing would otherwise take down every seat at once,
+ * turning a billing-mode change into an outage. The run proceeds, uncapped, and
+ * says so on stderr. A caller that needs a hard stop should read
+ * `snapshot().bindable` and decide for itself.
+ *
+ * **Tokens are not money.** The terminal frame's `usage` (CF-158) gives an
+ * EXACT token count, and the meter accumulates it as `observedTokens` so a
+ * blind run still reports a measured quantity. It is deliberately NOT converted
+ * to dollars: prices live on hq's side in `docs/deepinfra-catalogue.json` (per
+ * provider slug, keyed `input_tokens` / `cache_read_tokens`), which
+ * `packages/llm/src/capabilities.ts` points at but carries none of itself —
+ * and this repo has no price table at all, so any USD figure derived here would be a
+ * guess wearing a measurement's clothes — the exact failure CF-157 is about.
+ * `spent` therefore stays at the gateway's own figures, and only those.
+ *
+ * Pure apart from its own counters; no I/O.
+ *
+ * @module lib/engine/budget
+ */
+
+import { addUsage, emptyUsage, readFrameUsage, totalTokens } from "./wire/usage.mjs";
+
+/**
+ * `--max-budget-usd` as integer micro-USD, or an error. PURE.
+ * @param {unknown} value
+ * @returns {{ok:true, usd:number, micros:bigint}|{ok:false, error:string}}
+ */
+export function parseBudgetUsd(value) {
+  const s = String(value ?? "").trim();
+  const n = Number(s);
+  if (s === "" || !Number.isFinite(n) || n <= 0) return { ok: false, error: `--max-budget-usd must be a positive number of US dollars, got "${value}"` };
+  const micros = BigInt(Math.round(n * 1e6));
+  if (micros <= 0n) return { ok: false, error: `--max-budget-usd is below one micro-dollar: "${value}"` };
+  return { ok: true, usd: n, micros };
+}
+
+/** @param {bigint} micros */
+export function microsToUsdNumber(micros) {
+  return Number(micros) / 1e6;
+}
+
+/**
+ * @param {{maxMicros:bigint}} o
+ */
+export function createBudgetMeter({ maxMicros }) {
+  let spent = 0n;
+  let unknownCost = false;
+  let requests = 0;
+  /** Billed requests that carried a cost figure. */
+  let priced = 0;
+  /** Billed requests that carried NO cost figure — the shadow-mode signature. */
+  let unpriced = 0;
+  /** Exact token counts off the terminal frame (CF-158). Never priced. */
+  let tokens = emptyUsage("provider");
+  let tokenRequests = 0;
+  let noticed = false;
+
+  /** @returns {'exact'|'partial'|'blind'} */
+  const visibility = () => (unpriced === 0 ? "exact" : priced === 0 ? "blind" : "partial");
+
+  return {
+    maxMicros,
+    /** @param {any} res a wire result (ok or not) */
+    record(res) {
+      if (!res || typeof res !== "object") return;
+      requests++;
+      // CF-158: the frame's usage is exact for TOKENS. Kept separately from
+      // `spent`, which only ever holds the gateway's own money figures.
+      const u = readFrameUsage(res.cohort?.usage);
+      if (u) {
+        tokens = addUsage(tokens, u);
+        tokenRequests++;
+      }
+      const c = res.cohort?.costMicros;
+      if (c != null) {
+        try {
+          spent += BigInt(c);
+          priced++;
+          return;
+        } catch {
+          /* an unparseable figure is an unknown one */
+        }
+      }
+      // No figure: a refusal answered before acceptance (a status) was never billed.
+      if (res.ok || res.accepted === true || res.error?.status == null) {
+        unknownCost = true;
+        unpriced++;
+      }
+    },
+    // A blind meter never reaches the cap: spent stays 0 because no cost was
+    // ever reported. That is reported by bindable()/notice(), never papered
+    // over by treating an unreported cost as zero spend.
+    exhausted: () => spent >= maxMicros,
+    spentMicros: () => spent,
+    /** 'exact' | 'partial' | 'blind' — see the module header. */
+    costVisibility: visibility,
+    /** False when the gateway priced nothing, i.e. the cap cannot fire at all. */
+    bindable: () => visibility() !== "blind",
+    /**
+     * A one-time, run-level warning when the cap cannot bind, else null.
+     * Self-clearing, so a caller may ask after every turn and the operator
+     * still reads it once.
+     * @returns {string|null}
+     */
+    notice() {
+      if (noticed || visibility() !== "blind") return null;
+      noticed = true;
+      const observed =
+        tokenRequests > 0
+          ? `${totalTokens(tokens)} tokens over ${tokenRequests} request(s)`
+          : "no token counts either";
+      return (
+        // State the observation; do NOT diagnose the cause. An absent
+        // cost_micros is all this meter can see, and --base-url is free-form:
+        // a non-Cohort Anthropic-compatible endpoint, a proxy that drops the
+        // header, or a gateway bug land here identically. Naming shadow
+        // billing as THE reason would be inferring a cause from an absence,
+        // which is the habit this lane exists to break.
+        `--max-budget-usd ($${microsToUsdNumber(maxMicros)}) is NOT being enforced: ` +
+        `the endpoint priced none of ${unpriced} billed request(s) (no cost_micros; shadow billing is the usual cause), ` +
+        `so the run reports $0 spent and the cap can never trigger. Measured instead: ${observed} ` +
+        `— tokens are exact, but this SDK has no per-tier price table and does not convert them to dollars. ` +
+        `See docs/engine/eval.md §3 (CF-157).`
+      );
+    },
+    /**
+     * The `cohort.budget` block of a result.
+     *
+     * **`spentUsd` / `spentMicros` / `exhausted` are only meaningful when
+     * `bindable` is true.** On a blind run they read `0` / `"0"` / `false`
+     * because the endpoint priced nothing — not because nothing was spent.
+     * Any consumer that shows or acts on the spend must read `bindable` (or
+     * `costVisibility`) in the same breath; `observedTokens` is the figure
+     * that is actually measured on such a run.
+     */
+    snapshot: () => ({
+      maxUsd: microsToUsdNumber(maxMicros),
+      maxMicros: maxMicros.toString(),
+      spentUsd: microsToUsdNumber(spent),
+      spentMicros: spent.toString(),
+      exhausted: spent >= maxMicros,
+      unknownCost,
+      requests,
+      costVisibility: visibility(),
+      bindable: visibility() !== "blind",
+      pricedRequests: priced,
+      unpricedRequests: unpriced,
+      // Exact token counts, or null when no frame reported any. Never dollars.
+      observedTokens: tokenRequests > 0 ? { ...tokens, total: totalTokens(tokens) } : null,
+    }),
+  };
+}
+
+/** @typedef {ReturnType<typeof createBudgetMeter>} BudgetMeter */