browser-pilot-cli 0.5.0 → 0.5.1

package/README.md

@@ -25,15 +25,23 @@ Inspect installed browsers without requesting authorization:
 bp browsers
 ```
 
-Connect when browser work is needed:
+Follow the returned remediation first. Start the selected browser or enable
+remote debugging when requested. Browser Pilot does not connect automatically.
+
+When the browser is ready and browser work is needed, tell the user to watch
+for Chrome's Allow dialog, then connect once:
 
 ```bash
-bp connect
+bp connect --browser <browser-id>
 ```
 
 Chrome may display one Allow dialog for the browser connection. Browser
 discovery and background-service startup are passive. Concurrent clients share
 one pending connection request, so they do not create an authorization loop.
+Machine-readable `bp connect` output is emitted after the attempt finishes, so
+an Agent must show the Allow reminder before invoking the command. A timeout or
+`browser_not_authorized` result must be inspected; it is not a reason to loop
+connection attempts.
 
 ### 2. Install the Agent skill
 

package/dist/cli.js

@@ -6,7 +6,7 @@ import { writeFileSync as writeFileSync2, readFileSync as readFileSync4, existsS
 import { basename as basename2, isAbsolute as isAbsolute3, resolve as resolvePath } from "path";
 
 // src/version.ts
-var BROWSER_PILOT_VERSION = "0.5.0";
+var BROWSER_PILOT_VERSION = "0.5.1";
 
 // src/protocol/errors.ts
 var ERROR_CODES = [
@@ -1435,12 +1435,6 @@ async function resumeCompatibility(executableVersion, clientKey = CLIENT_KEY, in
     return null;
   }
 }
-async function withCompatibilityTarget(executableVersion, operation, clientKey = CLIENT_KEY, invocation = {}) {
-  const client = await resumeCompatibility(executableVersion, clientKey, invocation);
-  if (!client) throw new Error("Not connected");
-  const target = await client.ensureTarget();
-  return operation(client, target);
-}
 async function shutdownCompatibility(executableVersion, clientKey = CLIENT_KEY) {
   if (!isDaemonRunning()) return;
   const daemon = new DaemonClient();
@@ -1473,7 +1467,9 @@ var program = new Command();
 program.exitOverride();
 program.name("bp").description("Control your browser from the command line").version(BROWSER_PILOT_VERSION).option("--human", "force human-readable output (default when TTY)").option("--client-key <key>", "stable namespace for Agent browser state").option("--request-id <id>", "stable host request ID for safe retry recovery").option("--timeout <ms>", "browser command deadline in milliseconds", "60000").addHelpText("after", `
 Workflow:
-  bp connect                          # one-time setup (click Allow in Chrome)
+  bp status                           # inspect connection state without requesting authorization
+  bp browsers                         # inspect browser setup without requesting authorization
+  bp connect --browser <id>           # connect once after setup (click Allow in Chrome if prompted)
   bp profiles                         # list live Chrome Profile contexts
   bp profile <index>                  # route new managed tabs to one Profile
   bp open <url>                       # navigate \u2014 returns snapshot with [ref] numbers
@@ -1560,8 +1556,11 @@ function fail(error, hint, details) {
     ...stable.context ? { context: stable.context } : {},
     ...stable.remediation ? { remediation: stable.remediation } : {}
   }));
-  else console.error(`\u2717 ${error}${hint ? `
-  hint: ${hint}` : ""}`);
+  else {
+    const guidance = hint ?? stable.remediation?.message;
+    console.error(`\u2717 ${error}${guidance ? `
+  action: ${guidance}` : ""}`);
+  }
   process.exit(receivedSignal === "SIGINT" ? 130 : receivedSignal === "SIGTERM" ? 143 : 1);
 }
 function observationElements(result) {
@@ -1617,7 +1616,11 @@ function action(fn) {
       fail(msg, "Run 'bp snapshot' to refresh element refs.", stable);
     }
     if (stable.code === "browser_disconnected") {
-      fail(msg, "Run 'bp connect' first.", stable);
+      fail(
+        msg,
+        stable.remediation ? void 0 : "Run 'bp browsers', follow its setup remediation, then connect once.",
+        stable
+      );
     }
     if (stable.code === "unknown_outcome") {
       fail(msg, "Inspect the current tab state before deciding whether to retry.", stable);
@@ -1770,16 +1773,31 @@ async function cliElementAddress(client, target, raw) {
   if (!raw.trim()) throw invalidArgument("Element target must not be empty", "target");
   return { selector: raw };
 }
+async function disconnectedBrowserSetup() {
+  const discovered = await discoverBrowserCandidates();
+  const selected = discovered.find((candidate) => candidate.endpoint !== void 0) ?? discovered[0];
+  return {
+    discovered,
+    selected,
+    remediation: selected?.candidate.remediation ?? {
+      code: "connect_browser",
+      message: "Run 'bp browsers', follow its setup remediation, then run one explicit 'bp connect'.",
+      actionRequired: true
+    }
+  };
+}
 async function requireCompatibility() {
   const client = await resumeCompatibility(BROWSER_PILOT_VERSION, cliClientKey(), cliInvocationOptions());
   if (!client) {
+    const setup = await disconnectedBrowserSetup();
     throw new BrowserPilotError("browser_disconnected", "Browser Pilot is not connected", {
       retryable: true,
-      remediation: {
-        code: "connect_browser",
-        message: "Run 'bp connect', complete Chrome authorization if prompted, then retry.",
-        actionRequired: true
-      }
+      context: setup.selected ? {
+        browserId: setup.selected.candidate.id,
+        product: setup.selected.candidate.product,
+        browserState: setup.selected.candidate.state
+      } : void 0,
+      remediation: setup.remediation
     });
   }
   return client;
@@ -1824,8 +1842,10 @@ function cliProfile(profile, index) {
     representativeTabs: profile.representativeTabs
   };
 }
-function withCliTarget(operation) {
-  return withCompatibilityTarget(BROWSER_PILOT_VERSION, operation, cliClientKey(), cliInvocationOptions());
+async function withCliTarget(operation) {
+  const client = await requireCompatibility();
+  const target = await client.ensureTarget();
+  return operation(client, target);
 }
 function readStdin() {
   if (process.stdin.isTTY) return Promise.resolve("");
@@ -1841,7 +1861,9 @@ program.command("status").description("Show current Broker, browser, Agent names
   const brokerRunning = isDaemonRunning();
   const client = await resumeCompatibility(BROWSER_PILOT_VERSION, cliClientKey(), cliInvocationOptions());
   if (!client) {
-    const browsers = (await discoverBrowserCandidates()).map((discovered) => discovered.candidate);
+    const setup = await disconnectedBrowserSetup();
+    const browsers = setup.discovered.map((candidate) => candidate.candidate);
+    const action2 = setup.remediation.message;
     emit({
       ok: true,
       service: { state: brokerRunning ? "unavailable" : "stopped", version: BROWSER_PILOT_VERSION },
@@ -1851,9 +1873,11 @@ program.command("status").description("Show current Broker, browser, Agent names
       recovery: {
         required: true,
         code: "browser_disconnected",
-        action: "bp connect"
+        action: action2
       }
-    }, brokerRunning ? "Browser Pilot Broker is running, but the browser session is unavailable." : "Browser Pilot is not connected. Run bp connect.");
+    }, brokerRunning ? `Browser Pilot Broker is running, but the browser session is unavailable.
+Action: ${action2}` : `Browser Pilot is not connected.
+Action: ${action2}`);
     return;
   }
   const [activeCommands, uncertainCommands] = await Promise.all([
@@ -2063,7 +2087,16 @@ program.command("browsers").description("List supported local browsers and their
     return details.join("\n");
   }).join("\n\n"));
 }));
-program.command("connect").description("Connect to Chrome and prepare unambiguous managed browsing").option("-b, --browser <name>", "browser to connect to").addHelpText("after", "\nExamples:\n  bp connect\n  bp connect --browser brave").action(action(async (opts) => {
+program.command("connect").description("Connect to Chrome and prepare unambiguous managed browsing").option("-b, --browser <name>", "browser to connect to").addHelpText("after", [
+  "",
+  "Preparation:",
+  "  Run bp browsers and complete its setup remediation first.",
+  "  If an Agent invokes this command, it must tell the user about the possible Allow dialog before the call.",
+  "",
+  "Examples:",
+  "  bp connect",
+  "  bp connect --browser brave"
+].join("\n")).action(action(async (opts) => {
   if (!useJson()) {
     console.log("Connecting to Chrome...");
     console.log(`If prompted, click "Allow" in Chrome's authorization dialog.

package/dist/daemon.js

@@ -3680,7 +3680,12 @@ var MemoryBrokerRuntime = class {
     if (!binding || !isBrowserConnectTool && binding.instance.state !== "connected") {
       throw new BrowserPilotError("browser_disconnected", "Workspace browser is disconnected", {
         retryable: true,
-        context: workspaceRecord ? { workspaceId: workspaceRecord.value.id } : void 0
+        context: workspaceRecord ? { workspaceId: workspaceRecord.value.id } : void 0,
+        remediation: binding?.candidate.remediation ?? {
+          code: "connect_browser",
+          message: "Run 'bp browsers', follow its setup remediation, then run one explicit 'bp connect'.",
+          actionRequired: true
+        }
       });
     }
     const isBrowserConnectionAttempt = isBrowserConnectTool && binding.instance.state !== "connected";
@@ -14311,7 +14316,7 @@ var ManagedTargetJanitorClient = class {
 };
 
 // src/version.ts
-var BROWSER_PILOT_VERSION = "0.5.0";
+var BROWSER_PILOT_VERSION = "0.5.1";
 
 // src/daemon.ts
 var CLI_EXECUTABLE_PATH = publicExecutablePath(import.meta.url);

package/docs/releases/v0.5.1.md

@@ -0,0 +1,30 @@
+# Browser Pilot 0.5.1
+
+Browser Pilot 0.5.1 makes disconnected-browser recovery explicit and prevents
+Agents from creating repeated Chrome authorization prompts when remote
+debugging is not ready.
+
+## Deliberate connection flow
+
+- `bp status` and `bp browsers` remain passive setup checks and never request
+  Chrome authorization.
+- Disconnected browser commands preserve the selected browser candidate's
+  structured remediation, including `start_browser`,
+  `enable_remote_debugging`, and `restart_remote_debugging`.
+- `bp status` reports the same actionable setup message instead of always
+  suggesting another connection attempt.
+- Human CLI output labels structured recovery guidance as an action, while
+  JSON output keeps the stable `code`, `retryable`, and `remediation` contract.
+- Target commands now share the same connection requirement and return
+  `browser_disconnected` instead of exposing an internal not-connected error.
+
+## Agent guidance
+
+- The Browser Pilot skill checks status first, inspects browser candidates only
+  when disconnected, and follows the returned remediation before connecting.
+- Agents must warn the user about Chrome's possible Allow dialog before the
+  shell call, then issue exactly one explicit `bp connect --browser <id>`.
+- Connection timeouts, interruptions, and authorization failures require state
+  inspection; they never authorize a blind or concurrent connect loop.
+- Multiple ready browser candidates are selected explicitly rather than by an
+  ambiguous default.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-pilot-cli",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "CLI tool to control your browser via Chrome DevTools Protocol",
   "repository": "https://github.com/relixiaobo/browser-pilot",
   "type": "module",