# Architecture Related docs: - [`../README.md`](../README.md) - [`REQUIREMENTS.md`](REQUIREMENTS.md) - [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md) ## Decision Build this as a **thin `pi` extension/package** that exposes `agent-browser` as one native tool while keeping upstream `agent-browser` as the source of truth. The package install path is the primary product path. Local checkout development should use explicit CLI loading for isolated smoke tests and configured-source plain `pi` runs for lifecycle validation, while package-manifest behavior and packaged contents matter more. ## Chosen shape ### One primary tool V1 should expose one native tool: - `agent_browser` Why: - lowest maintenance cost - lowest drift risk as upstream changes - preserves full upstream power - avoids overengineering ### Direct subprocess execution The extension should: - resolve `agent-browser` from `PATH` - invoke it directly, not through a shell - inject `--json` - support optional stdin only for `eval --stdin` and `batch`, rejecting other command/stdin combinations before launch ### Agent-first UX The primary UX is the agent calling the tool directly. That means: - no command-heavy slash-command interface - no manual user orchestration as the main workflow - any future slash commands should be minimal and secondary ### Package layout versus local checkout development The published package should load from the `pi` manifest in `package.json`. Local checkout validation has two intentional modes: - **Quick isolated mode:** use explicit CLI loading such as `pi --no-extensions -e .` from the repository root. This bypasses Pi settings and extension discovery, avoids duplicate `agent_browser` registrations when another source is installed globally, and is the right mode for checkout smoke tests. - **Configured-source lifecycle mode:** configure exactly one active checkout or package source in Pi settings and launch plain `pi`. This is the right mode for validating `/reload`, restart, and `/resume` behavior because those lifecycle checks exercise discovered/configured resources. The repo should not add a repo-local `.pi/extensions/` autoload shim as the documented checkout path. Why: - avoids duplicate `agent_browser` registrations when the package is also installed globally - keeps the product contract centered on the package manifest instead of repo-local autoload wiring - keeps reload and resume validation tied to Pi's configured-source lifecycle instead of an isolated quick-test path - keeps the published tarball focused on the package manifest, extension code, canonical docs, and license The published package should exclude agent-only and superseded repo materials such as `AGENTS.md`, `docs/v1-tool-contract.md`, `docs/native-integration-design.md`, and other internal planning notes. ## Session model ### Default If the caller does not provide `--session`, the extension should default to `sessionMode: "auto"` and use an implicit session name derived from the current `pi` session id plus a hash of the absolute cwd. Why: - works out of the box - gives continuity across calls - avoids forcing the agent to invent session names for basic browsing ### Explicit upstream sessions and fresh launches If the caller provides `--session`, `--profile`, `--cdp`, or similar upstream flags, the extension should respect them with minimal interference. The tool should also expose a first-class `sessionMode: "fresh"` escape hatch so agents can intentionally rotate the extension-managed session to a fresh upstream launch without inventing a fixed explicit session name. ### Ownership V1 ownership rule: - implicit auto-generated sessions are extension-managed convenience sessions - unnamed `sessionMode: "fresh"` launches rotate that extension-managed session to a new upstream browser - explicit/user-managed sessions are not auto-managed by default - extension-managed sessions should be reusable during an active `pi` session and across `/reload` / `/resume`, while still being cleaned up predictably Practical policy: - preserve the current extension-managed session across `/reload` and resumable session transitions so persisted sessions can keep following the live browser after `/reload` or `/resume` - close the active extension-managed session when the originating `pi` process quits, while leaving explicit caller-provided sessions alone - set an idle timeout on extension-managed sessions as a backstop for abnormal exits or cleanup failures - clean up process-private temp spill artifacts on shutdown, but keep persisted-session snapshot spill files in a private session-scoped artifact directory with a bounded per-session budget so `details.fullOutputPath` stays usable after reload/resume without unbounded growth - reconstruct the current extension-managed session from persisted tool details on resume/reload so later default calls keep following the active managed browser - if an unnamed fresh launch replaces an active extension-managed session, best-effort close the old managed session after the switch succeeds - leave explicit caller-provided `--session` choices alone unless the caller closes them explicitly - after profiled `open` / `goto` / `navigate` calls, verify the active tab still matches the returned page URL and best-effort switch back when restored profile tabs steal focus - once the wrapper knows which tab the agent is operating on, later active-tab commands may synthesize a tiny upstream `batch` that re-selects that tab and then runs the requested command in the same upstream invocation; this stays thin while avoiding reconnect-time drift on profile-restored sessions - after a successful command on a known tab target, the wrapper may best-effort restore that same target again if restored/background tabs steal focus after the command returns - for local Unix launches, set a short private socket directory so extension-generated session names do not fail on the upstream Unix socket-path length limit This is primarily about ownership clarity and avoiding surprise, not adding a heavy safety wrapper. If the extension invented the session, the extension should own its lifecycle without breaking reload/resume semantics. If the caller explicitly chose the upstream session model, the extension should stay out of the way. ### Launch flags `agent-browser` startup flags are sticky once a session is already running. The extension should surface that clearly and avoid hidden restart behavior in v1. That means explicit startup-scoping flags like `--profile`, `--session-name`, and `--cdp` should remain explicit upstream choices instead of being wrapped in extra hidden restart or cloning logic. The wrapper may still apply narrow compatibility normalizations when observed behavior justifies them and the result remains thin, local, and opt-out. For example, if a specific site starts rejecting the default local headless Chrome user agent while the same flow works with a normal Chrome UA, the extension may inject a domain-specific fallback UA only when the caller did not already choose `--user-agent`, `--headed`, `--cdp`, `--auto-connect`, or a provider-backed launch. If the implicit session is already active and one of those startup-scoped flags appears again while `sessionMode` is still `"auto"`, the extension should fail clearly instead of silently sending a command shape that upstream would ignore. That failure should include a structured recovery hint pointing to `sessionMode: "fresh"` as the first-line fix, while still allowing an explicit `--session` when the caller wants to name the new upstream session. A successful unnamed `sessionMode: "fresh"` launch should become the new extension-managed session so later default calls follow that browser instead of silently snapping back to the older managed session. ## Preferring the native tool Keep the handling simple: - prefer the native tool through extension guidance and tool-call guards - do not rely on package skill overrides as the primary solution This keeps the product centered on native tool usage instead of auxiliary skill wiring. ## Responsibility split ### `pi-agent-browser-native` owns - tool registration and schema - subprocess execution and JSON parsing - clear missing-binary errors - compact result summaries - inline screenshots/images - lightweight session convenience - docs, including a repo-readable command reference that mirrors the blocked direct-binary help path closely enough for normal agent work ### Upstream `agent-browser` owns - browser automation semantics - command vocabulary - session/profile behavior - auth/profile mechanics - feature evolution ## Not the right design V1 should avoid: - a wide family of bespoke browser tools - compatibility layers for old `agent-browser` versions - deep embedded SDK-style integration - embedding a human-browsable browser UI inside `pi` - a slash-command-heavy UX ## V1 priorities ### Must have - one native `agent_browser` tool - direct `--json` execution - optional stdin support - implicit-session convenience - screenshot/image attachment - clear install and missing-binary messaging - solid docs ### Nice to have - compact renderers for snapshots and tab lists - lightweight status display ## Summary The architecture should stay: - thin - latest-only - close to upstream - native where it matters - low-maintenance