Web Access Edge

Windows browser automation for Codex and AI agents — persistent Microsoft Edge sessions, verified input, and multi-frame CDP control.

简体中文 · Quick start · Upstream comparison · API · Benchmarks

Turn an Edge browser into a local HTTP tool for an AI agent. Observe controls with accessibility snapshots, act through real CDP input, verify the resulting page state, and close only the tabs owned by the task. No npm runtime packages or hosted browser subscription are required.

This is an independent Windows / Codex edition derived from eze-is/web-access. It has its own skill name, configuration directory, default ports and maintenance history. See attribution and the pinned comparison.

Why this edition?

Everyday problem	What Web Access Edge adds
Reconnecting to the daily browser repeatedly prompts for debugging access	A dedicated, persistent Edge profile with a fixed loopback CDP port, verified startup and a reusable connection. Log in once in that profile.
An agent says it typed, but a controlled form did not accept the text	Native /type input with result verification, including Chinese, emoji and contenteditable. Rejected input returns an error.
A form lives inside a cross-origin iframe or Shadow DOM	Multi-frame accessibility snapshots with short references such as @e12, including nested out-of-process iframes.
A click lands on an overlay or a moving button	Native clicks check visibility, enabled state, stability and parent-frame hit tests.
A workflow opens tabs, popups or starts a download	Task-owned tab cleanup, popup adoption, download completion events and JavaScript dialog handling.
Agent context fills up with page dumps	Filter snapshots by interactive controls, role, name, frame, depth and node limit.

Local SQLite site memory stores verified strategies, promotes patterns only after success across three domains, and decays old evidence. History/bookmark search helps find previously visited URLs. Static reading and source discovery are routed through the host agent's existing tools; this repository does not bundle a separate search engine or LLM.

Quick start (Windows)

Use Windows 11, Microsoft Edge, Git and Node.js 24. The supported live-browser path is Windows + Edge. Linux CI checks the offline runtime, not browser support.

Open PowerShell and install as a separate Codex skill:

$skill = Join-Path $env:USERPROFILE '.codex\skills\web-access-edge'
git clone https://github.com/jayhigh425/web-access-edge.git $skill
if ($LASTEXITCODE -ne 0) { throw 'Clone failed; inspect any existing directory.' }
Set-Location $skill
npm.cmd test
if ($LASTEXITCODE -ne 0) { throw 'Tests failed.' }

For fewer remote-debugging prompts, select a dedicated persistent profile:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\edge-debug.ps1 Prepare
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\edge-debug.ps1 Activate
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\edge-debug.ps1 Start
npm.cmd start

These commands create a Web Access Edge Start menu shortcut and select %LOCALAPPDATA%\Codex\web-access-edge\edge-user-data. Sign into your sites in that window; the profile retains subsequent logins. It uses browser port 9334 and proxy port 3457. The daily Edge profile is not reused by this mode. To show the dedicated window, open its Start menu shortcut.

Restart Codex or reload skills if the new skill is not listed, then try:

Use $web-access-edge to open my Edge browser and complete this web task.

Run the local, account-free demo:

npm.cmd run demo

It opens a generated page, observes input and button references, types Chinese and English, clicks, verifies the displayed result and closes its task tab. Native actions can bring the test window to the foreground.

Already using the daily Edge debugging toggle? You can skip dedicated-profile setup and run npm.cmd start after enabling edge://inspect/#remote-debugging. That route can still require Edge's native permission confirmation. This project does not override that permission dialog.

Small API, explicit outcomes

Default proxy: http://127.0.0.1:3457. Full request formats, frame handling, error codes and cleanup are in the API reference.

Workflow	Endpoints
Connection and health	/health, /connect
Task ownership	/session/start, /session/status, /session/end
Navigation and readiness	/new, /navigate, /wait, /info
Observe controls	/snapshot, /frames, /eval, /screenshot
Act and verify	/type, /key, /clickAt, /select, /setFiles
Complete browser workflows	/downloads, /dialog, /popups

Use finally to end each task. Existing user tabs require explicit attachment; ending a task detaches them. keep=1 preserves task result pages. Snapshots report incomplete or truncated results; stale references return errors so an agent can observe again. A click response means input was dispatched: verify the receipt, changed page or target content before declaring the task complete.

Background behavior and permissions

Creating tabs, navigation, observation and waiting can run in the background. Native clicks, typing and keys intentionally activate the target page for reliable viewport and iframe input routing. This version is not fully hidden or headless. It supports web alert / confirm / prompt dialogs; those are different from browser debugging permission or operating-system dialogs.

The dedicated profile avoided repeated native debugging confirmation in the maintainer's Windows 11 / Edge 154 tests. Browser updates, managed policies, site logins and second-factor verification can change behavior. It is not a promise of permanent permission bypass.

The proxy binds to loopback and has no application authentication. It is a local tool for trusted programs with powerful browser and file access. Keep it on your own computer. Cookies, logins, site memory and configuration stay outside this repository. Only perform actions authorized by the user.

Validation and performance

npm.cmd test           # syntax + 19 offline / mock-CDP checks
npm.cmd run test:live  # 41 real Edge checks; start the proxy first

Live fixtures cover controlled/native inputs, contenteditable, open/closed Shadow DOM, nested cross-origin frames, stale refs, overlays, transforms, selects, dialogs, downloads, popups and cleanup. They use local synthetic pages and can activate test tabs. No real account is needed.

Click stability checks add latency: a small synthetic benchmark measured a median around 60 ms per native click, compared with roughly 4 ms in the previous local implementation. That is a reliability tradeoff, not a claim of universal speed improvement. Measurements and limitations.

Maintenance and troubleshooting

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\web-access.ps1 Diagnose
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\web-access.ps1 Restart
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\web-access.ps1 Update

Updates fetch this repository's origin/main, preserve uncommitted customizations, create a backup branch and run offline tests. Failed validation rolls back the merge. Stop stops this proxy; edge-debug.ps1 Restore restores the previous profile selection and shortcut while retaining profile data. Windows operations and rollback.

If startup fails, run edge-debug.ps1 Status, check the selected browser port and inspect local logs. An explicit unavailable profile/port does not silently switch to another Edge instance. Do not restart for every ordinary page error.

English and Chinese bug reports are welcome. Include a minimal reproduction and OS / Edge / Node versions. Contributing.

MIT license. Original Web Access by 一泽Eze; Windows / Edge enhancements and this edition maintained by jayhigh425. Microsoft Edge, Codex and ChatGPT are names of their respective products; this project is independently maintained.