@voltro/plugin-ai-flows 0.34.0 → 0.36.0

package/dist/index.d.ts

@@ -45,6 +45,15 @@ export declare const aiFlowRunsTable: Table<"_voltro_ai_flow_runs", FieldDefinit
     readonly humanResponse: ColumnBuilder<HumanResponse | null, "json", boolean>;
     /** Staged follow-up when the chain requires confirmation. */
     readonly chainPending: ColumnBuilder<ChainPending | null, "json", boolean>;
+    /**
+     * Why a declared `chainTo` did NOT start — a cycle, or the depth ceiling.
+     *
+     * A column rather than a log line, because the run row is what a user looks
+     * at: a chain that silently does not fire is indistinguishable from a chain
+     * that was never declared, and "the second flow never ran" is precisely the
+     * report this would otherwise generate.
+     */
+    readonly chainRefusal: ColumnBuilder<string | null, "text", boolean>;
     /** Accumulated cost in micro-USD (app view projects to €/cents). */
     readonly costMicroUsd: ColumnBuilder<number, "integer", true>;
     readonly durationMs: ColumnBuilder<number | null, "integer", boolean>;
@@ -72,6 +81,9 @@ export declare const aiFlowRunsTable: Table<"_voltro_ai_flow_runs", FieldDefinit
 export declare interface AiFlowsDefaults {
     /** Park bound for a `human` step, in ms. `0` = wait forever. */
     readonly humanReviewTimeoutMs?: number;
+    /** How many flows one `chainTo` chain may traverse. See
+     *  {@link MAX_CHAIN_DEPTH_DEFAULT}. */
+    readonly maxChainDepth?: number;
 }
 
 /**
@@ -273,6 +285,11 @@ export declare const clearRegistry: () => void;
 /** Every `{{ref}}` name referenced in `text` (order-preserving, may repeat). */
 export declare const collectRefs: (text: string) => ReadonlyArray<string>;
 
+/** The comparison a `when:` performs. */
+export declare const ConditionOp: Schema.Literal<["truthy", "falsy", "eq", "neq", "contains"]>;
+
+export declare type ConditionOp = typeof ConditionOp.Type;
+
 /** Create a flow row. Generates an id when absent; tenant/audit columns are
  *  auto-stamped by the runtime. */
 export declare const createFlow: (ctx: AppContext, fields: Record<string, unknown>) => Effect.Effect<Readonly<Record<string, unknown>>, never, never>;
@@ -309,6 +326,10 @@ export declare const deleteFlow: (ctx: AppContext, args: {
     id: string;
 }) => Effect.Effect<boolean, never, never>;
 
+/** 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;
+
 export declare interface EngineDeps {
     /** Resolve an `agent` step's `agentRef` → system prompt + model. Absent →
      *  agent steps with an `agentRef` fail with FlowCapabilityMissing. */
@@ -339,8 +360,24 @@ export declare interface EngineDeps {
      *  option / `VOLTRO_AI_FLOW_HUMAN_REVIEW_TIMEOUT_HOURS` (see `defaults.ts`).
      *  `0` = wait forever. */
     readonly humanReviewTimeoutMs?: number;
+    /** How many flows one `chainTo` chain may traverse, INCLUDING the flow that
+     *  started it. Sits between nothing and the `aiFlowsPlugin({...})` option /
+     *  `VOLTRO_AI_FLOW_MAX_CHAIN_DEPTH` (see `defaults.ts`). A cycle is refused
+     *  separately and cannot be raised by this number. */
+    readonly maxChainDepth?: number;
 }
 
+/**
+ * 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;
+
 /** The canonical name the launch action starts + the app re-export registers. */
 export declare const FLOW_RUN_WORKFLOW = "flow.run";
 
@@ -525,8 +562,34 @@ export declare interface FlowRunPayload {
     readonly input: Record<string, unknown>;
     readonly source: 'manual' | 'cron';
     readonly requestId: string;
+    readonly chainPath?: ReadonlyArray<string> | undefined;
 }
 
+/** One unit of execution: a single step, or a set that runs concurrently. */
+export declare interface FlowSegment {
+    /** `undefined` for an ungrouped single step. */
+    readonly group?: string | undefined;
+    /** The steps in this segment, with their ORIGINAL indices — the durable step
+     *  name and the timeline slot both key off the index, so it travels. */
+    readonly steps: ReadonlyArray<{
+        readonly index: number;
+        readonly step: FlowStep;
+    }>;
+}
+
+/**
+ * Split a step list into execution segments.
+ *
+ * Only CONSECUTIVE steps sharing a group name form a segment. A group that
+ * reappears after an interruption forms a SECOND segment — which is almost
+ * certainly not what the author meant, so `validateFlow` refuses it rather than
+ * letting this function silently produce two sequential fan-outs from what reads
+ * like one. This function stays permissive on purpose: it is used by the
+ * validator, and a validator whose input has already been sanitised cannot
+ * report on it.
+ */
+export declare const flowSegments: (steps: ReadonlyArray<FlowStep>) => ReadonlyArray<FlowSegment>;
+
 /** Flow-definition lifecycle. */
 export declare const FlowStatus: Schema.Literal<["draft", "active", "archived"]>;
 
@@ -568,6 +631,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
@@ -613,6 +694,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;
 }
 
@@ -626,7 +709,7 @@ export declare const flowStep: {
         prompt: string;
         model?: string;
         outputKey?: string;
-    }) => FlowStepDraft;
+    } & StepControls) => FlowStepDraft;
     /** An image/video/audio generation. */
     media: (modality: Modality, o: {
         title?: string;
@@ -635,7 +718,7 @@ export declare const flowStep: {
         model?: string;
         params?: Record<string, unknown>;
         outputKey?: string;
-    }) => FlowStepDraft;
+    } & StepControls) => FlowStepDraft;
     /** Delegate to an allowed sub-agent (text-only). */
     agent: (o: {
         title?: string;
@@ -644,7 +727,7 @@ export declare const flowStep: {
         prompt: string;
         model?: string;
         outputKey?: string;
-    }) => FlowStepDraft;
+    } & StepControls) => FlowStepDraft;
     /** Return a JSON object validated against a JSON Schema. */
     structured: (o: {
         title?: string;
@@ -653,14 +736,14 @@ export declare const flowStep: {
         schema: Record<string, unknown>;
         model?: string;
         outputKey?: string;
-    }) => FlowStepDraft;
+    } & StepControls) => FlowStepDraft;
     /** Free-text guidance — the interpolated prompt itself is the output. */
     note: (o: {
         title?: string;
         description?: string;
         prompt: string;
         outputKey?: string;
-    }) => FlowStepDraft;
+    } & StepControls) => FlowStepDraft;
     /** Pause for human review. `timeoutMs` bounds the park (default: the flow's
      *  `humanTimeoutMs`, then the plugin default — 7 days; `0` = wait forever). */
     human: (o: {
@@ -671,7 +754,7 @@ export declare const flowStep: {
         prompt?: string;
         outputKey?: string;
         timeoutMs?: number;
-    }) => FlowStepDraft;
+    } & Pick<StepControls, "when">) => FlowStepDraft;
 };
 
 /** A step without its `id` — `defineFlow` assigns stable index-based ids. */
@@ -746,6 +829,20 @@ export declare const humanResponseSignalName: (stepIndex: number) => string;
  *  absent/null value renders empty). */
 export declare const interpolate: (text: string, context: Record<string, unknown>) => string;
 
+/**
+ * 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>;
 
@@ -798,6 +895,20 @@ export declare const makeMediaGenerator: (persist: MediaPersist, opts?: {
     readonly resolveModel?: (model: string) => ProviderConfig;
 }) => MediaGenerator;
 
+/**
+ * How many flows one chain may traverse, including the flow that started it.
+ *
+ * Five, because a chain is a hand-authored pipeline and nobody writes six on
+ * purpose — but the number is a FIELD rather than a constant precisely because
+ * "nobody does that" is an assumption about other people's apps. A cycle is
+ * refused separately and unconditionally; this bounds the acyclic case, where
+ * every hop is a real LLM run somebody pays for.
+ */
+export declare const MAX_CHAIN_DEPTH_DEFAULT = 5;
+
+/** Deploy-time override for {@link MAX_CHAIN_DEPTH_DEFAULT}. */
+export declare const MAX_CHAIN_DEPTH_ENV = "VOLTRO_AI_FLOW_MAX_CHAIN_DEPTH";
+
 /** Legacy default was 30, clamped to [1,100]. (Distinct from `@voltro/ai`'s
  *  own `maxSteps` default of 8 for a single tool loop.) */
 export declare const MAX_STEPS_DEFAULT = 30;
@@ -894,6 +1005,9 @@ export declare type Modality = typeof Modality.Type;
  */
 export declare const nextRuns: (cadence: FlowCadence, from: Date, count?: number) => ReadonlyArray<Date>;
 
+/** Group names that appear in more than one segment — a non-contiguous group. */
+export declare const nonContiguousGroups: (segments: ReadonlyArray<FlowSegment>) => ReadonlyArray<string>;
+
 /**
  * Lower a raw flow definition (from code or a row) to the normalized IR:
  * default the mode, clamp maxSteps, sanitize outputKeys, drop empties. Pure +
@@ -928,6 +1042,20 @@ export declare const resolveHumanReviewTimeoutMs: (input: {
 /** Resolve the IR: code registry by name first, else the stored `ai_flows` row. */
 export declare const resolveIr: (ctx: AppContext, flowRef: string) => Effect.Effect<FlowIR, FlowNotFound>;
 
+/**
+ * Resolve the chain-depth ceiling down the same ladder as every other tunable:
+ * engine deps → plugin option (`app.config.ts`) → env → framework default.
+ *
+ * A value below 1 is IGNORED rather than honoured. `0` would mean "no flow may
+ * chain at all", which is expressible by not declaring a chain, and reading it
+ * literally would turn a typo into a silently disabled feature — the same
+ * reasoning `msFromHoursEnv` applies to a negative timeout.
+ */
+export declare const resolveMaxChainDepth: (deps?: {
+    readonly maxChainDepth?: number | undefined;
+    readonly env?: NodeJS.ProcessEnv;
+}) => number;
+
 /** Record a human's answer to a `waiting` run + signal the parked workflow to
  *  resume. The signal is addressed to THAT STEP's own durable deferred — one
  *  shared name meant a later review resolved with an earlier answer. */
@@ -1001,7 +1129,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). */
@@ -1015,6 +1143,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<{
@@ -1043,10 +1174,11 @@ 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;
 
@@ -1056,6 +1188,34 @@ export declare const sanitizeOutputKey: (key: string) => string;
 /** Record the `app.config.ts` tunables (called by the plugin factory). */
 export declare const setAiFlowsDefaults: (defaults: AiFlowsDefaults) => void;
 
+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 }
+
+/** Gating + fan-out, accepted by every builder. Kept as one type so a new
+ *  builder cannot quietly omit them — the six builders below spread it. */
+declare interface StepControls {
+    /** Run this step only when the condition holds; otherwise SKIP it. */
+    readonly when?: StepCondition;
+    /** Consecutive steps sharing a group run CONCURRENTLY. */
+    readonly group?: string;
+}
+
 /** The five step types. `generate` fans out to four modalities. */
 export declare const StepType: Schema.Literal<["agent", "generate", "structured", "note", "human"]>;