@cohortapp/agent-sdk 2.3.0

package/lib/model-router/llm-task.test.mjs

@@ -0,0 +1,392 @@
+/**
+ * lib/model-router/llm-task.test.mjs — the governed cheap one-shot path.
+ *
+ * Drives llmTask with an injected fetchImpl (no network) over a hermetic catalog,
+ * asserting the component-brief contract:
+ *   - routes to the CHEAPEST direct-harness model meeting minGrade;
+ *   - writes ONE ledger row (real writeLedgerRow into a tmp dir);
+ *   - tool-less by construction (no tools[] in the request body);
+ *   - non-Anthropic payloads pass through the injected PII mask (§7.4);
+ *   - HTTP/transport faults classify onto the taxonomy and fail-open (no throw);
+ *   - the kill switch forces an Anthropic direct row;
+ *   - missing credential / open breaker / grade floor are honored.
+ *
+ * House style: node:test, node:assert/strict, hermetic.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, existsSync, readFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { llmTask, pickDirectModel, _internals } from "./llm-task.mjs";
+import { loadCatalog } from "./catalog.mjs";
+import { sumLedgerToday } from "./ledger.mjs";
+
+// ---------------------------------------------------------------------------
+// A hermetic catalog: a cheap grade-B direct row, a cheaper grade-C row, and an
+// anthropic direct row. We inject raw YAML via catalogText so no FS is touched.
+// ---------------------------------------------------------------------------
+
+const CHEAP_YAML = `
+provider: cheapco
+auth_env: CHEAPCO_API_KEY
+endpoints:
+  openai: https://api.cheapco.test
+models:
+  - id: cheap-b
+    status: available
+    context_tokens: 200000
+    cost: { input: 0.20, output: 0.40 }
+    cost_provenance: { source: official, fetched: "2026-06-10", volatile: false }
+    compat: { cache_control: none, max_tokens_field: max_tokens }
+    tool_reliability: B
+    harness: { session: false, direct: true, batch: false }
+  - id: cheap-c
+    status: available
+    context_tokens: 100000
+    cost: { input: 0.05, output: 0.10 }
+    cost_provenance: { source: official, fetched: "2026-06-10", volatile: false }
+    compat: { cache_control: none, max_tokens_field: max_tokens }
+    tool_reliability: C
+    harness: { session: false, direct: true, batch: false }
+`;
+
+const ANTH_YAML = `
+provider: anthropic
+auth_env: ANTHROPIC_API_KEY
+endpoints:
+  anthropic: https://api.anthropic.com
+models:
+  - id: claude-haiku-4-5
+    status: available
+    context_tokens: 200000
+    cost: { input: 1.0, output: 5.0, cache_read: 0.1, cache_write: 1.25 }
+    cost_provenance: { source: official, fetched: "2026-06-10", volatile: false }
+    compat: { cache_control: anthropic }
+    tool_reliability: A
+    harness: { session: true, direct: true, batch: true }
+`;
+
+function hermeticCatalog() {
+  const res = loadCatalog("/tmp/nope", {
+    catalogText: { cheapco: CHEAP_YAML, anthropic: ANTH_YAML },
+  });
+  assert.ok(res.byRef.size >= 3, "catalog parsed three rows");
+  return res;
+}
+
+/** A config that permits cheapco for public data (otherwise deny-default). */
+function publicConfig() {
+  return {
+    schema_version: 2,
+    backends: {
+      anthropic: { allowed_data_classes: ["public", "internal", "sensitive"] },
+      cheapco: { allowed_data_classes: ["public"] },
+    },
+    defaults: { data_class: "public" },
+  };
+}
+
+/** A fake OpenAI-compatible response. */
+function openaiResponse(text, usage = {}) {
+  return {
+    ok: true,
+    status: 200,
+    async json() {
+      return {
+        choices: [{ message: { role: "assistant", content: text } }],
+        usage: { prompt_tokens: usage.in ?? 100, completion_tokens: usage.out ?? 20 },
+      };
+    },
+  };
+}
+
+/** A fake anthropic-messages response. */
+function anthropicResponse(text, usage = {}) {
+  return {
+    ok: true,
+    status: 200,
+    async json() {
+      return {
+        content: [{ type: "text", text }],
+        usage: { input_tokens: usage.in ?? 100, output_tokens: usage.out ?? 20 },
+      };
+    },
+  };
+}
+
+const baseDeps = (over = {}) => ({
+  catalog: hermeticCatalog(),
+  config: publicConfig(),
+  env: { CHEAPCO_API_KEY: "cheap-key", ANTHROPIC_API_KEY: "anth-key" },
+  now: () => 1_700_000_000_000,
+  isOpen: () => ({ open: false, until: 0, reason: null, strikes: 0 }),
+  ...over,
+});
+
+// ---------------------------------------------------------------------------
+// pickDirectModel
+// ---------------------------------------------------------------------------
+
+test("pickDirectModel returns the cheapest qualifying direct row for minGrade C", () => {
+  const catalog = hermeticCatalog();
+  const r = pickDirectModel(catalog, { data_class: "public" }, { ...baseDeps({ catalog }), minGrade: "C" });
+  assert.equal(r.row.ref, "cheapco/cheap-c", "cheapest (C) wins at minGrade C");
+});
+
+test("pickDirectModel skips below-grade rows for minGrade B", () => {
+  const catalog = hermeticCatalog();
+  const r = pickDirectModel(catalog, { data_class: "public" }, { ...baseDeps({ catalog }), minGrade: "B" });
+  assert.equal(r.row.ref, "cheapco/cheap-b", "cheap-c is grade C, excluded; cheap-b wins");
+});
+
+test("pickDirectModel denies cheapco for non-public data_class (deny-default)", () => {
+  const catalog = hermeticCatalog();
+  const r = pickDirectModel(
+    catalog,
+    { data_class: "sensitive" },
+    { ...baseDeps({ catalog }), minGrade: "C" }
+  );
+  // cheapco rows denied → anthropic haiku is the only allowed direct row.
+  assert.equal(r.row.ref, "anthropic/claude-haiku-4-5");
+});
+
+test("pickDirectModel skips a row whose credential is absent", () => {
+  const catalog = hermeticCatalog();
+  const r = pickDirectModel(
+    catalog,
+    { data_class: "public" },
+    { ...baseDeps({ catalog, env: { ANTHROPIC_API_KEY: "anth-key" } }), minGrade: "C" }
+  );
+  // No CHEAPCO_API_KEY → cheapco skipped → anthropic haiku.
+  assert.equal(r.row.ref, "anthropic/claude-haiku-4-5");
+});
+
+test("pickDirectModel skips a row with an open breaker", () => {
+  const catalog = hermeticCatalog();
+  const r = pickDirectModel(catalog, { data_class: "public" }, {
+    ...baseDeps({ catalog }),
+    minGrade: "C",
+    isOpen: (key) => ({ open: key.startsWith("cheapco"), until: 9e15, reason: "rate_limit", strikes: 1 }),
+  });
+  assert.equal(r.row.ref, "anthropic/claude-haiku-4-5", "cheapco breaker open → anthropic");
+});
+
+// ---------------------------------------------------------------------------
+// llmTask happy path
+// ---------------------------------------------------------------------------
+
+test("routes to the cheapest direct model, returns text + usage + estCostUSD, writes a ledger row", async () => {
+  const rows = [];
+  const out = await llmTask("classify this", {
+    ...baseDeps(),
+    minGrade: "C",
+    request: { task_class: "classify.inbox", data_class: "public", agent: "alex" },
+    fetchImpl: async (url, init) => {
+      // tool-less invariant: no tools[] ever sent.
+      const body = JSON.parse(init.body);
+      assert.equal(body.tools, undefined, "no tools[] in the request");
+      assert.match(url, /cheapco/, "cheapest cheapco model selected");
+      return openaiResponse("spam", { in: 80, out: 4 });
+    },
+    writeLedger: (catalog, entry) => rows.push(entry),
+  });
+
+  assert.equal(out.ok, true);
+  assert.equal(out.ref, "cheapco/cheap-c");
+  assert.equal(out.text, "spam");
+  assert.equal(out.usage.inputTokens, 80);
+  assert.equal(out.usage.outputTokens, 4);
+  assert.ok(out.estCostUSD != null);
+  // Exactly one ledger row, joined to the task + harness + exit reason.
+  assert.equal(rows.length, 1);
+  assert.equal(rows[0].ref, "cheapco/cheap-c");
+  assert.equal(rows[0].harness, "direct");
+  assert.equal(rows[0].task_class, "classify.inbox");
+  assert.equal(rows[0].exitReason, "ok");
+  assert.equal(rows[0].agent, "alex");
+});
+
+test("writes a REAL ledger row to state/cost-tracking via writeLedgerRow", async () => {
+  const root = mkdtempSync(join(tmpdir(), "maestro-llmtask-"));
+  mkdirSync(join(root, "state", "cost-tracking"), { recursive: true });
+  try {
+    const out = await llmTask("hi", {
+      ...baseDeps(),
+      minGrade: "C",
+      request: { task_class: "lookup.gmail", data_class: "public" },
+      ledgerDeps: { agentRoot: root, now: () => 1_700_000_000_000 },
+      fetchImpl: async () => openaiResponse("ok", { in: 50, out: 10 }),
+    });
+    assert.equal(out.ok, true);
+    const sum = sumLedgerToday({ agentRoot: root, now: () => 1_700_000_000_000 });
+    assert.equal(sum.sessions, 1, "one ledger row written to disk");
+    assert.ok(sum.spentUSD >= 0);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("non-Anthropic payload passes through the injected PII mask (§7.4)", async () => {
+  let masked = false;
+  let sentBody = null;
+  const out = await llmTask("email me at a@b.com", {
+    ...baseDeps(),
+    minGrade: "C",
+    request: { data_class: "public" },
+    maskInput: (s) => {
+      masked = true;
+      return s.replace(/[\w.]+@[\w.]+/g, "***");
+    },
+    fetchImpl: async (url, init) => {
+      sentBody = JSON.parse(init.body);
+      return openaiResponse("done");
+    },
+    writeLedger: () => {},
+  });
+  assert.equal(out.ok, true);
+  assert.equal(masked, true, "mask invoked for the cheapco (non-anthropic) route");
+  assert.match(sentBody.messages.at(-1).content, /\*\*\*/, "PII masked in the sent prompt");
+  assert.ok(!/a@b\.com/.test(sentBody.messages.at(-1).content));
+});
+
+test("kill switch forces an Anthropic direct row (mask NOT applied)", async () => {
+  let masked = false;
+  let url = null;
+  const out = await llmTask("anything", {
+    ...baseDeps({ env: { CHEAPCO_API_KEY: "k", ANTHROPIC_API_KEY: "a", MAESTRO_ROUTER_FORCE_ANTHROPIC: "1" } }),
+    minGrade: "C",
+    request: { data_class: "public" },
+    maskInput: () => {
+      masked = true;
+      return "x";
+    },
+    fetchImpl: async (u) => {
+      url = u;
+      return anthropicResponse("hello");
+    },
+    writeLedger: () => {},
+  });
+  assert.equal(out.ok, true);
+  assert.equal(out.provider, "anthropic");
+  assert.match(url, /anthropic/);
+  assert.equal(masked, false, "anthropic route is not PII-masked");
+});
+
+// ---------------------------------------------------------------------------
+// fault classification (fail-open, never throws)
+// ---------------------------------------------------------------------------
+
+test("HTTP 429 → rate_limit reason, fail-open (no throw), ledger row written", async () => {
+  const rows = [];
+  const out = await llmTask("x", {
+    ...baseDeps(),
+    minGrade: "C",
+    request: { data_class: "public" },
+    fetchImpl: async () => ({
+      ok: false,
+      status: 429,
+      async json() {
+        return { error: { message: "rate limit exceeded" } };
+      },
+    }),
+    writeLedger: (c, e) => rows.push(e),
+  });
+  assert.equal(out.ok, false);
+  assert.equal(out.reason, "rate_limit");
+  assert.equal(rows.length, 1);
+  assert.equal(rows[0].exitReason, "rate_limit");
+});
+
+test("transport throw → classified network, fail-open", async () => {
+  const out = await llmTask("x", {
+    ...baseDeps(),
+    minGrade: "C",
+    request: { data_class: "public" },
+    fetchImpl: async () => {
+      const e = new Error("getaddrinfo ENOTFOUND api.cheapco.test");
+      e.code = "ENOTFOUND";
+      throw e;
+    },
+    writeLedger: () => {},
+  });
+  assert.equal(out.ok, false);
+  assert.equal(out.reason, "network");
+});
+
+test("2xx with empty content → empty_response soft-fail", async () => {
+  const out = await llmTask("x", {
+    ...baseDeps(),
+    minGrade: "C",
+    request: { data_class: "public" },
+    fetchImpl: async () => openaiResponse("   "),
+    writeLedger: () => {},
+  });
+  assert.equal(out.ok, false);
+  assert.equal(out.reason, "empty_response");
+});
+
+test("no fetchImpl → no_fetch_impl, does not throw", async () => {
+  const out = await llmTask("x", { ...baseDeps(), request: { data_class: "public" } });
+  assert.equal(out.ok, false);
+  assert.equal(out.reason, "no_fetch_impl");
+});
+
+test("no qualifying candidate (no creds anywhere) → no_direct_candidate", async () => {
+  const out = await llmTask("x", {
+    ...baseDeps({ env: {} }),
+    minGrade: "C",
+    request: { data_class: "public" },
+    fetchImpl: async () => openaiResponse("y"),
+  });
+  assert.equal(out.ok, false);
+  assert.ok(["missing_credential", "no_direct_candidate"].includes(out.reason));
+});
+
+test("opts.repair promotes a leaked tool call in the response text", async () => {
+  const out = await llmTask("call the tool", {
+    ...baseDeps(),
+    minGrade: "C",
+    request: { data_class: "public" },
+    repair: true,
+    repairOpts: { idFor: (n) => `id_${n}` },
+    fetchImpl: async () => openaiResponse('```json\n{"name":"do","input":{"k":1}}\n```'),
+    writeLedger: () => {},
+  });
+  assert.equal(out.ok, true);
+  assert.equal(out.repaired, true);
+  assert.equal(out.toolCalls[0].name, "do");
+  assert.deepEqual(out.toolCalls[0].input, { k: 1 });
+});
+
+test("anthropic wire sends x-api-key + anthropic-version, parses content[]", async () => {
+  let headers = null;
+  const out = await llmTask("x", {
+    ...baseDeps(),
+    minGrade: "A", // forces the anthropic grade-A row
+    request: { data_class: "public" },
+    fetchImpl: async (url, init) => {
+      headers = init.headers;
+      assert.match(url, /\/v1\/messages$/);
+      return anthropicResponse("hi", { in: 10, out: 2 });
+    },
+    writeLedger: () => {},
+  });
+  assert.equal(out.ok, true);
+  assert.equal(out.provider, "anthropic");
+  assert.equal(headers["x-api-key"], "anth-key");
+  assert.equal(headers["anthropic-version"], "2023-06-01");
+  assert.equal(out.text, "hi");
+});
+
+test("_internals.wireFor + endpointFor pick the right wire per provider", () => {
+  const catalog = hermeticCatalog();
+  const cheap = catalog.byRef.get("cheapco/cheap-c");
+  const anth = catalog.byRef.get("anthropic/claude-haiku-4-5");
+  assert.equal(_internals.wireFor(cheap), "openai-completions");
+  assert.equal(_internals.wireFor(anth), "anthropic-messages");
+  assert.match(_internals.endpointFor(cheap, "openai-completions"), /cheapco.*chat\/completions/);
+  assert.match(_internals.endpointFor(anth, "anthropic-messages"), /\/v1\/messages$/);
+});

package/lib/model-router/org-credentials.mjs

@@ -0,0 +1,260 @@
+/**
+ * lib/model-router/org-credentials.mjs — make the router CONSUME org credentials.
+ *
+ * THE single-source-of-truth payoff. An org runs 50-100 agents on separate
+ * machines; provisioning a DeepSeek/Kimi/OpenAI key onto every one is
+ * unmanageable and a breach surface. Instead an admin sets each provider key
+ * ONCE in Cohort (credential.put); this module LEASES it short-lived,
+ * role-scoped, and audited (credential.lease) at spawn time — the org key never
+ * persists on the agent machine.
+ *
+ * resolveOrgCredentialEnv({catalog, cfg, roles, fetchImpl, now}) walks the
+ * router catalog's third-party providers; for each one whose `auth_env` is NOT
+ * already set in the local env AND which the org has configured, it leases the
+ * value from Cohort and maps provider → auth_env → value into an `envOverlay`.
+ * The daemon merges that overlay into the spawn child env BEFORE resolveChain
+ * (see the INTEGRATION POINT note below), so the router sees the leased key the
+ * same way it would a locally-provisioned one — and a genuinely missing key still
+ * surfaces as the router's existing `missing_credential`, never as a crash.
+ *
+ * DESIGN INVARIANTS:
+ *   - LOCAL WINS. If `env[auth_env]` is already a non-empty string, we never
+ *     lease that provider (the agent's own key beats the org broker).
+ *   - FAIL-OPEN. Cohort unreachable / disabled / errors ⇒ we return whatever
+ *     local env already has. We NEVER throw and NEVER block a spawn.
+ *   - NEVER PERSIST. Leased plaintext lives ONLY in this process's in-memory
+ *     cache (keyed by provider, expiring at the lease TTL) and in the returned
+ *     overlay the caller merges into the child env. It is NEVER written to disk
+ *     and NEVER logged.
+ *   - CACHE. A successful lease is cached for its TTL; a second resolve within
+ *     the TTL reuses the cached value WITHOUT a second lease call. Expiry
+ *     triggers a re-lease.
+ *
+ * INTEGRATION POINT (one-line follow-up, OUT of this lane's files): the spawn
+ * site (scripts/daemon/* / lib/model-router/spawn.mjs) must, BEFORE calling
+ * resolveChain, do roughly:
+ *     const { envOverlay } = await resolveOrgCredentialEnv({ catalog, cfg, roles });
+ *     childEnv = { ...childEnv, ...envOverlay };   // leased keys, local-wins already applied
+ * resolveChain then reads childEnv[row.auth_env] exactly as today.
+ *
+ * Node builtins only. ESM. Pure-core + injectable IO (fetchImpl, env, now, a
+ * private cache) so tests are deterministic and never touch the network.
+ *
+ * @module lib/model-router/org-credentials
+ */
+
+"use strict";
+
+import { credentialLease, isEnabled, configFromAgent } from "../org/client.mjs";
+
+/** Providers that ride the stock claude CLI / keychain OAuth — never brokered. */
+const NEVER_BROKER = new Set(["anthropic"]);
+
+/** Default lease TTL (ms) when the server's response omits one. 15 minutes. */
+const DEFAULT_LEASE_TTL_MS = 15 * 60 * 1000;
+
+/**
+ * Process-lifetime in-memory cache of leased credentials, keyed by provider.
+ * Value: { authEnv, value, expiresAtMs }. NEVER serialised to disk. A module
+ * singleton so successive spawns within a TTL share one lease; tests inject
+ * their own cache via opts.cache for isolation.
+ * @type {Map<string,{authEnv:string,value:string,expiresAtMs:number}>}
+ */
+const GLOBAL_CACHE = new Map();
+
+/**
+ * Enumerate the catalog's third-party providers and their auth_env. Accepts the
+ * loadCatalog result OR a bare catalog ({providers} Map / providers array /
+ * models array) — tolerant because the caller passes whatever it has on hand.
+ * Returns a de-duped list of { provider, authEnv }; providers we never broker
+ * (anthropic) and rows without an auth_env are dropped.
+ * @param {object} catalog
+ * @returns {{provider:string, authEnv:string}[]}
+ */
+function thirdPartyProviders(catalog) {
+  // Unwrap a loadCatalog result ({catalog, models, byRef}) to the bare catalog:
+  // prefer a top-level that actually carries a providers Map or non-empty models,
+  // else fall through to the nested `.catalog`. (An empty `models:[]` on the
+  // wrapper must NOT mask the real catalog underneath.)
+  let cat = catalog;
+  if (catalog && typeof catalog === "object") {
+    const topHasProviders = !!catalog.providers;
+    const topHasModels = Array.isArray(catalog.models) && catalog.models.length > 0;
+    if (!topHasProviders && !topHasModels && catalog.catalog) cat = catalog.catalog;
+  }
+  const out = new Map(); // provider -> authEnv (first non-null wins)
+
+  const consider = (provider, authEnv) => {
+    const p = typeof provider === "string" ? provider.trim() : "";
+    const a = typeof authEnv === "string" ? authEnv.trim() : "";
+    if (!p || !a) return;
+    if (NEVER_BROKER.has(p)) return;
+    if (!out.has(p)) out.set(p, a);
+  };
+
+  // Preferred source: the providers map (provider -> { auth_env, ... }).
+  const providers = cat && cat.providers;
+  if (providers && typeof providers.forEach === "function" && !(providers instanceof Array)) {
+    // Map<string, {auth_env}>
+    providers.forEach((meta, provider) => consider(provider, meta && meta.auth_env));
+  } else if (Array.isArray(providers)) {
+    for (const meta of providers) consider(meta && meta.provider, meta && meta.auth_env);
+  }
+
+  // Fallback / supplement: model rows each carry provider + auth_env.
+  const models = (cat && cat.models) || [];
+  if (Array.isArray(models)) {
+    for (const row of models) consider(row && row.provider, row && row.auth_env);
+  }
+
+  return [...out.entries()].map(([provider, authEnv]) => ({ provider, authEnv }));
+}
+
+/**
+ * Is a local env var already a usable (non-empty) credential? Local wins, so
+ * such a provider is NEVER leased.
+ * @param {object} env @param {string} authEnv @returns {boolean}
+ */
+function localHas(env, authEnv) {
+  const v = env && env[authEnv];
+  return typeof v === "string" && v.trim() !== "";
+}
+
+/**
+ * Extract the leased value + TTL from a credential.lease res frame, tolerant of
+ * where the server lands the fields (result.value | result.credential.value;
+ * ttlMs | ttl_ms | expiresAt). Returns null when there's no usable plaintext.
+ * @param {object} frame res frame {ok,result}
+ * @param {number} nowMs
+ * @returns {{value:string, expiresAtMs:number}|null}
+ */
+function parseLease(frame, nowMs) {
+  if (!frame || frame.ok !== true) return null;
+  const r = frame.result || {};
+  const inner = (r.credential && typeof r.credential === "object") ? r.credential : r;
+  const value = inner.value;
+  if (typeof value !== "string" || value === "") return null;
+
+  // Derive expiry: explicit expiresAt wins; else now + ttlMs; else default.
+  let expiresAtMs;
+  const exp = inner.expiresAt != null ? inner.expiresAt : r.expiresAt;
+  const ttl = pickTtlMs(inner, r);
+  const parsed = exp != null ? Date.parse(String(exp)) : NaN;
+  if (Number.isFinite(parsed)) expiresAtMs = parsed;
+  else if (Number.isFinite(ttl) && ttl > 0) expiresAtMs = nowMs + ttl;
+  else expiresAtMs = nowMs + DEFAULT_LEASE_TTL_MS;
+
+  return { value, expiresAtMs };
+}
+
+function pickTtlMs(inner, r) {
+  for (const v of [inner.ttlMs, inner.ttl_ms, r.ttlMs, r.ttl_ms]) {
+    const n = Number(v);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return NaN;
+}
+
+/**
+ * Resolve org-brokered third-party credentials into an env overlay the spawn
+ * site merges into the child env BEFORE resolveChain.
+ *
+ * For each third-party provider in the catalog whose `auth_env` is NOT already
+ * set in the local env: serve it from the in-memory cache if a non-expired lease
+ * exists, else lease it from Cohort (credential.lease) and cache the value at
+ * its TTL. Providers the org hasn't configured (lease ⇒ NOT_FOUND / error frame)
+ * are recorded in `errors` and simply omitted from the overlay — the router then
+ * skips that backend with its existing `missing_credential`, exactly as if no
+ * key were provisioned. Local-set providers are never leased (local wins).
+ *
+ * Fail-open everywhere: a disabled org plane or an unreachable Cohort yields an
+ * empty overlay (or whatever the cache already holds) and never throws.
+ *
+ * @param {object} args
+ *   @param {object}      args.catalog    loadCatalog result OR a bare catalog
+ *   @param {object}      args.cfg        agent config (org.cohort.* drives the client)
+ *   @param {string[]}    [args.roles]    the agent's roles (informational; scope is
+ *                                        enforced server-side from the verified token)
+ *   @param {object}      [args.env]      env to read local keys from (default process.env)
+ *   @param {function}    [args.fetchImpl] injected fetch (tests / determinism)
+ *   @param {()=>number}  [args.now]      clock (default Date.now)
+ *   @param {Map}         [args.cache]    injectable cache (default the module singleton)
+ * @returns {Promise<{envOverlay:Object<string,string>, leased:string[], errors:Array<{provider:string,reason:string}>}>}
+ */
+export async function resolveOrgCredentialEnv(args = {}) {
+  const catalog = args.catalog;
+  const cfg = args.cfg;
+  const env = args.env || process.env;
+  const fetchImpl = args.fetchImpl;
+  const nowFn = typeof args.now === "function" ? args.now : Date.now;
+  const cache = args.cache instanceof Map ? args.cache : GLOBAL_CACHE;
+
+  const envOverlay = {};
+  const leased = [];
+  const errors = [];
+
+  // Fail-open: org plane disabled or unconfigured ⇒ nothing to broker, return
+  // an empty overlay so the router falls through to whatever local env has.
+  if (!isEnabled(cfg)) {
+    return { envOverlay, leased, errors };
+  }
+
+  const conn = configFromAgent(cfg);
+  const o = { base: conn.base, token: conn.token, fetchImpl };
+
+  const providers = thirdPartyProviders(catalog);
+  if (providers.length === 0) {
+    return { envOverlay, leased, errors };
+  }
+
+  const nowMs = nowFn();
+
+  for (const { provider, authEnv } of providers) {
+    // LOCAL WINS — never lease a provider whose key the agent already holds.
+    if (localHas(env, authEnv)) continue;
+
+    // CACHE — reuse a non-expired lease without a second credential.lease call.
+    const cached = cache.get(provider);
+    if (cached && cached.value && cached.expiresAtMs > nowMs) {
+      envOverlay[cached.authEnv || authEnv] = cached.value;
+      leased.push(provider);
+      continue;
+    }
+    if (cached && cached.expiresAtMs <= nowMs) cache.delete(provider); // expired
+
+    // LEASE — short-lived, role-scoped, audited. Fail-open per provider: an
+    // error frame (provider not configured / Cohort down / FORBIDDEN_SCOPE)
+    // is recorded and the provider is left out of the overlay.
+    let frame;
+    try {
+      frame = await credentialLease({ provider }, o);
+    } catch {
+      // The client is fail-open and shouldn't throw, but belt-and-braces: a
+      // thrown fetchImpl must never crash the spawn path.
+      frame = null;
+    }
+
+    const parsed = parseLease(frame, nowMs);
+    if (!parsed) {
+      const reason =
+        (frame && frame.error && frame.error.code) ||
+        (frame && frame.ok === false ? "lease_failed" : "unreachable");
+      errors.push({ provider, reason: String(reason) });
+      continue;
+    }
+
+    cache.set(provider, { authEnv, value: parsed.value, expiresAtMs: parsed.expiresAtMs });
+    envOverlay[authEnv] = parsed.value;
+    leased.push(provider);
+  }
+
+  return { envOverlay, leased, errors };
+}
+
+/**
+ * Clear the module-singleton lease cache (test hygiene / forced re-lease, e.g.
+ * after a credential.revoke). Does NOT touch an injected cache.
+ */
+export function clearOrgCredentialCache() {
+  GLOBAL_CACHE.clear();
+}