browser-pilot-cli 0.2.2 → 0.3.0-rc.1

package/README.md

@@ -28,6 +28,9 @@ a Chrome WebSocket and never display the Allow dialog.
 Use `bp connect --browser <id|product|channel>` for an explicit choice. Product
 embedders can pass the same selector to `browser-pilot bridge --stdio
 --browser <selector>`; otherwise selection follows a stable platform order.
+One connection covers every live Chrome Profile on that endpoint. When several
+Profiles are open, `bp connect` lists them without creating a Pilot window; use
+`bp profiles` and `bp profile <index>`, or pass `--profile` to `bp open --new`.
 
 ### 2. Install the plugin for your agent
 
@@ -66,6 +69,7 @@ The agent will use `bp` commands automatically. Your real login sessions are pre
 
 - **No extension required** — Uses Chrome 144's native remote debugging toggle, not the Extension Debugger API
 - **Real login sessions** — Operates your actual browser profile. Cookies, extensions, logins all intact
+- **Multi-Profile routing** — Lists user tabs across live Chrome Profiles and creates managed work only in a resolved Profile
 - **CLI-native** — Any agent with bash access can use it. No MCP protocol, no SDK integration needed
 - **Auto-snapshot** — Every action returns page state with numbered `[ref]` elements, so the agent always knows what's on screen
 - **Adaptive page views** — Bounded read, text search, DOM metadata, page geometry, and annotated screenshots let an agent choose the smallest useful representation
@@ -139,8 +143,9 @@ launching the bridge. Bulk cleanup remains limited to managed tabs, and user
 tabs remain open when a session ends.
 
 The `browser-pilot bridge --stdio` transport, Broker lifecycle, browser tool
-dispatch, event replay, protected Artifacts, and protocol 1.1 transport limit
-negotiation are implemented. Browser disconnect and explicit reconnect handling, scoped
+dispatch, event replay, protected Artifacts, protocol 1.1 transport limit
+negotiation, and protocol 1.2 Chrome Profile routing are implemented. Browser
+disconnect and explicit reconnect handling, scoped
 download Artifacts, Workspace resource isolation, and typed watchdog events for
 stalled navigation, selected-frame detach, pending dialogs, and repeated
 browser-observable no-progress actions are also implemented. Bounded page
@@ -177,7 +182,7 @@ A project can pin Browser Pilot locally and run the same CLI without a global
 installation:
 
 ```bash
-npm install --save-exact browser-pilot-cli@0.2.2
+npm install --save-exact browser-pilot-cli@0.3.0-rc.1
 npx --no-install browser-pilot tabs
 ```
 
@@ -205,6 +210,7 @@ an incompatible isolated Broker.
 | Command | Returns | Description |
 |---------|---------|-------------|
 | `bp open <url>` | snapshot | Navigate to URL |
+| `bp open <url> --new --profile <selector>` | snapshot | Create managed work in one live Chrome Profile |
 | `bp snapshot` | snapshot | Get interactive elements |
 | `bp read [selector]` | text | Get bounded readable page/region content |
 | `bp search <text>` | matches | Find bounded visible text and nearby context |
@@ -243,8 +249,9 @@ dialogs are scoped to the compatibility Workspace and isolated from embedded
 Broker clients.
 
 Run `bp tabs` to list Pilot-managed tabs, their popups, and eligible tabs the
-user opened elsewhere in the same browser. `bp tab <n>` switches control to any
-listed tab.
+user opened elsewhere across all live Profiles in the same browser endpoint.
+Each JSON entry includes its opaque `profileContextId`; `bp tab <n>` switches
+control to any listed tab.
 
 ### Network
 
@@ -263,8 +270,10 @@ listed tab.
 
 | Command | Description |
 |---------|-------------|
-| `bp connect` | Connect to Chrome, create pilot window |
+| `bp connect` | Connect to Chrome; create a Pilot window immediately only when Profile routing is unambiguous |
 | `bp disconnect` | Close the CLI Pilot window; stop the daemon when no embedded client is live |
+| `bp profiles` | List live Chrome Profile contexts and representative tabs |
+| `bp profile <index\|id\|label\|name>` | Select a Profile for subsequent managed tabs |
 | `bp tabs` | List all controllable tabs in the current browser |
 | `bp tab <n>` | Switch to any listed managed or user tab |
 | `bp close` | Close the current tab (`--all` closes Pilot-managed tabs only) |

package/dist/cli.js

@@ -6,7 +6,7 @@ import { writeFileSync as writeFileSync2, readFileSync as readFileSync4, existsS
 import { resolve as resolvePath } from "path";
 
 // src/version.ts
-var BROWSER_PILOT_VERSION = "0.2.2";
+var BROWSER_PILOT_VERSION = "0.3.0-rc.1";
 
 // src/protocol/errors.ts
 var ERROR_CODES = [
@@ -17,6 +17,9 @@ var ERROR_CODES = [
   "browser_not_authorized",
   "browser_disconnected",
   "broker_in_use",
+  "profile_selection_required",
+  "profile_context_stale",
+  "profile_context_unavailable",
   "workspace_not_found",
   "lease_expired",
   "target_not_owned",
@@ -1929,6 +1932,7 @@ function resultSchema(context, properties = {}, required = []) {
   }
   if (context === "target") {
     contextProperties.targetId = opaqueIdSchema;
+    contextProperties.profileContextId = opaqueIdSchema;
     contextProperties.url = boundedUrl;
     contextRequired.push("targetId", "url");
   }
@@ -2008,6 +2012,27 @@ var dropdownChoiceSchema = {
     }, ["by", "value"])
   ]
 };
+var profileRepresentativeTabSchema = objectSchema({
+  targetId: opaqueIdSchema,
+  title: sensitive(stringSchema({ maxLength: 4096 }), "browser_data"),
+  url: boundedUrl
+}, ["targetId", "title", "url"]);
+var profileContextSchema = objectSchema({
+  profileContextId: opaqueIdSchema,
+  label: stringSchema({ minLength: 1, maxLength: 128 }),
+  displayName: sensitive(stringSchema({ minLength: 1, maxLength: 4096 }), "browser_data"),
+  tabCount: integerSchema({ minimum: 0 }),
+  eligibleTabCount: integerSchema({ minimum: 0 }),
+  selected: booleanSchema(),
+  representativeTabs: arraySchema(profileRepresentativeTabSchema, { maxItems: 3 })
+}, [
+  "profileContextId",
+  "label",
+  "tabCount",
+  "eligibleTabCount",
+  "selected",
+  "representativeTabs"
+]);
 function tool(definition) {
   return definition;
 }
@@ -2067,6 +2092,40 @@ var TOOL_DEFINITIONS = [
     sensitivity: { input: [], output: ["browser_data"] },
     artifactKinds: []
   }),
+  tool({
+    name: "browser.profiles.list",
+    title: "List browser Profiles",
+    description: "Passively list live Profile contexts and bounded representative tabs.",
+    context: "workspace",
+    inputSchema: emptyInput,
+    outputSchema: resultSchema("workspace", {
+      profiles: arraySchema(profileContextSchema, { maxItems: 128 })
+    }, ["profiles"]),
+    requiredCapabilities: ["browser.control"],
+    mutating: false,
+    idempotency: "read_only",
+    cancellation: "not_applicable",
+    sensitivity: { input: [], output: ["browser_data"] },
+    artifactKinds: []
+  }),
+  tool({
+    name: "browser.profiles.select",
+    title: "Select browser Profile",
+    description: "Select one current Profile context for new managed targets in this Workspace.",
+    context: "workspace",
+    inputSchema: objectSchema({ profileContextId: opaqueIdSchema }, ["profileContextId"]),
+    outputSchema: resultSchema("workspace", {
+      profileContextId: opaqueIdSchema,
+      label: stringSchema({ minLength: 1, maxLength: 128 }),
+      displayName: sensitive(stringSchema({ minLength: 1, maxLength: 4096 }), "browser_data")
+    }, ["profileContextId", "label"]),
+    requiredCapabilities: ["browser.control"],
+    mutating: true,
+    idempotency: "idempotent",
+    cancellation: "before_dispatch",
+    sensitivity: { input: [], output: ["browser_data"] },
+    artifactKinds: []
+  }),
   tool({
     name: "browser.open",
     title: "Open URL",
@@ -2076,6 +2135,7 @@ var TOOL_DEFINITIONS = [
       url: boundedUrl,
       targetId: opaqueIdSchema,
       newTarget: booleanSchema(),
+      profileContextId: opaqueIdSchema,
       observationLimit: integerSchema({ minimum: 1, maximum: OBSERVATION_V1_LIMITS.maxElements })
     }, ["url"]),
     outputSchema: observationOutput,
@@ -2481,6 +2541,7 @@ var TOOL_DEFINITIONS = [
     outputSchema: resultSchema("workspace", {
       targets: arraySchema(objectSchema({
         targetId: opaqueIdSchema,
+        profileContextId: opaqueIdSchema,
         title: sensitive(stringSchema({ maxLength: 4096 }), "browser_data"),
         url: boundedUrl,
         active: booleanSchema(),
@@ -3180,7 +3241,7 @@ var CompatibilityBrokerClient = class _CompatibilityBrokerClient {
         version: executableVersion,
         instanceId: "local:one-shot"
       },
-      protocol: { min: { major: 1, minor: 1 }, max: { major: 1, minor: 1 } },
+      protocol: { min: { major: 1, minor: 1 }, max: { major: 1, minor: 2 } },
       requestedCapabilities: [...CAPABILITIES],
       launchMode: "one-shot"
     }), "initialize");
@@ -3229,6 +3290,24 @@ var CompatibilityBrokerClient = class _CompatibilityBrokerClient {
     }
     return result.targets;
   }
+  async listProfiles() {
+    const result = await this.callTool("browser.profiles.list");
+    if (!Array.isArray(result.profiles)) {
+      throw new BrowserPilotError("internal_error", "browser.profiles.list returned invalid Profiles");
+    }
+    return result.profiles;
+  }
+  async selectProfile(profileContextId) {
+    const result = await this.callTool("browser.profiles.select", { profileContextId });
+    const profiles = await this.listProfiles();
+    const selected = profiles.find((profile) => profile.profileContextId === result.profileContextId);
+    if (!selected) {
+      throw new BrowserPilotError("profile_context_stale", "Selected Profile context is no longer available", {
+        retryable: true
+      });
+    }
+    return selected;
+  }
   async ensureTarget() {
     const targets = await this.listTabs("all");
     const selected = targets.find((target) => target.active) ?? targets.find((target) => target.origin !== "user_tab");
@@ -3261,6 +3340,7 @@ var CompatibilityBrokerClient = class _CompatibilityBrokerClient {
     });
     return {
       targetId: opened.targetId,
+      profileContextId: opened.profileContextId,
       title: String(opened.title ?? ""),
       url: String(opened.url),
       active: true,
@@ -3411,7 +3491,10 @@ var program = new Command();
 program.name("bp").description("Control your browser from the command line").version(BROWSER_PILOT_VERSION).option("--human", "force human-readable output (default when TTY)").addHelpText("after", `
 Workflow:
   bp connect                          # one-time setup (click Allow in Chrome)
+  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
+  bp open <url> --new --profile <id>  # create managed work in one Profile
   bp click <ref>                      # interact \u2014 returns updated snapshot
   bp click --xy 400,300              # click at coordinates (canvas/maps)
   bp locate ".selector"              # get element coordinates for click --xy
@@ -3498,7 +3581,8 @@ function emitObservation(result) {
       truncated,
       truncationReasons,
       ...Array.isArray(result.hints) ? { hints: result.hints } : {},
-      ...result.evidence && typeof result.evidence === "object" ? { evidence: result.evidence } : {}
+      ...result.evidence && typeof result.evidence === "object" ? { evidence: result.evidence } : {},
+      ...typeof result.profileContextId === "string" ? { profileContextId: result.profileContextId } : {}
     }));
   } else {
     const lines = [`[page] ${title} | ${url}`, ""];
@@ -3576,6 +3660,40 @@ async function requireCompatibility() {
   if (!client) throw new Error("Not connected");
   return client;
 }
+async function resolveCliProfile(client, selector) {
+  const profiles = await client.listProfiles();
+  const exactId = profiles.find((profile) => profile.profileContextId === selector);
+  if (exactId) return exactId;
+  if (/^\d+$/.test(selector)) {
+    const index = Number(selector);
+    if (Number.isSafeInteger(index) && profiles[index]) return profiles[index];
+    throw invalidCliProfile(`Profile index out of range (0-${Math.max(0, profiles.length - 1)})`, selector);
+  }
+  const normalized = selector.trim().toLocaleLowerCase();
+  const matches = profiles.filter((profile) => profile.label.toLocaleLowerCase() === normalized || profile.displayName?.toLocaleLowerCase() === normalized);
+  if (matches.length === 1) return matches[0];
+  if (matches.length > 1) {
+    throw invalidCliProfile("Profile selector is ambiguous; use its index or Profile context ID", selector);
+  }
+  throw invalidCliProfile("Profile selector does not match a live Chrome Profile", selector);
+}
+function invalidCliProfile(message, selector) {
+  return new BrowserPilotError("invalid_argument", message, {
+    context: { field: "profile", selector }
+  });
+}
+function cliProfile(profile, index) {
+  return {
+    index,
+    profileContextId: profile.profileContextId,
+    label: profile.label,
+    ...profile.displayName ? { displayName: profile.displayName } : {},
+    tabCount: profile.tabCount,
+    eligibleTabCount: profile.eligibleTabCount,
+    selected: profile.selected,
+    representativeTabs: profile.representativeTabs
+  };
+}
 function withCliTarget(operation) {
   return withCompatibilityTarget(BROWSER_PILOT_VERSION, operation);
 }
@@ -3611,7 +3729,7 @@ 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 create pilot window").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", "\nExamples:\n  bp connect\n  bp connect --browser brave").action(action(async (opts) => {
   if (!useJson()) {
     console.log("Connecting to Chrome...");
     console.log(`If prompted, click "Allow" in Chrome's authorization dialog.
@@ -3619,10 +3737,20 @@ program.command("connect").description("Connect to Chrome and create pilot windo
   }
   const client = await connectCompatibility(BROWSER_PILOT_VERSION, opts.browser);
   await client.connectBrowser();
-  await client.ensureManagedTarget();
+  const profiles = await client.listProfiles();
+  if (profiles.length <= 1) await client.ensureManagedTarget();
   const browser = client.initialized.browsers.find((candidate) => candidate.state === "ready")?.product ?? "browser";
+  if (profiles.length > 1) {
+    const listed = profiles.map(cliProfile);
+    emit(
+      { ok: true, browser, profileSelectionRequired: true, profiles: listed },
+      `\u2713 Connected to ${browser}
+Multiple Chrome Profiles are open. Run 'bp profiles', then 'bp profile <index>'.`
+    );
+    return;
+  }
   emit(
-    { ok: true, browser },
+    { ok: true, browser, profileSelectionRequired: false },
     `\u2713 Connected to ${browser}
 \u2713 Pilot window ready (daemon running in background)
 
@@ -3652,13 +3780,54 @@ program.command("disconnect").description("Release CLI browser state and stop an
   await shutdownCompatibility(BROWSER_PILOT_VERSION);
   emit({ ok: true }, "\u2713 Disconnected");
 }));
-program.command("open <url>").description("Navigate to URL and return page snapshot").option("-n, --new", "open in new tab").option("-l, --limit <n>", "max elements in snapshot", "50").addHelpText("after", "\nExamples:\n  bp open https://github.com\n  bp open github.com --new\n  bp open https://example.com --limit 20").action(action(async (url, opts) => {
+program.command("profiles").description("List live Chrome Profile contexts").action(action(async () => {
+  const profiles = (await (await requireCompatibility()).listProfiles()).map(cliProfile);
+  if (useJson()) {
+    console.log(JSON.stringify({ ok: true, profiles }));
+    return;
+  }
+  if (profiles.length === 0) {
+    console.log("No live Chrome Profile contexts found.");
+    return;
+  }
+  for (const profile of profiles) {
+    const name = profile.displayName ? ` (${profile.displayName})` : "";
+    console.log(`${profile.selected ? "*" : " "} ${profile.index}  ${profile.label}${name}  ${profile.tabCount} tab(s)`);
+  }
+}));
+program.command("profile <selector>").description("Select a Chrome Profile context for new managed tabs").action(action(async (selector) => {
+  const client = await requireCompatibility();
+  const profile = await resolveCliProfile(client, String(selector));
+  const selected = await client.selectProfile(profile.profileContextId);
+  emit(
+    {
+      ok: true,
+      profileContextId: selected.profileContextId,
+      label: selected.label,
+      ...selected.displayName ? { displayName: selected.displayName } : {}
+    },
+    `\u2713 Selected ${selected.displayName ?? selected.label}`
+  );
+}));
+program.command("open <url>").description("Navigate to URL and return page snapshot").option("-n, --new", "open in new tab").option("--profile <selector>", "Profile index, ID, label, or verified display name (requires --new)").option("-l, --limit <n>", "max elements in snapshot", "50").addHelpText("after", "\nExamples:\n  bp open https://github.com\n  bp open github.com --new\n  bp open https://example.com --new --profile 1\n  bp open https://example.com --limit 20").action(action(async (url, opts) => {
   url = normalizeUrl(url);
   const limit = parseLimit(opts.limit);
+  if (opts.profile && !opts.new) throw new Error("--profile requires --new");
+  if (opts.new) {
+    const client = await requireCompatibility();
+    const profile = opts.profile ? await resolveCliProfile(client, String(opts.profile)) : void 0;
+    emitObservation(await client.callTool("browser.open", {
+      url,
+      newTarget: true,
+      ...profile ? { profileContextId: profile.profileContextId } : {},
+      observationLimit: limit
+    }));
+    return;
+  }
   await withCliTarget(async (client, target) => {
     const result = await client.callTool("browser.open", {
       url,
-      ...opts.new ? { newTarget: true } : { targetId: target.targetId },
+      targetId: target.targetId,
       observationLimit: limit
     });
     emitObservation(result);