@farmslot/recipe-harness 0.2.0 → 0.2.2

package/dist/core/runner.js

@@ -1,12 +1,14 @@
-import { mkdir } from 'node:fs/promises';
+import { mkdir, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { getRecipeActionManifestActionNames, validateRecipeArtifactPackage, } from '@farmslot/protocol';
 import { JsonArtifactWriter, JsonSummaryWriter, JsonTraceWriter } from '../node/writers.js';
+import { createCaptureHelperVideoRecorder, errorMessage, manifestTarget, } from '../recording/capture-helper.js';
 import { collectFlows, executeInlineFlowCall } from './flows.js';
 import { extractWorkflowGraph, normalizePreconditionResult, resolveNextNode, } from './graph.js';
 import { buildHudNode } from './hud.js';
 import { isRecord, normalizeRelativePath, readJsonFile } from './json.js';
 import { evaluateNodeGate } from './predicates.js';
+import { cleanupAbortedRunVideoRecording, removePartialRunVideoOutput, } from './recording-cleanup.js';
 import { recordSyntheticFailure, traceNodeMetadata } from './trace.js';
 import { assertManifestIsValid, assertRecipeMatchesManifest } from './validation.js';
 const HARNESS_VERSION = '0.1.0';
@@ -55,7 +57,7 @@ export function createRecipeRunner(options) {
             throw new Error(`Manifest action ${action} has no registered adapter.`);
         }
     }
-    return new DefaultRecipeRunner(options.actionManifest, adapterMap, preconditionMap, options.logger ?? noopLogger, options.hud, options.runner);
+    return new DefaultRecipeRunner(options.actionManifest, adapterMap, preconditionMap, options.logger ?? noopLogger, options.hud, options.runner, options.recording);
 }
 class DefaultRecipeRunner {
     #actionManifest;
@@ -64,13 +66,15 @@ class DefaultRecipeRunner {
     #logger;
     #hud;
     #runnerProvenance;
-    constructor(actionManifest, adapters, preconditions, logger, hud, runnerProvenance) {
+    #recording;
+    constructor(actionManifest, adapters, preconditions, logger, hud, runnerProvenance, recording) {
         this.#actionManifest = actionManifest;
         this.#adapters = adapters;
         this.#preconditions = preconditions;
         this.#logger = logger;
         this.#hud = hud;
         this.#runnerProvenance = runnerProvenance;
+        this.#recording = recording;
     }
     async run(request) {
         if (!request.recipePath && request.recipeDocument == null) {
@@ -100,227 +104,281 @@ class DefaultRecipeRunner {
         const visited = new Set();
         let transitionCount = 0;
         const maxTransitions = Object.keys(graph.nodes).length * 3;
-        const preconditionStatus = await this.#runPreconditions({
-            graph,
-            recipe,
-            projectRoot,
-            artifactsDir,
-            request,
-            outputs,
-            artifactWriter,
-            traceWriter,
-        });
-        if (preconditionStatus === 'fail') {
-            status = 'fail';
-            currentNodeId = undefined;
-        }
-        while (currentNodeId) {
-            const activeNodeId = currentNodeId;
-            transitionCount += 1;
-            if (transitionCount > maxTransitions) {
-                const error = new Error('Recipe graph exceeded its maximum transition count.');
-                recordSyntheticFailure(traceWriter, activeNodeId, error);
-                status = 'fail';
-                break;
+        const videoOptions = normalizeVideoRecordingOptions(request.recordVideo);
+        const videoRecorder = videoOptions.mode !== 'off' ? this.#videoRecorder() : undefined;
+        let runRecording;
+        if (videoRecorder) {
+            try {
+                runRecording = await this.#startRunVideoRecording({
+                    recorder: videoRecorder,
+                    videoOptions,
+                    recipe,
+                    projectRoot,
+                    artifactsDir,
+                    env: request.env ?? {},
+                });
             }
-            visited.add(activeNodeId);
-            const node = graph.nodes[activeNodeId];
-            if (!node) {
-                const error = new Error(`Recipe node ${activeNodeId} does not exist.`);
-                recordSyntheticFailure(traceWriter, activeNodeId, error);
+            catch (error) {
+                const message = errorMessage(error);
+                traceWriter.record({
+                    nodeId: 'recipe-run:video',
+                    action: 'record.video',
+                    startedAt: startedAt.toISOString(),
+                    endedAt: new Date().toISOString(),
+                    durationMs: Date.now() - startedAt.getTime(),
+                    ok: false,
+                    error: message,
+                });
+                this.#logger.error(`record.video start failed: ${message}`);
                 status = 'fail';
-                break;
+                currentNodeId = undefined;
             }
-            const action = String(node.action);
-            const adapter = action === 'call' ? undefined : this.#adapters.get(action);
-            if (action !== 'call' && !adapter) {
-                const error = new Error(`No adapter registered for action ${action}.`);
-                recordSyntheticFailure(traceWriter, activeNodeId, error, action);
-                status = 'fail';
-                break;
+        }
+        try {
+            if (currentNodeId) {
+                const preconditionStatus = await this.#runPreconditions({
+                    graph,
+                    recipe,
+                    projectRoot,
+                    artifactsDir,
+                    request,
+                    outputs,
+                    artifactWriter,
+                    traceWriter,
+                });
+                if (preconditionStatus === 'fail') {
+                    status = 'fail';
+                    currentNodeId = undefined;
+                }
             }
-            const nodeStartedAt = new Date();
-            const context = {
-                nodeId: activeNodeId,
-                recipe,
-                projectRoot,
-                artifactsDir,
-                env: request.env ?? {},
-                outputs,
-                getOutput(nodeId) {
-                    if (!outputs.has(nodeId))
-                        throw new Error(`No output recorded for node ${nodeId}.`);
-                    return outputs.get(nodeId);
-                },
-                resolveProjectPath(relativePath) {
-                    return path.join(projectRoot, normalizeRelativePath(relativePath));
-                },
-                resolveArtifactPath(relativePath) {
-                    return path.join(artifactsDir, normalizeRelativePath(relativePath));
-                },
-                registerArtifact(entry) {
-                    artifactWriter.register(entry);
-                },
-                logger: this.#logger,
-            };
-            try {
-                const gate = evaluateNodeGate(node, context.outputs);
-                if (!gate.run) {
-                    const next = resolveNextNode(node, {});
+            while (currentNodeId) {
+                const activeNodeId = currentNodeId;
+                transitionCount += 1;
+                if (transitionCount > maxTransitions) {
+                    const error = new Error('Recipe graph exceeded its maximum transition count.');
+                    recordSyntheticFailure(traceWriter, activeNodeId, error);
+                    status = 'fail';
+                    break;
+                }
+                visited.add(activeNodeId);
+                const node = graph.nodes[activeNodeId];
+                if (!node) {
+                    const error = new Error(`Recipe node ${activeNodeId} does not exist.`);
+                    recordSyntheticFailure(traceWriter, activeNodeId, error);
+                    status = 'fail';
+                    break;
+                }
+                const action = String(node.action);
+                const adapter = action === 'call' ? undefined : this.#adapters.get(action);
+                if (action !== 'call' && !adapter) {
+                    const error = new Error(`No adapter registered for action ${action}.`);
+                    recordSyntheticFailure(traceWriter, activeNodeId, error, action);
+                    status = 'fail';
+                    break;
+                }
+                const nodeStartedAt = new Date();
+                const context = this.#createExecutionContext({
+                    nodeId: activeNodeId,
+                    recipe,
+                    projectRoot,
+                    artifactsDir,
+                    env: request.env ?? {},
+                    outputs,
+                    artifactWriter,
+                });
+                try {
+                    const gate = evaluateNodeGate(node, context.outputs);
+                    if (!gate.run) {
+                        const next = resolveNextNode(node, {});
+                        traceWriter.record({
+                            nodeId: activeNodeId,
+                            action,
+                            ...traceNodeMetadata(node),
+                            startedAt: nodeStartedAt.toISOString(),
+                            endedAt: new Date().toISOString(),
+                            durationMs: Date.now() - nodeStartedAt.getTime(),
+                            ok: true,
+                            next,
+                            output: { skipped: true, reason: gate.reason },
+                        });
+                        currentNodeId = next;
+                        continue;
+                    }
+                    const hudStarted = await this.#publishHudProgressOrRecord(traceWriter, 'running', {
+                        nodeId: activeNodeId,
+                        action,
+                        node,
+                        recipe,
+                        index: transitionCount,
+                        total: Object.keys(graph.nodes).length,
+                        context,
+                    });
+                    if (!hudStarted) {
+                        status = 'fail';
+                        break;
+                    }
+                    const result = action === 'call'
+                        ? await executeInlineFlowCall({
+                            callNodeId: activeNodeId,
+                            node,
+                            context,
+                            flowCatalog,
+                            adapters: this.#adapters,
+                            traceWriter,
+                            callStack: [],
+                            maxCallDepth: DEFAULT_MAX_FLOW_CALL_DEPTH,
+                            publishHudProgress: (hudStatus, flowEvent) => this.#publishHudProgressOrRecord(traceWriter, hudStatus, {
+                                ...flowEvent,
+                                recipe,
+                            }),
+                        })
+                        : await adapter.execute(node, context);
+                    if (result.output !== undefined)
+                        outputs.set(activeNodeId, result.output);
+                    for (const artifact of result.artifacts ?? [])
+                        artifactWriter.register(artifact);
+                    const next = resolveNextNode(node, result);
                     traceWriter.record({
                         nodeId: activeNodeId,
                         action,
-                        ...traceNodeMetadata(node),
+                        ...traceNodeMetadata(node, result),
                         startedAt: nodeStartedAt.toISOString(),
                         endedAt: new Date().toISOString(),
                         durationMs: Date.now() - nodeStartedAt.getTime(),
                         ok: true,
                         next,
-                        output: { skipped: true, reason: gate.reason },
+                        status: result.status,
+                        output: result.output,
                     });
+                    const hudCompleted = await this.#publishHudProgressOrRecord(traceWriter, result.status === 'fail' ? 'fail' : 'pass', {
+                        nodeId: activeNodeId,
+                        action,
+                        node,
+                        recipe,
+                        index: transitionCount,
+                        total: Object.keys(graph.nodes).length,
+                        context,
+                    });
+                    if (!hudCompleted) {
+                        status = 'fail';
+                        break;
+                    }
+                    if (result.status) {
+                        if (runningTeardown) {
+                            status = mainStatus === 'fail' ? 'fail' : result.status;
+                            break;
+                        }
+                        mainStatus = result.status;
+                        if (graph.teardownEntry) {
+                            runningTeardown = true;
+                            currentNodeId = graph.teardownEntry;
+                            continue;
+                        }
+                        status = result.status;
+                        break;
+                    }
                     currentNodeId = next;
-                    continue;
                 }
-                const hudStarted = await this.#publishHudProgressOrRecord(traceWriter, 'running', {
-                    nodeId: activeNodeId,
-                    action,
-                    node,
-                    recipe,
-                    index: transitionCount,
-                    total: Object.keys(graph.nodes).length,
-                    context,
-                });
-                if (!hudStarted) {
-                    status = 'fail';
-                    break;
-                }
-                const result = action === 'call'
-                    ? await executeInlineFlowCall({
-                        callNodeId: activeNodeId,
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    traceWriter.record({
+                        nodeId: activeNodeId,
+                        action,
+                        ...traceNodeMetadata(node),
+                        startedAt: nodeStartedAt.toISOString(),
+                        endedAt: new Date().toISOString(),
+                        durationMs: Date.now() - nodeStartedAt.getTime(),
+                        ok: false,
+                        error: message,
+                    });
+                    this.#logger.error(message);
+                    await this.#publishHudProgressOrRecord(traceWriter, 'fail', {
+                        nodeId: activeNodeId,
+                        action,
                         node,
+                        recipe,
+                        index: transitionCount,
+                        total: Object.keys(graph.nodes).length,
                         context,
-                        flowCatalog,
-                        adapters: this.#adapters,
-                        traceWriter,
-                        callStack: [],
-                        maxCallDepth: DEFAULT_MAX_FLOW_CALL_DEPTH,
-                    })
-                    : await adapter.execute(node, context);
-                if (result.output !== undefined)
-                    outputs.set(activeNodeId, result.output);
-                for (const artifact of result.artifacts ?? [])
-                    artifactWriter.register(artifact);
-                const next = resolveNextNode(node, result);
-                traceWriter.record({
-                    nodeId: activeNodeId,
-                    action,
-                    ...traceNodeMetadata(node, result),
-                    startedAt: nodeStartedAt.toISOString(),
-                    endedAt: new Date().toISOString(),
-                    durationMs: Date.now() - nodeStartedAt.getTime(),
-                    ok: true,
-                    next,
-                    status: result.status,
-                    output: result.output,
-                });
-                const hudCompleted = await this.#publishHudProgressOrRecord(traceWriter, result.status === 'fail' ? 'fail' : 'pass', {
-                    nodeId: activeNodeId,
-                    action,
-                    node,
-                    recipe,
-                    index: transitionCount,
-                    total: Object.keys(graph.nodes).length,
-                    context,
-                });
-                if (!hudCompleted) {
+                        error: message,
+                    });
                     status = 'fail';
-                    break;
-                }
-                if (result.status) {
-                    if (runningTeardown) {
-                        status = mainStatus === 'fail' ? 'fail' : result.status;
-                        break;
-                    }
-                    mainStatus = result.status;
-                    if (graph.teardownEntry) {
+                    if (!runningTeardown && graph.teardownEntry) {
+                        mainStatus = 'fail';
                         runningTeardown = true;
                         currentNodeId = graph.teardownEntry;
                         continue;
                     }
-                    status = result.status;
                     break;
                 }
-                currentNodeId = next;
             }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                traceWriter.record({
-                    nodeId: activeNodeId,
-                    action,
-                    ...traceNodeMetadata(node),
-                    startedAt: nodeStartedAt.toISOString(),
-                    endedAt: new Date().toISOString(),
-                    durationMs: Date.now() - nodeStartedAt.getTime(),
-                    ok: false,
-                    error: message,
-                });
-                this.#logger.error(message);
-                await this.#publishHudProgressOrRecord(traceWriter, 'fail', {
-                    nodeId: activeNodeId,
-                    action,
-                    node,
-                    recipe,
-                    index: transitionCount,
-                    total: Object.keys(graph.nodes).length,
-                    context,
-                    error: message,
-                });
-                status = 'fail';
-                if (!runningTeardown && graph.teardownEntry) {
-                    mainStatus = 'fail';
-                    runningTeardown = true;
-                    currentNodeId = graph.teardownEntry;
-                    continue;
+            artifactWriter.register({
+                path: 'summary.json',
+                type: 'summary',
+                label: 'Run summary',
+                category: 'system',
+            });
+            artifactWriter.register({
+                path: 'trace.json',
+                type: 'trace',
+                label: 'Execution trace',
+                category: 'system',
+            });
+            if (status === 'pass') {
+                const runHudStartedAt = new Date();
+                try {
+                    await this.#publishRunHud(status, {
+                        recipe,
+                        projectRoot,
+                        artifactsDir,
+                        env: request.env ?? {},
+                        outputs,
+                    });
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    traceWriter.record({
+                        nodeId: 'recipe-complete:hud',
+                        action: 'app.hud',
+                        startedAt: runHudStartedAt.toISOString(),
+                        endedAt: new Date().toISOString(),
+                        durationMs: Date.now() - runHudStartedAt.getTime(),
+                        ok: false,
+                        error: message,
+                    });
+                    this.#logger.error(`app.hud complete update failed: ${message}`);
+                    status = 'fail';
                 }
-                break;
             }
-        }
-        artifactWriter.register({
-            path: 'summary.json',
-            type: 'summary',
-            label: 'Run summary',
-            category: 'system',
-        });
-        artifactWriter.register({
-            path: 'trace.json',
-            type: 'trace',
-            label: 'Execution trace',
-            category: 'system',
-        });
-        if (status === 'pass') {
-            const runHudStartedAt = new Date();
-            try {
-                await this.#publishRunHud(status, {
-                    recipe,
-                    projectRoot,
-                    artifactsDir,
-                    env: request.env ?? {},
-                    outputs,
-                });
+            if (runRecording) {
+                const recordingToStop = runRecording;
+                runRecording = undefined;
+                try {
+                    const videoArtifact = await this.#stopRunVideoRecording(recordingToStop);
+                    artifactWriter.register(videoArtifact);
+                }
+                catch (error) {
+                    const message = errorMessage(error);
+                    await removePartialRunVideoOutput(recordingToStop.outputPath, this.#logger);
+                    traceWriter.record({
+                        nodeId: 'recipe-run:video',
+                        action: 'record.video',
+                        startedAt: startedAt.toISOString(),
+                        endedAt: new Date().toISOString(),
+                        durationMs: Date.now() - startedAt.getTime(),
+                        ok: false,
+                        error: message,
+                    });
+                    this.#logger.error(`record.video failed: ${message}`);
+                    status = 'fail';
+                }
             }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                traceWriter.record({
-                    nodeId: 'recipe-complete:hud',
-                    action: 'app.hud',
-                    startedAt: runHudStartedAt.toISOString(),
-                    endedAt: new Date().toISOString(),
-                    durationMs: Date.now() - runHudStartedAt.getTime(),
-                    ok: false,
-                    error: message,
-                });
-                this.#logger.error(`app.hud complete update failed: ${message}`);
-                status = 'fail';
+        }
+        finally {
+            if (runRecording) {
+                const recordingToCleanup = runRecording;
+                runRecording = undefined;
+                await cleanupAbortedRunVideoRecording(recordingToCleanup, this.#logger);
             }
         }
         const endedAt = new Date();
@@ -444,6 +502,76 @@ class DefaultRecipeRunner {
             logger: this.#logger,
         };
     }
+    #videoRecorder() {
+        return this.#recording?.videoRecorder ?? createCaptureHelperVideoRecorder();
+    }
+    async #startRunVideoRecording({ recorder, videoOptions, recipe, projectRoot, artifactsDir, env, }) {
+        const doctor = await recorder.doctor?.();
+        if (doctor && !doctor.ok) {
+            throw new Error(`${recorder.name} doctor ${doctor.code}: ${doctor.message}${doctor.suggestedFix ? ` Suggested fix: ${doctor.suggestedFix}` : ''}`);
+        }
+        const node = {
+            action: 'record.video',
+            intent: 'Record the recipe run when motion proof is useful',
+        };
+        const target = videoOptions.target ??
+            (await this.#recording?.targetProvider?.resolveRecordingTarget({
+                nodeId: 'recipe-run',
+                node,
+                recipe,
+                projectRoot,
+                artifactsDir,
+                env,
+                scope: 'run',
+            }));
+        if (!target) {
+            throw new Error('--record-video requires a recording target. Provide a project RecordingTargetProvider or CLI target flags.');
+        }
+        const relativePath = 'videos/recipe-run.mp4';
+        const outputPath = path.join(artifactsDir, relativePath);
+        await mkdir(path.dirname(outputPath), { recursive: true });
+        let recording;
+        try {
+            recording = await recorder.start({
+                outputPath,
+                target,
+                maxFps: videoOptions.maxFps,
+                maxSize: videoOptions.maxSize,
+                nodeId: 'recipe-run',
+                record: 'full_run',
+            });
+        }
+        catch (error) {
+            await removePartialRunVideoOutput(outputPath, this.#logger);
+            throw error;
+        }
+        const entry = {
+            path: relativePath,
+            type: 'video',
+            mimeType: 'video/mp4',
+            category: 'proof',
+            label: 'Recipe run video',
+            record: 'full_run',
+            recorder: {
+                name: recorder.name,
+                ...(recorder.version ? { version: recorder.version } : {}),
+                ...(recorder.platform ? { platform: recorder.platform } : {}),
+                target: manifestTarget(target),
+            },
+            ...(videoOptions.maxFps != null ? { maxFps: videoOptions.maxFps } : {}),
+        };
+        return { recording, entry, outputPath };
+    }
+    async #stopRunVideoRecording(runRecording) {
+        const result = await runRecording.recording.stop();
+        await assertVideoOutputReady(runRecording.outputPath);
+        return result.recorder
+            ? {
+                ...runRecording.entry,
+                recorder: result.recorder,
+            }
+            : runRecording.entry;
+    }
     #hudAction() {
         if (this.#hud === false || this.#hud?.enabled === false)
             return undefined;
@@ -529,4 +657,35 @@ class DefaultRecipeRunner {
         return 'Recipe run';
     }
 }
+function normalizeVideoRecordingOptions(input) {
+    if (!input)
+        return { mode: 'off' };
+    if (input === true)
+        return { mode: 'full-run' };
+    if (typeof input === 'string')
+        return normalizeVideoRecordingMode(input);
+    const mode = input.mode ?? 'full-run';
+    return { ...input, mode: normalizeVideoRecordingMode(mode).mode };
+}
+function normalizeVideoRecordingMode(mode) {
+    if (mode === 'off')
+        return { mode: 'off' };
+    if (mode === 'full-run')
+        return { mode: 'full-run' };
+    if (mode === 'proof-window' || mode === 'proof_window') {
+        throw new Error('recordVideo proof-window mode is reserved for future focused clips; use full-run for phase 1.');
+    }
+    throw new Error(`recordVideo mode must be full-run or off, got ${JSON.stringify(mode)}.`);
+}
+async function assertVideoOutputReady(outputPath) {
+    let stats;
+    try {
+        stats = await stat(outputPath);
+    }
+    catch {
+        throw new Error(`Recording output is missing: ${outputPath}`);
+    }
+    if (stats.size <= 0)
+        throw new Error(`Recording output is empty: ${outputPath}`);
+}
 //# sourceMappingURL=runner.js.map