pi-browser-harness 0.3.2 → 0.5.0

package/src/domains/tabs.ts

@@ -4,26 +4,41 @@ import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
 
 const ListTabsArgs = Type.Object({
   includeInternal: Type.Optional(Type.Boolean({ default: true, description: "Include chrome:// pages" })),
+  scope: Type.Optional(
+    Type.Union([Type.Literal("owned"), Type.Literal("all")], {
+      default: "owned",
+      description: "'owned' (default) shows only tabs this harness session opened; 'all' shows every tab in the browser.",
+    }),
+  ),
 });
 
 export const listTabsTool = defineBrowserTool({
   name: "browser_list_tabs",
   label: "Browser List Tabs",
-  description: "List all open browser tabs (page targets).",
+  description: "List browser tabs. Defaults to tabs this harness session opened (scope:'owned'). Pass scope:'all' to see the user's other tabs too.",
   promptSnippet: "List browser tabs",
   promptGuidelines: [
-    "Use to find a full targetId for browser_switch_tab.",
-    "Internal tabs (chrome://) included by default; pass includeInternal=false to exclude them.",
+    "Defaults to scope:'owned' — only tabs this session created. Pass scope:'all' to inspect the user's other tabs.",
+    "browser_switch_tab and browser_close_tab refuse non-owned tabs; use browser_new_tab to open one this session controls.",
     "Each tab shows its full 32-char hex targetId — use the exact value with browser_switch_tab.",
+    "Internal tabs (chrome://) included by default; pass includeInternal=false to exclude them.",
   ],
   parameters: ListTabsArgs,
   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 });
-    const lines = r.data.map((t, i) => `  [${i}] ${t.targetId} ${t.url}\n      ${t.title}`);
+    const scope = args.scope ?? "owned";
+    const filtered = scope === "owned" ? r.data.filter((t) => t.owned) : r.data;
+    const lines = filtered.map((t, i) => {
+      const flag = t.owned ? "★" : " ";
+      return `  ${flag} [${i}] ${t.targetId} ${t.url}\n      ${t.title}`;
+    });
+    const header = scope === "owned"
+      ? `Owned tabs (${filtered.length}):`
+      : `All tabs (${filtered.length}, ★ = owned by this session):`;
     return ok({
-      text: `Tabs (${r.data.length}):\n${lines.join("\n")}`,
-      details: { tabs: r.data },
+      text: `${header}\n${lines.join("\n")}`,
+      details: { tabs: filtered, scope },
     });
   },
 });
@@ -33,7 +48,7 @@ export const currentTabTool = defineBrowserTool({
   label: "Browser Current Tab",
   description: "Get info about the currently attached tab.",
   promptSnippet: "Get current tab info",
-  promptGuidelines: ["Returns targetId, url, title."],
+  promptGuidelines: ["Returns targetId, url, title, and whether the tab is owned by this harness session."],
   parameters: Type.Object({}),
   async handler(_a, { client }): Promise<Result<ToolOk, ToolErr>> {
     const cur = client.current();
@@ -41,9 +56,10 @@ export const currentTabTool = defineBrowserTool({
     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 owned = client.owns(info.targetId);
     return ok({
-      text: `Current tab:\n  ${info.targetId}\n  ${info.url}\n  ${info.title}`,
-      details: { targetId: info.targetId, url: info.url, title: info.title },
+      text: `Current tab${owned ? " (owned)" : " (NOT owned by this session)"}:\n  ${info.targetId}\n  ${info.url}\n  ${info.title}`,
+      details: { targetId: info.targetId, url: info.url, title: info.title, owned },
     });
   },
 });
@@ -52,47 +68,59 @@ const SwitchTabArgs = Type.Object({
   targetId: Type.String({ description: "Target ID from browser_list_tabs" }),
 });
 
+const ownershipDeniedMessage = (id: string, namespace: string): string =>
+  `Tab ${id} is not owned by this harness session (namespace: ${namespace}). ` +
+  `Use browser_list_tabs with scope:'all' to see it, or browser_new_tab to open one this session can control.`;
+
 export const switchTabTool = defineBrowserTool({
   name: "browser_switch_tab",
   label: "Browser Switch Tab",
-  description: "Switch to and attach to a different tab by targetId.",
+  description: "Switch to and attach to a different tab by targetId. Only tabs this harness session opened are accepted.",
   promptSnippet: "Switch tabs",
   promptGuidelines: [
     "Get a targetId via browser_list_tabs first.",
     "Accepts exact targetId or a unique prefix of at least 8 hex characters.",
+    "Refuses tabs not owned by this session — use browser_new_tab to open a controllable tab instead.",
   ],
   parameters: SwitchTabArgs,
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
-    // Try exact match first
-    let r = await client.switchTab(args.targetId);
-    if (r.success) {
-      return ok({ text: `Switched to ${args.targetId}`, details: { targetId: args.targetId } });
-    }
-    // If exact match failed and input looks like a short prefix (≥8 hex chars), try prefix resolution
-    const isHexPrefix = /^[0-9A-Fa-f]{8,}$/.test(args.targetId);
-    if (!isHexPrefix) {
-      return err({ kind: "cdp_error", message: r.error.message });
-    }
-    const tabs = await client.listTabs(true);
-    if (!tabs.success) return err({ kind: "cdp_error", message: r.error.message });
-    const matches = tabs.data.filter((t) => t.targetId.startsWith(args.targetId));
-    if (matches.length === 0) {
-      return err({ kind: "cdp_error", message: `No tab found with prefix "${args.targetId}"` });
+    // 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);
+      if (isHexPrefix) {
+        const tabs = await client.listTabs(true);
+        if (!tabs.success) return err({ kind: "cdp_error", message: tabs.error.message });
+        const matches = tabs.data.filter((t) => t.targetId.startsWith(args.targetId));
+        if (matches.length === 0) {
+          return err({ kind: "cdp_error", message: `No tab found with prefix "${args.targetId}"` });
+        }
+        if (matches.length > 1) {
+          const ids = matches.map((t) => t.targetId).join(", ");
+          return err({
+            kind: "invalid_state",
+            message: `Ambiguous prefix "${args.targetId}" matches ${matches.length} tabs: ${ids}`,
+            details: { matches: matches.map((t) => ({ targetId: t.targetId, url: t.url })) },
+          });
+        }
+        resolved = matches[0]!.targetId;
+      }
+      if (!client.owns(resolved)) {
+        return err({
+          kind: "invalid_state",
+          message: ownershipDeniedMessage(resolved, client.namespace),
+          details: { targetId: resolved, namespace: client.namespace },
+        });
+      }
     }
-    if (matches.length > 1) {
-      const ids = matches.map((t) => t.targetId).join(", ");
-      return err({
-        kind: "invalid_state",
-        message: `Ambiguous prefix "${args.targetId}" matches ${matches.length} tabs: ${ids}`,
-        details: { matches: matches.map((t) => ({ targetId: t.targetId, url: t.url })) },
-      });
-    }
-    const resolved = matches[0]!.targetId;
-    r = await client.switchTab(resolved);
+
+    const r = await client.switchTab(resolved);
     if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    const note = resolved === args.targetId ? "" : ` (resolved from prefix "${args.targetId}")`;
     return ok({
-      text: `Switched to ${resolved} (resolved from prefix "${args.targetId}")`,
-      details: { targetId: resolved, resolvedPrefix: args.targetId },
+      text: `Switched to ${resolved}${note}`,
+      details: { targetId: resolved },
     });
   },
 });
@@ -104,9 +132,12 @@ const NewTabArgs = Type.Object({
 export const newTabTool = defineBrowserTool({
   name: "browser_new_tab",
   label: "Browser New Tab",
-  description: "Open a new tab and switch to it. Optionally navigate to a URL.",
+  description: "Open a new tab in the harness's dedicated Chrome window and switch to it. Optionally navigate to a URL.",
   promptSnippet: "Open a new tab",
-  promptGuidelines: ["Pass url to navigate immediately."],
+  promptGuidelines: [
+    "All tabs opened by this tool live in a single dedicated Chrome window separate from the user's main browsing.",
+    "Pass url to navigate immediately.",
+  ],
   parameters: NewTabArgs,
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const r = await client.newTab(args.url);
@@ -119,3 +150,46 @@ export const newTabTool = defineBrowserTool({
     });
   },
 });
+
+const CloseTabArgs = Type.Object({
+  targetId: Type.String({ description: "Target ID from browser_list_tabs" }),
+});
+
+export const closeTabTool = defineBrowserTool({
+  name: "browser_close_tab",
+  label: "Browser Close Tab",
+  description: "Close a tab the harness owns. Refuses tabs not opened by this session.",
+  promptSnippet: "Close an owned tab",
+  promptGuidelines: [
+    "Only closes tabs this session opened (visible in browser_list_tabs default scope).",
+    "Accepts exact targetId or a unique hex prefix (>=8 chars).",
+  ],
+  parameters: CloseTabArgs,
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    let resolved = args.targetId;
+    if (!client.owns(resolved)) {
+      const isHexPrefix = /^[0-9A-Fa-f]{8,}$/.test(args.targetId);
+      if (isHexPrefix) {
+        const owned = client.ownership().list();
+        const matches = owned.filter((id) => id.startsWith(args.targetId));
+        if (matches.length === 1) resolved = matches[0]!;
+        else if (matches.length > 1) {
+          return err({
+            kind: "invalid_state",
+            message: `Ambiguous prefix "${args.targetId}" matches ${matches.length} owned tabs: ${matches.join(", ")}`,
+          });
+        }
+      }
+      if (!client.owns(resolved)) {
+        return err({
+          kind: "invalid_state",
+          message: ownershipDeniedMessage(resolved, client.namespace),
+          details: { targetId: resolved, namespace: client.namespace },
+        });
+      }
+    }
+    const r = await client.closeTab(resolved);
+    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    return ok({ text: `Closed tab ${resolved}`, details: { targetId: resolved } });
+  },
+});

package/src/index.ts

@@ -98,7 +98,23 @@ export default function browserHarnessExtension(pi: ExtensionAPI): void {
 
   pi.on("session_start", async (_event, ctx) => {
     state = restoreState(ctx, state.namespace);
-    client = createBrowserClient({ namespace: state.namespace });
+    const initialOwnership: { ownedTargetIds?: ReadonlyArray<string>; harnessWindowTargetId?: string } = {};
+    if (state.ownedTargetIds !== undefined) initialOwnership.ownedTargetIds = state.ownedTargetIds;
+    if (state.harnessWindowTargetId !== undefined) initialOwnership.harnessWindowTargetId = state.harnessWindowTargetId;
+    client = createBrowserClient({
+      namespace: state.namespace,
+      ...(Object.keys(initialOwnership).length > 0 ? { initialOwnership } : {}),
+      onOwnershipChange: (snap) => {
+        state = {
+          ...state,
+          ownedTargetIds: snap.ownedTargetIds,
+          ...(snap.harnessWindowTargetId !== undefined
+            ? { harnessWindowTargetId: snap.harnessWindowTargetId }
+            : {}),
+        };
+        persistState(pi, state);
+      },
+    });
     // failure is fine — surfaced via tool errors when the agent first tries to use the browser
     await client.start();
     if (!toolsRegistered) {

package/src/prompt.ts

@@ -36,6 +36,7 @@ to interact with pages visually, and other tools alongside them.
 | browser_switch_tab | Switch to a different tab by targetId |
 | browser_execute_js | Execute JavaScript and return the result |
 | browser_http_get | Direct HTTP GET (outside browser, for APIs) |
+| browser_console | Read JS errors / console output on the current tab (diagnostic — use when an action looks broken; pass sinceSeq from the previous nextCursor to see only new messages) |
 | browser_wait | Wait N seconds |
 | browser_wait_for_load | Wait for document.readyState === 'complete' (returns a typed timeout error if the page doesn't reach readyState=complete in N seconds, default 15) |
 | browser_handle_dialog | Accept or dismiss a JS dialog |
@@ -73,6 +74,8 @@ browser_screenshot() + browser_page_info() + browser_execute_js("document.title"
 browser_http_get("https://api.example.com/data") + browser_click(x, y)
 \`\`\`
 
+**Multi-agent note**: When multiple subagents use the browser, tab switching by one agent changes the active tab for all agents. Per-tab data (console buffers, network traces, dialogs, page info cache) is isolated — switching tabs does not destroy another agent's collected data. Call \`browser_current_tab\` before mutation tools to confirm you're on the expected tab. If \`browser_page_info\` returns a dialog, handle it with \`browser_handle_dialog\` promptly — dialogs block page interaction and are not queued across agents.
+
 ### Common Patterns
 
 **Navigation:**

package/src/registry.ts

@@ -9,11 +9,13 @@ import { handleDialogTool } from "./domains/dialog";
 import { screenshotTool } from "./domains/screenshot";
 import { navigateTool, openUrlsTool } from "./domains/navigate";
 import { goBackTool, goForwardTool, reloadTool } from "./domains/history";
-import { listTabsTool, currentTabTool, switchTabTool, newTabTool } from "./domains/tabs";
+import { listTabsTool, currentTabTool, switchTabTool, newTabTool, closeTabTool } from "./domains/tabs";
 import { uploadFileTool, downloadTool, printToPdfTool } from "./domains/files";
 import { viewportResizeTool } from "./domains/viewport";
 import { dragAndDropTool } from "./domains/drag";
-import { httpGetTool, getNetworkLogTool } from "./domains/network";
+import { httpGetTool, networkRequestsTool } from "./domains/network";
+import { consoleTool } from "./domains/console";
+import { snapshotTool } from "./domains/snapshot";
 import { executeJsTool, runScriptTool } from "./domains/js";
 
 // Mutation tools that modify page / browser state are marked `serialized: true`
@@ -39,13 +41,16 @@ const TOOLS: ReadonlyArray<AnyBrowserToolDefinition> = [
   currentTabTool,
   { ...switchTabTool, serialized: true },
   { ...newTabTool, serialized: true },
+  { ...closeTabTool, serialized: true },
   { ...uploadFileTool, serialized: true },
   { ...downloadTool, serialized: true },
   { ...printToPdfTool, serialized: true },
   { ...viewportResizeTool, serialized: true },
   { ...dragAndDropTool, serialized: true },
   httpGetTool,
-  getNetworkLogTool,
+  networkRequestsTool,
+  consoleTool,
+  snapshotTool,
   executeJsTool,
   runScriptTool,
 ];

package/src/state.ts

@@ -10,9 +10,14 @@ import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-age
 export type BrowserState = {
   readonly namespace: string;
   readonly remoteBrowserId?: string;
+  readonly ownedTargetIds?: ReadonlyArray<string>;
+  readonly harnessWindowTargetId?: string;
 };
 
-export const defaultState = (namespace = "default"): BrowserState => ({ namespace });
+export const defaultState = (namespace = "default"): BrowserState => ({
+  namespace,
+  ownedTargetIds: [],
+});
 
 export const persistState = (pi: ExtensionAPI, state: BrowserState): void => {
   pi.appendEntry<BrowserState>("browser-harness-state", state);