How to Use the `site` Facade for Site Skills in ego-lite

The site facade in ego-lite provides a runtime interface for discovering and executing site-specific skills through methods like runTool(), runBrowserTool(), and lookup(), automatically injected into agent scripts without requiring manual imports.

The ego-lite framework exposes a powerful abstraction layer for browser automation through the site facade, enabling agent scripts to interact with domain-specific capabilities called site skills. This facade is automatically injected into the helper context via helperContext() in src/helpers.ts, allowing seamless access to Node tools and browser tools defined in site-specific manifests. Understanding how to leverage the site facade unlocks the full potential of ego-lite's modular skill system for complex web automation tasks.

Understanding the Site Facade Architecture

The site facade operates as a runtime bridge between agent scripts and site-specific skill definitions stored in skills/ego-browser/learnings/<site-id>/manifest.json. According to the ego-lite source code in src/learning/index.ts, the facade exposes four primary methods for skill interaction: runTool() for Node environment execution, runBrowserTool() for browser context evaluation, lookup() for domain resolution, and knowledge() for retrieving site metadata.

Under the hood, domain matching occurs in src/learning/check-domain-learning.ts, which iterates over all learning directories to match hostnames against manifest domain arrays. Once matched, src/learning/validate-learning-format.ts validates the manifest structure before tool execution proceeds.

Core Facade Methods

The facade provides these essential entry points:

• site.runTool(siteId, toolName, args) – Executes a Node tool defined in the site's manifest within the agent's Node environment.
• site.runBrowserTool(siteId, toolName, args) – Executes a browser tool via Chrome DevTools Protocol (CDP) inside the controlled browser context.
• site.lookup(urlOrHostname) – Resolves a URL or hostname to its matching site skill, returning { siteId, siteName } or null.
• site.knowledge(url) – Retrieves compiled site metadata including notes and selector hints for LLM prompting.

Site Skill Structure and Manifest Files

Before invoking facade methods, ego-lite expects site skills to follow a specific directory structure. Each site skill resides in its own subdirectory under skills/ego-browser/learnings/ and must contain a manifest.json file defining the site's capabilities.

A valid manifest includes:

• domains: Array of hostnames the skill targets.
• nodeTools: Definitions for Node.js environment tools.
• browserTools: Definitions for browser-context tools.
• notes: Documentation content for LLM prompting.

Executing Node Tools with site.runTool

The site.runTool(siteId, toolName, args) method executes Node-based tools defined in a site's manifest. This method, implemented in src/learning/index.ts, dynamically imports tool files using loadNodeTool and validates the exported callable before invocation.

// Resolve site and execute Node tool
const url = "https://example.com/product/123";
const info = await site.lookup(url);

if (info) {
  const price = await site.runTool(info.siteId, "priceLookup", { 
    productId: "123" 
  });
  console.log("Price:", price);
}

The method signature accepts three parameters: siteId (the directory name), toolName (the key from nodeTools), and args (an object passed to the tool function).

Running Browser Tools with site.runBrowserTool

For operations requiring direct browser interaction, site.runBrowserTool(siteId, toolName, args) injects tool source into the controlled browser context. This method utilizes the helper js() function to evaluate scripts within the page environment via CDP, returning DOM-extracted data directly to the agent script.

// Extract page title using browser-side tool
await site.runBrowserTool("hackernews", "extractTitle", { 
  selector: "h1.title" 
})
.then(title => console.log("Page title:", title));

Resolving Sites with site.lookup

Before executing tools, scripts typically resolve URLs to site skills using site.lookup(urlOrHostname). This method parses the input URL and compares it against the domains array in each manifest file, as implemented in src/learning/check-domain-learning.ts.

const info = await site.lookup("https://news.ycombinator.com");
if (info) {
  console.log(`Matched site: ${info.siteName} (${info.siteId})`);
}

Retrieving Site Knowledge

The site.knowledge(url) method retrieves compiled site metadata including notes content and selector hints. This information proves valuable for constructing LLM prompts with domain-specific context.

const knowledge = await site.knowledge("https://news.ycombinator.com");
console.log("Site notes:", knowledge.notes);
console.log("Selector hints:", knowledge.selectorHints);

Complete Integration Example

The following example demonstrates combining lookup, browser tools, and Node tools within a task-space script where the site object is pre-injected:

// Check if site exists for the URL
if (await site.lookup("https://news.ycombinator.com")) {
  // Extract data using browser tool
  const items = await site.runBrowserTool(
    "hackernews", 
    "listTopPosts", 
    { limit: 5 }
  );
  
  // Process with Node tool
  const summary = await site.runTool("hackernews", "summarizePosts", {
    posts: items
  });
  
  console.log(summary);
}

Summary

• The site facade is automatically available in ego-lite agent scripts through src/helpers.ts, requiring no manual imports.
• Site skills are stored in skills/ego-browser/learnings/<site-id>/ with a mandatory manifest.json file.
• Use site.lookup() to resolve URLs to site IDs before invoking tools.
• site.runTool() executes Node.js environment tools, while site.runBrowserTool() runs code inside the browser context via CDP.
• The domain matching logic lives in src/learning/check-domain-learning.ts, and tool dispatch is handled in src/learning/index.ts.

Frequently Asked Questions

What is the site facade in ego-lite?

The site facade is a runtime interface exposed through the helper context that enables agent scripts to discover and invoke site-specific skills. It abstracts the complexity of loading manifests, matching domains, and dispatching tools, allowing developers to interact with website-specific automation logic through a consistent API.

How does site.runTool differ from site.runBrowserTool?

site.runTool() executes Node.js modules within the agent's Node environment, suitable for API calls, data processing, or file system operations. site.runBrowserTool() injects and executes JavaScript inside the controlled browser page via Chrome DevTools Protocol, enabling DOM manipulation, element extraction, and page interaction that requires actual browser context.

Where are site skill manifests stored?

Site skill manifests are located at skills/ego-browser/learnings/<site-id>/manifest.json relative to the ego-lite installation. Each site ID corresponds to a subdirectory containing the manifest.json file that declares domains, tools, and metadata for that specific site.

Do I need to import the site facade manually?

No. The site facade is automatically injected into the helper context by helperContext() in src/helpers.ts. When running scripts through the ego-browser CLI or within a task-space, the site object is available as a global-like variable without requiring import statements or explicit initialization.

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