diff options
| author | Aman Kumar <145339995+amankumarsingh77@users.noreply.github.com> | 2026-06-21 00:46:44 +0530 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2026-06-21 00:46:44 +0530 |
| commit | da5d31af999b728c31ab0169373531cab4543f0c (patch) | |
| tree | 5d350ad1428ff332372a9c724ac46c964d8ca477 /thoughts/shared/questions | |
| parent | 8db684d43366d335760e106eae39a74376bd7640 (diff) | |
release: v0.6.0 — per-tab isolation, Unix socket daemon, on-demand init (#6)
* feat: Unix socket daemon with auto-reconnect for persistent Chrome CDP
Eliminates the 'Allow Remote Debugging' Chrome prompt that appeared on
every pi session by multiplexing pi instances through a single persistent
daemon process.
Key additions:
- Unix socket IPC (net.createServer + readline JSON framing)
- CdpBridge with ID multiplexer + event router
- DaemonTransport implementing CdpTransport interface
- Auto-spawn with ensureDaemon() (lazy, checks socket)
Fixes since initial implementation:
- Bridge auto-reconnects to Chrome with exponential backoff (1s-60s).
Previously the bridge tried once at startup and permanently failed
if Chrome wasn't ready — causing 'Chrome not connected' on every
browser tool call.
- Daemon spawn uses project-local tsx binary instead of global --import
flag, fixing silent spawn failure (ERR_MODULE_NOT_FOUND).
- Stale ctx crash: persistState in onOwnershipChange wrapped in
try/catch to prevent CDP event consumer crashes.
49 test assertions across 4 test files. Zero TypeScript errors.
* feat: on-demand browser initialization
Browser daemon no longer auto-starts on session_start. Instead:
- session_start creates the client lazily but does NOT connect or spawn
the daemon. Zero Chrome prompts for non-browser pi sessions.
- Browser tool wrapper checks for daemon socket before each call.
Socket missing → clear error: 'Run /browser-setup first'.
Socket exists → proceeds silently (daemon already running).
- /browser-setup is the explicit, one-time init point. It spawns
the daemon and connects to Chrome only when the user opts in.
- SKILL.md updated with Connection Setup instructions telling agents
to direct users to /browser-setup when socket is missing.
* fix: checkChromeRunning on macOS — match by substring not exact
ps -A -o comm= returns full executable paths on modern macOS
(e.g. /Applications/Google Chrome.app/Contents/MacOS/Google Chrome),
not the basename. The old exact-match check (browserProcesses.includes(l))
never matched, causing false 'No browser instance running' errors.
Changed to substring includes() with helper/renderer/crashpad filtering.
* feat: browser_setup as agent-callable tool
The agent can now self-recover from 'Browser harness not initialized'
errors by calling browser_setup directly — no user mediation needed.
- Extracted shared performSetup() from the slash command into setup.ts
- Created src/domains/setup.ts with ensureAlive:false to bypass the
socket guard (this tool IS the setup, can't require itself)
- Registered browser_setup in the tool registry
- Updated SKILL.md: agent calls browser_setup directly, not ask user
- Removed stale test/manual/spawn-test.ts
* release: v0.6.0 — per-tab isolation, Unix socket daemon, on-demand init
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, 0 insertions, 40 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 deleted file mode 100644 index a14ae12..0000000 --- a/thoughts/shared/questions/2026-05-07_00-26_multi-agent-safety.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -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). |
