@proposit/proposit-core 1.10.0 → 2.0.0

package/dist/lib/pipelines/execute.js

@@ -14,7 +14,7 @@
 // with `output: null` for abort; we throw for misconfiguration).
 import { Value } from "typebox/value";
 import { depId, isOptionalDep } from "./types.js";
-import { LlmStageRetryExhaustedError, StageAbortedError, SubPipelineFailedError, readStashedTokenUsage, } from "./stage-helpers.js";
+import { LlmStageRetryExhaustedError, StageAbortedError, SubPipelineFailedError, readStashedTokenUsage, readLlmStageConfig, buildLlmRequest, applyRetrySuffix, validateLlmOutcome, failureRetryReason, } from "./stage-helpers.js";
 import { debugPipelineEnd, debugPipelineStart, debugStageEnd, debugStageStart, } from "./debug-log.js";
 export class PipelineConfigurationError extends Error {
     code;
@@ -113,6 +113,242 @@ function validateDag(pipeline) {
     }
     return { stageById };
 }
+// Build the per-stage / finalize `ctx`. `allowedDeps` is the set of
+// stage ids this context may read (the stage's or finalize's own
+// `dependsOn`); `ctx.get` returns the output only for a `completed`
+// upstream, exactly as the monolithic run does.
+function makeStageContext(state, allowedDeps, contextLabel) {
+    return {
+        input: state.input,
+        get(stageId) {
+            if (!allowedDeps.has(stageId)) {
+                throw new PipelineConfigurationError({
+                    code: "GET_OUTSIDE_DEPS",
+                    message: `${contextLabel} called ctx.get("${stageId}"), which is not in its dependsOn.`,
+                    stageId: contextLabel,
+                    depId: stageId,
+                });
+            }
+            const record = state.records.get(stageId);
+            if (!record)
+                return undefined;
+            if (record.outcome !== "completed")
+                return undefined;
+            return record.output;
+        },
+        stageStatus(stageId) {
+            // Mirror the `ctx.get` strictness: stages may only
+            // query the status of stages declared in their own
+            // `dependsOn` (required OR optional). Querying a
+            // non-dependency is a caller bug — surface it loudly
+            // rather than silently returning "skipped" for a
+            // stage id the calling stage shouldn't be peeking at.
+            if (!allowedDeps.has(stageId)) {
+                throw new PipelineConfigurationError({
+                    code: "STATUS_OUTSIDE_DEPS",
+                    message: `${contextLabel} called ctx.stageStatus("${stageId}"), which is not in its dependsOn.`,
+                    stageId: contextLabel,
+                    depId: stageId,
+                });
+            }
+            const record = state.records.get(stageId);
+            if (record)
+                return record.outcome;
+            return "skipped";
+        },
+        llm: state.llm,
+        generateId: state.generateId,
+        signal: state.signal,
+        emit: state.emit,
+        addFailure: (failure) => {
+            state.failures.push({ ...failure, stage: contextLabel });
+        },
+    };
+}
+// Execute exactly one stage against the supplied `ctx` + `state`. Records
+// the stage's outcome into `state.records`, pushes any failure into
+// `state.failures`, emits the `stage:start` / `stage:end` bookends, and
+// routes a `ctx.get`-on-non-dep `PipelineConfigurationError` through
+// `state.setConfigError`. The single source of truth for per-stage
+// execution semantics, shared by the scheduler and `executeStage`.
+async function runOneStage(stage, ctx, state) {
+    const stageDeps = stage.dependsOn.map((d) => depId(d));
+    const stageStartAt = now();
+    const finishStage = (args) => {
+        const endAt = now();
+        const event = args.tokenUsage !== undefined
+            ? {
+                kind: "stage:end",
+                stageId: stage.id,
+                status: args.status,
+                tokenUsage: args.tokenUsage,
+                at: endAt,
+            }
+            : {
+                kind: "stage:end",
+                stageId: stage.id,
+                status: args.status,
+                at: endAt,
+            };
+        state.emit(event);
+        debugStageEnd({
+            stageId: stage.id,
+            status: args.status,
+            durationMs: endAt - stageStartAt,
+            outputPresence: args.outputPresent
+                ? "present"
+                : "null-or-undefined",
+            tokenUsage: args.tokenUsage,
+        });
+    };
+    if (state.signal.aborted) {
+        // Pending stages don't start once aborted. Emit `stage:start`
+        // before `stage:end` so consumers walking the event stream
+        // for symmetric pairs (e.g. a server SSE bridge) see
+        // a balanced sequence — every `stage:end` is preceded by a
+        // matching `stage:start`.
+        state.emit({ kind: "stage:start", stageId: stage.id, at: stageStartAt });
+        debugStageStart({ stageId: stage.id, deps: stageDeps });
+        state.records.set(stage.id, { outcome: "skipped", output: undefined });
+        finishStage({ status: "skipped", outputPresent: false });
+        return;
+    }
+    state.emit({ kind: "stage:start", stageId: stage.id, at: stageStartAt });
+    debugStageStart({ stageId: stage.id, deps: stageDeps });
+    try {
+        const output = await stage.run(ctx);
+        if (!Value.Check(stage.outputSchema, output)) {
+            const errors = [...Value.Errors(stage.outputSchema, output)];
+            const message = errors
+                .map((e) => `${e.instancePath}: ${e.message}`)
+                .join("; ");
+            state.failures.push({
+                stage: stage.id,
+                code: "OUTPUT_SCHEMA_INVALID",
+                message,
+                severity: "error",
+            });
+            state.records.set(stage.id, {
+                outcome: "failed",
+                output: undefined,
+            });
+            finishStage({ status: "failed", outputPresent: false });
+            return;
+        }
+        const tokenUsage = readStashedTokenUsage(ctx, stage.id);
+        state.records.set(stage.id, {
+            outcome: "completed",
+            output,
+            tokenUsage,
+        });
+        finishStage({
+            status: "completed",
+            tokenUsage,
+            outputPresent: output !== null && output !== undefined,
+        });
+    }
+    catch (err) {
+        if (err instanceof PipelineConfigurationError) {
+            // ctx.get violation — caller bug. Route through the
+            // disposition seam, mark the stage failed for bookkeeping,
+            // and emit stage:end so consumers see a clean per-stage close.
+            state.records.set(stage.id, {
+                outcome: "failed",
+                output: undefined,
+            });
+            finishStage({ status: "failed", outputPresent: false });
+            state.setConfigError(err);
+            return;
+        }
+        if (err instanceof StageAbortedError) {
+            // Caller cancellation surfaced mid-stage. This is not
+            // a stage failure to report — no ProcessingFailure is
+            // recorded — and the outcome is `skipped` rather than
+            // `failed` so consumers can distinguish abort from a
+            // genuine provider error.
+            state.records.set(stage.id, {
+                outcome: "skipped",
+                output: undefined,
+            });
+            finishStage({ status: "skipped", outputPresent: false });
+            return;
+        }
+        if (err instanceof LlmStageRetryExhaustedError) {
+            state.failures.push({
+                stage: stage.id,
+                code: err.code,
+                message: err.message,
+                severity: "error",
+                context: err.failureContext,
+            });
+            state.records.set(stage.id, {
+                outcome: "failed",
+                output: undefined,
+            });
+            finishStage({ status: "failed", outputPresent: false });
+            return;
+        }
+        if (err instanceof SubPipelineFailedError) {
+            state.failures.push({
+                stage: stage.id,
+                code: err.code,
+                message: err.message,
+                severity: "error",
+                context: err.failureContext,
+            });
+            state.records.set(stage.id, {
+                outcome: "failed",
+                output: undefined,
+            });
+            finishStage({ status: "failed", outputPresent: false });
+            return;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        state.failures.push({
+            stage: stage.id,
+            code: "STAGE_UNCAUGHT_ERROR",
+            message,
+            severity: "error",
+        });
+        state.records.set(stage.id, { outcome: "failed", output: undefined });
+        finishStage({ status: "failed", outputPresent: false });
+    }
+}
+// Run the pipeline's finalize against the supplied `ctx` + `state`.
+// Applies the `finalizeRequiredOk()` gate (output stays `null` when a
+// required finalize dep is not `completed`) and captures a thrown
+// finalize as a `FINALIZE_UNCAUGHT_ERROR` failure. The single source of
+// truth for finalize semantics, shared by the scheduler and
+// `executeFinalize`. Returns the finalize output, or `null` when the
+// gate blocks it / the run is aborted / finalize threw.
+function runFinalize(pipeline, ctx, state) {
+    const finalizeRequiredOk = () => {
+        for (const dep of pipeline.finalize.dependsOn) {
+            if (isOptionalDep(dep))
+                continue;
+            const record = state.records.get(depId(dep));
+            if (record?.outcome !== "completed")
+                return false;
+        }
+        return true;
+    };
+    if (!finalizeRequiredOk() || state.signal.aborted) {
+        return null;
+    }
+    try {
+        return pipeline.finalize.run(ctx);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        state.failures.push({
+            stage: "finalize",
+            code: "FINALIZE_UNCAUGHT_ERROR",
+            message,
+            severity: "error",
+        });
+        return null;
+    }
+}
 export async function executePipeline(pipeline, input, deps) {
     // 1. Input validation. A schema mismatch is a caller bug; we throw.
     // Value.Parse infers its return type from the schema; since
@@ -150,6 +386,22 @@ export async function executePipeline(pipeline, input, deps) {
     // first one and re-throw after the scheduler drains so the
     // executor still emits the bookend events.
     let capturedConfigError = null;
+    // The explicit run state shared with the extracted `runOneStage` /
+    // `runFinalize` bodies. The scheduler's disposition for a
+    // `ctx.get`-on-non-dep config error is "capture the first, re-throw
+    // after the bookends" (see the drain-end re-throw below).
+    const state = {
+        records,
+        failures,
+        signal,
+        emit,
+        generateId,
+        llm: deps.llm,
+        input: validatedInput,
+        setConfigError: (error) => {
+            capturedConfigError ??= error;
+        },
+    };
     // Build per-stage `ctx.get` dep sets up front so we can throw on
     // out-of-deps access.
     const stageDepIds = new Map();
@@ -158,55 +410,6 @@ export async function executePipeline(pipeline, input, deps) {
     }
     const finalizeDepIds = new Set(pipeline.finalize.dependsOn.map((d) => depId(d)));
     // -- Helpers --
-    const makeCtx = (allowedDeps, contextLabel) => {
-        const ctx = {
-            input: validatedInput,
-            get(stageId) {
-                if (!allowedDeps.has(stageId)) {
-                    throw new PipelineConfigurationError({
-                        code: "GET_OUTSIDE_DEPS",
-                        message: `${contextLabel} called ctx.get("${stageId}"), which is not in its dependsOn.`,
-                        stageId: contextLabel,
-                        depId: stageId,
-                    });
-                }
-                const record = records.get(stageId);
-                if (!record)
-                    return undefined;
-                if (record.outcome !== "completed")
-                    return undefined;
-                return record.output;
-            },
-            stageStatus(stageId) {
-                // Mirror the `ctx.get` strictness: stages may only
-                // query the status of stages declared in their own
-                // `dependsOn` (required OR optional). Querying a
-                // non-dependency is a caller bug — surface it loudly
-                // rather than silently returning "skipped" for a
-                // stage id the calling stage shouldn't be peeking at.
-                if (!allowedDeps.has(stageId)) {
-                    throw new PipelineConfigurationError({
-                        code: "STATUS_OUTSIDE_DEPS",
-                        message: `${contextLabel} called ctx.stageStatus("${stageId}"), which is not in its dependsOn.`,
-                        stageId: contextLabel,
-                        depId: stageId,
-                    });
-                }
-                const record = records.get(stageId);
-                if (record)
-                    return record.outcome;
-                return "skipped";
-            },
-            llm: deps.llm,
-            generateId,
-            signal,
-            emit,
-            addFailure: (failure) => {
-                failures.push({ ...failure, stage: contextLabel });
-            },
-        };
-        return ctx;
-    };
     const isStageEligible = (stage) => {
         for (const dep of stage.dependsOn) {
             const id = depId(dep);
@@ -236,148 +439,8 @@ export async function executePipeline(pipeline, input, deps) {
     };
     // -- Stage execution --
     const runStage = async (stage) => {
-        const stageDeps = stage.dependsOn.map((d) => depId(d));
-        const stageStartAt = now();
-        const finishStage = (args) => {
-            const endAt = now();
-            const event = args.tokenUsage !== undefined
-                ? {
-                    kind: "stage:end",
-                    stageId: stage.id,
-                    status: args.status,
-                    tokenUsage: args.tokenUsage,
-                    at: endAt,
-                }
-                : {
-                    kind: "stage:end",
-                    stageId: stage.id,
-                    status: args.status,
-                    at: endAt,
-                };
-            emit(event);
-            debugStageEnd({
-                stageId: stage.id,
-                status: args.status,
-                durationMs: endAt - stageStartAt,
-                outputPresence: args.outputPresent
-                    ? "present"
-                    : "null-or-undefined",
-                tokenUsage: args.tokenUsage,
-            });
-        };
-        if (signal.aborted) {
-            // Pending stages don't start once aborted. Emit `stage:start`
-            // before `stage:end` so consumers walking the event stream
-            // for symmetric pairs (e.g. a server SSE bridge) see
-            // a balanced sequence — every `stage:end` is preceded by a
-            // matching `stage:start`.
-            emit({ kind: "stage:start", stageId: stage.id, at: stageStartAt });
-            debugStageStart({ stageId: stage.id, deps: stageDeps });
-            records.set(stage.id, { outcome: "skipped", output: undefined });
-            finishStage({ status: "skipped", outputPresent: false });
-            return;
-        }
-        emit({ kind: "stage:start", stageId: stage.id, at: stageStartAt });
-        debugStageStart({ stageId: stage.id, deps: stageDeps });
-        const ctx = makeCtx(stageDepIds.get(stage.id) ?? new Set(), stage.id);
-        try {
-            const output = await stage.run(ctx);
-            if (!Value.Check(stage.outputSchema, output)) {
-                const errors = [...Value.Errors(stage.outputSchema, output)];
-                const message = errors
-                    .map((e) => `${e.instancePath}: ${e.message}`)
-                    .join("; ");
-                failures.push({
-                    stage: stage.id,
-                    code: "OUTPUT_SCHEMA_INVALID",
-                    message,
-                    severity: "error",
-                });
-                records.set(stage.id, {
-                    outcome: "failed",
-                    output: undefined,
-                });
-                finishStage({ status: "failed", outputPresent: false });
-                return;
-            }
-            const tokenUsage = readStashedTokenUsage(ctx, stage.id);
-            records.set(stage.id, {
-                outcome: "completed",
-                output,
-                tokenUsage,
-            });
-            finishStage({
-                status: "completed",
-                tokenUsage,
-                outputPresent: output !== null && output !== undefined,
-            });
-        }
-        catch (err) {
-            if (err instanceof PipelineConfigurationError) {
-                // ctx.get violation — caller bug. Stash for re-throw,
-                // mark the stage failed for bookkeeping, and emit
-                // stage:end so consumers see a clean per-stage close.
-                records.set(stage.id, {
-                    outcome: "failed",
-                    output: undefined,
-                });
-                finishStage({ status: "failed", outputPresent: false });
-                capturedConfigError ??= err;
-                return;
-            }
-            if (err instanceof StageAbortedError) {
-                // Caller cancellation surfaced mid-stage. This is not
-                // a stage failure to report — no ProcessingFailure is
-                // recorded — and the outcome is `skipped` rather than
-                // `failed` so consumers can distinguish abort from a
-                // genuine provider error.
-                records.set(stage.id, {
-                    outcome: "skipped",
-                    output: undefined,
-                });
-                finishStage({ status: "skipped", outputPresent: false });
-                return;
-            }
-            if (err instanceof LlmStageRetryExhaustedError) {
-                failures.push({
-                    stage: stage.id,
-                    code: err.code,
-                    message: err.message,
-                    severity: "error",
-                    context: err.failureContext,
-                });
-                records.set(stage.id, {
-                    outcome: "failed",
-                    output: undefined,
-                });
-                finishStage({ status: "failed", outputPresent: false });
-                return;
-            }
-            if (err instanceof SubPipelineFailedError) {
-                failures.push({
-                    stage: stage.id,
-                    code: err.code,
-                    message: err.message,
-                    severity: "error",
-                    context: err.failureContext,
-                });
-                records.set(stage.id, {
-                    outcome: "failed",
-                    output: undefined,
-                });
-                finishStage({ status: "failed", outputPresent: false });
-                return;
-            }
-            const message = err instanceof Error ? err.message : String(err);
-            failures.push({
-                stage: stage.id,
-                code: "STAGE_UNCAUGHT_ERROR",
-                message,
-                severity: "error",
-            });
-            records.set(stage.id, { outcome: "failed", output: undefined });
-            finishStage({ status: "failed", outputPresent: false });
-        }
+        const ctx = makeStageContext(state, stageDepIds.get(stage.id) ?? new Set(), stage.id);
+        await runOneStage(stage, ctx, state);
     };
     // -- Scheduler loop --
     //
@@ -499,33 +562,8 @@ export async function executePipeline(pipeline, input, deps) {
         throw err;
     }
     // -- Finalize --
-    let output = null;
-    const finalizeRequiredOk = () => {
-        for (const dep of pipeline.finalize.dependsOn) {
-            if (isOptionalDep(dep))
-                continue;
-            const record = records.get(depId(dep));
-            if (record?.outcome !== "completed")
-                return false;
-        }
-        return true;
-    };
-    if (finalizeRequiredOk() && !signal.aborted) {
-        const finalizeCtx = makeCtx(finalizeDepIds, "finalize");
-        try {
-            output = pipeline.finalize.run(finalizeCtx);
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            failures.push({
-                stage: "finalize",
-                code: "FINALIZE_UNCAUGHT_ERROR",
-                message,
-                severity: "error",
-            });
-            output = null;
-        }
-    }
+    const finalizeCtx = makeStageContext(state, finalizeDepIds, "finalize");
+    const output = runFinalize(pipeline, finalizeCtx, state);
     // Aggregate stage outcomes + token usage.
     const stageOutcomes = {};
     let aggregatedTokens;
@@ -568,4 +606,321 @@ export async function executePipeline(pipeline, input, deps) {
         tokenUsage: aggregatedTokens,
     };
 }
+// Seed a fresh `records` map from the caller-supplied `upstream`,
+// keeping only the entries the consumer (a stage or finalize) actually
+// depends on, and dropping `output` for any non-`completed` record so a
+// caller bug can't leak a stale output into a skipped/failed dependency.
+function seedRecordsFromUpstream(upstream, depIds) {
+    const records = new Map();
+    for (const id of depIds) {
+        const supplied = upstream[id];
+        if (!supplied)
+            continue;
+        if (supplied.outcome === "completed") {
+            records.set(id, {
+                outcome: "completed",
+                output: supplied.output,
+            });
+        }
+        else {
+            records.set(id, {
+                outcome: supplied.outcome,
+                output: undefined,
+            });
+        }
+    }
+    return records;
+}
+// Shared run-state builder for the single-shot entry points. The
+// `setConfigError` disposition differs from the whole-DAG scheduler's:
+// a `ctx.get`-on-non-dep error throws straight out of the entry point
+// (there are no run-level bookends to emit first), so it is surfaced
+// directly to the caller as the caller bug it is.
+function buildSingleShotState(upstream, depIds, input, deps) {
+    return {
+        records: seedRecordsFromUpstream(upstream, depIds),
+        failures: [],
+        signal: deps.signal ?? new AbortController().signal,
+        emit: deps.onEvent ?? noopEmit,
+        generateId: deps.generateId ?? defaultGenerateId,
+        llm: deps.llm,
+        input,
+        setConfigError: (error) => {
+            throw error;
+        },
+    };
+}
+/**
+ * Run a single stage of `pipeline` against the caller-supplied upstream
+ * records, without re-running the whole DAG. The upstream map carries
+ * each dependency's `{ outcome, output? }` so `ctx.get` / `ctx.stageStatus`
+ * reproduce monolithic-run semantics exactly. `input` is validated +
+ * transformed via `Value.Parse(pipeline.inputSchema, input)` (a schema
+ * mismatch throws, same as `executePipeline`) and the PARSED value seeds
+ * `ctx.input`.
+ *
+ * Emits the per-stage events only (`stage:start`, `stage:llm-request`,
+ * `stage:llm-response-created`, `stage:llm-call`, `stage:retry`,
+ * `stage:end`) — no `pipeline:*` bookends. Throws `PipelineConfigurationError`
+ * (`UNKNOWN_STAGE`) when `stageId` is not in `pipeline.stages`, and throws a
+ * `PipelineConfigurationError` (`GET_OUTSIDE_DEPS` / `STATUS_OUTSIDE_DEPS`)
+ * out directly when the stage reads a non-dependency — both are caller
+ * bugs, surfaced rather than swallowed into the result.
+ *
+ * The caller may pass a superset of `upstream` records; `executeStage`
+ * uses the stage's own `dependsOn` to pick the relevant ones. It does NOT
+ * decide whether the stage SHOULD run given its upstream outcomes — a
+ * required-failed upstream just means `ctx.get` returns `undefined`; the
+ * skip decision belongs to the caller's scheduler.
+ */
+export async function executeStage(pipeline, stageId, upstream, input, deps) {
+    const stage = pipeline.stages.find((s) => s.id === stageId);
+    if (!stage) {
+        throw new PipelineConfigurationError({
+            code: "UNKNOWN_STAGE",
+            message: `Pipeline "${pipeline.id}" has no stage "${stageId}".`,
+            stageId,
+        });
+    }
+    // Input-validation parity with `executePipeline`: parse + seed the
+    // PARSED (Default/Convert/Clean-transformed) value into ctx.input.
+    const parsedInput = Value.Parse(pipeline.inputSchema, input);
+    const depIds = new Set(stage.dependsOn.map((d) => depId(d)));
+    const state = buildSingleShotState(upstream, depIds, parsedInput, deps);
+    const ctx = makeStageContext(state, depIds, stage.id);
+    await runOneStage(stage, ctx, state);
+    const record = state.records.get(stage.id);
+    const outcome = record?.outcome ?? "skipped";
+    const result = {
+        outcome,
+        failures: state.failures,
+    };
+    if (outcome === "completed") {
+        result.output = record?.output;
+        if (record?.tokenUsage !== undefined) {
+            result.tokenUsage = record.tokenUsage;
+        }
+    }
+    return result;
+}
+/**
+ * Run `pipeline.finalize` against the caller-supplied upstream records,
+ * without re-running the whole DAG. Symmetric with `executeStage`:
+ * `input` is parsed via `Value.Parse(pipeline.inputSchema, input)` and the
+ * PARSED value seeds the finalize `ctx.input`; the finalize `ctx` is built
+ * with `pipeline.finalize.dependsOn` as its allowed-dep set; the
+ * required-finalize-dep gate (`output` stays `null` if any required dep is
+ * not `completed`) and the `FINALIZE_UNCAUGHT_ERROR` capture match
+ * `executePipeline`.
+ *
+ * Emits NO events (finalize is not a stage — it has no `stage:*`
+ * lifecycle — and there are no `pipeline:*` bookends). `async` purely for
+ * signature symmetry with `executeStage`; `TPipelineFinalize.run` stays
+ * synchronous and the `async` wrapper just resolves its result.
+ */
+// `async` is deliberate (a Promise-returning signature symmetric with
+// `executeStage`, so callers `await` both uniformly) even though the
+// synchronous finalize body has nothing to await — the eslint
+// require-await rule does not apply here.
+// eslint-disable-next-line @typescript-eslint/require-await
+export async function executeFinalize(pipeline, upstream, input, deps) {
+    // Input-validation parity with `executePipeline` (see `executeStage`).
+    const parsedInput = Value.Parse(pipeline.inputSchema, input);
+    const depIds = new Set(pipeline.finalize.dependsOn.map((d) => depId(d)));
+    // Finalize emits no events, so swallow any caller-supplied onEvent.
+    const state = buildSingleShotState(upstream, depIds, parsedInput, {
+        ...deps,
+        onEvent: undefined,
+    });
+    const ctx = makeStageContext(state, depIds, "finalize");
+    const output = runFinalize(pipeline, ctx, state);
+    return { output, failures: state.failures };
+}
+// -- Launch / complete split for LLM-background stages -------------------
+//
+// A durable orchestrator (e.g. a server workflow) cannot block a single
+// step for an LLM call's full duration. `launchStage` submits the
+// background response and returns its `responseId` WITHOUT awaiting;
+// `completeStage` — in a later invocation, after the response completed —
+// validates the retrieved response into a `TExecuteStageResult`. Both
+// reuse the package-internal `llmStage` seam (`buildLlmRequest` /
+// `validateLlmOutcome`) so prompt assembly + output validation have a
+// single implementation shared with the in-process `llmStage` loop.
+// Resolve the LLM config carried by an `llmStage`-built stage, or throw a
+// clear error when the looked-up stage is not an LLM stage (no carrier).
+function requireLlmStage(pipeline, stageId, fnName) {
+    const stage = pipeline.stages.find((s) => s.id === stageId);
+    if (!stage) {
+        throw new PipelineConfigurationError({
+            code: "UNKNOWN_STAGE",
+            message: `Pipeline "${pipeline.id}" has no stage "${stageId}".`,
+            stageId,
+        });
+    }
+    const cfg = readLlmStageConfig(stage);
+    if (!cfg) {
+        throw new PipelineConfigurationError({
+            code: "UNKNOWN_STAGE",
+            message: `${fnName} requires an LLM stage, but stage "${stageId}" in pipeline "${pipeline.id}" is not one (it carries no LLM config). Run deterministic stages via executeStage.`,
+            stageId,
+        });
+    }
+    return { stage, cfg };
+}
+/**
+ * Launch an LLM-background stage: rehydrate `ctx` from `upstream` +
+ * parsed input, build the request via the shared seam, submit it via the
+ * injected `deps.submitBackgroundResponse`, and return
+ * `{ responseId, status }` WITHOUT awaiting completion.
+ *
+ * Emits `stage:start`, `stage:llm-request`, and `stage:llm-response-created`
+ * (from the submit's returned id) — but NO `stage:llm-call` / `stage:end`
+ * (the completion side emits those, in a later invocation). The
+ * per-stage event pair therefore spans two invocations; an `onEvent`
+ * consumer must NOT assume a balanced start↔end per call.
+ *
+ * `deps.submitBackgroundResponse` is REQUIRED; `launchStage` throws if it
+ * is absent. `stageId` must name an LLM stage (built by `llmStage`);
+ * a non-LLM stage throws. `attempt` (default 1) lets a re-launch rebuild
+ * the retry-suffixed user message for attempt 2+.
+ */
+export async function launchStage(pipeline, stageId, upstream, input, deps, attempt = 1) {
+    const submit = deps.submitBackgroundResponse;
+    if (!submit) {
+        throw new PipelineConfigurationError({
+            code: "UNKNOWN_STAGE",
+            message: `launchStage requires deps.submitBackgroundResponse (the submit-only background-response capability), but it was not supplied.`,
+            stageId,
+        });
+    }
+    const { stage, cfg } = requireLlmStage(pipeline, stageId, "launchStage");
+    // Input-validation parity: parse + seed the parsed ctx.input. The
+    // stage's `ctx` reads its own dependsOn as allowed deps.
+    const parsedInput = Value.Parse(pipeline.inputSchema, input);
+    const allowedDeps = new Set(stage.dependsOn.map((d) => depId(d)));
+    const state = buildSingleShotState(upstream, allowedDeps, parsedInput, deps);
+    const ctx = makeStageContext(state, allowedDeps, stageId);
+    // Compute the per-attempt user message. Attempt 1 is the prompt's
+    // user message; attempt 2+ appends the same retry-suffix the
+    // in-process loop adds after a schema-validation failure (the shared
+    // `applyRetrySuffix` helper). The exact prior-attempt validation
+    // error does not cross the durable suspend, so the re-launch suffix
+    // carries a generic prior-error note — the wrapper text matches the
+    // in-process loop's phrasing.
+    const baseUser = cfg.buildPrompt(ctx).user;
+    const userMessage = attempt > 1
+        ? applyRetrySuffix(baseUser, "the previous attempt's output did not conform to the schema", cfg.retryPolicy.maxAppendedErrorBytes ?? 2048)
+        : baseUser;
+    const { req } = buildLlmRequest(cfg, ctx, userMessage);
+    state.emit({ kind: "stage:start", stageId, at: now() });
+    state.emit({
+        kind: "stage:llm-request",
+        stageId,
+        attempt,
+        prompts: { system: req.systemPrompt, user: req.userMessage },
+        at: now(),
+    });
+    // The req is already TLlmRequest<unknown> (the recovered config is
+    // generic-erased at the lookup boundary); the typed output is
+    // recovered in completeStage via the stage's outputSchema.
+    const submitResult = await submit(req, {
+        apiKey: resolveApiKey(deps),
+        signal: deps.signal,
+    });
+    state.emit({
+        kind: "stage:llm-response-created",
+        stageId,
+        attempt,
+        responseId: submitResult.responseId,
+        at: now(),
+    });
+    return submitResult;
+}
+/**
+ * Complete an LLM-background stage from its retrieved response. Recovers
+ * the stage's LLM config, parses the RAW assistant text in
+ * `retrieved.output` against the stage's schema (via the shared seam),
+ * classifies a non-`completed` status per the launch/complete table, and
+ * returns the standard `TExecuteStageResult`.
+ *
+ * Emits `stage:llm-call` + `stage:end` (NO `stage:start` — that fired in
+ * the launch invocation). `tokenUsage` is taken directly from
+ * `retrieved.tokenUsage` (the per-`ctx` WeakMap cannot bridge the two
+ * invocations). On a RETRYABLE failure the result carries `retryReason`
+ * (the reason code); a fail-fast failure (`failed` envelope,
+ * `content_filter`) carries none; a `cancelled` response settles as
+ * `outcome: "skipped"` with no `ProcessingFailure`.
+ *
+ * `stageId` must name an LLM stage; a non-LLM stage throws.
+ */
+// eslint-disable-next-line @typescript-eslint/require-await
+export async function completeStage(pipeline, stageId, retrieved, deps, attempt = 1) {
+    const { cfg } = requireLlmStage(pipeline, stageId, "completeStage");
+    const emit = deps.onEvent ?? noopEmit;
+    const validated = validateLlmOutcome(cfg, retrieved.output, retrieved.status, retrieved.incompleteReason);
+    // The output shown on stage:llm-call is the parsed value when the
+    // response parsed + validated; otherwise the raw assistant text (so a
+    // consumer's bridge can persist whatever the model returned).
+    const callOutput = validated.output !== undefined ? validated.output : retrieved.output;
+    emit({
+        kind: "stage:llm-call",
+        stageId,
+        attempt,
+        prompts: { system: "", user: "" },
+        output: callOutput,
+        tokenUsage: retrieved.tokenUsage ?? { input: 0, output: 0 },
+        rawResponseId: retrieved.rawResponseId,
+        validationError: validated.validationError,
+        at: now(),
+    });
+    const failures = [];
+    let retryReason;
+    if (validated.outcome === "failed" && validated.failure) {
+        // A cancelled response settled as `skipped` above (no failure);
+        // only genuine failures push a ProcessingFailure.
+        failures.push({
+            stage: stageId,
+            code: validated.failure.code,
+            message: validated.failure.message,
+            severity: "error",
+        });
+        retryReason = failureRetryReason(validated.failure);
+    }
+    const stageEndEvent = retrieved.tokenUsage !== undefined
+        ? {
+            kind: "stage:end",
+            stageId,
+            status: validated.outcome,
+            tokenUsage: retrieved.tokenUsage,
+            at: now(),
+        }
+        : {
+            kind: "stage:end",
+            stageId,
+            status: validated.outcome,
+            at: now(),
+        };
+    emit(stageEndEvent);
+    const result = {
+        outcome: validated.outcome,
+        failures,
+    };
+    if (validated.outcome === "completed") {
+        result.output = validated.output;
+    }
+    if (retrieved.tokenUsage !== undefined) {
+        result.tokenUsage = retrieved.tokenUsage;
+    }
+    if (retryReason !== undefined) {
+        result.retryReason = retryReason;
+    }
+    return result;
+}
+// API-key resolution for the submit dep. The injected
+// `submitBackgroundResponse` is apiKey-bound by the consumer, so core
+// passes an empty key — the bound capability ignores it. (Kept as a seam
+// in case a future dep shape threads the key through deps.)
+function resolveApiKey(_deps) {
+    return "";
+}
 //# sourceMappingURL=execute.js.map