What Is the Site Facade in ego-lite? Purpose, API, and Implementation

The site facade in ego-lite is an abstraction layer that normalizes how automation agents interact with any website by wrapping site-specific configurations into a unified API for navigation, element resolution, and action execution.

In the citrolabs/ego-lite repository, the site facade serves as the critical bridge between the core browser-automation runtime and site-specific "learnings." By decoupling site-specific knowledge from the underlying automation logic, this facade enables the platform to support new websites simply by adding learning packages—bundles of selectors, tools, and validation rules—without modifying the core runtime.

Core Responsibilities of the Site Facade

The facade operates as a normalization layer that presents every website as if it exposes an identical set of high-level operations. Its architecture handles five primary responsibilities.

Uniform API for Cross-Site Automation

Regardless of underlying page structure, the facade exposes consistent helper functions to agent scripts. These include click, type, waitFor, and snapshot, along with site-specific tool execution via runSiteTool. This standardization means that automation scripts written for one site work identically on any other site with an installed learning.

Locator Translation and Resolution

Site-specific locator shortcuts—such as loc=css: or loc=role:—are converted into concrete Chrome DevTools Protocol (CDP) queries or DOM/A11Y queries. According to the source code in src/element-resolver.ts, this translation layer resolves abstract selectors into concrete element references before any interaction occurs.

Error Classification and Retry Logic

The facade classifies resolution failures as either transient (retryable) or permanent (hard errors). As implemented in src/element-resolver.ts, this classification enables the engine’s retry loops to operate reliably across different sites, distinguishing between network timing issues and invalid selectors.

Session Management and Stability

Before executing any operation, the facade validates that a valid CDP session is attached. If a session is lost—due to page navigation or browser disconnection—the facade automatically re-attaches or re-snapshots the page state, ensuring continuity without manual intervention.

Learning Validation and Safety

When a site learning loads, the facade validates its manifest and available tools in src/learning/*. This verification guarantees that only well-formed, stable selectors are used in production, preventing malformed learning packages from crashing automation runs.

How the Site Facade Decouples Site Logic from Runtime

By wrapping site-specific learnings, the facade isolates the core runtime from the complexity of individual website implementations. The runtime interacts only with the facade's standardized interface, while the facade handles the translation to site-specific commands. This separation allows developers to add support for new domains by creating learning packages in src/learning/* rather than modifying core browser drivers in src/driver/*.

Working with the Site Facade API

The facade injects helper functions directly into agent scripts, enabling concise, portable automation code.

Click a button using semantic role locators:

await click('loc=role:button[name="Submit"]');

Wait for dynamic content with configurable timeouts:

await waitFor('loc=css:#results', { timeout: 10 });

Capture the current page state for debugging or validation:

const snapshot = await observe.snapshot();

Execute site-specific tools exposed by the learning package:

await runSiteTool('login', { username: 'alice', password: '••••' });

These helpers are defined in src/helpers.ts, which builds the execution context that the facade injects into every script.

Key Implementation Files

The site facade functionality spans several critical source directories:

• src/helpers.ts – Constructs the helper context injected into agent scripts, providing the unified click, type, and waitFor functions.
• src/element-resolver.ts – Implements locator translation logic and error classification algorithms that determine retry eligibility.
• src/driver/* – Contains low-level CDP drivers for navigation, pointer events, and keyboard input that the facade orchestrates.
• src/learning/* – Handles discovery, validation, and execution of site-specific learnings that the facade wraps and exposes.

Summary

• The site facade normalizes interactions between automation agents and diverse websites in ego-lite.
• It provides a uniform API (click, waitFor, snapshot) regardless of underlying page structure.
• Locator translation converts site-specific shortcuts like loc=css: into concrete CDP or DOM queries via src/element-resolver.ts.
• Error classification distinguishes transient failures from permanent errors, enabling intelligent retry logic.
• Session management automatically re-attaches lost CDP sessions to maintain automation stability.
• The architecture decouples site-specific logic from the core runtime, allowing new sites to be supported solely through learning packages in src/learning/*.

Frequently Asked Questions

What is the primary purpose of the site facade in ego-lite?

The site facade serves as an abstraction layer that allows the core automation runtime to treat every website identically. It wraps site-specific "learnings"—containing selectors, tools, and validation rules—and exposes them through a standardized API, eliminating the need to modify core code when adding support for new sites.

How does the site facade handle different locator strategies?

The facade accepts abstract locator shortcuts such as loc=css: or loc=role: and translates them into concrete queries. According to src/element-resolver.ts, this translation supports both CDP-based queries and standard DOM/A11Y lookups, enabling flexible element resolution across different page architectures.

What happens when a CDP session is lost during execution?

The facade includes session management logic that detects disconnected Chrome DevTools Protocol sessions. When a session is lost—typically during navigation or browser events—the facade automatically re-attaches to the target or re-snapshots the page state, ensuring that subsequent operations proceed without manual session restoration.

Where is the site facade implemented in the codebase?

The facade's functionality is distributed across src/helpers.ts (API construction), src/element-resolver.ts (locator translation and error handling), src/driver/* (low-level CDP automation drivers), and src/learning/* (site-specific learning validation and execution).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}