@botbuddy/cli 1.57.0 → 1.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.57.0",
+  "version": "1.58.0",
   "description": "BotBuddy \u2014 Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {

package/src/deep-link.mjs

@@ -0,0 +1,24 @@
+// BOT-2468 — the dashboard deeplink for what this command just created (a stack
+// lease or a wait). The server answers `web_url` (built from its BOTBUDDY_WEB_URL
+// origin, null when that is unset); the CLI prints it on ONE stderr line telling the
+// agent to show it to the user, and carries it on the JSON receipt. A missing or
+// unsafe value prints nothing: there is no client-side fallback host.
+
+/** The server's `web_url` when it is a plain http(s) URL safe to print, else null.
+ *  Whitespace and control characters are refused so a hostile value cannot inject
+ *  terminal escapes or split the line. */
+export function safeWebUrl(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 2048) return null;
+  if (/[\s\u0000-\u001f\u007f]/.test(value)) return null;
+  let parsed;
+  try { parsed = new URL(value); } catch { return null; }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return null;
+  return value;
+}
+
+/** `<prefix>: 🔗 <url> — show this link …`, or null when there is no safe URL. */
+export function deepLinkNotice(prefix, webUrl) {
+  const url = safeWebUrl(webUrl);
+  if (!url) return null;
+  return `${prefix}: 🔗 ${url} — show this link to the user as a clickable Markdown link in your chat reply`;
+}

package/src/stack.mjs

@@ -36,6 +36,7 @@ import { basename, dirname, join, relative, isAbsolute } from "path";
 import { randomUUID } from "crypto";
 import { fileURLToPath } from "url";
 import { callToolJson, CALL_AUTH_ERROR_CODES } from "./api.mjs";
+import { deepLinkNotice, safeWebUrl } from "./deep-link.mjs";
 import { SERVER_URL, getConfig } from "./config.mjs";
 import { resolveOwnerToken, resolveAgentKey } from "./cli-credentials.mjs";
 import { AGENT_KEY_RE, readAgentSessionTokenEnv } from "./agent-key.mjs";
@@ -2298,6 +2299,11 @@ export async function cmdUp(opts, {
   }
   let leaseId = d.lease_id;
   let state = d.state;
+  // BOT-2468: the lease's /docker?lease= deeplink, printed once as soon as the id is known
+  // and carried on every receipt that names this lease (null from a server without one).
+  const webUrl = safeWebUrl(d.web_url);
+  const linkNotice = deepLinkNotice("bb stack", webUrl);
+  if (linkNotice) process.stderr.write(`${linkNotice}\n`);
   // BOT-2099: every lease wait in `stack up` (queue park, Helper provision, Helper takeover)
   // survives auth/availability blips (parkOnLease) and adopts the re-minted credential.
   const resilientWait = async (isDone, isFailed) => {
@@ -2330,7 +2336,10 @@ export async function cmdUp(opts, {
     error: `${r.error}; its server state is unknown to this command — inspect it with \`bb stack status ${leaseId}\` after \`bb doctor --fix\``,
   }), opts, EXIT.AUTH);
   const emitPlain = emitResult;
-  emitResult = (receipt, o, code) => emitPlain(upIncident && !receipt.platform_incident ? { ...receipt, platform_incident: upIncident } : receipt, o, code);
+  emitResult = (receipt, o, code) => {
+    const withIncident = upIncident && !receipt.platform_incident ? { ...receipt, platform_incident: upIncident } : receipt;
+    return emitPlain(withIncident.lease_id === leaseId && !("web_url" in withIncident) ? { ...withIncident, web_url: webUrl } : withIncident, o, code);
+  };
   // BOT-1711 (Codex R13): request_stack_lease returned an EXISTING active lease (reused),
   // rather than a freshly minted queued/provisioning one. A reused lease was not provisioned
   // in this invocation, so its recorded metadata cannot be trusted for a local-exec target.
@@ -3041,7 +3050,7 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
   // A receipt always says what happened to a port-block claim. Before allocation
   // no claim exists, which is a safe, explicit disposition rather than omission.
   // BOT-1803: whether this run re-adopted / re-provisioned an idle lease, and its stack digest.
-  const incidentBox = { incident: null, execution: null, idleLease: null, portBlock: { released: false, reason: "no port-block claim was created before stack allocation" } };
+  const incidentBox = { incident: null, execution: null, idleLease: null, webUrl: null, portBlock: { released: false, reason: "no port-block claim was created before stack allocation" } };
   let result;
   try {
     result = await runStackLifecycleOnce(opts, childArgv, adapters, incidentBox);
@@ -3051,7 +3060,8 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
   const withIncident = incidentBox.incident && !result?.incident ? { ...result, incident: incidentBox.incident } : result;
   const withExecution = incidentBox.execution && !withIncident?.execution ? { ...withIncident, execution: incidentBox.execution } : withIncident;
   const withIdle = incidentBox.idleLease && !withExecution?.idleLease ? { ...withExecution, idleLease: incidentBox.idleLease } : withExecution;
-  return incidentBox.portBlock && !withIdle?.portBlock ? { ...withIdle, portBlock: incidentBox.portBlock } : withIdle;
+  const withPortBlock = incidentBox.portBlock && !withIdle?.portBlock ? { ...withIdle, portBlock: incidentBox.portBlock } : withIdle;
+  return incidentBox.webUrl && withPortBlock && !withPortBlock.webUrl ? { ...withPortBlock, webUrl: incidentBox.webUrl } : withPortBlock;
 }
 
 async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
@@ -3514,6 +3524,10 @@ async function runStackLifecycleOnce(opts, childArgv, adapters, incidentBox) {
       };
     }
     leaseId = request.data.lease_id;
+    // BOT-2468: the lease's /docker?lease= deeplink, printed once as soon as the id is known.
+    incidentBox.webUrl = safeWebUrl(request.data.web_url);
+    const linkNotice = deepLinkNotice("bb stack", incidentBox.webUrl);
+    if (linkNotice) stderrLine(linkNotice);
     // BOT-1803: `reused_idle` — the slot's IDLE lease was re-adopted: it is active with its
     // stored connection and nothing is provisioned, so the run goes straight on to the
     // post-activation flow. Any other reuse is somebody's LIVE batch, refused as before.
@@ -3918,6 +3932,8 @@ export function runReceiptFields(result) {
     // BOT-1797: carry the server's typed refusal code (e.g. stack_path_root_refused)
     // so automation can branch on it instead of matching the message text.
     command: "run", outcome: result.outcome, code: result.code ?? null, lease_id: result.leaseId ?? null,
+    // BOT-2468: the lease's /docker?lease= deeplink (null when the server sent none).
+    web_url: result.webUrl ?? null,
     // BOT-2024: a stale-capacity refusal carries its phase + armable wait on the receipt.
     ...capacityStaleReceiptFields(result),
     ...(result.wait_exit_code != null ? { wait_exit_code: result.wait_exit_code, wait_receipt: result.wait_receipt ?? null } : {}),

package/src/wait.mjs

@@ -25,6 +25,7 @@ import { touchAgentStateExpiry } from "./agent-state.mjs";
 import { SETUP_BLOCK } from "./setup-block.mjs";
 import { createWaitCheckpointStore, WaitCheckpointError } from "./wait-checkpoint.mjs";
 import { realpath } from "node:fs/promises";
+import { deepLinkNotice, safeWebUrl } from "./deep-link.mjs";
 
 // A protocol is deliberately distinct from package semver: compatible pinned
 // clients keep working until the server raises this minimum, while a stale
@@ -537,6 +538,9 @@ async function registerWait(opts, conditions, deadlineIso) {
     // unmatchable alias registration.
     recoveryError: typeof body.recovery_error === "string" ? body.recovery_error : null,
     terminalReceipt: body.terminal_receipt && typeof body.terminal_receipt === "object" ? body.terminal_receipt : null,
+    // BOT-2468: the wait's /waits?wait= deeplink (null from a relay without BOTBUDDY_WEB_URL;
+    // absent from a pre-BOT-2468 relay — both print no link line).
+    webUrl: safeWebUrl(body.web_url),
   };
 }
 
@@ -843,8 +847,11 @@ function publicWaitReceipt(receipt, {
   sessionAgentId = null,
   sessionId = null,
   maxBytes = 10240,
+  // BOT-2468: the registered wait's deeplink; undefined (no relay registration) omits the field.
+  webUrl = undefined,
 } = {}) {
-  return truncateReceipt(withClientIdentity(withPrincipalReceipt(receipt, null, {
+  const linked = webUrl === undefined || (receipt && "web_url" in receipt) ? receipt : { ...receipt, web_url: webUrl };
+  return truncateReceipt(withClientIdentity(withPrincipalReceipt(linked, null, {
     sessionTenant,
     agentId,
     sessionAgentId,
@@ -1760,6 +1767,9 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
   // register and reused as the timeout receipt's error. Null when there is
   // nothing to report (no ci scope=next+branch condition, or no run yet).
   let ciArmNotice = null;
+  // BOT-2468: the wait's /waits?wait= deeplink from register; stays undefined when the
+  // wait never registered (live-only/offline), so its receipt carries no web_url key.
+  let registeredWebUrl;
   let replayMatchedClaim = false;
   let replayExpiredRecovery = false;
   if (needsRelay) {
@@ -1809,6 +1819,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
       registeredAgentId = reg.agentId;
       registeredSessionAgentId = reg.sessionAgentId;
       registeredSessionId = reg.sessionId;
+      registeredWebUrl = reg.webUrl ?? null;
       // A freshly minted session token may represent the same immutable agent,
       // but never a different tenant/agent or worktree. Check before exposing a
       // result or opening the SSE stream.
@@ -1841,7 +1852,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
       if (reg.terminalReceipt) {
         const recovered = preserveCheckpointCursor(publicWaitReceipt(reg.terminalReceipt, {
           sessionTenant, agentId: registeredAgentId, sessionAgentId: registeredSessionAgentId,
-          sessionId: registeredSessionId, maxBytes: opts.receiptMaxBytes,
+          sessionId: registeredSessionId, maxBytes: opts.receiptMaxBytes, webUrl: registeredWebUrl,
         }), checkpoint.safe_cursor, checkpoint.created_at);
         const recoveredCancellation = recovered.outcome === "cancelled";
         await store.update(checkpoint.local_wait_id, {
@@ -1858,6 +1869,11 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
         emitReceipt(recovered, { versioned: true });
         process.exit(exitForRecoveredOutcome(recovered));
       }
+      // BOT-2468: the wait's dashboard deeplink, once, at arm time (and again on
+      // `bb wait resume`, which re-registers). An agent that armed this in the
+      // background reads this first 🔗 line once and posts the link in its chat.
+      const linkNotice = deepLinkNotice("bb-wait", registeredWebUrl);
+      if (linkNotice) process.stderr.write(`${linkNotice}\n`);
       // BOT-1539: if any pr-review/pr-state target already has an outstanding
       // review, tell the operator now (stderr, one line per PR). Purely
       // informational — it does not change arming or exit semantics.
@@ -2104,6 +2120,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
     sessionAgentId: registeredSessionAgentId,
     sessionId: registeredSessionId,
     maxBytes: opts.receiptMaxBytes,
+    webUrl: registeredWebUrl,
   });
   let terminalPersistedFromFrame = false;