@botbuddy/cli 1.2.3 → 1.4.1

package/src/commands.mjs

@@ -1,9 +1,15 @@
-import { callTool, readResource } from "./api.mjs";
+import { callTool, callToolJson, readResource } from "./api.mjs";
 import { doLogin } from "./auth.mjs";
 import { runBridge } from "./codex-bridge.mjs";
-import { loadConfig, getConfig, clearConfig, saveConfig, getConfigPath } from "./config.mjs";
+import { loadConfig, getConfig, clearConfig, saveConfig, getConfigPath, SERVER_URL } from "./config.mjs";
+import { buildAcquireResourcesPayload, LocksUsageError } from "./locks.mjs";
+import { CallUsageError, discoveryUrlFor, formatDiscovery, parseCallArgs } from "./discovery.mjs";
+import { cmdStack } from "./stack.mjs";
+import { cmdRun } from "./run.mjs";
+import { runWait } from "./wait.mjs";
 import { green, red, cyan, dim, bold, die } from "./utils.mjs";
 import { VERSION } from "./version.mjs";
+import { bootstrapProfile, ProfileBootstrapError, profileShellRefresh } from "./profile-bootstrap.mjs";
 
 export async function run(argv) {
   loadConfig();
@@ -11,7 +17,7 @@ export async function run(argv) {
 
   switch (command) {
     case "start": return cmdStart(args);
-    case "login": return doLogin();
+    case "login": return cmdLogin(args);
     case "logout": return cmdLogout();
     case "status": return cmdStatus();
     // Agent-only commands (used by MCP agents, not humans)
@@ -20,6 +26,11 @@ export async function run(argv) {
     case "lock": return cmdLock(args);
     case "locks": return cmdLocks(args);
     case "unlock": return cmdUnlock(args);
+    // BOT-1220: batch-scoped local stack leases (request/park/status/touch/done).
+    case "stack": return cmdStack(args);
+    case "run": return cmdRun(args);
+    case "wait": return runWait(args);
+    case "profile": return cmdProfile(args);
     case "resources": return callTool("list_resources");
     case "agents": return callTool("list_agents");
     case "tasks": return readResource("botbuddy://tasks");
@@ -27,9 +38,16 @@ export async function run(argv) {
     case "hours": return cmdHours(args);
     case "browse": return cmdBrowse(args);
     case "codex": return cmdCodex(args);
+    // BOT-876: generic passthrough. The server advertises only `help` and
+    // `call`; these two commands reach every tool without the CLI carrying a
+    // single tool schema, so it stays at parity with the server for free.
+    case "call": return cmdCall(args);
     case "version": case "--version": case "-v":
       console.log(`botbuddy v${VERSION}`); return;
     case "help": case "--help": case "-h": case undefined:
+      // `botbuddy help` with a tool name (or --tools) fetches the live
+      // catalog; bare `help` stays the local usage screen.
+      if (args.length > 0) return cmdToolHelp(args);
       return cmdHelp();
     default:
       die(`Unknown command: ${command}. Run ${cyan("botbuddy help")} for usage.`);
@@ -50,26 +68,127 @@ ${bold("OPTIONS")}
     --no-server              Don't auto-start codex app-server
 
 ${bold("AUTH")}
-  login                      Re-authenticate via OAuth
+  login [--no-browser]       Authenticate via OAuth (opens browser + localhost callback)
   logout                     Remove saved credentials
   status                     Show current auth status
+  profile setup <profile>    Mint/reconnect and securely store a tenant-bound agent key
+
+${bold("TOOLS")}
+  help --tools               List every BotBuddy tool
+  help <tool>                Show one tool's arguments
+  call <tool> [--key value]  Invoke any tool
+  call <tool> --json '{...}' Invoke with a JSON arguments object
+
+${bold("STACK LEASES")}
+  stack up [options]         Request a batch-scoped local stack lease; park if full; hold it active
+  stack status <lease_id>    Show a lease's state + connection
+  stack touch  <lease_id>    Bump the lease idle clock
+  stack done   <lease_id>    Release (done) a lease — reap the stack
+  stack help                 Full stack usage + exit codes
+
+${bold("DURABLE WORKLOADS")}
+  run --session-id <id> --environment <env> -- <command>
+                              Launch a receipt-bearing command under a detached owner
+
+${bold("AGENT WAITS")}
+  wait [--any] <condition>... [options]
+                              Wait once for a pushed BotBuddy signal
 
 ${bold("OTHER")}
+  locks -m [--host name]    Reserve typed local resources, including Playwright MCP lanes
   help                       Show this help
   version                    Show version`);
 }
 
+// ─── BOT-876: generic tool access ───────────────────────────────
+
+async function cmdCall(args) {
+  let parsedArgs;
+  try {
+    parsedArgs = parseCallArgs(args);
+  } catch (e) {
+    if (e instanceof CallUsageError) die(e.message);
+    throw e;
+  }
+  return callTool(parsedArgs.tool, parsedArgs.args);
+}
+
+async function cmdToolHelp(args) {
+  // `help --tools` (or `help --all`) lists the catalog; `help <tool>` details one.
+  const tool = args[0].startsWith("-") ? null : args[0];
+  const res = await fetch(discoveryUrlFor(SERVER_URL, tool));
+  if (!res.ok) {
+    die(res.status === 404
+      ? `Unknown tool: ${tool}. Run ${cyan("botbuddy help --tools")} to list them.`
+      : `Discovery failed: ${res.status} ${res.statusText}`);
+  }
+  console.log(formatDiscovery(await res.json(), { tool }));
+}
+
+// BOT-1383: login now runs the RFC 8252 loopback flow (opens the browser,
+// waits for the localhost callback). Parse --no-browser and print focused help.
+async function cmdLogin(args) {
+  if (args.includes("--help") || args.includes("-h")) return loginHelp();
+  const noBrowser = args.includes("--no-browser");
+  const unknown = args.find((a) => a.startsWith("-") && !["--no-browser", "--help", "-h"].includes(a));
+  if (unknown) die(`Unknown login option: ${unknown}. Run ${cyan("botbuddy login --help")}.`);
+  try {
+    await doLogin({ noBrowser });
+  } catch (err) {
+    die(err.message);
+  }
+}
+
+function loginHelp() {
+  console.log(`${bold("botbuddy login")} — authenticate via OAuth (browser + loopback callback)
+
+${bold("USAGE")}
+  botbuddy login [--no-browser]
+
+${bold("HOW IT WORKS")}
+  Starts a localhost callback listener on an ephemeral 127.0.0.1 port, opens
+  your default browser at the BotBuddy authorization page, and waits for you to
+  sign in as an allowed user. On success the token is saved to
+  ${dim("~/.botbuddy/config.json")} and the browser tab can be closed.
+
+${bold("OPTIONS")}
+  --no-browser   Don't launch a browser; print the authorization URL to open
+                 in a browser on THIS machine yourself. The callback listener
+                 still runs on this machine's localhost.
+
+${bold("NOTES")}
+  • The authorization URL is always printed so you can open it manually.
+  • Login waits up to 5 minutes for the callback, then exits with an error and
+    saves nothing.
+  • If sign-in fails, just re-run ${cyan("botbuddy login")} — each attempt uses a fresh
+    listener and state.
+  • ${bold("Remote / SSH:")} the callback URL is ${dim("http://127.0.0.1:<port>/callback")}, which
+    always points at the machine whose browser opens it. If you run login on a
+    remote host but sign in from your laptop's browser, first forward that exact
+    port back to the host, e.g. ${cyan("ssh -L <port>:127.0.0.1:<port> <host>")}
+    (the port is printed in the URL). Without the tunnel the callback can't
+    reach the listener and login will time out.
+
+${bold("RECOVERY")}
+  If ${cyan("botbuddy profile setup <profile>")} reports an authentication error,
+  run ${cyan("botbuddy login")} first, then re-run profile setup.`);
+}
+
 async function cmdStart(args) {
   console.log(`${bold("botbuddy")} ${dim(`v${VERSION}`)}\n`);
   const cfg = getConfig();
 
   // Auto-login if not authenticated
-  if (!cfg.access_token && !cfg.api_key) {
-    console.log(dim("→ No credentials found. Starting login...\n"));
-    await doLogin();
-  } else if (cfg.token_expires_at && cfg.token_expires_at <= Date.now()) {
-    console.log(dim("→ Token expired. Re-authenticating...\n"));
-    await doLogin();
+  try {
+    if (!cfg.access_token && !cfg.api_key) {
+      console.log(dim("→ No credentials found. Starting login...\n"));
+      await doLogin();
+    } else if (cfg.token_expires_at && cfg.token_expires_at <= Date.now()) {
+      console.log(dim("→ Token expired. Re-authenticating...\n"));
+      await doLogin();
+    }
+  } catch (err) {
+    die(err.message);
   }
 
   // Start the bridge (which auto-starts codex app-server)
@@ -107,6 +226,44 @@ function cmdLogout() {
   console.log(`${green("✓")} Logged out. Credentials removed.`);
 }
 
+async function cmdAgentAuth(args) {
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+    console.log(`Usage: botbuddy auth <login|status|logout> [--profile <name>] [--token <key>]
+
+  auth login    Store a tenant-bound agent credential in the OS keyring. On macOS,
+                it imports the existing launchd credential once when no --token or
+                profile-specific environment key is supplied.
+  auth status   Show whether the profile has a stored key (never prints it).
+  auth logout   Remove the profile's stored key.`);
+    return;
+  }
+  let options;
+  try {
+    options = parseAgentAuthArgs(args);
+  } catch (error) {
+    die(error.message);
+  }
+  const profile = options.profile || await findProfileName(process.cwd());
+  if (!profile || !getProfileDefinition(profile)) {
+    die("No supported BotBuddy agent profile found. Add .botbuddy-agent.json or pass --profile <name>.");
+  }
+  if (options.action === "login") {
+    const token = await resolveLoginToken({ profile, explicitToken: options.token });
+    const result = await loginAgentCredential({ profile, token });
+    console.log(`${green("✓")} Stored ${result.profile} (${result.tenant}) agent credential in the OS keyring.`);
+    return;
+  }
+  if (options.action === "status") {
+    const result = await getAgentAuthStatus({ profile });
+    console.log(result.authenticated
+      ? `${green("✓")} ${result.profile} (${result.tenant}) machine credential is stored in the OS keyring.`
+      : `${red("✗")} ${result.profile} (${result.tenant}) has no stored machine credential.`);
+    return;
+  }
+  const result = await logoutAgentCredential({ profile });
+  console.log(`${green("✓")} ${result.profile} (${result.tenant}) machine credential ${result.removed ? "removed" : "was not present"}.`);
+}
+
 async function cmdRegister(args) {
   const name = args[0];
   if (!name) die("Usage: botbuddy register <name> [type]");
@@ -127,33 +284,52 @@ function cmdHeartbeat(args) {
   return args[0] ? callTool("heartbeat", { current_task: args[0] }) : callTool("heartbeat");
 }
 
+async function cmdProfile(args) {
+  if (args[0] === "--help" || args[0] === "-h") {
+    console.log(`Usage: botbuddy profile <setup|env> <botbuddy-dev|supplyguard-dev>
+
+  setup <profile>   Mint/reconnect and securely store a tenant-bound agent key
+  env <profile>     Print shell exports that load the stored agent key`);
+    return;
+  }
+  if (args[0] === "env" && args[1] && args.length === 2) {
+    try {
+      console.log(profileShellRefresh(args[1]));
+      return;
+    } catch {
+      die("Usage: botbuddy profile env <botbuddy-dev|supplyguard-dev>");
+    }
+  }
+  if (args[0] !== "setup" || !args[1] || args.length > 2) {
+    die("Usage: botbuddy profile <setup|env> <botbuddy-dev|supplyguard-dev>");
+  }
+  try {
+    const receipt = await bootstrapProfile(args[1], { call: callToolJson });
+    console.log(JSON.stringify(receipt));
+  } catch (error) {
+    const code = error instanceof ProfileBootstrapError ? error.code : "profile_agent_required";
+    console.log(JSON.stringify({
+      schema_version: 1,
+      outcome: "error",
+      error: code,
+      recovery: "botbuddy login && botbuddy profile setup " + args[1],
+    }));
+    process.exitCode = 3;
+  }
+}
+
 function cmdLock(args) {
   if (args.length < 2) die("Usage: botbuddy lock <resource_name> <type>");
   return callTool("acquire_lock", { resource_name: args[0], resource_type: args[1] });
 }
 
 function cmdLocks(args) {
-  const resources = [];
-  let ticketId, prId;
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "-p" || args[i] === "--port") {
-      const portType = (args[i + 1] && !args[i + 1].startsWith("-")) ? args[++i] : "frontend";
-      resources.push({ resource_type: "port", port_type: portType });
-    } else if (args[i] === "-m" || args[i] === "--mcp") {
-      resources.push({ resource_type: "mcp_server" });
-    } else if (args[i] === "-t" || args[i] === "--ticket") {
-      ticketId = args[++i];
-    } else if (args[i] === "--pr") {
-      prId = args[++i];
-    }
-  }
-  if (!resources.length) {
-    die("Usage: botbuddy locks -p [frontend|backend] -m [-t ticket] [--pr id]");
+  try {
+    return callTool("acquire_resources", buildAcquireResourcesPayload(args));
+  } catch (error) {
+    if (error instanceof LocksUsageError) die(error.message);
+    throw error;
   }
-  const payload = { resources };
-  if (ticketId) payload.ticket_id = ticketId;
-  if (prId) payload.pr_id = prId;
-  return callTool("acquire_resources", payload);
 }
 
 function cmdUnlock(args) {

package/src/config.mjs

@@ -5,7 +5,11 @@ import { homedir } from "os";
 const CONFIG_DIR = join(homedir(), ".botbuddy");
 const CONFIG_FILE = join(CONFIG_DIR, "config.json");
 
-export const SERVER_URL = "https://api.bot-buddy.ai/functions/v1/mcp-server";
+// BOT-876: overridable so the CLI can be pointed at a local Supabase stack
+// (`BOTBUDDY_SERVER_URL=http://127.0.0.1:56321/functions/v1/mcp-server`).
+// Production is the default; nothing changes for normal use.
+export const SERVER_URL = process.env.BOTBUDDY_SERVER_URL
+  || "https://api.bot-buddy.ai/functions/v1/mcp-server";
 
 let config = {};
 

package/src/discovery.mjs

@@ -0,0 +1,141 @@
+// BOT-876: generic tool invocation + discovery for the CLI.
+//
+// The MCP server now advertises only `help` and `call`, and serves its full
+// catalog from GET /discovery. The CLI is a schema-free passthrough, so it
+// reaches every tool without knowing any of them — these two commands are all
+// it needs to stay at parity with the server forever.
+//
+// Argument parsing is separated from I/O so it can be unit-tested without a
+// server. See discovery.test.mjs.
+
+export class CallUsageError extends Error {}
+
+/**
+ * Parse `botbuddy call <tool> [--json '<obj>'] [--key value ...]`.
+ *
+ * Two input styles, because both are natural depending on who is typing:
+ *   --json '{"name":"x"}'   one blob, for anything nested
+ *   --name x --count 3      flags, for simple scalar arguments
+ *
+ * Returns { tool, args }.
+ */
+export function parseCallArgs(argv) {
+  const [tool, ...rest] = argv;
+
+  if (!tool || tool.startsWith("-")) {
+    throw new CallUsageError(
+      "Usage: botbuddy call <tool> [--json '<args>'] [--key value ...]",
+    );
+  }
+
+  let args = {};
+  let sawJson = false;
+
+  for (let i = 0; i < rest.length; i++) {
+    const token = rest[i];
+
+    if (token === "--json" || token === "-j") {
+      const raw = rest[++i];
+      if (raw === undefined) throw new CallUsageError("--json requires a JSON object argument.");
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch (e) {
+        throw new CallUsageError(`--json is not valid JSON: ${e.message}`);
+      }
+      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CallUsageError("--json must be a JSON object, e.g. '{\"name\":\"value\"}'.");
+      }
+      // Flags already seen win over the blob only if they come later; merging
+      // in order keeps "last one wins" true for both styles.
+      args = { ...args, ...parsed };
+      sawJson = true;
+      continue;
+    }
+
+    if (token.startsWith("--")) {
+      const key = token.slice(2);
+      if (!key) throw new CallUsageError(`Malformed flag: ${token}`);
+
+      // `--flag` with no value, or followed by another flag, is a boolean.
+      const next = rest[i + 1];
+      if (next === undefined || next.startsWith("--")) {
+        args[key] = true;
+        continue;
+      }
+      args[key] = coerceScalar(next);
+      i++;
+      continue;
+    }
+
+    throw new CallUsageError(
+      `Unexpected argument: ${token}. Pass tool arguments as --key value or --json '{...}'.`,
+    );
+  }
+
+  return { tool, args, usedJson: sawJson };
+}
+
+/**
+ * Numbers and booleans typed on a command line arrive as strings; a tool whose
+ * schema says `number` would reject them. Anything that is not unambiguously a
+ * number or boolean stays a string.
+ */
+function coerceScalar(raw) {
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  if (raw === "null") return null;
+  if (raw !== "" && !Number.isNaN(Number(raw)) && /^-?\d+(\.\d+)?$/.test(raw)) {
+    return Number(raw);
+  }
+  return raw;
+}
+
+/** URL of the discovery document for a given MCP server URL. */
+export function discoveryUrlFor(serverUrl, tool) {
+  const base = `${String(serverUrl).replace(/\/+$/, "")}/discovery`;
+  return tool ? `${base}?tool=${encodeURIComponent(tool)}` : base;
+}
+
+/**
+ * Render the discovery document for a human. The full catalog is ~97 tools, so
+ * the index is one line each; a single tool gets its full schema.
+ */
+export function formatDiscovery(doc, { tool } = {}) {
+  if (!doc || !Array.isArray(doc.tools)) return "No tools found.";
+
+  if (tool) {
+    const match = doc.tools.find((t) => t.name === tool);
+    if (!match) return `Unknown tool: ${tool}`;
+    return [
+      match.name,
+      "",
+      match.description ?? "",
+      "",
+      // BOT-971: agent-identity-gated tools carry an `auth` note on the
+      // discovery entry — surface it so `botbuddy help <tool>` matches
+      // help({ tool }) instead of hiding the requirement.
+      ...(match.auth ? ["Auth:", match.auth, ""] : []),
+      "Arguments:",
+      JSON.stringify(match.inputSchema ?? {}, null, 2),
+      "",
+      `Invoke: botbuddy call ${match.name} --json '{...}'`,
+    ].join("\n");
+  }
+
+  const lines = [
+    `${doc.tools.length} tools available. botbuddy help <tool> for one tool's arguments.`,
+    "",
+  ];
+  for (const t of [...doc.tools].sort((a, b) => a.name.localeCompare(b.name))) {
+    lines.push(`  ${t.name.padEnd(34)} ${firstSentence(t.description ?? "")}`);
+  }
+  return lines.join("\n");
+}
+
+function firstSentence(text) {
+  const trimmed = String(text).replace(/\s+/g, " ").trim();
+  const stop = trimmed.indexOf(". ");
+  const sentence = stop === -1 ? trimmed : trimmed.slice(0, stop + 1);
+  return sentence.length > 96 ? `${sentence.slice(0, 93)}...` : sentence;
+}

package/src/discovery.test.mjs

@@ -0,0 +1,195 @@
+// BOT-876: unit coverage for the CLI's generic call + discovery commands.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  CallUsageError,
+  discoveryUrlFor,
+  formatDiscovery,
+  parseCallArgs,
+} from "./discovery.mjs";
+
+const SERVER = "https://api.bot-buddy.ai/functions/v1/mcp-server";
+
+// ─── parseCallArgs ──────────────────────────────────────────────
+
+test("call with no arguments yields an empty args object", () => {
+  assert.deepEqual(parseCallArgs(["list_agents"]), {
+    tool: "list_agents",
+    args: {},
+    usedJson: false,
+  });
+});
+
+test("--json supplies the whole arguments object", () => {
+  const { tool, args } = parseCallArgs([
+    "register_agent",
+    "--json",
+    '{"name":"claude-1","type":"claude"}',
+  ]);
+  assert.equal(tool, "register_agent");
+  assert.deepEqual(args, { name: "claude-1", type: "claude" });
+});
+
+test("--json accepts nested structures", () => {
+  const { args } = parseCallArgs([
+    "register_agent",
+    "--json",
+    '{"resources":[{"resource_type":"mcp_server","subtype":"playwright_lane"}]}',
+  ]);
+  assert.deepEqual(args.resources, [
+    { resource_type: "mcp_server", subtype: "playwright_lane" },
+  ]);
+});
+
+test("--key value flags build the arguments object", () => {
+  const { args } = parseCallArgs(["create_task", "--title", "Fix the thing", "--priority", "2"]);
+  assert.deepEqual(args, { title: "Fix the thing", priority: 2 });
+});
+
+test("numeric and boolean flag values are coerced off the command line", () => {
+  // A tool whose schema says `number` would reject the string "2".
+  const { args } = parseCallArgs([
+    "t",
+    "--count", "2",
+    "--ratio", "1.5",
+    "--negative", "-3",
+    "--yes", "true",
+    "--no", "false",
+    "--nothing", "null",
+  ]);
+  assert.deepEqual(args, {
+    count: 2, ratio: 1.5, negative: -3, yes: true, no: false, nothing: null,
+  });
+});
+
+test("values that only look numeric stay strings", () => {
+  const { args } = parseCallArgs([
+    "t",
+    "--ticket", "BOT-876",
+    "--version", "1.2.3",
+    "--hex", "0x10",
+    "--padded", "007",
+  ]);
+  assert.equal(args.ticket, "BOT-876");
+  assert.equal(args.version, "1.2.3");
+  assert.equal(args.hex, "0x10");
+  // "007" is unambiguously numeric; losing the padding is acceptable, but a
+  // leading-zero identifier is common enough to pin the behaviour.
+  assert.equal(args.padded, 7);
+});
+
+test("a valueless flag is a boolean true", () => {
+  const { args } = parseCallArgs(["t", "--force", "--name", "x"]);
+  assert.deepEqual(args, { force: true, name: "x" });
+});
+
+test("a trailing valueless flag is a boolean true", () => {
+  const { args } = parseCallArgs(["t", "--force"]);
+  assert.deepEqual(args, { force: true });
+});
+
+test("flags after --json override the blob", () => {
+  const { args } = parseCallArgs(["t", "--json", '{"name":"a"}', "--name", "b"]);
+  assert.equal(args.name, "b");
+});
+
+test("a missing tool name is a usage error", () => {
+  assert.throws(() => parseCallArgs([]), CallUsageError);
+  assert.throws(() => parseCallArgs(["--json", "{}"]), CallUsageError);
+});
+
+test("malformed --json is reported clearly, not swallowed", () => {
+  assert.throws(() => parseCallArgs(["t", "--json", "{not json}"]), (e) => {
+    assert.ok(e instanceof CallUsageError);
+    assert.match(e.message, /not valid JSON/);
+    return true;
+  });
+});
+
+test("--json must be an object, not an array or scalar", () => {
+  for (const bad of ["[1,2]", '"a string"', "42", "null"]) {
+    assert.throws(() => parseCallArgs(["t", "--json", bad]), CallUsageError, `accepted ${bad}`);
+  }
+});
+
+test("--json with no value is a usage error", () => {
+  assert.throws(() => parseCallArgs(["t", "--json"]), CallUsageError);
+});
+
+test("a bare positional argument is rejected rather than silently ignored", () => {
+  assert.throws(() => parseCallArgs(["t", "oops"]), (e) => {
+    assert.match(e.message, /--key value or --json/);
+    return true;
+  });
+});
+
+// ─── discoveryUrlFor ────────────────────────────────────────────
+
+test("discovery URL is derived from the server URL", () => {
+  assert.equal(discoveryUrlFor(SERVER), `${SERVER}/discovery`);
+  assert.equal(discoveryUrlFor(`${SERVER}/`), `${SERVER}/discovery`);
+});
+
+test("discovery URL encodes a requested tool", () => {
+  assert.equal(discoveryUrlFor(SERVER, "get_totp_code"), `${SERVER}/discovery?tool=get_totp_code`);
+});
+
+// ─── formatDiscovery ────────────────────────────────────────────
+
+const DOC = {
+  tools: [
+    { name: "register_agent", description: "Register an agent. Extra detail here.", inputSchema: { type: "object" } },
+    { name: "list_agents", description: "List all agents", inputSchema: { type: "object" } },
+  ],
+};
+
+test("the index lists every tool, sorted, one line each", () => {
+  const out = formatDiscovery(DOC);
+  const lines = out.split("\n").filter((l) => l.startsWith("  "));
+  assert.equal(lines.length, 2);
+  assert.match(lines[0], /list_agents/);
+  assert.match(lines[1], /register_agent/);
+  assert.match(out, /2 tools available/);
+});
+
+test("the index truncates a description to its first sentence", () => {
+  const out = formatDiscovery(DOC);
+  assert.match(out, /Register an agent\./);
+  assert.doesNotMatch(out, /Extra detail here/);
+});
+
+test("a single tool renders its full schema and an invocation example", () => {
+  const out = formatDiscovery(DOC, { tool: "register_agent" });
+  assert.match(out, /^register_agent/);
+  assert.match(out, /botbuddy call register_agent/);
+  assert.match(out, /"type": "object"/);
+  // register_agent carries no `auth` note → no Auth section.
+  assert.doesNotMatch(out, /Auth:/);
+});
+
+test("a single tool with an agent-identity note renders an Auth section", () => {
+  // BOT-971: the server stamps `auth` on discovery entries for agent-gated
+  // tools; `botbuddy help <tool>` must surface it (matching help({ tool })).
+  const doc = {
+    tools: [{
+      name: "acquire_resources",
+      description: "Batch lock",
+      inputSchema: { type: "object" },
+      auth: "Requires an agent identity — call register_agent first.",
+    }],
+  };
+  const out = formatDiscovery(doc, { tool: "acquire_resources" });
+  assert.match(out, /Auth:/);
+  assert.match(out, /register_agent/);
+});
+
+test("an unknown tool is reported, not rendered empty", () => {
+  assert.match(formatDiscovery(DOC, { tool: "nope" }), /Unknown tool: nope/);
+});
+
+test("a malformed discovery document does not throw", () => {
+  assert.equal(formatDiscovery(null), "No tools found.");
+  assert.equal(formatDiscovery({}), "No tools found.");
+});