@botbuddy/cli 1.33.8 → 1.33.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.33.8",
+  "version": "1.33.10",
   "description": "BotBuddy — Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {

package/src/agent-doctor.mjs

@@ -67,7 +67,13 @@ function prerequisiteRecovery(report) {
  * credential-store failure must point at unlocking the store — not `bb login` or a
  * binding repair — matching prerequisiteRecovery's wording.
  */
-function repairFailureRecovery(code) {
+function repairFailureRecovery(code, error = null) {
+  // BOT-1891: a tier-2 MCP key the server rejected (revoked/rotated) is replaced by
+  // minting a new one and re-delivering it — not by `bb login`, which a Background
+  // job cannot run anyway. Name the variable, never the value.
+  if (code === "session_mint_unauthorized" && error?.mintedWith === "mcp_key") {
+    return `the tier-2 MCP key in ${error.mcpEnv ?? "the binding's mcp_env"} was rejected (revoked?); mint a new one, store it in Keychain under that name, then re-run \`bash scripts/install-stack-canary.sh\` (or re-export it) and \`bb doctor --fix\``;
+  }
   if (code === "client_key_unavailable") {
     return "the client key could not be read (locked or failing credential store); unlock it, then run `bb doctor --fix`";
   }
@@ -120,11 +126,17 @@ export async function doctorAgentAuth({
   ]);
   try { owner = await ownerToken(); } catch { ownerReadFailed = true; }
   const fresh = Boolean(state && isFresh(state, new Date()));
+  // BOT-1891: whether the binding's tier-2 MCP key is in THIS process's env — the
+  // self-heal fallback when the owner token is unreachable (a Background
+  // LaunchAgent). Env only, exactly like selfHealAgentSession; never the value.
+  const mcpEnv = typeof bound?.mcpEnv === "string" && bound.mcpEnv ? bound.mcpEnv : null;
+  const mcpKeyInEnv = Boolean(mcpEnv && typeof env?.[mcpEnv] === "string" && env[mcpEnv]);
   const report = {
     schema_version: 1,
     worktree: cwd,
     binding: bound?.tenant ? { status: "available", tenant: bound.tenant } : { status: "missing" },
     client_key: clientKeyStatus(owner, now(), ownerReadFailed),
+    ...(mcpEnv ? { mcp_key: { env: mcpEnv, in_env: mcpKeyInEnv } } : {}),
     session: fresh
       ? { status: "fresh", agent_id: state.agent_id, session_id: state.session_id, expires_at: state.expires_at }
       : { status: state ? "stale" : "missing" },
@@ -147,14 +159,28 @@ export async function doctorAgentAuth({
   // `bb doctor --fix` (the remedy the stack refusal points at) would reuse a fresh but
   // never-attested session and never re-establish the capability. `force` makes the
   // self-heal run a registration/attestation round regardless of cache freshness.
-  if (fix && report.binding.status === "available" && report.client_key.status === "available") {
+  // BOT-1891: an UNREADABLE client key (a Background LaunchAgent cannot reach the
+  // login Keychain) is repairable when the binding's tier-2 MCP key is in the env —
+  // selfHeal mints with it. A missing or expired key keeps its `bb login` verdict.
+  const mintCredentialAvailable = report.client_key.status === "available"
+    || (mcpKeyInEnv && report.client_key.status === "unavailable");
+  if (fix && report.binding.status === "available" && mintCredentialAvailable) {
     try {
       credential = await selfHeal({ cwd, env, force: true });
-      report.session = { status: credential.source === "minted" ? "minted" : credential.source, agent_id: credential.agentId ?? null, session_id: credential.sessionId ?? null };
+      report.session = {
+        status: credential.source === "minted" ? "minted" : credential.source,
+        agent_id: credential.agentId ?? null,
+        session_id: credential.sessionId ?? null,
+        ...(credential.mintedWith ? { minted_with: credential.mintedWith } : {}),
+      };
       applyStackLeaseCapability(report, credential.stackLeaseCapability);
     } catch (error) {
-      report.session = { status: "repair_failed", error: error?.code ?? "agent_session_unavailable" };
-      report.recovery = repairFailureRecovery(error?.code);
+      report.session = {
+        status: "repair_failed",
+        error: error?.code ?? "agent_session_unavailable",
+        ...(error?.mintedWith ? { minted_with: error.mintedWith } : {}),
+      };
+      report.recovery = repairFailureRecovery(error?.code, error);
       return { exitCode: 3, report, exports: null };
     }
   }
@@ -173,7 +199,7 @@ export async function doctorAgentAuth({
   // cached session left `credential` populated, report THAT prerequisite — not the
   // Helper/capability message below, since registration never ran and the real remedy
   // is `bb login` or restoring the binding.
-  if (fix && (report.binding.status !== "available" || report.client_key.status !== "available")) {
+  if (fix && (report.binding.status !== "available" || !mintCredentialAvailable)) {
     report.recovery = prerequisiteRecovery(report) ?? "run `bb doctor --fix` to mint a replacement session";
     return { exitCode: 3, report, exports };
   }
@@ -194,5 +220,5 @@ export async function doctorAgentAuth({
 }
 
 export function doctorHelp() {
-  return "bb doctor [--fix] [--print-exports] [--json]\n\nChecks the client key, repo binding, cached agent session, and this worktree's stack-lease capability (registered host + attested machine). --fix mints a replacement session and (re)establishes the stack-lease capability; --print-exports prints its canonical shell exports.";
+  return "bb doctor [--fix] [--print-exports] [--json]\n\nChecks the client key, repo binding, cached agent session, and this worktree's stack-lease capability (registered host + attested machine). --fix mints a replacement session and (re)establishes the stack-lease capability; --print-exports prints its canonical shell exports. When the client key is unreachable (a Background LaunchAgent cannot read the login Keychain), --fix mints from the tier-2 MCP key exported under the binding's mcp_env name (env only, never Keychain).";
 }

package/src/api.mjs

@@ -1,6 +1,10 @@
 import { getConfig, SERVER_URL } from "./config.mjs";
 import { resolveOwnerToken, resolveAgentKey } from "./cli-credentials.mjs";
 import { readAgentBinding } from "./wait-profile.mjs";
+import { AGENT_KEY_RE } from "./agent-key.mjs";
+// BOT-1864: api.mjs ↔ agent-session.mjs is a deliberate import cycle — each side
+// only CALLS the other's functions at request time, never at module evaluation.
+import { resolveAgentSessionCredential } from "./agent-session.mjs";
 import { die, cyan, dim, yellow, prettyJson } from "./utils.mjs";
 
 // Same slug shape the server accepts on `?tenant=`.
@@ -51,41 +55,80 @@ async function genericEndpoint({ tenant = null, resolvePin = resolveDefaultTenan
 // BOT-1520: auth headers come from the Keychain, never a plaintext config.json
 // secret. The owner OAuth token (from `botbuddy login`) is preferred; the
 // tenant-bound agent key (from `botbuddy profile setup`) is the fallback.
-async function authHeader() {
-  const owner = await resolveOwnerToken({ getConfig });
-  if (owner) {
-    if (owner.expiresAt && Date.now() >= owner.expiresAt) {
-      const agentKey = await resolveAgentKey();
-      if (agentKey) return { "x-agent-api-key": agentKey };
-      die(`Token expired. Run: ${cyan("botbuddy login")} to re-authenticate.`);
-    }
-    if (owner.expiresAt && owner.expiresAt - Date.now() < 5 * 60 * 1000) {
+// BOT-1864: the generic commands (`bb call`, resources, heartbeat/locks/tasks)
+// first honour this worktree's tier-3 session — see resolveCallAuth.
+async function authHeader(toolName = null, { resolveAuth = resolveCallAuth } = {}) {
+  const resolved = await resolveAuth({ toolName, preferSession: true });
+  if (resolved.auth) {
+    const expiresAt = resolved.ownerExpiresAt ?? null;
+    if (expiresAt && expiresAt - Date.now() < 5 * 60 * 1000) {
       console.error(`${yellow("⚠")} Token expires in <5 minutes. Run ${cyan("botbuddy login")} soon.`);
     }
-    return { Authorization: `Bearer ${owner.token}` };
+    return resolved;
+  }
+  const code = resolved.error?.error;
+  if (code === "token_expired") die(`Token expired. Run: ${cyan("botbuddy login")} to re-authenticate.`);
+  if (code === "session_token_malformed") {
+    die(`The agent session token has an unexpected shape (source: ${resolved.error.source ?? "unknown"}). Run: ${cyan("bb doctor --fix")} in this checkout.`);
   }
-  const agentKey = await resolveAgentKey();
-  if (agentKey) return { "x-agent-api-key": agentKey };
   die(`Not authenticated. Run: ${cyan("botbuddy login")}`);
 }
 
-export async function callTool(toolName, args = {}, { fetchImpl = fetch, auth = null, tenant = null, resolvePin = resolveDefaultTenantPin, log = (line) => console.log(line) } = {}) {
-  const headers = { "Content-Type": "application/json", ...(auth ?? await authHeader()) };
+// BOT-1864: a cached session the server rejects (revoked by a concurrent
+// re-register, or expired server-side while locally fresh) must not strand a
+// `bb call` that worked before this change — retry ONCE with the durable
+// owner/MCP-key credential. An exported/flag token belongs to the caller and is
+// never silently swapped; a tenant refusal (-32002) is a typed verdict another
+// credential cannot fix.
+function isRejectedCachedSessionResponse(resolved, status, payload) {
+  if (resolved?.source !== "cache") return false;
+  const rpcCode = payload?.error?.code;
+  if (rpcCode === -32002) return false;
+  return status === 401 || status === 403 || rpcCode === -32001;
+}
+
+const SESSION_SOURCES = new Set(["cache", "env", "flag"]);
+
+// A session token is tenant-bound: never DERIVE a pin for it (a differing
+// derived pin would be a spurious conflict). An explicit --pin is still sent —
+// the server lets a pin confirm the session's tenant, never repoint it.
+async function requestEndpoint(resolved, { tenant, resolvePin }) {
+  return SESSION_SOURCES.has(resolved?.source) ? toolEndpoint(tenant) : genericEndpoint({ tenant, resolvePin });
+}
+
+export async function callTool(toolName, args = {}, { fetchImpl = fetch, auth = null, tenant = null, resolvePin = resolveDefaultTenantPin, resolveAuth = resolveCallAuth, log = (line) => console.log(line) } = {}) {
   const body = {
     jsonrpc: "2.0",
     id: 1,
     method: "tools/call",
     params: { name: toolName, arguments: args },
   };
+  const send = async (resolved) => {
+    const headers = { "Content-Type": "application/json", ...resolved.auth };
+    const res = await fetchImpl(await requestEndpoint(resolved, { tenant, resolvePin }), { method: "POST", headers, body: JSON.stringify(body) });
+    return { status: res.status, data: await res.json() };
+  };
 
-  const res = await fetchImpl(await genericEndpoint({ tenant, resolvePin }), { method: "POST", headers, body: JSON.stringify(body) });
-  const data = await res.json();
+  const first = auth ? { auth, source: null } : await authHeader(toolName, { resolveAuth });
+  let { status, data } = await send(first);
+  let staleSession = false;
+  if (!auth && isRejectedCachedSessionResponse(first, status, data)) {
+    const durable = await resolveAuth({ toolName, preferSession: false });
+    if (durable.auth) ({ status, data } = await send(durable));
+    else staleSession = true;
+  }
+  const exportedRejected = !auth && (first.source === "env" || first.source === "flag")
+    && (status === 401 || status === 403 || data?.error?.code === -32001);
 
   if (data.error?.message) {
     const code = data.error?.data?.code;
     const hint = code === "MCP_TENANT_PIN_REQUIRED"
       ? ` Pin a tenant: ${cyan("botbuddy call <tool> --pin <slug>")}, ${cyan("BOTBUDDY_TENANT=<slug>")}, or run from a repo with ${dim(".botbuddy-agent.json")}.`
-      : "";
+      : staleSession
+        ? ` The cached agent session in this checkout was rejected; run ${cyan("bb doctor --fix")} here.`
+        : exportedRejected
+          ? ` The exported agent session token was rejected; unset ${cyan("BOTBUDDY_AGENT_SESSION_TOKEN")} (and its legacy aliases) to use this checkout's session or your login.`
+          : "";
     die(`Server error: ${data.error.message}${hint}`);
   }
 
@@ -112,17 +155,63 @@ export async function callTool(toolName, args = {}, { fetchImpl = fetch, auth =
 // bound tenant mid-sequence (a TOCTOU that would register in the wrong tenant).
 // Returns { auth } with the header object, or { error } with the structured
 // not-authenticated / token-expired receipt to return verbatim.
-export async function resolveCallAuth() {
-  const owner = await resolveOwnerToken({ getConfig });
+//
+// BOT-1864: `preferSession` routes the call through the SAME shared resolver
+// `bb wait` / `bb stack` use (resolveAgentSessionCredential: exported
+// BOTBUDDY_AGENT_SESSION_TOKEN → this worktree's fresh 0600
+// `.botbuddy/agent-state.json`) BEFORE the Keychain-backed owner/MCP-key path.
+// That cache is the only credential a `user/<uid>` Background LaunchAgent (the
+// BOT-1751 stack canary) can reach — the login Keychain is not. It never
+// self-heals here: minting a session needs the Keychain client key (unreachable
+// in exactly the job this exists for), and a register_agent side effect on every
+// `bb call` would be wrong; a missing/stale cache falls through to the durable
+// path exactly as before. Opt-in, because the programmatic callers (setup,
+// bootstrap, mcp-key, telemetry attestation) deliberately act as the durable
+// principal. Identity-minting tools the server refuses for a session token never
+// ride it (SESSION_TOKEN_DENIED_TOOLS).
+export async function resolveCallAuth({
+  toolName = null,
+  preferSession = false,
+  env = process.env,
+  cwd = process.cwd(),
+  resolveSession = (opts) => resolveAgentSessionCredential({ ...opts, selfHeal: async () => null }),
+  resolveOwner = () => resolveOwnerToken({ getConfig }),
+  resolveAgentKeyFn = resolveAgentKey,
+} = {}) {
+  if (preferSession && !(toolName && SESSION_TOKEN_DENIED_TOOLS.has(toolName))) {
+    const session = await resolveSession({ argv: [], env, cwd });
+    if (session?.token) {
+      // Fail closed on a malformed token rather than silently switching to the
+      // owner principal (the stackAuthHeader rule, BOT-1750 R3).
+      if (typeof session.token !== "string" || !AGENT_KEY_RE.test(session.token)) {
+        return { error: { ok: false, auth: true, error: "session_token_malformed", source: session.source ?? null } };
+      }
+      return { auth: { "x-agent-api-key": session.token }, source: session.source ?? null };
+    }
+  }
+  const owner = await resolveOwner();
   if (owner && !(owner.expiresAt && Date.now() >= owner.expiresAt)) {
-    return { auth: { Authorization: `Bearer ${owner.token}` } };
+    return { auth: { Authorization: `Bearer ${owner.token}` }, source: "owner", ownerExpiresAt: owner.expiresAt ?? null };
   }
-  const agentKey = await resolveAgentKey();
-  if (agentKey) return { auth: { "x-agent-api-key": agentKey } };
+  const agentKey = await resolveAgentKeyFn();
+  if (agentKey) return { auth: { "x-agent-api-key": agentKey }, source: "mcp_key" };
   if (owner) return { error: { ok: false, auth: true, error: "token_expired" } };
   return { error: { ok: false, auth: true, error: "not_authenticated" } };
 }
 
+// BOT-1864: client mirror of the MCP server's SESSION_TOKEN_DENIED_TOOLS
+// (supabase/functions/mcp-server/index.ts, BOT-1649 AC-4). The server refuses a
+// session token for these, so `bb call <one of them>` keeps the durable
+// credential. bot1864-call-session-auth.test.mjs pins the two lists equal.
+export const SESSION_TOKEN_DENIED_TOOLS = new Set([
+  "register_agent",
+  "bootstrap_agent_session",
+  "create_service_account",
+  "mint_mcp_key",
+  "revoke_mcp_key",
+  "create_direct_chat",
+]);
+
 // BOT-1561: a multi-membership owner credential is tenant-ambiguous without an
 // explicit pin — the server (mcpSessionIdentity, BOT-1521) fails closed, so
 // stateless REST tools/call like whoami return no tenant_id. `tenant` pins the
@@ -189,17 +278,19 @@ export async function callToolJson(toolName, args = {}, { fetchImpl = fetch, sig
 }
 
 export async function listResources({ fetchImpl = fetch, auth = null, tenant = null, resolvePin = resolveDefaultTenantPin, log = (line) => console.log(line) } = {}) {
-  const headers = { "Content-Type": "application/json", ...(auth ?? await authHeader()) };
+  const resolved = auth ? { auth, source: null } : await authHeader();
+  const headers = { "Content-Type": "application/json", ...resolved.auth };
   const body = { jsonrpc: "2.0", id: 1, method: "resources/list", params: {} };
-  const res = await fetchImpl(await genericEndpoint({ tenant, resolvePin }), { method: "POST", headers, body: JSON.stringify(body) });
+  const res = await fetchImpl(await requestEndpoint(resolved, { tenant, resolvePin }), { method: "POST", headers, body: JSON.stringify(body) });
   const data = await res.json();
   log(JSON.stringify(data.result?.resources ?? data.result ?? data, null, 2));
 }
 
 export async function readResource(uri, { fetchImpl = fetch, auth = null, tenant = null, resolvePin = resolveDefaultTenantPin, log = (line) => console.log(line) } = {}) {
-  const headers = { "Content-Type": "application/json", ...(auth ?? await authHeader()) };
+  const resolved = auth ? { auth, source: null } : await authHeader();
+  const headers = { "Content-Type": "application/json", ...resolved.auth };
   const body = { jsonrpc: "2.0", id: 1, method: "resources/read", params: { uri } };
-  const res = await fetchImpl(await genericEndpoint({ tenant, resolvePin }), { method: "POST", headers, body: JSON.stringify(body) });
+  const res = await fetchImpl(await requestEndpoint(resolved, { tenant, resolvePin }), { method: "POST", headers, body: JSON.stringify(body) });
   const data = await res.json();
   const text = data.result?.contents?.[0]?.text;
   if (text) {

package/src/commands.mjs

@@ -226,7 +226,8 @@ export async function cmdDoctor(args, { log = (line) => console.log(line), error
   } else {
     log(`binding: ${result.report.binding.status}${result.report.binding.tenant ? ` (${result.report.binding.tenant})` : ""}`);
     log(`client key: ${result.report.client_key.status}`);
-    log(`agent session: ${result.report.session.status}`);
+    if (result.report.mcp_key) log(`mcp key: ${result.report.mcp_key.env} ${result.report.mcp_key.in_env ? "in env" : "not in env"}`);
+    log(`agent session: ${result.report.session.status}${result.report.session.minted_with ? ` (minted_with: ${result.report.session.minted_with})` : ""}`);
     if (result.report.stack_lease) {
       const sl = result.report.stack_lease;
       log(`stack lease: ${sl.capability} (host ${sl.host}, machine id ${sl.machine_id_readable ? "readable" : "unavailable"})${sl.reason ? ` — ${sl.reason}` : ""}`);