@botbuddy/cli 1.19.1 → 1.19.2

package/package.json

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

package/src/wait-core.mjs

@@ -576,13 +576,27 @@ export function truncateReceipt(receipt, maxBytes = 10240) {
     clone.detail_truncated = true;
   }
   if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes && clone.outcome === "error") {
-    return {
+    const base = {
       schema_version: clone.schema_version,
       outcome: "error",
       error: typeof clone.error === "string" ? clone.error.slice(0, 48) : "receipt_truncated",
       truncated: true,
       ...(clone.client ? { client: clone.client } : {}),
     };
+    // BOT-1590: the recovery hint is the whole point of an error receipt, so keep
+    // it (trimmed to whatever still fits the cap) rather than dropping it — a
+    // caller at the documented minimum cap must still get its one actionable line.
+    if (typeof clone.recovery === "string" && clone.recovery.length > 0) {
+      const room = maxBytes - Buffer.byteLength(JSON.stringify({ ...base, recovery: "" }));
+      if (room > 0) {
+        let recovery = clone.recovery;
+        while (recovery.length > 0 && Buffer.byteLength(recovery, "utf8") > room) {
+          recovery = recovery.slice(0, -1);
+        }
+        if (recovery.length > 0) base.recovery = recovery;
+      }
+    }
+    return base;
   }
   return clone;
 }

package/src/wait.mjs

@@ -14,7 +14,7 @@
 // Run     botbuddy wait --help for the condition grammar.
 
 import { EXIT, parseConditions, parseSseFrames, runWaitLoop, normalizeSince, truncateReceipt, formatPrReviewSnapshotWarnings } from "./wait-core.mjs";
-import { resolveAgentProfile, withPrincipalReceipt } from "./wait-profile.mjs";
+import { resolveAgentProfile, withPrincipalReceipt, PROFILE_FILE } from "./wait-profile.mjs";
 import { VERSION } from "./version.mjs";
 import { fileURLToPath } from "node:url";
 import { latestPublicCliCommand } from "./public-invocation.mjs";
@@ -643,10 +643,52 @@ function profileErrorReceipt(profile, error) {
     schema_version: 1,
     outcome: "error",
     error,
-    recovery: profileRecovery(profile),
+    recovery: profileCredentialRecovery(profile),
   }, profile, { sessionTenant: profile.tenant, agentId: null });
 }
 
+// BOT-1590: canonical one-line recoveries for every setup/auth/parameter error.
+// Each names the exact command to run and the source of any missing/invalid
+// value, so an agent (or a human) can self-serve without opening the docs. The
+// SAME string is written to stderr and the receipt `recovery` field that /waits
+// renders. Keep each to one line and never embed a secret value — names, slots,
+// and env-var names only.
+const RECOVERY = Object.freeze({
+  // $BOTBUDDY_SESSION_TOKEN (bb_sess_+64hex) is minted by register_agent; the
+  // harness exports it at session start.
+  sessionToken: "register_agent → export BOTBUDDY_SESSION_TOKEN=<session_token> (the harness exports it at session start)",
+  // $BOTBUDDY_SESSION_ID is the work-graph session id returned by register_agent.
+  sessionId: "register_agent → export BOTBUDDY_SESSION_ID=<session_id> (the work-graph session id from register_agent)",
+  // A --token / session-token contradiction: the session token is the whole
+  // credential, so drop --token (never advise also setting a session id here).
+  sessionTokenConflict: "unset --token — $BOTBUDDY_SESSION_TOKEN is the whole credential (protocol 3)",
+  // Grammar/condition errors point at the help and the canonical doc.
+  conditions: "check the condition grammar: botbuddy wait --help / docs/agent-wait.md",
+});
+
+const KNOWN_PROFILES = "botbuddy-dev, supplyguard-dev";
+
+// profile_required / unknown_profile: name the file, a minimal example, and the
+// known profile names so the fix is a single edit (AC-3).
+function profileResolutionRecovery(errorCode) {
+  return errorCode === "unknown_profile"
+    ? `set a known profile in ${PROFILE_FILE} or pass --profile <name> — known profiles: ${KNOWN_PROFILES}`
+    : `add ${PROFILE_FILE} ({"schema_version":1,"profile":"botbuddy-dev"}) or pass --profile <name> — known profiles: ${KNOWN_PROFILES}`;
+}
+
+// A profile-credential error (missing/revoked/wrong-tenant): name the exact
+// setup command and the credential's real source, then rule out human PATs,
+// which are never valid for waits (AC-4). `botbuddy profile setup` stores the
+// key in the macOS Keychain under the profile env-var's name (it REQUIRES the
+// Keychain — ensureProfileCredentialBackend); on a non-Keychain host the
+// supported path is exporting that same profile env var directly, which
+// resolveAgentProfile reads. (The 0600 config.json store is the owner login
+// token's, not a profile credential's — a wait cannot consume it.)
+const HUMAN_PAT_NOTE = "human PATs (BOTBUDDY_AGENT_KEY / BOTBUDDY_AGENT_API_KEY) are not valid for waits";
+function profileCredentialRecovery(profile) {
+  return `${profileRecovery(profile)} (stores $${profile.tokenEnv} in the macOS Keychain; on a non-Keychain host export $${profile.tokenEnv} directly); ${HUMAN_PAT_NOTE}`;
+}
+
 export async function runWait(argv) {
   const opts = parseArgv(argv);
   const emitReceipt = (receipt, options = {}) => emit(receipt, {
@@ -671,7 +713,8 @@ export async function runWait(argv) {
   const { conditions, errors } = parseConditions(opts.conditions);
   if (errors.length > 0) {
     for (const e of errors) process.stderr.write(`bb-wait: invalid condition '${e.spec}': ${e.message}\n`);
-    emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_conditions", errors });
+    process.stderr.write(`bb-wait: ${RECOVERY.conditions}\n`);
+    emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_conditions", errors, recovery: RECOVERY.conditions });
     process.exit(EXIT.INVALID);
   }
 
@@ -696,13 +739,13 @@ export async function runWait(argv) {
   // is a contradiction and is rejected.
   if (needsRelay && opts.sessionToken) {
     if (!SESSION_TOKEN_RE.test(opts.sessionToken)) {
-      process.stderr.write("botbuddy wait: $BOTBUDDY_SESSION_TOKEN must match bb_sess_<64 hex>\n");
-      emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_session_token" });
+      process.stderr.write(`botbuddy wait: $BOTBUDDY_SESSION_TOKEN must match bb_sess_<64 hex>; ${RECOVERY.sessionToken}\n`);
+      emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_session_token", recovery: RECOVERY.sessionToken });
       process.exit(EXIT.INVALID);
     }
     if (opts.token && opts.token !== opts.sessionToken) {
-      process.stderr.write("botbuddy wait: --token conflicts with $BOTBUDDY_SESSION_TOKEN; pass only one\n");
-      emitReceipt({ schema_version: 1, outcome: "error", error: "session_token_conflict" });
+      process.stderr.write(`botbuddy wait: --token conflicts with $BOTBUDDY_SESSION_TOKEN; ${RECOVERY.sessionTokenConflict}\n`);
+      emitReceipt({ schema_version: 1, outcome: "error", error: "session_token_conflict", recovery: RECOVERY.sessionTokenConflict });
       process.exit(EXIT.INVALID);
     }
     opts.useSessionToken = true;
@@ -714,19 +757,19 @@ export async function runWait(argv) {
     // timer-only wait needs no relay and no session id (handled by !needsRelay).
     if (!opts.sessionId) {
       process.stderr.write(
-        "botbuddy wait: --session-id is required (or set $BOTBUDDY_SESSION_ID) — the work-graph session id returned by register_agent\n",
+        `botbuddy wait: --session-id is required (or set $BOTBUDDY_SESSION_ID) — the work-graph session id returned by register_agent; ${RECOVERY.sessionId}\n`,
       );
       emitReceipt({
         schema_version: 1,
         outcome: "error",
         error: "session_id_required",
-        recovery: "register_agent → export BOTBUDDY_SESSION_ID=<session_id>",
+        recovery: RECOVERY.sessionId,
       });
       process.exit(EXIT.INVALID);
     }
     if (!SESSION_UUID.test(opts.sessionId)) {
-      process.stderr.write(`botbuddy wait: --session-id must be a uuid (got '${opts.sessionId}')\n`);
-      emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_session_agent", detail: "session_id must be a uuid" });
+      process.stderr.write(`botbuddy wait: --session-id must be a uuid (got '${opts.sessionId}'); ${RECOVERY.sessionId}\n`);
+      emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_session_agent", detail: "session_id must be a uuid", recovery: RECOVERY.sessionId });
       process.exit(EXIT.INVALID);
     }
     try {
@@ -735,14 +778,16 @@ export async function runWait(argv) {
         explicitToken: opts.token,
       });
     } catch (err) {
-      process.stderr.write(`bb-wait: ${err.message}\n`);
-      emitReceipt({ schema_version: 1, outcome: "error", error: err.code || "invalid_profile" });
+      const code = err.code || "invalid_profile";
+      const recovery = profileResolutionRecovery(code);
+      process.stderr.write(`bb-wait: ${err.message}; ${recovery}\n`);
+      emitReceipt({ schema_version: 1, outcome: "error", error: code, recovery });
       process.exit(EXIT.INVALID);
     }
     opts.token = opts.agentProfile.token;
     if (!opts.token) {
       process.stderr.write(
-        `botbuddy wait: profile '${opts.agentProfile.name}' has no tenant-bound agent credential; run '${profileRecovery(opts.agentProfile)}'\n`,
+        `botbuddy wait: profile '${opts.agentProfile.name}' has no tenant-bound agent credential; run ${profileCredentialRecovery(opts.agentProfile)}\n`,
       );
       emitReceipt(profileErrorReceipt(opts.agentProfile, "profile_required"));
       process.exit(EXIT.AUTH);
@@ -897,7 +942,7 @@ export async function runWait(argv) {
           process.exit(EXIT.AUTH);
         }
         const error = typedProfileError(err.errorCode);
-        process.stderr.write(`botbuddy wait: profile authentication failed (${error}); run '${profileRecovery(opts.agentProfile)}'\n`);
+        process.stderr.write(`botbuddy wait: profile authentication failed (${error}); run ${profileCredentialRecovery(opts.agentProfile)}\n`);
         emitReceipt(profileErrorReceipt(opts.agentProfile, error));
         process.exit(EXIT.AUTH);
       }