@studio-foundation/engine 0.4.0-beta → 0.6.0

package/dist/pipeline/map-orchestrator.js

@@ -0,0 +1,283 @@
+// MapOrchestrator — executes a fan-out (map) stage.
+//
+// A map stage runs a sub-pipeline once per item of a list and collects the
+// structured outputs. It replaces the "shell `studio run <pipeline>` per item
+// + parse stdout + scrape the run log" glue: child runs are spawned in-process
+// through the engine's RunSpawner and each returns its last-stage output
+// directly — no scraping, no tempfiles.
+//
+// Concurrency is bounded by `concurrency` (default 1 = sequential). The
+// per-item failure policy is `on_item_failure`:
+//   - fail-fast (default): stop launching new items on the first failure; the
+//     stage fails. In-flight items are allowed to finish.
+//   - collect-all: run every item regardless; the stage succeeds as long as at
+//     least one item succeeded (or the list was empty). Per-item failures are
+//     surfaced in the output, never fatal — the pipeline keeps going.
+import { randomUUID } from 'node:crypto';
+import { resolveContextPath, evaluateCondition } from './condition-evaluator.js';
+import { buildItemInput, mapItemLabel } from './map-input.js';
+import { hashItemInput } from './map-item-cache.js';
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export class MapOrchestrator {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async run(map, context, stageIndex, totalStages, runId, depth, pipelineName, signal) {
+        const startedAt = new Date().toISOString();
+        const stageRun = {
+            id: randomUUID(),
+            stage_name: map.map,
+            status: 'running',
+            started_at: startedAt,
+            tasks: [],
+        };
+        const finish = (status, output, skippedReason) => {
+            stageRun.status = status;
+            stageRun.completed_at = new Date().toISOString();
+            if (output !== undefined)
+                stageRun.output = output;
+            if (skippedReason)
+                stageRun.skipped_reason = skippedReason;
+            this.config.events?.onStageComplete?.({
+                stage_name: map.map,
+                stage_index: stageIndex,
+                total_stages: totalStages,
+                status,
+                attempts: 1,
+                duration_ms: Date.now() - new Date(startedAt).getTime(),
+                ...(output ? { output } : {}),
+                ...(skippedReason ? { skipped_reason: skippedReason } : {}),
+            });
+            this.config.emitter.emit({ type: 'stage_complete', stageId: stageRun.id, stageName: map.map });
+            return { status, stageRun, output };
+        };
+        // Technical failure (bad `over`, missing spawner, depth limit) — record the
+        // reason on the stage as a failed task so it surfaces in `studio status`,
+        // the run JSONL, and the CLI's "Errors:" line, then fail the stage.
+        const failTechnical = (reason) => {
+            const now = new Date().toISOString();
+            const taskRun = {
+                id: randomUUID(),
+                task_name: map.map,
+                status: 'failed',
+                started_at: startedAt,
+                completed_at: now,
+                agent_runs: [{
+                        id: randomUUID(),
+                        agent_name: `map:${map.pipeline}`,
+                        attempt: 1,
+                        status: 'failed',
+                        tool_calls: 0,
+                        started_at: startedAt,
+                        completed_at: now,
+                        error: reason,
+                    }],
+            };
+            stageRun.tasks = [taskRun];
+            return finish('failed');
+        };
+        this.config.events?.onStageStart?.({
+            stage_name: map.map,
+            stage_index: stageIndex,
+            total_stages: totalStages,
+            max_attempts: 1,
+        });
+        this.config.emitter.emit({ type: 'stage_start', stageId: stageRun.id, stageName: map.map });
+        // Condition — skip the whole fan-out if false
+        if (map.condition !== undefined) {
+            const shouldRun = evaluateCondition(map.condition, {
+                input: context.input,
+                stageOutputs: context.stageOutputs,
+            });
+            if (!shouldRun) {
+                return finish('skipped', undefined, `condition not met: ${map.condition}`);
+            }
+        }
+        if (signal?.aborted)
+            return finish('cancelled');
+        // A map stage spawns child runs — it needs a spawner.
+        if (!this.config.spawner) {
+            return failTechnical(`Map stage '${map.map}' requires a run spawner, but none is configured. ` +
+                `Fan-out stages spawn sub-pipeline runs; construct the engine with a 'spawner'.`);
+        }
+        const spawner = this.config.spawner;
+        // Resolve the list to iterate.
+        const resolved = resolveContextPath(map.over, {
+            input: context.input,
+            stageOutputs: context.stageOutputs,
+        });
+        if (!Array.isArray(resolved)) {
+            return failTechnical(`Map stage '${map.map}': 'over: ${map.over}' did not resolve to an array ` +
+                `(got ${resolved === undefined ? 'undefined' : typeof resolved}). ` +
+                `It must reference a list, e.g. stages.<name>.output.items or input.items.`);
+        }
+        const items = resolved;
+        const concurrency = Math.max(1, map.concurrency ?? 1);
+        const failFast = (map.on_item_failure ?? 'fail-fast') === 'fail-fast';
+        this.config.events?.onMapStart?.({ map_name: map.map, total_items: items.length, concurrency });
+        this.config.emitter.emit({ type: 'map_start', mapName: map.map, totalItems: items.length });
+        if (items.length === 0) {
+            const emptyOutput = { total: 0, succeeded: 0, failed: 0, resumed: 0, results: [], outputs: [] };
+            this.config.events?.onMapComplete?.({ map_name: map.map, total: 0, succeeded: 0, failed: 0, status: 'success' });
+            this.config.emitter.emit({ type: 'map_complete', mapName: map.map, succeeded: 0, failed: 0, status: 'success' });
+            return finish('success', emptyOutput);
+        }
+        // Depth guard — mirror studio_run's recursion limit.
+        if (depth + 1 > this.config.maxDepth) {
+            return failTechnical(`Map stage '${map.map}' would spawn runs at depth ${depth + 1}, exceeding maxDepth ${this.config.maxDepth}. ` +
+                `Recursive fan-out is not allowed at this nesting level.`);
+        }
+        // Per-item resume — skip items a previous run already completed. Opt-in
+        // (`resume: true`) and a no-op without a configured cache. The key is the
+        // item *input*, so a reordered/filtered list still hits and a changed item
+        // misses (see MapStage.resume docs). Failures are never cached, so they
+        // retry next run; a cache-served item counts as a success and never trips
+        // fail-fast.
+        const resumeEnabled = map.resume === true && this.config.cache !== undefined;
+        const cache = this.config.cache;
+        const namespace = {
+            pipeline: pipelineName,
+            stage: map.map,
+            subPipeline: map.pipeline,
+        };
+        const results = new Array(items.length);
+        let cursor = 0;
+        let abortLaunch = false; // fail-fast: stop pulling new items after a failure
+        const worker = async () => {
+            for (;;) {
+                if (signal?.aborted || abortLaunch)
+                    return;
+                const i = cursor++;
+                if (i >= items.length)
+                    return;
+                const label = mapItemLabel(items[i], i);
+                // Resume check — before announcing the item as started, so a cache hit
+                // is served without a spinner. buildItemInput can throw for a bad item;
+                // fall through to the normal path, which surfaces that as an item failure.
+                let itemInput;
+                let cached;
+                if (resumeEnabled && cache) {
+                    try {
+                        itemInput = buildItemInput(map, items[i], i, context.input);
+                        cached = await cache.get(namespace, hashItemInput(itemInput));
+                    }
+                    catch {
+                        itemInput = undefined;
+                        cached = undefined;
+                    }
+                }
+                if (cached) {
+                    const itemResult = {
+                        index: i,
+                        status: 'success',
+                        output: cached.output,
+                        cached: true,
+                        ...(cached.run_id ? { run_id: cached.run_id } : {}),
+                    };
+                    results[i] = itemResult;
+                    this.config.events?.onMapItemComplete?.({
+                        map_name: map.map,
+                        index: i,
+                        total_items: items.length,
+                        status: 'success',
+                        label,
+                        cached: true,
+                        ...(cached.run_id ? { run_id: cached.run_id } : {}),
+                    });
+                    this.config.emitter.emit({ type: 'map_item_complete', mapName: map.map, index: i, status: 'success' });
+                    continue;
+                }
+                // Name the item as it goes in flight, so a --live operator sees which
+                // items are running right now (not just an advancing count).
+                this.config.events?.onMapItemStart?.({
+                    map_name: map.map,
+                    index: i,
+                    total_items: items.length,
+                    label,
+                });
+                let itemResult;
+                try {
+                    const input = itemInput ?? buildItemInput(map, items[i], i, context.input);
+                    const spawn = await spawner.spawnAndWait({
+                        pipeline: map.pipeline,
+                        input,
+                        parentRunId: runId,
+                        depth: depth + 1,
+                    });
+                    itemResult = { index: i, status: 'success', output: spawn.output, run_id: spawn.run_id };
+                    // Only successful items are cached — a failure stays un-cached so it
+                    // retries next run.
+                    if (resumeEnabled && cache) {
+                        await cache.set(namespace, hashItemInput(input), {
+                            output: spawn.output,
+                            run_id: spawn.run_id,
+                            cached_at: new Date().toISOString(),
+                        });
+                    }
+                }
+                catch (err) {
+                    itemResult = { index: i, status: 'failed', error: errorMessage(err) };
+                    if (failFast)
+                        abortLaunch = true;
+                }
+                results[i] = itemResult;
+                this.config.events?.onMapItemComplete?.({
+                    map_name: map.map,
+                    index: i,
+                    total_items: items.length,
+                    status: itemResult.status,
+                    label,
+                    ...(itemResult.run_id ? { run_id: itemResult.run_id } : {}),
+                    ...(itemResult.error ? { error: itemResult.error } : {}),
+                });
+                this.config.emitter.emit({ type: 'map_item_complete', mapName: map.map, index: i, status: itemResult.status });
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, () => worker()));
+        // Cancelled mid-flight → cancelled (don't report success/failure of a partial batch).
+        if (signal?.aborted)
+            return finish('cancelled');
+        const settled = results.filter((r) => r !== undefined);
+        settled.sort((a, b) => a.index - b.index);
+        const succeeded = settled.filter(r => r.status === 'success');
+        const failed = settled.filter(r => r.status === 'failed');
+        const output = {
+            total: items.length,
+            succeeded: succeeded.length,
+            failed: failed.length,
+            resumed: succeeded.filter(r => r.cached).length,
+            results: settled,
+            outputs: succeeded.map(r => r.output),
+        };
+        // Status policy:
+        //   fail-fast   → any failure fails the stage.
+        //   collect-all → succeeds as long as at least one item succeeded; a batch
+        //                 where every item failed is a real failure, not per-item noise.
+        let status;
+        if (failFast) {
+            status = failed.length > 0 ? 'failed' : 'success';
+        }
+        else {
+            status = succeeded.length > 0 ? 'success' : 'failed';
+        }
+        this.config.events?.onMapComplete?.({
+            map_name: map.map,
+            total: items.length,
+            succeeded: succeeded.length,
+            failed: failed.length,
+            status,
+        });
+        this.config.emitter.emit({
+            type: 'map_complete',
+            mapName: map.map,
+            succeeded: succeeded.length,
+            failed: failed.length,
+            status,
+        });
+        return finish(status, output);
+    }
+}
+//# sourceMappingURL=map-orchestrator.js.map

package/dist/pipeline/map-orchestrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-orchestrator.js","sourceRoot":"","sources":["../../src/pipeline/map-orchestrator.ts"],"names":[],"mappings":"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"}

package/dist/pipeline/output-checker.d.ts

@@ -0,0 +1,3 @@
+import type { ExpectedOutputs, ValidationResult } from '@studio-foundation/contracts';
+export declare function checkExpectedOutputs(expected: ExpectedOutputs | undefined, cwd: string): Promise<ValidationResult>;
+//# sourceMappingURL=output-checker.d.ts.map

package/dist/pipeline/output-checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-checker.d.ts","sourceRoot":"","sources":["../../src/pipeline/output-checker.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAEtF,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,eAAe,GAAG,SAAS,EACrC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,gBAAgB,CAAC,CAa3B"}

package/dist/pipeline/output-checker.js

@@ -0,0 +1,40 @@
+// Post-execution filesystem check for a stage's declared outputs.
+//
+// A stage returning "success" only proves the agent finished — not that it
+// actually wrote the files it was supposed to. This is the orchestrator
+// responsibility that was previously bolted onto callers (e.g. run_wiki.py's
+// `check_outputs`/`required_files`: "succeeded but expected files are missing").
+// Declaring `expected_outputs.files` in the contract moves that check into the
+// engine, where it belongs.
+//
+// Each entry is a path or glob relative to the repo workspace and must match at
+// least one existing file. A miss is a validation error, so it flows into the
+// RALPH loop like any other validator: the agent gets a retry with enriched
+// feedback, and the stage fails only once attempts are exhausted.
+import { glob } from 'node:fs/promises';
+export async function checkExpectedOutputs(expected, cwd) {
+    if (!expected?.files || expected.files.length === 0) {
+        return { valid: true, errors: [], warnings: [] };
+    }
+    const errors = [];
+    for (const pattern of expected.files) {
+        if (!(await matchesAny(pattern, cwd))) {
+            errors.push(`Expected output missing: no file matches '${pattern}'`);
+        }
+    }
+    return { valid: errors.length === 0, errors, warnings: [] };
+}
+/** True as soon as one path matches the pattern under cwd. Fails closed on error. */
+async function matchesAny(pattern, cwd) {
+    try {
+        for await (const _match of glob(pattern, { cwd })) {
+            return true;
+        }
+    }
+    catch {
+        // An unreadable directory or bad pattern → treat as "not found", not a crash.
+        return false;
+    }
+    return false;
+}
+//# sourceMappingURL=output-checker.js.map

package/dist/pipeline/output-checker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-checker.js","sourceRoot":"","sources":["../../src/pipeline/output-checker.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,2EAA2E;AAC3E,wEAAwE;AACxE,6EAA6E;AAC7E,iFAAiF;AACjF,+EAA+E;AAC/E,4BAA4B;AAC5B,EAAE;AACF,gFAAgF;AAChF,8EAA8E;AAC9E,4EAA4E;AAC5E,kEAAkE;AAClE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAGxC,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,QAAqC,EACrC,GAAW;IAEX,IAAI,CAAC,QAAQ,EAAE,KAAK,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IACnD,CAAC;IAED,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;QACrC,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;YACtC,MAAM,CAAC,IAAI,CAAC,6CAA6C,OAAO,GAAG,CAAC,CAAC;QACvE,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AAC9D,CAAC;AAED,qFAAqF;AACrF,KAAK,UAAU,UAAU,CAAC,OAAe,EAAE,GAAW;IACpD,IAAI,CAAC;QACH,IAAI,KAAK,EAAE,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;YAClD,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,8EAA8E;QAC9E,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/pipeline/output-checker.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=output-checker.test.d.ts.map

package/dist/pipeline/output-checker.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-checker.test.d.ts","sourceRoot":"","sources":["../../src/pipeline/output-checker.test.ts"],"names":[],"mappings":""}

package/dist/pipeline/output-checker.test.js

@@ -0,0 +1,62 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { checkExpectedOutputs } from './output-checker.js';
+describe('checkExpectedOutputs', () => {
+    let dir;
+    beforeEach(async () => {
+        dir = await mkdtemp(join(tmpdir(), 'output-checker-'));
+    });
+    afterEach(async () => {
+        await rm(dir, { recursive: true, force: true });
+    });
+    it('is valid when there are no expected outputs', async () => {
+        expect(await checkExpectedOutputs(undefined, dir)).toEqual({
+            valid: true,
+            errors: [],
+            warnings: [],
+        });
+        expect((await checkExpectedOutputs({ files: [] }, dir)).valid).toBe(true);
+    });
+    it('passes when a declared literal file exists', async () => {
+        await writeFile(join(dir, 'wiki_pages.json'), '{}');
+        const res = await checkExpectedOutputs({ files: ['wiki_pages.json'] }, dir);
+        expect(res.valid).toBe(true);
+        expect(res.errors).toEqual([]);
+    });
+    it('fails when a declared literal file is missing', async () => {
+        const res = await checkExpectedOutputs({ files: ['wiki_pages.json'] }, dir);
+        expect(res.valid).toBe(false);
+        expect(res.errors).toEqual([
+            "Expected output missing: no file matches 'wiki_pages.json'",
+        ]);
+    });
+    it('passes when a glob pattern matches at least one file', async () => {
+        await writeFile(join(dir, 'batch_1.json'), '{}');
+        await writeFile(join(dir, 'batch_2.json'), '{}');
+        const res = await checkExpectedOutputs({ files: ['batch_*.json'] }, dir);
+        expect(res.valid).toBe(true);
+    });
+    it('fails when a glob pattern matches nothing', async () => {
+        const res = await checkExpectedOutputs({ files: ['batch_*.json'] }, dir);
+        expect(res.valid).toBe(false);
+        expect(res.errors[0]).toContain('batch_*.json');
+    });
+    it('matches files in nested directories', async () => {
+        await mkdir(join(dir, 'out'), { recursive: true });
+        await writeFile(join(dir, 'out', 'result.md'), '# hi');
+        expect((await checkExpectedOutputs({ files: ['out/result.md'] }, dir)).valid).toBe(true);
+        expect((await checkExpectedOutputs({ files: ['**/*.md'] }, dir)).valid).toBe(true);
+    });
+    it('reports one error per missing entry and passes the present ones', async () => {
+        await writeFile(join(dir, 'present.json'), '{}');
+        const res = await checkExpectedOutputs({ files: ['present.json', 'missing_a.json', 'missing_b.json'] }, dir);
+        expect(res.valid).toBe(false);
+        expect(res.errors).toHaveLength(2);
+        expect(res.errors.some((e) => e.includes('missing_a.json'))).toBe(true);
+        expect(res.errors.some((e) => e.includes('missing_b.json'))).toBe(true);
+        expect(res.errors.some((e) => e.includes('present.json'))).toBe(false);
+    });
+});
+//# sourceMappingURL=output-checker.test.js.map

package/dist/pipeline/output-checker.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-checker.test.js","sourceRoot":"","sources":["../../src/pipeline/output-checker.test.ts"],"names":[],"mappings":"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"}

package/dist/pipeline/stage-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stage-executor.d.ts","sourceRoot":"","sources":["../../src/pipeline/stage-executor.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,eAAe,EAMhB,MAAM,8BAA8B,CAAC;AAgBtC,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAErB,uBAAuB,EACxB,MAAM,2BAA2B,CAAC;AAKnC,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,0BAA0B,CAAC;AAMlC,OAAO,KAAK,EAAE,YAAY,EAAqB,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAY5D,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,OAAO,EAAE,oBAAoB,CAAC;IAC9B,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACxC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,aAAa;IACZ,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,mBAAmB;IAEzC,OAAO,CACX,QAAQ,EAAE,eAAe,EACzB,eAAe,EAAE,eAAe,EAChC,iBAAiB,EAAE,MAAM,GAAG,SAAS,EACrC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3C,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,YAAY,EACnB,YAAY,EAAE,YAAY,GAAG,SAAS,EACtC,aAAa,CAAC,EAAE,uBAAuB,GAAG,IAAI,EAC9C,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,WAAW,CAAC;IA6dvB,OAAO,CAAC,cAAc;IAsDtB,OAAO,CAAC,oBAAoB;YAgBd,aAAa;CAa5B"}
+{"version":3,"file":"stage-executor.d.ts","sourceRoot":"","sources":["../../src/pipeline/stage-executor.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,eAAe,EAMhB,MAAM,8BAA8B,CAAC;AAgBtC,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAErB,uBAAuB,EACxB,MAAM,2BAA2B,CAAC;AAMnC,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,0BAA0B,CAAC;AAQlC,OAAO,KAAK,EAAE,YAAY,EAAqB,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAY5D,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,OAAO,EAAE,oBAAoB,CAAC;IAC9B,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACxC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,aAAa;IACZ,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,mBAAmB;IAEzC,OAAO,CACX,QAAQ,EAAE,eAAe,EACzB,eAAe,EAAE,eAAe,EAChC,iBAAiB,EAAE,MAAM,GAAG,SAAS,EACrC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3C,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,YAAY,EACnB,YAAY,EAAE,YAAY,GAAG,SAAS,EACtC,aAAa,CAAC,EAAE,uBAAuB,GAAG,IAAI,EAC9C,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,WAAW,CAAC;IAofvB,OAAO,CAAC,cAAc;IAqEtB,OAAO,CAAC,oBAAoB;YAgBd,aAAa;CAa5B"}

package/dist/pipeline/stage-executor.js

@@ -4,6 +4,7 @@ import { randomUUID } from 'node:crypto';
 import { join } from 'node:path';
 import { ralph, validateSchema, validateToolCalls, validateRequiredTools, validateCountedTools, validateToolGroups, compose, exponentialBackoff, fixedDelay, noDelay, } from '@studio-foundation/ralph';
 import { runAgent, runScript, AnonymizationMiddleware, } from '@studio-foundation/runner';
+import { buildTaskInput } from './task-input.js';
 import { loadAgentProfile } from './agent-loader.js';
 import { loadContract } from './contract-loader.js';
 import { loadSkillFiles } from './skill-loader.js';
@@ -13,6 +14,8 @@ import { evaluateCondition } from './condition-evaluator.js';
 import { deriveStageStatus } from '../state/status-derivation.js';
 import { transition } from '../state/state-machine.js';
 import { postValidate } from './post-validator.js';
+import { runExternalValidators } from './external-validator.js';
+import { checkExpectedOutputs } from './output-checker.js';
 import { loadContextPacks } from './context-pack-loader.js';
 // Module-level helpers — verbatim from engine.ts lines 73-95
 function summarizeOutput(output) {
@@ -139,7 +142,7 @@ export class StageExecutor {
             };
             this.config.events.onStageContext(contextEvent);
         }
-        // Create a single task run (v7: 1 stage = 1 task = 1 ralph call)
+        // Create a single task run (1 stage = 1 task = 1 ralph call)
         const taskRun = {
             id: randomUUID(),
             task_name: stageDef.name,
@@ -246,10 +249,7 @@ export class StageExecutor {
                 executor: async (execContext) => {
                     const agentRunId = randomUUID();
                     const agentRunStartedAt = new Date().toISOString();
-                    const taskInput = {
-                        description: typeof userInput === 'string' ? userInput : JSON.stringify(userInput),
-                        contract_name: contract?.name,
-                    };
+                    const taskInput = buildTaskInput(userInput, contract?.name);
                     // Map ralph context to runner context
                     const runnerExecContext = {
                         attempt: execContext.attempt,
@@ -299,16 +299,21 @@ export class StageExecutor {
                             cwd: this.config.repoPath ?? this.config.configsDir,
                             timeoutMs: stageDef.timeout_ms,
                         });
-                    // Record agent run
+                    // Record agent run. A terminal executor error (a crashed script, max
+                    // tool iterations) must land on the run as status 'failed' + error —
+                    // otherwise the reason the runner already captured (e.g. a python
+                    // stage's stderr) never reaches `studio status`, the run JSONL, or the
+                    // CLI's "Errors:" line, which read the last agent run's error. (STU-568)
                     const agentRun = {
                         id: agentRunId,
                         agent_name: agentConfig?.name ?? `script:${stageDef.script ?? 'unknown'}`,
                         attempt: execContext.attempt,
-                        status: 'success',
+                        status: result.error ? 'failed' : 'success',
                         tool_calls: result.tool_calls_count,
                         started_at: agentRunStartedAt,
                         completed_at: new Date().toISOString(),
                         output: result.output,
+                        ...(result.error ? { error: result.error } : {}),
                     };
                     taskRun.agent_runs.push(agentRun);
                     return result;
@@ -316,6 +321,12 @@ export class StageExecutor {
                 validator: ralphValidator,
                 maxAttempts: stageDef.ralph?.max_attempts ?? 3,
                 retryStrategy,
+                // A script stage is deterministic: re-running the same command on the
+                // same stdin yields the same result, so a process-level error (a startup
+                // crash, a non-zero exit, a timeout) will not heal on retry. Fail fast
+                // instead of burning every attempt on an identical crash. Agent stages
+                // are stochastic and keep their retries. (STU-568)
+                isFatal: stageDef.agent ? undefined : (result) => result.error != null,
                 signal,
                 onRetry: async (event) => {
                     // Extract raw output for diagnostic logging
@@ -343,6 +354,21 @@ export class StageExecutor {
         catch (err) {
             // AbortError from signal propagation is handled inside ralph (returns 'cancelled').
             // Any other throw is a technical failure (network, timeout, etc.) — mark stage failed.
+            // Record it as a failed agent run: the executor throws before it can push one, so
+            // without this every reader (`studio status`, `logs`, the run JSONL, the CLI's own
+            // "Errors:" line) reports a stage that failed for no stated reason (STU-561).
+            taskRun.agent_runs.push({
+                id: randomUUID(),
+                agent_name: agentConfig?.name ?? `script:${stageDef.script ?? 'unknown'}`,
+                attempt: 1,
+                status: 'failed',
+                tool_calls: 0,
+                started_at: stageStartedAt,
+                completed_at: new Date().toISOString(),
+                error: err instanceof Error ? err.message : String(err),
+            });
+            taskRun.status = 'failed';
+            taskRun.completed_at = new Date().toISOString();
             stageRun.status = transition('running', 'fail');
             stageRun.completed_at = new Date().toISOString();
             stageRun.tasks = [taskRun];
@@ -478,8 +504,8 @@ export class StageExecutor {
         }
         // Compose ralph's built-in validators
         const validators = [errorCheck];
-        // Schema validation (required_fields)
-        if (contract.schema?.required_fields) {
+        // Schema validation (required_fields presence + field-level type/enum/nested)
+        if (contract.schema?.required_fields || contract.schema?.fields) {
             validators.push((result) => validateSchema(result.output, contract));
         }
         // Normalize tool call requirements from contract or stage definition
@@ -501,6 +527,19 @@ export class StageExecutor {
         if (toolCallReqs?.required_tool_groups?.length) {
             validators.push((result) => validateToolGroups(result.tool_calls, toolCallReqs));
         }
+        // External validators — run a command against the REAL output (not tool args).
+        // Enforces what the declarative schema can't (cross-field rules, computed
+        // constraints); field-level types/enums/nesting live in schema.fields.
+        if (contract.validators?.length) {
+            const cwd = this.config.repoPath ?? this.config.configsDir;
+            validators.push((result) => runExternalValidators(result.output, contract.validators, cwd));
+        }
+        // Expected outputs — check the filesystem for the files the stage must leave
+        // on disk. A "success" return code doesn't prove the artifacts exist; this does.
+        if (contract.expected_outputs?.files?.length) {
+            const cwd = this.config.repoPath ?? this.config.configsDir;
+            validators.push(() => checkExpectedOutputs(contract.expected_outputs, cwd));
+        }
         if (validators.length === 0) {
             return () => ({ valid: true, errors: [], warnings: [] });
         }