sentienceapi 0.90.1

package/dist/agent.js

@@ -0,0 +1,437 @@
+"use strict";
+/**
+ * Sentience Agent: High-level automation agent using LLM + SDK
+ * Implements observe-think-act loop for natural language commands
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SentienceAgent = void 0;
+const snapshot_1 = require("./snapshot");
+const actions_1 = require("./actions");
+const crypto_1 = require("crypto");
+/**
+ * High-level agent that combines Sentience SDK with any LLM provider.
+ *
+ * Uses observe-think-act loop to execute natural language commands:
+ * 1. OBSERVE: Get snapshot of current page state
+ * 2. THINK: Query LLM to decide next action
+ * 3. ACT: Execute action using SDK
+ *
+ * Example:
+ * ```typescript
+ * import { SentienceBrowser, SentienceAgent, OpenAIProvider } from 'sentience-ts';
+ *
+ * const browser = await SentienceBrowser.create({ apiKey: 'sentience_key' });
+ * const llm = new OpenAIProvider('openai_key', 'gpt-4o');
+ * const agent = new SentienceAgent(browser, llm);
+ *
+ * await browser.getPage().goto('https://google.com');
+ * await agent.act('Click the search box');
+ * await agent.act("Type 'magic mouse' into the search field");
+ * await agent.act('Press Enter key');
+ * ```
+ */
+class SentienceAgent {
+    /**
+     * Initialize Sentience Agent
+     * @param browser - SentienceBrowser instance
+     * @param llm - LLM provider (OpenAIProvider, AnthropicProvider, etc.)
+     * @param snapshotLimit - Maximum elements to include in context (default: 50)
+     * @param verbose - Print execution logs (default: true)
+     * @param tracer - Optional tracer for recording execution (default: undefined)
+     */
+    constructor(browser, llm, snapshotLimit = 50, verbose = true, tracer) {
+        this.browser = browser;
+        this.llm = llm;
+        this.snapshotLimit = snapshotLimit;
+        this.verbose = verbose;
+        this.tracer = tracer;
+        this.stepCount = 0;
+        this.history = [];
+        this.tokenUsage = {
+            totalPromptTokens: 0,
+            totalCompletionTokens: 0,
+            totalTokens: 0,
+            byAction: []
+        };
+    }
+    /**
+     * Execute a high-level goal using observe → think → act loop
+     * @param goal - Natural language instruction (e.g., "Click the Sign In button")
+     * @param maxRetries - Number of retries on failure (default: 2)
+     * @param snapshotOptions - Optional snapshot parameters (limit, filter, etc.)
+     * @returns Result dict with status, action_taken, reasoning, and execution data
+     *
+     * Example:
+     * ```typescript
+     * const result = await agent.act('Click the search box');
+     * console.log(result);
+     * // { success: true, action: 'click', elementId: 42, ... }
+     * ```
+     */
+    async act(goal, maxRetries = 2, snapshotOptions) {
+        if (this.verbose) {
+            console.log('\n' + '='.repeat(70));
+            console.log(`🤖 Agent Goal: ${goal}`);
+            console.log('='.repeat(70));
+        }
+        // Increment step counter and generate step ID
+        this.stepCount += 1;
+        const stepId = (0, crypto_1.randomUUID)();
+        // Emit step_start event
+        if (this.tracer) {
+            const currentUrl = this.browser.getPage().url();
+            this.tracer.emitStepStart(stepId, this.stepCount, goal, 0, currentUrl);
+        }
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                // 1. OBSERVE: Get refined semantic snapshot
+                const startTime = Date.now();
+                const snapOpts = {
+                    ...snapshotOptions,
+                    goal: snapshotOptions?.goal ?? goal,
+                    limit: snapshotOptions?.limit || this.snapshotLimit,
+                };
+                const snap = await (0, snapshot_1.snapshot)(this.browser, snapOpts);
+                if (snap.status !== 'success') {
+                    throw new Error(`Snapshot failed: ${snap.error}`);
+                }
+                // Apply element filtering based on goal
+                const filteredElements = this.filterElements(snap, goal);
+                // Create filtered snapshot
+                const filteredSnap = {
+                    ...snap,
+                    elements: filteredElements
+                };
+                // Emit snapshot event
+                if (this.tracer) {
+                    this.tracer.emit('snapshot', {
+                        url: filteredSnap.url,
+                        elements: filteredSnap.elements.slice(0, 50).map(el => ({
+                            id: el.id,
+                            bbox: el.bbox,
+                            role: el.role,
+                            text: el.text?.substring(0, 100),
+                        }))
+                    }, stepId);
+                }
+                // 2. GROUND: Format elements for LLM context
+                const context = this.buildContext(filteredSnap, goal);
+                // 3. THINK: Query LLM for next action
+                const llmResponse = await this.queryLLM(context, goal);
+                if (this.verbose) {
+                    console.log(`🧠 LLM Decision: ${llmResponse.content}`);
+                }
+                // Emit LLM response event
+                if (this.tracer) {
+                    this.tracer.emit('llm_response', {
+                        model: llmResponse.modelName,
+                        prompt_tokens: llmResponse.promptTokens,
+                        completion_tokens: llmResponse.completionTokens,
+                        response_text: llmResponse.content.substring(0, 500),
+                    }, stepId);
+                }
+                // Track token usage
+                this.trackTokens(goal, llmResponse);
+                // Parse action from LLM response
+                const actionStr = llmResponse.content.trim();
+                // 4. EXECUTE: Parse and run action
+                const result = await this.executeAction(actionStr, filteredSnap);
+                const durationMs = Date.now() - startTime;
+                result.durationMs = durationMs;
+                result.attempt = attempt;
+                result.goal = goal;
+                // Emit action event
+                if (this.tracer) {
+                    this.tracer.emit('action', {
+                        action_type: result.action,
+                        element_id: result.elementId,
+                        text: result.text,
+                        key: result.key,
+                        success: result.success,
+                    }, stepId);
+                }
+                // 5. RECORD: Track history
+                this.history.push({
+                    goal,
+                    action: actionStr,
+                    result,
+                    success: result.success,
+                    attempt,
+                    durationMs
+                });
+                if (this.verbose) {
+                    const status = result.success ? '✅' : '❌';
+                    console.log(`${status} Completed in ${durationMs}ms`);
+                }
+                return result;
+            }
+            catch (error) {
+                // Emit error event
+                if (this.tracer) {
+                    this.tracer.emitError(stepId, error.message, attempt);
+                }
+                if (attempt < maxRetries) {
+                    if (this.verbose) {
+                        console.log(`⚠️  Retry ${attempt + 1}/${maxRetries}: ${error.message}`);
+                    }
+                    await new Promise(resolve => setTimeout(resolve, 1000));
+                    continue;
+                }
+                else {
+                    const errorResult = {
+                        success: false,
+                        goal,
+                        error: error.message,
+                        attempt,
+                        durationMs: 0
+                    };
+                    this.history.push(errorResult);
+                    throw new Error(`Failed after ${maxRetries} retries: ${error.message}`);
+                }
+            }
+        }
+        throw new Error('Unexpected: loop should have returned or thrown');
+    }
+    /**
+     * Filter elements from snapshot based on goal context.
+     * Applies goal-based keyword matching to boost relevant elements and filters out irrelevant ones.
+     */
+    filterElements(snap, goal) {
+        let elements = snap.elements;
+        // If no goal provided, return all elements (up to limit)
+        if (!goal) {
+            return elements.slice(0, this.snapshotLimit);
+        }
+        const goalLower = goal.toLowerCase();
+        // Extract keywords from goal
+        const keywords = this.extractKeywords(goalLower);
+        // Boost elements matching goal keywords
+        const scoredElements = [];
+        for (const el of elements) {
+            let score = el.importance;
+            // Boost if element text matches goal
+            if (el.text && keywords.some(kw => el.text.toLowerCase().includes(kw))) {
+                score += 0.3;
+            }
+            // Boost if role matches goal intent
+            if (goalLower.includes('click') && el.visual_cues.is_clickable) {
+                score += 0.2;
+            }
+            if (goalLower.includes('type') && (el.role === 'textbox' || el.role === 'searchbox')) {
+                score += 0.2;
+            }
+            if (goalLower.includes('search')) {
+                // Filter out non-interactive elements for search tasks
+                if ((el.role === 'link' || el.role === 'img') && !el.visual_cues.is_primary) {
+                    score -= 0.5;
+                }
+            }
+            scoredElements.push([score, el]);
+        }
+        // Re-sort by boosted score
+        scoredElements.sort((a, b) => b[0] - a[0]);
+        elements = scoredElements.map(([, el]) => el);
+        return elements.slice(0, this.snapshotLimit);
+    }
+    /**
+     * Extract meaningful keywords from goal text
+     */
+    extractKeywords(text) {
+        const stopwords = new Set([
+            'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
+            'of', 'with', 'by', 'from', 'as', 'is', 'was'
+        ]);
+        const words = text.split(/\s+/);
+        return words.filter(w => !stopwords.has(w) && w.length > 2);
+    }
+    /**
+     * Convert snapshot elements to token-efficient prompt string
+     * Format: [ID] <role> "text" {cues} @ (x,y) (Imp:score)
+     * Note: elements are already filtered by filterElements() in act()
+     */
+    buildContext(snap, goal) {
+        const lines = [];
+        for (const el of snap.elements) {
+            // Extract visual cues
+            const cues = [];
+            if (el.visual_cues.is_primary)
+                cues.push('PRIMARY');
+            if (el.visual_cues.is_clickable)
+                cues.push('CLICKABLE');
+            if (el.visual_cues.background_color_name) {
+                cues.push(`color:${el.visual_cues.background_color_name}`);
+            }
+            // Format element line
+            const cuesStr = cues.length > 0 ? ` {${cues.join(',')}}` : '';
+            const text = el.text || '';
+            const textPreview = text.length > 50 ? text.substring(0, 50) + '...' : text;
+            lines.push(`[${el.id}] <${el.role}> "${textPreview}"${cuesStr} ` +
+                `@ (${Math.floor(el.bbox.x)},${Math.floor(el.bbox.y)}) (Imp:${el.importance})`);
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Query LLM with standardized prompt template
+     */
+    async queryLLM(domContext, goal) {
+        const systemPrompt = `You are an AI web automation agent.
+
+GOAL: ${goal}
+
+VISIBLE ELEMENTS (sorted by importance, max ${this.snapshotLimit}):
+${domContext}
+
+VISUAL CUES EXPLAINED:
+- {PRIMARY}: Main call-to-action element on the page
+- {CLICKABLE}: Element is clickable
+- {color:X}: Background color name
+
+RESPONSE FORMAT:
+Return ONLY the function call, no explanation or markdown.
+
+Available actions:
+- CLICK(id) - Click element by ID
+- TYPE(id, "text") - Type text into element
+- PRESS("key") - Press keyboard key (Enter, Escape, Tab, ArrowDown, etc)
+- FINISH() - Task complete
+
+Examples:
+- CLICK(42)
+- TYPE(15, "magic mouse")
+- PRESS("Enter")
+- FINISH()
+`;
+        const userPrompt = 'What is the next step to achieve the goal?';
+        return await this.llm.generate(systemPrompt, userPrompt, { temperature: 0.0 });
+    }
+    /**
+     * Parse action string and execute SDK call
+     */
+    async executeAction(actionStr, snap) {
+        // Parse CLICK(42)
+        let match = actionStr.match(/CLICK\s*\(\s*(\d+)\s*\)/i);
+        if (match) {
+            const elementId = parseInt(match[1], 10);
+            const result = await (0, actions_1.click)(this.browser, elementId);
+            return {
+                success: result.success,
+                action: 'click',
+                elementId,
+                outcome: result.outcome,
+                urlChanged: result.url_changed,
+                durationMs: 0,
+                attempt: 0,
+                goal: ''
+            };
+        }
+        // Parse TYPE(42, "hello world")
+        match = actionStr.match(/TYPE\s*\(\s*(\d+)\s*,\s*["']([^"']*)["']\s*\)/i);
+        if (match) {
+            const elementId = parseInt(match[1], 10);
+            const text = match[2];
+            const result = await (0, actions_1.typeText)(this.browser, elementId, text);
+            return {
+                success: result.success,
+                action: 'type',
+                elementId,
+                text,
+                outcome: result.outcome,
+                durationMs: 0,
+                attempt: 0,
+                goal: ''
+            };
+        }
+        // Parse PRESS("Enter")
+        match = actionStr.match(/PRESS\s*\(\s*["']([^"']+)["']\s*\)/i);
+        if (match) {
+            const key = match[1];
+            const result = await (0, actions_1.press)(this.browser, key);
+            return {
+                success: result.success,
+                action: 'press',
+                key,
+                outcome: result.outcome,
+                durationMs: 0,
+                attempt: 0,
+                goal: ''
+            };
+        }
+        // Parse FINISH()
+        if (/FINISH\s*\(\s*\)/i.test(actionStr)) {
+            return {
+                success: true,
+                action: 'finish',
+                message: 'Task marked as complete',
+                durationMs: 0,
+                attempt: 0,
+                goal: ''
+            };
+        }
+        throw new Error(`Unknown action format: ${actionStr}\n` +
+            `Expected: CLICK(id), TYPE(id, "text"), PRESS("key"), or FINISH()`);
+    }
+    /**
+     * Track token usage for analytics
+     */
+    trackTokens(goal, llmResponse) {
+        if (llmResponse.promptTokens) {
+            this.tokenUsage.totalPromptTokens += llmResponse.promptTokens;
+        }
+        if (llmResponse.completionTokens) {
+            this.tokenUsage.totalCompletionTokens += llmResponse.completionTokens;
+        }
+        if (llmResponse.totalTokens) {
+            this.tokenUsage.totalTokens += llmResponse.totalTokens;
+        }
+        this.tokenUsage.byAction.push({
+            goal,
+            promptTokens: llmResponse.promptTokens,
+            completionTokens: llmResponse.completionTokens,
+            totalTokens: llmResponse.totalTokens,
+            model: llmResponse.modelName
+        });
+    }
+    /**
+     * Get token usage statistics
+     * @returns Dictionary with token usage breakdown
+     */
+    getTokenStats() {
+        return { ...this.tokenUsage };
+    }
+    /**
+     * Get execution history
+     * @returns List of all actions taken with results
+     */
+    getHistory() {
+        return [...this.history];
+    }
+    /**
+     * Clear execution history and reset token counters
+     */
+    clearHistory() {
+        this.history = [];
+        this.stepCount = 0;
+        this.tokenUsage = {
+            totalPromptTokens: 0,
+            totalCompletionTokens: 0,
+            totalTokens: 0,
+            byAction: []
+        };
+    }
+    /**
+     * Close the tracer and flush events to disk
+     */
+    async closeTracer() {
+        if (this.tracer) {
+            await this.tracer.close();
+        }
+    }
+    /**
+     * Get the tracer instance (if any)
+     */
+    getTracer() {
+        return this.tracer;
+    }
+}
+exports.SentienceAgent = SentienceAgent;
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/browser.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Playwright browser harness with extension loading
+ */
+import { BrowserContext, Page } from 'playwright';
+import { StorageState } from './types';
+export declare class SentienceBrowser {
+    private context;
+    private browser;
+    private page;
+    private extensionPath;
+    private userDataDir;
+    private _apiKey?;
+    private _apiUrl?;
+    private headless;
+    private _proxy?;
+    private _userDataDir?;
+    private _storageState?;
+    constructor(apiKey?: string, apiUrl?: string, headless?: boolean, proxy?: string, userDataDir?: string, storageState?: string | StorageState | object);
+    start(): Promise<void>;
+    goto(url: string): Promise<void>;
+    private waitForExtension;
+    getPage(): Page;
+    private _copyRecursive;
+    getApiKey(): string | undefined;
+    getApiUrl(): string | undefined;
+    /**
+     * Parse proxy connection string into Playwright format.
+     *
+     * @param proxyString - Standard format "http://username:password@host:port"
+     *                    or "socks5://user:pass@host:port"
+     * @returns Playwright proxy object or undefined if invalid
+     */
+    private parseProxy;
+    /**
+     * Inject storage state (cookies + localStorage) into browser context.
+     *
+     * @param storageState - Path to JSON file, StorageState object, or plain object
+     */
+    private injectStorageState;
+    /**
+     * Get the browser context (for utilities like saveStorageState)
+     */
+    getContext(): BrowserContext;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAY,cAAc,EAAE,IAAI,EAAW,MAAM,YAAY,CAAC;AAKrE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,YAAY,CAAC,CAAS;IAC9B,OAAO,CAAC,aAAa,CAAC,CAAiC;gBAGrD,MAAM,CAAC,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,OAAO,EAClB,KAAK,CAAC,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM,EACpB,YAAY,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,MAAM;IA4BzC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA6VtB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAqBxB,gBAAgB;IAkB9B,OAAO,IAAI,IAAI;IAQf,OAAO,CAAC,cAAc;IAYtB,SAAS,IAAI,MAAM,GAAG,SAAS;IAI/B,SAAS,IAAI,MAAM,GAAG,SAAS;IAI/B;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAsClB;;;;OAIG;YACW,kBAAkB;IA0FhC;;OAEG;IACH,UAAU,IAAI,cAAc;IAOtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAmD7B"}