@modelrelay/sdk 1.28.0 → 1.29.0

package/dist/node.d.cts

@@ -146,4 +146,203 @@ declare function createLocalFSToolPack(options: LocalFSToolPackOptions): LocalFS
  */
 declare function createLocalFSTools(options: LocalFSToolPackOptions): ToolRegistry;
 
-export { DEFAULT_IGNORE_DIRS, FSDefaults, ToolNames as FSToolNames, LocalFSToolPack, type LocalFSToolPackOptions, createLocalFSToolPack, createLocalFSTools };
+/**
+ * Browser automation tools using Playwright with accessibility tree extraction.
+ *
+ * Uses CDP (Chrome DevTools Protocol) for semantic element targeting instead of
+ * pixel-based screenshots, making it 10-100x cheaper than vision-based automation.
+ *
+ * @example
+ * ```typescript
+ * import { BrowserToolPack, createBrowserTools } from "@modelrelay/sdk";
+ *
+ * // Create a browser tool pack with domain restrictions
+ * const pack = new BrowserToolPack({
+ *   allowedDomains: ["example.com", "docs.example.com"],
+ *   headless: true,
+ * });
+ *
+ * // Initialize the browser (must be called before use)
+ * await pack.initialize();
+ *
+ * // Get tool definitions for LLM
+ * const tools = pack.getToolDefinitions();
+ *
+ * // Get registry for executing tool calls
+ * const registry = pack.toRegistry();
+ *
+ * // Clean up when done
+ * await pack.close();
+ * ```
+ *
+ * @module
+ */
+
+type Browser = any;
+type BrowserContext = any;
+/**
+ * Tool names for browser automation.
+ */
+declare const BrowserToolNames: {
+    /** Navigate to a URL and return accessibility tree */
+    readonly NAVIGATE: "browser.navigate";
+    /** Click an element by accessible name/role */
+    readonly CLICK: "browser.click";
+    /** Type text into an input field */
+    readonly TYPE: "browser.type";
+    /** Get current accessibility tree */
+    readonly SNAPSHOT: "browser.snapshot";
+    /** Scroll the page */
+    readonly SCROLL: "browser.scroll";
+    /** Capture a screenshot */
+    readonly SCREENSHOT: "browser.screenshot";
+    /** Extract data using CSS selectors */
+    readonly EXTRACT: "browser.extract";
+};
+/**
+ * Default configuration values for browser tools.
+ */
+declare const BrowserDefaults: {
+    /** Navigation timeout in milliseconds */
+    readonly NAVIGATION_TIMEOUT_MS: 30000;
+    /** Action timeout in milliseconds */
+    readonly ACTION_TIMEOUT_MS: 5000;
+    /** Maximum nodes to include in accessibility tree output */
+    readonly MAX_SNAPSHOT_NODES: 500;
+    /** Maximum screenshot size in bytes */
+    readonly MAX_SCREENSHOT_BYTES: 5000000;
+};
+/**
+ * Configuration options for BrowserToolPack.
+ */
+interface BrowserToolPackOptions {
+    /**
+     * Whitelist of allowed domains. If set, only URLs matching these domains
+     * will be allowed. Supports suffix matching (e.g., "example.com" matches
+     * "sub.example.com").
+     */
+    allowedDomains?: string[];
+    /**
+     * Blacklist of blocked domains. URLs matching these domains will be rejected.
+     * Supports suffix matching.
+     */
+    blockedDomains?: string[];
+    /**
+     * Navigation timeout in milliseconds. Default: 30000
+     */
+    navigationTimeoutMs?: number;
+    /**
+     * Action timeout in milliseconds. Default: 5000
+     */
+    actionTimeoutMs?: number;
+    /**
+     * Maximum nodes to include in accessibility tree. Default: 500
+     */
+    maxSnapshotNodes?: number;
+    /**
+     * Run browser in headless mode. Default: true
+     */
+    headless?: boolean;
+    /**
+     * Existing Browser instance to use instead of creating a new one.
+     */
+    browser?: Browser;
+    /**
+     * Existing BrowserContext to use instead of creating a new one.
+     */
+    context?: BrowserContext;
+}
+/**
+ * A tool pack for browser automation using Playwright.
+ *
+ * Uses accessibility tree extraction via CDP for efficient, semantic-based
+ * browser automation. This is much cheaper than vision-based approaches
+ * because it works with structured text instead of screenshots.
+ *
+ * @example
+ * ```typescript
+ * const pack = new BrowserToolPack({
+ *   allowedDomains: ["example.com"],
+ * });
+ * await pack.initialize();
+ *
+ * const registry = pack.toRegistry();
+ * const result = await registry.execute(toolCall);
+ *
+ * await pack.close();
+ * ```
+ */
+declare class BrowserToolPack {
+    private browser;
+    private context;
+    private page;
+    private cdpSession;
+    private ownsBrowser;
+    private ownsContext;
+    private cfg;
+    constructor(options?: BrowserToolPackOptions);
+    /**
+     * Initialize the browser. Must be called before using any tools.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Close the browser and clean up resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Get tool definitions for use with LLM APIs.
+     */
+    getToolDefinitions(): Tool[];
+    /**
+     * Register tool handlers into an existing registry.
+     */
+    registerInto(registry: ToolRegistry): ToolRegistry;
+    /**
+     * Create a new registry with just this pack's tools.
+     */
+    toRegistry(): ToolRegistry;
+    private ensureInitialized;
+    private parseArgs;
+    private validateUrl;
+    /**
+     * Validates the current page URL against allowlist/blocklist.
+     * Called after navigation and before any action to catch redirects
+     * and in-session navigation to blocked domains.
+     */
+    private ensureCurrentUrlAllowed;
+    private getAccessibilityTree;
+    private formatAXTree;
+    private navigate;
+    private click;
+    private type;
+    private snapshot;
+    private scroll;
+    private screenshot;
+    private extract;
+}
+/**
+ * Create a BrowserToolPack with the given options.
+ */
+declare function createBrowserToolPack(options?: BrowserToolPackOptions): BrowserToolPack;
+/**
+ * Create a ToolRegistry with browser tools registered.
+ *
+ * Note: You must call `pack.initialize()` before using the registry.
+ *
+ * @example
+ * ```typescript
+ * const { pack, registry } = createBrowserTools({ headless: true });
+ * await pack.initialize();
+ *
+ * // Use registry to execute tool calls
+ * const result = await registry.execute(toolCall);
+ *
+ * await pack.close();
+ * ```
+ */
+declare function createBrowserTools(options?: BrowserToolPackOptions): {
+    pack: BrowserToolPack;
+    registry: ToolRegistry;
+};
+
+export { BrowserDefaults, BrowserToolNames, BrowserToolPack, type BrowserToolPackOptions, DEFAULT_IGNORE_DIRS, FSDefaults, ToolNames as FSToolNames, LocalFSToolPack, type LocalFSToolPackOptions, createBrowserToolPack, createBrowserTools, createLocalFSToolPack, createLocalFSTools };

package/dist/node.d.ts

@@ -146,4 +146,203 @@ declare function createLocalFSToolPack(options: LocalFSToolPackOptions): LocalFS
  */
 declare function createLocalFSTools(options: LocalFSToolPackOptions): ToolRegistry;
 
-export { DEFAULT_IGNORE_DIRS, FSDefaults, ToolNames as FSToolNames, LocalFSToolPack, type LocalFSToolPackOptions, createLocalFSToolPack, createLocalFSTools };
+/**
+ * Browser automation tools using Playwright with accessibility tree extraction.
+ *
+ * Uses CDP (Chrome DevTools Protocol) for semantic element targeting instead of
+ * pixel-based screenshots, making it 10-100x cheaper than vision-based automation.
+ *
+ * @example
+ * ```typescript
+ * import { BrowserToolPack, createBrowserTools } from "@modelrelay/sdk";
+ *
+ * // Create a browser tool pack with domain restrictions
+ * const pack = new BrowserToolPack({
+ *   allowedDomains: ["example.com", "docs.example.com"],
+ *   headless: true,
+ * });
+ *
+ * // Initialize the browser (must be called before use)
+ * await pack.initialize();
+ *
+ * // Get tool definitions for LLM
+ * const tools = pack.getToolDefinitions();
+ *
+ * // Get registry for executing tool calls
+ * const registry = pack.toRegistry();
+ *
+ * // Clean up when done
+ * await pack.close();
+ * ```
+ *
+ * @module
+ */
+
+type Browser = any;
+type BrowserContext = any;
+/**
+ * Tool names for browser automation.
+ */
+declare const BrowserToolNames: {
+    /** Navigate to a URL and return accessibility tree */
+    readonly NAVIGATE: "browser.navigate";
+    /** Click an element by accessible name/role */
+    readonly CLICK: "browser.click";
+    /** Type text into an input field */
+    readonly TYPE: "browser.type";
+    /** Get current accessibility tree */
+    readonly SNAPSHOT: "browser.snapshot";
+    /** Scroll the page */
+    readonly SCROLL: "browser.scroll";
+    /** Capture a screenshot */
+    readonly SCREENSHOT: "browser.screenshot";
+    /** Extract data using CSS selectors */
+    readonly EXTRACT: "browser.extract";
+};
+/**
+ * Default configuration values for browser tools.
+ */
+declare const BrowserDefaults: {
+    /** Navigation timeout in milliseconds */
+    readonly NAVIGATION_TIMEOUT_MS: 30000;
+    /** Action timeout in milliseconds */
+    readonly ACTION_TIMEOUT_MS: 5000;
+    /** Maximum nodes to include in accessibility tree output */
+    readonly MAX_SNAPSHOT_NODES: 500;
+    /** Maximum screenshot size in bytes */
+    readonly MAX_SCREENSHOT_BYTES: 5000000;
+};
+/**
+ * Configuration options for BrowserToolPack.
+ */
+interface BrowserToolPackOptions {
+    /**
+     * Whitelist of allowed domains. If set, only URLs matching these domains
+     * will be allowed. Supports suffix matching (e.g., "example.com" matches
+     * "sub.example.com").
+     */
+    allowedDomains?: string[];
+    /**
+     * Blacklist of blocked domains. URLs matching these domains will be rejected.
+     * Supports suffix matching.
+     */
+    blockedDomains?: string[];
+    /**
+     * Navigation timeout in milliseconds. Default: 30000
+     */
+    navigationTimeoutMs?: number;
+    /**
+     * Action timeout in milliseconds. Default: 5000
+     */
+    actionTimeoutMs?: number;
+    /**
+     * Maximum nodes to include in accessibility tree. Default: 500
+     */
+    maxSnapshotNodes?: number;
+    /**
+     * Run browser in headless mode. Default: true
+     */
+    headless?: boolean;
+    /**
+     * Existing Browser instance to use instead of creating a new one.
+     */
+    browser?: Browser;
+    /**
+     * Existing BrowserContext to use instead of creating a new one.
+     */
+    context?: BrowserContext;
+}
+/**
+ * A tool pack for browser automation using Playwright.
+ *
+ * Uses accessibility tree extraction via CDP for efficient, semantic-based
+ * browser automation. This is much cheaper than vision-based approaches
+ * because it works with structured text instead of screenshots.
+ *
+ * @example
+ * ```typescript
+ * const pack = new BrowserToolPack({
+ *   allowedDomains: ["example.com"],
+ * });
+ * await pack.initialize();
+ *
+ * const registry = pack.toRegistry();
+ * const result = await registry.execute(toolCall);
+ *
+ * await pack.close();
+ * ```
+ */
+declare class BrowserToolPack {
+    private browser;
+    private context;
+    private page;
+    private cdpSession;
+    private ownsBrowser;
+    private ownsContext;
+    private cfg;
+    constructor(options?: BrowserToolPackOptions);
+    /**
+     * Initialize the browser. Must be called before using any tools.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Close the browser and clean up resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Get tool definitions for use with LLM APIs.
+     */
+    getToolDefinitions(): Tool[];
+    /**
+     * Register tool handlers into an existing registry.
+     */
+    registerInto(registry: ToolRegistry): ToolRegistry;
+    /**
+     * Create a new registry with just this pack's tools.
+     */
+    toRegistry(): ToolRegistry;
+    private ensureInitialized;
+    private parseArgs;
+    private validateUrl;
+    /**
+     * Validates the current page URL against allowlist/blocklist.
+     * Called after navigation and before any action to catch redirects
+     * and in-session navigation to blocked domains.
+     */
+    private ensureCurrentUrlAllowed;
+    private getAccessibilityTree;
+    private formatAXTree;
+    private navigate;
+    private click;
+    private type;
+    private snapshot;
+    private scroll;
+    private screenshot;
+    private extract;
+}
+/**
+ * Create a BrowserToolPack with the given options.
+ */
+declare function createBrowserToolPack(options?: BrowserToolPackOptions): BrowserToolPack;
+/**
+ * Create a ToolRegistry with browser tools registered.
+ *
+ * Note: You must call `pack.initialize()` before using the registry.
+ *
+ * @example
+ * ```typescript
+ * const { pack, registry } = createBrowserTools({ headless: true });
+ * await pack.initialize();
+ *
+ * // Use registry to execute tool calls
+ * const result = await registry.execute(toolCall);
+ *
+ * await pack.close();
+ * ```
+ */
+declare function createBrowserTools(options?: BrowserToolPackOptions): {
+    pack: BrowserToolPack;
+    registry: ToolRegistry;
+};
+
+export { BrowserDefaults, BrowserToolNames, BrowserToolPack, type BrowserToolPackOptions, DEFAULT_IGNORE_DIRS, FSDefaults, ToolNames as FSToolNames, LocalFSToolPack, type LocalFSToolPackOptions, createBrowserToolPack, createBrowserTools, createLocalFSToolPack, createLocalFSTools };