autokap 1.9.8 → 1.9.10

package/dist/browser-pool.d.ts

@@ -2,6 +2,23 @@ import { type BrowserContext } from 'playwright';
 import type { BrowserStorageState } from './types.js';
 /** Chromium flags for server-side headless operation (used by pool and standalone launches). */
 export declare const CHROMIUM_ARGS: string[];
+/**
+ * Cloud Run NVIDIA L4 GPU launch flags for HEADLESS screenshot capture. Returns
+ * null off Cloud Run (Vercel/local have no GPU → keep software rasterization).
+ *
+ * The clip path (Browser.forClipCapture) proves the L4 binds via ANGLE/Vulkan on
+ * this image; screenshots don't need Xvfb (no ffmpeg x11grab), so we use Chromium
+ * NEW headless (`--headless=new` — the OLD `--headless` has no GPU) and strip
+ * Playwright's default `--headless` so the two don't clash. Verify the binding
+ * with the `[gpu-check]` log below: "NVIDIA"/"ANGLE (NVIDIA…)" = hardware,
+ * "SwiftShader"/"llvmpipe" = it fell back to software (then we'd need Xvfb).
+ * The GPU accelerates page render/composite (the win for animated/blur-heavy
+ * pages); the final PNG encode stays CPU-bound.
+ */
+export declare function resolveCloudGpuLaunch(): {
+    args: string[];
+    ignoreDefaultArgs: string[];
+} | null;
 declare class BrowserPool {
     private browser;
     private launchPromise;

package/dist/browser-pool.js

@@ -48,6 +48,72 @@ export const CHROMIUM_ARGS = [
 const MAX_CONCURRENT = parseInt(process.env.BROWSER_POOL_MAX_CONCURRENT ?? '5', 10);
 /** Restart the shared browser process after this many captures to prevent memory leaks. */
 const MAX_CAPTURES_BEFORE_RESTART = 100;
+/**
+ * Default per-action Playwright timeout for pooled contexts. Below the 30s
+ * CAPTURE_SCREENSHOT global deadline so a starved call fails with budget left
+ * for recovery instead of eating the whole variant. See usage in acquireContext.
+ */
+const POOL_CONTEXT_ACTION_TIMEOUT_MS = 25000;
+/**
+ * Cloud Run NVIDIA L4 GPU launch flags for HEADLESS screenshot capture. Returns
+ * null off Cloud Run (Vercel/local have no GPU → keep software rasterization).
+ *
+ * The clip path (Browser.forClipCapture) proves the L4 binds via ANGLE/Vulkan on
+ * this image; screenshots don't need Xvfb (no ffmpeg x11grab), so we use Chromium
+ * NEW headless (`--headless=new` — the OLD `--headless` has no GPU) and strip
+ * Playwright's default `--headless` so the two don't clash. Verify the binding
+ * with the `[gpu-check]` log below: "NVIDIA"/"ANGLE (NVIDIA…)" = hardware,
+ * "SwiftShader"/"llvmpipe" = it fell back to software (then we'd need Xvfb).
+ * The GPU accelerates page render/composite (the win for animated/blur-heavy
+ * pages); the final PNG encode stays CPU-bound.
+ */
+export function resolveCloudGpuLaunch() {
+    const isCloudRunner = process.env.AUTOKAP_CLOUD_RUNNER === '1';
+    if (process.platform !== 'linux' || !isCloudRunner)
+        return null;
+    return {
+        args: [
+            '--headless=new',
+            '--use-gl=angle',
+            '--use-angle=vulkan',
+            '--enable-features=Vulkan',
+            '--ignore-gpu-blocklist',
+            '--enable-gpu-rasterization',
+            '--enable-zero-copy',
+        ],
+        ignoreDefaultArgs: ['--headless'],
+    };
+}
+/** Log the active WebGL renderer once per pooled browser launch so a Cloud Run
+ *  deploy can confirm the L4 bound (NVIDIA) vs a silent SwiftShader fallback. */
+async function logPoolGpuRenderer(browser) {
+    try {
+        const context = await browser.newContext();
+        try {
+            const page = await context.newPage();
+            const info = await page.evaluate(() => {
+                const canvas = document.createElement('canvas');
+                const gl = (canvas.getContext('webgl2') || canvas.getContext('webgl'));
+                if (!gl)
+                    return { error: 'no webgl context' };
+                const ext = gl.getExtension('WEBGL_debug_renderer_info');
+                if (!ext)
+                    return { error: 'no debug_renderer_info extension' };
+                return {
+                    vendor: gl.getParameter(ext.UNMASKED_VENDOR_WEBGL),
+                    renderer: gl.getParameter(ext.UNMASKED_RENDERER_WEBGL),
+                };
+            });
+            console.info('[gpu-check] pool WebGL renderer:', JSON.stringify(info));
+        }
+        finally {
+            await context.close();
+        }
+    }
+    catch (err) {
+        console.warn('[gpu-check] pool WebGL query failed:', err.message);
+    }
+}
 function normalizeDeviceScaleFactor(value) {
     if (!Number.isFinite(value))
         return 2;
@@ -79,6 +145,12 @@ class BrowserPool {
             // any conflict). See PRIVACY_HEADERS / installAnalyticsBlock (AUT-234).
             extraHTTPHeaders: { ...PRIVACY_HEADERS, ...(extra ?? {}) },
         });
+        // Stop every Playwright call from inheriting the built-in 30 000 ms default.
+        // Pooled captures run many variants per Cloud Run container; under CPU
+        // contention a starved call (e.g. page.screenshot) would otherwise block the
+        // full 30s — equal to the CAPTURE_SCREENSHOT global deadline — leaving no
+        // budget for recovery and voiding the variant. 25s sits under that cap.
+        context.setDefaultTimeout(POOL_CONTEXT_ACTION_TIMEOUT_MS);
         // Block third-party analytics so pooled (server-side) captures don't
         // register a phantom visit in the captured site's analytics (AUT-234).
         // Skippable per-project via blockAnalytics === false.
@@ -122,7 +194,24 @@ class BrowserPool {
         await this.launchPromise;
     }
     async launchBrowser() {
-        this.browser = await chromium.launch({ headless: true, args: CHROMIUM_ARGS });
+        const gpu = resolveCloudGpuLaunch();
+        if (gpu) {
+            // Cloud Run L4: drop the software-only flags and enable Vulkan/ANGLE GPU
+            // rasterization for headless screenshot capture, mirroring the clip path.
+            const args = [
+                ...CHROMIUM_ARGS.filter((a) => a !== '--disable-gpu' && a !== '--disable-gpu-sandbox'),
+                ...gpu.args,
+            ];
+            this.browser = await chromium.launch({
+                headless: true,
+                ignoreDefaultArgs: gpu.ignoreDefaultArgs,
+                args,
+            });
+            await logPoolGpuRenderer(this.browser);
+        }
+        else {
+            this.browser = await chromium.launch({ headless: true, args: CHROMIUM_ARGS });
+        }
         this.captureCount = 0;
         this.browser.on('disconnected', () => {
             // Browser crashed — active contexts are now dead, they'll throw naturally

package/dist/browser.js

@@ -209,6 +209,31 @@ async function seedCloudChromiumPreferences(userDataDir) {
     };
     await writeFile(preferencesPath, `${JSON.stringify(preferences)}\n`, 'utf8');
 }
+/**
+ * Default per-action timeout applied to every Playwright context we create.
+ * Without this, calls (page.screenshot / page.title / locator actions) inherit
+ * Playwright's built-in 30 000 ms default. Under Cloud Run CPU contention (many
+ * variants per container) a single starved call would then block for the full
+ * 30s — which equals the CAPTURE_SCREENSHOT global deadline, leaving zero budget
+ * for recovery/recapture and voiding the whole variant. 25s sits just under that
+ * global cap so a hung call fails with budget left for a clean, bounded error.
+ * NAVIGATE keeps its own bounded path — we intentionally do NOT touch
+ * navigationTimeout here.
+ */
+const CONTEXT_ACTION_TIMEOUT_MS = 25000;
+/**
+ * Explicit backstop for the heavy screenshot primitives. Sits just under the 45s
+ * global screenshot deadline and ABOVE the runner's reserved action budget
+ * (~global − recovery reserve), so the runner's per-attempt bound is the real
+ * control and this only catches a screenshot that has genuinely wedged. Must not
+ * be smaller than a legitimate slow high-res capture, or it would pre-empt the
+ * runner and fail captures that would have completed.
+ */
+const SCREENSHOT_PRIMITIVE_TIMEOUT_MS = 40000;
+/** Apply our engine-wide Playwright defaults to a freshly created context. */
+function applyContextDefaults(context) {
+    context.setDefaultTimeout(CONTEXT_ACTION_TIMEOUT_MS);
+}
 async function withHelperTimeout(label, timeoutMs, work) {
     if (!timeoutMs || timeoutMs <= 0) {
         return work();
@@ -1085,6 +1110,7 @@ export class Browser {
                 headless: false,
                 args: clipArgs,
             });
+            applyContextDefaults(instance.context);
             instance.browser = instance.context.browser();
             instance.persistentContext = true;
             // launchPersistentContext opens an initial about:blank page automatically.
@@ -1110,6 +1136,7 @@ export class Browser {
                 args: clipArgs,
             });
             instance.context = await instance.browser.newContext(contextOptions);
+            applyContextDefaults(instance.context);
         }
         // Block third-party analytics beacons so clip/video capture doesn't
         // register a phantom visit either (AUT-234). Context-level so it covers
@@ -1253,6 +1280,7 @@ export class Browser {
             args: CHROMIUM_ARGS,
         });
         this.context = await this.browser.newContext(this.buildContextOptions());
+        applyContextDefaults(this.context);
         if (this.options.blockAnalytics !== false) {
             await installAnalyticsBlock(this.context);
         }
@@ -1345,6 +1373,7 @@ export class Browser {
             this.context = null;
         }
         this.context = await this.browser.newContext(this.buildContextOptions());
+        applyContextDefaults(this.context);
         if (this.options.blockAnalytics !== false) {
             await installAnalyticsBlock(this.context);
         }
@@ -1840,7 +1869,7 @@ export class Browser {
         // terminal block where ANSI escape literals were producing tofu boxes).
         await stripInvisibleControlChars(page);
         await logFontDiagnostics(page, 'before screenshot');
-        const screenshot = Buffer.from(await page.screenshot({ type: 'png', fullPage: false }));
+        const screenshot = Buffer.from(await page.screenshot({ type: 'png', fullPage: false, timeout: SCREENSHOT_PRIMITIVE_TIMEOUT_MS }));
         await logCaptureRenderDiagnostics(page, screenshot, this.options, 'after screenshot');
         return screenshot;
     }
@@ -5330,7 +5359,7 @@ export class Browser {
         try {
             await this.waitForFontsBeforeScreenshot(page);
             await logFontDiagnostics(page, 'before region screenshot');
-            const fullPage = Buffer.from(await page.screenshot({ type: 'png', fullPage: true }));
+            const fullPage = Buffer.from(await page.screenshot({ type: 'png', fullPage: true, timeout: SCREENSHOT_PRIMITIVE_TIMEOUT_MS }));
             const image = sharp(fullPage);
             const meta = await image.metadata();
             const imageWidth = meta.width ?? 0;
@@ -5453,7 +5482,7 @@ export class Browser {
             const dpr = pageInfo.dpr;
             await this.waitForFontsBeforeScreenshot(page);
             await logFontDiagnostics(page, 'before selector screenshot');
-            const fullPage = Buffer.from(await page.screenshot({ type: 'png', fullPage: true }));
+            const fullPage = Buffer.from(await page.screenshot({ type: 'png', fullPage: true, timeout: SCREENSHOT_PRIMITIVE_TIMEOUT_MS }));
             const image = sharp(fullPage);
             const meta = await image.metadata();
             const imgW = meta.width ?? 0;
@@ -5517,7 +5546,7 @@ export class Browser {
             const dpr = pageInfo.dpr;
             await this.waitForFontsBeforeScreenshot(page);
             await logFontDiagnostics(page, 'before bounding-region screenshot');
-            const fullPage = Buffer.from(await page.screenshot({ type: 'png', fullPage: true }));
+            const fullPage = Buffer.from(await page.screenshot({ type: 'png', fullPage: true, timeout: SCREENSHOT_PRIMITIVE_TIMEOUT_MS }));
             const image = sharp(fullPage);
             const meta = await image.metadata();
             const imgW = meta.width ?? 0;

package/dist/cli-runner.js

@@ -209,7 +209,15 @@ export async function runCapture(options) {
     // serialize variants (CPU/RAM bound on the encoder side). Only 'screenshot'
     // honors the requested concurrency.
     const isRecordable = program.mediaMode === 'clip' || program.mediaMode === 'video';
-    const maxParallelVariants = isRecordable ? 1 : program.maxParallelCaptures;
+    // AUTOKAP_MAX_PARALLEL_CAPTURES lets the RUNTIME (e.g. the Cloud Run container)
+    // clamp per-run variant concurrency below what the server compiled, decoupled
+    // from billing/queue limits. Fewer concurrent captures = more CPU/GPU per
+    // capture on a shared L4 container. Unset/invalid → honor the compiled value.
+    const runtimeConcurrencyCap = Number.parseInt(process.env.AUTOKAP_MAX_PARALLEL_CAPTURES ?? '', 10);
+    const requestedConcurrency = Number.isFinite(runtimeConcurrencyCap) && runtimeConcurrencyCap > 0
+        ? Math.min(program.maxParallelCaptures ?? runtimeConcurrencyCap, runtimeConcurrencyCap)
+        : program.maxParallelCaptures;
+    const maxParallelVariants = isRecordable ? 1 : requestedConcurrency;
     // AUT-149: collect structured logs + progress events for export on failure.
     const logCollector = new LogCollector();
     logCollector.start();

package/dist/opcode-runner.js

@@ -55,6 +55,20 @@ export class NoOpRecoveryChain {
 }
 const MIN_CLIP_FINALIZATION_TIMEOUT_MS = 30000;
 const DEFAULT_VIDEO_RECORDING_RESOLUTION = { width: 1920, height: 1080 };
+/**
+ * Recovery budget reserved from the global capture deadline. The screenshot
+ * buffer (the artifact-critical call) may use the REST of the deadline, so a
+ * slow-but-completing high-res capture (e.g. a 5K device frame legitimately
+ * needing 15-30s under load) succeeds, while a truly hung one still fails with
+ * this slice left for the recovery/recapture path. Replaces the old flat 12s
+ * buffer cap, which was smaller than legitimate heavy captures and killed them
+ * (and killed the recapture too, since it re-applied the same 12s wall).
+ */
+const CAPTURE_RECOVERY_RESERVE_MS = 10000;
+/** Floor for the first-attempt capture budget when little global time remains. */
+const MIN_CAPTURE_ACTION_BUDGET_MS = 8000;
+/** Best-effort bound for browser-mockup metadata (URL / favicon / title). */
+const CAPTURE_METADATA_TIMEOUT_MS = 3000;
 /**
  * The compiled per-opcode action budget. For CAPTURE_SCREENSHOT this governs
  * ONLY the deterministic capture (visual stabilize + screenshot + favicon/title
@@ -463,9 +477,12 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
             error: `recovery succeeded but produced no ${opcode.kind === 'END_CLIP' ? 'clip' : 'screenshot'} artifact: ${reason}`,
         };
     };
-    // Track page context for circuit breaker
+    // Track page context for circuit breaker. Bounded + best-effort: this runs on
+    // EVERY opcode inside its global-deadline window, so a getCurrentUrl starved by
+    // CPU contention must not eat the budget the capture + recovery need (it would
+    // otherwise be capped only by the 25s context default).
     try {
-        const url = await adapter.getCurrentUrl();
+        const url = await withTimeout(() => adapter.getCurrentUrl(), CAPTURE_METADATA_TIMEOUT_MS);
         breaker.setPage(url);
     }
     catch { /* ignore */ }
@@ -498,7 +515,15 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
         const isPureWait = opcode.kind === 'WAIT_FOR';
         const usesGlobalDeadline = isPureWait || isArtifactProducingOpcode(opcode.kind);
         const actionDeadlineMs = usesGlobalDeadline ? globalDeadlineMs : deadlineMs;
-        const actionBudgetMs = getRemainingTimeMs(actionDeadlineMs);
+        let actionBudgetMs = getRemainingTimeMs(actionDeadlineMs);
+        // Reserve a slice of the global deadline for recovery/recapture on the
+        // artifact-critical CAPTURE_SCREENSHOT: the capture uses the rest (so a slow
+        // high-res shot completes) yet a hung one still leaves room to recover.
+        // END_CLIP keeps its full budget — its finalization hard-fails without a
+        // recapture, so reserving would only shorten it.
+        if (opcode.kind === 'CAPTURE_SCREENSHOT') {
+            actionBudgetMs = Math.max(MIN_CAPTURE_ACTION_BUDGET_MS, actionBudgetMs - CAPTURE_RECOVERY_RESERVE_MS);
+        }
         if (actionBudgetMs <= 0) {
             const reason = `timeout after ${effectiveTimeoutMs}ms`;
             logger.debug(`[opcode ${index}] no budget left after captureBeforeState (deadline=${actionDeadlineMs}, now=${Date.now()})`);
@@ -879,25 +904,43 @@ async function executeOpcodeAction(opcode, opcodeIndex, adapter, artifacts, tele
                     lowConfidenceReasons.push(`captured before visual stability: ${stability.reason}`);
                 }
                 const captureLowConfidenceReason = lowConfidenceReasons.join('; ') || undefined;
-                const captureUrl = await adapter.getCurrentUrl();
+                // Capture the screenshot buffer FIRST — the only artifact-critical call.
+                // It is bounded by the reserved action budget (the withTimeout around this
+                // whole action in executeOpcode) and the screenshot primitive's own
+                // timeout — NOT a flat sub-cap — so a legitimately slow high-res capture
+                // can use most of the deadline while a hung one still frees the reserved
+                // recovery slice (handleFailure → recapture in `failWithRecovery`).
                 const buffer = await takeCaptureBuffer(adapter, opcode);
-                // Extract page favicon for browser bar mockup
+                // Everything below is best-effort browser-mockup metadata. The buffer is
+                // already in hand, so a slow/hung metadata call must NEVER throw out of
+                // the action and discard a good screenshot. Each is individually bounded
+                // and degrades gracefully (empty URL / no favicon / hostname title).
+                let captureUrl = '';
+                try {
+                    captureUrl = await withTimeout(() => adapter.getCurrentUrl(), CAPTURE_METADATA_TIMEOUT_MS);
+                }
+                catch { /* empty captureUrl is tolerated downstream */ }
                 let tabIconData;
                 let tabIconMimeType;
                 if (adapter.extractFavicon) {
-                    const favicon = await adapter.extractFavicon();
-                    if (favicon) {
-                        tabIconData = favicon.buffer;
-                        tabIconMimeType = favicon.mimeType;
+                    try {
+                        const favicon = await withTimeout(() => adapter.extractFavicon(), CAPTURE_METADATA_TIMEOUT_MS);
+                        if (favicon) {
+                            tabIconData = favicon.buffer;
+                            tabIconMimeType = favicon.mimeType;
+                        }
                     }
+                    catch { /* ship the screenshot without a favicon */ }
                 }
-                // Capture document title so browser mockups can render the real tab
-                // title instead of falling back to the hostname.
+                // Real tab title for the browser mockup; falls back to hostname when null.
                 let pageTitle;
                 if (adapter.getPageTitle) {
-                    const resolved = await adapter.getPageTitle();
-                    if (resolved)
-                        pageTitle = resolved;
+                    try {
+                        const resolved = await withTimeout(() => adapter.getPageTitle(), CAPTURE_METADATA_TIMEOUT_MS);
+                        if (resolved)
+                            pageTitle = resolved;
+                    }
+                    catch { /* fall back to the hostname mockup */ }
                 }
                 artifacts.push({
                     mediaMode: 'screenshot',

package/dist/wait-contract.js

@@ -23,7 +23,10 @@ export const WAIT_CONTRACT_VERSION = 1;
  * so it never shortens an intentionally-long opcode (`SLEEP`, `END_CLIP`).
  */
 export const GLOBAL_WAIT_CAP_MS = {
-    screenshot: 30_000,
+    // Heavy high-res captures (5K device frames, retina, animated pages) can take
+    // 15-30s under cloud CPU load with software rasterization. 45s gives them room
+    // to complete (and to reserve a recovery slice) instead of failing prematurely.
+    screenshot: 45_000,
     clip: 45_000,
     video: 60_000,
 };

package/dist/web-playwright-local.js

@@ -194,7 +194,15 @@ export class WebPlaywrightLocal {
     async getPageTitle() {
         const page = await this.browser.currentPage;
         try {
-            const raw = await page.title();
+            // Metadata for the browser-mockup tab, not the artifact itself. page.title()
+            // takes no timeout and inherits Playwright's 30s default; under CPU
+            // contention (Cloud Run) it can swallow the whole capture action budget
+            // AFTER the screenshot buffer was already produced, discarding a good shot.
+            // Bound it tightly and degrade to the hostname fallback (null) on timeout.
+            const raw = await Promise.race([
+                page.title(),
+                new Promise((resolve) => setTimeout(() => resolve(null), 2000)),
+            ]);
             const trimmed = raw?.trim();
             if (!trimmed)
                 return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autokap",
-  "version": "1.9.8",
+  "version": "1.9.10",
   "description": "AI-powered CLI tool for capturing clean screenshots of websites",
   "type": "module",
   "main": "./dist/index.js",