@cohortapp/agent-sdk 2.5.1 → 2.6.0

package/lib/model-router/ledger.mjs

@@ -41,6 +41,7 @@ import { join, resolve } from "node:path";
 
 import { lookupModel } from "./catalog.mjs";
 import { appendJsonl } from "../fs-atomic.mjs";
+import { billableUsd, summariseRows as summariseCostRows } from "../cost/ledger-row.mjs";
 
 const MTOK = 1e6;
 
@@ -288,6 +289,15 @@ export function buildLedgerRow(catalog, entry = {}, deps = {}) {
   const cacheReadTokens = nonNeg(entry.cacheReadTokens);
   const cacheWriteTokens = nonNeg(entry.cacheWriteTokens);
 
+  // DID THE CALLER ACTUALLY SUPPLY TOKEN COUNTS? `nonNeg` maps undefined/NaN to
+  // 0, so without this the row cannot tell "0 tokens" from "nobody told me", and
+  // an LLM session whose usage was unreadable is written as a measured, billable
+  // $0 — the exact defect lib/cost/ledger-row.mjs exists to end, re-created by
+  // its own v2 writer. `llm-task.mjs#writeRow` passes `usage.inputTokens`
+  // straight through, so absent usage lands here regularly.
+  const suppliedTokens =
+    Number.isFinite(Number(entry.inputTokens)) || Number.isFinite(Number(entry.outputTokens));
+
   const hasAuthoritative =
     typeof entry.totalCostUSD === "number" && Number.isFinite(entry.totalCostUSD);
 
@@ -304,10 +314,34 @@ export function buildLedgerRow(catalog, entry = {}, deps = {}) {
 
   const totalCostUSD = hasAuthoritative ? round6(entry.totalCostUSD) : est.usd;
   const estimated = !hasAuthoritative;
-  // Load-bearing: budget-guard sums `estimated_usd`. Use the authoritative cost
-  // when present, else the estimate. Never null here (default 0) so a row always
-  // counts as a session with a finite spend.
-  const estimated_usd = totalCostUSD == null ? 0 : totalCostUSD;
+  // Load-bearing: readers bill through lib/cost/ledger-row.mjs. `null` — NOT 0
+  // — when nothing could price this row (`estimateCost` returns
+  // `{usd:null, basis:"no-row"}` for a model that is not in the catalog). A 0
+  // here used to read downstream as "this session was free", which is how an
+  // unpriced model or an unreadable usage envelope quietly shrank the day's
+  // spend. Null classifies as `unknown` and gets IMPUTED instead.
+  const estimated_usd = totalCostUSD == null ? null : totalCostUSD;
+
+  // The explicit measurement class. Three cases, and the middle one is the fix:
+  //   n/a       no model ran (message-send attribution). $0 is a fact.
+  //   unknown   a model DID run but we have neither token counts nor a price —
+  //             the cost is unknown, not zero. Readers impute it and doctor
+  //             goes red; nothing here may launder it into a measured $0.
+  //   measured  real usage and/or a real price.
+  const measurement =
+    !ref && !suppliedTokens && inputTokens === 0 && outputTokens === 0
+      ? "n/a"
+      : !suppliedTokens && totalCostUSD == null
+        ? "unknown"
+        : totalCostUSD == null && inputTokens === 0 && outputTokens === 0
+          ? "unknown"
+          : "measured";
+  const unmeasuredReason =
+    measurement !== "unknown"
+      ? null
+      : !suppliedTokens
+        ? `no usage was supplied for ${ref || "an unknown model"} and no authoritative cost accompanied it`
+        : `usage was supplied as 0/0 and ${ref || "the model"} could not be priced (${est.basis})`;
 
   const now = (deps && typeof deps.now === "function" ? deps.now : Date.now)();
 
@@ -322,14 +356,21 @@ export function buildLedgerRow(catalog, entry = {}, deps = {}) {
     harness: entry.harness ?? null,
     backend: provider || null,
     model,
-    input_tokens: inputTokens,
-    output_tokens: outputTokens,
+    // Null, not 0, when nobody supplied a count — see `suppliedTokens`.
+    input_tokens: suppliedTokens ? inputTokens : null,
+    output_tokens: suppliedTokens ? outputTokens : null,
     cache_read_tokens: cacheReadTokens,
     cache_creation_tokens: cacheWriteTokens,
     total_cost_usd: totalCostUSD,
     // --- budget-guard compatibility (DO NOT REMOVE) ---
     estimated_usd,
     // ---------------------------------------------------
+    // Explicit measurement class so readers never have to infer it from the row
+    // shape. A row with no model and no tokens is zero-LLM attribution (a
+    // message send): $0 is a fact there, and it must not be counted as a session
+    // or arm the "sessions ran but spend is $0" tripwire.
+    measurement,
+    unmeasured_reason: unmeasuredReason,
     estimated,
     cost_basis: est.basis,
     volatile: est.volatile,
@@ -361,15 +402,26 @@ export function writeLedgerRow(catalog, entry = {}, deps = {}) {
 }
 
 /**
- * Sum today's ledger the SAME way budget-guard does (reads `estimated_usd`),
- * for tests / `maestro cost report`. NEVER throws.
+ * Sum today's ledger the SAME way budget-guard does, for tests /
+ * `maestro cost report`. NEVER throws.
+ *
+ * "The same way" now means via lib/cost/ledger-row.mjs: bill the CLI's
+ * authoritative `total_cost_usd` where present, fall back to the estimate, and
+ * treat an unmeasured session as UNKNOWN rather than free. It previously summed
+ * `estimated_usd` unconditionally, which both under-priced cache reads and
+ * silently reported unmeasured sessions as $0 — the two halves of the bug that
+ * kept the budget governor from ever tripping.
  *
  * @param {object} [deps] { now, ledgerDir, agentRoot }
- * @returns {{ spentUSD:number, sessions:number, byModel:Record<string,number> }}
+ * @returns {{ spentUSD:number, sessions:number, byModel:Record<string,number>,
+ *             unmeasuredSessions:number, nonLlmRows:number, degradations:string[] }}
  */
 export function sumLedgerToday(deps = {}) {
   const file = ledgerFile(deps);
-  const out = { spentUSD: 0, sessions: 0, byModel: {} };
+  const out = {
+    spentUSD: 0, sessions: 0, byModel: {},
+    unmeasuredSessions: 0, nonLlmRows: 0, degradations: [],
+  };
   if (!existsSync(file)) return out;
   let body;
   try {
@@ -377,22 +429,23 @@ export function sumLedgerToday(deps = {}) {
   } catch {
     return out;
   }
+  const rows = [];
   for (const line of body.split("\n")) {
     if (!line.trim()) continue;
-    let row;
-    try {
-      row = JSON.parse(line);
-    } catch {
-      continue;
-    }
-    const usd = Number(row.estimated_usd);
-    if (Number.isFinite(usd)) {
-      out.spentUSD += usd;
-      const key = row.model || row.backend || "unknown";
-      out.byModel[key] = round6((out.byModel[key] || 0) + usd);
-    }
+    try { rows.push(JSON.parse(line)); } catch { continue; }
+  }
+  for (const row of rows) {
+    const { usd, basis } = billableUsd(row);
+    if (basis === "non_llm" || basis === "invalid") continue;
     out.sessions += 1;
+    if (basis === "unmeasured") { out.unmeasuredSessions += 1; continue; }
+    out.spentUSD += usd;
+    const key = row.model || row.backend || "unknown";
+    out.byModel[key] = round6((out.byModel[key] || 0) + usd);
   }
+  const summary = summariseCostRows(rows);
+  out.nonLlmRows = summary.nonLlmRows;
+  out.degradations = summary.degradations;
   out.spentUSD = round6(out.spentUSD);
   return out;
 }

package/lib/model-router/ledger.test.mjs

@@ -11,6 +11,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { loadCatalog } from "./catalog.mjs";
+import { billableUsd } from "../cost/ledger-row.mjs";
 import {
   estimateCost,
   buildLedgerRow,
@@ -313,11 +314,43 @@ test("buildLedgerRow uses the authoritative totalCostUSD when present (estimated
   assert.equal(row.estimated, false);
 });
 
-test("buildLedgerRow estimated_usd is never null (budget-guard counts every row)", () => {
+test("buildLedgerRow: an UNPRICEABLE row is null, not 0 — a $0 here reads as a free session", () => {
+  // This asserted `estimated_usd === 0` for a model with no catalog row, on the
+  // theory that budget-guard needed a finite number on every line. It does not:
+  // readers bill through lib/cost/ledger-row.mjs, which treats a 0 on a row that
+  // NAMED a model as "could not price", imputes it, and turns doctor red. A
+  // literal 0 was the "a zero that means unmeasured" defect, re-created by the
+  // v2 writer the module was written to replace.
   const c = cat();
   const row = buildLedgerRow(c, { agent: "x", provider: "ghost", model: "model", inputTokens: 10 });
-  assert.equal(row.estimated_usd, 0);
+  assert.equal(row.estimated_usd, null);
   assert.equal(row.total_cost_usd, null);
+  assert.equal(row.measurement, "measured", "usage WAS supplied; only the price is missing");
+  assert.equal(billableUsd(row).basis, "unpriced");
+  assert.equal(billableUsd(row).usd, null);
+});
+
+test("buildLedgerRow: usage nobody supplied is `unknown`, never a measured zero", () => {
+  // llm-task.mjs#writeRow passes `usage.inputTokens` straight through, so an
+  // unreadable usage envelope arrives here as undefined. `nonNeg` mapped that to
+  // 0 and the row was stamped `measurement:"measured"` billing $0 — no
+  // degradation, no unmeasured count, doctor green.
+  const c = cat();
+  const row = buildLedgerRow(c, { agent: "x", ref: "anthropic/claude-opus-4-6", provider: "anthropic", model: "claude-opus-4-6" });
+  assert.equal(row.measurement, "unknown");
+  assert.equal(row.input_tokens, null);
+  assert.equal(row.output_tokens, null);
+  assert.equal(row.estimated_usd, null);
+  assert.match(row.unmeasured_reason, /no usage was supplied/);
+  assert.equal(billableUsd(row).usd, null, "unknown cost, not free");
+});
+
+test("buildLedgerRow: a zero-model attribution row is still a real $0", () => {
+  // The one case where 0 is a FACT: a message send, no model, no tokens.
+  const row = buildLedgerRow(cat(), { agent: "x", source: "messaging", task_class: "messaging.send" });
+  assert.equal(row.measurement, "n/a");
+  assert.equal(billableUsd(row).usd, 0);
+  assert.equal(billableUsd(row).basis, "non_llm");
 });
 
 test("buildLedgerRow projects volatile spend at steady-state for budgeting", () => {

package/lib/org/client.mjs

@@ -643,6 +643,20 @@ export function createItem(item, o = {}) {
   return call("board.create", item || {}, o);
 }
 
+/**
+ * Record ONE step of this agent's work against the board (board.track).
+ *
+ * The server holds all the policy — whether the ask deserves a row at all, the
+ * find-or-open, the column ladder, comment de-duplication and who gets tagged —
+ * because the SAME code serves hq's in-process responder. This wrapper is
+ * deliberately dumb so the two planes cannot drift.
+ *
+ * Idempotent on (askKey, stage): pass a stable idempotencyKey for safe retries.
+ */
+export function trackWork(params, o = {}) {
+  return call("board.track", params || {}, o);
+}
+
 /**
  * Claim a board item (board.claim). The server resolves the race atomically; the
  * loser gets a CONFLICT error frame. Caller MUST pass a stable idempotencyKey

package/lib/org/cost-sync.mjs

@@ -40,6 +40,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 
 import { isEnabled, configFromAgent, costReport } from "./client.mjs";
+import { summariseRows as summariseCostRows, imputeUnmeasured, billableUsd } from "../cost/ledger-row.mjs";
 
 const REPORT_BATCH = 100;
 
@@ -140,7 +141,13 @@ export function toReportRow(row, deps = {}) {
     output_tokens: numOr0(row.output_tokens),
     cache_read_tokens: numOr0(row.cache_read_tokens),
     cache_creation_tokens: numOr0(row.cache_creation_tokens),
-    estimated_usd: numOr0(row.estimated_usd),
+    // The BILLABLE figure (authoritative `total_cost_usd` first, cache-aware
+    // estimate second) rather than the raw `estimated_usd` column, so the org
+    // rollup and the seat's own governor read the same file the same way. A row
+    // we could not measure reports 0 here on purpose: a per-row imputation would
+    // be a fabricated number on a permanent record. The day-level imputation
+    // lives in `localUSD`, which is the reconciliation figure.
+    estimated_usd: billableUsd(row).usd ?? 0,
     total_cost_usd: row.total_cost_usd ?? null,
     decision_id: row.decision_id ?? null,
     session_id: row.session_id ?? null,
@@ -183,7 +190,14 @@ function numOr0(v) {
  */
 export async function reportLedger(o = {}) {
   const rows = readLedgerRows(o);
-  const localUSD = round6(rows.reduce((s, r) => s + numOr0(r.estimated_usd), 0));
+  // 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
+  // old `numOr0(row.estimated_usd)` under-read the same days budget-guard did
+  // (2026-08-11: $90.79 reported to hq against $235.62 actually spent), so the
+  // org rollup and the seat's own governor disagreed about the same file.
+  const summary = summariseCostRows(rows);
+  const localUSD = round6(summary.measuredUsd + imputeUnmeasured(summary).imputedUsd);
 
   if (!isEnabled(o.cfg)) {
     return { enabled: false, rowsRead: rows.length, reported: 0, failed: 0, localUSD, batches: [] };

package/lib/org/doctor.mjs

@@ -40,6 +40,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { PROTOCOL_VERSION, methodDef } from "./protocol.mjs";
 import { loadOrgConfig, configFromAgent, call, fetchSelfProfile } from "./client.mjs";
+import { remedyFor } from "./email-remedy.mjs";
 
 const PROBE_TIMEOUT_MS = 8000;
 
@@ -139,6 +140,66 @@ export function checkReactiveLaneWiring(agentRoot, deps = {}) {
   }
 }
 
+/**
+ * Turn an `email.inbox` error frame into an ACTIONABLE doctor line.
+ *
+ * The old line was `workspace mailbox probe: NOT_FOUND — no active mailbox is
+ * assigned to this agent (admin: Cohort → Settings → Email)`. Every word of
+ * that is true and none of it tells an operator what to actually do, so on a
+ * live seat it sat unresolved while the daemon logged the same sentence 478
+ * times in a day. A doctor line that describes a state without naming the actor
+ * and the act is a line people learn to scroll past.
+ *
+ * So: name WHO does WHAT, and distinguish the three genuinely different causes,
+ * because they have three different owners.
+ *
+ *   NOT_FOUND        — the seat has no mailbox (or the domain isn't verified).
+ *                      FAIL: the email lane is dead, not degraded. Since 2026-08
+ *                      `pairing.approve` provisions a mailbox at enrolment, so
+ *                      reaching this on a paired agent means either the org has
+ *                      no VERIFIED domain or this seat was paired before that
+ *                      shipped — hence both remedies, in order.
+ *   FORBIDDEN_SCOPE  — the key isn't paired, or lacks the email scope. FAIL.
+ *   anything else    — transient/unknown: WARN, fail-open.
+ *
+ * Pure; exported for tests.
+ *
+ * @param {{code?: string, message?: string}} [err]
+ * @returns {{level:"warn"|"fail", msg:string}}
+ */
+export function mailboxProbeVerdict(err) {
+  const code = (err && err.code) || "?";
+  const detail = (err && err.message) || "no detail";
+
+  if (code === "NOT_FOUND") {
+    return {
+      level: "fail",
+      msg:
+        "Workspace mailbox: NONE. This agent cannot receive email at all — the orgmail lane is dead, " +
+        "not degraded. TWO possible causes, check in this order: " +
+        "(1) the workspace has no VERIFIED email domain — a workspace ADMIN adds it at " +
+        "Cohort → Settings → Email → Domains, publishes the DNS records, and clicks Verify; " +
+        "(2) the domain IS verified but this seat predates automatic provisioning — the same ADMIN " +
+        "opens Cohort → Settings → Email → Mailboxes, picks this agent's member row, and assigns a " +
+        "local part (seats paired after 2026-08 get one automatically at `pairing.approve`). " +
+        `Server said: ${detail}`,
+    };
+  }
+  if (code === "FORBIDDEN_SCOPE" || code === "FORBIDDEN" || code === "UNAUTHORIZED") {
+    // Same sentence the adapter logs and `maestro setup` prints — one
+    // classifier, so an operator is told the same thing by whichever surface
+    // they happen to hit first (lib/org/email-remedy.mjs).
+    return {
+      level: "fail",
+      msg: `Workspace mailbox: ${remedyFor(code)}. Server said: ${detail}`,
+    };
+  }
+  return {
+    level: "warn",
+    msg: `workspace mailbox probe inconclusive (${code}: ${detail}) — retry; if it persists, a workspace ADMIN checks Cohort → Settings → Email`,
+  };
+}
+
 /**
  * Run the Cohort connectivity probes.
  * @param {object} o
@@ -331,7 +392,7 @@ export async function checkOrgConnectivity(o = {}) {
         const addr = inbox.result?.mailbox?.address || "";
         results.push({ level: "ok", msg: `workspace mailbox reachable${addr ? ` (${addr})` : ""}` });
       } else {
-        results.push({ level: "warn", msg: `workspace mailbox probe: ${inbox.error?.code || "?"} — ${inbox.error?.message || "no detail"} (admin: Cohort → Settings → Email)` });
+        results.push(mailboxProbeVerdict(inbox.error));
       }
     }
   }

package/lib/org/doctor.test.mjs

@@ -197,7 +197,7 @@ test("probe 4: orgmail gate + family vendored → mailbox probe surfaces the add
   rmSync(r, { recursive: true, force: true });
 });
 
-test("probe 4: mailbox probe failure warns with the admin remedy (never a fail)", async () => {
+test("probe 4: NO mailbox FAILS and names who does what (it is a dead lane, not a degraded one)", async () => {
   const r = root({ orgmail: true });
   const f = stubFetch({
     "/api/v1/directory": DIR_OK,
@@ -205,9 +205,42 @@ test("probe 4: mailbox probe failure warns with the admin remedy (never a fail)"
     "/api/v1/email.inbox": { status: 404, body: { ok: false, error: { code: "NOT_FOUND", message: "no mailbox for member" } } },
   });
   const rs = await checkOrgConnectivity({ agentRoot: r, fetchImpl: f, env: {} });
-  const mail = rs.find((x) => /workspace mailbox probe/.test(x.msg));
+  const mail = rs.find((x) => /Workspace mailbox/.test(x.msg));
+  assert.equal(mail.level, "fail");
+  // The whole point: an ACTOR and an ACT, not just a state.
+  assert.match(mail.msg, /workspace ADMIN/);
+  assert.match(mail.msg, /Settings → Email → Mailboxes/);
+  assert.match(mail.msg, /Settings → Email → Domains/);
+  // The server's own words survive, so the operator can tell the two apart.
+  assert.match(mail.msg, /no mailbox for member/);
+  rmSync(r, { recursive: true, force: true });
+});
+
+test("probe 4: an unpaired/unscoped key is a DIFFERENT fail with a different remedy", async () => {
+  const r = root({ orgmail: true });
+  const f = stubFetch({
+    "/api/v1/directory": DIR_OK,
+    "/api/v1/messaging.channels": CHANNELS_OK,
+    "/api/v1/email.inbox": { status: 403, body: { ok: false, error: { code: "FORBIDDEN_SCOPE", message: "not paired" } } },
+  });
+  const rs = await checkOrgConnectivity({ agentRoot: r, fetchImpl: f, env: {} });
+  const mail = rs.find((x) => /Workspace mailbox/.test(x.msg));
+  assert.equal(mail.level, "fail");
+  assert.match(mail.msg, /Settings → API keys/);
+  assert.ok(!/Settings → Email → Mailboxes/.test(mail.msg), "wrong remedy for this cause");
+  rmSync(r, { recursive: true, force: true });
+});
+
+test("probe 4: an unknown error stays a WARN (fail-open on the unclassified)", async () => {
+  const r = root({ orgmail: true });
+  const f = stubFetch({
+    "/api/v1/directory": DIR_OK,
+    "/api/v1/messaging.channels": CHANNELS_OK,
+    "/api/v1/email.inbox": { status: 500, body: { ok: false, error: { code: "INTERNAL", message: "boom" } } },
+  });
+  const rs = await checkOrgConnectivity({ agentRoot: r, fetchImpl: f, env: {} });
+  const mail = rs.find((x) => /mailbox probe inconclusive/.test(x.msg));
   assert.equal(mail.level, "warn");
-  assert.match(mail.msg, /Settings → Email/);
   rmSync(r, { recursive: true, force: true });
 });
 

package/lib/org/email-remedy.mjs

@@ -0,0 +1,49 @@
+/**
+ * lib/org/email-remedy.mjs — one classifier for `email.*` failures, so every
+ * surface tells the operator the same thing.
+ *
+ * Three places learn that a seat's mailbox is broken — the orgmail poll loop,
+ * `maestro doctor`, and the `maestro setup` orgmail section — and before this
+ * they each said something different, all of which described a STATE and none
+ * of which named an ACTOR and an ACT. The live consequence: a seat sat with no
+ * mailbox while its daemon wrote `NOT_FOUND no active mailbox is assigned to
+ * this agent` 478 times in one day. Every word true; nobody told what to do.
+ *
+ * So the remedy text lives here, once, and is imported by all three. Pure, no
+ * side effects, no imports — it is deliberately safe for the setup path to pull
+ * in (importing the adapter would run its `definePlatform` self-registration).
+ *
+ * @module lib/org/email-remedy
+ */
+
+"use strict";
+
+/**
+ * The remedy for a terminal `email.*` failure, in one sentence naming WHO does
+ * WHAT. Returns "" for codes that are transient (retry is the remedy).
+ *
+ * @param {string} code RPC error code
+ * @returns {string}
+ */
+export function remedyFor(code) {
+  switch (code) {
+    case "NOT_FOUND":
+      return (
+        "this seat has NO workspace mailbox, so it can receive no email at all. " +
+        "A workspace ADMIN assigns one at Cohort → Settings → Email → Mailboxes " +
+        "(and first verifies the domain under → Domains if it is not verified yet). " +
+        "Seats paired after 2026-08 get one automatically at pairing approval"
+      );
+    case "FORBIDDEN_SCOPE":
+    case "FORBIDDEN":
+    case "UNAUTHORIZED":
+      return (
+        "this key cannot read email — it is unpaired or lacks the email scope. " +
+        "Run `cohort pair`, or a workspace ADMIN re-mints it at Cohort → Settings → API keys"
+      );
+    default:
+      return "";
+  }
+}
+
+export default { remedyFor };