autokap 1.0.6 → 1.0.8

package/dist/benchmark.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Capture Agent — Benchmark Harness
+ *
+ * Runs the same preset repeatedly, comparing:
+ * - Total LLM cost
+ * - Total wall-clock time
+ * - Success rate
+ * - Recovery rate (how often healing was needed)
+ *
+ * Useful for tracking determinism, recovery rate, and runtime cost over time.
+ */
+import type { ExecutionProgram, RunResult } from './execution-types.js';
+export interface BenchmarkPreset {
+    name: string;
+    presetId: string;
+    program: ExecutionProgram;
+    /** Expected behavior description for manual verification */
+    expectedBehavior: string;
+    /** Difficulty tier */
+    tier: 'simple' | 'multi_step' | 'auth_required' | 'clip' | 'video';
+}
+export interface BenchmarkRunResult {
+    presetName: string;
+    tier: string;
+    success: boolean;
+    totalDurationMs: number;
+    llmCostEur: number;
+    llmCallCount: number;
+    totalOpcodes: number;
+    recoveredOpcodes: number;
+    failedOpcodes: number;
+    healerInvocations: number;
+    circuitBreakerTrips: number;
+    variantCount: number;
+    successfulVariants: number;
+    error?: string;
+}
+export interface BenchmarkSummary {
+    totalPresets: number;
+    successCount: number;
+    failCount: number;
+    successRate: number;
+    averageDurationMs: number;
+    averageLlmCostEur: number;
+    totalLlmCostEur: number;
+    deterministicRate: number;
+    recoveryRate: number;
+    results: BenchmarkRunResult[];
+    byTier: Record<string, {
+        total: number;
+        success: number;
+        rate: number;
+    }>;
+}
+export type RunFn = (program: ExecutionProgram) => Promise<RunResult>;
+export declare function runBenchmark(presets: BenchmarkPreset[], runCapture: RunFn, options?: {
+    runs?: number;
+}): Promise<BenchmarkSummary>;
+export declare function formatBenchmarkSummary(summary: BenchmarkSummary): string;

package/dist/benchmark.js

@@ -0,0 +1,135 @@
+/**
+ * Capture Agent — Benchmark Harness
+ *
+ * Runs the same preset repeatedly, comparing:
+ * - Total LLM cost
+ * - Total wall-clock time
+ * - Success rate
+ * - Recovery rate (how often healing was needed)
+ *
+ * Useful for tracking determinism, recovery rate, and runtime cost over time.
+ */
+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('  Capture 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('═══════════════════════════════════════════════════');
+    // Health 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('  Health 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/billing-operation-logging.d.ts

@@ -0,0 +1,38 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { StepUsage } from './types.js';
+export type BillingOperationType = 'screenshot' | 'clip' | 'video';
+type BillingOperationOutcome = 'succeeded' | 'failed' | 'cancelled';
+interface BillingOperationContext {
+    runId: string;
+    userId: string;
+    projectId?: string | null;
+    presetId?: string | null;
+    captureId?: string | null;
+    videoId?: string | null;
+    clipRecordId?: string | null;
+    operationType: BillingOperationType;
+    captureType?: 'fullpage' | 'element' | 'video' | null;
+    lang?: string | null;
+    theme?: 'light' | 'dark' | string | null;
+    elementName?: string;
+    targetId?: string;
+    viewportWidth?: number | null;
+    viewportHeight?: number | null;
+    deviceFrame?: string | null;
+}
+interface BillingOperationParams {
+    outcome: BillingOperationOutcome;
+    outcomeReason?: string | null;
+    billable: boolean;
+    creditsCharged: number;
+    costLogIds: string[];
+    usage: StepUsage[];
+    metadata?: Record<string, unknown>;
+}
+export declare function insertBillingOperationLog(supabase: SupabaseClient, ctx: BillingOperationContext, params: BillingOperationParams): Promise<string | null>;
+export declare function insertScreenshotOperationLog(supabase: SupabaseClient, ctx: Omit<BillingOperationContext, 'operationType'>, params: BillingOperationParams): Promise<string | null>;
+export declare function insertClipOperationLog(supabase: SupabaseClient, ctx: Omit<BillingOperationContext, 'operationType'>, params: BillingOperationParams): Promise<string | null>;
+export declare function insertVideoOperationLog(supabase: SupabaseClient, ctx: Omit<BillingOperationContext, 'operationType'>, params: BillingOperationParams): Promise<string | null>;
+export declare function cancelScreenshotOperationLogsForCapture(supabase: SupabaseClient, captureId: string, reason: string): Promise<void>;
+export declare function reconcilePendingBillingOperationCosts(supabase: SupabaseClient, operationIds?: string[]): Promise<void>;
+export {};

package/dist/billing-operation-logging.js

@@ -0,0 +1,248 @@
+function uniqNonEmpty(values) {
+    return Array.from(new Set(values
+        .map((value) => value?.trim())
+        .filter((value) => !!value)));
+}
+function summarizeUsage(usage) {
+    return {
+        llmCallCount: usage.length,
+        promptTokens: usage.reduce((sum, step) => sum + (step.promptTokens ?? 0), 0),
+        completionTokens: usage.reduce((sum, step) => sum + (step.completionTokens ?? 0), 0),
+        totalTokens: usage.reduce((sum, step) => sum + (step.totalTokens ?? 0), 0),
+        cacheReadTokens: usage.reduce((sum, step) => sum + (step.cacheReadTokens ?? 0), 0),
+        cacheWriteTokens: usage.reduce((sum, step) => sum + (step.cacheWriteTokens ?? 0), 0),
+        imagesInPrompt: usage.reduce((sum, step) => sum + (step.imagesInPrompt ?? 0), 0),
+        modelRequested: uniqNonEmpty(usage.map((step) => step.modelRequested)).join(', ') || null,
+        modelUsed: uniqNonEmpty(usage.map((step) => step.modelUsed)).join(', ') || null,
+        generationIds: uniqNonEmpty(usage.map((step) => step.generationId)),
+    };
+}
+async function resolveCostLogs(supabase, costLogIds) {
+    if (costLogIds.length === 0) {
+        return {
+            costUsd: 0,
+            costSource: 'no_llm',
+            costResolved: true,
+            costResolutionStatus: 'resolved',
+            costResolutionError: null,
+            resolvedAt: new Date().toISOString(),
+        };
+    }
+    const { data, error } = await supabase
+        .from('cost_logs')
+        .select('id, generation_id, cost_resolved, cost_usd')
+        .in('id', costLogIds);
+    if (error) {
+        return {
+            costUsd: null,
+            costSource: 'cost_logs_lookup_failed',
+            costResolved: false,
+            costResolutionStatus: 'unresolvable',
+            costResolutionError: error.message,
+            resolvedAt: null,
+        };
+    }
+    const rows = data ?? [];
+    if (rows.length !== costLogIds.length) {
+        return {
+            costUsd: null,
+            costSource: 'missing_cost_logs',
+            costResolved: false,
+            costResolutionStatus: 'unresolvable',
+            costResolutionError: `Expected ${costLogIds.length} cost log rows, found ${rows.length}.`,
+            resolvedAt: null,
+        };
+    }
+    if (rows.some((row) => !row.cost_resolved || row.cost_usd == null)) {
+        if (rows.some((row) => !row.cost_resolved && row.cost_usd == null && row.generation_id == null)) {
+            return {
+                costUsd: null,
+                costSource: 'missing_generation_id',
+                costResolved: false,
+                costResolutionStatus: 'unresolvable',
+                costResolutionError: 'At least one referenced cost log is missing a generation_id, so OpenRouter cannot return the real cost.',
+                resolvedAt: null,
+            };
+        }
+        return {
+            costUsd: null,
+            costSource: 'aggregated_cost_logs_pending',
+            costResolved: false,
+            costResolutionStatus: 'pending',
+            costResolutionError: null,
+            resolvedAt: null,
+        };
+    }
+    const costUsd = rows.reduce((sum, row) => sum + Number(row.cost_usd ?? 0), 0);
+    return {
+        costUsd,
+        costSource: 'aggregated_cost_logs',
+        costResolved: true,
+        costResolutionStatus: 'resolved',
+        costResolutionError: null,
+        resolvedAt: new Date().toISOString(),
+    };
+}
+function deriveInitialCostResolution(usage, costLogIds) {
+    if (usage.length === 0) {
+        return {
+            costUsd: 0,
+            costSource: 'no_llm',
+            costResolved: true,
+            costResolutionStatus: 'resolved',
+            costResolutionError: null,
+            resolvedAt: new Date().toISOString(),
+        };
+    }
+    if (costLogIds.length !== usage.length) {
+        return {
+            costUsd: null,
+            costSource: 'missing_cost_logs',
+            costResolved: false,
+            costResolutionStatus: 'unresolvable',
+            costResolutionError: `Expected ${usage.length} cost log ids, received ${costLogIds.length}.`,
+            resolvedAt: null,
+        };
+    }
+    const missingGenerationCount = usage.filter((step) => !step.generationId?.trim()).length;
+    if (missingGenerationCount > 0) {
+        return {
+            costUsd: null,
+            costSource: 'missing_generation_id',
+            costResolved: false,
+            costResolutionStatus: 'unresolvable',
+            costResolutionError: `Expected generation ids for all usage steps, but ${missingGenerationCount} step(s) are missing them.`,
+            resolvedAt: null,
+        };
+    }
+    return null;
+}
+export async function insertBillingOperationLog(supabase, ctx, params) {
+    const usageSummary = summarizeUsage(params.usage);
+    const forcedResolution = deriveInitialCostResolution(params.usage, params.costLogIds);
+    const costResolution = forcedResolution ?? await resolveCostLogs(supabase, params.costLogIds);
+    const id = crypto.randomUUID();
+    const { error } = await supabase.from('billing_operation_logs').insert({
+        id,
+        run_id: ctx.runId,
+        user_id: ctx.userId,
+        project_id: ctx.projectId ?? null,
+        preset_id: ctx.presetId ?? null,
+        capture_id: ctx.captureId ?? null,
+        video_id: ctx.videoId ?? null,
+        clip_record_id: ctx.clipRecordId ?? null,
+        operation_type: ctx.operationType,
+        operation_outcome: params.outcome,
+        outcome_reason: params.outcomeReason ?? null,
+        billable: params.billable,
+        credits_charged: params.creditsCharged,
+        cost_usd: costResolution.costUsd,
+        cost_resolved: costResolution.costResolved,
+        cost_resolution_status: costResolution.costResolutionStatus,
+        cost_source: costResolution.costSource,
+        cost_resolution_error: costResolution.costResolutionError,
+        resolved_at: costResolution.resolvedAt,
+        cost_log_ids: params.costLogIds,
+        llm_call_count: usageSummary.llmCallCount,
+        prompt_tokens: usageSummary.promptTokens,
+        completion_tokens: usageSummary.completionTokens,
+        total_tokens: usageSummary.totalTokens,
+        cache_read_tokens: usageSummary.cacheReadTokens,
+        cache_write_tokens: usageSummary.cacheWriteTokens,
+        images_in_prompt: usageSummary.imagesInPrompt,
+        model_requested: usageSummary.modelRequested,
+        model_used: usageSummary.modelUsed,
+        capture_type: ctx.captureType ?? null,
+        target_id: ctx.targetId ?? null,
+        element_name: ctx.elementName ?? null,
+        lang: ctx.lang ?? null,
+        theme: ctx.theme ?? null,
+        viewport_width: ctx.viewportWidth ?? null,
+        viewport_height: ctx.viewportHeight ?? null,
+        device_frame: ctx.deviceFrame ?? null,
+        metadata: {
+            ...(params.metadata ?? {}),
+            generationIds: usageSummary.generationIds,
+        },
+    });
+    if (error) {
+        console.error('Failed to insert billing operation log:', error.message);
+        return null;
+    }
+    return id;
+}
+export async function insertScreenshotOperationLog(supabase, ctx, params) {
+    return insertBillingOperationLog(supabase, { ...ctx, operationType: 'screenshot' }, params);
+}
+export async function insertClipOperationLog(supabase, ctx, params) {
+    return insertBillingOperationLog(supabase, { ...ctx, operationType: 'clip' }, params);
+}
+export async function insertVideoOperationLog(supabase, ctx, params) {
+    return insertBillingOperationLog(supabase, { ...ctx, operationType: 'video' }, params);
+}
+export async function cancelScreenshotOperationLogsForCapture(supabase, captureId, reason) {
+    try {
+        const { error } = await supabase
+            .from('billing_operation_logs')
+            .update({
+            operation_outcome: 'cancelled',
+            outcome_reason: reason,
+            billable: false,
+            credits_charged: 0,
+        })
+            .eq('capture_id', captureId)
+            .eq('operation_type', 'screenshot');
+        if (error) {
+            console.error('Failed to cancel screenshot billing operation logs:', error.message);
+        }
+    }
+    catch (error) {
+        console.error('Failed to cancel screenshot billing operation logs:', error.message);
+    }
+}
+export async function reconcilePendingBillingOperationCosts(supabase, operationIds) {
+    try {
+        let query = supabase
+            .from('billing_operation_logs')
+            .select('id, cost_log_ids')
+            .eq('cost_resolution_status', 'pending');
+        if (operationIds?.length) {
+            query = query.in('id', operationIds);
+        }
+        else {
+            query = query.limit(100);
+        }
+        const { data, error } = await query;
+        if (error) {
+            console.error('Failed to load pending billing operations:', error.message);
+            return;
+        }
+        for (const row of data ?? []) {
+            const costLogIds = Array.isArray(row.cost_log_ids)
+                ? row.cost_log_ids.filter((value) => typeof value === 'string')
+                : [];
+            const resolution = await resolveCostLogs(supabase, costLogIds);
+            if (!resolution.costResolved && resolution.costResolutionStatus === 'pending') {
+                continue;
+            }
+            const { error: updateError } = await supabase
+                .from('billing_operation_logs')
+                .update({
+                cost_usd: resolution.costUsd,
+                cost_resolved: resolution.costResolved,
+                cost_resolution_status: resolution.costResolutionStatus,
+                cost_source: resolution.costSource,
+                cost_resolution_error: resolution.costResolutionError,
+                resolved_at: resolution.resolvedAt,
+            })
+                .eq('id', row.id);
+            if (updateError) {
+                console.error(`Failed to reconcile billing operation log ${row.id}:`, updateError.message);
+            }
+        }
+    }
+    catch (error) {
+        console.error('Failed to reconcile pending billing operation costs:', error.message);
+    }
+}
+//# sourceMappingURL=billing-operation-logging.js.map

package/dist/browser-bar.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Browser bar — dispatches between coded browser chrome styles (Chrome, Safari, …).
+ *
+ * Chrome: pixel-perfect from toolbar4.svg (ref 2160×129, two-row layout).
+ * Safari: ref 1500×52, single-row toolbar with SF Pro Symbols icons.
+ *
+ * Dynamic content (page title, URL, favicon) overlaid as HTML.
+ * SF Pro embedded fonts for cross-OS rendering.
+ */
+export type BrowserBarStyle = 'chrome' | 'safari';
+export interface BrowserBarConfig {
+    url?: string;
+    pageTitle?: string;
+    tabIconUrl?: string;
+    colorScheme?: 'light' | 'dark';
+    /** Which coded browser chrome to draw. Defaults to 'chrome' when unset. */
+    style?: BrowserBarStyle;
+}
+export interface BrowserBarZoneRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fontSize?: number;
+    fontWeight?: number | string;
+    textAlign?: 'left' | 'center' | 'right';
+}
+export interface BrowserBarZones {
+    favicon?: BrowserBarZoneRect;
+    pageTitle?: BrowserBarZoneRect;
+    url?: BrowserBarZoneRect;
+}
+export interface BrowserBarRenderOptions {
+    config: BrowserBarConfig;
+    width: number;
+    height: number;
+    scale: number;
+    pixelScale?: number;
+}
+export declare function generateBrowserBarHtml(options: BrowserBarRenderOptions): string;
+export declare function generateBrowserBarSvg(options: BrowserBarRenderOptions): string;
+export declare function generateChromeBrowserBarHtml(options: BrowserBarRenderOptions): string;
+/**
+ * Generate a self-contained SVG string for the Chrome browser bar.
+ * Used by the sharp compositing pipeline (no Playwright).
+ * Returns an SVG at the target width×height with embedded fonts.
+ */
+export declare function generateChromeBrowserBarSvg(options: BrowserBarRenderOptions): string;