@voltro/plugin-ai-flows 0.1.0

package/dist/ir.d.ts

@@ -0,0 +1,279 @@
+import { Schema } from 'effect';
+
+/** A launch-form field. The run `input` is keyed by these `key`s. */
+export declare const BriefField: Schema.Struct<{
+    key: typeof Schema.String;
+    label: typeof Schema.String;
+    type: Schema.Literal<["text", "textarea", "number", "boolean"]>;
+    required: Schema.optional<typeof Schema.Boolean>;
+    placeholder: Schema.optional<typeof Schema.String>;
+}>;
+
+export declare type BriefField = typeof BriefField.Type;
+
+/** Staged follow-up when `chainTo.requireConfirmation` is set. */
+export declare const ChainPending: Schema.Struct<{
+    flowRef: typeof Schema.String;
+    input: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+    status: Schema.Literal<["pending", "confirmed", "dismissed"]>;
+}>;
+
+export declare type ChainPending = typeof ChainPending.Type;
+
+export declare const clampMaxSteps: (n: number | null | undefined) => number;
+
+/** 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<{
+    frequency: Schema.optional<Schema.Literal<["weekly", "monthly"]>>;
+    /** Weekdays, 0=Monday … 6=Sunday. */
+    repeats: Schema.Array$<typeof Schema.Number>;
+    /** Weekly cycle length: 1 | 2 | 4 (anchored by anchorDate). */
+    intervalWeeks: Schema.optional<typeof Schema.Number>;
+    /** ISO YYYY-MM-DD, cycle-0 week (interval > 1). */
+    anchorDate: Schema.optional<typeof Schema.String>;
+    weekOfMonth: Schema.optional<Schema.Union<[Schema.Literal<[1, 2, 3, 4]>, Schema.Literal<["last"]>]>>;
+    /** 0-23, default 9. */
+    hour: Schema.optional<typeof Schema.Number>;
+    minute: Schema.optional<Schema.Literal<[0, 15, 30, 45]>>;
+    /** Brief for unattended cron runs. */
+    defaultInput: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>;
+
+export declare type FlowCadence = typeof FlowCadence.Type;
+
+/** Follow-up flow spec. On success, map source → the child's brief. */
+export declare const FlowChain: Schema.Struct<{
+    /** Child flow id (data) or name (code). */
+    flowRef: typeof Schema.String;
+    mappings: Schema.Array$<Schema.Struct<{
+        targetKey: typeof Schema.String;
+        sourceKey: typeof Schema.String;
+    }>>;
+    requireConfirmation: Schema.optional<typeof Schema.Boolean>;
+}>;
+
+export declare type FlowChain = typeof FlowChain.Type;
+
+/** The raw flow definition either front door supplies before normalization.
+ *  Optional fields tolerate explicit `undefined` (row reads produce it). */
+export declare interface FlowDefinitionInput {
+    readonly name: string;
+    readonly mode?: FlowMode | undefined;
+    readonly steps?: ReadonlyArray<FlowStep> | undefined;
+    readonly maxSteps?: number | null | undefined;
+    readonly brief?: ReadonlyArray<BriefField> | undefined;
+    readonly orchestratorModel?: string | null | undefined;
+    readonly orchestratorInstructions?: string | null | undefined;
+    readonly chain?: FlowChain | null | undefined;
+    readonly cadence?: FlowCadence | null | undefined;
+}
+
+/** The single representation the engine interprets, from either front door. */
+export declare interface FlowIR {
+    readonly name: string;
+    readonly mode: FlowMode;
+    readonly steps: ReadonlyArray<FlowStep>;
+    readonly maxSteps: number;
+    readonly brief: ReadonlyArray<BriefField>;
+    readonly orchestrator?: {
+        readonly model?: string;
+        readonly instructions?: string;
+    };
+    readonly chain?: FlowChain;
+    readonly cadence?: FlowCadence;
+}
+
+/** Execution mode. Replaces the legacy `allowDeviation` boolean — a mode is not
+ *  a boolean. `deterministic` runs the plan verbatim (resumable per step);
+ *  `agentic` lets an orchestrator LLM adapt the plan via the four tools. */
+export declare const FlowMode: Schema.Literal<["deterministic", "agentic"]>;
+
+export declare type FlowMode = typeof FlowMode.Type;
+
+/** Flow-definition lifecycle. */
+export declare const FlowStatus: Schema.Literal<["draft", "active", "archived"]>;
+
+export declare type FlowStatus = typeof FlowStatus.Type;
+
+/**
+ * A plan step. This is the AUTHORED shape — stored on `ai_flows.steps` (data
+ * front door) or produced by `defineFlow`'s builders (code front door). The
+ * engine interprets it; later steps reference an earlier step's deliverable via
+ * `{{outputKey}}` in `prompt` / media refs.
+ */
+export declare const FlowStep: Schema.Struct<{
+    id: typeof Schema.String;
+    title: Schema.optional<typeof Schema.String>;
+    /** Informational; shown under the step in the run timeline. */
+    description: Schema.optional<typeof Schema.String>;
+    type: Schema.Literal<["agent", "generate", "structured", "note", "human"]>;
+    /** Sanitized [\w.-]; the result-bundle key + the `{{ref}}` name. */
+    outputKey: Schema.optional<typeof Schema.String>;
+    /** Template with `{{key}}` placeholders (brief inputs + prior outputKeys). */
+    prompt: Schema.optional<typeof Schema.String>;
+    modality: Schema.optional<Schema.Literal<["text", "image", "video", "audio"]>>;
+    model: Schema.optional<typeof Schema.String>;
+    params: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    mediaInputs: Schema.optional<Schema.Record$<typeof Schema.String, Schema.Union<[Schema.Struct<{
+        from: Schema.Literal<["upload"]>;
+        url: typeof Schema.String;
+    }>, Schema.Struct<{
+        from: Schema.Literal<["step"]>;
+        ref: typeof Schema.String;
+    }>]>>>;
+    /** Allowed sub-agent id/name. The framework resolves a real id; any
+     *  legacy-numeric bridge stays in the consumer app's mapping. */
+    agentRef: Schema.optional<typeof Schema.String>;
+    /** JSON Schema of the desired object (adapted to an Effect Schema at run). */
+    schema: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    reviewMode: Schema.optional<Schema.Literal<["approve", "choice", "text"]>>;
+    options: Schema.optional<Schema.Array$<Schema.Struct<{
+        value: typeof Schema.String;
+        label: typeof Schema.String;
+    }>>>;
+}>;
+
+export declare type FlowStep = typeof FlowStep.Type;
+
+/** The HITL answer, written by `respond`. */
+export declare const HumanResponse: Schema.Struct<{
+    decision: Schema.optional<Schema.Literal<["approve", "reject"]>>;
+    value: Schema.optional<typeof Schema.String>;
+    text: Schema.optional<typeof Schema.String>;
+    respondedAt: Schema.optional<typeof Schema.String>;
+}>;
+
+export declare type HumanResponse = typeof HumanResponse.Type;
+
+/** A JSON value (for `params` / `input` / a `structured` step's JSON Schema). */
+export declare const Json: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+
+export declare type Json = typeof Json.Type;
+
+/** 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;
+
+export declare const MAX_STEPS_MAX = 100;
+
+export declare const MAX_STEPS_MIN = 1;
+
+export declare const MediaInputs: Schema.Record$<typeof Schema.String, Schema.Union<[Schema.Struct<{
+    from: Schema.Literal<["upload"]>;
+    url: typeof Schema.String;
+}>, Schema.Struct<{
+    from: Schema.Literal<["step"]>;
+    ref: typeof Schema.String;
+}>]>>;
+
+export declare type MediaInputs = typeof MediaInputs.Type;
+
+/** A media-input slot for a video `generate` step — either an uploaded URL or a
+ *  reference to a prior step's output. Keyed by capability slot name
+ *  (`referenceImageUrl`, `lastFrameImageUrl`, `referenceVideoUrl`, …). */
+export declare const MediaInputSlot: Schema.Union<[Schema.Struct<{
+    from: Schema.Literal<["upload"]>;
+    url: typeof Schema.String;
+}>, Schema.Struct<{
+    from: Schema.Literal<["step"]>;
+    ref: typeof Schema.String;
+}>]>;
+
+export declare type MediaInputSlot = typeof MediaInputSlot.Type;
+
+export declare const Modality: Schema.Literal<["text", "image", "video", "audio"]>;
+
+export declare type Modality = typeof Modality.Type;
+
+/**
+ * Lower a raw flow definition (from code or a row) to the normalized IR:
+ * default the mode, clamp maxSteps, sanitize outputKeys, drop empties. Pure +
+ * browser-safe so the editor can preview exactly what the engine will run.
+ */
+export declare const normalizeFlow: (def: FlowDefinitionInput) => FlowIR;
+
+export declare const ReviewMode: Schema.Literal<["approve", "choice", "text"]>;
+
+export declare type ReviewMode = typeof ReviewMode.Type;
+
+export declare const ReviewOption: Schema.Struct<{
+    value: typeof Schema.String;
+    label: typeof Schema.String;
+}>;
+
+export declare type ReviewOption = typeof ReviewOption.Type;
+
+/** Human-review config projected onto a `waiting` run step. */
+export declare const RunReview: Schema.Struct<{
+    mode: Schema.Literal<["approve", "choice", "text"]>;
+    options: Schema.optional<Schema.Array$<Schema.Struct<{
+        value: typeof Schema.String;
+        label: typeof Schema.String;
+    }>>>;
+    prompt: typeof Schema.String;
+}>;
+
+export declare type RunReview = typeof RunReview.Type;
+
+/** What triggered a run. */
+export declare const RunSource: Schema.Literal<["manual", "cron"]>;
+
+export declare type RunSource = typeof RunSource.Type;
+
+/** Run status — ONE canonical set (the legacy vocabulary; the Voltro-port
+ *  additions `awaiting_human`/`completed`/`rejected` are collapsed: `waiting`
+ *  covers the human pause, `succeeded` is the single terminal-success literal). */
+export declare const RunStatus: Schema.Literal<["pending", "running", "waiting", "succeeded", "failed", "cancelled"]>;
+
+export declare type RunStatus = typeof RunStatus.Type;
+
+export declare const RunStep: Schema.Struct<{
+    id: typeof Schema.Number;
+    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"]>;
+    startedAt: Schema.optional<typeof Schema.String>;
+    completedAt: Schema.optional<typeof Schema.String>;
+    /** Per-step cost in micro-USD (the app view projects to €/cents). */
+    costMicroUsd: Schema.optional<typeof Schema.Number>;
+    /** Links a media step to its generation/usage record. */
+    requestId: Schema.optional<typeof Schema.String>;
+    /** Hosted media artifact URL (image/video/audio), via storage. */
+    url: Schema.optional<typeof Schema.String>;
+    /** Inline text output (rendered as markdown). */
+    output: Schema.optional<Schema.Struct<{
+        text: typeof Schema.String;
+    }>>;
+    errorMessage: Schema.optional<typeof Schema.String>;
+    review: Schema.optional<Schema.Struct<{
+        mode: Schema.Literal<["approve", "choice", "text"]>;
+        options: Schema.optional<Schema.Array$<Schema.Struct<{
+            value: typeof Schema.String;
+            label: typeof Schema.String;
+        }>>>;
+        prompt: typeof Schema.String;
+    }>>;
+}>;
+
+export declare type RunStep = typeof RunStep.Type;
+
+export declare const RunStepStatus: Schema.Literal<["pending", "running", "waiting", "succeeded", "failed"]>;
+
+export declare type RunStepStatus = typeof RunStepStatus.Type;
+
+/** Sanitize an outputKey to the `{{ref}}`-safe charset. */
+export declare const sanitizeOutputKey: (key: string) => string;
+
+/** The five step types. `generate` fans out to four modalities. */
+export declare const StepType: Schema.Literal<["agent", "generate", "structured", "note", "human"]>;
+
+export declare type StepType = typeof StepType.Type;
+
+/** Gallery scope. `shared` → per-subject share list; `organization` → tenant. */
+export declare const Visibility: Schema.Literal<["private", "organization", "shared"]>;
+
+export declare type Visibility = typeof Visibility.Type;
+
+export { }

package/dist/ir.js

@@ -0,0 +1,102 @@
+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 };

package/dist/rpc.d.ts

@@ -0,0 +1,7 @@
+import { PluginRpcClientDescriptor } from '@voltro/protocol';
+
+/** One `{ tag, kind, import }` per client-callable route. Populated when the
+ *  launch/retry/cancel/respond descriptors land. */
+export declare const aiFlowsRpcClientImports: ReadonlyArray<PluginRpcClientDescriptor>;
+
+export { }

package/dist/rpc.js

@@ -0,0 +1,4 @@
+//#region src/rpc.ts
+var e = [];
+//#endregion
+export { e as aiFlowsRpcClientImports };

package/dist/web.d.ts

@@ -0,0 +1,176 @@
+import { Schema } from 'effect';
+
+/** A launch-form field. The run `input` is keyed by these `key`s. */
+export declare const BriefField: Schema.Struct<{
+    key: typeof Schema.String;
+    label: typeof Schema.String;
+    type: Schema.Literal<["text", "textarea", "number", "boolean"]>;
+    required: Schema.optional<typeof Schema.Boolean>;
+    placeholder: Schema.optional<typeof Schema.String>;
+}>;
+
+export declare type BriefField = typeof BriefField.Type;
+
+/**
+ * Does `cadence` fire at wall-clock `now`? True only on a 15-min slot matching
+ * the configured hour/minute, on a configured weekday, and — for interval-weekly
+ * or monthly cadences — in the right week/occurrence.
+ */
+export declare const cadenceMatches: (cadence: FlowCadence, now: Date) => 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<{
+    frequency: Schema.optional<Schema.Literal<["weekly", "monthly"]>>;
+    /** Weekdays, 0=Monday … 6=Sunday. */
+    repeats: Schema.Array$<typeof Schema.Number>;
+    /** Weekly cycle length: 1 | 2 | 4 (anchored by anchorDate). */
+    intervalWeeks: Schema.optional<typeof Schema.Number>;
+    /** ISO YYYY-MM-DD, cycle-0 week (interval > 1). */
+    anchorDate: Schema.optional<typeof Schema.String>;
+    weekOfMonth: Schema.optional<Schema.Union<[Schema.Literal<[1, 2, 3, 4]>, Schema.Literal<["last"]>]>>;
+    /** 0-23, default 9. */
+    hour: Schema.optional<typeof Schema.Number>;
+    minute: Schema.optional<Schema.Literal<[0, 15, 30, 45]>>;
+    /** Brief for unattended cron runs. */
+    defaultInput: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>;
+
+export declare type FlowCadence = typeof FlowCadence.Type;
+
+/** Follow-up flow spec. On success, map source → the child's brief. */
+export declare const FlowChain: Schema.Struct<{
+    /** Child flow id (data) or name (code). */
+    flowRef: typeof Schema.String;
+    mappings: Schema.Array$<Schema.Struct<{
+        targetKey: typeof Schema.String;
+        sourceKey: typeof Schema.String;
+    }>>;
+    requireConfirmation: Schema.optional<typeof Schema.Boolean>;
+}>;
+
+export declare type FlowChain = typeof FlowChain.Type;
+
+/** Execution mode. Replaces the legacy `allowDeviation` boolean — a mode is not
+ *  a boolean. `deterministic` runs the plan verbatim (resumable per step);
+ *  `agentic` lets an orchestrator LLM adapt the plan via the four tools. */
+export declare const FlowMode: Schema.Literal<["deterministic", "agentic"]>;
+
+export declare type FlowMode = typeof FlowMode.Type;
+
+/** Flow-definition lifecycle. */
+export declare const FlowStatus: Schema.Literal<["draft", "active", "archived"]>;
+
+export declare type FlowStatus = typeof FlowStatus.Type;
+
+/**
+ * A plan step. This is the AUTHORED shape — stored on `ai_flows.steps` (data
+ * front door) or produced by `defineFlow`'s builders (code front door). The
+ * engine interprets it; later steps reference an earlier step's deliverable via
+ * `{{outputKey}}` in `prompt` / media refs.
+ */
+export declare const FlowStep: Schema.Struct<{
+    id: typeof Schema.String;
+    title: Schema.optional<typeof Schema.String>;
+    /** Informational; shown under the step in the run timeline. */
+    description: Schema.optional<typeof Schema.String>;
+    type: Schema.Literal<["agent", "generate", "structured", "note", "human"]>;
+    /** Sanitized [\w.-]; the result-bundle key + the `{{ref}}` name. */
+    outputKey: Schema.optional<typeof Schema.String>;
+    /** Template with `{{key}}` placeholders (brief inputs + prior outputKeys). */
+    prompt: Schema.optional<typeof Schema.String>;
+    modality: Schema.optional<Schema.Literal<["text", "image", "video", "audio"]>>;
+    model: Schema.optional<typeof Schema.String>;
+    params: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    mediaInputs: Schema.optional<Schema.Record$<typeof Schema.String, Schema.Union<[Schema.Struct<{
+        from: Schema.Literal<["upload"]>;
+        url: typeof Schema.String;
+    }>, Schema.Struct<{
+        from: Schema.Literal<["step"]>;
+        ref: typeof Schema.String;
+    }>]>>>;
+    /** Allowed sub-agent id/name. The framework resolves a real id; any
+     *  legacy-numeric bridge stays in the consumer app's mapping. */
+    agentRef: Schema.optional<typeof Schema.String>;
+    /** JSON Schema of the desired object (adapted to an Effect Schema at run). */
+    schema: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    reviewMode: Schema.optional<Schema.Literal<["approve", "choice", "text"]>>;
+    options: Schema.optional<Schema.Array$<Schema.Struct<{
+        value: typeof Schema.String;
+        label: typeof Schema.String;
+    }>>>;
+}>;
+
+export declare type FlowStep = typeof FlowStep.Type;
+
+export declare const Modality: Schema.Literal<["text", "image", "video", "audio"]>;
+
+export declare type Modality = typeof Modality.Type;
+
+/**
+ * The next `count` fire times at/after `from`, by stepping 15-min slots and
+ * testing `cadenceMatches`. Bounded to a ~400-day horizon so a never-matching
+ * cadence can't loop forever. Returns the fire `Date`s.
+ */
+export declare const nextRuns: (cadence: FlowCadence, from: Date, count?: number) => ReadonlyArray<Date>;
+
+export declare const ReviewMode: Schema.Literal<["approve", "choice", "text"]>;
+
+export declare type ReviewMode = typeof ReviewMode.Type;
+
+export declare const ReviewOption: Schema.Struct<{
+    value: typeof Schema.String;
+    label: typeof Schema.String;
+}>;
+
+export declare type ReviewOption = typeof ReviewOption.Type;
+
+/** Run status — ONE canonical set (the legacy vocabulary; the Voltro-port
+ *  additions `awaiting_human`/`completed`/`rejected` are collapsed: `waiting`
+ *  covers the human pause, `succeeded` is the single terminal-success literal). */
+export declare const RunStatus: Schema.Literal<["pending", "running", "waiting", "succeeded", "failed", "cancelled"]>;
+
+export declare type RunStatus = typeof RunStatus.Type;
+
+export declare const RunStep: Schema.Struct<{
+    id: typeof Schema.Number;
+    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"]>;
+    startedAt: Schema.optional<typeof Schema.String>;
+    completedAt: Schema.optional<typeof Schema.String>;
+    /** Per-step cost in micro-USD (the app view projects to €/cents). */
+    costMicroUsd: Schema.optional<typeof Schema.Number>;
+    /** Links a media step to its generation/usage record. */
+    requestId: Schema.optional<typeof Schema.String>;
+    /** Hosted media artifact URL (image/video/audio), via storage. */
+    url: Schema.optional<typeof Schema.String>;
+    /** Inline text output (rendered as markdown). */
+    output: Schema.optional<Schema.Struct<{
+        text: typeof Schema.String;
+    }>>;
+    errorMessage: Schema.optional<typeof Schema.String>;
+    review: Schema.optional<Schema.Struct<{
+        mode: Schema.Literal<["approve", "choice", "text"]>;
+        options: Schema.optional<Schema.Array$<Schema.Struct<{
+            value: typeof Schema.String;
+            label: typeof Schema.String;
+        }>>>;
+        prompt: typeof Schema.String;
+    }>>;
+}>;
+
+export declare type RunStep = typeof RunStep.Type;
+
+/** The five step types. `generate` fans out to four modalities. */
+export declare const StepType: Schema.Literal<["agent", "generate", "structured", "note", "human"]>;
+
+export declare type StepType = typeof StepType.Type;
+
+/** Gallery scope. `shared` → per-subject share list; `organization` → tenant. */
+export declare const Visibility: Schema.Literal<["private", "organization", "shared"]>;
+
+export declare type Visibility = typeof Visibility.Type;
+
+export { }

package/dist/web.js

@@ -0,0 +1,2 @@
+import { n as e, t } from "./cadence-Bt6dPelT.js";
+export { t as cadenceMatches, e as nextRuns };

package/dist/workflow.d.ts

@@ -0,0 +1,40 @@
+import { Schema } from 'effect';
+import { Workflow } from '@effect/workflow/Workflow';
+
+/** The canonical name the launch action starts + the app re-export registers. */
+export declare const FLOW_RUN_WORKFLOW = "flow.run";
+
+/** The workflow payload shape (server executor input). */
+export declare interface FlowRunPayload {
+    readonly runId: string;
+    readonly flowRef: string;
+    readonly input: Record<string, unknown>;
+    readonly source: 'manual' | 'cron';
+    readonly requestId: string;
+}
+
+/**
+ * `flow.run` — the single durable workflow that interprets a Flow IR (from a
+ * code registration or a stored `ai_flows` row) step-by-step. `requestId` is the
+ * idempotency key so repeated / crash-replayed starts collapse to one run.
+ */
+export declare const flowRunWorkflow: Workflow<"flow.run", Schema.Struct<{
+    /** The pre-created `ai_flow_runs` row id the executor patches. */
+    runId: typeof Schema.String;
+    /** Name (code flow) or id (data flow) to resolve the IR from. */
+    flowRef: typeof Schema.String;
+    /** Brief values keyed by `BriefField.key`. */
+    input: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+    /** manual | cron. */
+    source: Schema.Literal<["manual", "cron"]>;
+    /** Correlation + idempotency key. */
+    requestId: typeof Schema.String;
+}>, Schema.Struct<{
+    runId: typeof Schema.String;
+    status: Schema.Literal<["succeeded", "failed", "cancelled", "waiting"]>;
+}>, typeof Schema.Never>;
+
+/** The signal a `human` step parks on; `respondToFlow` sends it to resume. */
+export declare const HUMAN_RESPONSE_SIGNAL = "flow-human-response";
+
+export { }

package/dist/workflow.js

@@ -0,0 +1,23 @@
+import { Schema as e } from "effect";
+import { workflow as t } from "@voltro/workflow/define";
+//#region src/workflow.ts
+var n = "flow.run", r = "flow-human-response", i = t({
+	name: n,
+	payload: {
+		runId: e.String,
+		flowRef: e.String,
+		input: e.Record({
+			key: e.String,
+			value: e.Unknown
+		}),
+		source: e.Literal("manual", "cron"),
+		requestId: e.String
+	},
+	success: e.Struct({
+		runId: e.String,
+		status: e.Literal("succeeded", "failed", "cancelled", "waiting")
+	}),
+	idempotencyKey: ({ requestId: e }) => `flow-run:${e}`
+});
+//#endregion
+export { n as FLOW_RUN_WORKFLOW, r as HUMAN_RESPONSE_SIGNAL, i as flowRunWorkflow };