autokap 1.8.6 → 1.8.8

package/dist/execution-schema.d.ts

@@ -1092,6 +1092,7 @@ export declare const PreconditionSpecSchema: z.ZodObject<{
         domain: z.ZodString;
         path: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;
+    scenario: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export declare const ArtifactSpecSchema: z.ZodObject<{
     mediaMode: z.ZodEnum<{
@@ -1131,6 +1132,8 @@ export declare const ArtifactSpecSchema: z.ZodObject<{
 export declare const ExecutionProgramSchema: 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";
@@ -1241,6 +1244,7 @@ export declare const ExecutionProgramSchema: 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;
@@ -4202,6 +4206,7 @@ export declare function safeParseProgramResult(data: unknown): z.ZodSafeParseRes
             domain: string;
             path?: string | undefined;
         }[] | undefined;
+        scenario?: string | undefined;
     };
     steps: ({
         urlPattern: string;
@@ -4911,6 +4916,8 @@ export declare function safeParseProgramResult(data: unknown): z.ZodSafeParseRes
     };
     compileFingerprint: string;
     compiledAt: string;
+    programSchemaVersion?: number | undefined;
+    engineVersion?: number | undefined;
     maxParallelCaptures?: number | undefined;
     outputScale?: number | undefined;
     variantFingerprint?: string | undefined;
@@ -4930,3 +4937,18 @@ export declare function safeParseProgramResult(data: unknown): z.ZodSafeParseRes
     publicUrl?: string | undefined;
     environmentHttpHeaders?: Record<string, string> | undefined;
 }>;
+export interface ClipNavigationViolation {
+    /** Index of the offending NAVIGATE opcode in `program.steps`. */
+    stepIndex: number;
+    message: string;
+}
+/**
+ * Returns every NAVIGATE opcode located between a BEGIN_CLIP and its END_CLIP.
+ * Pure and mode-agnostic — mirrors the runtime clip window exactly.
+ */
+export declare function findNavigateInClipViolations(program: Pick<ExecutionProgram, 'steps'>): ClipNavigationViolation[];
+/**
+ * Hard-rejection variant for authoring boundaries (preset create/update).
+ * Throws with an actionable message if any NAVIGATE sits inside a clip.
+ */
+export declare function assertNoNavigateInClip(program: Pick<ExecutionProgram, 'steps'>): void;

package/dist/execution-schema.js

@@ -4,6 +4,7 @@
  * Validates ExecutionProgram at compile output (server) and CLI input boundaries.
  */
 import { z } from 'zod';
+import { upgradeProgram } from './program-migrations.js';
 // ── Postcondition ───────────────────────────────────────────────────
 export const PostconditionSpecSchema = z.object({
     type: z.enum([
@@ -596,6 +597,8 @@ export const PreconditionSpecSchema = z.object({
     storageState: StorageStateSchema.optional(),
     sessionStorage: z.record(z.string(), z.record(z.string(), z.string())).optional(),
     cookies: z.array(cookieSchema).optional(),
+    // AUT-239: active scenario id; runner injects a signed __ak_scenario cookie.
+    scenario: z.string().min(1).optional(),
 }).strict();
 // ── Artifact spec ───────────────────────────────────────────────────
 const ResolutionSchema = z.object({
@@ -603,7 +606,6 @@ const ResolutionSchema = z.object({
     height: z.number().int().positive(),
 }).strict();
 const DEFAULT_VIDEO_DELIVERY_RESOLUTION = { width: 1920, height: 1080 };
-const LEGACY_VIDEO_CAPTURE_RESOLUTION = { width: 2560, height: 1440 };
 function resolutionEquals(a, b) {
     return a.width === b.width && a.height === b.height;
 }
@@ -623,14 +625,14 @@ export const ArtifactSpecSchema = z.object({
 }).strict().superRefine((value, ctx) => {
     if (value.mediaMode === 'video') {
         const res = value.format?.captureResolution;
-        const matchesDefault = res ? resolutionEquals(res, DEFAULT_VIDEO_DELIVERY_RESOLUTION) : false;
-        const matchesLegacy = res ? resolutionEquals(res, LEGACY_VIDEO_CAPTURE_RESOLUTION) : false;
-        if (!res || (!matchesDefault && !matchesLegacy)) {
+        // Legacy 2560×1440 programs are normalized to 1920×1080 by migrate-on-read
+        // (program-migrations.ts, migrate_0→1) BEFORE this schema runs, so only the
+        // canonical resolution reaches validation here.
+        if (!res || !resolutionEquals(res, DEFAULT_VIDEO_DELIVERY_RESOLUTION)) {
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 path: ['format', 'captureResolution'],
-                message: "mediaMode='video' requires format.captureResolution = { width: 1920, height: 1080 }; " +
-                    'legacy 2560x1440 programs are accepted and normalized at runtime',
+                message: "mediaMode='video' requires format.captureResolution = { width: 1920, height: 1080 }",
             });
         }
     }
@@ -638,7 +640,17 @@ export const ArtifactSpecSchema = z.object({
 // ── Full program ────────────────────────────────────────────────────
 export const ExecutionProgramSchema = z.object({
     presetId: z.string().min(1),
+    // Content-revision counter bumped by the healer; orthogonal to programSchemaVersion (form).
     programVersion: z.number().int().positive(),
+    // FORM version. migrate-on-read (upgradeProgram, run inside parseProgram)
+    // stamps this to the current value before validation. Intentionally optional
+    // and WITHOUT a Zod default: this schema is reused inside signature
+    // verification (program-signing.ts), where injecting a default would mutate
+    // the signed payload and break signature symmetry for programs signed without
+    // the field. Presence at runtime is guaranteed by upgradeProgram, not here.
+    programSchemaVersion: z.number().int().positive().optional(),
+    // Provenance: engine semantics the generator targeted. Informational only.
+    engineVersion: z.number().int().positive().optional(),
     mediaMode: z.enum(['screenshot', 'clip', 'video']),
     baseUrl: StrictUrlSchema,
     maxParallelCaptures: z.number().int().positive().optional(),
@@ -685,12 +697,51 @@ export const HealerPatchSchema = z.object({
 }).strict();
 // ── Typed parse helpers ─────────────────────────────────────────────
 export function parseProgram(data) {
-    return ExecutionProgramSchema.parse(data);
+    // migrate-on-read: bring any stored FORM up to the current shape before the
+    // strict schema runs, so legacy presets parse instead of being rejected en bloc.
+    return ExecutionProgramSchema.parse(upgradeProgram(data));
 }
 export function parseOpcode(data) {
     return ExecutionOpcodeSchema.parse(data);
 }
 export function safeParseProgramResult(data) {
-    return ExecutionProgramSchema.safeParse(data);
+    return ExecutionProgramSchema.safeParse(upgradeProgram(data));
+}
+/**
+ * Returns every NAVIGATE opcode located between a BEGIN_CLIP and its END_CLIP.
+ * Pure and mode-agnostic — mirrors the runtime clip window exactly.
+ */
+export function findNavigateInClipViolations(program) {
+    const violations = [];
+    let insideClip = false;
+    program.steps.forEach((step, index) => {
+        if (step.kind === 'BEGIN_CLIP') {
+            insideClip = true;
+            return;
+        }
+        if (step.kind === 'END_CLIP') {
+            insideClip = false;
+            return;
+        }
+        if (insideClip && step.kind === 'NAVIGATE') {
+            violations.push({
+                stepIndex: index,
+                message: `NAVIGATE at step ${index} is inside a clip (between BEGIN_CLIP and END_CLIP) and would cause a ` +
+                    `white-flash cut in the recording. Move it before BEGIN_CLIP (off-camera warmup), or CLICK an ` +
+                    `in-app <Link> the router intercepts instead.`,
+            });
+        }
+    });
+    return violations;
+}
+/**
+ * Hard-rejection variant for authoring boundaries (preset create/update).
+ * Throws with an actionable message if any NAVIGATE sits inside a clip.
+ */
+export function assertNoNavigateInClip(program) {
+    const violations = findNavigateInClipViolations(program);
+    if (violations.length > 0) {
+        throw new Error(violations.map((v) => v.message).join(' '));
+    }
 }
 //# sourceMappingURL=execution-schema.js.map

package/dist/execution-types.d.ts

@@ -487,6 +487,14 @@ export interface PreconditionSpec {
         domain: string;
         path?: string;
     }>;
+    /**
+     * Active AutoKap Scenario id (AUT-239). When set and `AUTOKAP_SCENARIO_SECRET`
+     * is configured, the runner injects a signed `__ak_scenario=<id>.<sig>` cookie
+     * before navigation, so the client app's cooperative scenario layer reads it
+     * server-side (SSR-safe) and serves the named state's fixtures. Inert if the
+     * secret is absent.
+     */
+    scenario?: string;
 }
 export declare const MEDIA_MODES: readonly ["screenshot", "clip", "video"];
 export type MediaMode = (typeof MEDIA_MODES)[number];
@@ -534,7 +542,26 @@ export interface ArtifactSpec {
 }
 export interface ExecutionProgram {
     presetId: string;
+    /**
+     * Content-revision counter, bumped ONLY by the healer after a selector repair
+     * (program-patcher.ts). Orthogonal to `programSchemaVersion` — it tracks
+     * content changes, never the form of the program.
+     */
     programVersion: number;
+    /**
+     * FORM version of the program, driving migrate-on-read (program-migrations.ts).
+     * Optional on the type so hand-built literals (fixtures) stay terse; guaranteed
+     * present at runtime by `upgradeProgram` (run inside parseProgram), which stamps
+     * it to the current value. Absent = v0 (oldest form). Read with
+     * `?? CURRENT_PROGRAM_SCHEMA_VERSION` when stamping.
+     */
+    programSchemaVersion?: number;
+    /**
+     * Provenance stamp: the engine semantics version the generator compiled this
+     * program against. Informational only — the runtime engine always applies the
+     * current semantics regardless. Absent = legacy (pre-versioning) program.
+     */
+    engineVersion?: number;
     mediaMode: MediaMode;
     baseUrl: string;
     /** Server-resolved concurrency cap for this run, derived from the owner's plan. */
@@ -673,6 +700,22 @@ export interface ArtifactResult {
     /** Favicon extracted from the captured page */
     tabIconData?: Buffer;
     tabIconMimeType?: string;
+    /**
+     * AUT-240 (Layer 4): the capture was produced under a degraded signal — an
+     * AKTree probe that kept throwing was assumed-OK as a last resort, or the page
+     * never reached a visually-stable state. "Assume OK, but flag it." Q4 decision:
+     * produce-only for now (a downstream consumer in gallery / post-capture
+     * verification is a later phase); no LLM is forced off this flag.
+     */
+    lowConfidence?: boolean;
+    /** Why the artifact was flagged low-confidence (human-readable). */
+    lowConfidenceReason?: string;
+    /**
+     * AUT-241 — navigation-watcher warnings captured while this clip/video was
+     * recording (e.g. a full document load mid-take = white flash + cursor loss).
+     * Carried up to `RunResult.warnings`; diagnostic only, never fails the run.
+     */
+    warnings?: string[];
 }
 export type LLMStepType = 'capture_verification' | 'alt_text_generation' | 'healer_invocation';
 export interface LLMStepUsage {
@@ -763,6 +806,13 @@ export interface RunResult {
      * with the version actually captured on the page.
      */
     detectedAppVersion?: string | null;
+    /**
+     * AUT-241 — non-fatal warnings aggregated from every clip/video recording in
+     * the run (full document loads mid-take, unexpected page-side navigations).
+     * Empty/undefined when nothing was flagged. Anti-cut policy surfaces these
+     * instead of masking the cut; deployed presets are grandfathered at run.
+     */
+    warnings?: string[];
     error?: string;
 }
 export interface WaitCondition {
@@ -770,6 +820,38 @@ export interface WaitCondition {
     state: 'visible' | 'attached';
     timeoutMs: number;
 }
+/**
+ * Cheap, side-effect-free snapshot of page activity (AUT-240, Layer C).
+ * Compared across polls by the runner's progress watchdog to distinguish a
+ * slow-but-progressing page (extend the wait) from a genuinely stuck one (cut).
+ */
+export interface ProgressSnapshot {
+    /**
+     * Monotonic count of FIRST-PARTY network lifecycle events
+     * (request/finished/failed) — same site as the live page origin. Third-party
+     * telemetry is excluded so it cannot masquerade as progress.
+     */
+    networkEventCount: number;
+    /** First-party requests issued but not yet finished or failed. */
+    inflightRequests: number;
+    /** `Date.now()` of the last observed first-party network lifecycle event. */
+    lastNetworkActivityAtMs: number;
+    /** `document.readyState`, or 'unknown' if unreadable. */
+    readyState: string;
+    /** Total element count — a cheap DOM-churn signal — or -1 if unreadable. */
+    domNodeCount: number;
+    /** True when the readability probe threw (itself a sign of navigation). */
+    navigating?: boolean;
+}
+/** Result of `RuntimeAdapter.waitForVisuallyStable` (AUT-240, Layer B). */
+export interface VisualStabilityResult {
+    /** Whether the page reached a clean, stable state before the deadline. */
+    stable: boolean;
+    /** Human-readable explanation (which signal stayed noisy, if any). */
+    reason: string;
+    /** Total time spent stabilizing (ms). */
+    waitedMs: number;
+}
 export interface ClickOptions {
     /** Force click even if element is covered */
     force?: boolean;
@@ -822,6 +904,12 @@ export interface RecordingResult {
     durationMs: number;
     mimeType: string;
     trimStartMs?: number;
+    /**
+     * AUT-241 — human-readable warnings collected by the navigation watcher
+     * during this recording window (e.g. a full document load = white flash +
+     * cursor loss). Surfaced up to `RunResult.warnings`; never fails the run.
+     */
+    warnings?: string[];
 }
 export interface TypeOptions {
     /**
@@ -887,6 +975,14 @@ export interface RuntimeAdapter {
      * adapters that cannot resolve a title should leave this method off.
      */
     getPageTitle?(): Promise<string | null>;
+    /**
+     * Text content of the first element matching `selector`, read live from the
+     * DOM via Playwright (`locator().first().textContent()`). Preferred over the
+     * AKTree for `text_contains` postconditions (AUT-240, Layer A). Returns null
+     * if the selector misses or the read fails. Optional — adapters without it
+     * make `text_contains` fall back to the AKTree.
+     */
+    getTextContent?(selector: string): Promise<string | null>;
     /**
      * Read the captured app's version from the live page (meta tag, window
      * global, or data attribute). Mirrors `extractAppVersionFromHtml` server-side
@@ -989,4 +1085,24 @@ export interface RuntimeAdapter {
     clickHidden?(opts: {
         selector: string;
     }): Promise<void>;
+    /**
+     * Cheap snapshot of page activity used by the runner's progress watchdog to
+     * decide whether a wait is "slow-but-progressing" (keep waiting) or "stuck"
+     * (cut). Must never reject — implementations catch internally and set
+     * `navigating: true` when the readability probe throws. Adapters that cannot
+     * provide it leave it off; the runner then falls back to fixed budgets.
+     */
+    getProgressSnapshot?(): Promise<ProgressSnapshot>;
+    /**
+     * Wait for the page to be visually stable before a screenshot (Layer B):
+     * fonts ready, images loaded, no semantic loaders ([aria-busy]/progressbar)
+     * visible, DOM quiet, with a bounded pixel-convergence fallback. Best-effort —
+     * never throws and never blocks the capture: when it cannot reach a clean
+     * state it returns `stable: false` with a reason and the runner captures
+     * anyway. Adapters that cannot provide it leave it off; the runner falls back
+     * to the legacy `smartWaitForStability`.
+     */
+    waitForVisuallyStable?(options?: {
+        maxWaitMs?: number;
+    }): Promise<VisualStabilityResult>;
 }

package/dist/opcode-runner.d.ts

@@ -5,7 +5,7 @@
  * Executes opcodes sequentially, verifies postconditions,
  * delegates to recovery chain on failure, and respects circuit breaker.
  */
-import type { ExecutionProgram, ExecutionOpcode, RuntimeAdapter, OpcodeResultStatus, RunResult, HealerPatch, VariantSpec } from './execution-types.js';
+import type { ExecutionProgram, ExecutionOpcode, RuntimeAdapter, OpcodeResultStatus, RunResult, HealerPatch, VariantSpec, ProgressSnapshot } from './execution-types.js';
 import type { LLMProviderConfig, LLMCallResult } from './llm-provider.js';
 export interface RecoveryChain {
     attempt(failedOpcode: ExecutionOpcode, opcodeIndex: number, adapter: RuntimeAdapter, options?: RecoveryAttemptOptions): Promise<RecoveryAttemptResult>;
@@ -19,6 +19,13 @@ export interface RecoveryAttemptResult {
 }
 export interface RecoveryAttemptOptions {
     remainingTimeMs?: number;
+    /**
+     * AUT-240 (Phase 5): absolute global wait deadline. Lets recovery re-checks
+     * extend-on-progress (like the main path) instead of replaying a fixed budget.
+     */
+    globalDeadlineMs?: number;
+    /** Progress probe for the recovery watchdog (omitted ⇒ fixed budgets). */
+    getProgress?: () => Promise<ProgressSnapshot | null>;
     maxDeterministicRetries?: number;
     currentVariant?: VariantSpec;
     allowPageReload?: boolean;