Files
edge-kit/README.md
T
8ball 30346f026c midas: host the kit under MIDAS as its web search/fetch provider
MIDAS loads plugins but has no Cordis runtime, so the kit had no way to
register its tool or its web providers here. midas/kitd.mjs builds the
smallest ctx the plugin asks for and republishes the tool and both
providers over a loopback seam; midas/plugin.js is that seam's client and
brings up the host on demand, keeping the browser warm across restarts.

Headless Linux runs need two additions in index.js: --no-sandbox when
running as uid 0, and a chromiumArgs setting for container-specific flags.

Co-Authored-By: MIDAS <hello@trymidas.io>
2026-11-10 15:47:53 +00:00

8.1 KiB

Edge Kit Browser

Human-style browsing for AI agents — a zero-dependency Cordis 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):

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:

- insert:
    - id: edge-kit-easy
      name: "@local/edge-kit-easy"
      config: {}

Optionally route the built-in web tools through the kit (pin the seam):

- 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:

    { "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.