@predicatelabs/sdk 0.99.9

package/dist/conversational-agent.js

@@ -0,0 +1,341 @@
+"use strict";
+/**
+ * ConversationalAgent - Level 4 Abstraction
+ * Natural language interface for browser automation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConversationalAgent = void 0;
+const agent_1 = require("./agent");
+const snapshot_1 = require("./snapshot");
+/**
+ * ConversationalAgent provides the highest level of abstraction (Level 4).
+ * It accepts natural language instructions, automatically plans the execution,
+ * performs the actions, and synthesizes natural language responses.
+ *
+ * Example:
+ *   const agent = new ConversationalAgent({ llmProvider, browser });
+ *   const response = await agent.execute("Search Google for TypeScript tutorials");
+ *   console.log(response);
+ */
+class ConversationalAgent {
+    constructor(options) {
+        this.conversationHistory = [];
+        this.llmProvider = options.llmProvider;
+        this.browser = options.browser;
+        this.verbose = options.verbose ?? false;
+        this.maxTokens = options.maxTokens ?? 4000;
+        this.planningModel = options.planningModel;
+        this.executionModel = options.executionModel;
+        this.sentienceAgent = new agent_1.SentienceAgent(this.browser, this.llmProvider, 50, this.verbose);
+    }
+    /**
+     * Execute a natural language instruction.
+     * Plans the steps, executes them, and returns a natural language response.
+     */
+    async execute(userInput) {
+        const startTime = Date.now();
+        if (this.verbose) {
+            console.log(`\n[ConversationalAgent] User: ${userInput}`);
+        }
+        // Add user message to history
+        this.conversationHistory.push({
+            role: 'user',
+            content: userInput,
+            timestamp: new Date(),
+        });
+        try {
+            // Step 1: Create execution plan
+            const plan = await this.createPlan(userInput);
+            if (this.verbose) {
+                console.log(`[ConversationalAgent] Plan created with ${plan.steps.length} steps`);
+            }
+            // Step 2: Execute each step
+            const results = [];
+            for (let i = 0; i < plan.steps.length; i++) {
+                const step = plan.steps[i];
+                if (this.verbose) {
+                    console.log(`[ConversationalAgent] Step ${i + 1}/${plan.steps.length}: ${step.action}`);
+                }
+                const result = await this.executeStep(step);
+                results.push(result);
+                if (!result.success && this.verbose) {
+                    console.log(`[ConversationalAgent] Step ${i + 1} failed: ${result.error}`);
+                }
+            }
+            // Step 3: Synthesize response
+            const response = await this.synthesizeResponse(userInput, plan, results);
+            // Add to history
+            this.conversationHistory.push({
+                role: 'assistant',
+                content: response,
+                timestamp: new Date(),
+                plan,
+                results,
+            });
+            const duration = Date.now() - startTime;
+            if (this.verbose) {
+                console.log(`[ConversationalAgent] Completed in ${duration}ms`);
+            }
+            return response;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const response = `I encountered an error while trying to help: ${errorMessage}`;
+            this.conversationHistory.push({
+                role: 'assistant',
+                content: response,
+                timestamp: new Date(),
+            });
+            return response;
+        }
+    }
+    /**
+     * Create an execution plan from natural language input.
+     * Uses LLM to break down the request into atomic steps.
+     */
+    async createPlan(userInput) {
+        const systemPrompt = `You are a browser automation planner. Given a user's natural language request,
+create a detailed execution plan with atomic steps.
+
+Available actions:
+- NAVIGATE: Navigate to a URL
+  Parameters: { url: string }
+- FIND_AND_CLICK: Find and click an element
+  Parameters: { description: string }
+- FIND_AND_TYPE: Find an input field and type text
+  Parameters: { description: string, text: string }
+- PRESS_KEY: Press a keyboard key
+  Parameters: { key: string }
+- WAIT: Wait for a specified time
+  Parameters: { seconds: number }
+- EXTRACT_INFO: Extract specific information from the page
+  Parameters: { info_type: string }
+- VERIFY: Verify a condition is met
+  Parameters: { condition: string }
+
+Return a JSON object with this structure:
+{
+  "goal": "brief description of the overall goal",
+  "steps": [
+    {
+      "action": "ACTION_TYPE",
+      "parameters": { ... },
+      "reasoning": "why this step is needed"
+    }
+  ]
+}`;
+        const userPrompt = `Create an execution plan for this request: ${userInput}`;
+        const llmResponse = await this.llmProvider.generate(systemPrompt, userPrompt, {
+            json_mode: this.llmProvider.supportsJsonMode(),
+        });
+        const plan = JSON.parse(llmResponse.content);
+        if (!plan.steps || !Array.isArray(plan.steps)) {
+            throw new Error('Invalid plan format: missing steps array');
+        }
+        return plan;
+    }
+    /**
+     * Execute a single step from the plan.
+     */
+    async executeStep(step) {
+        const startTime = Date.now();
+        try {
+            let result;
+            let snap;
+            switch (step.action) {
+                case 'NAVIGATE':
+                    if (!step.parameters.url) {
+                        throw new Error('NAVIGATE requires url parameter');
+                    }
+                    const navPage = this.browser.getPage();
+                    if (!navPage) {
+                        throw new Error('Browser not started. Call start() first.');
+                    }
+                    await navPage.goto(step.parameters.url);
+                    await navPage.waitForLoadState('domcontentloaded');
+                    snap = await (0, snapshot_1.snapshot)(this.browser);
+                    result = { navigated_to: step.parameters.url };
+                    break;
+                case 'FIND_AND_CLICK':
+                    if (!step.parameters.description) {
+                        throw new Error('FIND_AND_CLICK requires description parameter');
+                    }
+                    const clickResult = await this.sentienceAgent.act(`Click on: ${step.parameters.description}`);
+                    result = { clicked: clickResult.success, outcome: clickResult.outcome };
+                    break;
+                case 'FIND_AND_TYPE':
+                    if (!step.parameters.description || !step.parameters.text) {
+                        throw new Error('FIND_AND_TYPE requires description and text parameters');
+                    }
+                    const typeResult = await this.sentienceAgent.act(`Type "${step.parameters.text}" into: ${step.parameters.description}`);
+                    result = { typed: typeResult.success, outcome: typeResult.outcome };
+                    break;
+                case 'PRESS_KEY':
+                    if (!step.parameters.key) {
+                        throw new Error('PRESS_KEY requires key parameter');
+                    }
+                    const pressPage = this.browser.getPage();
+                    if (!pressPage) {
+                        throw new Error('Browser not started. Call start() first.');
+                    }
+                    await pressPage.keyboard.press(step.parameters.key);
+                    snap = await (0, snapshot_1.snapshot)(this.browser);
+                    result = { key_pressed: step.parameters.key };
+                    break;
+                case 'WAIT':
+                    const seconds = step.parameters.seconds ?? 2;
+                    const waitPage = this.browser.getPage();
+                    if (!waitPage) {
+                        throw new Error('Browser not started. Call start() first.');
+                    }
+                    await waitPage.waitForTimeout(seconds * 1000);
+                    snap = await (0, snapshot_1.snapshot)(this.browser);
+                    result = { waited_seconds: seconds };
+                    break;
+                case 'EXTRACT_INFO':
+                    if (!step.parameters.info_type) {
+                        throw new Error('EXTRACT_INFO requires info_type parameter');
+                    }
+                    snap = await (0, snapshot_1.snapshot)(this.browser);
+                    const extractedInfo = await this.extractInformation(snap, step.parameters.info_type);
+                    result = { info: extractedInfo };
+                    break;
+                case 'VERIFY':
+                    if (!step.parameters.condition) {
+                        throw new Error('VERIFY requires condition parameter');
+                    }
+                    snap = await (0, snapshot_1.snapshot)(this.browser);
+                    const verified = await this.verifyCondition(snap, step.parameters.condition);
+                    result = { verified, condition: step.parameters.condition };
+                    break;
+                default:
+                    throw new Error(`Unknown action type: ${step.action}`);
+            }
+            const duration = Date.now() - startTime;
+            return {
+                success: true,
+                action: step.action,
+                result,
+                snapshot: snap,
+                duration_ms: duration,
+            };
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            return {
+                success: false,
+                action: step.action,
+                error: error instanceof Error ? error.message : String(error),
+                duration_ms: duration,
+            };
+        }
+    }
+    /**
+     * Extract specific information from a page snapshot.
+     */
+    async extractInformation(snap, infoType) {
+        const snapText = this.snapshotToText(snap);
+        const prompt = `From this webpage snapshot, extract: ${infoType}\n\nSnapshot:\n${snapText.slice(0, 3000)}`;
+        const llmResponse = await this.llmProvider.generate('You are a web page information extractor. Extract only the requested information concisely.', prompt);
+        return llmResponse.content.trim();
+    }
+    /**
+     * Verify a condition is met on the current page.
+     */
+    async verifyCondition(snap, condition) {
+        const snapText = this.snapshotToText(snap);
+        const prompt = `Does this webpage satisfy the following condition: "${condition}"?\n\nRespond with only "yes" or "no".\n\nSnapshot:\n${snapText.slice(0, 3000)}`;
+        const llmResponse = await this.llmProvider.generate('You are a web page condition verifier. Respond with only "yes" or "no".', prompt);
+        return llmResponse.content.toLowerCase().includes('yes');
+    }
+    /**
+     * Convert a Snapshot object to text representation for LLM.
+     */
+    snapshotToText(snap) {
+        let text = `URL: ${snap.url}\n\nElements:\n`;
+        for (const elem of snap.elements.slice(0, 50)) {
+            text += `[${elem.id}] ${elem.role || 'element'} ${elem.text || ''}\n`;
+        }
+        return text;
+    }
+    /**
+     * Synthesize a natural language response from execution results.
+     */
+    async synthesizeResponse(userInput, plan, results) {
+        const successCount = results.filter(r => r.success).length;
+        // Build context from results
+        let context = `User request: ${userInput}\n\n`;
+        context += `Execution summary: ${successCount}/${results.length} steps succeeded\n\n`;
+        for (let i = 0; i < results.length; i++) {
+            const step = plan.steps[i];
+            const result = results[i];
+            context += `Step ${i + 1}: ${step.action}\n`;
+            context += `  Reasoning: ${step.reasoning}\n`;
+            context += `  Success: ${result.success}\n`;
+            if (result.success && result.result) {
+                context += `  Result: ${JSON.stringify(result.result, null, 2)}\n`;
+            }
+            else if (!result.success && result.error) {
+                context += `  Error: ${result.error}\n`;
+            }
+            context += '\n';
+        }
+        const systemPrompt = `You are a helpful assistant that summarizes browser automation results.
+Given the user's request and execution results, provide a natural, conversational response.
+- Be concise but informative
+- Mention what was accomplished
+- If there were failures, explain them clearly
+- If information was extracted, present it clearly`;
+        const llmResponse = await this.llmProvider.generate(systemPrompt, context);
+        return llmResponse.content.trim();
+    }
+    /**
+     * Chat interface that maintains conversation context.
+     * Unlike execute(), this method keeps track of the full conversation
+     * and uses it for context in subsequent interactions.
+     */
+    async chat(message) {
+        return await this.execute(message);
+    }
+    /**
+     * Get a summary of the entire conversation session.
+     */
+    async getSummary() {
+        if (this.conversationHistory.length === 0) {
+            return 'No conversation history yet.';
+        }
+        const context = this.conversationHistory
+            .map((entry, i) => {
+            let text = `${i + 1}. [${entry.role}]: ${entry.content}`;
+            if (entry.plan) {
+                text += ` (${entry.plan.steps.length} steps)`;
+            }
+            return text;
+        })
+            .join('\n');
+        const systemPrompt = `You are summarizing a browser automation conversation session.
+Provide a brief summary of what was accomplished.`;
+        const llmResponse = await this.llmProvider.generate(systemPrompt, `Summarize this conversation:\n\n${context}`);
+        return llmResponse.content.trim();
+    }
+    /**
+     * Clear conversation history.
+     */
+    clearHistory() {
+        this.conversationHistory = [];
+    }
+    /**
+     * Get the conversation history.
+     */
+    getHistory() {
+        return [...this.conversationHistory];
+    }
+    /**
+     * Get token usage statistics from the underlying agent.
+     */
+    getTokenStats() {
+        return this.sentienceAgent.getTokenStats();
+    }
+}
+exports.ConversationalAgent = ConversationalAgent;
+//# sourceMappingURL=conversational-agent.js.map

package/dist/conversational-agent.js.map

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

package/dist/cursor-policy.d.ts

@@ -0,0 +1,41 @@
+export type CursorMode = 'instant' | 'human';
+/**
+ * Policy for cursor movement.
+ *
+ * - mode="instant": current behavior (single click without multi-step motion)
+ * - mode="human": move with a curved path + optional jitter/overshoot
+ */
+export interface CursorPolicy {
+    mode: CursorMode;
+    steps?: number;
+    durationMs?: number;
+    jitterPx?: number;
+    overshootPx?: number;
+    pauseBeforeClickMs?: number;
+    /** Determinism hook for tests/repro */
+    seed?: number;
+}
+export interface CursorPathPoint {
+    x: number;
+    y: number;
+    t?: number;
+}
+export interface CursorMovementMetadata {
+    mode: CursorMode;
+    from: {
+        x: number;
+        y: number;
+    };
+    to: {
+        x: number;
+        y: number;
+    };
+    steps: number;
+    duration_ms: number;
+    pause_before_click_ms: number;
+    jitter_px: number;
+    overshoot_px: number;
+    path: CursorPathPoint[];
+}
+export declare function buildHumanCursorPath(start: [number, number], target: [number, number], policy: CursorPolicy): CursorMovementMetadata;
+//# sourceMappingURL=cursor-policy.d.ts.map

package/dist/cursor-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-policy.d.ts","sourceRoot":"","sources":["../src/cursor-policy.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/B,EAAE,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,eAAe,EAAE,CAAC;CACzB;AA2CD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EACvB,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EACxB,MAAM,EAAE,YAAY,GACnB,sBAAsB,CAyDxB"}

package/dist/cursor-policy.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildHumanCursorPath = buildHumanCursorPath;
+function clamp(v, lo, hi) {
+    return Math.max(lo, Math.min(hi, v));
+}
+function easeInOut(t) {
+    return t * t * (3 - 2 * t);
+}
+function bezier(p0, p1, p2, p3, t) {
+    const u = 1 - t;
+    const tt = t * t;
+    const uu = u * u;
+    const uuu = uu * u;
+    const ttt = tt * t;
+    const x = uuu * p0[0] + 3 * uu * t * p1[0] + 3 * u * tt * p2[0] + ttt * p3[0];
+    const y = uuu * p0[1] + 3 * uu * t * p1[1] + 3 * u * tt * p2[1] + ttt * p3[1];
+    return [x, y];
+}
+// Simple seeded RNG for reproducibility (mulberry32)
+function mulberry32(seed) {
+    let t = seed >>> 0;
+    return () => {
+        t += 0x6d2b79f5;
+        let x = t;
+        x = Math.imul(x ^ (x >>> 15), x | 1);
+        x ^= x + Math.imul(x ^ (x >>> 7), x | 61);
+        return ((x ^ (x >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function randBetween(rng, lo, hi) {
+    return lo + (hi - lo) * rng();
+}
+function buildHumanCursorPath(start, target, policy) {
+    const seed = policy.seed ?? Date.now() & 0xffffffff;
+    const rng = mulberry32(seed);
+    const [x0, y0] = start;
+    const [x1, y1] = target;
+    const dx = x1 - x0;
+    const dy = y1 - y0;
+    const dist0 = Math.hypot(dx, dy);
+    const dist = dist0 < 1e-6 ? 1 : dist0;
+    const steps = Math.floor(policy.steps ?? clamp(10 + dist / 25, 12, 40));
+    const durationMs = Math.floor(policy.durationMs ?? clamp(120 + dist * 0.9, 120, 700));
+    const ux = dx / dist;
+    const uy = dy / dist;
+    const px = -uy;
+    const py = ux;
+    let curveMag = clamp(dist / 3.5, 10, 140);
+    curveMag *= randBetween(rng, 0.5, 1.2);
+    const c1 = [x0 + dx * 0.25 + px * curveMag, y0 + dy * 0.25 + py * curveMag];
+    const c2 = [x0 + dx * 0.75 - px * curveMag, y0 + dy * 0.75 - py * curveMag];
+    const overshoot = policy.overshootPx ?? 6.0;
+    const overshootPoint = overshoot > 0 ? [x1 + ux * overshoot, y1 + uy * overshoot] : [x1, y1];
+    const jitterPx = policy.jitterPx ?? 1.0;
+    const pts = [];
+    for (let i = 0; i < steps; i++) {
+        const tRaw = steps <= 1 ? 0 : i / (steps - 1);
+        const t = easeInOut(tRaw);
+        const [bx, by] = bezier([x0, y0], c1, c2, overshootPoint, t);
+        const jitterScale = jitterPx * (1 - tRaw) * 0.9;
+        const jx = randBetween(rng, -jitterScale, jitterScale);
+        const jy = randBetween(rng, -jitterScale, jitterScale);
+        pts.push({ x: bx + jx, y: by + jy, t: Math.round(tRaw * 10000) / 10000 });
+    }
+    if (overshoot > 0) {
+        pts.push({ x: x1, y: y1, t: 1.0 });
+    }
+    return {
+        mode: 'human',
+        from: { x: x0, y: y0 },
+        to: { x: x1, y: y1 },
+        steps,
+        duration_ms: durationMs,
+        pause_before_click_ms: policy.pauseBeforeClickMs ?? 20,
+        jitter_px: jitterPx,
+        overshoot_px: overshoot,
+        path: pts.slice(0, 64),
+    };
+}
+//# sourceMappingURL=cursor-policy.js.map

package/dist/cursor-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-policy.js","sourceRoot":"","sources":["../src/cursor-policy.ts"],"names":[],"mappings":";;AA8EA,oDA6DC;AAtGD,SAAS,KAAK,CAAC,CAAS,EAAE,EAAU,EAAE,EAAU;IAC9C,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;AACvC,CAAC;AAED,SAAS,SAAS,CAAC,CAAS;IAC1B,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,MAAM,CACb,EAAoB,EACpB,EAAoB,EACpB,EAAoB,EACpB,EAAoB,EACpB,CAAS;IAET,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChB,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;IACjB,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;IACjB,MAAM,GAAG,GAAG,EAAE,GAAG,CAAC,CAAC;IACnB,MAAM,GAAG,GAAG,EAAE,GAAG,CAAC,CAAC;IACnB,MAAM,CAAC,GAAG,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IAC9E,MAAM,CAAC,GAAG,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IAC9E,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAChB,CAAC;AAED,qDAAqD;AACrD,SAAS,UAAU,CAAC,IAAY;IAC9B,IAAI,CAAC,GAAG,IAAI,KAAK,CAAC,CAAC;IACnB,OAAO,GAAG,EAAE;QACV,CAAC,IAAI,UAAU,CAAC;QAChB,IAAI,CAAC,GAAG,CAAC,CAAC;QACV,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACrC,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;QAC1C,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,UAAU,CAAC;IAC/C,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,GAAiB,EAAE,EAAU,EAAE,EAAU;IAC5D,OAAO,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC;AAChC,CAAC;AAED,SAAgB,oBAAoB,CAClC,KAAuB,EACvB,MAAwB,EACxB,MAAoB;IAEpB,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,CAAC;IACpD,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAE7B,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC;IACvB,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,MAAM,CAAC;IACxB,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;IACnB,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;IACnB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IACjC,MAAM,IAAI,GAAG,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAEtC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,IAAI,KAAK,CAAC,EAAE,GAAG,IAAI,GAAG,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IACxE,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,IAAI,KAAK,CAAC,GAAG,GAAG,IAAI,GAAG,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAEtF,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;IACf,MAAM,EAAE,GAAG,EAAE,CAAC;IAEd,IAAI,QAAQ,GAAG,KAAK,CAAC,IAAI,GAAG,GAAG,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;IAC1C,QAAQ,IAAI,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAEvC,MAAM,EAAE,GAAqB,CAAC,EAAE,GAAG,EAAE,GAAG,IAAI,GAAG,EAAE,GAAG,QAAQ,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,GAAG,EAAE,GAAG,QAAQ,CAAC,CAAC;IAC9F,MAAM,EAAE,GAAqB,CAAC,EAAE,GAAG,EAAE,GAAG,IAAI,GAAG,EAAE,GAAG,QAAQ,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,GAAG,EAAE,GAAG,QAAQ,CAAC,CAAC;IAE9F,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,IAAI,GAAG,CAAC;IAC5C,MAAM,cAAc,GAClB,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,SAAS,EAAE,EAAE,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAExE,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,GAAG,CAAC;IACxC,MAAM,GAAG,GAAsB,EAAE,CAAC;IAElC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QAC9C,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAC1B,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC;QAC7D,MAAM,WAAW,GAAG,QAAQ,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC;QAChD,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;QACvD,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;QACvD,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,KAAM,CAAC,GAAG,KAAM,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;QAClB,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,OAAO;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE;QACtB,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE;QACpB,KAAK;QACL,WAAW,EAAE,UAAU;QACvB,qBAAqB,EAAE,MAAM,CAAC,kBAAkB,IAAI,EAAE;QACtD,SAAS,EAAE,QAAQ;QACnB,YAAY,EAAE,SAAS;QACvB,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;KACvB,CAAC;AACJ,CAAC"}

package/dist/debugger.d.ts

@@ -0,0 +1,28 @@
+import { Page } from 'playwright';
+import { AgentRuntime, AssertionHandle, AttachOptions } from './agent-runtime';
+import { Predicate } from './verification';
+import { Tracer } from './tracing/tracer';
+export declare class SentienceDebugger {
+    readonly runtime: AgentRuntime;
+    private stepOpen;
+    private autoStep;
+    private autoOpenedStep;
+    private autoOpenedStepId;
+    constructor(runtime: AgentRuntime, options?: {
+        autoStep?: boolean;
+    });
+    static attach(page: Page, tracer: Tracer, options?: AttachOptions): SentienceDebugger;
+    isAutoStepOpenFor(stepId: string | null): boolean;
+    beginStep(goal: string, stepIndex?: number): string;
+    endStep(opts?: Parameters<AgentRuntime['emitStepEnd']>[0]): Promise<any>;
+    step(goal: string, fn: () => Promise<void> | void, stepIndex?: number): Promise<void>;
+    snapshot(options?: Record<string, any>): Promise<import("./types").Snapshot>;
+    recordAction(action: string, url?: string): Promise<void>;
+    check(predicate: Predicate, label: string, required?: boolean): AssertionHandle;
+}
+/**
+ * Predicate rebrand alias for SentienceDebugger.
+ * Kept as a runtime alias to avoid breaking existing integrations.
+ */
+export declare const PredicateDebugger: typeof SentienceDebugger;
+//# sourceMappingURL=debugger.d.ts.map

package/dist/debugger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debugger.d.ts","sourceRoot":"","sources":["../src/debugger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAElC,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAwC1C,qBAAa,iBAAiB;IAC5B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,cAAc,CAAkB;IACxC,OAAO,CAAC,gBAAgB,CAAuB;gBAEnC,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE;IAKnE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,iBAAiB;IAKrF,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;IAUjD,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM;IAW7C,OAAO,CAAC,IAAI,GAAE,UAAU,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAQ5E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASrF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAItC,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/D,KAAK,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,OAAe;CAyBrE;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,0BAAoB,CAAC"}

package/dist/debugger.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PredicateDebugger = exports.SentienceDebugger = void 0;
+const agent_runtime_1 = require("./agent-runtime");
+class DebuggerAssertionHandle extends agent_runtime_1.AssertionHandle {
+    constructor(dbg, predicate, label, required, autoClose, openedStepId) {
+        super(dbg.runtime, predicate, label, required);
+        this.dbg = dbg;
+        this.autoClose = autoClose;
+        this.openedStepId = openedStepId;
+    }
+    once() {
+        const ok = super.once();
+        if (this.autoClose && this.dbg.isAutoStepOpenFor(this.openedStepId)) {
+            void this.dbg.endStep();
+        }
+        return ok;
+    }
+    async eventually(options = {}) {
+        const ok = await super.eventually(options);
+        if (this.autoClose && this.dbg.isAutoStepOpenFor(this.openedStepId)) {
+            await this.dbg.endStep();
+        }
+        return ok;
+    }
+}
+class SentienceDebugger {
+    constructor(runtime, options) {
+        this.stepOpen = false;
+        this.autoStep = true;
+        this.autoOpenedStep = false;
+        this.autoOpenedStepId = null;
+        this.runtime = runtime;
+        this.autoStep = options?.autoStep !== undefined ? Boolean(options.autoStep) : true;
+    }
+    static attach(page, tracer, options) {
+        const runtime = agent_runtime_1.AgentRuntime.fromPlaywrightPage(page, tracer, options);
+        return new SentienceDebugger(runtime);
+    }
+    isAutoStepOpenFor(stepId) {
+        return Boolean(this.stepOpen &&
+            this.autoOpenedStep &&
+            this.autoOpenedStepId &&
+            stepId &&
+            this.autoOpenedStepId === stepId);
+    }
+    beginStep(goal, stepIndex) {
+        // If we previously auto-opened a verification step, close it before starting a real step.
+        if (this.stepOpen && this.autoOpenedStep) {
+            void this.endStep();
+            this.autoOpenedStep = false;
+            this.autoOpenedStepId = null;
+        }
+        this.stepOpen = true;
+        return this.runtime.beginStep(goal, stepIndex);
+    }
+    async endStep(opts = {}) {
+        this.stepOpen = false;
+        this.autoOpenedStep = false;
+        this.autoOpenedStepId = null;
+        // emitStepEnd is synchronous; wrap to satisfy async/await lint rules.
+        return await Promise.resolve(this.runtime.emitStepEnd(opts));
+    }
+    async step(goal, fn, stepIndex) {
+        this.beginStep(goal, stepIndex);
+        try {
+            await fn();
+        }
+        finally {
+            await this.endStep();
+        }
+    }
+    async snapshot(options) {
+        return this.runtime.snapshot(options);
+    }
+    async recordAction(action, url) {
+        return await this.runtime.recordAction(action, url);
+    }
+    check(predicate, label, required = false) {
+        let didAutoOpen = false;
+        let openedStepId = null;
+        if (!this.stepOpen) {
+            if (!this.autoStep) {
+                throw new Error(`No active step. Call dbg.beginStep(...) or dbg.step(...) before check(label=${JSON.stringify(label)}).`);
+            }
+            this.beginStep(`verify:${label}`);
+            didAutoOpen = true;
+            openedStepId = this.runtime.stepId;
+            this.autoOpenedStep = true;
+            this.autoOpenedStepId = openedStepId;
+        }
+        const base = this.runtime.check(predicate, label, required);
+        if (!didAutoOpen) {
+            return base;
+        }
+        // Return an auto-closing handle for the common "casual" sidecar usage pattern.
+        // We still call runtime.check(...) above to keep behavior consistent.
+        return new DebuggerAssertionHandle(this, predicate, label, required, true, openedStepId);
+    }
+}
+exports.SentienceDebugger = SentienceDebugger;
+/**
+ * Predicate rebrand alias for SentienceDebugger.
+ * Kept as a runtime alias to avoid breaking existing integrations.
+ */
+exports.PredicateDebugger = SentienceDebugger;
+//# sourceMappingURL=debugger.js.map

package/dist/debugger.js.map

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

package/dist/expect.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Expect/Assert functionality
+ */
+import { SentienceBrowser } from './browser';
+import { Element, QuerySelector } from './types';
+export declare class Expectation {
+    private browser;
+    private selector;
+    constructor(browser: SentienceBrowser, selector: QuerySelector);
+    toBeVisible(timeout?: number): Promise<Element>;
+    toExist(timeout?: number): Promise<Element>;
+    toHaveText(expectedText: string, timeout?: number): Promise<Element>;
+    toHaveCount(expectedCount: number, timeout?: number): Promise<void>;
+}
+export declare function expect(browser: SentienceBrowser, selector: QuerySelector): Expectation;
+//# sourceMappingURL=expect.d.ts.map