stageflow 0.9.0 → 0.12.0

package/dist/tools/emitStageEnvelope.js

@@ -11,9 +11,87 @@
  */
 import { Type } from "typebox";
 import { assertRequiredEnvelope, isAdvancingEnvelope, } from "../envelope/check.js";
+import { assertFeedbackLoopAction } from "../envelope/feedbackLoop.js";
 import { assertCloneForks } from "../envelope/cloneForks.js";
 import { normalizeForkChoice } from "../envelope/forkChoice.js";
 import { assertEnvelopePayload, compilePayloadSchema, } from "../envelope/payloadSchema.js";
+import { assertPreEmitChecks, } from "../envelope/preEmitChecks.js";
+import { CLONE_ACTIONS, } from "../types/forkChoice.js";
+function stringLiteralsSchema(values) {
+    if (values.length === 1) {
+        return Type.Literal(values[0]);
+    }
+    return Type.Union(values.map((value) => Type.Literal(value)));
+}
+function stageEnvelopeSchema(payloadSchema) {
+    return Type.Object({
+        status: Type.Union([Type.Literal("success"), Type.Literal("failure")]),
+        summary: Type.String({ minLength: 1 }),
+        artifacts: Type.Array(Type.String()),
+        payload: Type.Optional(payloadSchema !== undefined
+            ? payloadSchema
+            : Type.Record(Type.String(), Type.Unknown())),
+    });
+}
+function feedbackLoopActionSchema(context) {
+    return Type.Union([
+        Type.Object({ action: Type.Literal("continue") }, { additionalProperties: false }),
+        Type.Object({
+            action: Type.Literal("send_back"),
+            target: stringLiteralsSchema([context.target]),
+        }, { additionalProperties: false }),
+    ]);
+}
+function cloneForksItemSchema(cloneEmitContext) {
+    const allowedActions = cloneEmitContext.allowedActions ?? [...CLONE_ACTIONS];
+    const allowSkip = allowedActions.includes("skip");
+    const allowOnce = allowedActions.includes("once");
+    const allowFanout = allowedActions.includes("fanout");
+    const variants = [];
+    for (const successor of cloneEmitContext.clonableSuccessors) {
+        const successorId = Type.Literal(successor.successorId);
+        const nestedPayload = successor.cloneInputSchema !== undefined
+            ? compilePayloadSchema(successor.cloneInputSchema)
+            : undefined;
+        const nestedEnvelope = stageEnvelopeSchema(nestedPayload);
+        if (allowSkip) {
+            variants.push(Type.Object({
+                successor_id: successorId,
+                action: Type.Literal("skip"),
+            }, { additionalProperties: false }));
+        }
+        if (allowOnce) {
+            variants.push(Type.Object({
+                successor_id: successorId,
+                action: Type.Literal("once"),
+                envelope: nestedEnvelope,
+            }));
+        }
+        if (allowFanout) {
+            variants.push(Type.Object({
+                successor_id: successorId,
+                action: Type.Literal("fanout"),
+                mode: Type.Union([
+                    Type.Literal("parallel"),
+                    Type.Literal("sequential"),
+                ]),
+                clones: Type.Array(Type.Object({
+                    envelope: nestedEnvelope,
+                }), { minItems: 2, maxItems: successor.cloneCap }),
+            }));
+        }
+    }
+    if (variants.length === 0) {
+        return Type.Object({
+            successor_id: Type.String(),
+            action: stringLiteralsSchema(allowedActions),
+        });
+    }
+    if (variants.length === 1) {
+        return variants[0];
+    }
+    return Type.Union(variants);
+}
 function toolResult(text, details, options) {
     return {
         content: [{ type: "text", text }],
@@ -22,23 +100,10 @@ function toolResult(text, details, options) {
         ...(options?.terminate ? { terminate: true } : {}),
     };
 }
-export function createEmitStageEnvelopeTool(capture, payloadSchema, forkEmitContext, cloneEmitContext) {
+export function createEmitStageEnvelopeTool(capture, payloadSchema, forkEmitContext, cloneEmitContext, preEmitCheckOptions, feedbackLoopEmitContext) {
     const compiledPayload = payloadSchema !== undefined
         ? compilePayloadSchema(payloadSchema)
         : undefined;
-    const cloneForksSchema = Type.Array(Type.Object({
-        successor_id: Type.String(),
-        action: Type.Union([
-            Type.Literal("skip"),
-            Type.Literal("once"),
-            Type.Literal("fanout"),
-        ]),
-        envelope: Type.Optional(Type.Unknown()),
-        mode: Type.Optional(Type.Union([Type.Literal("parallel"), Type.Literal("sequential")])),
-        clones: Type.Optional(Type.Array(Type.Object({
-            envelope: Type.Unknown(),
-        }))),
-    }));
     return {
         name: "emit_stage_envelope",
         label: "Emit stage envelope",
@@ -47,13 +112,28 @@ export function createEmitStageEnvelopeTool(capture, payloadSchema, forkEmitCont
             status: Type.Union([Type.Literal("success"), Type.Literal("failure")]),
             summary: Type.String({ minLength: 1 }),
             artifacts: Type.Array(Type.String()),
-            payload: compiledPayload !== undefined
+            payload: Type.Optional(compiledPayload !== undefined
                 ? compiledPayload
-                : Type.Optional(Type.Record(Type.String(), Type.Unknown())),
-            fork_choice: forkEmitContext !== undefined
+                : Type.Record(Type.String(), Type.Unknown())),
+            fork_choice: forkEmitContext !== undefined && feedbackLoopEmitContext === undefined
                 ? Type.Array(Type.String())
                 : Type.Optional(Type.Array(Type.String())),
-            ...(cloneEmitContext !== undefined ? { clone_forks: cloneForksSchema } : {}),
+            ...(cloneEmitContext !== undefined
+                ? {
+                    clone_forks: feedbackLoopEmitContext === undefined
+                        ? Type.Array(cloneForksItemSchema(cloneEmitContext))
+                        : Type.Optional(Type.Array(cloneForksItemSchema(cloneEmitContext))),
+                }
+                : {}),
+            ...(feedbackLoopEmitContext !== undefined
+                ? {
+                    feedback_loop: Type.Optional(feedbackLoopActionSchema(feedbackLoopEmitContext)),
+                }
+                : {}),
+            checklist_attestations: Type.Optional(Type.Array(Type.Object({
+                check_id: Type.String({ minLength: 1 }),
+                items: Type.Array(Type.String()),
+            }))),
             stage_id: Type.Optional(Type.String()),
             notes: Type.Optional(Type.String()),
         }),
@@ -62,15 +142,23 @@ export function createEmitStageEnvelopeTool(capture, payloadSchema, forkEmitCont
                 return toolResult("Envelope already accepted; later emits are ignored.", { advancing: isAdvancingEnvelope(capture.envelope), error: "" }, { terminate: true });
             }
             try {
-                const record = params;
-                if (record.status !== "failure" && forkEmitContext !== undefined) {
-                    normalizeForkChoice(record.fork_choice, "emit", forkEmitContext);
+                const envelope = assertRequiredEnvelope(params);
+                assertFeedbackLoopAction(envelope, feedbackLoopEmitContext);
+                const isSendBack = envelope.feedback_loop?.action === "send_back";
+                if (envelope.status !== "failure" &&
+                    !isSendBack &&
+                    forkEmitContext !== undefined) {
+                    normalizeForkChoice(envelope.fork_choice, "emit", forkEmitContext);
                 }
-                if (record.status !== "failure" && cloneEmitContext !== undefined) {
-                    assertCloneForks(params, cloneEmitContext);
+                if (envelope.status !== "failure" &&
+                    !isSendBack &&
+                    cloneEmitContext !== undefined) {
+                    assertCloneForks(envelope, cloneEmitContext);
                 }
-                const envelope = assertRequiredEnvelope(params);
                 assertEnvelopePayload(envelope, payloadSchema);
+                if (envelope.status !== "failure") {
+                    await assertPreEmitChecks(envelope, preEmitCheckOptions);
+                }
                 capture.envelope = envelope;
                 const advancing = isAdvancingEnvelope(envelope);
                 return toolResult(advancing

package/dist/types/completion.d.ts

@@ -0,0 +1,43 @@
+import type { StageGateKind } from "./stage.js";
+export declare const COMPLETION_VERIFICATION_FAILURE_PREFIX = "Completion verification failed:";
+export type CompletionCheck = {
+    id: string;
+    type: "command";
+    run: string;
+    cwd?: string;
+    timeout_ms?: number;
+} | {
+    id: string;
+    type: "artifact";
+    path: string;
+    nonempty?: boolean;
+} | {
+    id: string;
+    type: "checklist";
+    items: string[];
+} | {
+    id: string;
+    type: "payload_schema";
+} | {
+    id: string;
+    type: "gate";
+    kind: StageGateKind;
+} | {
+    id: string;
+    type: "checkout_changes";
+    path_fields?: string[];
+};
+export type CompletionContract = {
+    mode: "all";
+    checks: CompletionCheck[];
+};
+export type RecoveryPolicy = {
+    mode: "repair";
+    max_attempts: number;
+    retry_safety: "idempotent";
+    include_failed_checks: boolean;
+} | {
+    mode: "manual";
+    retry_safety: "idempotent" | "side_effecting";
+    include_failed_checks?: boolean;
+};

package/dist/types/completion.js

@@ -0,0 +1 @@
+export const COMPLETION_VERIFICATION_FAILURE_PREFIX = "Completion verification failed:";

package/dist/types/envelope.d.ts

@@ -1,5 +1,11 @@
 import type { CloneForkItem } from "./forkChoice.js";
 export type EnvelopeStatus = "success" | "failure";
+export type FeedbackLoopAction = {
+    action: "continue";
+} | {
+    action: "send_back";
+    target: string;
+};
 export type StageEnvelope = {
     status: EnvelopeStatus;
     summary: string;
@@ -7,9 +13,21 @@ export type StageEnvelope = {
     payload?: Record<string, unknown>;
     fork_choice?: string[];
     clone_forks?: CloneForkItem[];
+    feedback_loop?: FeedbackLoopAction;
+    /** Agent's explicit acknowledgement of pipeline-owned checklist items. */
+    checklist_attestations?: Array<{
+        check_id: string;
+        items: string[];
+    }>;
     stage_id?: string;
     notes?: string;
 };
+export type SyntheticSkippedEnvelope = {
+    status: "skipped";
+    summary: string;
+    artifacts: string[];
+};
+export type TerminalEnvelope = StageEnvelope | SyntheticSkippedEnvelope;
 export declare class EnvelopeError extends Error {
     constructor(message: string);
 }

package/dist/types/forkChoice.d.ts

@@ -7,6 +7,8 @@ export type ForkEmitContext = {
     immediateSuccessorIds: string[];
     forkShape: ForkChoiceShape | null;
 };
+export declare const CLONE_ACTIONS: readonly ["skip", "once", "fanout"];
+export type CloneAction = (typeof CLONE_ACTIONS)[number];
 export type CloneForkItem = {
     successor_id: string;
     action: "skip";
@@ -22,9 +24,12 @@ export type CloneForkItem = {
         envelope: StageEnvelope;
     }>;
 };
+export type CloneSuccessorEmit = {
+    successorId: string;
+    cloneCap: number;
+    cloneInputSchema?: unknown;
+};
 export type CloneEmitContext = {
-    clonableSuccessors: Array<{
-        successorId: string;
-        cloneCap: number;
-    }>;
+    clonableSuccessors: CloneSuccessorEmit[];
+    allowedActions?: CloneAction[];
 };

package/dist/types/forkChoice.js

@@ -1 +1 @@
-export {};
+export const CLONE_ACTIONS = ["skip", "once", "fanout"];

package/dist/types/pipeline.d.ts

@@ -1,21 +1,47 @@
+import type { CloneAction } from "./forkChoice.js";
 import type { StageConfig, StageGateKind } from "./stage.js";
+import type { CompletionContract, RecoveryPolicy } from "./completion.js";
 export type PipelineConfig = {
     id: string;
     stages: string[];
+    /** Selects the AgentPort backend for every stage in this pipeline; overrides the global default. */
+    agent?: string;
 };
 export type PipelineForkConfig = {
     select: "one" | "subset";
     allow_none: boolean;
 };
+export type NeedTerminalState = "succeeded" | "failed" | "skipped";
+export type PipelineNeedEdge = {
+    id: string;
+    on: NeedTerminalState[];
+};
+export type PipelineNeedItem = string | {
+    id: string;
+    on?: NeedTerminalState[];
+};
+export type PipelineNeeds = string | PipelineNeedEdge[];
+/** Runtime feedback-loop policy declared by the stage that can send work back. */
+export type FeedbackLoopConfig = {
+    target: string;
+    max_replays: number;
+    on_max_replays: "require_continue" | "wait_for_human";
+    replay_session: "resume" | "new_session";
+};
 export type PipelineStageRef = {
     id: string;
-    needs?: string;
+    needs?: string | PipelineNeedItem[];
     fork?: {
         select: "one" | "subset";
         allow_none?: boolean;
     };
     clonable?: boolean;
     clone_cap?: number;
+    completion?: CompletionContract;
+    recovery?: RecoveryPolicy;
+    feedback_loop?: FeedbackLoopConfig;
+    /** Omitted means this stage is safe to include in a feedback replay. */
+    replay_safe?: boolean;
 };
 export type PipelineStageYamlEntry = PipelineStageRef & {
     uses?: string;
@@ -23,6 +49,8 @@ export type PipelineStageYamlEntry = PipelineStageRef & {
     model?: string;
     payload_schema?: unknown;
     gate_kinds?: StageGateKind[];
+    clone_input_schema?: unknown;
+    clone_actions?: CloneAction[];
     skill?: string;
 };
 export type PipelineIncludeEntry = {
@@ -34,13 +62,17 @@ export type PipelineFragmentConfig = {
 };
 export type NormalizedPipelineStageEntry = {
     id: string;
-    needs?: string;
+    needs?: PipelineNeeds;
     fork?: {
         select: "one" | "subset";
         allow_none?: boolean;
     };
     clonable?: boolean;
     clone_cap?: number;
+    completion?: CompletionContract;
+    recovery?: RecoveryPolicy;
+    feedback_loop?: FeedbackLoopConfig;
+    replay_safe?: boolean;
     skill?: string;
     body: {
         kind: "inline";
@@ -61,12 +93,17 @@ export type PipelineStageSource = {
 export type ResolvedPipelineStageNode = {
     id: string;
     needs: string | null;
+    needsEdges: PipelineNeedEdge[];
     ancestors: string[];
     stageIndex: number;
     fork?: PipelineForkConfig;
     clonable?: boolean;
     clone_cap?: number;
     definition_id?: string;
+    completion?: CompletionContract;
+    recovery?: RecoveryPolicy;
+    feedback_loop?: FeedbackLoopConfig;
+    replay_safe?: boolean;
 };
 export type ResolvedPipelineDag = {
     nodes: ResolvedPipelineStageNode[];

package/dist/types/preEmitCheck.d.ts

@@ -0,0 +1,18 @@
+import type { StageGateKind } from "./stage.js";
+/**
+ * In-session checks `emit_stage_envelope` must satisfy this attempt before a
+ * success emit is accepted. Distinct from `CompletionCheck`/`CompletionContract`
+ * (`src/types/completion.ts`): those run post-hoc, after a candidate envelope
+ * has already been captured, driven by the pipeline-wiring `completion` field.
+ * `PreEmitCheck` runs synchronously inside the agent's own `emit_stage_envelope`
+ * tool call, driven by the stage-body `pre_emit_checks` field.
+ */
+export type PreEmitCheck = {
+    id: string;
+    type: "gate";
+    kind: StageGateKind;
+} | {
+    id: string;
+    type: "artifact_declared";
+    basename: string;
+};

package/dist/types/preEmitCheck.js

@@ -0,0 +1 @@
+export {};

package/dist/types/stage.d.ts

@@ -1,3 +1,5 @@
+import type { PreEmitCheck } from "./preEmitCheck.js";
+import type { CloneAction } from "./forkChoice.js";
 export declare const STAGE_GATE_KINDS: readonly ["free_text", "confirm", "multi_question", "artifact_backed"];
 export type StageGateKind = (typeof STAGE_GATE_KINDS)[number];
 export type StageConfig = {
@@ -8,5 +10,16 @@ export type StageConfig = {
     payload_schema?: unknown;
     /** Declared ask_operator kinds this stage is expected to stop on. */
     gate_kinds?: StageGateKind[];
+    /** In-session checks emit must satisfy this attempt before success is accepted. */
+    pre_emit_checks?: PreEmitCheck[];
+    clone_input_schema?: unknown;
+    clone_actions?: CloneAction[];
+    /** Optional stage wall-clock timeout in milliseconds (default 15 minutes). */
+    timeout_ms?: number;
     skill?: string;
+    /**
+     * Selects the AgentPort backend for this stage, overriding pipeline/global.
+     * Parsed but not yet consulted — see STAGE_LEVEL_AGENT_OVERRIDE_ENABLED.
+     */
+    agent?: string;
 };

package/dist/types/stageflowManifest.d.ts

@@ -11,6 +11,8 @@ export type StageflowManifestCatalog = {
 export type StageflowManifest = {
     version: StageflowManifestVersion;
     catalog: StageflowManifestCatalog;
+    /** Default AgentPort backend for every pipeline/stage that doesn't override it. */
+    agent?: string;
 };
 export type LoadedManifest = {
     path: string;