# chrome-cdp

Drive one extension-owned Chrome process from Pi using raw Chrome DevTools Protocol JSON.
The root `pi-ext` package loads this extension; no separate package install is needed.

## Usage

- `/chrome` toggles the `chrome_cdp` tool and checks for a Chrome binary without launching it; first tool call starts Chrome with a temporary profile and random loopback debugging port.
- Start Pi with `--chrome` or set `chrome-cdp.enable` to `true` to enable the tool at startup.
- `/chrome close` stops Chrome and deactivates the tool; a sole managed `close` operation stops it without deactivating the tool.
- Page-scoped CDP methods need an explicit `sessionId` from the returned status or `Target.attachToTarget`; browser-scoped methods omit it.
- `operations` runs sequentially and stops on error; failed batches include `failedOperation` with zero-based `operation` and `kind`, plus zero-based `skipped` operations; use labeled replies as whole-value references such as `{{label.result.path}}`.
- Managed operations include waits, screenshots, WebM video, performance traces, status, and close.
- A labeled command supports one `wait` in each batch; use distinct labeled commands for separate waits.
- Chrome's `/json/protocol` URL appears in status; consult it for the running browser's command schema.

## Configuration

Set keys under `"chrome-cdp"` in project `.pi/settings.json` or user `~/.pi/agent/settings.json`:

```json
{
  "chrome-cdp": {
    "enable": false,
    "profile": "work",
    "executablePath": "/path/to/chrome",
    "artifactDir": "/path/to/captures",
    "flags": []
  }
}
```

Each key resolves on its own: trusted project settings, then user settings, then unset.
`enable` resolves `--chrome` first and defaults to `false`; the flag can only express `true`.
Untrusted project settings are ignored.
`enable` must be a boolean; `executablePath`, `profile`, and `artifactDir` must be strings; `flags` must be an array of strings that replaces rather than merges with lower sources.
An invalid value never falls back to a lower source.
An invalid `enable` warns at session start and leaves the tool off.
Other invalid values fail the next launch with the error, and `/chrome` shows it as a warning.

A named profile lives in extension-owned OS application data; omitting `profile` uses a disposable profile.
Managed captures default to OS Downloads unless `artifactDir` is set; browser downloads use a separate temporary directory.
`ffmpeg` is needed only for WebM recording.
Set `PI_CHROME_CDP_DEBUG=1` to force bounded metadata-only diagnostics, or `=0` to disable them.
Otherwise, set user-level `pi-ext.debug` to `true`, `"chrome-cdp"`, or `["chrome-cdp"]` in `~/.pi/agent/settings.json`.
See [debug contract](../DEBUG.md).

Raw CDP is unrestricted and may access local URLs, browser data, or override download settings; managed capture paths are not a sandbox.
Events, traces, browser profiles, and captures can contain secrets.
Spool paths returned by a batch remain until its next batch starts or Chrome closes; when current-batch files consume the 16 MiB spool quota, later responses fail rather than deleting returned files.
Replay returns only event files containing events after `replayFrom`; an evicted in-memory event returns `lost: true` without `spooled`, while `status.gaps` counts discarded spool data.
Linux real-Chrome checks exist; macOS and Windows launch paths are not empirically verified.

## Verification

- `mise run //extensions/chrome-cdp:lint`
- `mise run //extensions/chrome-cdp:test`
- `mise run //extensions/chrome-cdp:check`
- `mise run //extensions/chrome-cdp:e2e` runs real-Chrome acceptance checks and writes temporary profiles, test captures, and a named test profile outside this repository.
- `mise run //extensions/chrome-cdp:bench -- 60 compare` measures large labeled-response handling; see [benchmark methodology](__bench__/README.md).