@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/model-router/taxonomy.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/model-router/taxonomy.mjs — FailoverReason taxonomy + classifiers.
  *
- * The closed, 16-value `FAILOVER_REASONS` enum and its `DISPOSITION` table are
+ * The closed, 20-value `FAILOVER_REASONS` enum and its `DISPOSITION` table are
  * the *contract* between every outcome-producing surface (CLI stream-json,
  * result-json subtype, stderr, direct-api HTTP) and `failover.mjs`. The
  * disposition column semantics — retrySame, failoverNext, cooldownScope,
@@ -30,7 +30,7 @@
  * name and an alias under that exact byte sequence so either spelling resolves.
  */
 
-import { classifyStderr as rateGuardClassifyStderr } from "../rate-guard.mjs";
+import { classifyStderr as rateGuardClassifyStderr, classifyCohortRefusal } from "../rate-guard.mjs";
 
 // ---------------------------------------------------------------------------
 // The closed 16-value enum. Order is the SPEC §4.5 order; do not reorder
@@ -40,9 +40,57 @@ import { classifyStderr as rateGuardClassifyStderr } from "../rate-guard.mjs";
 /** @typedef {(
  *   "auth"|"auth_permanent"|"billing"|"rate_limit"|"overloaded"|"server_error"|
  *   "timeout"|"model_not_found"|"context_overflow"|"payload_too_large"|
- *   "content_policy"|"provider_policy"|"format"|"empty_response"|"network"|"unknown"
+ *   "content_policy"|"provider_policy"|"format"|"empty_response"|"network"|"unknown"|
+ *   "local_refusal"|"gateway_retry"|"budget_refusal"|"request_timeout"
  * )} FailoverReason */
 
+/**
+ * Gateway codes that mean "cohort-llm cannot serve right now" (CF-136), never a
+ * credential, quota or model fault. Hard refusals (cohort_limit_exceeded,
+ * cohort_credits_exhausted, cohort_spend_limit_reached) are NOT here: they keep
+ * their non-retrying rate_limit / billing classification.
+ */
+export const GATEWAY_RETRY_CODES = Object.freeze(["cohort_concurrency_exceeded", "cohort_unavailable"]);
+
+/**
+ * Gateway codes for a HARD budget refusal (CF-143, design §4.6): the tenant's
+ * seat window, credits or spend limit. Sent with `x-should-retry: false`. The
+ * refusal is about the tenant's budget, not the credential's health, so it
+ * classifies as `budget_refusal`: no credential cooling, no breaker, and no
+ * failover — another credential of the same tenant is refused again, or worse,
+ * slips past an operator's limit.
+ */
+export const BUDGET_REFUSAL_CODES = Object.freeze(["cohort_limit_exceeded", "cohort_credits_exhausted", "cohort_spend_limit_reached"]);
+
+/**
+ * Same-candidate backoff ladder for `request_timeout` (a 408: the request body
+ * stalled, so the model never saw it). One sleep per retry; the ladder's length
+ * is the retry count. Matches the engine's ladder (lib/engine/wire/http.mjs
+ * backoffMs: 500 ms, 1 s). Named here pending owner confirmation (CF-143).
+ */
+export const REQUEST_TIMEOUT_BACKOFF_MS = Object.freeze([500, 1000]);
+
+/** A same-candidate retry never sleeps through a retry-after longer than this (the engine's DEFAULT_MAX_RETRY_AFTER_MS). */
+export const MAX_SAME_RETRY_AFTER_MS = 30_000;
+
+/**
+ * The cohort code in a gateway error body on either wire — the top-level
+ * `cohort` refusal object first, then `error.code`. null when there is none.
+ * @param {object|string|null} body
+ * @returns {string|null}
+ */
+export function cohortCodeOf(body) {
+  let o = body;
+  if (typeof body === "string") {
+    try { o = JSON.parse(body); } catch { return null; }
+  }
+  if (!o || typeof o !== "object") return null;
+  const top = o.cohort && typeof o.cohort === "object" && typeof o.cohort.code === "string" ? o.cohort.code : null;
+  if (top && top.startsWith("cohort_")) return top;
+  const e = o.error && typeof o.error === "object" && typeof o.error.code === "string" ? o.error.code : null;
+  return e && e.startsWith("cohort_") ? e : null;
+}
+
 export const FAILOVER_REASONS = Object.freeze([
   "auth",
   "auth_permanent",
@@ -60,6 +108,29 @@ export const FAILOVER_REASONS = Object.freeze([
   "empty_response",
   "network",
   "unknown",
+  // Appended (CF-11, Cohort Compute W2-E): the retarget was refused BEFORE any
+  // request left the machine (no third-party token, a subscription token as the
+  // token, a helper aimed at the wrong gateway). Nothing about the backend is
+  // known, so it fails over without opening any breaker.
+  "local_refusal",
+  // Appended (CF-136, Cohort Compute W7): the cohort-llm gateway is briefly
+  // unable to serve — 429 `cohort_concurrency_exceeded` (retry-after: 2) or 503
+  // `cohort_unavailable` (its OWN provider key refused upstream). Neither says
+  // anything about this seat's credential or the model: no credential cooling,
+  // no breaker, no failover to another provider's credential. The walk stops
+  // and hands the gateway's refusal (and retry-after) back to the caller.
+  "gateway_retry",
+  // Appended (CF-143, Cohort Compute W8): a HARD budget refusal from the
+  // gateway — 429 `cohort_limit_exceeded`, 402 `cohort_credits_exhausted` /
+  // `cohort_spend_limit_reached` (x-should-retry: false). The tenant's budget,
+  // not the credential: no cooling, no breaker, no failover, never retried. The
+  // walk stops and returns the refusal object (resetsAt) to the caller.
+  "budget_refusal",
+  // Appended (CF-143): a 408 — the request body stalled before the model saw
+  // it. Always safe to resend: the same candidate is retried on the
+  // REQUEST_TIMEOUT_BACKOFF_MS ladder before failing over. A generic `timeout`
+  // (a turn that ran too long) keeps its single immediate retry.
+  "request_timeout",
 ]);
 
 const REASON_SET = new Set(FAILOVER_REASONS);
@@ -130,6 +201,9 @@ export function cooldownMsFor(reason, strike = 0) {
 //                    | "jittered" (once, jittered) | "backoff" (once, backoff)
 //                    | "cli" (the CLI already retried server_error ≤10× internally;
 //                            we do not re-retry the same candidate ourselves).
+//   retryBackoffMs — when present, the same candidate is retried once per
+//                    entry, sleeping that many ms first (a retry-after the
+//                    attempt reported wins, up to MAX_SAME_RETRY_AFTER_MS).
 //   failoverNext   — may we advance to the next candidate in the chain?
 //   cooldownScope  — which breaker key cools: none | backend | backend:model |
 //                    model-id | operator
@@ -153,6 +227,35 @@ export function cooldownMsFor(reason, strike = 0) {
 // ---------------------------------------------------------------------------
 
 export const DISPOSITION = Object.freeze({
+  gateway_retry: Object.freeze({
+    retrySame: false, // the engine's HTTP edge already retried; the caller holds the seat on the refusal
+    failoverNext: false, // the gateway is the route; another provider's credential is not a fix
+    cooldownScope: "none",
+    cooldownMs: 0,
+    opensBreaker: false,
+  }),
+  budget_refusal: Object.freeze({
+    retrySame: false, // x-should-retry: false — retrying a drained window only burns requests
+    failoverNext: false, // the same tenant is refused again, or an operator limit is bypassed
+    cooldownScope: "none", // the credential is healthy
+    cooldownMs: 0,
+    opensBreaker: false, // the backend is healthy
+  }),
+  request_timeout: Object.freeze({
+    retrySame: "backoff",
+    retryBackoffMs: REQUEST_TIMEOUT_BACKOFF_MS, // one sleep per same-candidate retry, then fail over
+    failoverNext: true,
+    cooldownScope: "none",
+    cooldownMs: 0,
+    opensBreaker: false,
+  }),
+  local_refusal: Object.freeze({
+    retrySame: false,
+    failoverNext: true,
+    cooldownScope: "none",
+    cooldownMs: 0,
+    opensBreaker: false,
+  }),
   auth: Object.freeze({
     retrySame: false,
     failoverNext: true,
@@ -459,6 +562,15 @@ export function classifyStderr(text) {
   if (typeof text !== "string" || !text) return null;
   const t = text.toLowerCase();
 
+  // A cohort-llm transient code in a run's output (an engine JSON result, an
+  // echoed gateway body) is checked first: its body also says "rate_limit_error"
+  // or "503", which the patterns below would read as a provider fault (CF-136).
+  // Only a parsed refusal object counts, never the bare word: a transcript or a
+  // file that merely mentions the code must not mask a real 401 or overflow.
+  const refusal = classifyCohortRefusal(text);
+  if (refusal && GATEWAY_RETRY_CODES.includes(refusal.code)) return "gateway_retry";
+  if (refusal && BUDGET_REFUSAL_CODES.includes(refusal.code)) return "budget_refusal";
+
   if (STDERR_CONTEXT_OVERFLOW.some((p) => t.includes(p))) return "context_overflow";
   if (STDERR_CONTENT_POLICY.some((p) => t.includes(p))) return "content_policy";
   if (STDERR_AUTH.some((p) => t.includes(p))) return "auth";
@@ -743,6 +855,16 @@ export function classifyHttp(status, body) {
   const { text, code } = flattenHttpBody(body);
   const st = Number.isFinite(status) ? Number(status) : null;
 
+  // ── 0. cohort-llm transient codes (CF-136). Before every status rule: a 429
+  //        concurrency cap must not read as rate_limit (credential cooling +
+  //        breaker + failover), and a 503 provider-key outage must not read as
+  //        overloaded or auth. ─────────────────────────────────────────────────
+  const cohortCode = cohortCodeOf(body);
+  if (cohortCode && GATEWAY_RETRY_CODES.includes(cohortCode)) return "gateway_retry";
+  // Hard budget refusals (CF-143): before the 429 → rate_limit and 402 → billing
+  // rows, which cool the credential, open a breaker and fail over.
+  if (cohortCode && BUDGET_REFUSAL_CODES.includes(cohortCode)) return "budget_refusal";
+
   // ── 1. Body-pattern signals that override status (deterministic refusals,
   //        OpenRouter policy blocks, content policy) ─────────────────────────
   if (hasAny(text, CONTENT_POLICY_PATTERNS)) return "content_policy";
@@ -792,7 +914,7 @@ export function classifyHttp(status, body) {
     if (st === 413) return "payload_too_large";
     if (st === 429) return "rate_limit";
     if (st === 400) return classify400(text, code);
-    if (st === 408) return "timeout";
+    if (st === 408) return "request_timeout"; // the body stalled; safe to resend (CF-143)
     if (st === 500 || st === 502) {
       // Some gateways return request-validation errors as 5xx — fail fast.
       if (hasAny(text, REQUEST_VALIDATION_PATTERNS) || code === "invalid_request_error")

package/lib/org/cost-sync.mjs

@@ -26,6 +26,17 @@
  * `${decision_id}:${session_id}:${ts}` || a content hash). The server is
  * idempotent on cost.report, so the same row reported twice is a no-op replay.
  *
+ * cohort-llm rows: a row whose session cohort-llm served carries
+ * `billed_by:"cohort-llm"`. The gateway already metered it at the point of
+ * service (design §8.3), so reporting it again would double-count it in hq.
+ * Such rows are SKIPPED here and counted in `skippedBilledBy`.
+ *
+ * Per-row results (CF-17): hq's cost.report now answers per row —
+ * `results[]` of {index, id, status: ingested|duplicate|rejected, code?, error?}.
+ * A batch whose frame carries it is counted row by row (ingested + duplicate
+ * are delivered; rejected are failed, with their codes); an older server that
+ * only returns `frame.ok` is counted per batch as before.
+ *
  * Node builtins only. Fail-open (a down/disabled server reports nothing rather
  * than throwing). `fetchImpl`, `now`, and `ledgerDir`/`agentRoot` are injectable
  * for deterministic tests. ESM.
@@ -134,7 +145,9 @@ export function toReportRow(row, deps = {}) {
   const day = (row && row.ts && String(row.ts).slice(0, 10)) || dayStr(deps);
   return {
     id,
-    agent: row.agent ?? null,
+    // Tracker rows carry no `agent`, and hq rejects a row without one — the
+    // seat's own Cohort identity is the default (deps.agent, see seatAgentId).
+    agent: row.agent ?? deps.agent ?? null,
     model: row.model ?? null,
     backend: row.backend ?? null,
     input_tokens: numOr0(row.input_tokens),
@@ -152,8 +165,11 @@ export function toReportRow(row, deps = {}) {
     decision_id: row.decision_id ?? null,
     session_id: row.session_id ?? null,
     // G16: attribution fields — DO NOT STRIP. cadence/source surface coordination
-    // spend in the rollup so an LLM-in-the-loop violation is visible.
-    source: row.source ?? null,
+    // spend in the rollup so an LLM-in-the-loop violation is visible. `source` is
+    // mapped into the vocabulary hq accepts (an out-of-set source used to reject
+    // the whole batch); the ledger's own spelling rides in `source_detail`.
+    source: reportSource(row.source),
+    source_detail: row.source ?? null,
     cadence: row.cadence ?? row.lane ?? null,
     task_class: row.task_class ?? null,
     ts: row.ts ?? null,
@@ -166,6 +182,69 @@ function numOr0(v) {
   return Number.isFinite(n) ? n : 0;
 }
 
+// ---------------------------------------------------------------------------
+// Wire vocabulary: the sources hq accepts, and the seat identity
+// ---------------------------------------------------------------------------
+
+/**
+ * The `source` values hq's cost.report accepts
+ * (hq src/server/methods/cost/report.ts VALID_SOURCES). A row outside this set
+ * is a BAD_REQUEST that rejects the entire batch — and every live ledger writer
+ * (`--source dispatcher|responder|cadence-consumer`, `messaging`, `lookup`)
+ * was outside it, so no seat's spend reached hq (A2 §6.3).
+ */
+export const HQ_REPORT_SOURCES = Object.freeze(["router", "cadence", "channel", "manual", "org-server"]);
+
+/**
+ * Live ledger source → hq source. hq is widening its list to the live names
+ * (Cohort Compute W1-D); this map is valid against both the old and the new
+ * list, so the push never depends on which hq is deployed.
+ */
+const LIVE_SOURCE_MAP = Object.freeze({
+  "cadence-consumer": "cadence",
+  "handoff-timeout": "cadence",
+  dispatcher: "router",
+  backlog: "router",
+  lookup: "router",
+  classifier: "router",
+  responder: "channel",
+  messaging: "channel",
+  ack: "channel",
+});
+
+/**
+ * Map a ledger row's source onto hq's accepted vocabulary. Pure.
+ * Absent → null (hq defaults it); an accepted value passes through; a known
+ * live source maps; anything else is "router", hq's own default for a routed
+ * spend row, so one unfamiliar writer can never reject a batch again.
+ * @param {unknown} source
+ * @returns {string|null}
+ */
+export function reportSource(source) {
+  if (source == null || source === "") return null;
+  const s = String(source);
+  if (HQ_REPORT_SOURCES.includes(s)) return s;
+  return LIVE_SOURCE_MAP[s] || "router";
+}
+
+/**
+ * The seat's Cohort identity — the member slug hq authenticates this seat's key
+ * as — for rows that carry no `agent`. Explicit enrolment wins:
+ * `org.cohort.agentId` in config/org.yaml, then COHORT_AGENT_ID (the canonical
+ * provisioning variable). Pure over its inputs. null when the seat has neither:
+ * a guessed slug (a directory name) would be attributed to the wrong member,
+ * and hq defaults a missing agent to the authenticated actor.
+ * @param {{cfg?:object, env?:object}} o
+ * @returns {string|null}
+ */
+export function seatAgentId({ cfg, env = process.env } = {}) {
+  const n = (cfg && cfg.org && cfg.org.cohort) || {};
+  for (const v of [n.agentId, env && env.COHORT_AGENT_ID]) {
+    if (typeof v === "string" && v.trim()) return v.trim();
+  }
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Report — batched, idempotent push to cost.report
 // ---------------------------------------------------------------------------
@@ -188,8 +267,41 @@ function numOr0(v) {
  *   localUSD:number, batches:Array<{count:number, ok:boolean, code?:string}>
  * }>}
  */
+/** The billed_by value of rows cohort-llm metered itself. */
+export const COHORT_LLM_BILLED_BY = "cohort-llm";
+
+/**
+ * Count a batch outcome from hq's per-row results when present. PURE.
+ * @param {object|null} frame the cost.report response frame
+ * @param {number} sent       rows in the batch
+ * @returns {{perRow:boolean, delivered:number, failed:number, ingested:number, duplicate:number, rejected:number, rejections:Array<{id:string|null, code:string|null, error:string|null}>}}
+ */
+export function countBatchResults(frame, sent) {
+  const result = frame && frame.ok && frame.result && typeof frame.result === "object" ? frame.result : null;
+  const results = result && Array.isArray(result.results) ? result.results : null;
+  if (!results) {
+    const ok = !!(frame && frame.ok);
+    return { perRow: false, delivered: ok ? sent : 0, failed: ok ? 0 : sent, ingested: ok ? sent : 0, duplicate: 0, rejected: ok ? 0 : sent, rejections: [] };
+  }
+  let ingested = 0, duplicate = 0, rejected = 0;
+  const rejections = [];
+  for (const r of results) {
+    const status = r && r.status;
+    // "accepted" is tolerated as a synonym of "ingested" (the design's wording).
+    if (status === "ingested" || status === "accepted") ingested++;
+    else if (status === "duplicate") duplicate++;
+    else { rejected++; rejections.push({ id: (r && r.id) ?? null, code: (r && r.code) ?? null, error: (r && r.error) ?? null }); }
+  }
+  // Rows the server never mentioned did not land.
+  const unaccounted = Math.max(0, sent - results.length);
+  return { perRow: true, delivered: ingested + duplicate, failed: rejected + unaccounted, ingested, duplicate, rejected: rejected + unaccounted, rejections };
+}
+
 export async function reportLedger(o = {}) {
-  const rows = readLedgerRows(o);
+  const allRows = readLedgerRows(o);
+  const rows = allRows.filter((r) => !(r && r.billed_by === COHORT_LLM_BILLED_BY));
+  const skippedBilledBy = allRows.length - rows.length;
+  const log = typeof o.log === "function" ? o.log : null;
   // Bill through the ONE definition (lib/cost/ledger-row.mjs), not `estimated_usd`:
   // the authoritative `total_cost_usd` where present, the cache-aware estimate as
   // a fallback, and unmeasured sessions IMPUTED rather than summed as free. The
@@ -200,15 +312,16 @@ export async function reportLedger(o = {}) {
   const localUSD = round6(summary.measuredUsd + imputeUnmeasured(summary).imputedUsd);
 
   if (!isEnabled(o.cfg)) {
-    return { enabled: false, rowsRead: rows.length, reported: 0, failed: 0, localUSD, batches: [] };
+    return { enabled: false, rowsRead: allRows.length, reported: 0, failed: 0, skippedBilledBy, localUSD, batches: [] };
   }
   if (rows.length === 0) {
-    return { enabled: true, rowsRead: 0, reported: 0, failed: 0, localUSD, batches: [] };
+    return { enabled: true, rowsRead: allRows.length, reported: 0, failed: 0, skippedBilledBy, localUSD, batches: [] };
   }
 
   const c = configFromAgent(o.cfg);
   const batchSize = Number.isFinite(o.batchSize) && o.batchSize > 0 ? Math.floor(o.batchSize) : REPORT_BATCH;
-  const wireRows = rows.map((r) => toReportRow(r, o));
+  const agent = o.agent !== undefined ? o.agent : seatAgentId({ cfg: o.cfg, env: o.env || process.env });
+  const wireRows = rows.map((r) => toReportRow(r, { ...o, agent }));
 
   let reported = 0;
   let failed = 0;
@@ -225,11 +338,28 @@ export async function reportLedger(o = {}) {
       fetchImpl: o.fetchImpl,
     });
     const ok = !!(frame && frame.ok);
-    if (ok) reported += slice.length; else failed += slice.length;
-    batches.push({ count: slice.length, ok, code: ok ? undefined : (frame && frame.error && frame.error.code) || "error" });
+    const counts = countBatchResults(frame, slice.length);
+    reported += counts.delivered;
+    failed += counts.failed;
+    batches.push({
+      count: slice.length,
+      ok,
+      code: ok ? undefined : (frame && frame.error && frame.error.code) || "error",
+      ...(counts.perRow ? { ingested: counts.ingested, duplicate: counts.duplicate, rejected: counts.rejected, rejections: counts.rejections } : {}),
+    });
+    if (log) {
+      try {
+        if (counts.perRow) {
+          const codes = [...new Set(counts.rejections.map((r) => r.code).filter(Boolean))];
+          log(counts.rejected ? "warn" : "info", `cost.report batch of ${slice.length}: ${counts.ingested} ingested, ${counts.duplicate} duplicate, ${counts.rejected} rejected${codes.length ? ` (${codes.join(", ")})` : ""}`);
+        } else {
+          log(ok ? "info" : "warn", `cost.report batch of ${slice.length}: ${ok ? "ok" : `failed (${batches[batches.length - 1].code})`} (server sent no per-row results)`);
+        }
+      } catch { /* logging must not break the push */ }
+    }
   }
 
-  return { enabled: true, rowsRead: rows.length, reported, failed, localUSD, batches };
+  return { enabled: true, rowsRead: allRows.length, reported, failed, skippedBilledBy, localUSD, batches };
 }
 
 function round6(n) {
@@ -238,4 +368,4 @@ function round6(n) {
 
 export const _internals = { ledgerFile, ledgerDir, dayStr, stableJson, REPORT_BATCH };
 
-export default { readLedgerRows, rowId, toReportRow, reportLedger };
+export default { readLedgerRows, rowId, toReportRow, reportLedger, reportSource, seatAgentId, countBatchResults, COHORT_LLM_BILLED_BY };