# Edge Kit Browser Human-style browsing for AI agents — a zero-dependency [Cordis](https://github.com/moeru-ai) plugin for DeepSeek Harness that drives **Microsoft Edge, Google Chrome, or Mozilla Firefox** directly, with no extra services and no API keys. The kit talks to the browser the way a person does: it *sees* the page (visible text + numbered actionable elements, shadow-DOM aware), *acts* (click, type, press, scroll — real input events), *verifies* (screenshots, wait-for-content), and *organizes* work across tabs. It also powers the harness's native `web_search` / `web_fetch` seam, so agents get clean, JavaScript-rendered content from signed-in or bot-walled pages. ## What it does - **Human-style browsing** — `see`, `click`, `clickAt`, `drag`, `type`, `press` (real key codes + repeats), `scroll`, `waitFor`, `goto`, tabs, screenshots, raw `eval`. - **Video understanding** — the `video` action enumerates players, reports full playback state (`playing`, `currentTime`, `duration`, `readyState`, geometry, source), controls them (`play`/`pause`/`seek`/`rate`), and captures PNG frames straight off the player region. - **Gameplay** — correct key codes (Space is actually Space), coordinate clicks, and drags, plus before/after screenshots: agents can literally play a browser game and see what happened. - **Native web seam** — registers `edge-kit` as a `web_search` / `web_fetch` provider: rendered-page extraction with dual-engine fallback (Google/Bing), no bot walls, no API keys. - **Live-attach first** — if a debuggable browser is already listening, the kit attaches to it (borrowed browsers are never closed). Otherwise it launches: your signed-in profile (default) or an isolated kit profile. ## Install Run the deploy self-check first — it finds your browsers, checks Node, ports, profile dirs and direct egress, then prints the exact integration steps (Windows, Linux and macOS): ```bash node setup.mjs # exit code 0 = ready to integrate ``` Copy this package into your harness profile (or `pnpm install` it as a workspace link), then add to your composition: ```yaml - insert: - id: edge-kit-easy name: "@local/edge-kit-easy" config: {} ``` Optionally route the built-in web tools through the kit (pin the seam): ```yaml - id: web config: fetchProvider: edge-kit searchProvider: edge-kit ``` Settings live on the plugin's native page (**Plugins → Edge Kit Browser**); every field is volatile, so changes apply live without restarting the browser session. ## How it drives each browser | Engine | Protocol | Launch flags | Port (default) | |---|---|---|---| | Edge / Chrome | CDP over WebSocket (`/json/version`) | `--remote-debugging-port`, `--user-data-dir`, anti-occlusion | 9444 (Edge) | | Firefox | **WebDriver BiDi** (`/session`) — the kit contains a CDP→BiDi adapter | `-remote-debugging-port`, `-profile`, `-no-remote` | — | Firefox (158+) exposes WebDriver BiDi on its debug port rather than CDP; the adapter translates every call transparently, including `session.status`/`session.new` handshaking, `script.evaluate` with `expression`, `browsingContext.captureScreenshot` (`{type:'box'}` clips), and load-event mapping. Per-browser profiles: the user's real profile by default (`realProfile`), or isolated kit profiles under `~/.dsh/browser-profiles/edge-kit[-chrome|-firefox]`. If your everyday browser owns the profile, pass `relaunch: true` to restart it debuggable (logins survive) or set `profileDir`. Browser discovery is cross-platform — Windows, Linux (apt **and** snap paths, including `chromium`) and macOS, for all three browsers; pass `executablePath` for anything exotic. ## Actions `launch` · `attach` · `status` · `tabs` · `newTab` · `switchTab` · `closeTab` · `goto` · `back` · `forward` · `reload` · `see` · `click` · `clickAt` · `drag` · `video` · `type` · `press` · `scroll` · `waitFor` · `eval` · `screenshot` · `wait` · `proxy` · `close` ## Proxy support `proxy {op:auto|set|status|clear, proxyChain:"ip:port[,ip:port,...]", chainTo?}`: - **auto** — probes every candidate by fetching an IP echo **through** it (ladder: checkip.amazonaws.com → ifconfig.me → ipinfo.io, so a single rate-limited echo service can't fake a failure), picks the fastest working proxy, restarts the browser onto it, and reports the verified exit IP/country. - **set** — installs a list verbatim. One hop is handed to the browser directly (`--proxy-server`); two or more are **chained** through an in-kit local CONNECT forwarder (browser → 127.0.0.1 → hop1 → hop2 → … → origin), verified end-to-end before the switch — a rejected chain falls back to the fastest single hop (or errors, in `set`). - **status** — live re-probe of the current route; **clear** — direct traffic again. `chainTo` adds one chained hop behind the auto-pick. Switching routes force-closes any survivor browser process (Edge startup-boost / profile handoff) before relaunch, so the new proxy state can never be silently lost — logins survive, windows reopen. - The `proxyChain` setting preloads a chain into every launch; the native web seam (`web_fetch` / `web_search`) rides the same route. - **Fully built in** — no system/v2ray proxy anywhere in the path: probes use raw sockets, and launched browsers get explicit proxy state (`--proxy-server` when routing; `--no-proxy-server` / `network.proxy.type:0` when direct, with `HTTP(S)_PROXY`/`ALL_PROXY` stripped from the launch environment). A local v2ray can never silently capture the browser. - A candidate whose echo comes back **with your own egress IP** is rejected as *transparent* — a route that doesn't change your exit is a no-op, not a proxy. `setup.mjs` also disables Edge's startup boost (registry policy) so background Edge processes can't re-grab the debug port with stale, proxy-less flags. A proxy counts as *working* only when an echo comes back through it — no blind trust in proxy-list sites. ## Running under MIDAS MIDAS loads plugins but has no Cordis runtime, so `midas/` supplies one: - **`midas/kitd.mjs`** — the host. Builds the smallest `ctx` the plugin asks for (`tools.register`, `web.registerSearchProvider`, `web.registerFetchProvider`, `effect`), applies the kit with a plain-object config, and republishes the kit's tool and both web providers over a loopback HTTP seam on `127.0.0.1:7789` (`/health`, `/tool-def`, `/tool`, `/search`, `/fetch`, `/settings`, `/shutdown`). It runs as its own process on purpose: the launched browser is the expensive part, and a warm profile survives MIDAS restarting. - **`midas/kit.settings.json`** — host defaults (`browser`, `headless`, `port`, `searchEngine`, caps, `chromiumArgs`). Edit and restart the host to apply. - **`midas/plugin.js`** — the MIDAS plugin. Starts the host on demand, then registers `edge_kit` (the full action surface), `edge_kit_search` and `edge_kit_fetch`. MIDAS reserves the built-in `websearch` / `webfetch` ids, so a plugin tool cannot take those names; instead the plugin hooks `tool.execute.after` and upgrades a thin built-in `webfetch` result to the rendered page. Register it in `~/.config/midas/midas.json`: ```json { "plugin": ["file:///root/gitea/8ball/edge-kit/midas/plugin.js"] } ``` Env overrides: `EDGE_KIT_REPO` (checkout), `EDGE_KIT_HTTP` (seam URL), `EDGE_KIT_NODE` (node binary — `process.execPath` inside MIDAS is the MIDAS binary, so the plugin looks for a real node itself). Headless Linux launches needed two additions to `index.js`, both harmless elsewhere: `--no-sandbox` is appended automatically when running as uid 0, and the new `chromiumArgs` setting appends whatever extra flags a container wants. ## Troubleshooting - **`Maximum number of active sessions` (Firefox)** — a zombie Firefox is holding the BiDi session slot; terminate `firefox.exe` and relaunch. - **DevTools port never opens** — your normal browser owns that profile: pass `relaunch: true` or a separate `profileDir`. - **Screenshots black on headless/console sessions** — the kit launches with anti-occlusion flags and `fromSurface:false` to avoid this; on Firefox use the default screenshot path.