@voltro/plugin-ai-flows 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,880 @@
+import { AppContext } from '@voltro/runtime';
+import { ColumnBuilder } from '@voltro/database';
+import { ColumnDefinition } from '@voltro/database';
+import { Effect } from 'effect';
+import { FieldDefinitions } from '@voltro/database';
+import { ProviderConfig } from '@voltro/ai';
+import { Schema } from 'effect';
+import { Table } from '@voltro/database';
+import { TableLike } from '@voltro/database';
+import { VoltroPlugin } from '@voltro/protocol';
+import { WorkflowEngine } from '@effect/workflow/WorkflowEngine';
+import { WorkflowInstance } from '@effect/workflow/WorkflowEngine';
+
+/** An `agent` step's resolved persona. */
+export declare interface AgentResolution {
+    readonly system: string;
+    readonly model: string;
+}
+
+/** `ai_flow_runs` — one execution. `.reactive()`: the engine patches this row
+ *  as it progresses and the client's subscription streams the live timeline. */
+export declare const aiFlowRunsTable: Table<"ai_flow_runs", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id">;
+    /** Name (code flow) or id (data flow). Not an FK — no single target. */
+    readonly flowRef: ColumnBuilder<string, "text">;
+    /** Denormalized flow name — survives a definition delete. */
+    readonly flowName: ColumnBuilder<string | null, "text">;
+    /** Snapshot of the mode this run executes in. */
+    readonly mode: ColumnBuilder<string, "text">;
+    /** pending | running | waiting | succeeded | failed | cancelled. */
+    readonly status: ColumnBuilder<string, "text">;
+    /** manual | cron. */
+    readonly source: ColumnBuilder<string | null, "text">;
+    /** Correlation + idempotency key (→ the workflow's idempotencyKey). */
+    readonly requestId: ColumnBuilder<string, "text">;
+    /** Brief values, keyed by `BriefField.key`. */
+    readonly input: ColumnBuilder<Record<string, unknown> | null, "json">;
+    /** The result bundle: `outputKey → value` (what the UI's result dialog reads). */
+    readonly output: ColumnBuilder<Record<string, unknown> | null, "json">;
+    /** Live per-step timeline (`RunStep[]`); the engine writes it on every step. */
+    readonly steps: ColumnBuilder<readonly {
+        readonly id: number;
+        readonly output?: {
+            readonly text: string;
+        } | undefined;
+        readonly type: "generate" | "agent" | "structured" | "note" | "human";
+        readonly status: "failed" | "running" | "succeeded" | "pending" | "waiting";
+        readonly url?: string | undefined;
+        readonly description?: string | undefined;
+        readonly errorMessage?: string | undefined;
+        readonly startedAt?: string | undefined;
+        readonly completedAt?: string | undefined;
+        readonly title: string;
+        readonly costMicroUsd?: number | undefined;
+        readonly requestId?: string | undefined;
+        readonly review?: {
+            readonly prompt: string;
+            readonly options?: readonly {
+                readonly value: string;
+                readonly label: string;
+            }[] | undefined;
+            readonly mode: "text" | "approve" | "choice";
+        } | undefined;
+    }[] | null, "json">;
+    readonly currentStep: ColumnBuilder<number, "integer">;
+    readonly totalSteps: ColumnBuilder<number, "integer">;
+    /** The HITL answer, written by `respond`. */
+    readonly humanResponse: ColumnBuilder<{
+        readonly value?: string | undefined;
+        readonly text?: string | undefined;
+        readonly decision?: "approve" | "reject" | undefined;
+        readonly respondedAt?: string | undefined;
+    } | null, "json">;
+    /** Staged follow-up when the chain requires confirmation. */
+    readonly chainPending: ColumnBuilder<{
+        readonly input: {
+            readonly [x: string]: unknown;
+        };
+        readonly status: "pending" | "confirmed" | "dismissed";
+        readonly flowRef: string;
+    } | null, "json">;
+    /** Accumulated cost in micro-USD (app view projects to €/cents). */
+    readonly costMicroUsd: ColumnBuilder<number, "integer">;
+    readonly durationMs: ColumnBuilder<number | null, "integer">;
+    readonly error: ColumnBuilder<string | null, "text">;
+    readonly errorMessage: ColumnBuilder<string | null, "text">;
+    readonly startedAt: ColumnBuilder<Date | null, "timestamp">;
+    readonly completedAt: ColumnBuilder<Date | null, "timestamp">;
+    readonly cancelledAt: ColumnBuilder<Date | null, "timestamp">;
+    /** Studio session grouping (app concept; soft ref). */
+    readonly sessionId: ColumnBuilder<string | null, "text">;
+    readonly sessionName: ColumnBuilder<string | null, "text">;
+    /** App subject the run is for/by. */
+    readonly ownerId: ColumnBuilder<string | null, "text">;
+    readonly metadata: ColumnBuilder<Record<string, unknown> | null, "json">;
+}> & {
+    tenantId: ColumnDefinition<string>;
+} & {
+    readonly createdAt: ColumnDefinition<Date, "timestamp">;
+    readonly updatedAt: ColumnDefinition<Date, "timestamp">;
+    readonly createdBy: ColumnDefinition<string | null, "reference">;
+    readonly updatedBy: ColumnDefinition<string | null, "reference">;
+}, true, never>;
+
+/**
+ * The AI-Flows plugin. Install it in `app.config.ts` `plugins: [...]`. It
+ * contributes the canonical `ai_flows` + `ai_flow_runs` tables plus the
+ * read-only inspect surface; the durable engine, the client-callable
+ * procedures, and the cadence tick ship from this package's subpath exports.
+ */
+export declare const aiFlowsPlugin: (options?: AiFlowsPluginOptions) => VoltroPlugin;
+
+/** Options for the AI-Flows plugin. Runtime capabilities (AI generation,
+ *  storage for media artifacts, notifications) are resolved as injected
+ *  capabilities as the engine lands — NOT hard plugin-to-plugin deps — so an
+ *  app can run text-only flows without installing storage. */
+export declare interface AiFlowsPluginOptions {
+    /** Namespace for this plugin's routes / inspect endpoints. Default `aiFlows`. */
+    readonly alias?: string;
+}
+
+/** `ai_flows` — a reusable flow DEFINITION (the data front door persists these;
+ *  code-first `defineFlow` flows are NOT rows — they register in-process). */
+export declare const aiFlowsTable: Table<"ai_flows", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id">;
+    readonly name: ColumnBuilder<string, "text">;
+    readonly description: ColumnBuilder<string | null, "text">;
+    /** 'deterministic' | 'agentic' — the execution mode (replaces allowDeviation). */
+    readonly mode: ColumnBuilder<string, "text">;
+    /** 'draft' | 'active' | 'archived'. */
+    readonly status: ColumnBuilder<string, "text">;
+    /** 'private' | 'organization' | 'shared'. */
+    readonly visibility: ColumnBuilder<string, "text">;
+    readonly orchestratorModel: ColumnBuilder<string | null, "text">;
+    readonly orchestratorInstructions: ColumnBuilder<string | null, "text">;
+    /** Agentic loop bound; clamped [1,100] at run (default 30). */
+    readonly maxSteps: ColumnBuilder<number, "integer">;
+    /** The ordered plan (`FlowStep[]`); null ≡ empty. */
+    readonly steps: ColumnBuilder<readonly {
+        readonly id: string;
+        readonly type: "generate" | "agent" | "structured" | "note" | "human";
+        readonly description?: string | undefined;
+        readonly outputKey?: string | undefined;
+        readonly schema?: {
+            readonly [x: string]: unknown;
+        } | undefined;
+        readonly title?: string | undefined;
+        readonly prompt?: string | undefined;
+        readonly modality?: "text" | "image" | "video" | "audio" | undefined;
+        readonly model?: string | undefined;
+        readonly params?: {
+            readonly [x: string]: unknown;
+        } | undefined;
+        readonly mediaInputs?: {
+            readonly [x: string]: {
+                readonly from: "upload";
+                readonly url: string;
+            } | {
+                readonly from: "step";
+                readonly ref: string;
+            };
+        } | undefined;
+        readonly agentRef?: string | undefined;
+        readonly reviewMode?: "text" | "approve" | "choice" | undefined;
+        readonly options?: readonly {
+            readonly value: string;
+            readonly label: string;
+        }[] | undefined;
+    }[] | null, "json">;
+    /** The launch-form brief (`BriefField[]`). */
+    readonly inputSchema: ColumnBuilder<readonly {
+        readonly key: string;
+        readonly type: "number" | "boolean" | "text" | "textarea";
+        readonly required?: boolean | undefined;
+        readonly label: string;
+        readonly placeholder?: string | undefined;
+    }[] | null, "json">;
+    readonly chainTo: ColumnBuilder<{
+        readonly flowRef: string;
+        readonly mappings: readonly {
+            readonly sourceKey: string;
+            readonly targetKey: string;
+        }[];
+        readonly requireConfirmation?: boolean | undefined;
+    } | null, "json">;
+    readonly cadence: ColumnBuilder<{
+        readonly frequency?: "weekly" | "monthly" | undefined;
+        readonly repeats: readonly 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?: {
+            readonly [x: string]: unknown;
+        } | undefined;
+    } | null, "json">;
+    /** Master on/off — gates scheduling. */
+    readonly isEnabled: ColumnBuilder<boolean, "boolean">;
+    readonly metadata: ColumnBuilder<Record<string, unknown> | null, "json">;
+    readonly icon: ColumnBuilder<string | null, "text">;
+    readonly color: ColumnBuilder<string | null, "text">;
+    /** Flow avatar as a plain URL (avoids a hard storage-plugin schema dep). */
+    readonly avatarUrl: ColumnBuilder<string | null, "text">;
+    /** Run counter (incremented on launch). */
+    readonly usageCount: ColumnBuilder<number, "integer">;
+    /** App subject the flow belongs to (distinct from audit `createdBy` → actors). */
+    readonly ownerId: ColumnBuilder<string | null, "text">;
+}> & {
+    tenantId: ColumnDefinition<string>;
+} & {
+    readonly createdAt: ColumnDefinition<Date, "timestamp">;
+    readonly updatedAt: ColumnDefinition<Date, "timestamp">;
+    readonly createdBy: ColumnDefinition<string | null, "reference">;
+    readonly updatedBy: ColumnDefinition<string | null, "reference">;
+} & {
+    readonly deletedAt: ColumnDefinition<Date | null, "timestamp">;
+    readonly deletedBy: ColumnDefinition<string | null, "reference">;
+}, true, never>;
+
+/** Every table this plugin contributes (fed to `extendSchema`). */
+export declare const aiFlowsTables: ReadonlyArray<TableLike>;
+
+/** 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;
+
+/**
+ * Build the `flow.run` executor over a live `AppContext` + injected capabilities.
+ * The consumer's `flow.run.workflow.server.tsx` does:
+ * `export default (ctx) => buildFlowRunExecute(ctx, myDeps)`.
+ */
+export declare const buildFlowRunExecute: (ctx: AppContext, deps?: EngineDeps) => (payload: FlowRunPayload, _executionId: string) => Effect.Effect<{
+    runId: string;
+    status: "cancelled";
+    output?: never;
+} | {
+    runId: string;
+    status: "failed";
+    output?: never;
+} | {
+    runId: string;
+    status: "succeeded";
+    output: Record<string, unknown>;
+}, never, WorkflowEngine | WorkflowInstance>;
+
+/**
+ * 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;
+
+/** Cooperatively cancel a run: flip the row → the engine aborts before its next
+ *  step (it can't interrupt an in-flight generation). */
+export declare const cancelFlow: (ctx: AppContext, args: {
+    runId: string;
+}) => Effect.Effect<{
+    runId: string;
+    status: RunStatus;
+}, FlowRunNotFound, never>;
+
+/** 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;
+
+/** Clear the registry — test hygiene only. */
+export declare const clearRegistry: () => void;
+
+/** Every `{{ref}}` name referenced in `text` (order-preserving, may repeat). */
+export declare const collectRefs: (text: string) => ReadonlyArray<string>;
+
+/** 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>;
+
+/** Deterministic per-slot request id: same flow + same 15-min slot ⇒ same id. */
+export declare const cronRequestId: (flowRef: string, now: Date) => string;
+
+/**
+ * Declare a code-first flow. Normalizes to the Flow IR, validates its `{{ref}}`
+ * graph, registers it (so `launch({ flowRef: name })` runs it), and returns the
+ * IR. Call at module load, e.g. in an app `flows/*.flow.ts` file.
+ */
+export declare const defineFlow: (input: DefineFlowInput) => FlowIR;
+
+export declare interface DefineFlowInput {
+    readonly name: string;
+    readonly mode?: FlowMode;
+    readonly maxSteps?: number;
+    readonly steps: ReadonlyArray<FlowStepDraft | FlowStep>;
+    readonly brief?: ReadonlyArray<BriefField>;
+    readonly orchestrator?: {
+        readonly model?: string;
+        readonly instructions?: string;
+    };
+    readonly chain?: FlowChain;
+    readonly cadence?: FlowCadence;
+}
+
+/** Hard-delete a flow row by id. Returns whether a row was removed. */
+export declare const deleteFlow: (ctx: AppContext, args: {
+    id: string;
+}) => Effect.Effect<boolean, never, never>;
+
+export declare interface EngineDeps {
+    /** Resolve an `agent` step's `agentRef` → system prompt + model. Absent →
+     *  agent steps with an `agentRef` fail with FlowCapabilityMissing. */
+    readonly resolveAgent?: (agentRef: string) => Effect.Effect<AgentResolution, FlowNotFound>;
+    /** Media generator for image/video/audio steps (task #31 plugs in here). */
+    readonly generateMedia?: MediaGenerator;
+    /** Fallback model per modality when a step omits `model`. */
+    readonly defaultModels?: {
+        readonly text?: string;
+        readonly image?: string;
+        readonly video?: string;
+        readonly audio?: string;
+    };
+    /** Resolve a model string → a provider config. Absent → every call routes to
+     *  the AI Gateway (`{ name:'gateway', model }`). Supply this to honour a
+     *  `provider/model` prefix or pin a default provider (e.g. wrap the framework's
+     *  `providerFromEnv`), so an app WITHOUT a valid gateway key can run the engine. */
+    readonly resolveModel?: (model: string) => ProviderConfig;
+    /** Lifecycle hook — wire to @voltro/plugin-notifications. Best-effort; a
+     *  throwing/absent notifier never affects the run. */
+    readonly onEvent?: (event: FlowLifecycleEvent) => Effect.Effect<void>;
+    /** Long-term-memory prefix prepended to the orchestrator system prompt (wire
+     *  to the app's ai_user_memories). Best-effort. */
+    readonly memoryPrefix?: (ownerId: string | null) => Effect.Effect<string>;
+}
+
+/** The canonical name the launch action starts + the app re-export registers. */
+export declare const FLOW_RUN_WORKFLOW = "flow.run";
+
+/** A required brief field was blank at launch. */
+declare class FlowBriefIncomplete extends FlowBriefIncomplete_base {
+}
+
+declare const FlowBriefIncomplete_base: Schema.TaggedErrorClass<FlowBriefIncomplete, "FlowBriefIncomplete", {
+    readonly _tag: Schema.tag<"FlowBriefIncomplete">;
+} & {
+    missing: Schema.Array$<typeof Schema.String>;
+    message: typeof Schema.String;
+}>;
+
+/** 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;
+
+/** A generation step required a capability the host did not provide (e.g. a
+ *  media modality with no configured generator, or storage for the artifact). */
+declare class FlowCapabilityMissing extends FlowCapabilityMissing_base {
+}
+
+declare const FlowCapabilityMissing_base: Schema.TaggedErrorClass<FlowCapabilityMissing, "FlowCapabilityMissing", {
+    readonly _tag: Schema.tag<"FlowCapabilityMissing">;
+} & {
+    capability: typeof Schema.String;
+    message: typeof Schema.String;
+}>;
+
+/** 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;
+}
+
+/** A lifecycle event the host can turn into a notification (best-effort). */
+export declare interface FlowLifecycleEvent {
+    readonly kind: 'succeeded' | 'failed' | 'review-needed';
+    readonly runId: string;
+    readonly flowName: string;
+    readonly ownerId: string | null;
+    readonly source: 'manual' | 'cron';
+}
+
+/** 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;
+
+/** A run cannot accept a human response in its current state (not `waiting`,
+ *  already answered, or cancelled). */
+declare class FlowNotAwaitingResponse extends FlowNotAwaitingResponse_base {
+}
+
+declare const FlowNotAwaitingResponse_base: Schema.TaggedErrorClass<FlowNotAwaitingResponse, "FlowNotAwaitingResponse", {
+    readonly _tag: Schema.tag<"FlowNotAwaitingResponse">;
+} & {
+    runId: typeof Schema.String;
+    status: typeof Schema.String;
+    message: typeof Schema.String;
+}>;
+
+/** A flow (definition) could not be resolved by ref (code name or row id). */
+declare class FlowNotFound extends FlowNotFound_base {
+}
+
+declare const FlowNotFound_base: Schema.TaggedErrorClass<FlowNotFound, "FlowNotFound", {
+    readonly _tag: Schema.tag<"FlowNotFound">;
+} & {
+    flowRef: typeof Schema.String;
+    message: typeof Schema.String;
+}>;
+
+/** A flow run row could not be found. */
+declare class FlowRunNotFound extends FlowRunNotFound_base {
+}
+
+declare const FlowRunNotFound_base: Schema.TaggedErrorClass<FlowRunNotFound, "FlowRunNotFound", {
+    readonly _tag: Schema.tag<"FlowRunNotFound">;
+} & {
+    runId: typeof Schema.String;
+    message: typeof Schema.String;
+}>;
+
+/** 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-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;
+
+/** Typed builders for each step kind — terser + safer than hand-writing the
+ *  union. Every builder returns a draft; `defineFlow` assigns the id. */
+export declare const flowStep: {
+    /** A text generation. */
+    text: (o: {
+        title?: string;
+        description?: string;
+        prompt: string;
+        model?: string;
+        outputKey?: string;
+    }) => FlowStepDraft;
+    /** An image/video/audio generation. */
+    media: (modality: Modality, o: {
+        title?: string;
+        description?: string;
+        prompt: string;
+        model?: string;
+        params?: Record<string, unknown>;
+        outputKey?: string;
+    }) => FlowStepDraft;
+    /** Delegate to an allowed sub-agent (text-only). */
+    agent: (o: {
+        title?: string;
+        description?: string;
+        agentRef: string;
+        prompt: string;
+        model?: string;
+        outputKey?: string;
+    }) => FlowStepDraft;
+    /** Return a JSON object validated against a JSON Schema. */
+    structured: (o: {
+        title?: string;
+        description?: string;
+        prompt: string;
+        schema: Record<string, unknown>;
+        model?: string;
+        outputKey?: string;
+    }) => FlowStepDraft;
+    /** Free-text guidance — the interpolated prompt itself is the output. */
+    note: (o: {
+        title?: string;
+        description?: string;
+        prompt: string;
+        outputKey?: string;
+    }) => FlowStepDraft;
+    /** Pause for human review. */
+    human: (o: {
+        title?: string;
+        description?: string;
+        reviewMode: ReviewMode;
+        options?: ReadonlyArray<ReviewOption>;
+        prompt?: string;
+        outputKey?: string;
+    }) => FlowStepDraft;
+};
+
+/** A step without its `id` — `defineFlow` assigns stable index-based ids. */
+export declare type FlowStepDraft = Omit<FlowStep, 'id'>;
+
+/** One stored flow by id, or undefined (tenant-scoped by the runtime). */
+export declare const getFlow: (ctx: AppContext, args: {
+    id: string;
+}) => Effect.Effect<Record<string, unknown> | undefined, never, never>;
+
+/** Resolve a code-registered flow by name, or `undefined` for a data flow. */
+export declare const getRegisteredFlow: (name: string) => FlowIR | undefined;
+
+/** The signal a `human` step parks on; `respondToFlow` sends it to resume. */
+export declare const HUMAN_RESPONSE_SIGNAL = "flow-human-response";
+
+/** 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;
+
+/** Replace `{{key}}` with `context[key]` (objects/arrays JSON-stringified; an
+ *  absent/null value renders empty). */
+export declare const interpolate: (text: string, context: Record<string, unknown>) => string;
+
+/** 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;
+
+/** Launch a fresh run of a flow (by code name or row id). Validates the brief,
+ *  creates the run row, and starts the durable `flow.run` workflow. */
+export declare const launchFlow: (ctx: AppContext, args: {
+    flowRef: string;
+    input?: Record<string, unknown>;
+    source?: "manual" | "cron";
+}) => Effect.Effect<{
+    runId: string;
+    requestId: string;
+    status: RunStatus;
+}, FlowNotFound | FlowBriefIncomplete, never>;
+
+/** All stored flows for the caller's tenant. */
+export declare const listFlows: (ctx: AppContext) => Effect.Effect<ReadonlyArray<Record<string, unknown>>>;
+
+/** Every code-registered flow (for the inspect surface / cadence enumeration). */
+export declare const listRegisteredFlows: () => ReadonlyArray<FlowIR>;
+
+/**
+ * Build a `MediaGenerator` from a persistence adapter. Generates via @voltro/ai,
+ * persists the artifact, and returns `{ url, costMicroUsd, requestId? }`. Any
+ * failure (generation or persistence) surfaces as a typed `FlowCapabilityMissing`
+ * so the engine records a clean per-step error.
+ */
+export declare const makeMediaGenerator: (persist: MediaPersist, opts?: {
+    readonly resolveModel?: (model: string) => ProviderConfig;
+}) => MediaGenerator;
+
+/** 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;
+
+/** Host-supplied media generator for image/video/audio steps — `@voltro/ai`'s
+ *  first-class media gen (task #31) plugs in here via the app's server re-export. */
+export declare type MediaGenerator = (args: {
+    readonly modality: 'image' | 'video' | 'audio';
+    readonly model?: string;
+    readonly prompt: string;
+    readonly params?: Record<string, unknown>;
+    readonly inputs?: Record<string, unknown>;
+}) => Effect.Effect<MediaResult, FlowCapabilityMissing>;
+
+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;
+
+/** Host-supplied persistence (from @voltro/plugin-storage's StorageService). */
+export declare interface MediaPersist {
+    /** Store raw bytes / base64 → a hosted URL (StorageService.put). */
+    readonly put: (args: {
+        data: Uint8Array | string;
+        mediaType: string;
+    }) => Promise<StoredMedia>;
+    /** Re-host a provider URL (StorageService.ingestUrl). If absent, a provider
+     *  video URL is used as-is (no re-hosting). */
+    readonly ingestUrl?: (url: string) => Promise<StoredMedia>;
+}
+
+/** Media generation result (the host generator persists the artifact + returns
+ *  a hosted URL). */
+export declare interface MediaResult {
+    readonly url: string;
+    readonly costMicroUsd?: number;
+    readonly requestId?: string;
+}
+
+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>;
+
+/**
+ * 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;
+
+/** Register (or replace) a code-defined flow by its IR name. Called by
+ *  `defineFlow` when the module is loaded. */
+export declare const registerFlow: (ir: FlowIR) => void;
+
+/** 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>;
+
+/** Record a human's answer to a `waiting` run + signal the parked workflow to
+ *  resume. (The park itself lands with the slot-freeing await, task #32/#35.) */
+export declare const respondToFlow: (ctx: AppContext, args: {
+    runId: string;
+    response: HumanResponse;
+}) => Effect.Effect<{
+    runId: string;
+}, FlowRunNotFound | FlowNotAwaitingResponse, never>;
+
+/** Re-run a run from its first unfinished step. Reuses the SAME requestId so the
+ *  workflow's idempotencyKey resolves to the same execution → journal replay
+ *  resumes (deterministic runs skip already-succeeded steps). */
+export declare const retryFlow: (ctx: AppContext, args: {
+    runId: string;
+}) => Effect.Effect<{
+    runId: string;
+    requestId: string;
+    status: RunStatus;
+}, FlowRunNotFound, never>;
+
+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;
+
+/**
+ * Evaluate every enabled flow's cadence against `now` and start a `flow.run` per
+ * match. Returns the started request ids. Idempotent across replicas +
+ * re-invocations within a slot (deterministic requestId + the run-row insert
+ * tolerates the duplicate). Never throws — a single bad flow can't abort the tick.
+ */
+export declare const runCadenceTick: (ctx: AppContext, now?: Date) => Promise<{
+    readonly matched: number;
+    readonly started: ReadonlyArray<string>;
+}>;
+
+/** 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;
+
+/** A persisted artifact — a hosted URL + optional storage ref id. */
+export declare interface StoredMedia {
+    readonly url: string;
+    readonly refId?: string;
+}
+
+/** The `{{ref}}`s in `text` whose producing key is absent/null in `context` —
+ *  the agentic/deterministic dependency guard: a non-empty result means a step
+ *  depends on an output that never materialized (its producer failed/skipped). */
+export declare const unresolvedRefs: (text: string, context: Record<string, unknown>) => ReadonlyArray<string>;
+
+/** Patch a flow row by id. Returns the post-image (or null when absent). */
+export declare const updateFlow: (ctx: AppContext, args: {
+    id: string;
+    patch: Record<string, unknown>;
+}) => Effect.Effect<Readonly<Record<string, unknown>> | null, never, never>;
+
+/**
+ * Validate that every `{{ref}}` a step's prompt uses resolves to a brief field
+ * or an EARLIER step's `outputKey` (order matters). Throws FlowValidationError
+ * with all issues so a bad code flow fails at registration, not mid-run.
+ */
+export declare const validateFlow: (ir: FlowIR) => void;
+
+/** 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 { }