Chris Tate
8d78fcbbb3
* windows debugging
* fixes
* fixes
* fix: handle Windows path separators in Chrome zip extraction
The zip crate's enclosed_name() normalizes paths to use backslashes on
Windows, but extract_zip used split_once('/') which only matches forward
slashes. This caused Chrome to be extracted into a nested chrome-win64/
subdirectory instead of directly into the version directory.
Also adds debug diagnostics to find_installed_chrome() (gated behind
AGENT_BROWSER_DEBUG) and better error messages when Chrome cache exists
but no binary is found.
Fixes #1076
* feat: add Puppeteer browser cache as Chrome fallback
Search ~/.cache/puppeteer/chrome/ (or PUPPETEER_CACHE_DIR) for Chrome
binaries before falling back to Playwright's cache. Puppeteer v19+
stores Chrome for Testing in this location, so users with an existing
Puppeteer install can use agent-browser without a separate install step.
* fmt
5.3 KiB
AGENTS.md
Instructions for AI coding agents working with this codebase.
Package Manager
This project uses pnpm. Always use pnpm instead of npm or yarn for installing dependencies, running scripts, etc. (e.g., pnpm install, pnpm run build).
Code Style
- Do not use emojis in code, output, or documentation. Unicode symbols (✓, ✗, →, ⚠) are acceptable.
- CLI colored output uses
cli/src/color.rs. This module respects theNO_COLORenvironment variable. Never use hardcoded ANSI color codes. - CLI flags must always use kebab-case (e.g.,
--auto-connect,--allow-file-access). Never use camelCase for flags (e.g.,--autoConnectis wrong).
Documentation
When adding or changing user-facing features (new flags, commands, behaviors, environment variables, etc.), update all of the following:
cli/src/output.rs----helpoutput (flags list, examples, environment variables)README.md-- Options table, relevant feature sections, examplesskills/agent-browser/SKILL.md-- so AI agents know about the featuredocs/src/app/-- the Next.js docs site (MDX pages)- Inline doc comments in the relevant source files
This applies to changes that either human users or AI agents would need to know about. Do not skip any of these locations.
In the docs/src/app/ MDX files, always use HTML <table> syntax for tables (not markdown pipe tables). This matches the existing convention across the docs site.
Dashboard (packages/dashboard)
- Never use native browser dialogs (
alert,confirm,prompt). Use shadcn/ui components (Dialog,AlertDialog, etc.) instead. - Use param-case (kebab-case) for all file and folder names (e.g.,
session-tree.tsx, notSessionTree.tsx). Theui/directory follows shadcn conventions which already uses param-case.
Architecture
This is a Rust codebase. The browser automation daemon lives in cli/src/native/ (daemon, actions, browser, CDP client, snapshot, state). The --engine flag selects Chrome vs Lightpanda. The install command downloads Chrome from Chrome for Testing directly.
Testing
Unit Tests
cd cli && cargo test
Runs all unit tests (~320 tests). These are fast and don't require Chrome.
End-to-End Tests
cd cli && cargo test e2e -- --ignored --test-threads=1
Runs 18 e2e tests that launch real headless Chrome instances and exercise the full native daemon command pipeline. Requirements:
- Chrome must be installed
- Must run serially (
--test-threads=1) to avoid Chrome instance contention - Tests are
#[ignore]'d so they don't run during normalcargo test
The e2e tests live in cli/src/native/e2e_tests.rs and cover: launch/close, navigation, snapshots, screenshots, form interaction, cookies, storage, tabs, element queries, viewport/emulation, domain filtering, diff, state management, error handling, and Phase 8 commands.
Linting and Formatting
cd cli && cargo fmt -- --check # Check formatting
cd cli && cargo clippy # Lint
Windows Debugging
A remote Windows Server 2022 EC2 instance is available for debugging Windows-specific issues. It uses AWS Systems Manager (SSM) -- no SSH, no open ports. Commands run via aws ssm send-command and return stdout/stderr.
Prerequisites
The instance must be provisioned first (one-time, by a human):
./scripts/windows-debug/provision.sh
Requires: AWS CLI v2 configured with ec2:*, iam:CreateRole, iam:AttachRolePolicy, ssm:SendCommand, ssm:GetCommandInvocation permissions and a default VPC.
Usage
Start the instance (if stopped):
./scripts/windows-debug/start.sh
Run a command on Windows:
./scripts/windows-debug/run.sh "<powershell-command>"
Sync the current git branch and rebuild:
./scripts/windows-debug/sync.sh
Stop the instance when done (avoids cost):
./scripts/windows-debug/stop.sh
Common Workflows
Run unit tests on Windows:
./scripts/windows-debug/run.sh "cd C:\agent-browser && cargo test --manifest-path cli\Cargo.toml"
Run e2e tests on Windows:
./scripts/windows-debug/run.sh "cd C:\agent-browser && cargo test e2e --manifest-path cli\Cargo.toml -- --ignored --test-threads=1"
Check bootstrap progress (first boot only):
./scripts/windows-debug/run.sh "Get-Content C:\bootstrap.log"
The repo lives at C:\agent-browser on the instance. Rust, Git, and Chrome are pre-installed. The run.sh wrapper automatically adds cargo and git to PATH.
Source Code Reference
Source code for dependencies is available in opensrc/ for deeper understanding of implementation details.
See opensrc/sources.json for the list of available packages and their versions.
Use this source code when you need to understand how a package works internally, not just its types/interface.
Fetching Additional Source Code
To fetch source code for a package or repository you need to understand, run:
npx opensrc <package> # npm package (e.g., npx opensrc zod)
npx opensrc pypi:<package> # Python package (e.g., npx opensrc pypi:requests)
npx opensrc crates:<package> # Rust crate (e.g., npx opensrc crates:serde)
npx opensrc <owner>/<repo> # GitHub repo (e.g., npx opensrc vercel/ai)