@predicatelabs/sdk 0.99.9

package/dist/agent-runtime.js

@@ -0,0 +1,1170 @@
+"use strict";
+/**
+ * Agent runtime for verification loop support.
+ *
+ * This module provides a thin runtime wrapper that combines:
+ * 1. Browser session management
+ * 2. Snapshot/query helpers
+ * 3. Tracer for event emission
+ * 4. Assertion/verification methods
+ *
+ * The AgentRuntime is designed to be used in agent verification loops where
+ * you need to repeatedly take snapshots, execute actions, and verify results.
+ *
+ * @example
+ * ```typescript
+ * import { SentienceBrowser } from './browser';
+ * import { AgentRuntime } from './agent-runtime';
+ * import { urlMatches, exists } from './verification';
+ * import { Tracer, JsonlTraceSink } from './tracing';
+ *
+ * const browser = await SentienceBrowser.create();
+ * const page = await browser.newPage();
+ * await page.goto("https://example.com");
+ *
+ * const sink = new JsonlTraceSink("trace.jsonl");
+ * const tracer = new Tracer("test-run", sink);
+ *
+ * const runtime = new AgentRuntime(browser, page, tracer);
+ *
+ * // Take snapshot and run assertions
+ * await runtime.snapshot();
+ * runtime.assert(urlMatches(/example\.com/), "on_homepage");
+ * runtime.assert(exists("role=button"), "has_buttons");
+ *
+ * // Check if task is done
+ * if (runtime.assertDone(exists("text~'Success'"), "task_complete")) {
+ *   console.log("Task completed!");
+ * }
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentRuntime = exports.AssertionHandle = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const trace_event_builder_1 = require("./utils/trace-event-builder");
+const failure_artifacts_1 = require("./failure-artifacts");
+const browser_1 = require("./browser");
+const types_1 = require("./captcha/types");
+const DEFAULT_CAPTCHA_OPTIONS = {
+    policy: 'abort',
+    minConfidence: 0.7,
+    timeoutMs: 120000,
+    pollMs: 1000,
+    maxRetriesNewSession: 1,
+};
+class AssertionHandle {
+    constructor(runtime, predicate, label, required) {
+        this.runtime = runtime;
+        this.predicate = predicate;
+        this.label = label;
+        this.required = required;
+    }
+    once() {
+        return this.runtime.assert(this.predicate, this.label, this.required);
+    }
+    async eventually(options = {}) {
+        const timeoutMs = options.timeoutMs ?? 10000;
+        const pollMs = options.pollMs ?? 250;
+        const snapshotOptions = options.snapshotOptions;
+        const minConfidence = options.minConfidence;
+        const maxSnapshotAttempts = options.maxSnapshotAttempts ?? 3;
+        const visionProvider = options.visionProvider;
+        const visionSystemPrompt = options.visionSystemPrompt;
+        const visionUserPrompt = options.visionUserPrompt;
+        const deadline = Date.now() + timeoutMs;
+        let attempt = 0;
+        let snapshotAttempt = 0;
+        let lastOutcome = null;
+        while (true) {
+            attempt += 1;
+            await this.runtime.snapshot(snapshotOptions);
+            snapshotAttempt += 1;
+            const diagnostics = this.runtime.lastSnapshot?.diagnostics;
+            const confidence = diagnostics?.confidence;
+            if (typeof minConfidence === 'number' &&
+                typeof confidence === 'number' &&
+                Number.isFinite(confidence) &&
+                confidence < minConfidence) {
+                lastOutcome = {
+                    passed: false,
+                    reason: `Snapshot confidence ${confidence.toFixed(3)} < minConfidence ${minConfidence.toFixed(3)}`,
+                    details: {
+                        reason_code: 'snapshot_low_confidence',
+                        confidence,
+                        min_confidence: minConfidence,
+                        snapshot_attempt: snapshotAttempt,
+                        diagnostics,
+                    },
+                };
+                this.runtime._recordOutcome(lastOutcome, this.label, this.required, { eventually: true, attempt, snapshot_attempt: snapshotAttempt, final: false }, false);
+                if (snapshotAttempt >= maxSnapshotAttempts) {
+                    // Optional: vision fallback after snapshot exhaustion (last resort).
+                    // Keeps the assertion surface invariant; only perception changes.
+                    if (visionProvider && visionProvider.supportsVision?.()) {
+                        try {
+                            const buf = (await this.runtime.page.screenshot({ type: 'png' }));
+                            const imageBase64 = Buffer.from(buf).toString('base64');
+                            const sys = visionSystemPrompt ?? 'You are a strict visual verifier. Answer only YES or NO.';
+                            const user = visionUserPrompt ??
+                                `Given the screenshot, is the following condition satisfied?\n\n${this.label}\n\nAnswer YES or NO.`;
+                            const resp = await visionProvider.generateWithImage(sys, user, imageBase64, {
+                                temperature: 0.0,
+                            });
+                            const text = (resp.content || '').trim().toLowerCase();
+                            const passed = text.startsWith('yes');
+                            const finalOutcome = {
+                                passed,
+                                reason: passed ? 'vision_fallback_yes' : 'vision_fallback_no',
+                                details: {
+                                    reason_code: passed ? 'vision_fallback_pass' : 'vision_fallback_fail',
+                                    vision_response: resp.content,
+                                    min_confidence: minConfidence,
+                                    snapshot_attempts: snapshotAttempt,
+                                },
+                            };
+                            this.runtime._recordOutcome(finalOutcome, this.label, this.required, {
+                                eventually: true,
+                                attempt,
+                                snapshot_attempt: snapshotAttempt,
+                                final: true,
+                                vision_fallback: true,
+                            }, true);
+                            if (this.required && !passed) {
+                                this.runtime.persistFailureArtifacts(`assert_eventually_failed:${this.label}`);
+                            }
+                            return passed;
+                        }
+                        catch {
+                            // fall through to snapshot_exhausted
+                        }
+                    }
+                    const finalOutcome = {
+                        passed: false,
+                        reason: `Snapshot exhausted after ${snapshotAttempt} attempt(s) below minConfidence ${minConfidence.toFixed(3)}`,
+                        details: {
+                            reason_code: 'snapshot_exhausted',
+                            confidence,
+                            min_confidence: minConfidence,
+                            snapshot_attempts: snapshotAttempt,
+                            diagnostics,
+                        },
+                    };
+                    this.runtime._recordOutcome(finalOutcome, this.label, this.required, {
+                        eventually: true,
+                        attempt,
+                        snapshot_attempt: snapshotAttempt,
+                        final: true,
+                        exhausted: true,
+                    }, true);
+                    if (this.required) {
+                        this.runtime.persistFailureArtifacts(`assert_eventually_failed:${this.label}`);
+                    }
+                    return false;
+                }
+                if (Date.now() >= deadline) {
+                    this.runtime._recordOutcome(lastOutcome, this.label, this.required, {
+                        eventually: true,
+                        attempt,
+                        snapshot_attempt: snapshotAttempt,
+                        final: true,
+                        timeout: true,
+                    }, true);
+                    if (this.required) {
+                        this.runtime.persistFailureArtifacts(`assert_eventually_timeout:${this.label}`);
+                    }
+                    return false;
+                }
+                await new Promise(resolve => setTimeout(resolve, pollMs));
+                continue;
+            }
+            lastOutcome = this.predicate(this.runtime.ctx());
+            // Emit attempt event (not recorded in step_end)
+            this.runtime._recordOutcome(lastOutcome, this.label, this.required, { eventually: true, attempt, final: false }, false);
+            if (lastOutcome.passed) {
+                // Record final success once
+                this.runtime._recordOutcome(lastOutcome, this.label, this.required, { eventually: true, attempt, final: true }, true);
+                return true;
+            }
+            if (Date.now() >= deadline) {
+                // Record final failure once
+                this.runtime._recordOutcome(lastOutcome, this.label, this.required, { eventually: true, attempt, final: true, timeout: true }, true);
+                if (this.required) {
+                    this.runtime.persistFailureArtifacts(`assert_eventually_timeout:${this.label}`);
+                }
+                return false;
+            }
+            await new Promise(resolve => setTimeout(resolve, pollMs));
+        }
+    }
+}
+exports.AssertionHandle = AssertionHandle;
+/**
+ * Runtime wrapper for agent verification loops.
+ *
+ * Provides ergonomic methods for:
+ * - snapshot(): Take page snapshot
+ * - assert(): Evaluate assertion predicates
+ * - assertDone(): Assert task completion (required assertion)
+ *
+ * The runtime manages assertion state per step and emits verification events
+ * to the tracer for Studio timeline display.
+ */
+class AgentRuntime {
+    static similarity(a, b) {
+        const s1 = a.toLowerCase();
+        const s2 = b.toLowerCase();
+        if (!s1 || !s2)
+            return 0;
+        if (s1 === s2)
+            return 1;
+        // Bigram overlap (cheap, robust enough for suggestions)
+        const bigrams = (s) => {
+            const out = [];
+            for (let i = 0; i < s.length - 1; i++)
+                out.push(s.slice(i, i + 2));
+            return out;
+        };
+        const a2 = bigrams(s1);
+        const b2 = bigrams(s2);
+        const setB = new Set(b2);
+        let common = 0;
+        for (const g of a2)
+            if (setB.has(g))
+                common += 1;
+        return (2 * common) / (a2.length + b2.length + 1e-9);
+    }
+    static stringifyEvalValue(value) {
+        if (value === null || value === undefined) {
+            return 'null';
+        }
+        if (Array.isArray(value) || typeof value === 'object') {
+            try {
+                return JSON.stringify(value);
+            }
+            catch {
+                return String(value);
+            }
+        }
+        return String(value);
+    }
+    _recordOutcome(outcome, label, required, extra, recordInStep) {
+        const details = { ...(outcome.details || {}) };
+        // Failure intelligence: nearest matches for selector-driven assertions
+        if (!outcome.passed && this.lastSnapshot && typeof details.selector === 'string') {
+            const selector = details.selector;
+            const scored = [];
+            for (const el of this.lastSnapshot.elements) {
+                const hay = el.name ?? el.text ?? '';
+                if (!hay)
+                    continue;
+                const score = AgentRuntime.similarity(selector, hay);
+                scored.push({ score, el });
+            }
+            scored.sort((x, y) => y.score - x.score);
+            details.nearest_matches = scored.slice(0, 3).map(({ score, el }) => ({
+                id: el.id,
+                role: el.role,
+                text: (el.text ?? '').toString().slice(0, 80),
+                name: (el.name ?? '').toString().slice(0, 80),
+                score: Math.round(score * 10000) / 10000,
+            }));
+        }
+        const record = {
+            label,
+            passed: outcome.passed,
+            required,
+            reason: outcome.reason,
+            details,
+            ...(extra || {}),
+        };
+        if (recordInStep) {
+            this.assertionsThisStep.push(record);
+        }
+        this.tracer.emit('verification', {
+            kind: 'assert',
+            ...record,
+        }, this.stepId || undefined);
+    }
+    check(predicate, label, required = false) {
+        return new AssertionHandle(this, predicate, label, required);
+    }
+    /**
+     * Create AgentRuntime from a raw Playwright Page (sidecar mode).
+     */
+    static fromPlaywrightPage(page, tracer, options) {
+        const browser = options?.browser ??
+            (() => {
+                const sentienceBrowser = browser_1.SentienceBrowser.fromPage(page, options?.apiKey, options?.apiUrl);
+                return {
+                    snapshot: async (_page, snapshotOptions) => sentienceBrowser.snapshot(snapshotOptions),
+                };
+            })();
+        return new AgentRuntime(browser, page, tracer, options?.toolRegistry);
+    }
+    /**
+     * Sidecar alias for fromPlaywrightPage().
+     */
+    static attach(page, tracer, options) {
+        return AgentRuntime.fromPlaywrightPage(page, tracer, options);
+    }
+    /**
+     * Create a new AgentRuntime.
+     *
+     * @param browser - Browser instance for taking snapshots
+     * @param page - Playwright Page for browser interaction
+     * @param tracer - Tracer for emitting verification events
+     */
+    constructor(browser, page, tracer, toolRegistry) {
+        /** Current step identifier */
+        this.stepId = null;
+        /** Current step index (0-based) */
+        // 0-based step indexing (first auto-generated stepId is "step-0")
+        this.stepIndex = -1;
+        /** Most recent snapshot (for assertion context) */
+        this.lastSnapshot = null;
+        this.stepPreSnapshot = null;
+        this.stepPreUrl = null;
+        /** Best-effort download records (Playwright downloads) */
+        this.downloads = [];
+        /** Tab registry for tab operations */
+        this.tabRegistry = new Map();
+        this.tabIds = new WeakMap();
+        /** Failure artifact buffer (Phase 1) */
+        this.artifactBuffer = null;
+        this.artifactTimer = null;
+        /** Assertions accumulated during current step */
+        this.assertionsThisStep = [];
+        this.stepGoal = null;
+        this.lastAction = null;
+        /** Task completion tracking */
+        this.taskDone = false;
+        this.taskDoneLabel = null;
+        /** CAPTCHA handling (optional, disabled by default) */
+        this.captchaOptions = null;
+        this.captchaRetryCount = 0;
+        this.browser = browser;
+        this.page = page;
+        this.tracer = tracer;
+        this.toolRegistry = toolRegistry;
+        // Best-effort download tracking (does not change behavior unless a download occurs).
+        try {
+            this.page.on('download', download => {
+                void this.trackDownload(download);
+            });
+        }
+        catch {
+            // ignore
+        }
+    }
+    capabilities() {
+        const hasTabs = typeof this.listTabs === 'function';
+        const hasEval = typeof this.evaluateJs === 'function';
+        const hasKeyboard = Boolean(this.page?.keyboard);
+        const hasDownloads = this.downloads.length >= 0;
+        let hasPermissions = false;
+        try {
+            const context = typeof this.page?.context === 'function' ? this.page.context() : null;
+            hasPermissions =
+                Boolean(context) &&
+                    typeof context.clearPermissions === 'function' &&
+                    typeof context.grantPermissions === 'function';
+        }
+        catch {
+            hasPermissions = false;
+        }
+        let hasFiles = false;
+        if (this.toolRegistry) {
+            hasFiles = Boolean(this.toolRegistry.get('read_file'));
+        }
+        return {
+            tabs: hasTabs,
+            evaluate_js: hasEval,
+            downloads: hasDownloads,
+            filesystem_tools: hasFiles,
+            keyboard: hasKeyboard,
+            permissions: hasPermissions,
+        };
+    }
+    can(name) {
+        return Boolean(this.capabilities()[name]);
+    }
+    /**
+     * Configure CAPTCHA handling (disabled by default unless set).
+     */
+    setCaptchaOptions(options) {
+        this.captchaOptions = {
+            ...DEFAULT_CAPTCHA_OPTIONS,
+            ...options,
+        };
+        this.captchaRetryCount = 0;
+    }
+    /**
+     * Build assertion context from current state.
+     */
+    ctx() {
+        let url = null;
+        if (this.lastSnapshot) {
+            url = this.lastSnapshot.url;
+        }
+        else if (this.page) {
+            url = this.page.url();
+        }
+        return {
+            snapshot: this.lastSnapshot,
+            url,
+            stepId: this.stepId,
+            downloads: this.downloads,
+        };
+    }
+    async trackDownload(download) {
+        const rec = {
+            status: 'started',
+            suggested_filename: download?.suggestedFilename?.() ?? download?.suggested_filename,
+            url: download?.url?.() ?? download?.url,
+        };
+        this.downloads.push(rec);
+        try {
+            const p = (await download.path?.());
+            rec.status = 'completed';
+            if (p) {
+                rec.path = p;
+                try {
+                    // Best-effort size and mime type (no new deps).
+                    rec.size_bytes = Number(fs.statSync(p).size);
+                    const ext = String(path.extname(p) || '').toLowerCase();
+                    const mimeByExt = {
+                        '.pdf': 'application/pdf',
+                        '.txt': 'text/plain',
+                        '.csv': 'text/csv',
+                        '.json': 'application/json',
+                        '.zip': 'application/zip',
+                        '.png': 'image/png',
+                        '.jpg': 'image/jpeg',
+                        '.jpeg': 'image/jpeg',
+                        '.webp': 'image/webp',
+                    };
+                    if (mimeByExt[ext])
+                        rec.mime_type = mimeByExt[ext];
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+        catch (e) {
+            rec.status = 'failed';
+            rec.error = String(e?.message ?? e);
+        }
+    }
+    /**
+     * Take a snapshot of the current page state.
+     *
+     * This updates lastSnapshot which is used as context for assertions.
+     * When emitTrace=true (default), automatically emits a 'snapshot' trace event
+     * with screenshot_base64 for Sentience Studio visualization.
+     *
+     * @param options - Options passed through to browser.snapshot()
+     * @param options.emitTrace - If true (default), emit a 'snapshot' trace event with screenshot.
+     *                           Set to false to disable automatic trace emission.
+     * @returns Snapshot of current page state
+     *
+     * @example
+     * // Default: snapshot with auto-emit trace event
+     * const snapshot = await runtime.snapshot();
+     *
+     * // Disable auto-emit for manual control
+     * const snapshot = await runtime.snapshot({ emitTrace: false });
+     * // Later, manually emit if needed:
+     * tracer.emitSnapshot(snapshot, runtime.getStepId());
+     */
+    async snapshot(options) {
+        const { _skipCaptchaHandling, emitTrace = true, ...snapshotOptions } = options || {};
+        this.lastSnapshot = await this.browser.snapshot(this.page, snapshotOptions);
+        if (this.lastSnapshot && !this.stepPreSnapshot) {
+            this.stepPreSnapshot = this.lastSnapshot;
+            this.stepPreUrl = this.lastSnapshot.url;
+        }
+        if (!_skipCaptchaHandling) {
+            await this.handleCaptchaIfNeeded(this.lastSnapshot, 'gateway');
+        }
+        // Auto-emit snapshot trace event for Studio visualization
+        if (emitTrace && this.lastSnapshot && this.tracer) {
+            this.emitSnapshotTrace(this.lastSnapshot);
+        }
+        return this.lastSnapshot;
+    }
+    /**
+     * Emit a snapshot trace event with screenshot for Studio visualization.
+     *
+     * This is called automatically by snapshot() when emitTrace=true.
+     */
+    emitSnapshotTrace(snapshot) {
+        if (!this.tracer) {
+            return;
+        }
+        try {
+            this.tracer.emitSnapshot(snapshot, this.stepId ?? undefined, this.stepIndex, 'jpeg');
+        }
+        catch {
+            // Best-effort: don't let trace emission errors break snapshot
+        }
+    }
+    /**
+     * Evaluate JavaScript in the page context.
+     */
+    async evaluateJs(request) {
+        try {
+            const value = await this.page.evaluate(request.code);
+            const text = AgentRuntime.stringifyEvalValue(value);
+            const maxChars = request.max_output_chars ?? 4000;
+            const truncate = request.truncate ?? true;
+            let truncated = false;
+            let finalText = text;
+            if (truncate && finalText.length > maxChars) {
+                finalText = `${finalText.slice(0, maxChars)}...`;
+                truncated = true;
+            }
+            return {
+                ok: true,
+                value,
+                text: finalText,
+                truncated,
+            };
+        }
+        catch (err) {
+            return { ok: false, error: String(err?.message ?? err) };
+        }
+    }
+    /**
+     * List open tabs in the current browser context.
+     */
+    async listTabs() {
+        const context = this.page?.context?.();
+        if (!context || typeof context.pages !== 'function') {
+            return { ok: false, tabs: [], error: 'unsupported_capability' };
+        }
+        this.pruneTabs();
+        const pages = context.pages();
+        const tabs = [];
+        for (const page of pages) {
+            const tab_id = this.ensureTabId(page);
+            let title = null;
+            try {
+                title = await page.title();
+            }
+            catch {
+                title = null;
+            }
+            let url = null;
+            try {
+                url = page.url();
+            }
+            catch {
+                url = null;
+            }
+            tabs.push({ tab_id, url, title, is_active: page === this.page });
+        }
+        return { ok: true, tabs };
+    }
+    /**
+     * Open a new tab and navigate to the URL.
+     */
+    async openTab(url) {
+        const context = this.page?.context?.();
+        if (!context || typeof context.newPage !== 'function') {
+            return { ok: false, error: 'unsupported_capability' };
+        }
+        this.pruneTabs();
+        try {
+            const page = await context.newPage();
+            await page.goto(url);
+            this.page = page;
+            const tab_id = this.ensureTabId(page);
+            let title = null;
+            try {
+                title = await page.title();
+            }
+            catch {
+                title = null;
+            }
+            return { ok: true, tab: { tab_id, url: page.url?.() ?? url, title, is_active: true } };
+        }
+        catch (err) {
+            return { ok: false, error: String(err?.message ?? err) };
+        }
+    }
+    /**
+     * Switch to an existing tab by id.
+     */
+    async switchTab(tab_id) {
+        this.pruneTabs();
+        const page = this.tabRegistry.get(tab_id);
+        if (!page) {
+            return { ok: false, error: `unknown tab_id: ${tab_id}` };
+        }
+        this.page = page;
+        try {
+            await page.bringToFront();
+        }
+        catch {
+            // best-effort
+        }
+        let title = null;
+        try {
+            title = await page.title();
+        }
+        catch {
+            title = null;
+        }
+        return {
+            ok: true,
+            tab: { tab_id, url: page.url?.() ?? null, title, is_active: true },
+        };
+    }
+    /**
+     * Close a tab by id.
+     */
+    async closeTab(tab_id) {
+        this.pruneTabs();
+        const page = this.tabRegistry.get(tab_id);
+        if (!page) {
+            return { ok: false, error: `unknown tab_id: ${tab_id}` };
+        }
+        let title = null;
+        try {
+            title = await page.title();
+        }
+        catch {
+            title = null;
+        }
+        const wasActive = page === this.page;
+        try {
+            await page.close();
+        }
+        catch (err) {
+            return { ok: false, error: String(err?.message ?? err) };
+        }
+        this.tabRegistry.delete(tab_id);
+        if (wasActive) {
+            const context = page?.context?.();
+            const pages = context?.pages?.() ?? [];
+            if (pages.length > 0) {
+                this.page = pages[0];
+            }
+        }
+        return {
+            ok: true,
+            tab: { tab_id, url: page.url?.() ?? null, title, is_active: wasActive },
+        };
+    }
+    ensureTabId(page) {
+        const existing = this.tabIds.get(page);
+        if (existing) {
+            return existing;
+        }
+        const tab_id = `tab-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+        this.tabIds.set(page, tab_id);
+        this.tabRegistry.set(tab_id, page);
+        return tab_id;
+    }
+    pruneTabs() {
+        for (const [tab_id, page] of this.tabRegistry.entries()) {
+            try {
+                const isClosed = page.isClosed?.();
+                if (isClosed) {
+                    this.tabRegistry.delete(tab_id);
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    isCaptchaDetected(snapshot) {
+        const options = this.captchaOptions;
+        if (!options) {
+            return false;
+        }
+        const captcha = snapshot.diagnostics?.captcha;
+        if (!captcha || !captcha.detected) {
+            return false;
+        }
+        // Many pages load CAPTCHA libraries proactively. Only block when we have
+        // evidence it's actually present/active (iframe/url/text hits), otherwise
+        // interactive runs can "do nothing" and time out.
+        const evidence = captcha.evidence;
+        const iframeHits = evidence?.iframe_src_hits ?? [];
+        const urlHits = evidence?.url_hits ?? [];
+        const textHits = evidence?.text_hits ?? [];
+        const selectorHits = evidence?.selector_hits ?? [];
+        if (iframeHits.length === 0 && urlHits.length === 0 && textHits.length === 0) {
+            return false;
+        }
+        // Heuristic: many sites include passive reCAPTCHA badges (v3) that should not block.
+        // Only block when there is evidence of an interactive challenge.
+        const hitsAll = [...iframeHits, ...urlHits, ...textHits, ...selectorHits];
+        const hitsLower = hitsAll.map(hit => String(hit || '').toLowerCase()).filter(Boolean);
+        const joinedHits = hitsLower.join(' ');
+        const strongText = [
+            "i'm not a robot",
+            'verify you are human',
+            'human verification',
+            'complete the security check',
+            'please verify',
+        ].some(needle => joinedHits.includes(needle));
+        const strongIframe = hitsLower.some(hit => ['api2/bframe', 'hcaptcha', 'turnstile'].some(needle => hit.includes(needle)));
+        const strongSelector = hitsLower.some(hit => [
+            'g-recaptcha-response',
+            'h-captcha-response',
+            'cf-turnstile-response',
+            'recaptcha-checkbox',
+            'hcaptcha-checkbox',
+        ].some(needle => hit.includes(needle)));
+        const onlyGeneric = !strongText &&
+            !strongIframe &&
+            !strongSelector &&
+            hitsLower.length > 0 &&
+            hitsLower.every(hit => hit.includes('captcha') || hit.includes('recaptcha'));
+        if (onlyGeneric) {
+            return false;
+        }
+        const confidence = captcha.confidence ?? 0;
+        const minConfidence = options.minConfidence ?? DEFAULT_CAPTCHA_OPTIONS.minConfidence;
+        return confidence >= minConfidence;
+    }
+    buildCaptchaContext(snapshot, source) {
+        return {
+            runId: this.tracer.getRunId(),
+            stepIndex: this.stepIndex,
+            url: snapshot.url,
+            source,
+            captcha: snapshot.diagnostics?.captcha ?? null,
+            evaluateJs: async (code) => {
+                const result = await this.evaluateJs({ code });
+                if (!result.ok) {
+                    throw new Error(result.error ?? 'evaluateJs failed');
+                }
+                return result.value;
+            },
+        };
+    }
+    emitCaptchaEvent(reasonCode, details = {}) {
+        this.tracer.emit('verification', {
+            kind: 'captcha',
+            passed: false,
+            label: reasonCode,
+            details: { reason_code: reasonCode, ...details },
+        }, this.stepId || undefined);
+    }
+    async handleCaptchaIfNeeded(snapshot, source) {
+        if (!this.captchaOptions) {
+            return;
+        }
+        if (!this.isCaptchaDetected(snapshot)) {
+            return;
+        }
+        const options = this.captchaOptions;
+        const minConfidence = options.minConfidence ?? DEFAULT_CAPTCHA_OPTIONS.minConfidence;
+        const captcha = snapshot.diagnostics?.captcha ?? null;
+        this.emitCaptchaEvent('captcha_detected', { captcha, min_confidence: minConfidence });
+        let resolution;
+        if (options.policy === 'callback') {
+            if (!options.handler) {
+                this.emitCaptchaEvent('captcha_handler_error');
+                throw new types_1.CaptchaHandlingError('captcha_handler_error', 'Captcha handler is required for policy="callback".');
+            }
+            try {
+                resolution = await options.handler(this.buildCaptchaContext(snapshot, source));
+            }
+            catch (err) {
+                this.emitCaptchaEvent('captcha_handler_error', { error: String(err?.message || err) });
+                throw new types_1.CaptchaHandlingError('captcha_handler_error', 'Captcha handler failed.', {
+                    error: String(err?.message || err),
+                });
+            }
+            if (!resolution || !resolution.action) {
+                this.emitCaptchaEvent('captcha_handler_error');
+                throw new types_1.CaptchaHandlingError('captcha_handler_error', 'Captcha handler returned an invalid resolution.');
+            }
+        }
+        else {
+            resolution = { action: 'abort' };
+        }
+        await this.applyCaptchaResolution(resolution, snapshot, source);
+    }
+    async applyCaptchaResolution(resolution, snapshot, source) {
+        const options = this.captchaOptions || DEFAULT_CAPTCHA_OPTIONS;
+        if (resolution.action === 'abort') {
+            this.emitCaptchaEvent('captcha_policy_abort', { message: resolution.message });
+            throw new types_1.CaptchaHandlingError('captcha_policy_abort', resolution.message || 'Captcha detected. Aborting per policy.');
+        }
+        if (resolution.action === 'retry_new_session') {
+            this.captchaRetryCount += 1;
+            this.emitCaptchaEvent('captcha_retry_new_session');
+            if (this.captchaRetryCount > (options.maxRetriesNewSession ?? 1)) {
+                this.emitCaptchaEvent('captcha_retry_exhausted');
+                throw new types_1.CaptchaHandlingError('captcha_retry_exhausted', 'Captcha retry_new_session exhausted.');
+            }
+            const resetSession = this.captchaOptions?.resetSession;
+            if (!resetSession) {
+                throw new types_1.CaptchaHandlingError('captcha_retry_new_session', 'resetSession callback is required for retry_new_session.');
+            }
+            await resetSession();
+            return;
+        }
+        if (resolution.action === 'wait_until_cleared') {
+            const timeoutMs = resolution.timeoutMs ?? options.timeoutMs ?? DEFAULT_CAPTCHA_OPTIONS.timeoutMs;
+            const pollMs = resolution.pollMs ?? options.pollMs ?? DEFAULT_CAPTCHA_OPTIONS.pollMs;
+            await this.waitUntilCleared(timeoutMs, pollMs, snapshot, source);
+            this.emitCaptchaEvent('captcha_resumed');
+        }
+    }
+    async waitUntilCleared(timeoutMs, pollMs, snapshot, source) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() <= deadline) {
+            await new Promise(res => setTimeout(res, pollMs));
+            const next = await this.snapshot({ _skipCaptchaHandling: true });
+            if (!this.isCaptchaDetected(next)) {
+                this.emitCaptchaEvent('captcha_cleared', { source });
+                return;
+            }
+        }
+        this.emitCaptchaEvent('captcha_wait_timeout', { timeout_ms: timeoutMs });
+        throw new types_1.CaptchaHandlingError('captcha_wait_timeout', 'Captcha wait_until_cleared timed out.');
+    }
+    /**
+     * Enable failure artifact buffer (Phase 1).
+     */
+    enableFailureArtifacts(options = {}) {
+        this.artifactBuffer = new failure_artifacts_1.FailureArtifactBuffer(this.tracer.getRunId(), options);
+        const fps = this.artifactBuffer.getOptions().fps;
+        if (fps && fps > 0) {
+            const intervalMs = Math.max(1, Math.floor(1000 / fps));
+            this.artifactTimer = setInterval(() => {
+                this.captureArtifactFrame().catch(() => {
+                    // best-effort
+                });
+            }, intervalMs);
+        }
+    }
+    /**
+     * Disable failure artifact buffer and stop background capture.
+     */
+    disableFailureArtifacts() {
+        if (this.artifactTimer) {
+            clearInterval(this.artifactTimer);
+            this.artifactTimer = null;
+        }
+    }
+    /**
+     * Record an action in the artifact timeline and capture a frame if enabled.
+     */
+    async recordAction(action, url) {
+        this.lastAction = action;
+        if (!this.artifactBuffer) {
+            return;
+        }
+        this.artifactBuffer.recordStep(action, this.stepId, this.stepIndex, url);
+        if (this.artifactBuffer.getOptions().captureOnAction) {
+            await this.captureArtifactFrame();
+        }
+    }
+    /**
+     * Emit a step_end event using TraceEventBuilder.
+     */
+    emitStepEnd(opts) {
+        const goal = this.stepGoal || '';
+        const preSnap = this.stepPreSnapshot || this.lastSnapshot;
+        const preUrl = this.stepPreUrl || preSnap?.url || this.page?.url?.() || '';
+        const postUrl = opts.postUrl || this.page?.url?.() || this.lastSnapshot?.url || preUrl;
+        const preDigest = preSnap ? trace_event_builder_1.TraceEventBuilder.buildSnapshotDigest(preSnap) : undefined;
+        const postDigest = opts.postSnapshotDigest ||
+            (this.lastSnapshot ? trace_event_builder_1.TraceEventBuilder.buildSnapshotDigest(this.lastSnapshot) : undefined);
+        const urlChanged = Boolean(preUrl && postUrl && String(preUrl) !== String(postUrl));
+        const assertionsData = this.getAssertionsForStepEnd();
+        const signals = { ...(opts.verifySignals || {}) };
+        if (signals.url_changed === undefined) {
+            signals.url_changed = urlChanged;
+        }
+        if (opts.error && signals.error === undefined) {
+            signals.error = opts.error;
+        }
+        if (assertionsData.task_done !== undefined) {
+            signals.task_done = assertionsData.task_done;
+        }
+        if (assertionsData.task_done_label) {
+            signals.task_done_label = assertionsData.task_done_label;
+        }
+        const verifyPassed = opts.verifyPassed !== undefined ? opts.verifyPassed : this.requiredAssertionsPassed();
+        const execData = {
+            success: opts.success !== undefined ? opts.success : verifyPassed,
+            action: opts.action || this.lastAction || 'unknown',
+            outcome: opts.outcome || '',
+            duration_ms: opts.durationMs,
+            error: opts.error,
+        };
+        const verifyData = {
+            passed: Boolean(verifyPassed),
+            signals,
+        };
+        const stepEndData = trace_event_builder_1.TraceEventBuilder.buildRuntimeStepEndData({
+            stepId: this.stepId || '',
+            stepIndex: this.stepIndex,
+            goal,
+            attempt: opts.attempt ?? 0,
+            preUrl,
+            postUrl,
+            preSnapshotDigest: preDigest,
+            postSnapshotDigest: postDigest,
+            execData,
+            verifyData,
+            assertions: assertionsData.assertions,
+            taskDone: assertionsData.task_done,
+            taskDoneLabel: assertionsData.task_done_label,
+        });
+        this.tracer.emit('step_end', stepEndData, this.stepId || undefined);
+        return stepEndData;
+    }
+    /**
+     * User-friendly alias for emitStepEnd().
+     *
+     * Keeps step lifecycle naming symmetric with beginStep().
+     */
+    endStep(opts = {}) {
+        return this.emitStepEnd(opts);
+    }
+    async captureArtifactFrame() {
+        if (!this.artifactBuffer) {
+            return;
+        }
+        try {
+            const image = await this.page.screenshot({ type: 'jpeg', quality: 80 });
+            await this.artifactBuffer.addFrame(image, 'jpeg');
+        }
+        catch {
+            // best-effort
+        }
+    }
+    /**
+     * Finalize artifact buffer at end of run.
+     */
+    async finalizeRun(success) {
+        if (!this.artifactBuffer) {
+            return;
+        }
+        if (success) {
+            if (this.artifactBuffer.getOptions().persistMode === 'always') {
+                await this.artifactBuffer.persist('success', 'success', this.lastSnapshot ?? undefined, this.lastSnapshot?.diagnostics, this.artifactMetadata());
+            }
+            await this.artifactBuffer.cleanup();
+        }
+        else {
+            await this.persistFailureArtifacts('finalize_failure');
+        }
+    }
+    async persistFailureArtifacts(reason) {
+        if (!this.artifactBuffer) {
+            return;
+        }
+        await this.artifactBuffer.persist(reason, 'failure', this.lastSnapshot ?? undefined, this.lastSnapshot?.diagnostics, this.artifactMetadata());
+        await this.artifactBuffer.cleanup();
+        if (this.artifactBuffer.getOptions().persistMode === 'onFail') {
+            this.disableFailureArtifacts();
+        }
+    }
+    artifactMetadata() {
+        const url = this.lastSnapshot?.url ?? this.page?.url?.();
+        return {
+            backend: 'playwright',
+            url,
+        };
+    }
+    /**
+     * Begin a new step in the verification loop.
+     *
+     * This:
+     * - Generates a new stepId
+     * - Clears assertions from previous step
+     * - Increments stepIndex (or uses provided value)
+     * - Emits step_start trace event (optional)
+     *
+     * @param goal - Description of what this step aims to achieve
+     * @param stepIndex - Optional explicit step index (otherwise auto-increments)
+     * @param options - Optional settings: emitTrace (default true), preUrl
+     * @returns Generated stepId in format 'step-N' where N is the step index
+     */
+    beginStep(goal, stepIndex, options) {
+        const { emitTrace = true, preUrl } = options || {};
+        // Clear previous step state
+        this.assertionsThisStep = [];
+        this.stepPreSnapshot = null;
+        this.stepPreUrl = null;
+        this.stepGoal = goal;
+        this.lastAction = null;
+        // Update step index
+        if (stepIndex !== undefined) {
+            this.stepIndex = stepIndex;
+        }
+        else {
+            this.stepIndex += 1;
+        }
+        // Generate stepId in 'step-N' format for Studio compatibility
+        this.stepId = `step-${this.stepIndex}`;
+        // Emit step_start trace event for Studio timeline display
+        if (emitTrace && this.tracer) {
+            try {
+                const url = preUrl || this.lastSnapshot?.url || this.page?.url?.() || '';
+                this.tracer.emitStepStart(this.stepId, this.stepIndex, goal, 0, url);
+            }
+            catch {
+                // Tracing must be non-fatal
+            }
+        }
+        return this.stepId;
+    }
+    /**
+     * Evaluate an assertion against current snapshot state.
+     *
+     * The assertion result is:
+     * 1. Accumulated for inclusion in step_end.data.verify.signals.assertions
+     * 2. Emitted as a dedicated 'verification' event for Studio timeline
+     *
+     * @param predicate - Predicate function to evaluate
+     * @param label - Human-readable label for this assertion
+     * @param required - If true, this assertion gates step success (default: false)
+     * @returns True if assertion passed, false otherwise
+     */
+    assert(predicate, label, required = false) {
+        const outcome = predicate(this.ctx());
+        this._recordOutcome(outcome, label, required, null, true);
+        if (required && !outcome.passed) {
+            this.persistFailureArtifacts(`assert_failed:${label}`).catch(() => {
+                // best-effort
+            });
+        }
+        return outcome.passed;
+    }
+    /**
+     * Assert task completion (required assertion).
+     *
+     * This is a convenience wrapper for assert() with required=true.
+     * When the assertion passes, it marks the task as done.
+     *
+     * Use this for final verification that the agent's goal is complete.
+     *
+     * @param predicate - Predicate function to evaluate
+     * @param label - Human-readable label for this assertion
+     * @returns True if task is complete (assertion passed), false otherwise
+     */
+    assertDone(predicate, label) {
+        const ok = this.assert(predicate, label, true);
+        if (ok) {
+            this.taskDone = true;
+            this.taskDoneLabel = label;
+            // Emit task_done verification event
+            this.tracer.emit('verification', {
+                kind: 'task_done',
+                passed: true,
+                label,
+            }, this.stepId || undefined);
+        }
+        return ok;
+    }
+    /**
+     * Get assertions data for inclusion in step_end.data.verify.signals.
+     *
+     * This is called when building the step_end event to include
+     * assertion results in the trace.
+     *
+     * @returns Object with 'assertions', 'task_done', 'task_done_label' keys
+     */
+    getAssertionsForStepEnd() {
+        const result = {
+            assertions: [...this.assertionsThisStep],
+        };
+        if (this.taskDone) {
+            result.task_done = true;
+            result.task_done_label = this.taskDoneLabel || undefined;
+        }
+        return result;
+    }
+    /**
+     * Get and clear assertions for current step.
+     *
+     * Call this at step end to get accumulated assertions
+     * for the step_end event, then clear for next step.
+     *
+     * @returns List of assertion records from this step
+     */
+    flushAssertions() {
+        const assertions = [...this.assertionsThisStep];
+        this.assertionsThisStep = [];
+        return assertions;
+    }
+    /**
+     * Check if task has been marked as done via assertDone().
+     */
+    get isTaskDone() {
+        return this.taskDone;
+    }
+    /**
+     * Reset task_done state (for multi-task runs).
+     */
+    resetTaskDone() {
+        this.taskDone = false;
+        this.taskDoneLabel = null;
+    }
+    /**
+     * Check if all assertions in current step passed.
+     *
+     * @returns True if all assertions passed (or no assertions made)
+     */
+    allAssertionsPassed() {
+        return this.assertionsThisStep.every(a => a.passed);
+    }
+    /**
+     * Check if all required assertions in current step passed.
+     *
+     * @returns True if all required assertions passed (or no required assertions)
+     */
+    requiredAssertionsPassed() {
+        const required = this.assertionsThisStep.filter(a => a.required);
+        return required.every(a => a.passed);
+    }
+}
+exports.AgentRuntime = AgentRuntime;
+//# sourceMappingURL=agent-runtime.js.map