autokap 1.0.7 → 1.0.8

package/dist/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 './execution-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/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 './execution-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/cli-config.d.ts

@@ -5,9 +5,16 @@ export interface AutokapConfig {
 }
 declare const DEFAULT_API_BASE_URL = "https://autokap.app";
 declare const DEFAULT_WS_URL = "wss://autokap.app/ws";
+declare const LOCAL_API_BASE_URL = "http://localhost:3000";
+declare const LOCAL_WS_URL = "ws://localhost:3000/ws";
+declare const API_BASE_URL_ENV_VAR = "AUTOKAP_API_BASE_URL";
+declare const WS_URL_ENV_VAR = "AUTOKAP_WS_URL";
 export declare function getConfigDir(): string;
 export declare function getConfigPath(): string;
+export declare function getDefaultApiBaseUrl(): string;
+export declare function getDefaultWsUrl(apiBaseUrl?: string): string;
 export declare function readConfig(): Promise<AutokapConfig | null>;
 export declare function writeConfig(config: AutokapConfig): Promise<void>;
+export declare function deleteConfig(): Promise<void>;
 export declare function requireConfig(): Promise<AutokapConfig>;
-export { DEFAULT_API_BASE_URL, DEFAULT_WS_URL };
+export { DEFAULT_API_BASE_URL, DEFAULT_WS_URL, LOCAL_API_BASE_URL, LOCAL_WS_URL, API_BASE_URL_ENV_VAR, WS_URL_ENV_VAR, };

package/dist/cli-config.js

@@ -4,22 +4,38 @@ import fs from 'node:fs/promises';
 import { logger } from './logger.js';
 const DEFAULT_API_BASE_URL = 'https://autokap.app';
 const DEFAULT_WS_URL = 'wss://autokap.app/ws';
+const LOCAL_API_BASE_URL = 'http://localhost:3000';
+const LOCAL_WS_URL = 'ws://localhost:3000/ws';
+const API_BASE_URL_ENV_VAR = 'AUTOKAP_API_BASE_URL';
+const WS_URL_ENV_VAR = 'AUTOKAP_WS_URL';
 export function getConfigDir() {
     return path.join(os.homedir(), '.autokap');
 }
 export function getConfigPath() {
     return path.join(getConfigDir(), 'config.json');
 }
+export function getDefaultApiBaseUrl() {
+    return normalizeUrl(process.env[API_BASE_URL_ENV_VAR]) ?? DEFAULT_API_BASE_URL;
+}
+export function getDefaultWsUrl(apiBaseUrl = getDefaultApiBaseUrl()) {
+    return normalizeUrl(process.env[WS_URL_ENV_VAR]) ?? deriveWsUrl(apiBaseUrl);
+}
 export async function readConfig() {
     try {
         const raw = await fs.readFile(getConfigPath(), 'utf-8');
         const parsed = JSON.parse(raw);
         if (!parsed.apiKey)
             return null;
+        const envApiBaseUrl = normalizeUrl(process.env[API_BASE_URL_ENV_VAR]);
+        const envWsUrl = normalizeUrl(process.env[WS_URL_ENV_VAR]);
+        const storedApiBaseUrl = normalizeUrl(parsed.apiBaseUrl) ?? DEFAULT_API_BASE_URL;
+        const apiBaseUrl = envApiBaseUrl ?? storedApiBaseUrl;
+        const wsUrl = envWsUrl
+            ?? (envApiBaseUrl ? deriveWsUrl(apiBaseUrl) : normalizeUrl(parsed.wsUrl) ?? deriveWsUrl(apiBaseUrl));
         return {
             apiKey: parsed.apiKey,
-            apiBaseUrl: parsed.apiBaseUrl ?? DEFAULT_API_BASE_URL,
-            wsUrl: parsed.wsUrl ?? DEFAULT_WS_URL,
+            apiBaseUrl,
+            wsUrl,
         };
     }
     catch {
@@ -27,16 +43,56 @@ export async function readConfig() {
     }
 }
 export async function writeConfig(config) {
-    await fs.mkdir(getConfigDir(), { recursive: true });
-    await fs.writeFile(getConfigPath(), JSON.stringify(config, null, 2), 'utf-8');
+    const dir = getConfigDir();
+    await fs.mkdir(dir, { recursive: true });
+    const configPath = getConfigPath();
+    const normalizedConfig = {
+        ...config,
+        apiBaseUrl: normalizeUrl(config.apiBaseUrl) ?? DEFAULT_API_BASE_URL,
+        wsUrl: normalizeUrl(config.wsUrl) ?? deriveWsUrl(config.apiBaseUrl),
+    };
+    await fs.writeFile(configPath, JSON.stringify(normalizedConfig, null, 2), 'utf-8');
+    // Restrict file permissions on Unix (NTFS ignores POSIX modes)
+    if (process.platform !== 'win32') {
+        await fs.chmod(dir, 0o700);
+        await fs.chmod(configPath, 0o600);
+    }
+}
+export async function deleteConfig() {
+    try {
+        await fs.rm(getConfigPath());
+    }
+    catch {
+        // config file doesn't exist, nothing to do
+    }
 }
 export async function requireConfig() {
     const config = await readConfig();
     if (!config) {
-        logger.error('Not authenticated. Run `autokap login <key>` first.');
+        logger.error('Not authenticated. Run `npx autokap@latest init --cli-key <key>` first.');
         process.exit(1);
     }
     return config;
 }
-export { DEFAULT_API_BASE_URL, DEFAULT_WS_URL };
+function normalizeUrl(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return null;
+    return trimmed.replace(/\/+$/, '');
+}
+function deriveWsUrl(apiBaseUrl) {
+    try {
+        const url = new URL(apiBaseUrl);
+        url.protocol = url.protocol === 'https:' ? 'wss:' : url.protocol === 'http:' ? 'ws:' : url.protocol;
+        const pathname = url.pathname.replace(/\/+$/, '');
+        url.pathname = `${pathname || ''}/ws`;
+        url.search = '';
+        url.hash = '';
+        return url.toString().replace(/\/+$/, '');
+    }
+    catch {
+        return DEFAULT_WS_URL;
+    }
+}
+export { DEFAULT_API_BASE_URL, DEFAULT_WS_URL, LOCAL_API_BASE_URL, LOCAL_WS_URL, API_BASE_URL_ENV_VAR, WS_URL_ENV_VAR, };
 //# sourceMappingURL=cli-config.js.map

package/dist/cli-contract.d.ts

@@ -0,0 +1,15 @@
+export interface CliPublicCommandDescriptor {
+    id: string;
+    command: string;
+    summary: string;
+    docsDescriptionKey?: string;
+}
+export declare const CLI_KEY_TERM = "CLI key";
+export declare const CLI_DEFAULT_INSTALL_COMMAND = "npm install -g autokap";
+export declare const CLI_DEFAULT_SETUP_COMMAND = "npx autokap@latest init --cli-key <your-cli-key>";
+export declare const CLI_ADVANCED_SKILL_COMMAND = "npx autokap@latest skill --agent <agent>";
+export declare const CLI_FALLBACK_PROGRAM_COMMAND = "autokap run <preset-id> --program <file>";
+export declare function buildCliRunCommand(presetId: string, options?: {
+    local?: boolean;
+}): string;
+export declare const CLI_PUBLIC_COMMANDS: CliPublicCommandDescriptor[];

package/dist/cli-contract.js

@@ -0,0 +1,167 @@
+export const CLI_KEY_TERM = "CLI key";
+export const CLI_DEFAULT_INSTALL_COMMAND = "npm install -g autokap";
+export const CLI_DEFAULT_SETUP_COMMAND = "npx autokap@latest init --cli-key <your-cli-key>";
+export const CLI_ADVANCED_SKILL_COMMAND = "npx autokap@latest skill --agent <agent>";
+export const CLI_FALLBACK_PROGRAM_COMMAND = "autokap run <preset-id> --program <file>";
+export function buildCliRunCommand(presetId, options = {}) {
+    return `autokap run${options.local ? " --local" : ""} ${presetId}`;
+}
+export const CLI_PUBLIC_COMMANDS = [
+    {
+        id: "init",
+        command: "autokap init",
+        summary: "Authenticate and install the AI skill in one step",
+        docsDescriptionKey: "cliCmdInit",
+    },
+    {
+        id: "login",
+        command: "autokap login <key>",
+        summary: "Authenticate with your CLI key",
+        docsDescriptionKey: "cliCmdLogin",
+    },
+    {
+        id: "logout",
+        command: "autokap logout",
+        summary: "Remove stored credentials",
+        docsDescriptionKey: "cliCmdLogout",
+    },
+    {
+        id: "whoami",
+        command: "autokap whoami",
+        summary: "Show the account linked to the current CLI key",
+        docsDescriptionKey: "cliCmdWhoami",
+    },
+    {
+        id: "ping",
+        command: "autokap ping",
+        summary: "Verify CLI connection and confirm the stored key is still valid",
+        docsDescriptionKey: "cliCmdPing",
+    },
+    {
+        id: "run",
+        command: "autokap run <preset-id>",
+        summary: "Run a preset capture using local Playwright",
+        docsDescriptionKey: "cliCmdRun",
+    },
+    {
+        id: "run-headed",
+        command: "autokap run <preset-id> --headed",
+        summary: "Show the browser window for debugging",
+        docsDescriptionKey: "cliCmdHeaded",
+    },
+    {
+        id: "project-list",
+        command: "autokap project list",
+        summary: "List accessible projects as JSON",
+        docsDescriptionKey: "cliCmdProjectList",
+    },
+    {
+        id: "project-get",
+        command: "autokap project get <project-id>",
+        summary: "Get a single project as JSON",
+        docsDescriptionKey: "cliCmdProjectGet",
+    },
+    {
+        id: "project-create",
+        command: "autokap project create --name <name> --url <url>",
+        summary: "Create a project and print its ID",
+        docsDescriptionKey: "cliCmdProjectCreate",
+    },
+    {
+        id: "preset-info",
+        command: "autokap preset info <preset-id>",
+        summary: "Get structured JSON with endpoints, variants, and URL parameters",
+        docsDescriptionKey: "cliCmdPresetInfo",
+    },
+    {
+        id: "capture-list",
+        command: "autokap capture list",
+        summary: "List captures as JSON",
+        docsDescriptionKey: "cliCmdCaptureList",
+    },
+    {
+        id: "usage",
+        command: "autokap usage",
+        summary: "Show the current billing-period usage as JSON",
+        docsDescriptionKey: "cliCmdUsage",
+    },
+    {
+        id: "endpoints-list",
+        command: "autokap endpoints list --preset <id>",
+        summary: "List dev link endpoints as JSON or table",
+        docsDescriptionKey: "cliCmdEndpointsList",
+    },
+    {
+        id: "endpoints-get",
+        command: "autokap endpoints get <endpoint-id>",
+        summary: "Get a single dev link endpoint as JSON",
+        docsDescriptionKey: "cliCmdEndpointsGet",
+    },
+    {
+        id: "endpoints-export",
+        command: "autokap endpoints export --preset <id>",
+        summary: "Export dev link endpoints as JSON or CSV",
+        docsDescriptionKey: "cliCmdEndpointsExport",
+    },
+    {
+        id: "auth-capture",
+        command: "autokap auth capture <project-id>",
+        summary: "Capture a browser session for a session account",
+        docsDescriptionKey: "cliCmdAuthCapture",
+    },
+    {
+        id: "auth-account-list",
+        command: "autokap auth account list <project-id>",
+        summary: "List project credential accounts as JSON",
+        docsDescriptionKey: "cliCmdAuthAccountList",
+    },
+    {
+        id: "auth-account-create",
+        command: "autokap auth account create <project-id> --name <name>",
+        summary: "Create a project credential account and print its ID",
+        docsDescriptionKey: "cliCmdAuthAccountCreate",
+    },
+    {
+        id: "auth-account-update",
+        command: "autokap auth account update <project-id> --account <name-or-id>",
+        summary: "Update a project credential account",
+        docsDescriptionKey: "cliCmdAuthAccountUpdate",
+    },
+    {
+        id: "auth-account-delete",
+        command: "autokap auth account delete <project-id> --account <name-or-id>",
+        summary: "Delete an unused project credential account",
+        docsDescriptionKey: "cliCmdAuthAccountDelete",
+    },
+    {
+        id: "auth-session-clear",
+        command: "autokap auth session clear <project-id> --account <name-or-id>",
+        summary: "Clear the stored browser session for a session account",
+        docsDescriptionKey: "cliCmdAuthSessionClear",
+    },
+    {
+        id: "proxy-register",
+        command: "autokap proxy register --project <id> --proxy-url <url>",
+        summary: "Register a user-side proxy for dev links",
+        docsDescriptionKey: "cliCmdProxyRegister",
+    },
+    {
+        id: "proxy-verify",
+        command: "autokap proxy verify --project <id>",
+        summary: "Verify the configured proxy for a project",
+        docsDescriptionKey: "cliCmdProxyVerify",
+    },
+    {
+        id: "skill",
+        command: "autokap skill",
+        summary: "Export the AI agent skill bundle",
+        docsDescriptionKey: "cliCmdSkill",
+    },
+    {
+        id: "version",
+        command: "autokap --version",
+        summary: "Show the installed version",
+        docsDescriptionKey: "cliCmdVersion",
+    },
+];
+//# sourceMappingURL=cli-contract.js.map

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

@@ -0,0 +1,12 @@
+/**
+ * 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;
+    debug?: boolean;
+}): Promise<void>;

package/dist/cli-runner-local.js

@@ -0,0 +1,102 @@
+/**
+ * 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 './execution-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.mediaMode === 'dom'
+                ? 'html'
+                : artifact.mimeType === 'image/png'
+                    ? 'png'
+                    : artifact.mimeType === 'image/jpeg'
+                        ? 'jpg'
+                        : artifact.mimeType.includes('gif')
+                            ? 'gif'
+                            : artifact.mimeType.includes('mp4')
+                                ? 'mp4'
+                                : 'webm';
+            let suffix = '';
+            if (artifact.mediaMode === 'dom') {
+                if (artifact.fragmentName && artifact.parentStateName) {
+                    suffix = `-${artifact.parentStateName}-fragment-${artifact.fragmentName}`;
+                }
+                else if (artifact.stateName) {
+                    suffix = `-${artifact.stateName}`;
+                }
+            }
+            const filePath = path.join(outputDir, `capture-${presetId.slice(0, 8)}-${variant.variantId}${suffix}-${index}.${ext}`);
+            await fs.writeFile(filePath, artifact.buffer);
+            logger.info(`[capture] Artifact saved locally: ${filePath}`);
+        }
+    }
+}
+//# sourceMappingURL=cli-runner-local.js.map

package/dist/cli-runner.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Capture Agent — CLI Runner
+ *
+ * Entry point for deterministic execution from the CLI.
+ * Flow:
+ * 1. Authenticate via stored CLI 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 './execution-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>;