@voltro/plugin-ai-flows 0.33.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

@@ -9,7 +9,17 @@ export declare const BriefField: Schema.Struct<{
     placeholder: Schema.optional<typeof Schema.String>;
 }>;
 
-export declare type BriefField = typeof BriefField.Type;
+/** An INTERFACE for the same reason as {@link FlowStep} — it is reached from an
+ *  exported table (`aiFlows.inputSchema`), so an alias to a mapped type gets
+ *  expanded structurally into the api report, in an order that is not stable
+ *  across build scopes. The `Equals` pin below fails to compile on any drift. */
+export declare interface BriefField {
+    readonly key: string;
+    readonly label: string;
+    readonly type: 'text' | 'textarea' | 'number' | 'boolean';
+    readonly required?: boolean | undefined;
+    readonly placeholder?: string | undefined;
+}
 
 /** Staged follow-up when `chainTo.requireConfirmation` is set. */
 export declare const ChainPending: Schema.Struct<{
@@ -18,10 +28,35 @@ export declare const ChainPending: Schema.Struct<{
     status: Schema.Literal<["pending", "confirmed", "dismissed"]>;
 }>;
 
-export declare type ChainPending = typeof ChainPending.Type;
+/** An INTERFACE — reached from `aiFlowRuns.chainPending`; see {@link BriefField}. */
+export declare interface ChainPending {
+    readonly flowRef: string;
+    readonly input: Json;
+    readonly status: 'pending' | 'confirmed' | 'dismissed';
+}
 
 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<{
@@ -40,7 +75,25 @@ export declare const FlowCadence: Schema.Struct<{
     defaultInput: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
 }>;
 
-export declare type FlowCadence = typeof FlowCadence.Type;
+/**
+ * An INTERFACE — reached from `aiFlows.cadence`; see {@link BriefField}.
+ *
+ * This one is not hypothetical: a single-package `api:report` and a
+ * full-monorepo build emitted `hour`/`minute` in DIFFERENT positions inside the
+ * structurally-expanded alias, so the api-surface gate rejected a file nobody
+ * had touched, showing the same members moving. That is the exact failure
+ * {@link FlowStep}'s comment describes.
+ */
+export declare interface FlowCadence {
+    readonly frequency?: 'weekly' | 'monthly' | undefined;
+    readonly repeats: ReadonlyArray<number>;
+    readonly intervalWeeks?: number | undefined;
+    readonly anchorDate?: string | undefined;
+    readonly weekOfMonth?: 1 | 2 | 3 | 4 | 'last' | undefined;
+    readonly hour?: number | undefined;
+    readonly minute?: 0 | 15 | 30 | 45 | undefined;
+    readonly defaultInput?: Json | undefined;
+}
 
 /** Follow-up flow spec. On success, map source → the child's brief. */
 export declare const FlowChain: Schema.Struct<{
@@ -53,7 +106,15 @@ export declare const FlowChain: Schema.Struct<{
     requireConfirmation: Schema.optional<typeof Schema.Boolean>;
 }>;
 
-export declare type FlowChain = typeof FlowChain.Type;
+/** An INTERFACE — reached from `aiFlows.chainTo`; see {@link BriefField}. */
+export declare interface FlowChain {
+    readonly flowRef: string;
+    readonly mappings: ReadonlyArray<{
+        readonly targetKey: string;
+        readonly sourceKey: string;
+    }>;
+    readonly requireConfirmation?: boolean | undefined;
+}
 
 /** The raw flow definition either front door supplies before normalization.
  *  Optional fields tolerate explicit `undefined` (row reads produce it). */
@@ -67,6 +128,7 @@ export declare interface FlowDefinitionInput {
     readonly orchestratorInstructions?: string | null | undefined;
     readonly chain?: FlowChain | null | undefined;
     readonly cadence?: FlowCadence | null | undefined;
+    readonly humanTimeoutMs?: number | null | undefined;
 }
 
 /** The single representation the engine interprets, from either front door. */
@@ -82,6 +144,10 @@ export declare interface FlowIR {
     };
     readonly chain?: FlowChain;
     readonly cadence?: FlowCadence;
+    /** Flow-wide default for a `human` step's park bound, in ms. A step's own
+     *  `timeoutMs` wins; absent here too → the engine/plugin default. `0` = wait
+     *  forever. */
+    readonly humanTimeoutMs?: number;
 }
 
 /** Execution mode. Replaces the legacy `allowDeviation` boolean — a mode is not
@@ -132,6 +198,29 @@ 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
+     *  FOREVER (the park is slot-free, so an unbounded wait costs no worker). */
+    timeoutMs: Schema.optional<typeof Schema.Number>;
 }>;
 
 /**
@@ -172,6 +261,9 @@ 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;
 }
 
 /** The HITL answer, written by `respond`. */
@@ -182,7 +274,27 @@ export declare const HumanResponse: Schema.Struct<{
     respondedAt: Schema.optional<typeof Schema.String>;
 }>;
 
-export declare type HumanResponse = typeof HumanResponse.Type;
+/** An INTERFACE — reached from `aiFlowRuns.humanResponse`; see {@link BriefField}. */
+export declare interface HumanResponse {
+    readonly decision?: 'approve' | 'reject' | undefined;
+    readonly value?: string | undefined;
+    readonly text?: string | undefined;
+    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>;
@@ -271,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). */
@@ -285,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<{
@@ -313,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,102 +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))
-}), 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 } : {}
-	};
-};
-//#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 };