pi-browser-harness 0.10.2 → 0.11.0

package/src/domains/tabs.ts

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
 import { type Result, err, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { cdpCallBrowser } from "./cdp-call";
 
 const ListTabsArgs = Type.Object({
   includeInternal: Type.Optional(Type.Boolean({ default: true, description: "Include chrome:// pages" })),
@@ -24,6 +25,7 @@ export const listTabsTool = defineBrowserTool({
     "Internal tabs (chrome://) included by default; pass includeInternal=false to exclude them.",
   ],
   parameters: ListTabsArgs,
+  concurrency: "parallel",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const r = await client.listTabs(args.includeInternal ?? true);
     if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
@@ -50,12 +52,13 @@ export const currentTabTool = defineBrowserTool({
   promptSnippet: "Get current tab info",
   promptGuidelines: ["Returns targetId, url, title, and whether the tab is owned by this harness session."],
   parameters: Type.Object({}),
+  concurrency: "parallel",
   async handler(_a, { client }): Promise<Result<ToolOk, ToolErr>> {
     const cur = client.current();
     if (!cur) return err({ kind: "invalid_state", message: "No tab attached." });
-    const ti = await client.session().callBrowser("Target.getTargetInfo", { targetId: cur.targetId });
-    if (!ti.success) return err({ kind: "cdp_error", message: ti.error.message });
-    const info = (ti.data as { targetInfo: { targetId: string; url: string; title: string } }).targetInfo; // CDP boundary cast: Target.getTargetInfo returns { targetInfo: { targetId, url, title } }
+    const ti = await cdpCallBrowser(client, "Target.getTargetInfo", { targetId: cur.targetId });
+    if (!ti.success) return ti;
+    const info = ti.data.targetInfo;
     const owned = client.owns(info.targetId);
     return ok({
       text: `Current tab${owned ? " (owned)" : " (NOT owned by this session)"}:\n  ${info.targetId}\n  ${info.url}\n  ${info.title}`,
@@ -83,9 +86,8 @@ export const switchTabTool = defineBrowserTool({
     "Refuses tabs not owned by this session — use browser_new_tab to open a controllable tab instead.",
   ],
   parameters: SwitchTabArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
-    // Resolve to a concrete targetId (exact, or unique hex prefix). We resolve
-    // first so the ownership check sees the canonical id, not the prefix.
     let resolved = args.targetId;
     if (!client.owns(resolved)) {
       const isHexPrefix = /^[0-9A-Fa-f]{8,}$/.test(args.targetId);
@@ -104,7 +106,9 @@ export const switchTabTool = defineBrowserTool({
             details: { matches: matches.map((t) => ({ targetId: t.targetId, url: t.url })) },
           });
         }
-        resolved = matches[0]!.targetId;
+        const first = matches[0];
+        if (first === undefined) return err({ kind: "invalid_state", message: "no matching tab" });
+        resolved = first.targetId;
       }
       if (!client.owns(resolved)) {
         return err({
@@ -139,6 +143,7 @@ export const newTabTool = defineBrowserTool({
     "Pass url to navigate immediately.",
   ],
   parameters: NewTabArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const r = await client.newTab(args.url);
     if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
@@ -165,6 +170,7 @@ export const closeTabTool = defineBrowserTool({
     "Accepts exact targetId or a unique hex prefix (>=8 chars).",
   ],
   parameters: CloseTabArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     let resolved = args.targetId;
     if (!client.owns(resolved)) {
@@ -172,7 +178,8 @@ export const closeTabTool = defineBrowserTool({
       if (isHexPrefix) {
         const owned = client.ownership().list();
         const matches = owned.filter((id) => id.startsWith(args.targetId));
-        if (matches.length === 1) resolved = matches[0]!;
+        const first = matches[0];
+        if (matches.length === 1 && first !== undefined) resolved = first;
         else if (matches.length > 1) {
           return err({
             kind: "invalid_state",

package/src/domains/target.ts

@@ -0,0 +1,35 @@
+import type { BrowserClient } from "../client";
+import { type Result, err, ok } from "../util/result";
+import type { ToolErr } from "../util/tool";
+import { resolveRefToBox } from "./ref-resolve";
+
+export type PointArgs = {
+  readonly ref?: string | undefined;
+  readonly x?: number | undefined;
+  readonly y?: number | undefined;
+};
+
+export type ResolvedTarget = {
+  readonly x: number;
+  readonly y: number;
+  readonly label: string;
+};
+
+export const resolveTarget = async (
+  client: BrowserClient,
+  args: PointArgs,
+): Promise<Result<ResolvedTarget, ToolErr>> => {
+  if (args.ref !== undefined) {
+    const box = await resolveRefToBox(client, args.ref);
+    if (!box.success) return box;
+    return ok({
+      x: box.data.cx,
+      y: box.data.cy,
+      label: `[${args.ref}] (${box.data.cx}, ${box.data.cy})`,
+    });
+  }
+  if (args.x !== undefined && args.y !== undefined) {
+    return ok({ x: args.x, y: args.y, label: `(${args.x}, ${args.y})` });
+  }
+  return err({ kind: "invalid_state", message: "Provide either `ref` or both `x` and `y`." });
+};

package/src/domains/viewport.ts

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
-import { type Result, err, ok } from "../util/result";
+import { type Result, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { cdpCall } from "./cdp-call";
 
 const ViewportArgs = Type.Object({
   width: Type.Integer({ minimum: 100, maximum: 8000, description: "Viewport CSS pixel width" }),
@@ -20,14 +21,15 @@ export const viewportResizeTool = defineBrowserTool({
     "Pass deviceScaleFactor=2 to simulate retina displays.",
   ],
   parameters: ViewportArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
-    const r = await client.session().call("Emulation.setDeviceMetricsOverride", {
+    const r = await cdpCall(client, "Emulation.setDeviceMetricsOverride", {
       width: args.width,
       height: args.height,
       deviceScaleFactor: args.deviceScaleFactor ?? 1,
       mobile: false,
     });
-    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    if (!r.success) return r;
     return ok({
       text: `Viewport set to ${args.width}x${args.height} @${args.deviceScaleFactor ?? 1}x`,
       details: {

package/src/index.ts

@@ -1,41 +1,18 @@
-/**
- * pi-browser-harness — browser control extension for pi.
- *
- * Gives pi agents full control of a real Chrome browser via CDP.
- * Connects to the user's running Chrome (chrome://inspect/#remote-debugging),
- * registers browser_* tools, and injects browser control guidance into the
- * system prompt.
- *
- * Install:
- *   pi install npm:pi-browser-harness
- *   # or copy to .pi/extensions/pi-browser-harness/
- *
- * Commands:
- *   /browser-setup          — guided setup wizard
- *   /browser-profile        — choose which browser profile the agent uses
- *   /browser-status         — show client status and current page
- *   /browser-reload-daemon  — restart the browser client
- *   /deep-research <q>      — research a question on the web, write a cited report
- *
- * Flags:
- *   --browser-namespace <name>   — override namespace (default: auto)
- *   --browser-debug-clicks       — enable debug click overlay
- */
-
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { type BrowserClient, createBrowserClient } from "./client";
 import { getBrowserSystemPrompt } from "./prompt";
 import { registerSetupCommand } from "./setup";
 import { registerProfileCommand } from "./profile/command";
 import { readPin } from "./profile/store";
-import { registerDeepResearchCommand } from "./deep-research";
 import { type BrowserState, defaultState, persistState, restoreState } from "./state";
 import { registerAllTools } from "./registry";
 import { cleanupTempDirs } from "./util/truncate";
-import { createDaemonTransport } from "./cdp/daemon-transport";
+import { createDaemonTransport } from "./daemon/transport";
+import { setDebugClicks } from "./util/debug";
+import { asBoolean, asString } from "./util/guards";
 
 export default function browserHarnessExtension(pi: ExtensionAPI): void {
-  const flagNs = pi.getFlag("browser-namespace") as string | undefined;
+  const flagNs = asString(pi.getFlag("browser-namespace"));
   const namespace = flagNs ?? `pi-${Math.random().toString(36).slice(2, 10)}`;
 
   let state: BrowserState = defaultState(namespace);
@@ -106,16 +83,11 @@ export default function browserHarnessExtension(pi: ExtensionAPI): void {
 
   pi.on("session_start", async (_event, ctx) => {
     state = restoreState(ctx, state.namespace);
+    setDebugClicks(asBoolean(pi.getFlag("browser-debug-clicks")) ?? false);
 
-    // The pinned profile lives on disk, not in the session, so it survives
-    // session termination. Re-read it every session start: another pi session
-    // may have changed it since this client was created.
+    // Re-read the on-disk profile pin every session start: another pi session may have changed it since this client was created.
     const profilePin = await readPin();
 
-    // Create the client lazily on first session. The daemon transport
-    // is created but NOT connected — that only happens when the user
-    // runs /browser-setup or a browser tool call finds an existing socket.
-    // This means zero Chrome prompts for non-browser pi sessions.
     if (!client) {
       const transport = createDaemonTransport(state.namespace);
 
@@ -140,53 +112,31 @@ export default function browserHarnessExtension(pi: ExtensionAPI): void {
               ? { harnessWindowId: snap.harnessWindowId }
               : {}),
           };
-          // Ownership changes can fire from CDP events at any time,
-          // including after session replacement when pi's ctx is stale.
-          // Persistence is best-effort — failure must not crash the event consumer.
-          // ponytail: try/catch is the simplest guard against stale-ctx.
-          try { persistState(pi, state); } catch { /* stale ctx — safe to ignore */ }
+          try { persistState(pi, state); } catch {}
         },
       });
     } else {
-      // Client carried over from a previous session — adopt whatever pin is on
-      // disk now, which another pi session may have changed.
       client.setProfilePin(profilePin);
     }
 
-    // Do NOT call client.start() here — browser control is on-demand.
-    // The first browser tool call or /browser-setup triggers the actual
-    // daemon socket connection and Chrome prompt.
-
     if (!toolsRegistered) {
       registerAllTools(pi, client);
       toolsRegistered = true;
     }
     registerSetupCommand(pi, client);
     registerProfileCommand(pi, client);
-    registerDeepResearchCommand(pi);
   });
 
   pi.on("session_shutdown", async () => {
     if (client) {
       try {
-        // Detach from the page target (removes the "Chrome is being controlled"
-        // banner) but keep the transport alive for the next session.
         await client.detach();
-        // Close every tab this session opened so no stale harness tabs linger
-        // in the user's browser between sessions. This also clears the persisted
-        // ownership + window binding via onOwnershipChange, so the next session
-        // starts with a fresh dedicated window rather than reattaching to leftovers.
         await client.closeOwnedTabs();
       } catch (e) {
         console.warn("[pi-browser-harness] browser teardown failed during shutdown:", e);
       }
-      // ponytail: keep the transport alive across sessions.
-      // Do NOT call client.stop() or null out client — the daemon connection
-      // persists and eliminates the per-session "Allow Remote Debugging" prompt.
-      // Only Chrome restart or daemon death triggers a new prompt.
+      // Do NOT stop the client or null it out: the surviving daemon connection is what eliminates the per-session "Allow Remote Debugging" prompt.
     }
-    // Persist last — closeOwnedTabs mutates `state` through onOwnershipChange,
-    // so this captures the cleared ownership set.
     persistState(pi, state);
     await cleanupTempDirs();
   });

package/src/profile/bind.ts

@@ -1,62 +1,30 @@
-/**
- * Binding the harness session to a pinned profile.
- *
- * Sequence, all of it verified against a live browser:
- *   1. resolve the browser binary and any explicit --user-data-dir
- *   2. launch a window into the profile, marked with a file:// sentinel
- *   3. poll Target.getTargets for the sentinel page — its browserContextId IS
- *      the profile's context, which is otherwise undiscoverable (CDP exposes no
- *      profile identity)
- *   4. adopt that page as the harness window, blank it, drop the sentinel file
- *
- * If the sentinel never appears the bind FAILS LOUDLY. Falling through to a
- * normal createTarget would put the agent in the focus-derived default profile
- * — the exact bug this feature exists to remove — so the caller gets an
- * actionable error instead.
- *
- * The resolved context id is session-scoped state, never persisted: Chrome
- * mints new context ids on every browser run.
- */
-
 import type { BrowserClient } from "../client";
+import type { ResultOf } from "../cdp/commands";
 import { type CdpError, cdpError } from "../cdp/errors";
 import { type Result, err, ok } from "../util/result";
 import { detectRunningBrowser, resolveBrowserExecutable } from "./browser-process";
 import { openProfileWindow } from "./launch";
 import type { ProfilePin } from "./store";
 
-/** The launch delegates through ProcessSingleton, so allow for a cold profile. */
 const SEED_DEADLINE_MS = 15_000;
 const SEED_POLL_MS = 500;
 
-type PageTarget = {
-  readonly targetId: string;
-  readonly type: string;
-  readonly url: string;
-  readonly browserContextId?: string;
-};
+type PageTarget = ResultOf<"Target.getTargets">["targetInfos"][number];
 
 const pageTargets = async (client: BrowserClient): Promise<ReadonlyArray<PageTarget>> => {
   const r = await client.session().callBrowser("Target.getTargets");
   if (!r.success) return [];
-  const data = r.data as { targetInfos: ReadonlyArray<PageTarget> };
-  return data.targetInfos.filter((t) => t.type === "page");
+  return r.data.targetInfos.filter((t) => t.type === "page");
 };
 
 const manualFallbackHint = (pin: ProfilePin): string =>
   `open a window for "${pin.label}" yourself (browser profile menu → ${pin.profileDir}), then retry. ` +
   `Run /browser-profile to pick a different profile, or clear the selection to use whichever window is focused.`;
 
-/**
- * Open (and adopt) a harness window inside the pinned profile. Returns the
- * seed tab's target id.
- */
 export const seedProfileWindow = async (
   client: BrowserClient,
   pin: ProfilePin,
 ): Promise<Result<string, CdpError>> => {
-  // A pin belongs to one user-data-dir. If the harness is now attached to a
-  // different browser, silently seeding the "same" profile name would be wrong.
   const connectedDir = client.userDataDir();
   if (connectedDir && connectedDir !== pin.userDataDir) {
     return err(cdpError(
@@ -66,9 +34,6 @@ export const seedProfileWindow = async (
     ));
   }
 
-  // Identify the browser by the dir we're connected to. With several Chromium
-  // browsers running, launching into the wrong one would open a window the
-  // harness cannot see — in a browser the user never pointed us at.
   const targetUserDataDir = connectedDir ?? pin.userDataDir;
   const running = await detectRunningBrowser(targetUserDataDir);
   const exePath = await resolveBrowserExecutable(running);
@@ -82,11 +47,7 @@ export const seedProfileWindow = async (
   const launched = await openProfileWindow({
     exePath,
     profileDir: pin.profileDir,
-    // Forward the user-data-dir ONLY when the running browser advertises one.
-    // ProcessSingleton keys on this path: passing the value the target process
-    // itself reports guarantees delegation, whereas supplying a default dir we
-    // reconstructed could differ by case or normalisation and start a SECOND
-    // browser instead.
+    // ProcessSingleton keys on the user-data-dir path, so forward only the value the running browser reports: a reconstructed one may differ by case and start a SECOND browser.
     ...(running.explicitUserDataDir ? { explicitUserDataDir: running.explicitUserDataDir } : {}),
   });
   if (!launched.success) {
@@ -116,22 +77,12 @@ export const seedProfileWindow = async (
   const ownership = client.ownership();
   ownership.setHarnessWindow(seed.targetId);
   ownership.add(seed.targetId);
-  const win = await client.session().callBrowser("Browser.getWindowForTarget", { targetId: seed.targetId });
-  if (win.success) {
-    const windowId = (win.data as { windowId?: number }).windowId;
-    if (typeof windowId === "number") ownership.setHarnessWindowId(windowId);
-  }
+  const win = await client.session().windowId(seed.targetId);
+  if (win.success) ownership.setHarnessWindowId(win.data);
 
-  // Blank the handshake page so the seed tab behaves like any other fresh tab,
-  // then remove the sentinel file. Best-effort: a failure here costs nothing
-  // beyond the placeholder page staying visible.
-  const attached = await client.session().callBrowser("Target.attachToTarget", {
-    targetId: seed.targetId,
-    flatten: true,
-  });
+  const attached = await client.session().attach(seed.targetId);
   if (attached.success) {
-    const sessionId = (attached.data as { sessionId: string }).sessionId;
-    await client.session().callOnTarget("Page.navigate", { url: "about:blank" }, sessionId);
+    await client.session().callOnTarget("Page.navigate", { url: "about:blank" }, attached.data);
   }
   await cleanup();