@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/runtime/child-env.mjs

@@ -0,0 +1,191 @@
+/**
+ * lib/runtime/child-env.mjs — the ONE child-env builder for every runtime spawn.
+ *
+ * Every lane that starts an agent runtime (today the `claude` binary) builds its
+ * child environment here, through `buildRuntimeEnv`. There are two shapes:
+ *
+ *   STOCK     no retarget. The child keeps the seat's own Claude credential
+ *             (`CLAUDE_CODE_OAUTH_TOKEN`, keychain, or a Console key the lane
+ *             owns). Foreign `*_API_KEY` / `*_AUTH_TOKEN` / `*_SECRET` /
+ *             `*_ACCESS_KEY` / `*_PRIVATE_KEY` values are scrubbed (§7.3).
+ *
+ *   RETARGET  the router pointed the session at a third-party backend
+ *             (`ANTHROPIC_BASE_URL` in the retarget set). This is where the old
+ *             builder leaked: its scrub regex ends in `_AUTH_TOKEN$`, which does
+ *             not match `CLAUDE_CODE_OAUTH_TOKEN`, so a Max subscription token
+ *             rode into a child whose base URL was someone else's server. With
+ *             only a base URL set, "a saved claude.ai login remains the active
+ *             credential" — the token would have been sent to that server
+ *             (F1 §5.3). A retarget therefore ALWAYS:
+ *               - scrubs `CLAUDE_CODE_OAUTH_*` and every `*_OAUTH_TOKEN`;
+ *               - scrubs every inherited `ANTHROPIC_*` variable, then injects
+ *                 only the allowlisted retarget keys;
+ *               - refuses (a returned error, never a throw) when the retarget
+ *                 carries no usable `ANTHROPIC_AUTH_TOKEN`, or carries a
+ *                 subscription OAuth token (`sk-ant-oat…`) as that token;
+ *               - forces `ANTHROPIC_API_KEY=""` (no keychain fallthrough) and
+ *                 `CLAUDE_CODE_ATTRIBUTION_HEADER=0` (a third-party prompt cache
+ *                 is poisoned by the per-request attribution header).
+ *
+ * Pure: no process.env read, no clock, no I/O. The caller passes the base env.
+ *
+ * @module lib/runtime/child-env
+ */
+
+"use strict";
+
+/**
+ * Env keys a retarget set may introduce. Everything else in a retarget set is
+ * dropped, so an internal marker (e.g. `__credFingerprint`) can never reach a
+ * child.
+ */
+export const RETARGET_KEYS = Object.freeze(new Set([
+  "ANTHROPIC_BASE_URL",
+  "ANTHROPIC_AUTH_TOKEN",
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_MODEL",
+  "ANTHROPIC_SMALL_FAST_MODEL",
+  "CLAUDE_CODE_ATTRIBUTION_HEADER",
+  "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS",
+  // Slot → model mapping (design §4.7: ANTHROPIC_SMALL_FAST_MODEL is deprecated).
+  "ANTHROPIC_DEFAULT_OPUS_MODEL",
+  "ANTHROPIC_DEFAULT_SONNET_MODEL",
+  "ANTHROPIC_DEFAULT_HAIKU_MODEL",
+  "ANTHROPIC_DEFAULT_FABLE_MODEL",
+  "CLAUDE_CODE_SUBAGENT_MODEL",
+  // The cohort-llm helper credential (see COHORT_HELPER_KEY below).
+  "COHORT_LLM_BASE_URL",
+  "COHORT_LLM_API_KEY_HELPER",
+  "CLAUDE_CODE_API_KEY_HELPER_TTL_MS",
+]));
+
+/**
+ * A cohort-llm retarget authenticates with an `apiKeyHelper` that prints the
+ * seat's short-lived token, not with a static ANTHROPIC_AUTH_TOKEN. Claude Code
+ * ranks ANTHROPIC_AUTH_TOKEN ABOVE apiKeyHelper (code.claude.com/docs/en/iam,
+ * "Authentication precedence"), so a static token would pin the session to a
+ * token that dies after at most an hour. The helper counts as the retarget's
+ * credential only when the retarget names the SAME gateway in
+ * COHORT_LLM_BASE_URL and ANTHROPIC_BASE_URL — a Cohort seat token is never
+ * handed to a third-party base URL. The runtime adapter turns the helper
+ * command into `--settings {"apiKeyHelper": …}`.
+ */
+export const COHORT_HELPER_KEY = "COHORT_LLM_API_KEY_HELPER";
+
+const trimUrl = (u) => (typeof u === "string" ? u.trim().replace(/\/+$/, "") : "");
+
+/** Does this retarget authenticate through the cohort-llm apiKeyHelper? */
+export function isCohortHelperRetarget(retarget) {
+  const set = retarget && typeof retarget === "object" ? retarget : {};
+  const helper = set[COHORT_HELPER_KEY];
+  return isRetarget(set) && typeof helper === "string" && helper.trim() !== "" &&
+    trimUrl(set.COHORT_LLM_BASE_URL) !== "" && trimUrl(set.COHORT_LLM_BASE_URL) === trimUrl(set.ANTHROPIC_BASE_URL);
+}
+
+/** Prefix of a Claude subscription OAuth token (`claude setup-token` output). */
+const SUBSCRIPTION_TOKEN_PREFIX = /^sk-ant-oat/i;
+
+/**
+ * Credential-shaped in EVERY shape (stock and retarget). Unchanged from the
+ * historical §7.3 scrub so the stock path stays byte-compatible: it keeps the
+ * seat's `CLAUDE_CODE_OAUTH_TOKEN`, which a stock Anthropic spawn needs.
+ * @param {string} k
+ */
+export function isCredentialKey(k) {
+  return /(_API_KEY|_AUTH_TOKEN|_SECRET|_ACCESS_KEY|_PRIVATE_KEY)$/i.test(k) || k === "ANTHROPIC_API_KEY";
+}
+
+/**
+ * Additionally scrubbed on a retarget: the Claude subscription credential in
+ * any spelling, and the whole inherited `ANTHROPIC_*` namespace (credentials,
+ * a stale base URL, custom headers) — the retarget set re-injects what the
+ * child actually needs.
+ * @param {string} k
+ */
+export function isRetargetScrubbedKey(k) {
+  return (
+    isCredentialKey(k) ||
+    /^CLAUDE_CODE_OAUTH/i.test(k) ||
+    /_OAUTH_TOKEN$/i.test(k) ||
+    /^ANTHROPIC_/i.test(k) ||
+    /^COHORT_LLM_TOKEN$/i.test(k)
+  );
+}
+
+/** Does a retarget set actually point the child at another backend? */
+export function isRetarget(retarget) {
+  return !!(retarget && typeof retarget === "object" &&
+    typeof retarget.ANTHROPIC_BASE_URL === "string" && retarget.ANTHROPIC_BASE_URL.trim() !== "");
+}
+
+/**
+ * Build a child env.
+ *
+ * @param {object} o
+ * @param {object} o.baseEnv   the parent env to start from (never mutated)
+ * @param {object} [o.retarget] the router's envForSpawn, or {} / null
+ * @param {boolean} [o.keepAnthropicApiKey=false] stock only: keep the parent's
+ *   ANTHROPIC_API_KEY (a Console key the lane owns) instead of scrubbing it
+ * @returns {{ok:true, env:object, retargeting:boolean} |
+ *           {ok:false, error:{code:"retarget_without_token"|"retarget_with_subscription_token", message:string}}}
+ */
+export function buildRuntimeEnv({ baseEnv, retarget = {}, keepAnthropicApiKey = false } = {}) {
+  const src = baseEnv && typeof baseEnv === "object" ? baseEnv : {};
+  const set = retarget && typeof retarget === "object" ? retarget : {};
+  const retargeting = isRetarget(set);
+
+  const viaHelper = retargeting && isCohortHelperRetarget(set);
+  if (retargeting && typeof set[COHORT_HELPER_KEY] === "string" && set[COHORT_HELPER_KEY].trim() !== "" && !viaHelper) {
+    return {
+      ok: false,
+      error: {
+        code: "retarget_helper_mismatch",
+        message: `refusing to retarget to ${set.ANTHROPIC_BASE_URL}: the cohort-llm key helper is only valid for the gateway named in COHORT_LLM_BASE_URL`,
+      },
+    };
+  }
+  if (retargeting && !viaHelper) {
+    const token = set.ANTHROPIC_AUTH_TOKEN;
+    if (typeof token !== "string" || token.trim() === "") {
+      return {
+        ok: false,
+        error: {
+          code: "retarget_without_token",
+          message: `refusing to retarget to ${set.ANTHROPIC_BASE_URL}: no ANTHROPIC_AUTH_TOKEN for that backend (the seat's own Claude credential is never sent to a third party)`,
+        },
+      };
+    }
+    if (SUBSCRIPTION_TOKEN_PREFIX.test(token.trim())) {
+      return {
+        ok: false,
+        error: {
+          code: "retarget_with_subscription_token",
+          message: `refusing to retarget to ${set.ANTHROPIC_BASE_URL}: the token is a Claude subscription OAuth token, which may never be sent to a third-party endpoint`,
+        },
+      };
+    }
+  }
+
+  const out = {};
+  for (const [k, v] of Object.entries(src)) {
+    if (retargeting ? isRetargetScrubbedKey(k) : isCredentialKey(k)) continue;
+    out[k] = v;
+  }
+  if (!retargeting && keepAnthropicApiKey && typeof src.ANTHROPIC_API_KEY === "string") {
+    out.ANTHROPIC_API_KEY = src.ANTHROPIC_API_KEY;
+  }
+  for (const [k, v] of Object.entries(set)) {
+    if (RETARGET_KEYS.has(k)) out[k] = v;
+  }
+  if (retargeting) {
+    // Empty string, NOT unset: an unset key lets Claude Code fall through to a
+    // keychain login against api.anthropic.com.
+    out.ANTHROPIC_API_KEY = "";
+    out.CLAUDE_CODE_ATTRIBUTION_HEADER = "0";
+    // The helper must be the credential in use: a static token would outrank it.
+    if (viaHelper) delete out.ANTHROPIC_AUTH_TOKEN;
+  }
+  return { ok: true, env: out, retargeting, viaHelper };
+}
+
+export default { buildRuntimeEnv, isCredentialKey, isRetargetScrubbedKey, isRetarget, isCohortHelperRetarget, RETARGET_KEYS, COHORT_HELPER_KEY };

package/lib/runtime/legacy-shell-guard.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * lib/runtime/legacy-shell-guard.mjs — the legacy shell lanes are retired for engine-cohort seats (W4-E1, row 36).
+ *
+ * Three shell scripts run the `claude` binary directly, outside the runtime
+ * adapter: scripts/spawn-session.sh, scripts/continuous-monitor.sh and
+ * scripts/local-triggers/run-trigger.sh. They are RETIRED for a seat whose
+ * config/agent.json `runtime.engine` is `cohort`, not ported:
+ *
+ *   - each has a maintained JS successor that already goes through
+ *     `buildSpawn` with the seat's engine — `maestro session spawn` (peers) and
+ *     the dispatcher for spawn-session.sh, the poller + dispatcher for
+ *     continuous-monitor.sh, the cadence bus
+ *     (`scripts/cadence/enqueue-cadence-tick.mjs`) for run-trigger.sh;
+ *   - no daemon lane, generated plist or cadence calls them (doctor already
+ *     flags plists that still call run-trigger.sh);
+ *   - porting them would keep a third spawn path to hold at parity with the
+ *     adapter (argv mapping, credential scrub, send gate, spend cap) for tools
+ *     an operator runs by hand.
+ *
+ * Each script calls this guard first. On an engine-cohort seat the guard
+ * refuses (exit 3, the reason on stderr) — running `claude` there would spend
+ * the seat's Anthropic credential on work the org routed to cohort-llm and
+ * bypass the engine's in-process send gate. On a claude seat it exits 0 and the
+ * script behaves exactly as before. `maestro doctor` warns on engine-cohort
+ * seats that the lanes are retired.
+ *
+ *   node lib/runtime/legacy-shell-guard.mjs <script-name> <agent-root>
+ *
+ * @module lib/runtime/legacy-shell-guard
+ */
+
+"use strict";
+
+import { pathToFileURL } from "node:url";
+import { realpathSync } from "node:fs";
+import { readSeatEngine, SHELL_LEGACY_LANES } from "./adapter.mjs";
+
+/** The exit code a retired lane stops with. */
+export const LEGACY_LANE_REFUSED_EXIT = 3;
+
+/** The successor to use instead of each retired script. */
+export const LEGACY_LANE_SUCCESSORS = Object.freeze({
+  "spawn-session.sh": "maestro session spawn --name <slug> \"<prompt>\" (or let the dispatcher take the work)",
+  "continuous-monitor.sh": "the maestro daemon's pollers and dispatcher",
+  "run-trigger.sh": "node scripts/cadence/enqueue-cadence-tick.mjs <trigger> --source=manual",
+});
+
+/**
+ * May a legacy shell lane run on this seat? PURE.
+ * @param {{engine:string, script:string}} o
+ * @returns {{allowed:true}|{allowed:false, exitCode:number, message:string}}
+ */
+export function legacyShellLaneVerdict({ engine, script }) {
+  if (engine !== "cohort") return { allowed: true };
+  const name = String(script || "").split("/").pop() || "this script";
+  const successor = LEGACY_LANE_SUCCESSORS[name];
+  return {
+    allowed: false,
+    exitCode: LEGACY_LANE_REFUSED_EXIT,
+    message:
+      `${name} is retired on this seat: runtime.engine is "cohort", and this legacy lane runs the claude binary directly, ` +
+      `outside the runtime adapter.${successor ? ` Use ${successor}.` : ""}`,
+  };
+}
+
+/** The retired scripts' names, from the adapter's register. */
+export function legacyLaneNames() {
+  return SHELL_LEGACY_LANES.map((l) => l.path.split("/").pop());
+}
+
+/**
+ * The CLI edge.
+ * @param {string[]} argv  [script, agentRoot]
+ * @param {{readSeatEngine?:(root:string)=>string, stderr?:{write:(s:string)=>void}}} [deps]
+ * @returns {number} exit code
+ */
+export function main(argv, deps = {}) {
+  const [script, agentRoot] = argv;
+  if (!script || !agentRoot) {
+    (deps.stderr || process.stderr).write("usage: legacy-shell-guard.mjs <script-name> <agent-root>\n");
+    return 2;
+  }
+  const v = legacyShellLaneVerdict({ engine: (deps.readSeatEngine || readSeatEngine)(agentRoot), script });
+  if (v.allowed) return 0;
+  (deps.stderr || process.stderr).write(`${v.message}\n`);
+  return v.exitCode;
+}
+
+const isEntry = (() => {
+  try {
+    return process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+})();
+if (isEntry) process.exitCode = main(process.argv.slice(2));

package/lib/runtime/seat-engine.mjs

@@ -0,0 +1,162 @@
+/**
+ * lib/runtime/seat-engine.mjs — which engine a spawn runs, decided once per spawn (W4-E1, CF-44, row 5).
+ *
+ * Every JavaScript site that launches a session — the supervisor's main
+ * session, `maestro session spawn` peers, and the daemon's dispatcher, resume,
+ * cadence, responder, classifier and ack lanes — asks this module ONCE per
+ * spawn for the seat's engine (config/agent.json `runtime.engine`) and spreads
+ * the answer into `buildSpawn`:
+ *
+ *   engine claude  `{}` — the buildSpawn input, and so the argv and env, are
+ *                  byte-for-byte what they were before this module existed.
+ *   engine cohort  `{engine:"cohort", cohortToken, agentRoot}` — the adapter
+ *                  launches the Cohort Engine (`cli.mjs run` for run lanes,
+ *                  `cli.mjs session` for main-session and peer) with the seat
+ *                  token and the token helper, every Claude credential scrubbed.
+ *
+ * Reading the config on every spawn is the rollback: flipping `runtime.engine`
+ * back to `claude` restores the claude binary on the NEXT spawn, with no
+ * restart (design §8.4: "Rollback is one flag flip").
+ *
+ * An engine-cohort seat never falls back to claude. With no seat token the
+ * adapter returns `cohort_token_unavailable` and the lane reports a failure —
+ * running claude instead would spend the seat's Anthropic credential on work
+ * the org routed to cohort-llm.
+ *
+ * The decisions (`seatEngineFields`, `engineRunShape`, `sessionBudgetUsd`) are
+ * pure; `seatTokenSync` / `seatToken` are the edge.
+ *
+ * @module lib/runtime/seat-engine
+ */
+
+"use strict";
+
+import { isRetarget } from "./child-env.mjs";
+import { isCohortRouted, readSeatEngine } from "./adapter.mjs";
+
+/**
+ * The buildSpawn fields for a seat's engine. PURE.
+ * `baseUrl` is the gateway the seat token was minted against (the token
+ * manager's `baseUrl`, from config/org.yaml `llmBaseUrl` or the env): the engine
+ * must talk to the same gateway, never the adapter's default.
+ * @param {{engine:string, agentRoot?:string|null, token?:string|null, baseUrl?:string|null}} o
+ * @returns {{}|{engine:"cohort", cohortToken:string|undefined, agentRoot:string|undefined, cohortBaseUrl?:string}}
+ */
+export function seatEngineFields({ engine, agentRoot = null, token = null, baseUrl = null }) {
+  if (engine !== "cohort") return {};
+  return {
+    engine: "cohort",
+    cohortToken: typeof token === "string" && token ? token : undefined,
+    agentRoot: typeof agentRoot === "string" && agentRoot ? agentRoot : undefined,
+    ...(typeof baseUrl === "string" && baseUrl ? { cohortBaseUrl: baseUrl } : {}),
+  };
+}
+
+/**
+ * What a routed run lane passes for engine cohort. PURE.
+ *
+ * The engine talks to cohort-llm directly, so a router retarget never applies:
+ *   model   the router's flag when the router chose the cohort provider (a
+ *           cohort-* tier), else the lane's own Anthropic slot (sonnet/opus/haiku),
+ *           which the adapter maps to a Cohort tier. A third-party id is never
+ *           handed to the engine.
+ *   knobs   the router's --max-turns/--effort/--agents, unless they were sized for
+ *           a third-party backend (CF-11).
+ *   retarget `{}`.
+ *
+ * @param {{target?:object|null, laneModel?:string|null}} o
+ * @returns {{model:string|null, knobs:object|null, retarget:{}}}
+ */
+export function engineRunShape({ target = null, laneModel = null }) {
+  const t = target && typeof target === "object" ? target : null;
+  const cohortTarget = t ? isCohortRouted({ target: t }) : false;
+  const foreign = t ? !cohortTarget && isRetarget(t.envForSpawn) : false;
+  const model = cohortTarget && t && t.modelFlag ? String(t.modelFlag) : laneModel ? String(laneModel) : null;
+  return { model, knobs: foreign ? null : t, retarget: {} };
+}
+
+/** The smallest per-session cap passed: one model call's worth at most. */
+export const MIN_SESSION_BUDGET_USD = 0.01;
+
+/**
+ * The per-session spend cap for an engine-cohort dispatcher session, from the
+ * seat's funded envelope (budget-guard `dailyAllowance`). PURE.
+ *
+ * A session may not spend more than one day's binding allowance (the lower of
+ * the envelope's share for today and the local cap). No funded envelope → no
+ * cap is invented (null): the budget guard's bands still govern the seat.
+ * An envelope with nothing left today gets {@link MIN_SESSION_BUDGET_USD}.
+ *
+ * @param {{funded?:boolean, allowanceUSD?:number}|null|undefined} allowance
+ * @returns {number|null}
+ */
+export function sessionBudgetUsd(allowance) {
+  if (!allowance || allowance.funded !== true) return null;
+  const usd = Number(allowance.allowanceUSD);
+  if (!Number.isFinite(usd)) return null;
+  const cents = Math.ceil(Math.max(0, usd) * 100) / 100;
+  return Math.max(MIN_SESSION_BUDGET_USD, cents);
+}
+
+// ---------------------------------------------------------------------------
+// Edge: the seat token
+// ---------------------------------------------------------------------------
+
+/**
+ * A usable seat token right now, without a network call (a synchronous spawn
+ * path). null when none is cached.
+ * @param {{peek?:(o:{allowStale:boolean})=>({token?:string}|null)}|null} tokenManager
+ */
+export function seatTokenSync(tokenManager) {
+  try {
+    const t = tokenManager && typeof tokenManager.peek === "function" ? tokenManager.peek({ allowStale: true }) : null;
+    return t && typeof t.token === "string" && t.token ? t.token : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A seat token: the cached one, else minted through the manager. null when the
+ * seat cannot get one (no OrgApiKey, the gateway refuses) — never throws.
+ * @param {{peek?:Function, getToken?:Function}|null} tokenManager
+ * @returns {Promise<string|null>}
+ */
+export async function seatToken(tokenManager) {
+  const cached = seatTokenSync(tokenManager);
+  if (cached) return cached;
+  try {
+    const t = tokenManager && typeof tokenManager.getToken === "function" ? await tokenManager.getToken() : null;
+    return t && t.ok !== false && typeof t.token === "string" && t.token ? t.token : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The seat's engine and its buildSpawn fields, for a lane that may wait for a
+ * token (responder, classifier, ack, the supervisor, `session spawn`). A claude
+ * seat reads config/agent.json and nothing else — no token manager is touched.
+ * Never throws.
+ * @param {string} agentRoot
+ * @param {{readSeatEngine?:(root:string)=>string, tokenManager?:(root:string)=>any}} [deps]
+ * @returns {Promise<{engine:"claude"|"cohort", fields:object}>}
+ */
+export async function resolveSeatSpawn(agentRoot, deps = {}) {
+  let engine = "claude";
+  try {
+    engine = (deps.readSeatEngine || readSeatEngine)(agentRoot) === "cohort" ? "cohort" : "claude";
+  } catch {
+    engine = "claude"; // unreadable config: the default engine, as readSeatEngine answers
+  }
+  if (engine !== "cohort") return { engine, fields: {} };
+  let manager = null;
+  try {
+    manager = deps.tokenManager ? deps.tokenManager(agentRoot) : (await import("../org/llm-token.mjs")).seatTokenManager({ agentRoot });
+  } catch {
+    manager = null; // no seat key: the adapter refuses the spawn (cohort_token_unavailable)
+  }
+  return { engine, fields: seatEngineFields({ engine, agentRoot, token: await seatToken(manager), baseUrl: manager && typeof manager.baseUrl === "string" ? manager.baseUrl : null }) };
+}
+
+export default { seatEngineFields, engineRunShape, sessionBudgetUsd, seatTokenSync, seatToken, resolveSeatSpawn, MIN_SESSION_BUDGET_USD };