@voltro/plugin-ai-flows 0.34.0 → 0.35.0

package/dist/ir-BOv5uwYI.js

@@ -0,0 +1,142 @@
+import { Schema as e } from "effect";
+//#region src/condition.ts
+var t = e.Literal("truthy", "falsy", "eq", "neq", "contains"), n = e.Struct({
+	ref: e.String,
+	op: t,
+	value: e.optional(e.Unknown)
+}), r = (e) => e == null ? !1 : typeof e == "boolean" ? e : !Array.isArray(e) || e.length > 0, i = (e, t) => {
+	if (e === t) return !0;
+	if (e === null || t === null || e === void 0 || t === void 0) return !1;
+	if (typeof e == "object" || typeof t == "object") try {
+		return JSON.stringify(e) === JSON.stringify(t);
+	} catch {
+		return !1;
+	}
+	return String(e) === String(t);
+}, a = (e, t) => {
+	let n = t[e.ref];
+	switch (e.op) {
+		case "truthy": return r(n);
+		case "falsy": return !r(n);
+		case "eq": return i(n, e.value);
+		case "neq": return !i(n, e.value);
+		case "contains": {
+			if (n == null) return !1;
+			if (Array.isArray(n)) return n.some((t) => i(t, e.value));
+			let t = e.value;
+			return typeof t != "string" && typeof t != "number" ? !1 : String(n).includes(String(t));
+		}
+	}
+}, o = (e) => {
+	switch (e.op) {
+		case "truthy": return `{{${e.ref}}} is set`;
+		case "falsy": return `{{${e.ref}}} is not set`;
+		case "eq": return `{{${e.ref}}} equals ${JSON.stringify(e.value)}`;
+		case "neq": return `{{${e.ref}}} does not equal ${JSON.stringify(e.value)}`;
+		case "contains": return `{{${e.ref}}} contains ${JSON.stringify(e.value)}`;
+	}
+}, s = e.Literal("deterministic", "agentic"), c = e.Literal("draft", "active", "archived"), l = e.Literal("private", "organization", "shared"), u = e.Literal("pending", "running", "waiting", "succeeded", "failed", "cancelled"), d = e.Literal("manual", "cron"), f = e.Literal("agent", "generate", "structured", "note", "human"), p = e.Literal("text", "image", "video", "audio"), m = e.Literal("approve", "choice", "text"), h = e.Struct({
+	value: e.String,
+	label: e.String
+}), g = e.Union(e.Struct({
+	from: e.Literal("upload"),
+	url: e.String
+}), e.Struct({
+	from: e.Literal("step"),
+	ref: e.String
+})), _ = e.Record({
+	key: e.String,
+	value: g
+}), v = e.Record({
+	key: e.String,
+	value: e.Unknown
+}), y = e.Struct({
+	id: e.String,
+	title: e.optional(e.String),
+	description: e.optional(e.String),
+	type: f,
+	outputKey: e.optional(e.String),
+	prompt: e.optional(e.String),
+	modality: e.optional(p),
+	model: e.optional(e.String),
+	params: e.optional(v),
+	mediaInputs: e.optional(_),
+	agentRef: e.optional(e.String),
+	schema: e.optional(v),
+	reviewMode: e.optional(m),
+	options: e.optional(e.Array(h)),
+	when: e.optional(n),
+	group: e.optional(e.String),
+	timeoutMs: e.optional(e.Number)
+}), b = e.Struct({
+	key: e.String,
+	label: e.String,
+	type: e.Literal("text", "textarea", "number", "boolean"),
+	required: e.optional(e.Boolean),
+	placeholder: e.optional(e.String)
+}), x = e.Struct({
+	flowRef: e.String,
+	mappings: e.Array(e.Struct({
+		targetKey: e.String,
+		sourceKey: e.String
+	})),
+	requireConfirmation: e.optional(e.Boolean)
+}), S = e.Struct({
+	frequency: e.optional(e.Literal("weekly", "monthly")),
+	repeats: e.Array(e.Number),
+	intervalWeeks: e.optional(e.Number),
+	anchorDate: e.optional(e.String),
+	weekOfMonth: e.optional(e.Union(e.Literal(1, 2, 3, 4), e.Literal("last"))),
+	hour: e.optional(e.Number),
+	minute: e.optional(e.Literal(0, 15, 30, 45)),
+	defaultInput: e.optional(v)
+}), C = e.Literal("pending", "running", "waiting", "succeeded", "failed", "skipped"), w = e.Struct({
+	mode: m,
+	options: e.optional(e.Array(h)),
+	prompt: e.String
+}), T = e.Struct({
+	id: e.Number,
+	title: e.String,
+	description: e.optional(e.String),
+	type: f,
+	status: C,
+	startedAt: e.optional(e.String),
+	completedAt: e.optional(e.String),
+	costMicroUsd: e.optional(e.Number),
+	requestId: e.optional(e.String),
+	url: e.optional(e.String),
+	output: e.optional(e.Struct({ text: e.String })),
+	errorMessage: e.optional(e.String),
+	skipReason: e.optional(e.String),
+	review: e.optional(w)
+}), E = e.Struct({
+	decision: e.optional(e.Literal("approve", "reject")),
+	value: e.optional(e.String),
+	text: e.optional(e.String),
+	respondedAt: e.optional(e.String)
+}), D = e.Struct({
+	flowRef: e.String,
+	input: v,
+	status: e.Literal("pending", "confirmed", "dismissed")
+}), O = 30, k = 1, A = 100, j = (e) => e == null || !Number.isFinite(e) ? 30 : Math.min(100, Math.max(1, Math.trunc(e))), M = (e) => e.replace(/[^\w.-]/g, "_"), N = (e) => {
+	let t = (e.steps ?? []).map((e) => e.outputKey ? {
+		...e,
+		outputKey: M(e.outputKey)
+	} : e), n = e.orchestratorModel || e.orchestratorInstructions ? {
+		...e.orchestratorModel ? { model: e.orchestratorModel } : {},
+		...e.orchestratorInstructions ? { instructions: e.orchestratorInstructions } : {}
+	} : void 0;
+	return {
+		name: e.name,
+		mode: e.mode ?? "deterministic",
+		steps: t,
+		maxSteps: j(e.maxSteps),
+		brief: e.brief ?? [],
+		...n ? { orchestrator: n } : {},
+		...e.chain ? { chain: e.chain } : {},
+		...e.cadence ? { cadence: e.cadence } : {},
+		...e.humanTimeoutMs != null && Number.isFinite(e.humanTimeoutMs) ? { humanTimeoutMs: e.humanTimeoutMs } : {}
+	};
+};
+//#endregion
+export { o as A, f as C, M as D, N as E, r as M, t as O, C as S, j as T, h as _, s as a, u as b, E as c, A as d, k as f, m as g, p as h, x as i, a as j, n as k, v as l, _ as m, D as n, c as o, g as p, S as r, y as s, b as t, O as u, w as v, l as w, T as x, d as y };

package/dist/ir.d.ts

@@ -37,6 +37,26 @@ export declare interface ChainPending {
 
 export declare const clampMaxSteps: (n: number | null | undefined) => number;
 
+/** The comparison a `when:` performs. */
+export declare const ConditionOp: Schema.Literal<["truthy", "falsy", "eq", "neq", "contains"]>;
+
+export declare type ConditionOp = typeof ConditionOp.Type;
+
+/** A one-line rendering for the run timeline and the editor preview. Exported
+ *  so the reason a step was skipped is the SAME sentence in both places. */
+export declare const describeCondition: (condition: StepCondition) => string;
+
+/**
+ * Evaluate `condition` against a run context.
+ *
+ * A condition on a ref the context does not carry evaluates as ABSENT — false
+ * for `truthy`/`eq`/`contains`, true for `falsy`/`neq`. That asymmetry is the
+ * honest reading of "the producing step did not run", and it is why
+ * `validateFlow` refuses a dangling ref at registration: at run time, a typo and
+ * a genuinely-skipped producer are indistinguishable here.
+ */
+export declare const evaluateCondition: (condition: StepCondition, context: Readonly<Record<string, unknown>>) => boolean;
+
 /** Schedule spec — richer than a single cron expr (weekly interval + anchor,
  *  monthly weekOfMonth), evaluated by the shared `cadenceMatches` predicate. */
 export declare const FlowCadence: Schema.Struct<{
@@ -178,6 +198,24 @@ export declare const FlowStep: Schema.Struct<{
         value: typeof Schema.String;
         label: typeof Schema.String;
     }>>>;
+    /** Gate this step on a prior value. Absent → the step always runs. A step
+     *  whose condition is false is SKIPPED, not failed: it produces no output, so
+     *  anything referencing its `outputKey` sees an absent value. */
+    when: Schema.optional<Schema.Struct<{
+        ref: typeof Schema.String;
+        op: Schema.Literal<["truthy", "falsy", "eq", "neq", "contains"]>;
+        value: Schema.optional<typeof Schema.Unknown>;
+    }>>;
+    /**
+     * Fan-out group. CONSECUTIVE steps sharing a group name run CONCURRENTLY,
+     * each still journaled as its own durable step.
+     *
+     * Steps in one group may not reference each other's outputs — they have no
+     * order between them — and `validateFlow` refuses a flow that tries. A `human`
+     * step may not join a group either: it suspends the whole workflow, which is
+     * not a thing one branch of a fan-out can do.
+     */
+    group: Schema.optional<typeof Schema.String>;
     /** `human` step only — how long the run parks awaiting this review before it
      *  fails, in milliseconds. Omitted → the flow's `humanTimeoutMs`, then the
      *  engine/plugin default (see `resolveHumanReviewTimeoutMs`). `0` means WAIT
@@ -223,6 +261,8 @@ export declare interface FlowStep {
     readonly schema?: Json | undefined;
     readonly reviewMode?: ReviewMode | undefined;
     readonly options?: ReadonlyArray<ReviewOption> | undefined;
+    readonly when?: StepCondition | undefined;
+    readonly group?: string | undefined;
     readonly timeoutMs?: number | undefined;
 }
 
@@ -242,6 +282,20 @@ export declare interface HumanResponse {
     readonly respondedAt?: string | undefined;
 }
 
+/**
+ * Truthiness, defined once so the engine and the editor cannot disagree.
+ *
+ * Deliberately NOT JavaScript's: `0` and `''` are falsy in JS, and a step gated
+ * on a count or a generated string would then be skipped for a legitimate value.
+ * A flow author writing `when: { ref: 'count', op: 'truthy' }` means "there is a
+ * count", not "the count is non-zero" — the second is `{ op: 'neq', value: 0 }`,
+ * which they can say if they mean it.
+ *
+ * Absent, null and the empty ARRAY are the falsy set: those are the three
+ * shapes a step that produced nothing actually leaves behind.
+ */
+export declare const isTruthy: (v: unknown) => boolean;
+
 /** A JSON value (for `params` / `input` / a `structured` step's JSON Schema). */
 export declare const Json: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
 
@@ -329,7 +383,7 @@ export declare const RunStep: Schema.Struct<{
     title: typeof Schema.String;
     description: Schema.optional<typeof Schema.String>;
     type: Schema.Literal<["agent", "generate", "structured", "note", "human"]>;
-    status: Schema.Literal<["pending", "running", "waiting", "succeeded", "failed"]>;
+    status: Schema.Literal<["pending", "running", "waiting", "succeeded", "failed", "skipped"]>;
     startedAt: Schema.optional<typeof Schema.String>;
     completedAt: Schema.optional<typeof Schema.String>;
     /** Per-step cost in micro-USD (the app view projects to €/cents). */
@@ -343,6 +397,9 @@ export declare const RunStep: Schema.Struct<{
         text: typeof Schema.String;
     }>>;
     errorMessage: Schema.optional<typeof Schema.String>;
+    /** Why a `skipped` step was skipped — the rendered condition, so the timeline
+     *  says "{{approved}} is not set" instead of leaving a silent gap. */
+    skipReason: Schema.optional<typeof Schema.String>;
     review: Schema.optional<Schema.Struct<{
         mode: Schema.Literal<["approve", "choice", "text"]>;
         options: Schema.optional<Schema.Array$<Schema.Struct<{
@@ -371,16 +428,36 @@ export declare interface RunStep {
         readonly text: string;
     } | undefined;
     readonly errorMessage?: string | undefined;
+    readonly skipReason?: string | undefined;
     readonly review?: RunReview | undefined;
 }
 
-export declare const RunStepStatus: Schema.Literal<["pending", "running", "waiting", "succeeded", "failed"]>;
+export declare const RunStepStatus: Schema.Literal<["pending", "running", "waiting", "succeeded", "failed", "skipped"]>;
 
 export declare type RunStepStatus = typeof RunStepStatus.Type;
 
 /** Sanitize an outputKey to the `{{ref}}`-safe charset. */
 export declare const sanitizeOutputKey: (key: string) => string;
 
+declare const StepCondition: Schema.Struct<{
+    /** A brief-field key or an EARLIER step's `outputKey`. */
+    ref: typeof Schema.String;
+    op: Schema.Literal<["truthy", "falsy", "eq", "neq", "contains"]>;
+    /** The right-hand side for `eq` / `neq` / `contains`. Ignored by the unary ops. */
+    value: Schema.optional<typeof Schema.Unknown>;
+}>;
+
+/** An INTERFACE, for the same api-report reason as `FlowStep` — it is reached
+ *  from an exported table column, and an alias to a mapped type gets expanded
+ *  structurally in an order that is not stable across build scopes. */
+declare interface StepCondition {
+    readonly ref: string;
+    readonly op: ConditionOp;
+    readonly value?: unknown;
+}
+export { StepCondition }
+export { StepCondition as StepConditionType }
+
 /** The five step types. `generate` fans out to four modalities. */
 export declare const StepType: Schema.Literal<["agent", "generate", "structured", "note", "human"]>;
 

package/dist/ir.js

@@ -1,104 +1,2 @@
-import { Schema as e } from "effect";
-//#region src/ir.ts
-var t = e.Literal("deterministic", "agentic"), n = e.Literal("draft", "active", "archived"), r = e.Literal("private", "organization", "shared"), i = e.Literal("pending", "running", "waiting", "succeeded", "failed", "cancelled"), a = e.Literal("manual", "cron"), o = e.Literal("agent", "generate", "structured", "note", "human"), s = e.Literal("text", "image", "video", "audio"), c = e.Literal("approve", "choice", "text"), l = e.Struct({
-	value: e.String,
-	label: e.String
-}), u = e.Union(e.Struct({
-	from: e.Literal("upload"),
-	url: e.String
-}), e.Struct({
-	from: e.Literal("step"),
-	ref: e.String
-})), d = e.Record({
-	key: e.String,
-	value: u
-}), f = e.Record({
-	key: e.String,
-	value: e.Unknown
-}), p = e.Struct({
-	id: e.String,
-	title: e.optional(e.String),
-	description: e.optional(e.String),
-	type: o,
-	outputKey: e.optional(e.String),
-	prompt: e.optional(e.String),
-	modality: e.optional(s),
-	model: e.optional(e.String),
-	params: e.optional(f),
-	mediaInputs: e.optional(d),
-	agentRef: e.optional(e.String),
-	schema: e.optional(f),
-	reviewMode: e.optional(c),
-	options: e.optional(e.Array(l)),
-	timeoutMs: e.optional(e.Number)
-}), m = e.Struct({
-	key: e.String,
-	label: e.String,
-	type: e.Literal("text", "textarea", "number", "boolean"),
-	required: e.optional(e.Boolean),
-	placeholder: e.optional(e.String)
-}), h = e.Struct({
-	flowRef: e.String,
-	mappings: e.Array(e.Struct({
-		targetKey: e.String,
-		sourceKey: e.String
-	})),
-	requireConfirmation: e.optional(e.Boolean)
-}), g = e.Struct({
-	frequency: e.optional(e.Literal("weekly", "monthly")),
-	repeats: e.Array(e.Number),
-	intervalWeeks: e.optional(e.Number),
-	anchorDate: e.optional(e.String),
-	weekOfMonth: e.optional(e.Union(e.Literal(1, 2, 3, 4), e.Literal("last"))),
-	hour: e.optional(e.Number),
-	minute: e.optional(e.Literal(0, 15, 30, 45)),
-	defaultInput: e.optional(f)
-}), _ = e.Literal("pending", "running", "waiting", "succeeded", "failed"), v = e.Struct({
-	mode: c,
-	options: e.optional(e.Array(l)),
-	prompt: e.String
-}), y = e.Struct({
-	id: e.Number,
-	title: e.String,
-	description: e.optional(e.String),
-	type: o,
-	status: _,
-	startedAt: e.optional(e.String),
-	completedAt: e.optional(e.String),
-	costMicroUsd: e.optional(e.Number),
-	requestId: e.optional(e.String),
-	url: e.optional(e.String),
-	output: e.optional(e.Struct({ text: e.String })),
-	errorMessage: e.optional(e.String),
-	review: e.optional(v)
-}), b = e.Struct({
-	decision: e.optional(e.Literal("approve", "reject")),
-	value: e.optional(e.String),
-	text: e.optional(e.String),
-	respondedAt: e.optional(e.String)
-}), x = e.Struct({
-	flowRef: e.String,
-	input: f,
-	status: e.Literal("pending", "confirmed", "dismissed")
-}), S = 30, C = 1, w = 100, T = (e) => e == null || !Number.isFinite(e) ? 30 : Math.min(100, Math.max(1, Math.trunc(e))), E = (e) => e.replace(/[^\w.-]/g, "_"), D = (e) => {
-	let t = (e.steps ?? []).map((e) => e.outputKey ? {
-		...e,
-		outputKey: E(e.outputKey)
-	} : e), n = e.orchestratorModel || e.orchestratorInstructions ? {
-		...e.orchestratorModel ? { model: e.orchestratorModel } : {},
-		...e.orchestratorInstructions ? { instructions: e.orchestratorInstructions } : {}
-	} : void 0;
-	return {
-		name: e.name,
-		mode: e.mode ?? "deterministic",
-		steps: t,
-		maxSteps: T(e.maxSteps),
-		brief: e.brief ?? [],
-		...n ? { orchestrator: n } : {},
-		...e.chain ? { chain: e.chain } : {},
-		...e.cadence ? { cadence: e.cadence } : {},
-		...e.humanTimeoutMs != null && Number.isFinite(e.humanTimeoutMs) ? { humanTimeoutMs: e.humanTimeoutMs } : {}
-	};
-};
-//#endregion
-export { m as BriefField, x as ChainPending, g as FlowCadence, h as FlowChain, t as FlowMode, n as FlowStatus, p as FlowStep, b as HumanResponse, f as Json, S as MAX_STEPS_DEFAULT, w as MAX_STEPS_MAX, C as MAX_STEPS_MIN, u as MediaInputSlot, d as MediaInputs, s as Modality, c as ReviewMode, l as ReviewOption, v as RunReview, a as RunSource, i as RunStatus, y as RunStep, _ as RunStepStatus, o as StepType, r as Visibility, T as clampMaxSteps, D as normalizeFlow, E as sanitizeOutputKey };
+import { A as e, C as t, D as n, E as r, M as i, O as a, S as o, T as s, _ as c, a as l, b as u, c as d, d as f, f as p, g as m, h, i as g, j as _, k as v, l as y, m as b, n as x, o as S, p as C, r as w, s as T, t as E, u as D, v as O, w as k, x as A, y as j } from "./ir-BOv5uwYI.js";
+export { E as BriefField, x as ChainPending, a as ConditionOp, w as FlowCadence, g as FlowChain, l as FlowMode, S as FlowStatus, T as FlowStep, d as HumanResponse, y as Json, D as MAX_STEPS_DEFAULT, f as MAX_STEPS_MAX, p as MAX_STEPS_MIN, C as MediaInputSlot, b as MediaInputs, h as Modality, m as ReviewMode, c as ReviewOption, O as RunReview, j as RunSource, u as RunStatus, A as RunStep, o as RunStepStatus, v as StepCondition, t as StepType, k as Visibility, s as clampMaxSteps, e as describeCondition, _ as evaluateCondition, i as isTruthy, r as normalizeFlow, n as sanitizeOutputKey };

package/dist/web.d.ts

@@ -28,6 +28,11 @@ export declare interface BriefField {
  */
 export declare const cadenceMatches: (cadence: FlowCadence, now: Date) => boolean;
 
+/** The comparison a `when:` performs. */
+declare const ConditionOp: Schema.Literal<["truthy", "falsy", "eq", "neq", "contains"]>;
+
+declare type ConditionOp = typeof ConditionOp.Type;
+
 export declare const DEFAULT_FLOW_RPC_TAGS: FlowRpcTags;
 
 /** Schedule spec — richer than a single cron expr (weekly interval + anchor,
@@ -193,6 +198,24 @@ export declare const FlowStep: Schema.Struct<{
         value: typeof Schema.String;
         label: typeof Schema.String;
     }>>>;
+    /** Gate this step on a prior value. Absent → the step always runs. A step
+     *  whose condition is false is SKIPPED, not failed: it produces no output, so
+     *  anything referencing its `outputKey` sees an absent value. */
+    when: Schema.optional<Schema.Struct<{
+        ref: typeof Schema.String;
+        op: Schema.Literal<["truthy", "falsy", "eq", "neq", "contains"]>;
+        value: Schema.optional<typeof Schema.Unknown>;
+    }>>;
+    /**
+     * Fan-out group. CONSECUTIVE steps sharing a group name run CONCURRENTLY,
+     * each still journaled as its own durable step.
+     *
+     * Steps in one group may not reference each other's outputs — they have no
+     * order between them — and `validateFlow` refuses a flow that tries. A `human`
+     * step may not join a group either: it suspends the whole workflow, which is
+     * not a thing one branch of a fan-out can do.
+     */
+    group: Schema.optional<typeof Schema.String>;
     /** `human` step only — how long the run parks awaiting this review before it
      *  fails, in milliseconds. Omitted → the flow's `humanTimeoutMs`, then the
      *  engine/plugin default (see `resolveHumanReviewTimeoutMs`). `0` means WAIT
@@ -238,6 +261,8 @@ export declare interface FlowStep {
     readonly schema?: Json | undefined;
     readonly reviewMode?: ReviewMode | undefined;
     readonly options?: ReadonlyArray<ReviewOption> | undefined;
+    readonly when?: StepCondition | undefined;
+    readonly group?: string | undefined;
     readonly timeoutMs?: number | undefined;
 }
 
@@ -330,7 +355,7 @@ export declare const RunStep: Schema.Struct<{
     title: typeof Schema.String;
     description: Schema.optional<typeof Schema.String>;
     type: Schema.Literal<["agent", "generate", "structured", "note", "human"]>;
-    status: Schema.Literal<["pending", "running", "waiting", "succeeded", "failed"]>;
+    status: Schema.Literal<["pending", "running", "waiting", "succeeded", "failed", "skipped"]>;
     startedAt: Schema.optional<typeof Schema.String>;
     completedAt: Schema.optional<typeof Schema.String>;
     /** Per-step cost in micro-USD (the app view projects to €/cents). */
@@ -344,6 +369,9 @@ export declare const RunStep: Schema.Struct<{
         text: typeof Schema.String;
     }>>;
     errorMessage: Schema.optional<typeof Schema.String>;
+    /** Why a `skipped` step was skipped — the rendered condition, so the timeline
+     *  says "{{approved}} is not set" instead of leaving a silent gap. */
+    skipReason: Schema.optional<typeof Schema.String>;
     review: Schema.optional<Schema.Struct<{
         mode: Schema.Literal<["approve", "choice", "text"]>;
         options: Schema.optional<Schema.Array$<Schema.Struct<{
@@ -372,13 +400,31 @@ export declare interface RunStep {
         readonly text: string;
     } | undefined;
     readonly errorMessage?: string | undefined;
+    readonly skipReason?: string | undefined;
     readonly review?: RunReview | undefined;
 }
 
-declare const RunStepStatus: Schema.Literal<["pending", "running", "waiting", "succeeded", "failed"]>;
+declare const RunStepStatus: Schema.Literal<["pending", "running", "waiting", "succeeded", "failed", "skipped"]>;
 
 declare type RunStepStatus = typeof RunStepStatus.Type;
 
+declare const StepCondition: Schema.Struct<{
+    /** A brief-field key or an EARLIER step's `outputKey`. */
+    ref: typeof Schema.String;
+    op: Schema.Literal<["truthy", "falsy", "eq", "neq", "contains"]>;
+    /** The right-hand side for `eq` / `neq` / `contains`. Ignored by the unary ops. */
+    value: Schema.optional<typeof Schema.Unknown>;
+}>;
+
+/** An INTERFACE, for the same api-report reason as `FlowStep` — it is reached
+ *  from an exported table column, and an alias to a mapped type gets expanded
+ *  structurally in an order that is not stable across build scopes. */
+declare interface StepCondition {
+    readonly ref: string;
+    readonly op: ConditionOp;
+    readonly value?: unknown;
+}
+
 /** The five step types. `generate` fans out to four modalities. */
 export declare const StepType: Schema.Literal<["agent", "generate", "structured", "note", "human"]>;
 

package/dist/workflow.d.ts

@@ -12,6 +12,7 @@ export declare interface FlowRunPayload {
     readonly input: Record<string, unknown>;
     readonly source: 'manual' | 'cron';
     readonly requestId: string;
+    readonly chainPath?: ReadonlyArray<string> | undefined;
 }
 
 /**
@@ -30,6 +31,19 @@ export declare const flowRunWorkflow: Workflow<"flow.run", Schema.Struct<{
     source: Schema.Literal<["manual", "cron"]>;
     /** Correlation + idempotency key. */
     requestId: typeof Schema.String;
+    /**
+     * The chain of flows that led here, oldest first, INCLUDING this one.
+     *
+     * `chainTo` had a self-chain guard and nothing else, so A→B→A was an
+     * unbounded loop: each hop started a fresh child workflow with a fresh
+     * `requestId`, so idempotency never collapsed it and nothing counted the
+     * hops. The framework would happily run it until an operator noticed the
+     * bill.
+     *
+     * Optional so a run started by an older caller (or by hand) still decodes;
+     * an absent path is read as "this is the first flow", which it is.
+     */
+    chainPath: Schema.optional<Schema.Array$<typeof Schema.String>>;
 }>, Schema.Struct<{
     runId: typeof Schema.String;
     status: Schema.Literal<["succeeded", "failed", "cancelled", "waiting"]>;

package/dist/workflow.js

@@ -11,7 +11,8 @@ var n = "flow.run", r = "flow-human-response", i = (e) => `${r}:${e}`, a = t({
 			value: e.Unknown
 		}),
 		source: e.Literal("manual", "cron"),
-		requestId: e.String
+		requestId: e.String,
+		chainPath: e.optional(e.Array(e.String))
 	},
 	success: e.Struct({
 		runId: e.String,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-ai-flows",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "AI Flows — durable multi-step AI pipelines (deterministic + agentic) with human-in-the-loop, chaining, and cadence. Author flows in code (defineFlow) or as data (visual editor rows); one engine runs both on @voltro/workflow durability, @voltro/ai generation, storage artifacts, and notifications.",
   "keywords": [
     "voltro",
@@ -58,16 +58,16 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/ai": "0.34.0",
-    "@voltro/client": "0.34.0",
-    "@voltro/database": "0.34.0",
-    "@voltro/env": "0.34.0",
-    "@voltro/plugin-audit": "0.34.0",
-    "@voltro/plugin-multitenancy": "0.34.0",
-    "@voltro/plugin-soft-delete": "0.34.0",
-    "@voltro/protocol": "0.34.0",
-    "@voltro/runtime": "0.34.0",
-    "@voltro/workflow": "0.34.0"
+    "@voltro/ai": "0.35.0",
+    "@voltro/client": "0.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/plugin-audit": "0.35.0",
+    "@voltro/plugin-multitenancy": "0.35.0",
+    "@voltro/plugin-soft-delete": "0.35.0",
+    "@voltro/protocol": "0.35.0",
+    "@voltro/runtime": "0.35.0",
+    "@voltro/workflow": "0.35.0"
   },
   "peerDependencies": {
     "effect": "^3.22.0"