autokap 1.8.6 → 1.8.7

package/dist/postcondition.d.ts

@@ -4,13 +4,28 @@
  * Deterministic evaluation of postconditions after each opcode.
  * No LLM calls — purely structural checks against AKTree, URL, and screenshots.
  */
-import type { RuntimeAdapter, PostconditionSpec } from './execution-types.js';
+import type { RuntimeAdapter, PostconditionSpec, ProgressSnapshot } from './execution-types.js';
 /**
  * Evaluates whether a postcondition holds.
  * Retries internally up to postcondition.waitMs (polling).
  * Returns true if the condition is satisfied, false otherwise.
  */
-export declare function evaluatePostcondition(adapter: RuntimeAdapter, spec: PostconditionSpec): Promise<{
+export interface PostconditionResult {
     passed: boolean;
     reason: string;
-}>;
+    /**
+     * AUT-240 (decision 2): the check could not be verified deterministically
+     * (an AKTree probe kept throwing) and was assumed-OK as a last resort. The
+     * capture is flagged low-confidence rather than failed.
+     */
+    lowConfidence?: boolean;
+}
+export declare function evaluatePostcondition(adapter: RuntimeAdapter, spec: PostconditionSpec): Promise<PostconditionResult>;
+/**
+ * Evaluate a postcondition with extend-on-progress (AUT-240, Layer C): the poll
+ * gets a generous budget up to the global deadline and the progress watchdog
+ * cuts it only when the page is genuinely stuck. Replaces the old clamp-to-
+ * remaining-budget that could starve the check to ~1ms after a slow action.
+ * Shared by the runner (main path) and the recovery chain (retry re-check).
+ */
+export declare function evaluatePostconditionWithProgress(adapter: RuntimeAdapter, spec: PostconditionSpec, startedAtMs: number, globalDeadlineMs: number, getProgress: (() => Promise<ProgressSnapshot | null>) | undefined): Promise<PostconditionResult>;

package/dist/postcondition.js

@@ -4,12 +4,7 @@
  * Deterministic evaluation of postconditions after each opcode.
  * No LLM calls — purely structural checks against AKTree, URL, and screenshots.
  */
-import { serializeAKTree } from './ak-tree.js';
-/**
- * Evaluates whether a postcondition holds.
- * Retries internally up to postcondition.waitMs (polling).
- * Returns true if the condition is satisfied, false otherwise.
- */
+import { runWithProgressBudget } from './wait-contract.js';
 export async function evaluatePostcondition(adapter, spec) {
     const maxWait = spec.waitMs ?? 5000;
     const pollInterval = 500;
@@ -31,6 +26,29 @@ export async function evaluatePostcondition(adapter, spec) {
     // Final check after timeout
     return checkOnce(adapter, spec, context);
 }
+/**
+ * Evaluate a postcondition with extend-on-progress (AUT-240, Layer C): the poll
+ * gets a generous budget up to the global deadline and the progress watchdog
+ * cuts it only when the page is genuinely stuck. Replaces the old clamp-to-
+ * remaining-budget that could starve the check to ~1ms after a slow action.
+ * Shared by the runner (main path) and the recovery chain (retry re-check).
+ */
+export async function evaluatePostconditionWithProgress(adapter, spec, startedAtMs, globalDeadlineMs, getProgress) {
+    // Immediate specs need no adaptive budget.
+    if (spec.type === 'always') {
+        return evaluatePostcondition(adapter, spec);
+    }
+    const compiledWaitMs = spec.waitMs ?? 5000;
+    const waited = await runWithProgressBudget((budgetMs) => evaluatePostcondition(adapter, { ...spec, waitMs: Math.max(1, Math.round(budgetMs)) }), { startedAtMs, globalDeadlineMs, minBudgetMs: compiledWaitMs, getProgress });
+    if (waited.result)
+        return waited.result;
+    return {
+        passed: false,
+        reason: waited.cut === 'stuck'
+            ? `not met (page stuck, no progress for ${Math.round(waited.waitedMs)}ms)`
+            : 'not met (global wait deadline reached)',
+    };
+}
 async function checkOnce(adapter, spec, context) {
     switch (spec.type) {
         case 'route_matches':
@@ -117,16 +135,15 @@ async function checkElementVisible(adapter, selector) {
     catch {
         // Fall through to AKTree check
     }
-    // Fallback: check AKTree
+    // Fallback: a visible node matching the selector in the AKTree.
+    // (AUT-240, Layer A: the old `serializeAKTree().includes(selector)` fallback
+    // was dropped — a substring match on the serialized tree produced false
+    // positives.)
     try {
         const tree = await adapter.getAKTree();
         if (hasVisibleNodeWithSelector(tree, selector)) {
             return { passed: true, reason: `element "${selector}" is visible in AKTree` };
         }
-        const serialized = serializeAKTree(tree);
-        if (serialized.includes(selector.replace(/[[\]"]/g, ''))) {
-            return { passed: true, reason: `element pattern "${selector}" found in serialized AKTree` };
-        }
         return { passed: false, reason: `element "${selector}" not visible` };
     }
     catch {
@@ -147,6 +164,23 @@ async function checkElementAbsent(adapter, selector) {
     }
 }
 async function checkTextContains(adapter, selector, expectedText) {
+    const expected = normalizeText(expectedText);
+    // Playwright-first (AUT-240, Layer A): read the live DOM text.
+    if (adapter.getTextContent) {
+        try {
+            const live = await adapter.getTextContent(selector);
+            if (live !== null && normalizeText(live).includes(expected)) {
+                return { passed: true, reason: `element "${selector}" contains "${expectedText}" (Playwright)` };
+            }
+            // Element found but text didn't match (or selector missed): fall through
+            // to the AKTree, which may surface label/value/aria text the raw
+            // textContent omits.
+        }
+        catch {
+            // Fall through to AKTree.
+        }
+    }
+    // Fallback: AKTree (label / value / own text).
     try {
         const tree = await adapter.getAKTree();
         const node = findNodeBySelector(tree, selector);
@@ -158,9 +192,8 @@ async function checkTextContains(adapter, selector, expectedText) {
             node.value || '',
             node.attributes.__ownText || '',
         ].join(' '));
-        const expected = normalizeText(expectedText);
         if (nodeText.includes(expected)) {
-            return { passed: true, reason: `element "${selector}" contains "${expectedText}"` };
+            return { passed: true, reason: `element "${selector}" contains "${expectedText}" (AKTree)` };
         }
         return { passed: false, reason: `element "${selector}" text "${nodeText}" does not contain "${expectedText}"` };
     }
@@ -168,24 +201,39 @@ async function checkTextContains(adapter, selector, expectedText) {
         return { passed: false, reason: `error checking text: ${err}` };
     }
 }
+function evaluateOverlayTree(tree) {
+    if (tree.overlays.length === 0) {
+        return { passed: true, reason: 'no overlays detected' };
+    }
+    const blocking = tree.overlays.filter(o => o.blocksInteraction);
+    if (blocking.length === 0) {
+        return { passed: true, reason: 'overlays present but none blocking interaction' };
+    }
+    return { passed: false, reason: `${blocking.length} blocking overlay(s) still present` };
+}
 async function checkOverlayDismissed(adapter) {
     try {
-        const tree = await adapter.getAKTree();
-        // Check if any overlays are reported in the tree
-        if (tree.overlays.length === 0) {
-            return { passed: true, reason: 'no overlays detected' };
-        }
-        // Check if remaining overlays are blocking
-        const blocking = tree.overlays.filter(o => o.blocksInteraction);
-        if (blocking.length === 0) {
-            return { passed: true, reason: 'overlays present but none blocking interaction' };
-        }
-        return { passed: false, reason: `${blocking.length} blocking overlay(s) still present` };
+        return evaluateOverlayTree(await adapter.getAKTree());
     }
     catch {
-        // If AKTree is unavailable (e.g. page.evaluate failure), assume overlays are dismissed.
-        // The overlay dismissal itself ran; we just can't verify via AKTree.
-        return { passed: true, reason: 'overlay check skipped (AKTree unavailable), assuming dismissed' };
+        // AUT-240 (decision 2): "assume OK, but smart". A first `page.evaluate`
+        // hiccup (e.g. navigation in flight) is no longer assumed-OK immediately —
+        // settle the page and retry the AKTree once.
+        try {
+            if (adapter.waitForVisuallyStable) {
+                await adapter.waitForVisuallyStable({ maxWaitMs: 2000 });
+            }
+            return evaluateOverlayTree(await adapter.getAKTree());
+        }
+        catch {
+            // Still unverifiable: assume dismissed as a last resort, but flag
+            // low-confidence so the post-capture verification scrutinizes it.
+            return {
+                passed: true,
+                reason: 'overlay check unverifiable after settle; assuming dismissed (low-confidence)',
+                lowConfidence: true,
+            };
+        }
     }
 }
 async function checkScreenshotStable(adapter, threshold, context) {

package/dist/program-hash.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Capture Agent — Program content hashing (run provenance)
+ *
+ * Stable content hash of an ExecutionProgram, persisted as `program_hash` on
+ * each run so a screenshot can be traced back to the exact program bytes that
+ * produced it. Isolated from program-migrations.ts to keep `node:crypto` out of
+ * the schema validation import chain.
+ */
+import type { ExecutionProgram } from './execution-types.js';
+/** sha256 of the canonicalized program (stable across runs of the same program). */
+export declare function hashProgram(program: ExecutionProgram): string;

package/dist/program-hash.js

@@ -0,0 +1,28 @@
+/**
+ * Capture Agent — Program content hashing (run provenance)
+ *
+ * Stable content hash of an ExecutionProgram, persisted as `program_hash` on
+ * each run so a screenshot can be traced back to the exact program bytes that
+ * produced it. Isolated from program-migrations.ts to keep `node:crypto` out of
+ * the schema validation import chain.
+ */
+import { createHash } from 'node:crypto';
+/** Deterministic JSON serialization with object keys sorted recursively. */
+function stableStringify(value) {
+    if (value === undefined)
+        return 'null';
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const obj = value;
+    const entries = Object.keys(obj)
+        .sort()
+        .map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`);
+    return `{${entries.join(',')}}`;
+}
+/** sha256 of the canonicalized program (stable across runs of the same program). */
+export function hashProgram(program) {
+    return createHash('sha256').update(stableStringify(program)).digest('hex');
+}
+//# sourceMappingURL=program-hash.js.map

package/dist/program-migrations.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Capture Agent — Program FORM migrations (migrate-on-read)
+ *
+ * Old presets are stored at whatever `programSchemaVersion` (FORM) was current
+ * when they were authored. `upgradeProgram` runs a chain of pure
+ * `migrate_vN→vN+1` functions to bring any stored program up to the current
+ * form BEFORE strict schema validation, so the runner only ever sees one shape.
+ *
+ * Properties of this layer (decisions locked in AUT-242):
+ * - Compat forever: the chain is kept indefinitely; no support window.
+ * - Migrate-on-read only: programs are NEVER rewritten back to storage. The
+ *   stored form changes only when the generator recompiles (create/modify).
+ * - Pure + idempotent: a program already at the current form is a no-op.
+ *
+ * This module is intentionally free of Node-only imports so it can be pulled
+ * into the schema validation chain on any runtime. Content hashing
+ * (`node:crypto`) lives in program-hash.ts.
+ */
+/**
+ * Reads the FORM version a raw (pre-migration) program was stored at.
+ * Absent / non-finite ⇒ 0 (the oldest form). Used to stamp run provenance
+ * (`program_schema_version_origin`) before `upgradeProgram` bumps it.
+ */
+export declare function readOriginSchemaVersion(raw: unknown): number;
+/**
+ * Brings any stored program up to {@link CURRENT_PROGRAM_SCHEMA_VERSION} (form)
+ * before strict validation. Pure: clones, never mutates `raw`. Idempotent: a
+ * program already at the current form is returned with only its version stamped.
+ * Non-object input is returned untouched so the schema raises a clean error.
+ */
+export declare function upgradeProgram(raw: unknown): unknown;

package/dist/program-migrations.js

@@ -0,0 +1,93 @@
+/**
+ * Capture Agent — Program FORM migrations (migrate-on-read)
+ *
+ * Old presets are stored at whatever `programSchemaVersion` (FORM) was current
+ * when they were authored. `upgradeProgram` runs a chain of pure
+ * `migrate_vN→vN+1` functions to bring any stored program up to the current
+ * form BEFORE strict schema validation, so the runner only ever sees one shape.
+ *
+ * Properties of this layer (decisions locked in AUT-242):
+ * - Compat forever: the chain is kept indefinitely; no support window.
+ * - Migrate-on-read only: programs are NEVER rewritten back to storage. The
+ *   stored form changes only when the generator recompiles (create/modify).
+ * - Pure + idempotent: a program already at the current form is a no-op.
+ *
+ * This module is intentionally free of Node-only imports so it can be pulled
+ * into the schema validation chain on any runtime. Content hashing
+ * (`node:crypto`) lives in program-hash.ts.
+ */
+import { CURRENT_PROGRAM_SCHEMA_VERSION } from './engine-version.js';
+/** Canonical video capture/delivery resolution (1920×1080 @1×). */
+const VIDEO_RESOLUTION = { width: 1920, height: 1080 };
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Reads the FORM version a raw (pre-migration) program was stored at.
+ * Absent / non-finite ⇒ 0 (the oldest form). Used to stamp run provenance
+ * (`program_schema_version_origin`) before `upgradeProgram` bumps it.
+ */
+export function readOriginSchemaVersion(raw) {
+    if (isRecord(raw) &&
+        typeof raw.programSchemaVersion === 'number' &&
+        Number.isFinite(raw.programSchemaVersion)) {
+        return raw.programSchemaVersion;
+    }
+    return 0;
+}
+/**
+ * v0 → v1: fold the legacy video capture-resolution normalization (formerly the
+ * runtime `normalizeVideoCaptureProgram` in cli-runner.ts) into the program
+ * FORM. Legacy video presets carrying viewport=2560×1440 / DPR=1.3333 /
+ * captureResolution=2560×1440 are normalized to 1920×1080 @1×. Non-video
+ * programs pass through unchanged. Defensive on malformed shapes — anything it
+ * can't normalize is left for the strict schema to reject with a clean error.
+ */
+function migrate_0_to_1(prog) {
+    if (prog.mediaMode !== 'video')
+        return prog;
+    const artifactPlan = isRecord(prog.artifactPlan) ? prog.artifactPlan : undefined;
+    const format = artifactPlan && isRecord(artifactPlan.format) ? artifactPlan.format : {};
+    const variants = Array.isArray(prog.variants)
+        ? prog.variants.map((v) => isRecord(v) ? { ...v, viewport: { ...VIDEO_RESOLUTION }, deviceScaleFactor: 1 } : v)
+        : prog.variants;
+    return {
+        ...prog,
+        outputScale: 1,
+        variants,
+        artifactPlan: {
+            ...(artifactPlan ?? {}),
+            format: {
+                ...format,
+                captureResolution: { ...VIDEO_RESOLUTION },
+                deliveryResolution: { ...VIDEO_RESOLUTION },
+            },
+        },
+    };
+}
+/** Ordered FORM migrations. `MIGRATIONS[n]` upgrades a vN program to vN+1. */
+const MIGRATIONS = {
+    0: migrate_0_to_1,
+};
+/**
+ * Brings any stored program up to {@link CURRENT_PROGRAM_SCHEMA_VERSION} (form)
+ * before strict validation. Pure: clones, never mutates `raw`. Idempotent: a
+ * program already at the current form is returned with only its version stamped.
+ * Non-object input is returned untouched so the schema raises a clean error.
+ */
+export function upgradeProgram(raw) {
+    if (!isRecord(raw))
+        return raw;
+    let prog = { ...raw };
+    let v = readOriginSchemaVersion(raw);
+    while (v < CURRENT_PROGRAM_SCHEMA_VERSION) {
+        const migrate = MIGRATIONS[v];
+        if (!migrate)
+            break; // no path forward; let the schema reject a wrong shape
+        prog = migrate(prog);
+        v += 1;
+    }
+    prog.programSchemaVersion = CURRENT_PROGRAM_SCHEMA_VERSION;
+    return prog;
+}
+//# sourceMappingURL=program-migrations.js.map

package/dist/program-signing.d.ts

@@ -13,6 +13,13 @@ export interface SignedExecutionProgramEnvelope {
     signature: string;
     meta?: {
         stale?: boolean;
+        /**
+         * FORM version the stored program was at BEFORE the server migrated it
+         * (0 = legacy / no version field). Debug-only run provenance; lives in the
+         * UNSIGNED meta because it carries no security weight — the server reads it
+         * from the raw preset config before `extractExecutionProgram` normalizes.
+         */
+        programSchemaVersionOrigin?: number;
     };
 }
 export declare const ProgramSecurityMetadataSchema: z.ZodObject<{
@@ -31,6 +38,8 @@ export declare const SignedExecutionProgramEnvelopeSchema: 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";
@@ -141,6 +150,7 @@ export declare const SignedExecutionProgramEnvelopeSchema: 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;
@@ -1133,6 +1143,7 @@ export declare const SignedExecutionProgramEnvelopeSchema: z.ZodObject<{
     signature: z.ZodString;
     meta: z.ZodOptional<z.ZodObject<{
         stale: z.ZodOptional<z.ZodBoolean>;
+        programSchemaVersionOrigin: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare function normalizeAllowedOrigins(origins: Iterable<string>): string[];

package/dist/program-signing.js

@@ -30,6 +30,7 @@ export const SignedExecutionProgramEnvelopeSchema = z.object({
     signature: z.string().regex(/^[a-f0-9]{64}$/i),
     meta: z.object({
         stale: z.boolean().optional(),
+        programSchemaVersionOrigin: z.number().int().nonnegative().optional(),
     }).strict().optional(),
 }).strict();
 function stableNormalize(value) {

package/dist/recovery-chain.js

@@ -9,7 +9,7 @@
  * 5. LLM Healer (last resort)
  */
 import { resolveSelector } from './selector-resolver.js';
-import { evaluatePostcondition } from './postcondition.js';
+import { evaluatePostcondition, evaluatePostconditionWithProgress } from './postcondition.js';
 import { LLMHealer } from './llm-healer.js';
 import { serializeAKTree } from './ak-tree.js';
 import { executeOpcodeCoreAction } from './opcode-actions.js';
@@ -35,7 +35,7 @@ export class RecoveryChainImpl {
         const retryBudget = Math.max(0, Math.min(recovery.retries, options.maxDeterministicRetries ?? recovery.retries));
         if (retryBudget > 0) {
             logger.debug(`[recovery ${opcodeIndex}] strategy 1 (retry x${retryBudget})`);
-            const result = await retryOpcode(failedOpcode, adapter, retryBudget, options.remainingTimeMs, options.currentVariant, this.credentials, options.suppressPageReloads);
+            const result = await retryOpcode(failedOpcode, adapter, retryBudget, options.remainingTimeMs, options.currentVariant, this.credentials, options.suppressPageReloads, options.globalDeadlineMs, options.getProgress);
             logger.debug(`[recovery ${opcodeIndex}] strategy 1 → recovered=${result.recovered}, reason=${result.reason}`);
             if (result.recovered)
                 return result;
@@ -86,7 +86,7 @@ export class RecoveryChainImpl {
     }
 }
 // ── Strategy 1: Deterministic retry ─────────────────────────────────
-async function retryOpcode(opcode, adapter, maxRetries, remainingTimeMs, currentVariant, credentials, suppressPageReloads = false) {
+async function retryOpcode(opcode, adapter, maxRetries, remainingTimeMs, currentVariant, credentials, suppressPageReloads = false, globalDeadlineMs, getProgress) {
     const deadlineMs = typeof remainingTimeMs === 'number'
         ? Date.now() + remainingTimeMs
         : Number.POSITIVE_INFINITY;
@@ -97,7 +97,11 @@ async function retryOpcode(opcode, adapter, maxRetries, remainingTimeMs, current
         await sleep(500 * (i + 1)); // backoff
         try {
             await executeRawAction(opcode, adapter, currentVariant, credentials, suppressPageReloads);
-            const postcondition = await evaluatePostcondition(adapter, clampPostconditionWait(opcode.postcondition, deadlineMs));
+            // AUT-240 (Phase 5): the re-check extends-on-progress up to the global
+            // deadline instead of replaying a fixed clamped budget. Without the global
+            // deadline (legacy callers), `getProgress` is dropped so it degrades to the
+            // compiled postcondition budget.
+            const postcondition = await evaluatePostconditionWithProgress(adapter, opcode.postcondition, Date.now(), globalDeadlineMs ?? deadlineMs, globalDeadlineMs !== undefined ? getProgress : undefined);
             if (postcondition.passed) {
                 return { recovered: true, strategy: 'retry', reason: `retry ${i + 1}/${maxRetries} succeeded` };
             }
@@ -363,11 +367,4 @@ async function resolveSelectorCoordinates(adapter, selector) {
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
-function clampPostconditionWait(spec, deadlineMs) {
-    const remainingTimeMs = Math.max(1, deadlineMs - Date.now());
-    return {
-        ...spec,
-        waitMs: Math.max(1, Math.min(spec.waitMs ?? remainingTimeMs, remainingTimeMs)),
-    };
-}
 //# sourceMappingURL=recovery-chain.js.map

package/dist/scenario-cookie.d.ts

@@ -0,0 +1,36 @@
+import type { PreconditionSpec } from './execution-types.js';
+/**
+ * AUT-239 — signing side of the AutoKap Scenario cookie.
+ *
+ * The runner (this CLI) signs; the client app's `@autokap/scenario` package
+ * verifies. At runtime these live in two separate processes/deployments, so the
+ * only thing they share is the WIRE FORMAT, not a module. We therefore keep a
+ * tiny local signer here rather than taking a runtime dependency on the
+ * published `@autokap/scenario` package. `scenario-cookie.test.ts` locks the
+ * format against the real resolver so the two can never drift.
+ *
+ * Format: `<id>.<base64url(HMAC-SHA256(secret, id))>`.
+ */
+export declare const SCENARIO_COOKIE_NAME = "__ak_scenario";
+export declare function signScenarioCookie(id: string, secret: string): string;
+/** A cookie ready for Playwright's `context.addCookies`. */
+export interface PreconditionCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path?: string;
+    secure: boolean;
+}
+/**
+ * Build the cookie set injected before navigation: the preset's seed cookies
+ * plus, when configured, the signed scenario switch.
+ *
+ * `secure` is derived from the target protocol — a Secure cookie is never sent
+ * over http://localhost, so the runner must NOT default it to true (that would
+ * silently drop seed/scenario cookies in local captures and fall back to real
+ * data). Returns a `warning` when a scenario is requested but unsignable.
+ */
+export declare function buildPreconditionCookies(preconditions: Pick<PreconditionSpec, 'cookies' | 'scenario'>, baseUrl: string, secret: string | undefined): {
+    cookies: PreconditionCookie[];
+    warning?: string;
+};

package/dist/scenario-cookie.js

@@ -0,0 +1,62 @@
+import { createHmac } from 'node:crypto';
+/**
+ * AUT-239 — signing side of the AutoKap Scenario cookie.
+ *
+ * The runner (this CLI) signs; the client app's `@autokap/scenario` package
+ * verifies. At runtime these live in two separate processes/deployments, so the
+ * only thing they share is the WIRE FORMAT, not a module. We therefore keep a
+ * tiny local signer here rather than taking a runtime dependency on the
+ * published `@autokap/scenario` package. `scenario-cookie.test.ts` locks the
+ * format against the real resolver so the two can never drift.
+ *
+ * Format: `<id>.<base64url(HMAC-SHA256(secret, id))>`.
+ */
+export const SCENARIO_COOKIE_NAME = '__ak_scenario';
+export function signScenarioCookie(id, secret) {
+    const sig = createHmac('sha256', secret).update(id).digest('base64url');
+    return `${id}.${sig}`;
+}
+/**
+ * Build the cookie set injected before navigation: the preset's seed cookies
+ * plus, when configured, the signed scenario switch.
+ *
+ * `secure` is derived from the target protocol — a Secure cookie is never sent
+ * over http://localhost, so the runner must NOT default it to true (that would
+ * silently drop seed/scenario cookies in local captures and fall back to real
+ * data). Returns a `warning` when a scenario is requested but unsignable.
+ */
+export function buildPreconditionCookies(preconditions, baseUrl, secret) {
+    let secure = true;
+    let hostname = '';
+    try {
+        const url = new URL(baseUrl);
+        secure = url.protocol === 'https:';
+        hostname = url.hostname;
+    }
+    catch {
+        /* baseUrl is validated upstream; fall back to Secure on parse failure */
+    }
+    const cookies = (preconditions.cookies ?? []).map((c) => ({
+        ...c,
+        secure,
+    }));
+    let warning;
+    if (preconditions.scenario) {
+        if (!secret) {
+            warning =
+                `preconditions.scenario="${preconditions.scenario}" set but AUTOKAP_SCENARIO_SECRET ` +
+                    `is missing — scenario cookie NOT injected; capture will use real data`;
+        }
+        else {
+            cookies.push({
+                name: SCENARIO_COOKIE_NAME,
+                value: signScenarioCookie(preconditions.scenario, secret),
+                domain: hostname,
+                path: '/',
+                secure,
+            });
+        }
+    }
+    return { cookies, warning };
+}
+//# sourceMappingURL=scenario-cookie.js.map

package/dist/security.d.ts

@@ -16,6 +16,27 @@ export interface SecurityDecision {
     reason?: string;
     target?: InteractiveElement | null;
 }
+/**
+ * Is `candidateUrl` part of the same first-party site as `scopeUrl`? Shares the
+ * navigation site-scope model (`isWithinProjectScope`): exact-host for IPs /
+ * localhost / shared-hosting suffixes (so sibling `*.vercel.app` previews are
+ * NOT same-site), sub-domain family match for real registrable domains.
+ *
+ * Used to scope the adaptive-wait progress signal (AUT-240) to the app's own
+ * traffic, so third-party telemetry (PostHog beacons, analytics/ad pixels,
+ * Sentry, …) no longer reads as "the page is making progress" and the stuck
+ * watchdog can still cut a wait whose condition will never be met.
+ *
+ * Fail-OPEN by design: a false "first-party" only makes the watchdog slightly
+ * more patient (still bounded by the per-media cap), whereas a false "foreign"
+ * could suppress a real progress signal and cut a legitimately-slow page early.
+ * So when in doubt we count it as first-party:
+ *  - unparseable / non-http(s) `scopeUrl` (e.g. `about:blank` before the first
+ *    navigation commits) ⇒ true (don't filter);
+ *  - non-http(s) `candidateUrl` (`data:` / `blob:` / `about:`) ⇒ true (in-page
+ *    resource).
+ */
+export declare function isFirstPartyUrl(scopeUrl: string | null | undefined, candidateUrl: string): boolean;
 export declare function evaluateResolvedActionSecurity(action: ActionType, args: Record<string, unknown>, context: SecurityContext, target: InteractiveElement | null): SecurityDecision;
 export declare function evaluateActionSecurity(action: ActionType, args: Record<string, unknown>, context: SecurityContext): SecurityDecision;
 export declare function describeSecurityTarget(target: InteractiveElement | null | undefined): string;

package/dist/security.js

@@ -109,6 +109,16 @@ function isSharedHostingHostname(hostname) {
 function normalizeScopeHostname(hostname) {
     return hostname.startsWith('www.') ? hostname.slice(4) : hostname;
 }
+function scopeFromParsedUrl(parsed) {
+    const hostname = parsed.hostname.toLowerCase();
+    const exactHost = isLocalHostname(hostname) || isIpv4Hostname(hostname) || isIpv6Hostname(hostname) || isSharedHostingHostname(hostname);
+    const scopeHostname = exactHost ? hostname : normalizeScopeHostname(hostname);
+    return {
+        hostname: scopeHostname,
+        port: effectivePort(parsed),
+        exactHost,
+    };
+}
 function buildNavigationScopes(context) {
     const sources = [
         context.rootUrl,
@@ -119,18 +129,46 @@ function buildNavigationScopes(context) {
         const parsed = parseHttpUrl(value);
         if (!parsed)
             continue;
-        const hostname = parsed.hostname.toLowerCase();
-        const exactHost = isLocalHostname(hostname) || isIpv4Hostname(hostname) || isIpv6Hostname(hostname) || isSharedHostingHostname(hostname);
-        const scopeHostname = exactHost ? hostname : normalizeScopeHostname(hostname);
-        const scope = {
-            hostname: scopeHostname,
-            port: effectivePort(parsed),
-            exactHost,
-        };
+        const scope = scopeFromParsedUrl(parsed);
         dedup.set(`${scope.hostname}:${scope.port}:${scope.exactHost ? 'exact' : 'family'}`, scope);
     }
     return Array.from(dedup.values());
 }
+/**
+ * Is `candidateUrl` part of the same first-party site as `scopeUrl`? Shares the
+ * navigation site-scope model (`isWithinProjectScope`): exact-host for IPs /
+ * localhost / shared-hosting suffixes (so sibling `*.vercel.app` previews are
+ * NOT same-site), sub-domain family match for real registrable domains.
+ *
+ * Used to scope the adaptive-wait progress signal (AUT-240) to the app's own
+ * traffic, so third-party telemetry (PostHog beacons, analytics/ad pixels,
+ * Sentry, …) no longer reads as "the page is making progress" and the stuck
+ * watchdog can still cut a wait whose condition will never be met.
+ *
+ * Fail-OPEN by design: a false "first-party" only makes the watchdog slightly
+ * more patient (still bounded by the per-media cap), whereas a false "foreign"
+ * could suppress a real progress signal and cut a legitimately-slow page early.
+ * So when in doubt we count it as first-party:
+ *  - unparseable / non-http(s) `scopeUrl` (e.g. `about:blank` before the first
+ *    navigation commits) ⇒ true (don't filter);
+ *  - non-http(s) `candidateUrl` (`data:` / `blob:` / `about:`) ⇒ true (in-page
+ *    resource).
+ */
+export function isFirstPartyUrl(scopeUrl, candidateUrl) {
+    const scopeParsed = parseHttpUrl(scopeUrl ?? undefined);
+    if (!scopeParsed)
+        return true;
+    let candidate;
+    try {
+        candidate = new URL(candidateUrl);
+    }
+    catch {
+        return true;
+    }
+    if (candidate.protocol !== 'http:' && candidate.protocol !== 'https:')
+        return true;
+    return isWithinProjectScope(candidate, [scopeFromParsedUrl(scopeParsed)]);
+}
 function isWithinProjectScope(candidate, scopes) {
     const hostname = candidate.hostname.toLowerCase();
     const port = effectivePort(candidate);

package/dist/version.d.ts

@@ -1 +1,2 @@
+/** npm package version of the CLI, transmitted as the `x-autokap-cli-version` header. */
 export declare const APP_VERSION: string;