ego-lite AGENTS.md

Repository Guidelines

Project Overview

ego-browser is a Node.js CDP browser-automation harness for AI agents. It drives the ego lite browser through globalThis.ego bindings (provided by the closed-source ego lite app), exposes a compact snapshot/ref workflow, and layers reusable site-specific knowledge ("learnings") on top of the browser runtime.

This repo contains the open-source harness and the agent skill package — not the browser itself. The ego lite app bundles its own ego-browser binary that embeds this runtime; skills/ego-browser/SKILL.md documents that binary's usage (ego-browser nodejs <<'EOF' ... EOF). The repo CLI built here takes the heredoc directly on stdin with no subcommand.

Architecture & Data Flow

• package/ego-browser/src/index.ts is the entrypoint with two startup paths:
  • Executed directly as a CLI → runMain() (reads JavaScript from stdin, executes it).
  • Imported as a module (how the app embeds it) → installEgoSdk(globalThis).
• Both paths expose the same helper surface, built by helperContext() in src/helpers.ts — the single source of truth for what agents can call (including help() and agent_helpers.js extensions).
• src/run.ts executes stdin JavaScript inside an async function with the helpers injected as parameters.
• src/browser-runtime.ts owns CDP transport over ego.sendCDPMessage, session attach/caching (2s TTL, auto re-attach on session loss), the buffered event queue (10k cap), and JS dialog tracking.
• src/cdp-eval.ts provides cdp() and js() (string-expression evaluation; top-level return is auto-wrapped in an IIFE).
• src/element-resolver.ts resolves all target forms — @N refs, loc=css: / loc=role: / loc=href: locators, xpath=, raw CSS — and classifies failures as transient (retryable) or permanent.
• src/ref-map.ts + src/ref-state.ts: refs are numeric backendNodeIds (@21, not @e21). The map is rebuilt on every snapshot; using a ref while the map is empty triggers an automatic re-snapshot, which is what makes refs work across heredoc rounds.
• src/driver/ — nav (tabs, navigation), pointer (click/scroll/drag), keyboard, observe (snapshot/screenshot), waits, files (upload), element-ops (objectId handles), load.
• src/learning/ — discovery, validation, and execution of site skills from skills/ego-browser/learnings/<site>/manifest.json (runSiteTool, runSiteBrowserTool, learnContext).
• src/state.ts is the shared mutable runtime state singleton; src/env.ts resolves the agent workspace (EGO_BROWSER_AGENT_WORKSPACE, falling back to the skill dir bundled next to the build output, then the repo's skills/ego-browser).
• src/help-runtime.ts parses the built bundle's JSDoc with acorn at runtime to power help() — JSDoc on exported helpers is therefore user-facing documentation.