stageflow 0.16.0 → 0.19.0

package/dist/tools/emitStageEnvelope.d.ts

@@ -14,12 +14,12 @@ import type { TSchema } from "typebox/type";
 import { type PreEmitCheckOptions } from "../envelope/preEmitChecks.js";
 import type { StageEnvelope } from "../types/envelope.js";
 import type { FeedbackLoopConfig } from "../types/pipeline.js";
-import { type CloneEmitContext, type ForkEmitContext } from "../types/forkChoice.js";
+import type { CloneEmitContext, ForkEmitContext } from "../types/forkChoice.js";
 export type EmitCapture = {
     envelope?: StageEnvelope;
     error?: string;
 };
-export declare function createEmitStageEnvelopeTool(capture: EmitCapture, payloadSchema?: unknown, forkEmitContext?: ForkEmitContext, cloneEmitContext?: CloneEmitContext, preEmitCheckOptions?: PreEmitCheckOptions, feedbackLoopEmitContext?: FeedbackLoopConfig): {
+export declare function createEmitStageEnvelopeTool(capture: EmitCapture, payloadSchema?: unknown, forkEmitContext?: ForkEmitContext, _cloneEmitContext?: CloneEmitContext, preEmitCheckOptions?: PreEmitCheckOptions, feedbackLoopEmitContext?: FeedbackLoopConfig): {
     name: string;
     label: string;
     description: string;
@@ -29,7 +29,6 @@ export declare function createEmitStageEnvelopeTool(capture: EmitCapture, payloa
         artifacts: Type.TArray<Type.TString>;
         payload: Type.TOptional<TSchema>;
         fork_choice: Type.TArray<Type.TString>;
-        clone_forks?: Type.TArray<TSchema> | undefined;
         feedback_loop?: Type.TOptional<TSchema> | undefined;
         checklist_attestations: Type.TOptional<Type.TArray<Type.TObject<{
             check_id: Type.TString;
@@ -38,6 +37,7 @@ export declare function createEmitStageEnvelopeTool(capture: EmitCapture, payloa
         stage_id: Type.TOptional<Type.TString>;
         notes: Type.TOptional<Type.TString>;
     }>;
+    prepareArguments: (args: unknown) => never;
     execute: (_toolCallId: string, params: unknown) => Promise<{
         content: {
             type: "text";

package/dist/tools/emitStageEnvelope.js

@@ -12,11 +12,10 @@
 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";
+import { prepareEmitStageEnvelopeArguments } from "./prepareToolArguments.js";
 function stringLiteralsSchema(values) {
     if (values.length === 1) {
         return Type.Literal(values[0]);
@@ -42,56 +41,6 @@ function feedbackLoopActionSchema(context) {
         }, { 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 }],
@@ -100,7 +49,7 @@ function toolResult(text, details, options) {
         ...(options?.terminate ? { terminate: true } : {}),
     };
 }
-export function createEmitStageEnvelopeTool(capture, payloadSchema, forkEmitContext, cloneEmitContext, preEmitCheckOptions, feedbackLoopEmitContext) {
+export function createEmitStageEnvelopeTool(capture, payloadSchema, forkEmitContext, _cloneEmitContext, preEmitCheckOptions, feedbackLoopEmitContext) {
     const compiledPayload = payloadSchema !== undefined
         ? compilePayloadSchema(payloadSchema)
         : undefined;
@@ -118,13 +67,6 @@ export function createEmitStageEnvelopeTool(capture, payloadSchema, forkEmitCont
             fork_choice: forkEmitContext !== undefined && feedbackLoopEmitContext === undefined
                 ? Type.Array(Type.String())
                 : Type.Optional(Type.Array(Type.String())),
-            ...(cloneEmitContext !== undefined
-                ? {
-                    clone_forks: feedbackLoopEmitContext === undefined
-                        ? Type.Array(cloneForksItemSchema(cloneEmitContext))
-                        : Type.Optional(Type.Array(cloneForksItemSchema(cloneEmitContext))),
-                }
-                : {}),
             ...(feedbackLoopEmitContext !== undefined
                 ? {
                     feedback_loop: Type.Optional(feedbackLoopActionSchema(feedbackLoopEmitContext)),
@@ -137,12 +79,13 @@ export function createEmitStageEnvelopeTool(capture, payloadSchema, forkEmitCont
             stage_id: Type.Optional(Type.String()),
             notes: Type.Optional(Type.String()),
         }),
+        prepareArguments: prepareEmitStageEnvelopeArguments,
         execute: async (_toolCallId, params) => {
             if (capture.envelope) {
                 return toolResult("Envelope already accepted; later emits are ignored.", { advancing: isAdvancingEnvelope(capture.envelope), error: "" }, { terminate: true });
             }
             try {
-                const envelope = assertRequiredEnvelope(params);
+                const envelope = assertRequiredEnvelope(prepareEmitStageEnvelopeArguments(params));
                 assertFeedbackLoopAction(envelope, feedbackLoopEmitContext);
                 const isSendBack = envelope.feedback_loop?.action === "send_back";
                 if (envelope.status !== "failure" &&
@@ -150,11 +93,6 @@ export function createEmitStageEnvelopeTool(capture, payloadSchema, forkEmitCont
                     forkEmitContext !== undefined) {
                     normalizeForkChoice(envelope.fork_choice, "emit", forkEmitContext);
                 }
-                if (envelope.status !== "failure" &&
-                    !isSendBack &&
-                    cloneEmitContext !== undefined) {
-                    assertCloneForks(envelope, cloneEmitContext);
-                }
                 assertEnvelopePayload(envelope, payloadSchema);
                 if (envelope.status !== "failure") {
                     await assertPreEmitChecks(envelope, preEmitCheckOptions);

package/dist/tools/prepareToolArguments.d.ts

@@ -0,0 +1,4 @@
+export declare function coerceJsonArrayField(args: Record<string, unknown>, key: string): void;
+export declare function coerceJsonObjectField(args: Record<string, unknown>, key: string): void;
+export declare function prepareAskOperatorArguments(input: unknown): unknown;
+export declare function prepareEmitStageEnvelopeArguments(input: unknown): unknown;

package/dist/tools/prepareToolArguments.js

@@ -0,0 +1,79 @@
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseJsonArrayString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed.startsWith("["))
+        return undefined;
+    try {
+        const parsed = JSON.parse(trimmed);
+        return Array.isArray(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseJsonObjectString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed.startsWith("{"))
+        return undefined;
+    try {
+        const parsed = JSON.parse(trimmed);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function coerceJsonArrayField(args, key) {
+    const parsed = parseJsonArrayString(args[key]);
+    if (parsed !== undefined) {
+        args[key] = parsed;
+    }
+}
+export function coerceJsonObjectField(args, key) {
+    const parsed = parseJsonObjectString(args[key]);
+    if (parsed !== undefined) {
+        args[key] = parsed;
+    }
+}
+function coerceJsonObjectArrayElements(args, key) {
+    const value = args[key];
+    if (!Array.isArray(value))
+        return;
+    args[key] = value.map((item) => parseJsonObjectString(item) ?? item);
+}
+export function prepareAskOperatorArguments(input) {
+    if (!isRecord(input))
+        return input;
+    const args = { ...input };
+    coerceJsonArrayField(args, "questions");
+    coerceJsonObjectArrayElements(args, "questions");
+    coerceJsonArrayField(args, "artifacts");
+    return args;
+}
+export function prepareEmitStageEnvelopeArguments(input) {
+    if (!isRecord(input))
+        return input;
+    const args = { ...input };
+    coerceJsonObjectField(args, "payload");
+    coerceJsonObjectField(args, "feedback_loop");
+    coerceJsonArrayField(args, "artifacts");
+    coerceJsonArrayField(args, "fork_choice");
+    coerceJsonArrayField(args, "checklist_attestations");
+    coerceJsonObjectArrayElements(args, "checklist_attestations");
+    if (Array.isArray(args.checklist_attestations)) {
+        args.checklist_attestations = args.checklist_attestations.map((item) => {
+            if (!isRecord(item))
+                return item;
+            const next = { ...item };
+            coerceJsonArrayField(next, "items");
+            return next;
+        });
+    }
+    return args;
+}

package/dist/types/envelope.d.ts

@@ -1,4 +1,3 @@
-import type { CloneForkItem } from "./forkChoice.js";
 export type EnvelopeStatus = "success" | "failure";
 export type FeedbackLoopAction = {
     action: "continue";
@@ -12,7 +11,6 @@ export type StageEnvelope = {
     artifacts: string[];
     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<{

package/dist/types/forkChoice.d.ts

@@ -1,4 +1,3 @@
-import type { StageEnvelope } from "./envelope.js";
 export type ForkChoiceShape = {
     cardinality: "one" | "subset";
     allowNone: boolean;
@@ -9,21 +8,6 @@ export type ForkEmitContext = {
 };
 export declare const CLONE_ACTIONS: readonly ["skip", "once", "fanout"];
 export type CloneAction = (typeof CLONE_ACTIONS)[number];
-export type CloneForkItem = {
-    successor_id: string;
-    action: "skip";
-} | {
-    successor_id: string;
-    action: "once";
-    envelope: StageEnvelope;
-} | {
-    successor_id: string;
-    action: "fanout";
-    mode: "parallel" | "sequential";
-    clones: Array<{
-        envelope: StageEnvelope;
-    }>;
-};
 export type CloneSuccessorEmit = {
     successorId: string;
     cloneCap: number;

package/dist/types/pipeline.d.ts

@@ -1,4 +1,3 @@
-import type { CloneAction } from "./forkChoice.js";
 import type { LoadedStageConfig, StageGateKind, StageIoYaml } from "./stage.js";
 import type { CompletionContract, RecoveryPolicy } from "./completion.js";
 export type PipelineConfig = {
@@ -16,15 +15,75 @@ export type PipelineForkConfig = {
     allow_none: boolean;
 };
 export type NeedTerminalState = "succeeded" | "failed" | "skipped";
+export type RouteIfOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "not_in";
+export type RouteIfLeafPredicate = {
+    field: string;
+    op: RouteIfOp;
+    value: unknown;
+};
+export type RouteIfAllPredicate = {
+    all: RouteIfPredicate[];
+    field?: never;
+};
+export type RouteIfAnyPredicate = {
+    any: RouteIfPredicate[];
+    field?: never;
+};
+export type RouteIfNotPredicate = {
+    not: RouteIfPredicate;
+    field?: never;
+};
+export type RouteIfPredicate = RouteIfLeafPredicate | RouteIfAllPredicate | RouteIfAnyPredicate | RouteIfNotPredicate;
 export type PipelineNeedEdge = {
     id: string;
     on: NeedTerminalState[];
+    if?: RouteIfPredicate;
 };
 export type PipelineNeedItem = string | {
     id: string;
     on?: NeedTerminalState[];
 };
 export type PipelineNeeds = string | PipelineNeedEdge[];
+/**
+ * Terminal states a route entry (or its inverted predecessor edge) can gate on.
+ * Same domain as `NeedTerminalState` — kept as a distinct alias since `route`
+ * is a separate vocabulary from `needs` (see docs/yaml-catalog.md).
+ */
+export type RouteTerminalState = NeedTerminalState;
+/**
+ * A forward route entry: hands off from the declaring stage to `to`, gated on
+ * the declaring stage's own terminal state (`on`, defaulting to succeeded-only).
+ */
+export type PipelineRouteForwardEntry = {
+    to: string;
+    on?: RouteTerminalState | RouteTerminalState[];
+    if?: RouteIfPredicate;
+};
+/**
+ * A loop route entry (ticket 03, route-based-pipeline-wiring spec): sends
+ * execution back to a declared ancestor of the source stage instead of
+ * continuing forward, carrying the same replay policy `FeedbackLoopConfig`
+ * carries today — `target` renamed to `to` for naming consistency with
+ * forward entries. Contributes no forward DAG edge (`toRouteEdges` skips
+ * it), so it is excluded from cycle detection; it is a runtime-only replay
+ * schedule over the already-resolved forward graph.
+ */
+export type PipelineRouteLoopEntry = {
+    type: "loop";
+    to: string;
+    max_replays: number;
+    on_max_replays: "require_continue" | "wait_for_human";
+    replay_session: "resume" | "new_session";
+};
+export type PipelineRouteEntry = PipelineRouteForwardEntry | PipelineRouteLoopEntry;
+/** A stage's outbound `route` field: where execution goes next. */
+export type PipelineRoute = PipelineRouteEntry[];
+/** Normalized forward route edge (post-parse): `on` is always populated. */
+export type PipelineRouteEdge = {
+    to: string;
+    on: RouteTerminalState[];
+    if?: RouteIfPredicate;
+};
 /** Runtime feedback-loop policy declared by the stage that can send work back. */
 export type FeedbackLoopConfig = {
     target: string;
@@ -32,43 +91,44 @@ export type FeedbackLoopConfig = {
     on_max_replays: "require_continue" | "wait_for_human";
     replay_session: "resume" | "new_session";
 };
+export type CloneMode = "parallel" | "sequential";
 export type PipelineStageRef = {
     id: string;
-    needs?: string | PipelineNeedItem[];
-    fork?: {
-        select: "one" | "subset";
-        allow_none?: boolean;
-    };
-    clonable?: boolean;
-    clone_cap?: number;
     /** IR: after-phase checks. YAML: `verify` items whose `when` includes `after`. */
     completion?: CompletionContract;
     /** IR: after-phase failure policy. YAML: `on_verify_fail`. */
     recovery?: RecoveryPolicy;
-    feedback_loop?: FeedbackLoopConfig;
     /** Omitted means this stage is safe to include in a feedback replay. */
     replay_safe?: boolean;
+    /** Pipeline wiring vocabulary (see docs/yaml-catalog.md). */
+    route?: PipelineRouteEntry[];
+    /** Marks this stage as a pipeline entry point. */
+    entry?: boolean;
+    clone_cap?: number;
+    clone_mode?: CloneMode;
 };
 /**
- * Pipeline YAML stage entry (both dialects). Target authoring is `io` / `verify`
- * / `on_verify_fail`. The payload_schema / pre_emit_checks / completion /
- * recovery keys are the legacy YAML dialect (and also the IR names after compile).
- * New catalog fields: add target YAML keys here and compile them in yamlDialect.ts.
+ * Catalog YAML stage entry (`io` / `verify` / `on_verify_fail`). Not IR.
+ * Dual-read of `payload_schema` / `pre_emit_checks` / `completion` / `recovery`
+ * stays in `legacyYaml.ts` on the raw record.
  */
-export type PipelineStageYamlEntry = PipelineStageRef & {
+export type PipelineStageYamlEntry = {
+    id?: string;
     uses?: string;
     system_prompt?: string;
     model?: string;
-    payload_schema?: unknown;
     gate_kinds?: StageGateKind[];
-    clone_input_schema?: unknown;
-    clone_actions?: CloneAction[];
+    timeout_ms?: number;
     skill?: string;
     mcp?: string[];
+    replay_safe?: boolean;
+    route?: PipelineRouteEntry[];
+    entry?: boolean;
+    clone_cap?: number;
+    clone_mode?: CloneMode;
     io?: StageIoYaml;
     verify?: unknown;
     on_verify_fail?: RecoveryPolicy;
-    pre_emit_checks?: unknown;
 };
 export type PipelineIncludeEntry = {
     local: string;
@@ -79,20 +139,16 @@ export type PipelineFragmentConfig = {
 };
 export type NormalizedPipelineStageEntry = {
     id: string;
-    needs?: PipelineNeeds;
-    fork?: {
-        select: "one" | "subset";
-        allow_none?: boolean;
-    };
-    clonable?: boolean;
-    clone_cap?: number;
     /** IR after compile. YAML `verify` after-phase / `on_verify_fail`. */
     completion?: CompletionContract;
     recovery?: RecoveryPolicy;
-    feedback_loop?: FeedbackLoopConfig;
     replay_safe?: boolean;
+    route?: PipelineRouteEntry[];
+    entry?: boolean;
     skill?: string;
     mcp?: string[];
+    clone_cap?: number;
+    clone_mode?: CloneMode;
     body: {
         kind: "inline";
         raw: Record<string, unknown>;
@@ -116,8 +172,9 @@ export type ResolvedPipelineStageNode = {
     ancestors: string[];
     stageIndex: number;
     fork?: PipelineForkConfig;
-    clonable?: boolean;
     clone_cap?: number;
+    clone_mode?: CloneMode;
+    clone_array_field?: string;
     definition_id?: string;
     /** Persisted on pipeline_dag. YAML `verify` after-phase. */
     completion?: CompletionContract;
@@ -125,6 +182,8 @@ export type ResolvedPipelineStageNode = {
     recovery?: RecoveryPolicy;
     feedback_loop?: FeedbackLoopConfig;
     replay_safe?: boolean;
+    /** Present (true) only when this stage was declared `entry: true`. */
+    entry?: boolean;
 };
 export type ResolvedPipelineDag = {
     nodes: ResolvedPipelineStageNode[];

package/dist/types/stage.d.ts

@@ -1,14 +1,19 @@
 import type { PreEmitCheck } from "./preEmitCheck.js";
-import type { CloneAction } from "./forkChoice.js";
+/** Typed emit/schema fields from `compileTargetContract`. Not catalog YAML keys. */
+export type CompiledStageEmitBody = {
+    payload_schema?: unknown;
+    clone_input_schema?: unknown;
+    pre_emit_checks?: PreEmitCheck[];
+};
 export declare const STAGE_GATE_KINDS: readonly ["free_text", "confirm", "multi_question", "artifact_backed"];
 export type StageGateKind = (typeof STAGE_GATE_KINDS)[number];
 /** Target YAML `io:` block. Compiles onto StageConfig.payload_schema / clone_input_schema. */
 export type StageIoYaml = {
-    input?: {
-        schema?: unknown;
+    input: {
+        schema: unknown;
     };
-    output?: {
-        schema?: unknown;
+    output: {
+        schema: unknown;
     };
 };
 /**
@@ -27,9 +32,8 @@ export type StageConfig = {
     gate_kinds?: StageGateKind[];
     /** IR: emit-phase checks. YAML: `verify` items whose `when` includes `emit`. */
     pre_emit_checks?: PreEmitCheck[];
-    /** IR: clone/fan-out assignment schema. YAML: `io.input.schema`. */
+    /** IR: inbound assignment schema. YAML: `io.input.schema`. */
     clone_input_schema?: unknown;
-    clone_actions?: CloneAction[];
     /** Optional stage wall-clock timeout in milliseconds (default 60 minutes). */
     timeout_ms?: number;
     skill?: string;