# citrolabs/ego-lite architecture

> Architecture diagram of the GitHub repository citrolabs/ego-lite, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/citrolabs/ego-lite
- Repository: https://github.com/citrolabs/ego-lite

## Overview

ego-browser is the JavaScript connection layer that lets external agents automate ego lite’s browser. The documented workflow is: an agent submits browser-side JavaScript, the runtime operates in a page within an isolated task Space, and the agent receives structured results such as snapshots or extracted data. Page navigation, observation, interaction, and result delivery are distinct stages; page-model orchestration and reference tracking support them internally. The README documents parallel Spaces and high-quality snapshots. Source excerpts confirm selected page-action and learning-tool wiring, but do not expose every API dispatch, so uncertain links are omitted.

Main entry points: [`package/ego-browser/src/page-model.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/page-model.ts) (Task Spaces), [`package/ego-browser/src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/browser-runtime.ts) (Browser runtime), [`package/ego-browser/src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/run.ts) (Task runner), [`package/ego-browser/src/driver/page-waits.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/page-waits.ts) (Navigation and waits)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Agent interface"]
  node_api["Public API<br/>[index.ts]"]
  node_runner["Task runner<br/>[run.ts]"]
  node_output["Output sink<br/>[output-sink.ts]"]
end

subgraph group_spaces["Spaces and pages"]
  node_spaces["Task Spaces<br/>[page-model.ts]"]
  node_browser["Browser runtime<br/>[browser-runtime.ts]"]
  node_state["Page state<br/>[state.ts]"]
  node_ledger["Page ledger<br/>[page-ledger.ts]"]
  node_discovery["Page discovery<br/>[page-discovery.ts]"]
  node_refs["Page references"]
end

subgraph group_automation["Page automation"]
  node_snapshot["Snapshots<br/>[snapshot-result.ts]"]
  node_observe["Page observation<br/>[observe.ts]"]
  node_nav["Navigation and waits<br/>[page-waits.ts]"]
  node_actions["Page actions<br/>[page-actions.ts]"]
  node_resolve["Element resolution"]
  node_keyboard["Keyboard input<br/>[page-keyboard.ts]"]
  node_downloads["Downloads<br/>[downloads.ts]"]
end

subgraph group_skills["Site skills"]
  node_learning["Learning loader<br/>[index.ts]"]
  node_sitefiles["Site tools"]
end

node_agent(("Agent"))
node_browserservice["ego lite browser"]

node_agent -->|"calls tools"| node_api
node_api -->|"executes code"| node_runner
node_runner -->|"runs in Space"| node_spaces
node_runner -->|"emits results"| node_output
node_spaces -->|"controls browser"| node_browser
node_browser -->|"uses runtime"| node_browserservice
node_spaces -->|"tracks state"| node_state
node_spaces -->|"tracks pages"| node_ledger
node_spaces -->|"discovers pages"| node_discovery
node_spaces -->|"tracks refs"| node_refs
node_spaces -->|"navigates and waits"| node_nav
node_spaces -->|"creates snapshots"| node_snapshot
node_spaces -->|"dispatches actions"| node_actions
node_spaces -->|"dispatches keys"| node_keyboard
node_spaces -->|"handles downloads"| node_downloads
node_spaces -->|"observes pages"| node_observe
node_actions -->|"resolves targets"| node_resolve
node_actions -->|"sends CDP commands"| node_browser
node_nav -->|"resolves selectors"| node_resolve
node_nav -->|"sends CDP commands"| node_browser
node_learning -->|"loads site tools"| node_sitefiles
node_agent -.->|"requests learned context"| node_learning

click node_api "https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts"
click node_runner "https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/run.ts"
click node_output "https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/output-sink.ts"
click node_spaces "https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/page-model.ts"
click node_browser "https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/browser-runtime.ts"
click node_state "https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/state.ts"
click node_ledger "https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/page-ledger.ts"
click node_discovery "https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/page-discovery.ts"
click node_refs "https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/page-ref-registry.ts"
click node_snapshot "https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/snapshot-result.ts"
click node_observe "https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/observe.ts"
click node_nav "https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/page-waits.ts"
click node_actions "https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/page-actions.ts"
click node_resolve "https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/element-resolver.ts"
click node_keyboard "https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/page-keyboard.ts"
click node_downloads "https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/downloads.ts"
click node_learning "https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/learning/index.ts"
click node_sitefiles "https://github.com/citrolabs/ego-lite/tree/main/skills/ego-browser/learnings"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_runner,node_output,node_browserservice toneBlue
class node_spaces,node_browser,node_state,node_ledger,node_discovery,node_refs toneAmber
class node_snapshot,node_observe,node_nav,node_actions,node_resolve,node_keyboard,node_downloads toneMint
class node_learning,node_sitefiles toneRose
class node_agent toneIndigo
```

## Components

### Agent interface

- [Public API](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts): `package/ego-browser/src/index.ts`
- [Task runner](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/run.ts): `package/ego-browser/src/run.ts`
- [Output sink](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/output-sink.ts): `package/ego-browser/src/output-sink.ts`

### Spaces and pages

- [Task Spaces](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/page-model.ts): `package/ego-browser/src/page-model.ts`
- [Browser runtime](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/browser-runtime.ts): `package/ego-browser/src/browser-runtime.ts`
- [Page state](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/state.ts): `package/ego-browser/src/state.ts`
- [Page ledger](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/page-ledger.ts): `package/ego-browser/src/page-ledger.ts`
- [Page discovery](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/page-discovery.ts): `package/ego-browser/src/page-discovery.ts`
- [Page references](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/page-ref-registry.ts): `package/ego-browser/src/page-ref-registry.ts`

### Page automation

- [Snapshots](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/snapshot-result.ts): `package/ego-browser/src/snapshot-result.ts`
- [Page observation](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/observe.ts): `package/ego-browser/src/driver/observe.ts`
- [Navigation and waits](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/page-waits.ts): `package/ego-browser/src/driver/page-waits.ts`
- [Page actions](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/page-actions.ts): `package/ego-browser/src/driver/page-actions.ts`
- [Element resolution](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/element-resolver.ts): `package/ego-browser/src/element-resolver.ts`
- [Keyboard input](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/page-keyboard.ts): `package/ego-browser/src/driver/page-keyboard.ts`
- [Downloads](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/downloads.ts): `package/ego-browser/src/driver/downloads.ts`

### Site skills

- [Learning loader](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/learning/index.ts): `package/ego-browser/src/learning/index.ts`
- [Site tools](https://github.com/citrolabs/ego-lite/tree/main/skills/ego-browser/learnings): `skills/ego-browser/learnings`

### Other components

- **Agent**
- **ego lite browser**

## Connections

- Agent → Public API: calls tools
- Public API → Task runner: executes code
- Task runner → Task Spaces: runs in Space
- Task runner → Output sink: emits results
- Task Spaces → Browser runtime: controls browser
- Browser runtime → ego lite browser: uses runtime
- Task Spaces → Page state: tracks state
- Task Spaces → Page ledger: tracks pages
- Task Spaces → Page discovery: discovers pages
- Task Spaces → Page references: tracks refs
- Task Spaces → Navigation and waits: navigates and waits
- Task Spaces → Snapshots: creates snapshots
- Task Spaces → Page actions: dispatches actions
- Task Spaces → Keyboard input: dispatches keys
- Task Spaces → Downloads: handles downloads
- Task Spaces → Page observation: observes pages
- Page actions → Element resolution: resolves targets
- Page actions → Browser runtime: sends CDP commands
- Navigation and waits → Element resolution: resolves selectors
- Navigation and waits → Browser runtime: sends CDP commands
- Learning loader → Site tools: loads site tools
- Agent → Learning loader: requests learned context