@botbuddy/cli 1.33.11 → 1.34.0

package/package.json

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

package/src/api.mjs

@@ -5,7 +5,7 @@ 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";
+import { die, red, cyan, dim, yellow, prettyJson } from "./utils.mjs";
 
 // Same slug shape the server accepts on `?tenant=`.
 const TENANT_PIN_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
@@ -57,7 +57,7 @@ async function genericEndpoint({ tenant = null, resolvePin = resolveDefaultTenan
 // tenant-bound agent key (from `botbuddy profile setup`) is the fallback.
 // 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 } = {}) {
+async function authHeader(toolName = null, { resolveAuth = resolveCallAuth, exitCode = 1 } = {}) {
   const resolved = await resolveAuth({ toolName, preferSession: true });
   if (resolved.auth) {
     const expiresAt = resolved.ownerExpiresAt ?? null;
@@ -66,12 +66,15 @@ async function authHeader(toolName = null, { resolveAuth = resolveCallAuth } = {
     }
     return resolved;
   }
+  // BOT-1896: a missing/expired local credential is auth-class — callTool passes
+  // CALL_EXIT.AUTH so it never collapses into the generic exit 1.
+  const fail = (msg) => { console.error(`${red("✗")} ${msg}`); process.exit(exitCode); };
   const code = resolved.error?.error;
-  if (code === "token_expired") die(`Token expired. Run: ${cyan("botbuddy login")} to re-authenticate.`);
+  if (code === "token_expired") fail(`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.`);
+    fail(`The agent session token has an unexpected shape (source: ${resolved.error.source ?? "unknown"}). Run: ${cyan("bb doctor --fix")} in this checkout.`);
   }
-  die(`Not authenticated. Run: ${cyan("botbuddy login")}`);
+  fail(`Not authenticated. Run: ${cyan("botbuddy login")}`);
 }
 
 // BOT-1864: a cached session the server rejects (revoked by a concurrent
@@ -96,39 +99,200 @@ 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) } = {}) {
+// BOT-1896: `botbuddy call` (and every command riding callTool) exits with a
+// code that tells a tenant gate WHY it failed: AUTH when BotBuddy refused the
+// credential (fail closed), TRANSPORT when BotBuddy could not be reached or
+// answered with a gateway/5xx failure (the only case that may degrade to a
+// local-only lock). The values reuse `botbuddy stack`'s EXIT table (stack.mjs:
+// AUTH 3, BACKEND 5) — restated rather than imported because stack.mjs imports
+// this module; bot1896-call-auth-exit.test.mjs pins them equal.
+// ERROR (1) is the generic failure: a reachable server said something other than
+// "ok" or "auth" (a proxy 404, a 429 page, …). A gate must fail closed on it —
+// only TRANSPORT licenses a local-only fallback.
+export const CALL_EXIT = Object.freeze({ OK: 0, ERROR: 1, AUTH: 3, TRANSPORT: 5 });
+
+// BOT-1896: mirror of the server's AUTH_CLASS_ERROR_CODES
+// (supabase/functions/_shared/lib/authDenial.ts), used when an older server
+// sends a typed code without `error_class`. Pinned equal by the same test.
+export const CALL_AUTH_ERROR_CODES = new Set([
+  "scope_denied",
+  "session_token_revoked",
+  "session_token_expired",
+  "session_token_scope",
+  "credential_unknown",
+  "credential_missing",
+  "MCP_REAUTH_TENANT_REQUIRED",
+  "MCP_TENANT_PIN_REQUIRED",
+  "MCP_TENANT_SESSION_MISMATCH",
+  "MCP_TENANT_MEMBERSHIP_REQUIRED",
+  "MCP_TENANT_PIN_UNSUPPORTED",
+]);
+
+// BOT-1896: the codes the server's 401 gates emit when a request authenticated
+// as nothing — a dead/absent credential, never a tenant refusal.
+const UNAUTHENTICATED_CODES = new Set(["credential_unknown", "credential_missing", "session_token_revoked", "session_token_expired"]);
+
+function typedCodeOf(fields) {
+  if (!fields || typeof fields !== "object") return null;
+  const raw = fields.error_code ?? fields.code;
+  return typeof raw === "string" && raw ? raw : null;
+}
+
+function isAuthClass(fields) {
+  return Boolean(fields && typeof fields === "object" &&
+    (fields.error_class === "auth" || CALL_AUTH_ERROR_CODES.has(typedCodeOf(fields))));
+}
+
+/**
+ * BOT-1896: classify one tools/call exchange. Pure — no I/O.
+ *   kind "ok"           — a normal result (printed as before, exit 0)
+ *   kind "tool_error"   — a non-auth isError result (printed as before, exit 0)
+ *   kind "server_error" — a non-auth JSON-RPC error (die as before, exit 1)
+ *   kind "auth"         — BotBuddy refused the credential → receipt, CALL_EXIT.AUTH
+ *   kind "transport"    — no HTTP response, or a 5xx → receipt, CALL_EXIT.TRANSPORT
+ *   kind "http_error"   — any other HTTP failure (non-JSON or error-less 4xx,
+ *                         a non-JSON 2xx) → receipt, CALL_EXIT.ERROR (fail closed)
+ * The receipt carries the server's `error_code` and typed fields UNCHANGED. A
+ * 401/403 is auth even with no typed code (an older server), never transport.
+ */
+export function classifyCallResponse({ status = null, data = null, transportError = null, parseError = null } = {}) {
+  if (transportError) {
+    return {
+      kind: "transport",
+      receipt: { ok: false, error_class: "transport", error_code: "transport_error", http_status: null, message: String(transportError?.message ?? transportError) },
+    };
+  }
+  const authStatus = status === 401 || status === 403;
+  if (parseError || !data || typeof data !== "object") {
+    if (authStatus) {
+      return { kind: "auth", receipt: { ok: false, error_class: "auth", error_code: "unauthorized", http_status: status, message: "BotBuddy refused the credential (no typed body)." } };
+    }
+    // Codex P1 (PR #970): only a 5xx gateway page reads as transport. A reachable
+    // endpoint answering non-JSON with anything else (a proxy 404 from a wrong
+    // URL, a 429 rate-limit page) must fail closed, never license a fallback.
+    return typeof status === "number" && status >= 500
+      ? { kind: "transport", receipt: { ok: false, error_class: "transport", error_code: "invalid_response", http_status: status, message: `BotBuddy returned a non-JSON response (HTTP ${status}).` } }
+      : httpError(status, `BotBuddy returned a non-JSON response (HTTP ${status ?? "?"}).`);
+  }
+  const rpcError = data.error && typeof data.error === "object" ? data.error : null;
+  if (rpcError) {
+    const detail = rpcError.data && typeof rpcError.data === "object" ? rpcError.data : {};
+    if (isAuthClass(detail) || authStatus || rpcError.code === -32001) {
+      return {
+        kind: "auth",
+        receipt: { ok: false, ...detail, error_class: "auth", error_code: typedCodeOf(detail) ?? "unauthorized", http_status: status, message: rpcError.message ?? null },
+      };
+    }
+    if (typeof status === "number" && status >= 500) {
+      return { kind: "transport", receipt: { ok: false, error_class: "transport", error_code: "server_unavailable", http_status: status, message: rpcError.message ?? null } };
+    }
+    return { kind: "server_error", receipt: null };
+  }
+  // A bare REST-style `{ error }` body (not JSON-RPC).
+  if (typeof data.error === "string") {
+    if (isAuthClass(data) || authStatus) {
+      return { kind: "auth", receipt: { ok: false, ...data, error_class: "auth", error_code: typedCodeOf(data) ?? "unauthorized", http_status: status, message: data.error } };
+    }
+    if (typeof status === "number" && status >= 500) {
+      return { kind: "transport", receipt: { ok: false, error_class: "transport", error_code: "server_unavailable", http_status: status, message: data.error } };
+    }
+    return { kind: "server_error", receipt: null };
+  }
+  if (authStatus) {
+    return { kind: "auth", receipt: { ok: false, error_class: "auth", error_code: "unauthorized", http_status: status, message: null } };
+  }
+  if (typeof status === "number" && status >= 500) {
+    return { kind: "transport", receipt: { ok: false, error_class: "transport", error_code: "server_unavailable", http_status: status, message: null } };
+  }
+  if (typeof status === "number" && status >= 400) {
+    return httpError(status, null);
+  }
+  if (data.result?.isError === true) {
+    const first = data.result?.content?.[0]?.text;
+    let envelope = null;
+    try { envelope = typeof first === "string" ? JSON.parse(first) : null; } catch { envelope = null; }
+    if (isAuthClass(envelope)) {
+      const { success: _success, ...fields } = envelope;
+      return { kind: "auth", receipt: { ok: false, ...fields, error_class: "auth", error_code: typedCodeOf(envelope), http_status: status } };
+    }
+    return { kind: "tool_error", receipt: null };
+  }
+  return { kind: "ok", receipt: null };
+}
+
+function httpError(status, message) {
+  return { kind: "http_error", receipt: { ok: false, error_class: "http", error_code: `http_${status ?? "unknown"}`, http_status: status, message } };
+}
+
+function authFailureLine(receipt) {
+  const what = receipt.error_code === "scope_denied" && receipt.tool && receipt.required_scope
+    ? `scope_denied: \`${receipt.tool}\` requires the \`${receipt.required_scope}\` scope${receipt.key_prefix ? ` (presented a ${receipt.key_prefix} key)` : ""}`
+    : receipt.error_code;
+  return `BotBuddy refused the credential (${what}).${receipt.remedy ? ` ${receipt.remedy}` : ""}`;
+}
+
+export async function callTool(toolName, args = {}, { fetchImpl = fetch, auth = null, tenant = null, resolvePin = resolveDefaultTenantPin, resolveAuth = resolveCallAuth, log = (line) => console.log(line), errorLog = (line) => console.error(line) } = {}) {
   const body = {
     jsonrpc: "2.0",
     id: 1,
     method: "tools/call",
     params: { name: toolName, arguments: args },
   };
+  // BOT-1896: never throw on the wire — a fetch rejection or a non-JSON body is
+  // returned as a classified transport failure instead of an uncaught exit 1.
   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() };
+    let res;
+    try {
+      res = await fetchImpl(await requestEndpoint(resolved, { tenant, resolvePin }), { method: "POST", headers, body: JSON.stringify(body) });
+    } catch (transportError) {
+      return { status: null, data: null, transportError };
+    }
+    try {
+      return { status: res.status, data: await res.json() };
+    } catch (parseError) {
+      return { status: res.status, data: null, parseError };
+    }
   };
 
-  const first = auth ? { auth, source: null } : await authHeader(toolName, { resolveAuth });
-  let { status, data } = await send(first);
+  const first = auth ? { auth, source: null } : await authHeader(toolName, { resolveAuth, exitCode: CALL_EXIT.AUTH });
+  let exchange = await send(first);
   let staleSession = false;
-  if (!auth && isRejectedCachedSessionResponse(first, status, data)) {
+  if (!auth && isRejectedCachedSessionResponse(first, exchange.status, exchange.data)) {
     const durable = await resolveAuth({ toolName, preferSession: false });
-    if (durable.auth) ({ status, data } = await send(durable));
+    if (durable.auth) exchange = await send(durable);
     else staleSession = true;
   }
+  const { status, data } = exchange;
   const exportedRejected = !auth && (first.source === "env" || first.source === "flag")
     && (status === 401 || status === 403 || data?.error?.code === -32001);
 
+  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.`
+        : "";
+
+  const outcome = classifyCallResponse(exchange);
+  if (outcome.kind === "auth") {
+    log(JSON.stringify(outcome.receipt, null, 2));
+    errorLog(`${red("✗")} ${authFailureLine(outcome.receipt)}${hint}`);
+    return CALL_EXIT.AUTH;
+  }
+  if (outcome.kind === "transport") {
+    log(JSON.stringify(outcome.receipt, null, 2));
+    errorLog(`${red("✗")} BotBuddy unreachable (${outcome.receipt.error_code}${outcome.receipt.http_status ? `, HTTP ${outcome.receipt.http_status}` : ""}): ${outcome.receipt.message ?? ""}`);
+    return CALL_EXIT.TRANSPORT;
+  }
+  if (outcome.kind === "http_error") {
+    log(JSON.stringify(outcome.receipt, null, 2));
+    errorLog(`${red("✗")} BotBuddy answered HTTP ${outcome.receipt.http_status ?? "?"} (${outcome.receipt.error_code}); not treating this as unreachable.${hint}`);
+    return CALL_EXIT.ERROR;
+  }
   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}`);
   }
 
@@ -260,13 +424,21 @@ export async function callToolJson(toolName, args = {}, { fetchImpl = fetch, sig
     // { error: { code: -32002, data: { code } } }). Surface that `code` so a
     // caller can tell a tenant refusal apart from a plain credential failure.
     // Best-effort: an opaque/bodyless 401/403 keeps the generic shape.
+    // BOT-1896: the unauthenticated 401 now carries a typed code too
+    // (credential_unknown / session_token_revoked / …). Those are exposed as
+    // `error_code` but NOT lifted into `code`, which callers (mcp-key,
+    // isRejectedCachedMcpSession) read as "a structured refusal other than a dead
+    // credential" — so a bad key keeps its not-authenticated / self-heal path.
     let code = null;
+    let errorCode = null;
     try {
       const body = await res.json();
       const raw = body?.error?.data?.code ?? body?.error?.code ?? body?.code ?? null;
-      if (typeof raw === "string" && raw) code = raw;
+      if (typeof raw === "string" && raw && !UNAUTHENTICATED_CODES.has(raw)) code = raw;
+      const typed = body?.error?.data?.error_code ?? body?.error_code ?? null;
+      if (typeof typed === "string" && typed) errorCode = typed;
     } catch { /* opaque body */ }
-    return { ok: false, auth: true, status: res.status, error: "unauthorized", ...(code ? { code } : {}) };
+    return { ok: false, auth: true, status: res.status, error: "unauthorized", ...(code ? { code } : {}), ...(errorCode ? { error_code: errorCode } : {}) };
   }
   let payload;
   try { payload = await res.json(); } catch { return { ok: false, status: res.status, error: "invalid_json" }; }

package/src/stack.mjs

@@ -27,7 +27,7 @@ import { open, unlink, readFile } from "fs/promises";
 import { tmpdir } from "os";
 import { basename, dirname, join, relative, isAbsolute } from "path";
 import { randomUUID } from "crypto";
-import { callToolJson } from "./api.mjs";
+import { callToolJson, CALL_AUTH_ERROR_CODES } from "./api.mjs";
 import { SERVER_URL, getConfig } from "./config.mjs";
 import { resolveOwnerToken, resolveAgentKey } from "./cli-credentials.mjs";
 import { AGENT_KEY_RE, readAgentSessionTokenEnv } from "./agent-key.mjs";
@@ -696,6 +696,9 @@ export function stackPathRootRefusalNotice(code, message) {
  * reads as "the control plane is unhealthy, retry". Every other refusal keeps BACKEND (5).
  */
 export function leaseRefusalExit(code) {
+  // BOT-1896: an auth-class refusal (scope_denied, a tenant mismatch, …) is the
+  // server refusing the credential — never BACKEND, which a gate reads as "down".
+  if (CALL_AUTH_ERROR_CODES.has(code)) return EXIT.AUTH;
   return code === STACK_PATH_ROOT_REFUSED_CODE ? EXIT.INVALID : EXIT.BACKEND;
 }