stageflow 0.9.0 → 0.12.0

package/dist/server/http.js

@@ -9,6 +9,7 @@ import { browseCatalog } from "../config/browseCatalog.js";
 import { listExtensions } from "../config/listExtensions.js";
 import { listSkills } from "../config/listSkills.js";
 import { readRunArtifact } from "../mcp/readArtifact.js";
+import { readStageVerificationHistory } from "../runstore/verificationHistory.js";
 import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
 import { INVALID_SLOT_COUNT_MESSAGE, parseSlotCount, } from "../runtime/settingsFile.js";
 import { isTaskFile } from "../runtime/taskInput.js";
@@ -87,7 +88,10 @@ function isMutatingApi(method, pathname) {
         pathname === "/api/pipelines" ||
         /^\/api\/runs\/[^/]+\/rerun$/.test(pathname) ||
         /^\/api\/runs\/[^/]+\/stages\/[^/]+\/answer$/.test(pathname) ||
+        /^\/api\/runs\/[^/]+\/stages\/[^/]+\/feedback-decision$/.test(pathname) ||
         /^\/api\/runs\/[^/]+\/stages\/[^/]+\/retry$/.test(pathname) ||
+        /^\/api\/runs\/[^/]+\/stages\/[^/]+\/recovery$/.test(pathname) ||
+        /^\/api\/runs\/[^/]+\/stages\/[^/]+\/recovery\/stop$/.test(pathname) ||
         /^\/api\/runs\/[^/]+\/stages\/[^/]+\/abandon$/.test(pathname) ||
         /^\/api\/providers\/[^/]+\/login$/.test(pathname) ||
         /^\/api\/providers\/[^/]+\/login\/[^/]+\/answer$/.test(pathname) ||
@@ -166,6 +170,9 @@ function assertLoopbackHttpAccess(req, res) {
 }
 export function defaultUiDistDir() {
     const here = path.dirname(fileURLToPath(import.meta.url));
+    if (path.basename(path.dirname(here)) === "src") {
+        return path.resolve(here, "../../dist/ui");
+    }
     return path.resolve(here, "../ui");
 }
 export async function startUiServer(options) {
@@ -219,6 +226,20 @@ export async function startUiServer(options) {
                     }
                     return true;
                 }
+                const verificationMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/verification$/);
+                if (method === "GET" && verificationMatch) {
+                    const runId = decodeURIComponent(verificationMatch[1] ?? "");
+                    const stageId = decodeURIComponent(verificationMatch[2] ?? "");
+                    try {
+                        json(res, 200, await readStageVerificationHistory(store, runId, stageId));
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        const notFound = /not found|no such/i.test(message);
+                        json(res, notFound ? 404 : 500, { error: message });
+                    }
+                    return true;
+                }
                 if (method === "GET" && pathname.startsWith("/api/runs/")) {
                     const rest = pathname.slice("/api/runs/".length);
                     if (rest && !rest.includes("/")) {
@@ -290,6 +311,55 @@ export async function startUiServer(options) {
                     json(res, 202, { ok: true });
                     return true;
                 }
+                const feedbackDecisionMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/feedback-decision$/);
+                if (method === "POST" && feedbackDecisionMatch) {
+                    const runId = decodeURIComponent(feedbackDecisionMatch[1] ?? "");
+                    const stageId = decodeURIComponent(feedbackDecisionMatch[2] ?? "");
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        json(res, 400, { error: "Invalid JSON body" });
+                        return true;
+                    }
+                    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+                        json(res, 400, { error: "Body must be a JSON object" });
+                        return true;
+                    }
+                    const raw = body;
+                    if (raw.decision !== "extend" &&
+                        raw.decision !== "continue" &&
+                        raw.decision !== "abandon") {
+                        json(res, 400, {
+                            error: "decision must be extend, continue, or abandon",
+                        });
+                        return true;
+                    }
+                    if (raw.loopId !== undefined && typeof raw.loopId !== "string") {
+                        json(res, 400, { error: "loopId must be a string" });
+                        return true;
+                    }
+                    if (raw.reason !== undefined && typeof raw.reason !== "string") {
+                        json(res, 400, { error: "reason must be a string" });
+                        return true;
+                    }
+                    const result = await manager.decideFeedbackLoop(runId, stageId, {
+                        decision: raw.decision,
+                        ...(raw.loopId !== undefined ? { loopId: raw.loopId } : {}),
+                        ...(raw.reason !== undefined ? { reason: raw.reason } : {}),
+                    });
+                    if (!result.ok) {
+                        json(res, result.status ?? 500, { error: result.reason });
+                        return true;
+                    }
+                    json(res, 202, {
+                        ok: true,
+                        effect: result.effect,
+                        loopId: result.loopId,
+                    });
+                    return true;
+                }
                 const retryMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/retry$/);
                 if (method === "POST" && retryMatch) {
                     await readJsonBody(req);
@@ -307,6 +377,50 @@ export async function startUiServer(options) {
                     });
                     return true;
                 }
+                const recoverMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/recovery$/);
+                if (method === "POST" && recoverMatch) {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        json(res, 400, { error: "Invalid JSON body" });
+                        return true;
+                    }
+                    const guidance = body !== null && typeof body === "object" && !Array.isArray(body)
+                        ? body.guidance
+                        : undefined;
+                    if (guidance !== undefined && typeof guidance !== "string") {
+                        json(res, 400, { error: "guidance must be a string" });
+                        return true;
+                    }
+                    const runId = decodeURIComponent(recoverMatch[1] ?? "");
+                    const stageId = decodeURIComponent(recoverMatch[2] ?? "");
+                    const result = await manager.recoverManualStage(runId, stageId, guidance);
+                    if (!result.ok) {
+                        json(res, result.status ?? 500, mapRetryStageFailure(result));
+                        return true;
+                    }
+                    json(res, 202, {
+                        runId: result.runId,
+                        stageId: result.stageId,
+                        attemptIndex: result.attemptIndex,
+                    });
+                    return true;
+                }
+                const stopRecoveryMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/recovery\/stop$/);
+                if (method === "POST" && stopRecoveryMatch) {
+                    await readJsonBody(req);
+                    const runId = decodeURIComponent(stopRecoveryMatch[1] ?? "");
+                    const stageId = decodeURIComponent(stopRecoveryMatch[2] ?? "");
+                    const result = await manager.stopManualRecovery(runId, stageId);
+                    if (!result.ok) {
+                        json(res, result.status ?? 500, { error: result.reason });
+                        return true;
+                    }
+                    json(res, 202, result);
+                    return true;
+                }
                 const abandonMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/abandon$/);
                 if (method === "POST" && abandonMatch) {
                     await readJsonBody(req);

package/dist/server/operatorResults.js

@@ -9,6 +9,8 @@ export function inferRetryStageErrorCode(reason) {
         return "run_not_retryable";
     if (/stage is not failed/i.test(reason))
         return "stage_not_failed";
+    if (/manual recovery/i.test(reason))
+        return "manual_recovery_required";
     return undefined;
 }
 export function mapRetryStageFailure(result) {

package/dist/tools/askOperator.d.ts

@@ -107,6 +107,96 @@ export declare const askOperatorParamsSchema: Type.TUnion<[Type.TObject<{
     artifacts: Type.TArray<Type.TString>;
     id: Type.TOptional<Type.TString>;
 }>]>;
+/**
+ * Narrows the ask_operator params schema to only the declared gate kinds
+ * (stage `gate_kinds` allowlist). Omitted/empty falls back to the full
+ * union so back-compat stages keep accepting every kind.
+ */
+export declare function askOperatorParamsSchemaFor(allowedKinds?: readonly AskOperatorKind[]): Type.TObject<{
+    kind: Type.TLiteral<"free_text">;
+    message: Type.TString;
+    id: Type.TOptional<Type.TString>;
+}> | Type.TObject<{
+    kind: Type.TLiteral<"confirm">;
+    message: Type.TString;
+    id: Type.TOptional<Type.TString>;
+}> | Type.TObject<{
+    kind: Type.TLiteral<"multi_question">;
+    questions: Type.TArray<Type.TObject<{
+        kind: Type.TUnion<[Type.TLiteral<"free_text">, Type.TLiteral<"confirm">]>;
+        message: Type.TString;
+        id: Type.TOptional<Type.TString>;
+    }>>;
+    id: Type.TOptional<Type.TString>;
+}> | Type.TObject<{
+    kind: Type.TLiteral<"artifact_backed">;
+    message: Type.TString;
+    artifacts: Type.TArray<Type.TString>;
+    id: Type.TOptional<Type.TString>;
+}> | Type.TUnion<[Type.TObject<{
+    kind: Type.TLiteral<"free_text">;
+    message: Type.TString;
+    id: Type.TOptional<Type.TString>;
+}> | Type.TObject<{
+    kind: Type.TLiteral<"confirm">;
+    message: Type.TString;
+    id: Type.TOptional<Type.TString>;
+}> | Type.TObject<{
+    kind: Type.TLiteral<"multi_question">;
+    questions: Type.TArray<Type.TObject<{
+        kind: Type.TUnion<[Type.TLiteral<"free_text">, Type.TLiteral<"confirm">]>;
+        message: Type.TString;
+        id: Type.TOptional<Type.TString>;
+    }>>;
+    id: Type.TOptional<Type.TString>;
+}> | Type.TObject<{
+    kind: Type.TLiteral<"artifact_backed">;
+    message: Type.TString;
+    artifacts: Type.TArray<Type.TString>;
+    id: Type.TOptional<Type.TString>;
+}>, Type.TObject<{
+    kind: Type.TLiteral<"free_text">;
+    message: Type.TString;
+    id: Type.TOptional<Type.TString>;
+}> | Type.TObject<{
+    kind: Type.TLiteral<"confirm">;
+    message: Type.TString;
+    id: Type.TOptional<Type.TString>;
+}> | Type.TObject<{
+    kind: Type.TLiteral<"multi_question">;
+    questions: Type.TArray<Type.TObject<{
+        kind: Type.TUnion<[Type.TLiteral<"free_text">, Type.TLiteral<"confirm">]>;
+        message: Type.TString;
+        id: Type.TOptional<Type.TString>;
+    }>>;
+    id: Type.TOptional<Type.TString>;
+}> | Type.TObject<{
+    kind: Type.TLiteral<"artifact_backed">;
+    message: Type.TString;
+    artifacts: Type.TArray<Type.TString>;
+    id: Type.TOptional<Type.TString>;
+}>, ...(Type.TObject<{
+    kind: Type.TLiteral<"free_text">;
+    message: Type.TString;
+    id: Type.TOptional<Type.TString>;
+}> | Type.TObject<{
+    kind: Type.TLiteral<"confirm">;
+    message: Type.TString;
+    id: Type.TOptional<Type.TString>;
+}> | Type.TObject<{
+    kind: Type.TLiteral<"multi_question">;
+    questions: Type.TArray<Type.TObject<{
+        kind: Type.TUnion<[Type.TLiteral<"free_text">, Type.TLiteral<"confirm">]>;
+        message: Type.TString;
+        id: Type.TOptional<Type.TString>;
+    }>>;
+    id: Type.TOptional<Type.TString>;
+}> | Type.TObject<{
+    kind: Type.TLiteral<"artifact_backed">;
+    message: Type.TString;
+    artifacts: Type.TArray<Type.TString>;
+    id: Type.TOptional<Type.TString>;
+}>)[]]>;
 export declare const askOperatorAnswerSchema: Type.TUnion<[Type.TObject<{
     promptId: Type.TString;
     kind: Type.TLiteral<"free_text">;
@@ -142,25 +232,28 @@ export declare const parseAnswer: typeof parseAskOperatorAnswer;
 export type AskOperatorWaitBridge = {
     requestWait: (prompt: AskOperatorPrompt) => Promise<unknown>;
 };
-export type AskOperatorToolOptions = AskOperatorWaitBridge;
+export type AskOperatorToolOptions = AskOperatorWaitBridge & {
+    allowedKinds?: readonly AskOperatorKind[];
+};
 export type AskOperatorToolDetails = {
     prompt: AskOperatorPrompt | null;
     answer: AskOperatorAnswer | null;
     error: string;
 };
+export declare function summarizeAnswer(answer: AskOperatorAnswer): string;
 export declare function createAskOperatorTool(options: AskOperatorToolOptions): {
     name: string;
     label: string;
     description: string;
-    parameters: Type.TUnion<[Type.TObject<{
+    parameters: Type.TObject<{
         kind: Type.TLiteral<"free_text">;
         message: Type.TString;
         id: Type.TOptional<Type.TString>;
-    }>, Type.TObject<{
+    }> | Type.TObject<{
         kind: Type.TLiteral<"confirm">;
         message: Type.TString;
         id: Type.TOptional<Type.TString>;
-    }>, Type.TObject<{
+    }> | Type.TObject<{
         kind: Type.TLiteral<"multi_question">;
         questions: Type.TArray<Type.TObject<{
             kind: Type.TUnion<[Type.TLiteral<"free_text">, Type.TLiteral<"confirm">]>;
@@ -168,12 +261,75 @@ export declare function createAskOperatorTool(options: AskOperatorToolOptions):
             id: Type.TOptional<Type.TString>;
         }>>;
         id: Type.TOptional<Type.TString>;
+    }> | Type.TObject<{
+        kind: Type.TLiteral<"artifact_backed">;
+        message: Type.TString;
+        artifacts: Type.TArray<Type.TString>;
+        id: Type.TOptional<Type.TString>;
+    }> | Type.TUnion<[Type.TObject<{
+        kind: Type.TLiteral<"free_text">;
+        message: Type.TString;
+        id: Type.TOptional<Type.TString>;
+    }> | Type.TObject<{
+        kind: Type.TLiteral<"confirm">;
+        message: Type.TString;
+        id: Type.TOptional<Type.TString>;
+    }> | Type.TObject<{
+        kind: Type.TLiteral<"multi_question">;
+        questions: Type.TArray<Type.TObject<{
+            kind: Type.TUnion<[Type.TLiteral<"free_text">, Type.TLiteral<"confirm">]>;
+            message: Type.TString;
+            id: Type.TOptional<Type.TString>;
+        }>>;
+        id: Type.TOptional<Type.TString>;
+    }> | Type.TObject<{
+        kind: Type.TLiteral<"artifact_backed">;
+        message: Type.TString;
+        artifacts: Type.TArray<Type.TString>;
+        id: Type.TOptional<Type.TString>;
     }>, Type.TObject<{
+        kind: Type.TLiteral<"free_text">;
+        message: Type.TString;
+        id: Type.TOptional<Type.TString>;
+    }> | Type.TObject<{
+        kind: Type.TLiteral<"confirm">;
+        message: Type.TString;
+        id: Type.TOptional<Type.TString>;
+    }> | Type.TObject<{
+        kind: Type.TLiteral<"multi_question">;
+        questions: Type.TArray<Type.TObject<{
+            kind: Type.TUnion<[Type.TLiteral<"free_text">, Type.TLiteral<"confirm">]>;
+            message: Type.TString;
+            id: Type.TOptional<Type.TString>;
+        }>>;
+        id: Type.TOptional<Type.TString>;
+    }> | Type.TObject<{
+        kind: Type.TLiteral<"artifact_backed">;
+        message: Type.TString;
+        artifacts: Type.TArray<Type.TString>;
+        id: Type.TOptional<Type.TString>;
+    }>, ...(Type.TObject<{
+        kind: Type.TLiteral<"free_text">;
+        message: Type.TString;
+        id: Type.TOptional<Type.TString>;
+    }> | Type.TObject<{
+        kind: Type.TLiteral<"confirm">;
+        message: Type.TString;
+        id: Type.TOptional<Type.TString>;
+    }> | Type.TObject<{
+        kind: Type.TLiteral<"multi_question">;
+        questions: Type.TArray<Type.TObject<{
+            kind: Type.TUnion<[Type.TLiteral<"free_text">, Type.TLiteral<"confirm">]>;
+            message: Type.TString;
+            id: Type.TOptional<Type.TString>;
+        }>>;
+        id: Type.TOptional<Type.TString>;
+    }> | Type.TObject<{
         kind: Type.TLiteral<"artifact_backed">;
         message: Type.TString;
         artifacts: Type.TArray<Type.TString>;
         id: Type.TOptional<Type.TString>;
-    }>]>;
+    }>)[]]>;
     execute: (_toolCallId: string, params: unknown) => Promise<{
         content: {
             type: "text";

package/dist/tools/askOperator.js

@@ -30,29 +30,53 @@ const multiQuestionItemSchema = Type.Object({
     message: Type.String({ minLength: 1 }),
     id: Type.Optional(Type.String()),
 });
+const freeTextParamsSchema = Type.Object({
+    kind: Type.Literal("free_text"),
+    message: Type.String({ minLength: 1 }),
+    id: Type.Optional(Type.String()),
+});
+const confirmParamsSchema = Type.Object({
+    kind: Type.Literal("confirm"),
+    message: Type.String({ minLength: 1 }),
+    id: Type.Optional(Type.String()),
+});
+const multiQuestionParamsSchema = Type.Object({
+    kind: Type.Literal("multi_question"),
+    questions: Type.Array(multiQuestionItemSchema, { minItems: 1 }),
+    id: Type.Optional(Type.String()),
+});
+const artifactBackedParamsSchema = Type.Object({
+    kind: Type.Literal("artifact_backed"),
+    message: Type.String({ minLength: 1 }),
+    artifacts: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+    id: Type.Optional(Type.String()),
+});
+const KIND_PARAM_SCHEMAS = {
+    free_text: freeTextParamsSchema,
+    confirm: confirmParamsSchema,
+    multi_question: multiQuestionParamsSchema,
+    artifact_backed: artifactBackedParamsSchema,
+};
 export const askOperatorParamsSchema = Type.Union([
-    Type.Object({
-        kind: Type.Literal("free_text"),
-        message: Type.String({ minLength: 1 }),
-        id: Type.Optional(Type.String()),
-    }),
-    Type.Object({
-        kind: Type.Literal("confirm"),
-        message: Type.String({ minLength: 1 }),
-        id: Type.Optional(Type.String()),
-    }),
-    Type.Object({
-        kind: Type.Literal("multi_question"),
-        questions: Type.Array(multiQuestionItemSchema, { minItems: 1 }),
-        id: Type.Optional(Type.String()),
-    }),
-    Type.Object({
-        kind: Type.Literal("artifact_backed"),
-        message: Type.String({ minLength: 1 }),
-        artifacts: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
-        id: Type.Optional(Type.String()),
-    }),
+    freeTextParamsSchema,
+    confirmParamsSchema,
+    multiQuestionParamsSchema,
+    artifactBackedParamsSchema,
 ]);
+/**
+ * Narrows the ask_operator params schema to only the declared gate kinds
+ * (stage `gate_kinds` allowlist). Omitted/empty falls back to the full
+ * union so back-compat stages keep accepting every kind.
+ */
+export function askOperatorParamsSchemaFor(allowedKinds) {
+    if (!allowedKinds || allowedKinds.length === 0) {
+        return askOperatorParamsSchema;
+    }
+    const schemas = allowedKinds.map((kind) => KIND_PARAM_SCHEMAS[kind]);
+    if (schemas.length === 1)
+        return schemas[0];
+    return Type.Union(schemas);
+}
 const decisionSchema = Type.Union([
     Type.Literal("accept"),
     Type.Literal("reject"),
@@ -352,7 +376,7 @@ function toolResult(text, details, options) {
         ...(options?.isError ? { isError: true } : {}),
     };
 }
-function summarizeAnswer(answer) {
+export function summarizeAnswer(answer) {
     if (answer.kind === "free_text") {
         return `Operator answered: ${answer.text}`;
     }
@@ -365,16 +389,25 @@ function summarizeAnswer(answer) {
     return `Operator answered ${count} question${count === 1 ? "" : "s"}`;
 }
 export function createAskOperatorTool(options) {
-    const { requestWait } = options;
+    const { requestWait, allowedKinds } = options;
+    const allowed = allowedKinds && allowedKinds.length > 0
+        ? new Set(allowedKinds)
+        : null;
+    const kindList = allowed
+        ? [...allowed].join(", ")
+        : ASK_OPERATOR_KINDS.join(", ");
     return {
         name: "ask_operator",
         label: "Ask operator",
-        description: "Ask the operator a question and wait for their answer. Supports free_text, confirm, multi_question, and artifact_backed prompts. Does not complete the stage — call emit_stage_envelope when finished.",
-        parameters: askOperatorParamsSchema,
+        description: `Ask the operator a question and wait for their answer. Supports ${kindList} prompts. Does not complete the stage — call emit_stage_envelope when finished.`,
+        parameters: askOperatorParamsSchemaFor(allowedKinds),
         execute: async (_toolCallId, params) => {
             let prompt;
             try {
                 const parsed = parseAskOperatorParams(params);
+                if (allowed && !allowed.has(parsed.kind)) {
+                    throw new AskOperatorError(`unsupported prompt kind "${parsed.kind}" (allowed: ${kindList})`);
+                }
                 prompt = normalizePromptIds(parsed);
             }
             catch (err) {

package/dist/tools/emitStageEnvelope.d.ts

@@ -10,13 +10,16 @@
  * deadlocks waitForIdle so later pipeline stages never start.
  */
 import { Type } from "typebox";
+import type { TSchema } from "typebox/type";
+import { type PreEmitCheckOptions } from "../envelope/preEmitChecks.js";
 import type { StageEnvelope } from "../types/envelope.js";
-import type { CloneEmitContext, ForkEmitContext } from "../types/forkChoice.js";
+import type { FeedbackLoopConfig } from "../types/pipeline.js";
+import { type CloneEmitContext, type ForkEmitContext } from "../types/forkChoice.js";
 export type EmitCapture = {
     envelope?: StageEnvelope;
     error?: string;
 };
-export declare function createEmitStageEnvelopeTool(capture: EmitCapture, payloadSchema?: unknown, forkEmitContext?: ForkEmitContext, cloneEmitContext?: CloneEmitContext): {
+export declare function createEmitStageEnvelopeTool(capture: EmitCapture, payloadSchema?: unknown, forkEmitContext?: ForkEmitContext, cloneEmitContext?: CloneEmitContext, preEmitCheckOptions?: PreEmitCheckOptions, feedbackLoopEmitContext?: FeedbackLoopConfig): {
     name: string;
     label: string;
     description: string;
@@ -24,17 +27,14 @@ export declare function createEmitStageEnvelopeTool(capture: EmitCapture, payloa
         status: Type.TUnion<[Type.TLiteral<"success">, Type.TLiteral<"failure">]>;
         summary: Type.TString;
         artifacts: Type.TArray<Type.TString>;
-        payload: Type.TSchema;
+        payload: Type.TOptional<TSchema>;
         fork_choice: Type.TArray<Type.TString>;
-        clone_forks?: Type.TArray<Type.TObject<{
-            successor_id: Type.TString;
-            action: Type.TUnion<[Type.TLiteral<"skip">, Type.TLiteral<"once">, Type.TLiteral<"fanout">]>;
-            envelope: Type.TOptional<Type.TUnknown>;
-            mode: Type.TOptional<Type.TUnion<[Type.TLiteral<"parallel">, Type.TLiteral<"sequential">]>>;
-            clones: Type.TOptional<Type.TArray<Type.TObject<{
-                envelope: Type.TUnknown;
-            }>>>;
-        }>> | undefined;
+        clone_forks?: Type.TArray<TSchema> | undefined;
+        feedback_loop?: Type.TOptional<TSchema> | undefined;
+        checklist_attestations: Type.TOptional<Type.TArray<Type.TObject<{
+            check_id: Type.TString;
+            items: Type.TArray<Type.TString>;
+        }>>>;
         stage_id: Type.TOptional<Type.TString>;
         notes: Type.TOptional<Type.TString>;
     }>;