autokap 1.8.6 → 1.8.7

package/dist/version.js

@@ -1,5 +1,6 @@
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
+/** npm package version of the CLI, transmitted as the `x-autokap-cli-version` header. */
 export const APP_VERSION = pkg.version;
 //# sourceMappingURL=version.js.map

package/dist/video-narration-schema.d.ts

@@ -57,6 +57,8 @@ export declare const VideoIngestPayloadSchema: z.ZodObject<{
     program: z.ZodObject<{
         presetId: z.ZodString;
         programVersion: z.ZodNumber;
+        programSchemaVersion: z.ZodOptional<z.ZodNumber>;
+        engineVersion: z.ZodOptional<z.ZodNumber>;
         mediaMode: z.ZodEnum<{
             video: "video";
             clip: "clip";
@@ -167,6 +169,7 @@ export declare const VideoIngestPayloadSchema: z.ZodObject<{
                 domain: z.ZodString;
                 path: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>>;
+            scenario: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
         steps: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             url: z.ZodString;

package/dist/video-narration-schema.js

@@ -83,6 +83,9 @@ export const VideoNarrationOverlaySchema = z.object({
  *      match a `program.steps[*].stepId`.
  */
 export const VideoIngestPayloadSchema = z.object({
+    // Strict by design: this is a legacy compatibility-test ingest schema with no
+    // live consumer (test-only + barrel re-export), so it validates the raw form
+    // without migrate-on-read. Live program validation goes through parseProgram.
     program: ExecutionProgramSchema,
     narration: VideoNarrationOverlaySchema.optional(),
 }).strict().superRefine((value, ctx) => {

package/dist/wait-contract.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Capture Agent — Wait Contract (AUT-240)
+ *
+ * Single source of truth for the engine's adaptive waiting behaviour. Zero user
+ * configuration: every budget/deadline below is an internal constant. Versioned
+ * (`WAIT_CONTRACT_VERSION`) so runs can be debugged and future migrations
+ * reasoned about; the global engine-versioning infrastructure is a separate
+ * effort.
+ *
+ * The model has three layers (see the AUT-240 issue):
+ *  - Layer A — actionability & semantic postconditions.
+ *  - Layer B — `waitForVisuallyStable` (screenshot stabilization).
+ *  - Layer C — dynamic budgets: a wait extends while the page is making progress
+ *    (network / DOM) and is cut once it is genuinely stuck, up to a hard
+ *    per-media global deadline. This is the real cure for the engine's #1 pain —
+ *    a slow-but-progressing page no longer trips a fixed timeout.
+ */
+import type { MediaMode, ProgressSnapshot } from './execution-types.js';
+/** Bump when the wait semantics change in a way worth tracing on a run. */
+export declare const WAIT_CONTRACT_VERSION = 1;
+/**
+ * Hard ceiling on adaptive waiting, per media mode. Applied as a FLOOR via
+ * `max()` with the compiled opcode timeout (see `resolveGlobalWaitDeadlineMs`)
+ * so it never shortens an intentionally-long opcode (`SLEEP`, `END_CLIP`).
+ */
+export declare const GLOBAL_WAIT_CAP_MS: Record<MediaMode, number>;
+/** No observed progress for this long ⇒ the wait is "stuck" and gets cut. */
+export declare const STUCK_WINDOW_MS = 4000;
+/** Watchdog poll cadence while a wait is in flight. */
+export declare const PROGRESS_POLL_INTERVAL_MS = 250;
+/**
+ * A timed-out wait cannot be cancelled through the adapter API. Before recovery
+ * or the next opcode starts, give the orphaned operation this long to settle so
+ * it does not mutate the page concurrently. Mirrors the runner's drain.
+ */
+export declare const ORPHAN_DRAIN_MS = 2000;
+/** DOM-quiet settle window for visual stabilization (Layer B). */
+export declare const DOM_QUIET_WINDOW_MS = 250;
+/** Bounded pixel-convergence fallback (Layer B). */
+export declare const PIXEL_FALLBACK_MAX_PASSES = 3;
+export declare const PIXEL_FALLBACK_DIFF_THRESHOLD = 0.01;
+/**
+ * Resolve the per-opcode global wait deadline (absolute ms timestamp).
+ * `compiledTimeoutMs` is the opcode's compiled `timeoutMs` — treated as a FLOOR,
+ * never a ceiling, so the deadline can only ever be extended past the compiled
+ * value, never shortened below it.
+ */
+export declare function resolveGlobalWaitDeadlineMs(startedAtMs: number, compiledTimeoutMs: number, mediaMode: MediaMode): number;
+/**
+ * Did the page make observable progress between two snapshots? Any of: a
+ * navigation in flight, new network events, in-flight count change, network
+ * activity advancing, readyState change, or DOM node-count change. A null
+ * current reading is treated conservatively as "no progress"; the first real
+ * reading (null `prev`) counts as progress to seed the watchdog window.
+ *
+ * The network fields are first-party-scoped at the source (see
+ * `getProgressSnapshot` / `isFirstPartyUrl`): background third-party telemetry
+ * (analytics beacons, ad pixels, polling to other origins) is excluded, so it
+ * cannot keep this `true` forever and starve the stuck-cut.
+ */
+export declare function hasProgress(prev: ProgressSnapshot | null | undefined, cur: ProgressSnapshot | null | undefined): boolean;
+export type ProgressBudgetCut = 'stuck' | 'deadline';
+export interface ProgressBudgetOptions {
+    /** `Date.now()` when the surrounding opcode started (for elapsed/min-budget). */
+    startedAtMs: number;
+    /** Absolute hard deadline — the wait never runs past this. */
+    globalDeadlineMs: number;
+    /**
+     * Minimum patience (the compiled `timeoutMs` floor) before the stuck-cut may
+     * fire. A slow page that produces no early signal still gets at least this
+     * long before being judged stuck.
+     */
+    minBudgetMs: number;
+    /** No-progress window before cutting "stuck". Defaults to `STUCK_WINDOW_MS`. */
+    stuckWindowMs?: number;
+    /** Watchdog cadence. Defaults to `PROGRESS_POLL_INTERVAL_MS`. */
+    pollIntervalMs?: number;
+    /**
+     * Progress probe. When omitted, the stuck-cut is disabled and the operation
+     * simply runs with its compiled floor budget (legacy fixed-timeout behaviour)
+     * — graceful degradation for adapters with no progress signal.
+     */
+    getProgress?: () => Promise<ProgressSnapshot | null>;
+}
+export interface ProgressBudgetResult<T> {
+    /** Present when the wrapped operation resolved before any cut. */
+    result?: T;
+    /** Present when the watchdog cut the wait early. */
+    cut?: ProgressBudgetCut;
+    /** Total time spent (ms). */
+    waitedMs: number;
+}
+/**
+ * Run an adaptive wait that extends while the page is making progress and is cut
+ * once it is genuinely stuck or the global deadline is reached.
+ *
+ * `run(budgetMs)` is given a generous budget (up to the global deadline) and is
+ * expected to resolve as soon as its condition is met (or to time out at the
+ * budget). A concurrent watchdog races it: while `run` is still pending, the
+ * watchdog cuts the wait if no progress is observed for `stuckWindowMs` (after
+ * `minBudgetMs` has elapsed) or once the global deadline passes. If `run`
+ * resolves first, its result is returned and the watchdog is moot.
+ */
+export declare function runWithProgressBudget<T>(run: (budgetMs: number) => Promise<T>, options: ProgressBudgetOptions): Promise<ProgressBudgetResult<T>>;

package/dist/wait-contract.js

@@ -0,0 +1,144 @@
+/**
+ * Capture Agent — Wait Contract (AUT-240)
+ *
+ * Single source of truth for the engine's adaptive waiting behaviour. Zero user
+ * configuration: every budget/deadline below is an internal constant. Versioned
+ * (`WAIT_CONTRACT_VERSION`) so runs can be debugged and future migrations
+ * reasoned about; the global engine-versioning infrastructure is a separate
+ * effort.
+ *
+ * The model has three layers (see the AUT-240 issue):
+ *  - Layer A — actionability & semantic postconditions.
+ *  - Layer B — `waitForVisuallyStable` (screenshot stabilization).
+ *  - Layer C — dynamic budgets: a wait extends while the page is making progress
+ *    (network / DOM) and is cut once it is genuinely stuck, up to a hard
+ *    per-media global deadline. This is the real cure for the engine's #1 pain —
+ *    a slow-but-progressing page no longer trips a fixed timeout.
+ */
+/** Bump when the wait semantics change in a way worth tracing on a run. */
+export const WAIT_CONTRACT_VERSION = 1;
+/**
+ * Hard ceiling on adaptive waiting, per media mode. Applied as a FLOOR via
+ * `max()` with the compiled opcode timeout (see `resolveGlobalWaitDeadlineMs`)
+ * so it never shortens an intentionally-long opcode (`SLEEP`, `END_CLIP`).
+ */
+export const GLOBAL_WAIT_CAP_MS = {
+    screenshot: 30_000,
+    clip: 45_000,
+    video: 60_000,
+};
+/** No observed progress for this long ⇒ the wait is "stuck" and gets cut. */
+export const STUCK_WINDOW_MS = 4_000;
+/** Watchdog poll cadence while a wait is in flight. */
+export const PROGRESS_POLL_INTERVAL_MS = 250;
+/**
+ * A timed-out wait cannot be cancelled through the adapter API. Before recovery
+ * or the next opcode starts, give the orphaned operation this long to settle so
+ * it does not mutate the page concurrently. Mirrors the runner's drain.
+ */
+export const ORPHAN_DRAIN_MS = 2_000;
+/** DOM-quiet settle window for visual stabilization (Layer B). */
+export const DOM_QUIET_WINDOW_MS = 250;
+/** Bounded pixel-convergence fallback (Layer B). */
+export const PIXEL_FALLBACK_MAX_PASSES = 3;
+export const PIXEL_FALLBACK_DIFF_THRESHOLD = 0.01;
+/**
+ * Resolve the per-opcode global wait deadline (absolute ms timestamp).
+ * `compiledTimeoutMs` is the opcode's compiled `timeoutMs` — treated as a FLOOR,
+ * never a ceiling, so the deadline can only ever be extended past the compiled
+ * value, never shortened below it.
+ */
+export function resolveGlobalWaitDeadlineMs(startedAtMs, compiledTimeoutMs, mediaMode) {
+    const cap = GLOBAL_WAIT_CAP_MS[mediaMode] ?? GLOBAL_WAIT_CAP_MS.screenshot;
+    return startedAtMs + Math.max(compiledTimeoutMs, cap);
+}
+/**
+ * Did the page make observable progress between two snapshots? Any of: a
+ * navigation in flight, new network events, in-flight count change, network
+ * activity advancing, readyState change, or DOM node-count change. A null
+ * current reading is treated conservatively as "no progress"; the first real
+ * reading (null `prev`) counts as progress to seed the watchdog window.
+ *
+ * The network fields are first-party-scoped at the source (see
+ * `getProgressSnapshot` / `isFirstPartyUrl`): background third-party telemetry
+ * (analytics beacons, ad pixels, polling to other origins) is excluded, so it
+ * cannot keep this `true` forever and starve the stuck-cut.
+ */
+export function hasProgress(prev, cur) {
+    if (!cur)
+        return false;
+    if (cur.navigating)
+        return true;
+    if (!prev)
+        return true;
+    return (cur.networkEventCount !== prev.networkEventCount
+        || cur.inflightRequests !== prev.inflightRequests
+        || cur.lastNetworkActivityAtMs !== prev.lastNetworkActivityAtMs
+        || cur.readyState !== prev.readyState
+        || cur.domNodeCount !== prev.domNodeCount);
+}
+/**
+ * Run an adaptive wait that extends while the page is making progress and is cut
+ * once it is genuinely stuck or the global deadline is reached.
+ *
+ * `run(budgetMs)` is given a generous budget (up to the global deadline) and is
+ * expected to resolve as soon as its condition is met (or to time out at the
+ * budget). A concurrent watchdog races it: while `run` is still pending, the
+ * watchdog cuts the wait if no progress is observed for `stuckWindowMs` (after
+ * `minBudgetMs` has elapsed) or once the global deadline passes. If `run`
+ * resolves first, its result is returned and the watchdog is moot.
+ */
+export async function runWithProgressBudget(run, options) {
+    const { startedAtMs, globalDeadlineMs, minBudgetMs, stuckWindowMs = STUCK_WINDOW_MS, pollIntervalMs = PROGRESS_POLL_INTERVAL_MS, getProgress, } = options;
+    // No progress signal ⇒ behave like a plain bounded wait (legacy behaviour):
+    // give the operation its compiled floor budget, no extension, no stuck-cut.
+    if (!getProgress) {
+        const budget = Math.max(1, minBudgetMs);
+        const result = await run(budget);
+        return { result, waitedMs: Date.now() - startedAtMs };
+    }
+    const budget = Math.max(1, globalDeadlineMs - Date.now());
+    const runPromise = Promise.resolve().then(() => run(budget));
+    let cut = null;
+    let stop = false;
+    const watchdog = (async () => {
+        let prev = await getProgress().catch(() => null);
+        let lastProgressAt = Date.now();
+        while (!stop) {
+            await sleep(pollIntervalMs);
+            if (stop)
+                return;
+            const now = Date.now();
+            if (now >= globalDeadlineMs) {
+                cut = 'deadline';
+                return;
+            }
+            const cur = await getProgress().catch(() => prev);
+            if (hasProgress(prev, cur)) {
+                lastProgressAt = now;
+                prev = cur;
+            }
+            const elapsed = now - startedAtMs;
+            if (elapsed >= minBudgetMs && now - lastProgressAt >= stuckWindowMs) {
+                cut = 'stuck';
+                return;
+            }
+        }
+    })();
+    const settled = await Promise.race([
+        runPromise.then((value) => ({ kind: 'run', value })),
+        watchdog.then(() => ({ kind: 'watchdog' })),
+    ]);
+    stop = true;
+    if (settled.kind === 'run') {
+        return { result: settled.value, waitedMs: Date.now() - startedAtMs };
+    }
+    // Watchdog cut the wait early: drain the orphan so it does not mutate the page
+    // concurrently with recovery or the next opcode.
+    await Promise.race([runPromise.catch(() => undefined), sleep(ORPHAN_DRAIN_MS)]);
+    return { cut: cut ?? 'stuck', waitedMs: Date.now() - startedAtMs };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=wait-contract.js.map

package/dist/web-playwright-local.d.ts

@@ -6,7 +6,7 @@
  */
 import type { Browser } from './browser.js';
 import type { AKTree, OutscaleConfig, VideoPageSignals } from './types.js';
-import type { RuntimeAdapter, ClickOptions, WaitCondition, RecordingOptions, RecordingResult, SemanticTarget } from './execution-types.js';
+import type { RuntimeAdapter, ClickOptions, WaitCondition, RecordingOptions, RecordingResult, SemanticTarget, ProgressSnapshot, VisualStabilityResult } from './execution-types.js';
 import { type ResolveOptions } from './semantic-resolver.js';
 export declare class WebPlaywrightLocal implements RuntimeAdapter {
     private browser;
@@ -28,6 +28,8 @@ export declare class WebPlaywrightLocal implements RuntimeAdapter {
     navigate(url: string): Promise<void>;
     getCurrentUrl(): Promise<string>;
     getPageTitle(): Promise<string | null>;
+    /** AUT-240 (Layer A): live text of the first match, for text_contains. */
+    getTextContent(selector: string): Promise<string | null>;
     detectAppVersion(): Promise<string | null>;
     getAKTree(): Promise<AKTree>;
     getPageSignals(): Promise<VideoPageSignals>;
@@ -60,6 +62,12 @@ export declare class WebPlaywrightLocal implements RuntimeAdapter {
     scroll(direction: 'up' | 'down' | 'left' | 'right', amount?: number): Promise<void>;
     scrollIntoView(selector: string): Promise<void>;
     waitFor(condition: WaitCondition): Promise<boolean>;
+    /** AUT-240 (Layer C): cheap page-activity snapshot for the progress watchdog. */
+    getProgressSnapshot(): Promise<ProgressSnapshot>;
+    /** AUT-240 (Layer B): wait for the page to be visually stable before capture. */
+    waitForVisuallyStable(options?: {
+        maxWaitMs?: number;
+    }): Promise<VisualStabilityResult>;
     dismissOverlays(): Promise<{
         dismissed: boolean;
         method: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autokap",
-  "version": "1.8.6",
+  "version": "1.8.7",
   "description": "AI-powered CLI tool for capturing clean screenshots of websites",
   "type": "module",
   "main": "./dist/index.js",
@@ -224,7 +224,7 @@
     "commander": "^14.0.3",
     "dotenv": "^17.3.1",
     "openai": "^6.25.0",
-    "playwright": "^1.58.2",
+    "playwright": "^1.61.0",
     "posthog-node": "^5.26.2",
     "sharp": "^0.34.5",
     "@resvg/resvg-js": "^2.6.2",