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
153 lines
5.3 KiB
Markdown
153 lines
5.3 KiB
Markdown
# 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 the `NO_COLOR` environment 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., `--autoConnect` is wrong).
|
|
|
|
## Documentation
|
|
|
|
When adding or changing user-facing features (new flags, commands, behaviors, environment variables, etc.), update **all** of the following:
|
|
|
|
1. `cli/src/output.rs` -- `--help` output (flags list, examples, environment variables)
|
|
2. `README.md` -- Options table, relevant feature sections, examples
|
|
3. `skills/agent-browser/SKILL.md` -- so AI agents know about the feature
|
|
4. `docs/src/app/` -- the Next.js docs site (MDX pages)
|
|
5. 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`, not `SessionTree.tsx`). The `ui/` 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
|
|
|
|
```bash
|
|
cd cli && cargo test
|
|
```
|
|
|
|
Runs all unit tests (~320 tests). These are fast and don't require Chrome.
|
|
|
|
### End-to-End Tests
|
|
|
|
```bash
|
|
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 normal `cargo 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
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
./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):
|
|
|
|
```bash
|
|
./scripts/windows-debug/start.sh
|
|
```
|
|
|
|
Run a command on Windows:
|
|
|
|
```bash
|
|
./scripts/windows-debug/run.sh "<powershell-command>"
|
|
```
|
|
|
|
Sync the current git branch and rebuild:
|
|
|
|
```bash
|
|
./scripts/windows-debug/sync.sh
|
|
```
|
|
|
|
Stop the instance when done (avoids cost):
|
|
|
|
```bash
|
|
./scripts/windows-debug/stop.sh
|
|
```
|
|
|
|
### Common Workflows
|
|
|
|
Run unit tests on Windows:
|
|
|
|
```bash
|
|
./scripts/windows-debug/run.sh "cd C:\agent-browser && cargo test --manifest-path cli\Cargo.toml"
|
|
```
|
|
|
|
Run e2e tests on Windows:
|
|
|
|
```bash
|
|
./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):
|
|
|
|
```bash
|
|
./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.
|
|
|
|
<!-- opensrc:start -->
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
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)
|
|
```
|
|
|
|
<!-- opensrc:end -->
|