aegis-bridge 0.1.0

package/dist/pipeline.js

@@ -0,0 +1,291 @@
+/**
+ * pipeline.ts — Batch create and pipeline orchestration.
+ *
+ * Issue #36: Create multiple sessions in parallel, or define
+ * sequential pipelines with stage dependencies.
+ */
+import { getErrorMessage } from './validation.js';
+import { shouldRetry } from './error-categories.js';
+import { retryWithJitter } from './retry.js';
+export class PipelineManager {
+    sessions;
+    eventBus;
+    static PIPELINE_RETRY_MAX_ATTEMPTS = 3;
+    static PIPELINE_FIX_MAX_RETRIES = 3;
+    pipelines = new Map();
+    pipelineConfigs = new Map(); // #219: preserve original stage config
+    pollInterval = null;
+    cleanupTimers = new Map(); // #1092: track cleanup timers per pipeline
+    constructor(sessions, eventBus) {
+        this.sessions = sessions;
+        this.eventBus = eventBus;
+    }
+    /** Create multiple sessions in parallel. */
+    async batchCreate(specs) {
+        const results = await Promise.allSettled(specs.map(async (spec) => {
+            const session = await this.sessions.createSession({
+                workDir: spec.workDir,
+                name: spec.name,
+                permissionMode: spec.permissionMode,
+                autoApprove: spec.autoApprove,
+                stallThresholdMs: spec.stallThresholdMs,
+            });
+            let promptDelivery;
+            if (spec.prompt) {
+                promptDelivery = await this.sessions.sendInitialPrompt(session.id, spec.prompt);
+            }
+            return {
+                id: session.id,
+                name: session.windowName,
+                promptDelivery,
+            };
+        }));
+        const sessions = [];
+        const errors = [];
+        for (const result of results) {
+            if (result.status === 'fulfilled') {
+                sessions.push(result.value);
+            }
+            else {
+                errors.push(result.reason?.message || 'Unknown error');
+            }
+        }
+        return {
+            sessions,
+            created: sessions.length,
+            failed: errors.length,
+            errors,
+        };
+    }
+    /** Create a pipeline with stage dependencies. */
+    async createPipeline(config) {
+        const id = crypto.randomUUID();
+        // Validate: all dependsOn references must exist as stage names
+        const stageNames = new Set(config.stages.map(s => s.name));
+        for (const stage of config.stages) {
+            for (const dep of stage.dependsOn || []) {
+                if (!stageNames.has(dep)) {
+                    throw new Error(`Stage "${stage.name}" depends on unknown stage "${dep}"`);
+                }
+            }
+        }
+        // Check for circular dependencies
+        this.detectCycles(config.stages);
+        const pipeline = {
+            id,
+            name: config.name,
+            currentStage: 'plan',
+            status: 'running',
+            retryCount: 0,
+            maxRetries: PipelineManager.PIPELINE_FIX_MAX_RETRIES,
+            stageHistory: [{ stage: 'plan', enteredAt: Date.now() }],
+            stages: config.stages.map(s => ({
+                name: s.name,
+                status: 'pending',
+                dependsOn: s.dependsOn || [],
+            })),
+            createdAt: Date.now(),
+        };
+        this.pipelines.set(id, pipeline);
+        this.pipelineConfigs.set(id, config); // #219: store original config for polling
+        // Start stages with no dependencies immediately
+        await this.advancePipeline(id, config);
+        // Start polling for stage completion
+        if (!this.pollInterval) {
+            this.pollInterval = setInterval(() => this.pollPipelines(), 5000);
+        }
+        return pipeline;
+    }
+    /** Get pipeline state. */
+    getPipeline(id) {
+        return this.pipelines.get(id) || null;
+    }
+    /** List all pipelines. */
+    listPipelines() {
+        return Array.from(this.pipelines.values());
+    }
+    /** Advance a pipeline: start stages whose dependencies are met. */
+    async advancePipeline(id, config) {
+        const pipeline = this.pipelines.get(id);
+        if (!pipeline || pipeline.status !== 'running')
+            return;
+        const completedStages = new Set(pipeline.stages.filter(s => s.status === 'completed').map(s => s.name));
+        const failedStages = pipeline.stages.filter(s => s.status === 'failed');
+        // If any stage failed, fail the pipeline
+        if (failedStages.length > 0) {
+            pipeline.status = 'failed';
+            this.transitionPipelineStage(pipeline, 'fix', { reason: 'stage_failed', failedStages: failedStages.map(s => s.name) });
+            return;
+        }
+        // Check if all stages are completed
+        if (pipeline.stages.every(s => s.status === 'completed')) {
+            pipeline.status = 'completed';
+            this.transitionPipelineStage(pipeline, 'submit', { reason: 'all_stages_completed' });
+            this.transitionPipelineStage(pipeline, 'done', { status: 'completed' });
+            if (this.eventBus) {
+                this.eventBus.emitEnded(id, 'pipeline_completed');
+            }
+            return;
+        }
+        // Start pending stages whose dependencies are all completed
+        for (const stage of pipeline.stages) {
+            if (stage.status !== 'pending')
+                continue;
+            const depsComplete = stage.dependsOn.every(d => completedStages.has(d));
+            if (!depsComplete)
+                continue;
+            // Find matching config stage
+            const stageConfig = config.stages.find(s => s.name === stage.name);
+            if (!stageConfig)
+                continue;
+            try {
+                const session = await retryWithJitter(async () => this.sessions.createSession({
+                    workDir: stageConfig.workDir || config.workDir,
+                    name: `pipeline-${config.name}-${stage.name}`,
+                    permissionMode: stageConfig.permissionMode,
+                    autoApprove: stageConfig.autoApprove,
+                }), {
+                    maxAttempts: PipelineManager.PIPELINE_RETRY_MAX_ATTEMPTS,
+                    shouldRetry: (error) => shouldRetry(error),
+                });
+                if (stageConfig.prompt) {
+                    await retryWithJitter(async () => this.sessions.sendInitialPrompt(session.id, stageConfig.prompt), {
+                        maxAttempts: PipelineManager.PIPELINE_RETRY_MAX_ATTEMPTS,
+                        shouldRetry: (error) => shouldRetry(error),
+                    });
+                }
+                stage.sessionId = session.id;
+                stage.status = 'running';
+                stage.startedAt = Date.now();
+                this.transitionPipelineStage(pipeline, 'execute', { stage: stage.name, sessionId: session.id });
+            }
+            catch (e) {
+                stage.status = 'failed';
+                stage.error = getErrorMessage(e);
+                pipeline.status = 'failed';
+                this.transitionPipelineStage(pipeline, 'fix', { stage: stage.name, error: stage.error });
+            }
+        }
+        const hasRunning = pipeline.stages.some(s => s.status === 'running');
+        const hasPending = pipeline.stages.some(s => s.status === 'pending');
+        if (hasRunning) {
+            this.transitionPipelineStage(pipeline, 'verify', { runningStages: pipeline.stages.filter(s => s.status === 'running').map(s => s.name) });
+        }
+        else if (hasPending) {
+            this.transitionPipelineStage(pipeline, 'plan', { pendingStages: pipeline.stages.filter(s => s.status === 'pending').map(s => s.name) });
+        }
+    }
+    /** Poll running pipelines and advance stages. */
+    async pollPipelines() {
+        // #830: Stop polling immediately when no pipelines remain, rather than
+        // waiting for the 30s cleanup setTimeout to fire. Prevents ~6 no-op poll
+        // cycles and stale config references during the cleanup window.
+        if (this.pipelines.size === 0) {
+            if (this.pollInterval) {
+                clearInterval(this.pollInterval);
+                this.pollInterval = null;
+            }
+            return;
+        }
+        for (const [id, pipeline] of this.pipelines) {
+            if (pipeline.status !== 'running')
+                continue;
+            // Check running stages for completion (idle status = done)
+            for (const stage of pipeline.stages) {
+                if (stage.status !== 'running' || !stage.sessionId)
+                    continue;
+                const session = this.sessions.getSession(stage.sessionId);
+                if (!session) {
+                    stage.status = 'failed';
+                    stage.error = 'Session disappeared';
+                    continue;
+                }
+                if (session.status === 'idle') {
+                    stage.status = 'completed';
+                    stage.completedAt = Date.now();
+                    this.transitionPipelineStage(pipeline, 'verify', { stageCompleted: stage.name });
+                }
+            }
+            // #219: Use stored original config so stage prompt/permissionMode/autoApprove/workDir are preserved
+            const storedConfig = this.pipelineConfigs.get(id);
+            if (storedConfig) {
+                await this.advancePipeline(id, storedConfig);
+            }
+            // #221: Clean up completed/failed pipelines after 30s to avoid memory leak
+            // Note: advancePipeline may change status from 'running' to 'completed'/'failed'
+            // #1092: Track cleanup timer to prevent duplicates and allow destroy() cleanup
+            if (pipeline.status !== 'running' && !this.cleanupTimers.has(id)) {
+                const pipelineId = id;
+                const timer = setTimeout(() => {
+                    this.cleanupTimers.delete(pipelineId);
+                    this.pipelines.delete(pipelineId);
+                    this.pipelineConfigs.delete(pipelineId); // #219: clean up stored config
+                    // #578: Stop polling when no pipelines remain
+                    if (this.pipelines.size === 0 && this.pollInterval) {
+                        clearInterval(this.pollInterval);
+                        this.pollInterval = null;
+                    }
+                }, 30_000);
+                this.cleanupTimers.set(pipelineId, timer);
+            }
+        }
+    }
+    transitionPipelineStage(pipeline, stage, output) {
+        if (pipeline.currentStage === stage)
+            return;
+        const now = Date.now();
+        const previous = pipeline.stageHistory[pipeline.stageHistory.length - 1];
+        if (previous && previous.exitedAt === undefined) {
+            previous.exitedAt = now;
+            if (output !== undefined)
+                previous.output = output;
+        }
+        pipeline.currentStage = stage;
+        pipeline.stageHistory.push({ stage, enteredAt: now });
+        if (stage === 'fix') {
+            pipeline.retryCount += 1;
+            if (pipeline.retryCount > pipeline.maxRetries) {
+                pipeline.status = 'failed';
+            }
+        }
+    }
+    /** Detect circular dependencies. Throws if found. */
+    detectCycles(stages) {
+        const graph = new Map();
+        for (const stage of stages) {
+            graph.set(stage.name, stage.dependsOn || []);
+        }
+        const visited = new Set();
+        const inStack = new Set();
+        const dfs = (node) => {
+            if (inStack.has(node))
+                throw new Error(`Circular dependency detected involving stage "${node}"`);
+            if (visited.has(node))
+                return;
+            inStack.add(node);
+            visited.add(node);
+            for (const dep of graph.get(node) || []) {
+                dfs(dep);
+            }
+            inStack.delete(node);
+        };
+        for (const stage of stages) {
+            dfs(stage.name);
+        }
+    }
+    /** Clean up. */
+    destroy() {
+        if (this.pollInterval) {
+            clearInterval(this.pollInterval);
+            this.pollInterval = null;
+        }
+        // #1092: Clear all pending cleanup timers
+        for (const timer of this.cleanupTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.cleanupTimers.clear();
+        // #1092: Clear maps to release memory
+        this.pipelines.clear();
+        this.pipelineConfigs.clear();
+    }
+}

package/dist/process-utils.d.ts

@@ -0,0 +1,4 @@
+export declare function buildWindowsFindPidOnPortScript(port: number): string;
+export declare function buildWindowsReadParentPidScript(pid: number): string;
+export declare function findPidOnPort(port: number): Promise<number[]>;
+export declare function readParentPid(pid: number): Promise<number | null>;

package/dist/process-utils.js

@@ -0,0 +1,73 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+const SUBPROCESS_TIMEOUT_MS = 5_000;
+function runCommand(command, args) {
+    return new Promise((resolve, reject) => {
+        execFile(command, args, { encoding: 'utf-8', timeout: SUBPROCESS_TIMEOUT_MS, maxBuffer: 1024 * 1024 }, (error, stdout) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}
+function parsePidLines(output) {
+    return [...new Set(output
+            .trim()
+            .split(/\r?\n/)
+            .map(line => parseInt(line.trim(), 10))
+            .filter(pid => Number.isInteger(pid) && pid > 0))];
+}
+export function buildWindowsFindPidOnPortScript(port) {
+    return [
+        `Get-NetTCPConnection -State Listen -LocalPort ${port} -ErrorAction SilentlyContinue`,
+        'Select-Object -ExpandProperty OwningProcess -Unique',
+    ].join(' | ');
+}
+export function buildWindowsReadParentPidScript(pid) {
+    return [
+        `Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}" -ErrorAction SilentlyContinue`,
+        'Select-Object -ExpandProperty ParentProcessId',
+    ].join(' | ');
+}
+export async function findPidOnPort(port) {
+    if (!Number.isInteger(port) || port <= 0 || port > 65535)
+        return [];
+    try {
+        if (process.platform === 'win32') {
+            const script = buildWindowsFindPidOnPortScript(port);
+            const stdout = await runCommand('powershell', ['-NoProfile', '-Command', script]);
+            return parsePidLines(stdout);
+        }
+        const stdout = await runCommand('lsof', ['-ti', `tcp:${port}`]);
+        return parsePidLines(stdout);
+    }
+    catch {
+        return [];
+    }
+}
+export async function readParentPid(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    try {
+        if (process.platform === 'win32') {
+            const script = buildWindowsReadParentPidScript(pid);
+            const stdout = await runCommand('powershell', ['-NoProfile', '-Command', script]);
+            const parent = parseInt(stdout.trim(), 10);
+            return Number.isInteger(parent) && parent > 0 ? parent : null;
+        }
+        if (process.platform !== 'linux') {
+            return null;
+        }
+        const status = await readFile(`/proc/${pid}/status`, 'utf-8');
+        const match = status.match(/^PPid:\s+(\d+)/m);
+        if (!match)
+            return null;
+        const parent = parseInt(match[1], 10);
+        return Number.isInteger(parent) && parent > 0 ? parent : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/question-manager.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Question Manager: Manages pending user questions and their lifecycle.
+ * Issue #336: Store a pending AskUserQuestion and return a promise that
+ * resolves when the external client provides an answer via POST /answer.
+ *
+ * Phase 2: Extracted from session.ts as part of Issue #351 decomposition.
+ */
+export declare class QuestionManager {
+    private pendingQuestions;
+    /**
+     * Store a pending AskUserQuestion and return a promise that resolves
+     * when the external client provides an answer via POST /answer.
+     *
+     * @param sessionId - Aegis session ID
+     * @param toolUseId - Unique tool use ID for this question
+     * @param question - The question text to ask the user
+     * @param timeoutMs - Timeout before resolving with null (default 30_000ms)
+     * @returns Promise that resolves with the user's answer or null on timeout
+     */
+    waitForAnswer(sessionId: string, toolUseId: string, question: string, timeoutMs?: number): Promise<string | null>;
+    /**
+     * Submit an answer to a pending question.
+     *
+     * @param sessionId - Aegis session ID
+     * @param questionId - Tool use ID of the question (for verification)
+     * @param answer - The user's answer
+     * @returns True if the question was resolved, false if not found or ID mismatch
+     */
+    submitAnswer(sessionId: string, questionId: string, answer: string): boolean;
+    /**
+     * Check if a session has a pending question.
+     *
+     * @param sessionId - Aegis session ID
+     * @returns True if a pending question exists for this session
+     */
+    hasPendingQuestion(sessionId: string): boolean;
+    /**
+     * Get info about a pending question (for API responses).
+     *
+     * @param sessionId - Aegis session ID
+     * @returns Object with toolUseId, question, and timestamp, or null if no pending question
+     */
+    getPendingQuestionInfo(sessionId: string): {
+        toolUseId: string;
+        question: string;
+        timestamp: number;
+    } | null;
+    /**
+     * Clean up any pending question for a session (e.g. on session delete).
+     *
+     * @param sessionId - Aegis session ID
+     */
+    cleanupPendingQuestion(sessionId: string): void;
+}

package/dist/question-manager.js

@@ -0,0 +1,80 @@
+/**
+ * Question Manager: Manages pending user questions and their lifecycle.
+ * Issue #336: Store a pending AskUserQuestion and return a promise that
+ * resolves when the external client provides an answer via POST /answer.
+ *
+ * Phase 2: Extracted from session.ts as part of Issue #351 decomposition.
+ */
+export class QuestionManager {
+    pendingQuestions = new Map();
+    /**
+     * Store a pending AskUserQuestion and return a promise that resolves
+     * when the external client provides an answer via POST /answer.
+     *
+     * @param sessionId - Aegis session ID
+     * @param toolUseId - Unique tool use ID for this question
+     * @param question - The question text to ask the user
+     * @param timeoutMs - Timeout before resolving with null (default 30_000ms)
+     * @returns Promise that resolves with the user's answer or null on timeout
+     */
+    waitForAnswer(sessionId, toolUseId, question, timeoutMs = 30_000) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.pendingQuestions.delete(sessionId);
+                console.log(`Hooks: AskUserQuestion timeout for session ${sessionId} — allowing without answer`);
+                resolve(null);
+            }, timeoutMs);
+            this.pendingQuestions.set(sessionId, { resolve, timer, toolUseId, question, timestamp: Date.now() });
+        });
+    }
+    /**
+     * Submit an answer to a pending question.
+     *
+     * @param sessionId - Aegis session ID
+     * @param questionId - Tool use ID of the question (for verification)
+     * @param answer - The user's answer
+     * @returns True if the question was resolved, false if not found or ID mismatch
+     */
+    submitAnswer(sessionId, questionId, answer) {
+        const pending = this.pendingQuestions.get(sessionId);
+        if (!pending)
+            return false;
+        if (pending.toolUseId !== questionId)
+            return false;
+        clearTimeout(pending.timer);
+        this.pendingQuestions.delete(sessionId);
+        pending.resolve(answer);
+        return true;
+    }
+    /**
+     * Check if a session has a pending question.
+     *
+     * @param sessionId - Aegis session ID
+     * @returns True if a pending question exists for this session
+     */
+    hasPendingQuestion(sessionId) {
+        return this.pendingQuestions.has(sessionId);
+    }
+    /**
+     * Get info about a pending question (for API responses).
+     *
+     * @param sessionId - Aegis session ID
+     * @returns Object with toolUseId, question, and timestamp, or null if no pending question
+     */
+    getPendingQuestionInfo(sessionId) {
+        const pending = this.pendingQuestions.get(sessionId);
+        return pending ? { toolUseId: pending.toolUseId, question: pending.question, timestamp: pending.timestamp } : null;
+    }
+    /**
+     * Clean up any pending question for a session (e.g. on session delete).
+     *
+     * @param sessionId - Aegis session ID
+     */
+    cleanupPendingQuestion(sessionId) {
+        const pending = this.pendingQuestions.get(sessionId);
+        if (pending) {
+            clearTimeout(pending.timer);
+            this.pendingQuestions.delete(sessionId);
+        }
+    }
+}

package/dist/retry.d.ts

@@ -0,0 +1,11 @@
+/**
+ * retry.ts — shared retry helper with bounded exponential backoff + jitter.
+ */
+export interface RetryOptions {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
+}
+export declare function retryWithJitter<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/retry.js

@@ -0,0 +1,34 @@
+/**
+ * retry.ts — shared retry helper with bounded exponential backoff + jitter.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function computeDelayMs(attempt, baseDelayMs, maxDelayMs) {
+    const exponential = Math.min(baseDelayMs * (2 ** (attempt - 1)), maxDelayMs);
+    const jitterMultiplier = 0.5 + (Math.random() * 0.5);
+    return Math.round(exponential * jitterMultiplier);
+}
+export async function retryWithJitter(fn, options = {}) {
+    const maxAttempts = options.maxAttempts ?? 3;
+    const baseDelayMs = options.baseDelayMs ?? 250;
+    const maxDelayMs = options.maxDelayMs ?? 3_000;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            const isLastAttempt = attempt >= maxAttempts;
+            const canRetry = options.shouldRetry ? options.shouldRetry(error, attempt) : true;
+            if (isLastAttempt || !canRetry) {
+                throw error;
+            }
+            const delayMs = computeDelayMs(attempt, baseDelayMs, maxDelayMs);
+            options.onRetry?.(error, attempt, delayMs);
+            await sleep(delayMs);
+        }
+    }
+    throw lastError;
+}

package/dist/safe-json.d.ts

@@ -0,0 +1,12 @@
+import type { ZodType } from 'zod';
+export type SafeJsonResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+};
+/** Parse JSON without throwing and return a contextual error message. */
+export declare function safeJsonParse(raw: string, context?: string): SafeJsonResult<unknown>;
+/** Parse JSON and validate the resulting structure with a Zod schema. */
+export declare function safeJsonParseSchema<T>(raw: string, schema: ZodType<T>, context?: string): SafeJsonResult<T>;

package/dist/safe-json.js

@@ -0,0 +1,22 @@
+import { getErrorMessage } from './validation.js';
+/** Parse JSON without throwing and return a contextual error message. */
+export function safeJsonParse(raw, context = 'JSON payload') {
+    try {
+        return { ok: true, data: JSON.parse(raw) };
+    }
+    catch (err) {
+        return { ok: false, error: `${context} is not valid JSON: ${getErrorMessage(err)}` };
+    }
+}
+/** Parse JSON and validate the resulting structure with a Zod schema. */
+export function safeJsonParseSchema(raw, schema, context = 'JSON payload') {
+    const parsed = safeJsonParse(raw, context);
+    if (!parsed.ok)
+        return parsed;
+    const validated = schema.safeParse(parsed.data);
+    if (!validated.success) {
+        const reason = validated.error.issues.map(i => i.message).join(', ');
+        return { ok: false, error: `${context} has invalid structure: ${reason}` };
+    }
+    return { ok: true, data: validated.data };
+}

package/dist/screenshot.d.ts

@@ -0,0 +1,28 @@
+/**
+ * screenshot.ts — Headless screenshot capture via Playwright.
+ *
+ * Issue #22: Visual verification for CC sessions.
+ * Uses Playwright if available; returns 501 Not Implemented otherwise.
+ */
+export interface ScreenshotOptions {
+    url: string;
+    fullPage?: boolean;
+    width?: number;
+    height?: number;
+    /** Chromium --host-resolver-rules value to pin DNS (prevents TOCTOU rebinding). */
+    hostResolverRule?: string;
+}
+export interface ScreenshotResult {
+    screenshot: string;
+    timestamp: string;
+    url: string;
+    width: number;
+    height: number;
+}
+/**
+ * Capture a screenshot of the given URL using headless Chromium.
+ * Returns the result or throws if Playwright is not available.
+ */
+export declare function captureScreenshot(opts: ScreenshotOptions): Promise<ScreenshotResult>;
+/** Check if Playwright is available for screenshot capture. */
+export declare function isPlaywrightAvailable(): boolean;

package/dist/screenshot.js

@@ -0,0 +1,60 @@
+/**
+ * screenshot.ts — Headless screenshot capture via Playwright.
+ *
+ * Issue #22: Visual verification for CC sessions.
+ * Uses Playwright if available; returns 501 Not Implemented otherwise.
+ */
+let playwrightAvailable = false;
+let chromium = null;
+// Lazy-load Playwright — only fails at startup, not import time
+try {
+    const pw = await import('playwright');
+    chromium = pw.chromium;
+    playwrightAvailable = true;
+}
+catch { /* playwright not installed — screenshot feature disabled */
+    playwrightAvailable = false;
+}
+/**
+ * Capture a screenshot of the given URL using headless Chromium.
+ * Returns the result or throws if Playwright is not available.
+ */
+export async function captureScreenshot(opts) {
+    if (!playwrightAvailable || !chromium) {
+        throw new Error('Playwright is not installed. Install it with: npx playwright install chromium && npm install -D playwright');
+    }
+    const launchOptions = { headless: true };
+    if (opts.hostResolverRule) {
+        launchOptions.args = [`--host-resolver-rules=${opts.hostResolverRule}`];
+    }
+    const browser = await chromium.launch(launchOptions);
+    try {
+        const context = await browser.newContext({
+            viewport: {
+                width: opts.width || 1280,
+                height: opts.height || 720,
+            },
+        });
+        const page = await context.newPage();
+        await page.goto(opts.url, { waitUntil: 'load', timeout: 30_000 });
+        const buffer = await page.screenshot({
+            fullPage: opts.fullPage || false,
+            type: 'png',
+        });
+        await context.close();
+        return {
+            screenshot: buffer.toString('base64'),
+            timestamp: new Date().toISOString(),
+            url: opts.url,
+            width: opts.width || 1280,
+            height: opts.height || 720,
+        };
+    }
+    finally {
+        await browser.close();
+    }
+}
+/** Check if Playwright is available for screenshot capture. */
+export function isPlaywrightAvailable() {
+    return playwrightAvailable;
+}