How to Run Learned Site Tools and Browser Tools Using ego-lite

Use runSiteTool() for server-side Node tools and runSiteBrowserTool() for client-side browser tools after discovering available capabilities via siteSkills() or learnContext().

The ego-lite framework from citrolabs/ego-lite provides a learning subsystem that allows sites to contribute reusable automation scripts. These learned tools enable agents to invoke domain-specific logic either within the Node.js host process or directly inside the browser page context via Chrome DevTools Protocol (CDP).

Understanding Learned Tool Types

ego-lite categorizes learned capabilities into two distinct execution environments:

• Node (server-side) site tools – Execute inside the Node.js process hosting the ego-lite helpers. These are ideal for file-system operations, heavy computation, or API orchestration. Invoke these using runSiteTool(siteId, toolName, args?).

• Browser (client-side) site tools – Execute within the current page's JavaScript environment using CDP evaluation. These handle DOM-centric actions like extraction or interaction. Invoke these using runSiteBrowserTool(siteId, toolName, args?).

Discovering Available Tools

Before invoking tools, you must identify what capabilities exist for your target domain. The framework provides two discovery helpers in src/helpers.ts.

Query Site Skills with siteSkills()

The siteSkills() function returns available tools matching a specific URL (defaulting to the current page). According to the source code in package/ego-browser/src/helpers.ts (lines 64-78), this helper chains through siteSkillsForUrl() to siteSkillsForUrlCore(), which traverses the learned-skills directory.

const skills = await siteSkills();  // Defaults to current page URL
// Returns: [{ siteId, siteName, tools: [{ toolName, toolType, ... }] }, ...]

Load Full Context with learnContext()

For complete site intelligence including notes, signatures, and examples, use learnContext(). Defined at lines 13-18 in src/helpers.ts, this delegates to loadLearnedContext() in src/learning/index.ts (lines 46-58), which reads the site's manifest.json and associated documentation.

const ctx = await learnContext();  // Returns { knowledge, tools, ... }
console.log(ctx.tools);            // Array of available tool definitions

Both helpers rely on check-domain-learning.js within the learning module to match URLs against site IDs in the skills/ego-browser/learnings/ directory structure.

Executing Learned Tools

Once you have the siteId and toolName from discovery, invoke the appropriate runner based on the tool's execution context.

Running Node Site Tools with runSiteTool()

For server-side logic, runSiteTool() forwards your request to runNodeSiteTool() in src/learning/index.ts (lines 45-75). This loads the tool's module, resolves the exported callable, and executes it with the current helper context.

// Execute a Node tool for x-com that extracts timeline data
const result = await runSiteTool('x-com', 'extractTimeline', { page: 1 });
console.log('Node tool result:', result);

The helper automatically injects the helper context via helperContext() and the agent workspace path, allowing the tool to call other ego-lite helpers like click() or goto() without manual wiring.

Running Browser Site Tools with runSiteBrowserTool()

For DOM operations, runSiteBrowserTool() retrieves the tool source via loadBrowserToolSource() and evaluates it in the page context. As implemented in src/helpers.ts (lines 99-105) and src/learning/index.ts (lines 78-96), this uses evaluate(wrapBrowserTool(...)) to inject arguments and return the async result.

// Execute a browser tool for google that extracts search results
const html = await runSiteBrowserTool('google', 'extractSearchResults', { 
  query: 'ego-lite' 
});
console.log('Extracted HTML:', html);

Complete Workflow Example

This end-to-end example demonstrates discovery, selection by type, and execution:

// Step 1: Discover tools for the current page
const { tools } = await learnContext();
console.log('Available tools:', tools.map(t => t.toolName));

// Step 2: Execute a Node tool if available
const nodeTool = tools.find(t => t.toolType === 'node');
if (nodeTool) {
  const output = await runSiteTool(
    nodeTool.siteId, 
    nodeTool.toolName, 
    { foo: 'bar' }
  );
  console.log('Node output:', output);
}

// Step 3: Execute a Browser tool if available
const browserTool = tools.find(t => t.toolType === 'browser');
if (browserTool) {
  const output = await runSiteBrowserTool(
    browserTool.siteId, 
    browserTool.toolName, 
    { query: 'ego' }
  );
  console.log('Browser output:', output);
}

Summary

• Discovery: Use siteSkills() for quick tool listings or learnContext() for full site intelligence including notes and examples.
• Node Execution: Use runSiteTool() for server-side scripts that run in the Node.js process, defined in src/learning/index.ts.
• Browser Execution: Use runSiteBrowserTool() for client-side scripts evaluated in the page context via CDP.
• Context Injection: Both runners automatically provide helper context and workspace paths to tools, enabling seamless integration with other ego-lite functions.
• Storage: Tools reside in skills/ego-browser/learnings/{siteId}/ with manifests defining nodeTools and browserTools arrays.

Frequently Asked Questions

What is the difference between node and browser tools in ego-lite?

Node tools execute within the Node.js process hosting the ego-lite framework, enabling file-system access, database operations, and complex computation. Browser tools execute inside the actual web page via Chrome DevTools Protocol, allowing direct DOM manipulation and extraction. Choose node tools for data processing tasks and browser tools for page interaction tasks.

How does ego-lite match tools to a specific website?

The framework uses check-domain-learning.js (part of the learning module) to match URLs against site IDs in the skills/ego-browser/learnings/ directory. When you call siteSkills() or learnContext(), the system traverses this directory, validates manifest.json files, and returns tools associated with the matching domain.

Can learned tools access other ego-lite helpers?

Yes. When runSiteTool() or runSiteBrowserTool() executes a tool, it automatically injects the helper context (via helperContext()) and the agent workspace path. This allows learned tools to invoke any standard ego-lite helper such as goto(), click(), or type() without requiring explicit imports or configuration.

Where are learned tool manifests and implementations stored?

Site-specific learned data resides in skills/ego-browser/learnings/{siteId}/. Each site contains a manifest.json listing available nodeTools and browserTools with their paths and callables, a tools/ directory containing the actual JavaScript implementations, and a notes/ directory with Markdown documentation that populates learnContext() results.

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