How to Inject Ego-Browser SDK Helpers into globalThis: Complete Guide

To inject Ego-Browser SDK helpers into globalThis, use the installEgoSdk function exported from package/ego-browser/src/index.ts in the citrolabs/ego-lite repository, which creates a helper context, removes legacy globals, and defines non-enumerable properties for page, browser, and other facades on your target object.

The citrolabs/ego-lite repository provides the Ego-Browser SDK as a set of helper functions designed for browser automation and agent scripting. When you inject ego-browser SDK helpers into globalThis, you make utilities like page, browser, taskSpaces, site, and fetch available globally within your execution environment, enabling seamless scripting without explicit imports in every module.

Understanding the SDK Installation Architecture

The installEgoSdk Function

The core mechanism for injecting helpers resides in package/ego-browser/src/index.ts. This file exports installEgoSdk, the primary installer function responsible for attaching the SDK to any target object. According to the source code, this function orchestrates the entire injection process by coordinating context creation, legacy cleanup, and property definition.

Helper Context Creation

Before injection occurs, the installer calls helperContext() defined in package/ego-browser/src/helpers.ts (lines 22-36). This function builds the facades for:

• page – Page manipulation utilities
• browser – Browser-level controls
• taskSpaces – Task space management
• site – Site-specific skill handlers
• fetch – Network request helpers

The context function returns an object containing these exposed helpers, which the installer then attaches to the target.

Step-by-Step Injection Process

When you call installEgoSdk(target), the function executes five distinct operations:

1. Creates the helper context – Invokes helperContext() to instantiate all facade objects.
2. Deletes legacy global helpers – Iterates over LEGACY_GLOBAL_HELPERS (e.g., click, goto) and removes any existing definitions from the target to prevent conflicts (lines 51-57).
3. Defines non-enumerable properties – Uses Object.defineProperty(target, name, { value: exposed, ... }) (lines 66-73 in index.ts) to attach each helper as a non-enumerable property, ensuring they don't appear in for...in loops or Object.keys().
4. Attaches the helper bundle – Assigns target.ego.helpers = installed (lines 94-98), creating a reference to the full helper bundle on the Ego runtime object.
5. Wraps mutating methods – Applies wrapCreateTab and wrapInvalidating (lines 81-84) to Ego-specific methods like createTab and useTaskSpace, ensuring internal session state remains consistent when these methods are called.

Automatic vs. Manual Installation

The Ego-Browser SDK supports two installation modes depending on your usage context.

Automatic Installation (Script Mode)

When importing the module as a script via node ego-browser ... or using the default import, the SDK automatically invokes installEgoSdk() at the bottom of package/ego-browser/src/index.ts. This side-effect import immediately populates globalThis with all helpers.

// Automatic injection on import
import 'ego-browser'

// Helpers are now available on globalThis
await page.goto('https://example.com')
await click('#submit')

Manual Installation (Library Mode)

When using the SDK as a library within your own application, import installEgoSdk explicitly and provide a custom target object. This approach allows you to inject helpers into sandboxes, virtual machines, or iframe contexts.

import { installEgoSdk } from 'ego-browser'

const sandbox = {}
installEgoSdk(sandbox)

// Use helpers from the custom object
await sandbox.page.goto('https://example.com')
await sandbox.click('#login')

Practical Implementation Examples

Injecting into a Custom Sandbox

For isolated execution environments, inject helpers into a plain object to avoid polluting the global scope:

import { installEgoSdk } from 'ego-browser'

const isolatedContext = {}
installEgoSdk(isolatedContext)

// All helpers available on the isolated context
await isolatedContext.browser.newContext()
await isolatedContext.page.screenshot({ path: 'capture.png' })

Injecting into a VM Context

When running untrusted code in a virtual machine (VM2 or Node.js VM module), inject the SDK into the VM's global object:

import { installEgoSdk } from 'ego-browser'
import { VM } from 'vm2'

const vm = new VM()
installEgoSdk(vm.globalThis)

// Helpers available within VM execution
vm.run(`
  await page.goto('https://example.com')
  return browser.version()
`)

Accessing the Helper Bundle

After installation, access the complete helper bundle through the Ego runtime property:

installEgoSdk(globalThis)

// Access the raw helper objects
console.log(globalThis.ego.helpers.page)
console.log(globalThis.ego.helpers.browser)

Key Source Files Reference

File	Role
package/ego-browser/src/index.ts	Exports installEgoSdk, handles legacy global cleanup, defines helpers on target, and wraps Ego runtime methods.
package/ego-browser/src/helpers.ts	Implements helperContext() to build facades for page, browser, taskSpaces, site, and fetch operations.
package/ego-browser/src/run.ts	CLI entry point that triggers automatic SDK installation when the module executes directly.
package/ego-browser/src/browser-runtime.ts	Provides session-management utilities (invalidateSession, clearPreferredTarget) that the installer wraps for consistency.

Summary

• installEgoSdk is the primary function for injecting Ego-Browser SDK helpers, located in package/ego-browser/src/index.ts.
• The installer creates a helper context via helperContext() in helpers.ts, then attaches facades for page, browser, taskSpaces, site, and fetch.
• Legacy globals (defined in LEGACY_GLOBAL_HELPERS) are automatically purged before injection to prevent naming collisions.
• Helpers are attached as non-enumerable properties using Object.defineProperty, ensuring they don't interfere with enumeration loops.
• The installation process wraps mutating methods like createTab to maintain internal session state consistency.
• You can inject into globalThis automatically via side-effect import or manually into custom objects like VM contexts.

Frequently Asked Questions

How do I prevent Ego-Browser from polluting the global scope?

Import installEgoSdk explicitly and pass a custom object instead of using the automatic installation. This injects ego-browser SDK helpers into your specified target (e.g., a sandbox object) rather than globalThis, keeping the global namespace clean while still providing full SDK functionality within your controlled context.

What happens if legacy global helpers like click or goto already exist?

The installEgoSdk function includes a cleanup phase that iterates over LEGACY_GLOBAL_HELPERS and deletes any existing properties with those names from the target object before defining the new helpers. This prevents conflicts between old and new API versions, ensuring consistent behavior according to the implementation in package/ego-browser/src/index.ts (lines 51-57).

Can I install the SDK helpers into multiple different contexts?

Yes, installEgoSdk is designed to be called multiple times with different target objects. Each call creates a fresh helper context and attaches it to the supplied target. This allows you to maintain separate SDK instances in different VM contexts, iframes, or sandboxed environments, each with isolated state and helper references.

Why are the helpers defined as non-enumerable properties?

The SDK uses Object.defineProperty with the non-enumerable flag (lines 66-73 in index.ts) to ensure that helpers like page and browser don't appear when enumerating object properties with for...in loops or Object.keys(). This design choice prevents the SDK methods from interfering with user scripts that iterate over global properties, while still making them accessible as direct property references.

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