autokap 1.0.6 → 1.0.8

package/dist/v2/benchmark.js

@@ -0,0 +1,135 @@
+/**
+ * Capture Agent — Benchmark Harness
+ *
+ * Runs the same preset through V2, comparing:
+ * - Total LLM cost
+ * - Total wall-clock time
+ * - Success rate
+ * - Recovery rate (how often healing was needed)
+ *
+ * Used to prove V2 >= V1 before cutover.
+ */
+import { logger } from '../logger.js';
+export async function runBenchmark(presets, runCapture, options) {
+    const runsPerPreset = options?.runs ?? 1;
+    const results = [];
+    for (const preset of presets) {
+        logger.info(`[Benchmark] Running "${preset.name}" (${preset.tier}) — ${runsPerPreset} run(s)`);
+        for (let run = 0; run < runsPerPreset; run++) {
+            try {
+                const runResult = await runCapture(preset.program);
+                results.push({
+                    presetName: preset.name,
+                    tier: preset.tier,
+                    success: runResult.success,
+                    totalDurationMs: runResult.totalDurationMs,
+                    llmCostEur: runResult.telemetry.llmCostEur,
+                    llmCallCount: runResult.telemetry.llmCallCount,
+                    totalOpcodes: runResult.telemetry.totalOpcodes,
+                    recoveredOpcodes: runResult.telemetry.recoveredOpcodes,
+                    failedOpcodes: runResult.telemetry.failedOpcodes,
+                    healerInvocations: runResult.telemetry.healerInvocations,
+                    circuitBreakerTrips: runResult.telemetry.circuitBreakerTrips,
+                    variantCount: runResult.variantResults.length,
+                    successfulVariants: runResult.variantResults.filter(v => v.success).length,
+                    error: runResult.error,
+                });
+            }
+            catch (err) {
+                results.push({
+                    presetName: preset.name,
+                    tier: preset.tier,
+                    success: false,
+                    totalDurationMs: 0,
+                    llmCostEur: 0,
+                    llmCallCount: 0,
+                    totalOpcodes: 0,
+                    recoveredOpcodes: 0,
+                    failedOpcodes: 0,
+                    healerInvocations: 0,
+                    circuitBreakerTrips: 0,
+                    variantCount: 0,
+                    successfulVariants: 0,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
+    return computeSummary(results);
+}
+// ── Summary computation ─────────────────────────────────────────────
+function computeSummary(results) {
+    const total = results.length;
+    const successCount = results.filter(r => r.success).length;
+    const failCount = total - successCount;
+    const totalDuration = results.reduce((sum, r) => sum + r.totalDurationMs, 0);
+    const totalLlmCost = results.reduce((sum, r) => sum + r.llmCostEur, 0);
+    const totalOpcodes = results.reduce((sum, r) => sum + r.totalOpcodes, 0);
+    const totalRecovered = results.reduce((sum, r) => sum + r.recoveredOpcodes, 0);
+    const deterministicRuns = results.filter(r => r.llmCallCount === 0 && r.success).length;
+    // By tier
+    const byTier = {};
+    for (const result of results) {
+        if (!byTier[result.tier])
+            byTier[result.tier] = { total: 0, success: 0, rate: 0 };
+        byTier[result.tier].total++;
+        if (result.success)
+            byTier[result.tier].success++;
+    }
+    for (const tier of Object.values(byTier)) {
+        tier.rate = tier.total > 0 ? tier.success / tier.total : 0;
+    }
+    return {
+        totalPresets: total,
+        successCount,
+        failCount,
+        successRate: total > 0 ? successCount / total : 0,
+        averageDurationMs: total > 0 ? totalDuration / total : 0,
+        averageLlmCostEur: total > 0 ? totalLlmCost / total : 0,
+        totalLlmCostEur: totalLlmCost,
+        deterministicRate: total > 0 ? deterministicRuns / total : 0,
+        recoveryRate: totalOpcodes > 0 ? totalRecovered / totalOpcodes : 0,
+        results,
+        byTier,
+    };
+}
+// ── Pretty printer ──────────────────────────────────────────────────
+export function formatBenchmarkSummary(summary) {
+    const lines = [];
+    lines.push('═══════════════════════════════════════════════════');
+    lines.push('  V2 Benchmark Summary');
+    lines.push('═══════════════════════════════════════════════════');
+    lines.push(`  Total presets:       ${summary.totalPresets}`);
+    lines.push(`  Success:             ${summary.successCount}/${summary.totalPresets} (${(summary.successRate * 100).toFixed(1)}%)`);
+    lines.push(`  Deterministic rate:  ${(summary.deterministicRate * 100).toFixed(1)}% (no LLM needed)`);
+    lines.push(`  Recovery rate:       ${(summary.recoveryRate * 100).toFixed(1)}% of opcodes`);
+    lines.push(`  Avg duration:        ${(summary.averageDurationMs / 1000).toFixed(1)}s`);
+    lines.push(`  Avg LLM cost:        ${summary.averageLlmCostEur.toFixed(4)} EUR`);
+    lines.push(`  Total LLM cost:      ${summary.totalLlmCostEur.toFixed(4)} EUR`);
+    lines.push('───────────────────────────────────────────────────');
+    for (const [tier, stats] of Object.entries(summary.byTier)) {
+        lines.push(`  ${tier.padEnd(18)} ${stats.success}/${stats.total} (${(stats.rate * 100).toFixed(0)}%)`);
+    }
+    lines.push('───────────────────────────────────────────────────');
+    for (const result of summary.results) {
+        const status = result.success ? 'OK' : 'FAIL';
+        const duration = `${(result.totalDurationMs / 1000).toFixed(1)}s`;
+        const cost = result.llmCostEur > 0 ? `${result.llmCostEur.toFixed(4)}EUR` : 'free';
+        lines.push(`  [${status}] ${result.presetName.padEnd(30)} ${duration.padStart(6)} ${cost.padStart(10)}${result.error ? ` — ${result.error.slice(0, 50)}` : ''}`);
+    }
+    lines.push('═══════════════════════════════════════════════════');
+    // Cutover check
+    const simpleStats = summary.byTier['simple'];
+    const multiStats = summary.byTier['multi_step'];
+    const simpleOk = !simpleStats || simpleStats.rate >= 0.95;
+    const multiOk = !multiStats || multiStats.rate >= 0.80;
+    const costOk = summary.averageLlmCostEur < 0.05;
+    lines.push('');
+    lines.push('  Cutover Checklist:');
+    lines.push(`  ${simpleOk ? '[x]' : '[ ]'} Simple scenarios > 95% (${simpleStats ? (simpleStats.rate * 100).toFixed(0) : 'N/A'}%)`);
+    lines.push(`  ${multiOk ? '[x]' : '[ ]'} Multi-step > 80% (${multiStats ? (multiStats.rate * 100).toFixed(0) : 'N/A'}%)`);
+    lines.push(`  ${costOk ? '[x]' : '[ ]'} Avg cost < 0.05 EUR (${summary.averageLlmCostEur.toFixed(4)} EUR)`);
+    lines.push('');
+    return lines.join('\n');
+}
+//# sourceMappingURL=benchmark.js.map

package/dist/v2/capture-strategy.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Capture Agent — Capture Strategy
+ *
+ * Abstraction over the two V2 media modes: screenshot and clip.
+ * The opcode runner is identical for all three — only the capture
+ * opcodes dispatch to different strategies.
+ */
+import type { ArtifactSpec, ArtifactResult, RuntimeAdapter, MediaMode } from './types.js';
+export interface CaptureStrategy {
+    readonly mediaMode: MediaMode;
+    /** Prepare the adapter for capture (e.g. lock viewport, inject cursor overlay) */
+    prepare(adapter: RuntimeAdapter, spec: ArtifactSpec): Promise<void>;
+    /** Perform the capture and return the raw artifact */
+    capture(adapter: RuntimeAdapter, spec: ArtifactSpec): Promise<ArtifactResult>;
+    /** Post-process the artifact (mockup frame, status bar, format conversion) */
+    postProcess(artifact: ArtifactResult, spec: ArtifactSpec): Promise<ArtifactResult>;
+}
+export declare class ScreenshotStrategy implements CaptureStrategy {
+    readonly mediaMode: "screenshot";
+    prepare(_adapter: RuntimeAdapter, _spec: ArtifactSpec): Promise<void>;
+    capture(adapter: RuntimeAdapter, _spec: ArtifactSpec): Promise<ArtifactResult>;
+    postProcess(artifact: ArtifactResult, spec: ArtifactSpec): Promise<ArtifactResult>;
+}
+export declare class ClipStrategy implements CaptureStrategy {
+    readonly mediaMode: "clip";
+    prepare(adapter: RuntimeAdapter, _spec: ArtifactSpec): Promise<void>;
+    capture(adapter: RuntimeAdapter, _spec: ArtifactSpec): Promise<ArtifactResult>;
+    postProcess(artifact: ArtifactResult, spec: ArtifactSpec): Promise<ArtifactResult>;
+}
+export declare function createCaptureStrategy(mediaMode: MediaMode): CaptureStrategy;

package/dist/v2/capture-strategy.js

@@ -0,0 +1,67 @@
+/**
+ * Capture Agent — Capture Strategy
+ *
+ * Abstraction over the two V2 media modes: screenshot and clip.
+ * The opcode runner is identical for all three — only the capture
+ * opcodes dispatch to different strategies.
+ */
+// ── Screenshot strategy ─────────────────────────────────────────────
+export class ScreenshotStrategy {
+    mediaMode = 'screenshot';
+    async prepare(_adapter, _spec) {
+        // Viewport locking is handled externally by the CLI runner
+        // when creating the browser context per variant.
+    }
+    async capture(adapter, _spec) {
+        const buffer = await adapter.takeScreenshot();
+        return {
+            mediaMode: 'screenshot',
+            buffer,
+            mimeType: 'image/png',
+        };
+    }
+    async postProcess(artifact, spec) {
+        // Post-processing (mockup frame, status bar) will be applied
+        // by the CLI runner using existing utilities:
+        // - applyDeviceFrame() from src/mockup.ts
+        // - generateStatusBarHtml() from src/status-bar.ts
+        // For now, return as-is. Phase 4 CLI runner handles the orchestration.
+        return artifact;
+    }
+}
+// ── Clip strategy ───────────────────────────────────────────────────
+export class ClipStrategy {
+    mediaMode = 'clip';
+    async prepare(adapter, _spec) {
+        // Clip recording preparation:
+        // - The browser context is created with video recording enabled
+        // - Cursor overlay is injected by Browser.forVideoRecording()
+    }
+    async capture(adapter, _spec) {
+        // Clip capture is bounded by BEGIN_CLIP / END_CLIP opcodes.
+        // The opcode runner calls adapter.beginRecording() and adapter.endRecording().
+        // This method is called for the final artifact assembly.
+        const recording = await adapter.endRecording();
+        return {
+            mediaMode: 'clip',
+            buffer: recording.buffer,
+            mimeType: recording.mimeType,
+        };
+    }
+    async postProcess(artifact, spec) {
+        // Post-processing for clips:
+        // - Convert WebM to GIF/MP4 via src/clip-postprocess.ts (if it exists)
+        // - Trim start/end
+        // - Apply cursor theme
+        // Handled by CLI runner using existing video processing utilities.
+        return artifact;
+    }
+}
+// ── Factory ─────────────────────────────────────────────────────────
+export function createCaptureStrategy(mediaMode) {
+    switch (mediaMode) {
+        case 'screenshot': return new ScreenshotStrategy();
+        case 'clip': return new ClipStrategy();
+    }
+}
+//# sourceMappingURL=capture-strategy.js.map

package/dist/v2/capture-verification.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Capture Agent — Capture Verification
+ *
+ * Post-capture quality check via LLM vision.
+ * Detects: blank pages, error pages, loading spinners, skeletons,
+ * obstructing overlays, and other visual issues.
+ *
+ * This is the ONLY place where AutoKap uses AI at runtime.
+ * Cost: ~0.002 EUR per check (1 image + short prompt).
+ */
+import { type LLMProviderConfig, type LLMCallResult } from './llm-provider.js';
+export interface VerificationResult {
+    /** Whether the screenshot is acceptable for delivery */
+    passed: boolean;
+    /** Issue detected (if failed) */
+    issue?: 'blank_page' | 'error_page' | 'loading' | 'overlay_blocking' | 'wrong_content' | 'other';
+    /** Human-readable explanation */
+    reason: string;
+    /** LLM call metadata */
+    llmResult?: LLMCallResult;
+}
+export interface VerificationContext {
+    /** What was this screenshot supposed to show? */
+    expectedDescription: string;
+    /** Target URL */
+    url: string;
+    /** Locale of this variant */
+    locale?: string;
+    /** Theme of this variant */
+    theme?: string;
+}
+/**
+ * Verifies a captured screenshot is clean and ready for delivery.
+ */
+export declare function verifyCaptureQuality(screenshot: Buffer, context: VerificationContext, llmConfig: LLMProviderConfig): Promise<VerificationResult>;

package/dist/v2/capture-verification.js

@@ -0,0 +1,95 @@
+/**
+ * Capture Agent — Capture Verification
+ *
+ * Post-capture quality check via LLM vision.
+ * Detects: blank pages, error pages, loading spinners, skeletons,
+ * obstructing overlays, and other visual issues.
+ *
+ * This is the ONLY place where AutoKap uses AI at runtime.
+ * Cost: ~0.002 EUR per check (1 image + short prompt).
+ */
+import { callLLM } from './llm-provider.js';
+const SYSTEM_PROMPT = `You are a screenshot quality checker for a web capture tool. You receive a screenshot of a web page and must verify it is clean and ready for delivery.
+
+Check for these issues:
+1. BLANK - The page is completely white/blank or has no meaningful content
+2. ERROR - The page shows an error message (404, 500, "something went wrong", crash screen)
+3. LOADING - The page has visible loading indicators (spinners, skeletons, progress bars, "Loading..." text)
+4. OVERLAY - A modal, popup, cookie banner, or other overlay is blocking the main content
+5. WRONG - The content doesn't match what was expected
+
+Respond with EXACTLY one line in this format:
+PASS: Screenshot looks clean and ready.
+or
+FAIL:<issue>: <explanation>
+
+Where <issue> is one of: blank_page, error_page, loading, overlay_blocking, wrong_content, other
+
+Examples:
+PASS: Screenshot looks clean and ready.
+FAIL:loading: A skeleton loader is visible in the main content area.
+FAIL:overlay_blocking: A cookie consent banner covers the bottom of the page.
+FAIL:error_page: The page shows a 404 Not Found error.`;
+/**
+ * Verifies a captured screenshot is clean and ready for delivery.
+ */
+export async function verifyCaptureQuality(screenshot, context, llmConfig) {
+    const userPrompt = buildUserPrompt(context);
+    try {
+        const result = await callLLM(llmConfig, SYSTEM_PROMPT, userPrompt, screenshot);
+        return parseVerificationResponse(result.text, result);
+    }
+    catch (err) {
+        // If LLM fails, pass the screenshot — don't block delivery because of LLM issues
+        return {
+            passed: true,
+            reason: `verification skipped (LLM error: ${err instanceof Error ? err.message : String(err)})`,
+        };
+    }
+}
+function buildUserPrompt(context) {
+    const parts = [
+        `Expected content: ${context.expectedDescription}`,
+        `URL: ${context.url}`,
+    ];
+    if (context.locale)
+        parts.push(`Locale: ${context.locale}`);
+    if (context.theme)
+        parts.push(`Theme: ${context.theme}`);
+    parts.push('\nIs this screenshot clean and ready for delivery?');
+    return parts.join('\n');
+}
+function parseVerificationResponse(text, llmResult) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith('PASS')) {
+        return {
+            passed: true,
+            reason: trimmed.replace(/^PASS:?\s*/, ''),
+            llmResult,
+        };
+    }
+    if (trimmed.startsWith('FAIL')) {
+        const match = trimmed.match(/^FAIL:(\w+):\s*(.+)/);
+        if (match) {
+            return {
+                passed: false,
+                issue: match[1],
+                reason: match[2],
+                llmResult,
+            };
+        }
+        return {
+            passed: false,
+            issue: 'other',
+            reason: trimmed.replace(/^FAIL:?\s*/, ''),
+            llmResult,
+        };
+    }
+    // Ambiguous response — assume pass
+    return {
+        passed: true,
+        reason: `ambiguous LLM response: "${trimmed.slice(0, 100)}"`,
+        llmResult,
+    };
+}
+//# sourceMappingURL=capture-verification.js.map

package/dist/v2/circuit-breaker.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Capture Agent — Circuit Breaker
+ *
+ * Three-level circuit breaker to prevent infinite recovery loops:
+ * - Per-opcode: max failures before the opcode is abandoned
+ * - Per-page: max failures across all opcodes on the same page
+ * - Per-run: max total failures across the entire program
+ */
+import type { CircuitBreakerConfig } from './types.js';
+export type BreakerTrip = 'opcode' | 'page' | 'run';
+export interface BreakerState {
+    tripped: boolean;
+    level?: BreakerTrip;
+    reason: string;
+    opcodeFailures: number;
+    pageFailures: number;
+    runFailures: number;
+}
+export declare class CircuitBreaker {
+    private config;
+    private opcodeFailures;
+    private pageFailures;
+    private runFailures;
+    private currentPageKey;
+    constructor(config?: CircuitBreakerConfig);
+    /** Set the current page context (URL-based key) */
+    setPage(url: string): void;
+    /** Record a failure for an opcode. Returns breaker state. */
+    recordFailure(opcodeIndex: number, maxPerOpcode?: number): BreakerState;
+    /** Record a success for an opcode (resets opcode-level counter) */
+    recordSuccess(opcodeIndex: number): void;
+    /** Check if the breaker is currently tripped at any level */
+    isTripped(): BreakerState;
+    /** Get summary of all failure counts */
+    getSummary(): {
+        opcodeFailures: Record<number, number>;
+        pageFailures: Record<string, number>;
+        runFailures: number;
+    };
+    /** Reset all counters */
+    reset(): void;
+}

package/dist/v2/circuit-breaker.js

@@ -0,0 +1,119 @@
+/**
+ * Capture Agent — Circuit Breaker
+ *
+ * Three-level circuit breaker to prevent infinite recovery loops:
+ * - Per-opcode: max failures before the opcode is abandoned
+ * - Per-page: max failures across all opcodes on the same page
+ * - Per-run: max total failures across the entire program
+ */
+import { DEFAULT_CIRCUIT_BREAKER } from './types.js';
+export class CircuitBreaker {
+    config;
+    opcodeFailures = new Map();
+    pageFailures = new Map();
+    runFailures = 0;
+    currentPageKey = null;
+    constructor(config = DEFAULT_CIRCUIT_BREAKER) {
+        this.config = config;
+    }
+    /** Set the current page context (URL-based key) */
+    setPage(url) {
+        this.currentPageKey = new URL(url).pathname;
+    }
+    /** Record a failure for an opcode. Returns breaker state. */
+    recordFailure(opcodeIndex, maxPerOpcode = this.config.maxPerOpcode) {
+        // Opcode level
+        const opcodeFails = (this.opcodeFailures.get(opcodeIndex) ?? 0) + 1;
+        this.opcodeFailures.set(opcodeIndex, opcodeFails);
+        // Page level
+        const pageKey = this.currentPageKey ?? 'unknown';
+        const pageFails = (this.pageFailures.get(pageKey) ?? 0) + 1;
+        this.pageFailures.set(pageKey, pageFails);
+        // Run level
+        this.runFailures++;
+        // Check breakers from most specific to least
+        if (opcodeFails >= maxPerOpcode) {
+            return {
+                tripped: true,
+                level: 'opcode',
+                reason: `opcode ${opcodeIndex} reached ${opcodeFails}/${maxPerOpcode} failures`,
+                opcodeFailures: opcodeFails,
+                pageFailures: pageFails,
+                runFailures: this.runFailures,
+            };
+        }
+        if (pageFails >= this.config.maxPerPage) {
+            return {
+                tripped: true,
+                level: 'page',
+                reason: `page "${pageKey}" reached ${pageFails}/${this.config.maxPerPage} failures`,
+                opcodeFailures: opcodeFails,
+                pageFailures: pageFails,
+                runFailures: this.runFailures,
+            };
+        }
+        if (this.runFailures >= this.config.maxPerRun) {
+            return {
+                tripped: true,
+                level: 'run',
+                reason: `run reached ${this.runFailures}/${this.config.maxPerRun} total failures`,
+                opcodeFailures: opcodeFails,
+                pageFailures: pageFails,
+                runFailures: this.runFailures,
+            };
+        }
+        return {
+            tripped: false,
+            reason: `opcode ${opcodeIndex}: ${opcodeFails}/${maxPerOpcode}, page: ${pageFails}/${this.config.maxPerPage}, run: ${this.runFailures}/${this.config.maxPerRun}`,
+            opcodeFailures: opcodeFails,
+            pageFailures: pageFails,
+            runFailures: this.runFailures,
+        };
+    }
+    /** Record a success for an opcode (resets opcode-level counter) */
+    recordSuccess(opcodeIndex) {
+        this.opcodeFailures.delete(opcodeIndex);
+    }
+    /** Check if the breaker is currently tripped at any level */
+    isTripped() {
+        if (this.runFailures >= this.config.maxPerRun) {
+            return {
+                tripped: true,
+                level: 'run',
+                reason: `run limit reached: ${this.runFailures}/${this.config.maxPerRun}`,
+                opcodeFailures: 0,
+                pageFailures: 0,
+                runFailures: this.runFailures,
+            };
+        }
+        const pageKey = this.currentPageKey ?? 'unknown';
+        const pageFails = this.pageFailures.get(pageKey) ?? 0;
+        if (pageFails >= this.config.maxPerPage) {
+            return {
+                tripped: true,
+                level: 'page',
+                reason: `page limit reached: ${pageFails}/${this.config.maxPerPage}`,
+                opcodeFailures: 0,
+                pageFailures: pageFails,
+                runFailures: this.runFailures,
+            };
+        }
+        return { tripped: false, reason: 'ok', opcodeFailures: 0, pageFailures: pageFails, runFailures: this.runFailures };
+    }
+    /** Get summary of all failure counts */
+    getSummary() {
+        return {
+            opcodeFailures: Object.fromEntries(this.opcodeFailures),
+            pageFailures: Object.fromEntries(this.pageFailures),
+            runFailures: this.runFailures,
+        };
+    }
+    /** Reset all counters */
+    reset() {
+        this.opcodeFailures.clear();
+        this.pageFailures.clear();
+        this.runFailures = 0;
+        this.currentPageKey = null;
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/v2/cli-runner-local.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Capture Agent — CLI command wrapper
+ *
+ * `autokap run` stays local-first: Playwright runs on the user's machine.
+ * The server only provides the compiled program and persists artifacts/results.
+ */
+export declare function runLocal(presetId: string, opts: {
+    headed: boolean;
+    output?: string;
+    program?: string;
+}): Promise<void>;

package/dist/v2/cli-runner-local.js

@@ -0,0 +1,91 @@
+/**
+ * Capture Agent — CLI command wrapper
+ *
+ * `autokap run` stays local-first: Playwright runs on the user's machine.
+ * The server only provides the compiled program and persists artifacts/results.
+ */
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { logger } from '../logger.js';
+import { parseProgram } from './schema.js';
+import { runCapture } from './cli-runner.js';
+export async function runLocal(presetId, opts) {
+    let program;
+    if (opts.program) {
+        try {
+            const raw = await fs.readFile(opts.program, 'utf-8');
+            program = parseProgram(JSON.parse(raw));
+            logger.info(`[capture] Loaded program from file: ${opts.program}`);
+        }
+        catch (err) {
+            logger.error(`[capture] Failed to load program: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    }
+    const run = await runCapture({
+        presetId,
+        program,
+        headed: opts.headed,
+        onProgress: (event) => {
+            const prefix = `[capture][${event.variantId}]`;
+            switch (event.type) {
+                case 'variant_start':
+                    logger.info(`${prefix} Starting variant`);
+                    break;
+                case 'variant_end':
+                    logger.info(`${prefix} ${event.status === 'ok' ? 'DONE' : 'FAILED'}: ${event.message}`);
+                    break;
+                case 'opcode_start':
+                    logger.info(`${prefix}[${event.opcodeIndex}] >> ${event.opcodeKind}: ${event.message}`);
+                    break;
+                case 'opcode_end':
+                    if (event.status === 'ok') {
+                        logger.info(`${prefix}[${event.opcodeIndex}] << OK (${event.opcodeKind})`);
+                    }
+                    else if (event.status === 'recovered') {
+                        logger.warn(`${prefix}[${event.opcodeIndex}] << RECOVERED: ${event.message}`);
+                    }
+                    else {
+                        logger.error(`${prefix}[${event.opcodeIndex}] << FAILED: ${event.message}`);
+                    }
+                    break;
+                case 'recovery':
+                    logger.warn(`${prefix}[${event.opcodeIndex}] RECOVERY: ${event.message}`);
+                    break;
+                case 'breaker_trip':
+                    logger.error(`${prefix} CIRCUIT BREAKER: ${event.message}`);
+                    break;
+            }
+        },
+    });
+    if (run.runResult && opts.output) {
+        await persistArtifactsLocally(presetId, opts.output, run.runResult.variantResults);
+    }
+    if (!run.success) {
+        logger.error(`Error: ${run.error ?? run.runResult?.error ?? 'capture failed'}`);
+        process.exit(1);
+    }
+    process.exit(0);
+}
+async function persistArtifactsLocally(presetId, outputDirOption, variants) {
+    const outputDir = path.resolve(outputDirOption);
+    await fs.mkdir(outputDir, { recursive: true });
+    for (const variant of variants) {
+        for (let index = 0; index < variant.artifacts.length; index += 1) {
+            const artifact = variant.artifacts[index];
+            const ext = artifact.mimeType === 'image/png'
+                ? 'png'
+                : artifact.mimeType === 'image/jpeg'
+                    ? 'jpg'
+                    : artifact.mimeType.includes('gif')
+                        ? 'gif'
+                        : artifact.mimeType.includes('mp4')
+                            ? 'mp4'
+                            : 'webm';
+            const filePath = path.join(outputDir, `v2-${presetId.slice(0, 8)}-${variant.variantId}-${index}.${ext}`);
+            await fs.writeFile(filePath, artifact.buffer);
+            logger.info(`[capture] Artifact saved locally: ${filePath}`);
+        }
+    }
+}
+//# sourceMappingURL=cli-runner-local.js.map

package/dist/v2/cli-runner.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Capture Agent — CLI Runner
+ *
+ * Entry point for V2 execution from the CLI.
+ * Flow:
+ * 1. Authenticate via stored API key
+ * 2. Fetch compiled program from server
+ * 3. Validate program against Zod schema
+ * 4. Launch local Playwright browser per variant
+ * 5. Execute program via opcode-runner
+ * 6. Upload artifacts + telemetry to server
+ */
+import { type ProgressEvent } from './opcode-runner.js';
+import type { ExecutionProgram, RunResult } from './types.js';
+export interface CLIRunnerOptions {
+    /** Preset ID to run */
+    presetId: string;
+    /** Override: provide program directly instead of fetching from server */
+    program?: ExecutionProgram;
+    /** Selector memory map (fetched from server or cached locally) */
+    selectorMemory?: Record<string, string[]>;
+    /** Show browser window. Default: false (headless) */
+    headed?: boolean;
+    /** Abort signal for cancellation */
+    abortSignal?: AbortSignal;
+    /** Progress callback */
+    onProgress?: (event: ProgressEvent) => void;
+}
+export interface CLIRunResult {
+    success: boolean;
+    runResult?: RunResult;
+    error?: string;
+}
+export declare function runCapture(options: CLIRunnerOptions): Promise<CLIRunResult>;