autokap 2.0.0 → 2.0.1

package/dist/cli-runner.js

@@ -174,7 +174,7 @@ export async function runCapture(options) {
     // durations + audio assets are only consumed on the upload path (signalVideoComplete), which a dry
     // run never reaches, so skipping prep here is side-effect-free for dry.
     if (!options.dryRun && !options.program && program.mediaMode === 'video') {
-        const prepareResult = await prepareVideoSpeechForRun(config, options.presetId, runId, options.regenerateTts ?? false, sessionId);
+        const prepareResult = await prepareVideoSpeechForRun(config, options.presetId, runId, options.regenerateTts ?? false, sessionId, options.onProgress);
         if (!prepareResult.success) {
             return { success: false, runId, error: prepareResult.error };
         }
@@ -524,7 +524,7 @@ async function fetchProgram(config, presetId, environmentName) {
     }
     return { success: false, error: 'failed to fetch program: retry attempts exhausted' };
 }
-async function prepareVideoSpeechForRun(config, videoId, runId, regenerateTts, sessionId) {
+async function prepareVideoSpeechForRun(config, videoId, runId, regenerateTts, sessionId, onProgress) {
     if (regenerateTts) {
         logger.info('[capture] Forcing TTS regeneration — all cached segments will be re-synthesized and billed.');
     }
@@ -578,6 +578,17 @@ async function prepareVideoSpeechForRun(config, videoId, runId, regenerateTts, s
         }
         if (event.type === 'tts_progress') {
             logTtsProgress(event);
+            // Forward to the caller so cloud runs can surface the narration phase as
+            // checkpoints (local runs only ever logged it — the original blind spot).
+            onProgress?.({
+                type: 'tts_progress',
+                variantId: 'tts',
+                message: '',
+                stage: event.stage,
+                index: event.index,
+                total: event.total,
+                stepId: event.stepId,
+            });
             return;
         }
         if (event.type === 'error') {

package/dist/cli.d.ts

@@ -1,3 +1,24 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import type { ProgressEvent } from './opcode-runner.js';
 export declare const program: Command;
+type CloudCheckpointType = 'preset_progress' | 'upload_start' | 'upload_end';
+/** Interval below which consecutive `granular` checkpoints are coalesced. */
+export declare const GRANULAR_CHECKPOINT_THROTTLE_MS = 1200;
+export declare function cloudCaptureProgressCheckpoint(event: ProgressEvent): {
+    type: CloudCheckpointType;
+    message: string;
+    status?: 'running';
+    /** Fine-grained intra-preset event (per-opcode / per-narration) — throttled
+     *  so a long video's step stream can't bury the coarse structural events in
+     *  the server's bounded timeline window. Structural events are never marked. */
+    granular?: boolean;
+} | null;
+/**
+ * Stateful gate that admits at most one `granular` checkpoint per throttle
+ * window; structural (non-granular) checkpoints always pass. Create one per
+ * preset so each preset streams its own opcode/narration cadence. `now` is
+ * injectable for tests.
+ */
+export declare function createGranularCheckpointThrottle(throttleMs?: number, now?: () => number): (granular: boolean) => boolean;
+export {};

package/dist/cli.js

@@ -51,7 +51,9 @@ function displayPresetName(preset) {
     const name = preset.name?.trim();
     return name && name.length > 0 ? name : preset.id;
 }
-function cloudCaptureProgressCheckpoint(event) {
+/** Interval below which consecutive `granular` checkpoints are coalesced. */
+export const GRANULAR_CHECKPOINT_THROTTLE_MS = 1200;
+export function cloudCaptureProgressCheckpoint(event) {
     switch (event.type) {
         case 'variant_start':
             return {
@@ -66,6 +68,26 @@ function cloudCaptureProgressCheckpoint(event) {
                     : `Capture failed: ${event.variantId}`,
                 status: event.status === 'failed' ? 'running' : undefined,
             };
+        case 'opcode_start': {
+            const position = (event.opcodeIndex ?? 0) + 1;
+            const total = event.opcodeTotal ? `/${event.opcodeTotal}` : '';
+            const label = event.message || event.opcodeKind || '';
+            return {
+                type: 'preset_progress',
+                granular: true,
+                message: label ? `Step ${position}${total}: ${label}` : `Step ${position}${total}`,
+            };
+        }
+        case 'tts_progress': {
+            const position = event.index ?? '?';
+            const total = event.total ?? '?';
+            const suffix = event.stage === 'uploading' ? ' · uploading' : event.stage === 'done' ? ' · done' : '';
+            return {
+                type: 'preset_progress',
+                granular: true,
+                message: `Narration ${position}/${total}${suffix}`,
+            };
+        }
         case 'upload_start':
             return {
                 type: 'upload_start',
@@ -81,6 +103,24 @@ function cloudCaptureProgressCheckpoint(event) {
             return null;
     }
 }
+/**
+ * Stateful gate that admits at most one `granular` checkpoint per throttle
+ * window; structural (non-granular) checkpoints always pass. Create one per
+ * preset so each preset streams its own opcode/narration cadence. `now` is
+ * injectable for tests.
+ */
+export function createGranularCheckpointThrottle(throttleMs = GRANULAR_CHECKPOINT_THROTTLE_MS, now = Date.now) {
+    let lastGranularAt = null;
+    return (granular) => {
+        if (!granular)
+            return true;
+        const current = now();
+        if (lastGranularAt !== null && current - lastGranularAt < throttleMs)
+            return false;
+        lastGranularAt = current;
+        return true;
+    };
+}
 // ── login command ───────────────────────────────────────────────────
 program
     .command('login <key>')
@@ -420,6 +460,9 @@ program
             failedPresets: failures.length,
             message: `Preset started: ${presetDisplayName}`,
         });
+        // Fresh throttle per preset so each preset streams its own opcode/
+        // narration cadence and the window resets at each preset boundary.
+        const admitCheckpoint = createGranularCheckpointThrottle();
         const result = await runCapture({
             presetId: preset.id,
             env: opts.env,
@@ -437,6 +480,10 @@ program
                 const checkpoint = cloudCaptureProgressCheckpoint(event);
                 if (!checkpoint)
                     return;
+                // Coalesce fine-grained (opcode / narration) checkpoints; structural
+                // ones (capture/export start/end) always pass through.
+                if (!admitCheckpoint(checkpoint.granular ?? false))
+                    return;
                 void postCloudCheckpoint({
                     type: checkpoint.type,
                     presetId: preset.id,

package/dist/opcode-runner.d.ts

@@ -52,11 +52,20 @@ export interface RunOptions {
     dryRun?: boolean;
 }
 export interface ProgressEvent {
-    type: 'variant_start' | 'variant_end' | 'opcode_start' | 'opcode_end' | 'recovery' | 'breaker_trip' | 'upload_start' | 'upload_end';
+    type: 'variant_start' | 'variant_end' | 'opcode_start' | 'opcode_end' | 'recovery' | 'breaker_trip' | 'upload_start' | 'upload_end' | 'tts_progress';
     variantId: string;
     opcodeIndex?: number;
+    /** Total opcode count in the variant program (set on opcode_start). */
+    opcodeTotal?: number;
     opcodeKind?: string;
     status?: OpcodeResultStatus;
     message: string;
+    /** tts_progress only: 'synthesizing' | 'uploading' | 'done'. */
+    stage?: string;
+    /** tts_progress only: 1-based segment index and total. */
+    index?: number;
+    total?: number;
+    /** tts_progress only: the SLEEP anchor / step id being synthesized. */
+    stepId?: string;
 }
 export declare function executeProgram(program: ExecutionProgram, createAdapter: (variant: VariantSpec) => Promise<RuntimeAdapter>, options?: RunOptions): Promise<RunResult>;

package/dist/opcode-runner.js

@@ -318,6 +318,7 @@ async function executeVariant(program, variant, createAdapter, recoveryChain, te
                 type: 'opcode_start',
                 variantId: variant.id,
                 opcodeIndex: i,
+                opcodeTotal: program.steps.length,
                 opcodeKind: opcode.kind,
                 message: opcode.description,
             });

package/package.json

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