diff options
| author | amankumarsingh77 <amankumarsingh7702@gmal.com> | 2026-05-08 00:18:22 +0530 |
|---|---|---|
| committer | amankumarsingh77 <amankumarsingh7702@gmal.com> | 2026-05-08 00:18:22 +0530 |
| commit | 8db684d43366d335760e106eae39a74376bd7640 (patch) | |
| tree | 241757f766f72b6dd4265326c9c92640418330cf /thoughts/shared/questions | |
| parent | aa08e740cb2f12cb424a2d042619955c99230ed7 (diff) | |
docs: add per-tab isolation research, design, and implementation plan
- Research: multi-agent safety analysis with precedent findings
- Design: 4-slice per-tab isolation architecture (thoughts/shared/designs/)
- Plan: 3-phase implementation plan (thoughts/shared/plans/)
- Agent definitions (.pi/agents/) for codebase analysis workflow
Diffstat (limited to 'thoughts/shared/questions')
| -rw-r--r-- | thoughts/shared/questions/2026-05-07_00-26_multi-agent-safety.md | 40 |
1 files changed, 40 insertions, 0 deletions
diff --git a/thoughts/shared/questions/2026-05-07_00-26_multi-agent-safety.md b/thoughts/shared/questions/2026-05-07_00-26_multi-agent-safety.md new file mode 100644 index 0000000..a14ae12 --- /dev/null +++ b/thoughts/shared/questions/2026-05-07_00-26_multi-agent-safety.md @@ -0,0 +1,40 @@ +--- +date: 2026-05-07T00:26:00Z +researcher: amankumarsingh77 +git_commit: bd19739 +branch: main +repository: pi-browser-harness +topic: "multi-agent safety in pi-browser-harness: how to make browser tools safe when multiple subagents use them concurrently, preventing shared state corruption, tab switching races, dialog buffer conflicts, and ownership confusion" +tags: [discover, mutex, ownership, dialog, tabs, session, concurrency, safety] +status: complete +last_updated: 2026-05-07 +last_updated_by: amankumarsingh77 +--- + +# Research Questions: Multi-Agent Safety in pi-browser-harness + +## Discovery Summary + +The harness uses three primary safety mechanisms: a lightweight async mutex (`src/util/mutex.ts`, `createMutex()`) that serializes all mutation tools marked `serialized: true` in `src/registry.ts`; an `OwnershipRegistry` (`src/cdp/ownership.ts`) backed by a Set that tracks which tab `targetId`s belong to this session and gates `switchTab`, `closeTab`, and `newTab` in `src/domains/tabs.ts`; and a single-slot dialog buffer in `src/cdp/session.ts` (`createCdpSession`) read via `takeDialog()`. Key files read for depth: `client.ts` (mutationMutex, switchTab, ownership wiring), `session.ts` (dialog buffering, tab switch buffer clearing, pageInfoDirty flag), `tool.ts` (serialized lane acquisition with AbortSignal check), `ownership.ts` (Set-backed registry with change listener), `state.ts` (persistence across sessions), `tabs.ts` (ownership-denied gating), `dialog.ts` (single Page.handleJavaScriptDialog call), `prompt.ts` (concurrency guidance injected into the system prompt), and `index.ts` (lifecycle wiring). The architecture is single-agent by design: one mutex, one sessionId/targetId pair, one dialog slot, one pageCache, and ownership tracked per-session not per-agent — none of these primitives are namespaced or partitioned for concurrent sub-agents. + +## Questions + +1. Trace the full mutation-tool serialization path from invocation to completion: the `registerBrowserTool` function in `src/util/tool.ts` wraps each tool's handler in an `execute` closure that first calls `client.ensureAlive()` (unless `ensureAlive` is false), then checks `def.serialized` and calls `client.mutationMutex().acquire()` — an async FIFO mutex defined by `createMutex` in `src/util/mutex.ts` that chains promises. After acquiring, it checks `signal?.aborted`, calls `def.handler(args, ctx)`, and releases in a `finally` block. Map every tool marked `serialized: true` in `src/registry.ts` (22 of 32 tools). Explain why `waitTool` is NOT serialized while `waitForLoadTool` IS, and whether the mutex provides sufficient isolation when two sub-agents each want to operate on different tabs independently. + +2. Follow the tab ownership lifecycle end-to-end: when `createBrowserClient` in `src/client.ts` creates an `OwnershipRegistry` via `createOwnershipRegistry` in `src/cdp/ownership.ts`, it optionally seeds `ownedTargetIds` from persisted `BrowserState` (restored in `index.ts` `session_start` from `restoreState` in `src/state.ts`). During `attachFirstPage` in `src/cdp/session.ts`, the session reconciles persisted ownership against live targets (dropping dead IDs), prefers re-attaching to an owned tab, or creates a fresh one via `Target.createTarget { newWindow: true }` and registers it with `ownership.add()`. On `Target.targetDestroyed` events, ownership is removed. Trace how `switchTabTool` and `closeTabTool` in `src/domains/tabs.ts` enforce ownership via `client.owns(resolved)` — including hex-prefix resolution logic — and what happens when a sub-agent tries to switch to a tab owned by the session but currently in use by another sub-agent. + +3. Analyze the dialog buffer's single-slot design and its multi-agent failure modes: in `createCdpSession` ( `src/cdp/session.ts` ), the `consumeEvents` async iterator catches `Page.javascriptDialogOpening` and writes to a single `dialog: DialogInfo | null` variable. Critically, `Page.javascriptDialogClosed` is intentionally NOT handled — dialogs stay in the buffer until `takeDialog()` is called. However, `takeDialog()` reads `dialog` then sets it to `null` atomically via assignment, and when the transport closes the dialog is preserved (not cleared in `onClose`). Trace how `client.pageInfo()` in `src/client.ts` calls `session.takeDialog()` first (returning `{ dialog: d }` if present), and how the system prompt in `src/prompt.ts` guides agents to call `browser_handle_dialog`. Identify the race condition where sub-agent A opens a page triggering a dialog, sub-agent B triggers a different dialog on a different tab before A consumes it, and only B's dialog survives. + +4. Map the shared-session architecture and its impact on concurrent sub-agents: `createCdpSession` in `src/cdp/session.ts` maintains a single `sessionId: string | null` and `targetId: string | null` pair. The `switchTo(tid)` method calls `Target.activateTarget`, `Target.attachToTarget`, updates both `sessionId` and `targetId`, sets `pageInfoDirty = true`, and clears both `networkBuffer` and `consoleBuffer`. Trace how `client.switchTab()` in `src/client.ts` additionally nullifies `pageCache` and best-effort marks the tab title. Explain why if sub-agent A is mid-workflow on tab X (expecting `browser_execute_js` results from that tab's DOM) and sub-agent B calls `browser_switch_tab` to tab Y, agent A's subsequent `browser_execute_js` silently targets the wrong page — the `sessionId`/`targetId` pair is global, with no per-agent override. + +5. Trace the page-info caching and invalidation pipeline: `client.readPageInfo()` in `src/client.ts` checks `session.drainPageInfoInvalidations()` (the `pageInfoDirty` boolean in `session.ts`, set on `Page.frameNavigated` and `Page.loadEventFired`), consults a `pageCache` with 1-second TTL, evaluates a JS expression to collect URL/title/viewport/scroll/page-dimensions, parses it through `parsePageInfoPayload()`, and caches the result. Investigate whether a sub-agent switching tabs invalidates another sub-agent's cached page info, and whether the 1-second TTL (`PAGE_INFO_TTL_MS = 1_000`) combined with the shared `pageCache` could cause a sub-agent to receive stale page info from a tab it didn't navigate to. + +6. Examine the state persistence and resumption mechanism across session boundaries: `state.ts` defines `BrowserState` (namespace, remoteBrowserId, ownedTargetIds, harnessWindowTargetId), `persistState()` calls `pi.appendEntry`, and `restoreState()` scans branch entries for the last `browser-harness-state` custom entry. In `index.ts`, `session_start` restores state and wires `onOwnershipChange` to persist on every mutation. Map the full flow: `OwnershipRegistry.onChange` → `onOwnershipChange` callback in `client.ts` → `persistState` → `pi.appendEntry`. Assess whether this persistence model could cause cross-agent confusion if two sub-agents with different browser namespaces share the same pi branch session entries. + +7. Follow the console and network buffer lifecycle across tab switches: in `session.ts`, `createConsoleBuffer()` and `createNetworkBuffer()` (imported from `src/cdp/console-buffer.ts` and `src/cdp/network-buffer.ts`) are cleared wholesale in `switchTo()` — `networkBuffer.clear()` and `consoleBuffer.clear()` — because "the network history of the previous tab is no longer relevant." The `browser_network_requests` domain in `src/domains/network.ts` drains the buffer with filters, and `browser_console` in `src/domains/console.ts` uses a `sinceSeq` cursor for incremental reads. Trace what happens when sub-agent A is iterating console output incrementally (using `sinceSeq` from a prior `nextCursor`) and sub-agent B switches tabs, clearing the buffer and invalidating A's cursor. + +8. Investigate whether the namespace system provides any multi-agent isolation boundary: `index.ts` generates or accepts a `--browser-namespace` flag, stored in `BrowserState.namespace` and passed to `createBrowserClient`. The ownership-denied error message in `src/domains/tabs.ts` (`ownershipDeniedMessage`) references the namespace string, and `client.namespace` is exposed on the `BrowserClient` type. Determine whether two sub-agents running with different `--browser-namespace` values would each get their own `BrowserClient`, mutex, ownership registry, and session — or whether the extension's singleton `client` variable in `index.ts` means all agents share one client regardless of namespace. If the latter, assess what would need to change to support namespace-per-agent client instances. + +9. Analyze the `before_agent_start` hook in `index.ts` and the system prompt injection in `src/prompt.ts` for multi-agent guidance: the hook appends `getBrowserSystemPrompt()` to the system prompt, which includes a "Parallel Execution" section stating that observation tools run in parallel while mutation tools are serialized. Examine whether this prompt guidance is sufficient for a sub-agent to understand that another sub-agent might be concurrently mutating shared state — or whether the prompt assumes single-agent usage and omits crucial warnings about tab switching side effects, dialog slot overwrites, and buffer clearing. + +10. Model the full set of shared mutable state across the entire client and session layer: enumerate every piece of mutable state — `sessionId`, `targetId`, `dialog`, `pageInfoDirty`, `pageCache`, `lastHealth`, `mutationMutex` queue, `networkBuffer` entries, `consoleBuffer` entries, `ownership` Set, `harnessWindow`, `transport` connection — and classify each as either "safe to share across agents" or "requires per-agent partitioning." For each item requiring partitioning, propose the minimal abstraction change (e.g., per-agent dialog queue, per-agent sessionId/targetId stack with restore-on-switch, namespaced buffers with merge semantics). |
