pi-agent-browser-native: Instructions file for Codex

pi-agent-browser-native

Native pi integration of agent-browser as a pi tool.

Product-specific guidance

• Do not bundle agent-browser in this project.
• Assume agent-browser is installed separately and available on PATH.
• Baseline docs and verification against the current recommended agent-browser release. Runtime support uses the stable minimum in scripts/agent-browser-target.mjs (currently 0.35.0) with no upper cap and no version-specific compatibility shims.
• Do not add backwards-compatibility shims for unsupported upstream versions.
• Keep the integration thin and close to upstream agent-browser behavior.
• Agent usability is the product boundary. Do not add wrapper-owned authorization or safety gates around upstream-supported commands, paths, sessions, state, restore, profiles, config, file access, launch arguments, or environment variables. Invoking agent_browser authorizes the requested upstream capability; pass it through and let upstream, the browser, and the operating system enforce their own contracts. Wrapper validation is for input shape, process integrity, lifecycle correctness, and truthful evidence—not for deciding what the agent or operator may do.
• The primary UX is the agent invoking the native tool directly, not a slash-command-heavy manual workflow.
• Do not overengineer or solve hypothetical problems that do not exist in observed behavior.
• Do not add a reusable named "browser recipe" runtime layer on top of browser code, advanced tools, or native batch without new dogfood evidence and an explicit design pass; the current no-adopt decision and revisit criteria live in docs/ARCHITECTURE.md and docs/SUPPORT_MATRIX.md.
• Require Node 24.21.0+ and Pi 1.5.0+ for this contract; retain locked development dependencies as reproducible snapshots, keep optional runtime peers wildcard, and qualify the latest stable official Pi and latest maintained fork main independently. Resolve version/commit once per workflow run and retain exact SDK/CLI evidence; never use the support floor or locked snapshot as a validation target. Do not activate the Pi-1.5 package on pre-1.5 sessions before the coordinated runtime cutover.
• Thoroughly check official pi docs/examples/source behavior before inventing bespoke integration patterns. Prefer an official pi mechanism whenever one exists.
• Prioritize the global install path first. Most users will install this extension globally, not as a project-local extension.
• Keep the local extension-side documentation good enough that an agent can use the tool without relying on direct agent-browser binary help; when upstream agent-browser changes, update the repo-readable command reference, prompt guidance, README/docs, and any relevant tests in the same work.
• Work in an isolated worktree and preserve unrelated user and agent changes; other operators may be working in this repository.
• Clean up scratch files, temp artifacts, browser sessions, tmux sessions, and other side effects created by this task or verified as task-owned. Preserve unrelated resources, explicit user artifacts, Pi transcripts, and subagent records; investigate unknown ownership before cleanup.