@botbuddy/cli 1.14.0 → 1.16.0

package/package.json

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

package/src/auth.mjs

@@ -69,6 +69,12 @@ export async function doLogin(options = {}, deps = {}) {
   const noBrowser = Boolean(options.noBrowser);
   // BOT-1566: optional tenant preselection (validated by the argument parser).
   const tenant = typeof options.tenant === "string" && options.tenant ? options.tenant : null;
+  // BOT-1580: display-only caller identity hints. Forwarded to the authorization
+  // screen so the approver knows who requested the login; sanitized inside
+  // buildAuthorizeUrl. These never influence tenant, scope, or token minting.
+  const caller = typeof options.caller === "string" && options.caller ? options.caller : null;
+  const callerHarness = typeof options.callerHarness === "string" && options.callerHarness ? options.callerHarness : null;
+  const callerTicket = typeof options.callerTicket === "string" && options.callerTicket ? options.callerTicket : null;
 
   log(`${bold("BotBuddy OAuth Login")}\n`);
 
@@ -108,7 +114,7 @@ export async function doLogin(options = {}, deps = {}) {
 
     // AC-6/AC-7: build the authorization URL and always print it (headless users
     // open it themselves). The CLI never fetches /authorize.
-    const authUrl = buildAuthorizeUrl({ serverUrl, clientId, redirectUri, state, codeChallenge, tenant });
+    const authUrl = buildAuthorizeUrl({ serverUrl, clientId, redirectUri, state, codeChallenge, tenant, caller, callerHarness, callerTicket });
     log("");
     log(dim("→ Authorize BotBuddy in your browser:"));
     log(`  ${cyan(authUrl)}`);

package/src/commands.mjs

@@ -91,7 +91,7 @@ ${bold("OPTIONS")}
     --no-server              Don't auto-start codex app-server
 
 ${bold("AUTH")}
-  login [--no-browser] [--tenant <slug>]
+  login [--no-browser] [--tenant <slug>] [--caller <name>] [--caller-harness <h>] [--caller-ticket <ref>]
                              Authenticate via OAuth (opens browser + localhost callback)
   logout                     Remove saved credentials
   status                     Show current auth status (local metadata + server check)
@@ -176,7 +176,16 @@ export class LoginUsageError extends Error {
 // preselects the tenant on the OAuth picker; a malformed slug is a usage
 // error with exit code 2 (never sent to the server).
 export function parseLoginArgs(args) {
-  const out = { noBrowser: false, tenant: null, help: false };
+  const out = { noBrowser: false, tenant: null, help: false, caller: null, callerHarness: null, callerTicket: null };
+  // BOT-1580: display-only caller flags. Unlike --tenant they are free text (an
+  // unverified hint shown on the consent screen), so they are never validated
+  // into a usage error here — sanitization/length-capping happens when the URL is
+  // built. A value is taken verbatim from `--flag value` or `--flag=value`.
+  const CALLER_FLAGS = {
+    "--caller": "caller",
+    "--caller-harness": "callerHarness",
+    "--caller-ticket": "callerTicket",
+  };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === "--help" || arg === "-h") { out.help = true; continue; }
@@ -189,6 +198,31 @@ export function parseLoginArgs(args) {
       out.tenant = value;
       continue;
     }
+    let matchedCaller = false;
+    for (const [flag, key] of Object.entries(CALLER_FLAGS)) {
+      if (arg === flag || arg.startsWith(`${flag}=`)) {
+        let value;
+        if (arg.startsWith(`${flag}=`)) {
+          // `--flag=value` takes the value verbatim (an explicit leading dash is
+          // the user's own choice, e.g. --caller=--weird).
+          value = arg.slice(`${flag}=`.length);
+        } else {
+          // `--flag value`: the next token is the value only if it exists and is
+          // not itself an option. Otherwise it would silently swallow the next
+          // flag (e.g. `--caller --no-browser` would set caller="--no-browser"
+          // and drop --no-browser) — reject that as a usage error instead.
+          value = args[i + 1];
+          if (typeof value !== "string" || value.startsWith("-")) {
+            throw new LoginUsageError(`error: ${flag} requires a value`, { exitCode: 2 });
+          }
+          i++;
+        }
+        out[key] = value;
+        matchedCaller = true;
+        break;
+      }
+    }
+    if (matchedCaller) continue;
     if (arg.startsWith("-")) {
       throw new LoginUsageError(`Unknown login option: ${arg}. Run ${cyan("botbuddy login --help")}.`);
     }
@@ -196,6 +230,26 @@ export function parseLoginArgs(args) {
   return out;
 }
 
+// BOT-1580: resolve the caller identity from parsed flags, falling back to the
+// BOTBUDDY_CALLER* environment variables so an agent harness can advertise who it
+// is without every wrapper having to pass flags. A flag always wins over the env.
+// Returns only the three caller fields; empty values collapse to null.
+export function resolveCaller(parsed = {}, env = {}) {
+  const pick = (flagVal, envKey) => {
+    // A flag that was PROVIDED wins over the environment, even when it is an
+    // explicit empty `--caller=` — that is how a user clears a stale inherited
+    // identity, so it must NOT fall back to the env. `null` means the flag was
+    // omitted → fall back to the env var. Either way an empty result is null.
+    const raw = flagVal != null ? flagVal : env[envKey];
+    return typeof raw === "string" && raw !== "" ? raw : null;
+  };
+  return {
+    caller: pick(parsed.caller, "BOTBUDDY_CALLER"),
+    callerHarness: pick(parsed.callerHarness, "BOTBUDDY_CALLER_HARNESS"),
+    callerTicket: pick(parsed.callerTicket, "BOTBUDDY_CALLER_TICKET"),
+  };
+}
+
 // BOT-1383: login now runs the RFC 8252 loopback flow (opens the browser,
 // waits for the localhost callback). Parse --no-browser / --tenant and print
 // focused help.
@@ -209,8 +263,10 @@ async function cmdLogin(args, { errorLog = (line) => console.error(line) } = {})
     die(err.message);
   }
   if (options.help) return loginHelp();
+  // BOT-1580: merge caller flags with the BOTBUDDY_CALLER* env fallback.
+  const caller = resolveCaller(options, process.env);
   try {
-    await doLogin({ noBrowser: options.noBrowser, tenant: options.tenant });
+    await doLogin({ noBrowser: options.noBrowser, tenant: options.tenant, ...caller });
   } catch (err) {
     die(err.message);
   }
@@ -221,6 +277,7 @@ function loginHelp() {
 
 ${bold("USAGE")}
   botbuddy login [--no-browser] [--tenant <slug>]
+                 [--caller <name>] [--caller-harness <harness>] [--caller-ticket <ref>]
 
 ${bold("HOW IT WORKS")}
   Starts a localhost callback listener on an ephemeral 127.0.0.1 port, opens
@@ -238,6 +295,20 @@ ${bold("OPTIONS")}
                  Preselect a tenant (e.g. ${cyan("supply-guard")}) on the sign-in page when
                  your account belongs to more than one. Must be a lowercase slug;
                  membership is still enforced by the server.
+  --caller <name>
+                 Show WHO requested this login on the authorization screen, so
+                 the human approving it can confirm the request came from the
+                 agent/session they are actually running. Display-only and
+                 unverified — it never affects the tenant, scope, or token.
+  --caller-harness <harness>
+                 Optional harness label shown next to the caller (e.g.
+                 ${cyan("claude-code")}, ${cyan("codex")}).
+  --caller-ticket <ref>
+                 Optional ticket the caller is working on. A full
+                 ${dim("https://linear.app/…")} URL is shown as a link; anything else is
+                 shown as plain text.
+                 ${dim("Each --caller* value also falls back to $BOTBUDDY_CALLER,")}
+                 ${dim("$BOTBUDDY_CALLER_HARNESS and $BOTBUDDY_CALLER_TICKET.")}
 
 ${bold("NOTES")}
   • The authorization URL is always printed so you can open it manually.
@@ -264,14 +335,19 @@ async function cmdStart(args) {
   // (owner token from `login`, agent key from `profile setup`), so probe those
   // rather than a plaintext config secret.
   try {
+    // BOT-1580: the auto-login path has no --caller flags of its own, but a
+    // harness that exports BOTBUDDY_CALLER* should still be identified on the
+    // authorization screen. Resolve the caller from the environment and forward
+    // it, exactly as `botbuddy login` does.
+    const caller = resolveCaller({}, process.env);
     const owner = await resolveOwnerToken({ getConfig });
     const agentKey = owner ? null : await resolveAgentKey();
     if (!owner && !agentKey) {
       console.log(dim("→ No credentials found. Starting login...\n"));
-      await doLogin();
+      await doLogin({ ...caller });
     } else if (owner && owner.expiresAt && owner.expiresAt <= Date.now() && !(await resolveAgentKey())) {
       console.log(dim("→ Token expired. Re-authenticating...\n"));
-      await doLogin();
+      await doLogin({ ...caller });
     }
   } catch (err) {
     die(err.message);

package/src/oauth-loopback.mjs

@@ -44,9 +44,43 @@ export function generateState() {
   return randomBytes(16).toString("hex");
 }
 
+// BOT-1580: display-only caller identity is UNTRUSTED text. Sanitize it before
+// it ever enters the authorize URL: strip control characters (they can break the
+// consent-screen layout or smuggle terminal escapes into any log that echoes the
+// URL) and cap the length. Returns the cleaned string, or null when nothing
+// printable remains — so an absent/blank/garbage field is simply omitted rather
+// than rendered as an empty or fabricated identity. This is defense in depth; the
+// web consent screen sanitizes again at render time and never trusts this hint
+// for tenant selection, scope, or token minting.
+export function sanitizeCallerField(value, maxLen = 200) {
+  if (typeof value !== "string") return null;
+  // Strip Unicode control (C0/C1/DEL), format (bidi overrides, zero-width, BOM,
+  // soft hyphen), and line/paragraph separators — an untrusted caller must not be
+  // able to alter line breaking or visual ordering on the consent screen — while
+  // preserving legitimate visible non-ASCII in names.
+  const cleaned = value.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, "").trim();
+  if (!cleaned) return null;
+  return cleaned.slice(0, maxLen);
+}
+
+// BOT-1580: length caps per caller field. Names and harnesses are short labels;
+// a ticket may be a full Linear URL, so it gets more headroom.
+export const CALLER_FIELD_LIMITS = { name: 80, harness: 40, ticket: 200 };
+
 // AC-6/AC-7: build the complete /authorize URL. The browser follows it; the CLI
 // never fetches it. `redirectUri` must be the exact loopback callback we bound.
-export function buildAuthorizeUrl({ serverUrl, clientId, redirectUri, state, codeChallenge, scope = "read write lock", tenant = null }) {
+export function buildAuthorizeUrl({
+  serverUrl,
+  clientId,
+  redirectUri,
+  state,
+  codeChallenge,
+  scope = "read write lock",
+  tenant = null,
+  caller = null,
+  callerHarness = null,
+  callerTicket = null,
+}) {
   const url = new URL(`${serverUrl}/authorize`);
   url.searchParams.set("client_id", clientId);
   url.searchParams.set("redirect_uri", redirectUri);
@@ -59,6 +93,16 @@ export function buildAuthorizeUrl({ serverUrl, clientId, redirectUri, state, cod
   // it to the /mcp-auth picker as `requestedTenant`; membership is still
   // enforced server-side at authorize_complete — this only preselects.
   if (tenant) url.searchParams.set("tenant", tenant);
+  // BOT-1580: display-only caller identity, so the human approving the login can
+  // check it against the agent session they are actually running. These are
+  // UNVERIFIED hints — /authorize only forwards them to the consent screen; they
+  // never influence tenant, scope, or the minted token.
+  const callerName = sanitizeCallerField(caller, CALLER_FIELD_LIMITS.name);
+  const harness = sanitizeCallerField(callerHarness, CALLER_FIELD_LIMITS.harness);
+  const ticket = sanitizeCallerField(callerTicket, CALLER_FIELD_LIMITS.ticket);
+  if (callerName) url.searchParams.set("caller", callerName);
+  if (harness) url.searchParams.set("caller_harness", harness);
+  if (ticket) url.searchParams.set("caller_ticket", ticket);
   return url.toString();
 }