lyd123qw2008/pi-control-chrome

pi-control-chrome

English · 简体中文

Codex-aligned Chrome and Edge browser control for Pi, Codex and DSH. It reuses the user's existing Chromium profile through a local WebSocket Bridge and a Manifest V3 extension.

The Stage 1/2 core implementation is complete. Later-stage capabilities remain tracked separately in FEATURES.md.

What it provides

• Reuses the current Chrome or Edge profile, login state, cookies, extensions, and tabs.
• Lets Pi inspect and claim explicitly selected existing tabs without moving them by default.
• Places Agent-created tabs in a dedicated blue Pi tab group.
• Tracks Agent ownership, sessions, handoff, and deliverable lifecycle states.
• Closes unmarked Agent temporary tabs at turn end, releases claimed user tabs without closing them, and preserves only handoff or deliverable tabs marked for the current turn.
• Provides DOM, accessibility, locator, coordinate, and native CDP controls.
• Returns bounded semantic page state by default: visible/actionable snapshot nodes, 20,000-character/200-node snapshot and DOM-CUA budgets, and a shared 12,000-character extract budget. Same-origin iframe text is included by default with bounded frames diagnostics; pass includeFrames: false for shell-only inspection. browser_snapshot keeps refs and snapshotId while Pi/DSH projections omit duplicate raw accessibility and frameTree data; the Bridge advertises capabilities.compactResponses and negotiates compact page-read responses, while unspecified mode remains raw-compatible for older consumers; when tab metadata already carries title and URL, projections do not repeat them inside page results, and full page text is reserved for browser_extract when no semantic state is available.
• Accessibility reads prefer the real Chromium AX tree and support full, incremental-diff, and unchanged states; actionable/focusable AX nodes may carry document-scoped aN refs, which require the matching snapshotId for operations. Sensitive values stay redacted in AX and locator results. If the Accessibility domain is unavailable, reads safely fall back to the DOM semantic tree. Pass disableDiffing: true only when a complete AX state is required. Snapshot, accessibility, extract, and DOM-CUA reads accept optional selector, includeFrames, and output budgets. Pi and DSH adapters omit blank optional selector, snapshotId, incarnation, and screenshot path fields before dispatch.
• Ordinary role/name, label, and accessible-text locator, wait, and interaction targets now try Chromium AX first. AX resolves the computed role/name/state, then maps the current backend DOM node under the existing document/frame fence; successful actions expose internal provenance as resolvedBy: "chromium_ax". AX ambiguity, incomplete trees, and unsafe DOM mapping fail closed. Only an unavailable Accessibility domain, or a text-only target whose custom clickable element is absent from AX, uses the bounded DOM fallback; selectors, test IDs, and placeholders remain DOM-driven.
• Bounds browser_evaluate results to depth 8, 2,000 array items, 200 object fields, and 200,000 characters before returning them through the Bridge.
• Supports screenshots, page extraction, Console, Network, JavaScript dialogs, file upload, downloads, and clipboard text. Console and Network listings retain at most 200 entries and 20,000 serialized characters per read; Console reads support bounded only: "errors" filtering and since/nextSince cursors, including pageerror events.
• browser_probe_interaction performs exactly one explicit page action and returns before/after document identity, action confirmation, post-action Console errors, settle status, and post-action target state for UI regression diagnosis. It never replays an uncertain side effect.
• Captures ordinary active-tab viewport screenshots without opening a DevTools debugger session; full-page and background-tab captures use a short session-owned debugger lease.
• Persists debugger lease identity across an MV3 worker restart. Ordinary cleanup reports an unverified old lease instead of detaching an untracked target; explicit stale recovery verifies the current tab fence and CDP target identity before detaching it.
• Fences tab handles with a tab fence and document identity. Snapshot refs are document-scoped: the same element keeps its number for the life of the document, and a ref outlives the observation that published it (resolved from the page document registry and reported as resolvedBy: document_registry). DOM-CUA node ids are live observations within their originating document: title/focus changes, user tab switching, later observations, and unrelated DOM churn do not invalidate them; an original detached node can be rebound once only when a strongly equivalent replacement is unique. Navigation, reload, and document replacement remain hard boundaries and reject old observations with BROWSER_DOCUMENT_CHANGED; tab closure and tab-fence changes reject them with BROWSER_TAB_CLOSED and BROWSER_TAB_FENCE_CHANGED; navigate(wait: false), back, forward, and reload return a tab marked transitionPending whose handle omits unstable URL/title and document-incarnation fields, so wait or re-observe before document-bound work. Read-only page reads re-observe a user tab and retry once when its document changes, while side-effecting operations that lose document identity return an uncertain result and are not replayed automatically.
• Keeps a Manifest V3 Bridge socket active with application heartbeats, preventing idle worker suspension from creating avoidable connection-generation churn during long browser waits.
• Includes a reusable pi-control-chrome Skill. Browser tool schemas are hidden until that Skill is explicitly loaded for the current session; the bundled CLI remains available for explicit human/developer workflows and tests.