Skip to content

architecture.md

Latest commit

 

History

History
73 lines (50 loc) · 2.98 KB

architecture.md

File metadata and controls

73 lines (50 loc) · 2.98 KB
Raw

Architecture: CDP vs Playwright vs extension

Layers

Agent (Cursor / Codex / QuickerAgent)
  └─ Tool surface (CLI / MCP / skill)
       ├─ Dedicated profile + CDP          ← lab primary path
       │    └─ Chrome/Edge --user-data-dir=lab-profile --remote-debugging-port=N
       └─ Extension bridge                 ← logged-in user browser only
            └─ Quicker Connector / chrome.* APIs / optional chrome.debugger

Primary path: dedicated profile + CDP

Use when the agent can operate in an isolated browser (fresh or lab-persisted logins), and you care about:

  • Accessibility tree snapshots (Accessibility.getFullAXTree)
  • Compact @eN refs for click/fill
  • Network, screenshots, multi-target debugging

How

  1. scripts/start-cdp.ps1 starts Chrome/Edge with a separate user-data-dir (default under %LOCALAPPDATA%\QuickerOrg\agent-browser-lab\).
  2. Main browser stays open; no profile lock fight.
  3. Drive the instance with agent-browser, Playwright connectOverCDP, or raw CDP WebSocket.

Prefer high-level actions (Playwright locator / agent-browser click @eN) over raw Input.dispatchMouseEvent for everyday navigate-click-fill. Use raw CDP when measuring protocols or needing debugger-only APIs.

Secondary path: extension bridge

Use when the task requires cookies / tabs already open in the user's daily browser.

Capabilities (product side, not reimplemented here):

  • Tab query / activate / open URL
  • RunScript / element ops via Quicker sys:chromecontrol
  • MCP: qkrpc_chrome_control / qkrpc_chrome_tabs

Limits (MV3):

  • No native Accessibility CDP from a normal content script
  • User-scripts permission for some RunScript worlds
  • Restricted pages (chrome://, store, often file://)
  • Message size and round-trips through the host

Optional hybrid (research only): extension chrome.debugger attach to one tab for CDP without restarting Chrome with --remote-debugging-port. Sensitive permission; not the default agent path.

Playwright placement

Mode Login model Role in lab
Launch Chromium Isolated Fast tests; not the user's Chrome
connectOverCDP to lab profile Lab profile cookies Preferred Playwright mode for this lab
Extension / Connector User cookies Product path; out of this harness

Playwright shines for auto-wait and locator stability. CDP shines for AX tree fidelity and DevTools-depth APIs. Agent CLIs (agent-browser) optimize token cost of snapshots.

Observation rule (all paths)

Default observation = interactive accessibility snapshot, not full HTML or unlabeled screenshots.

See observation-protocol.md.

Decision tree (short)

Need user cookies / existing tabs?
  yes → extension / qkrpc chrome tools
  no  → start-cdp.ps1 → agent-browser or Playwright CDP
         measuring AX / network → raw CDP experiment
         everyday agent loop → CLI snapshot -i + refs