@voltro/plugin-ai-flows 0.33.0 → 0.34.0

package/dist/index.d.ts

@@ -42,20 +42,9 @@ export declare const aiFlowRunsTable: Table<"_voltro_ai_flow_runs", FieldDefinit
     readonly currentStep: ColumnBuilder<number, "integer", true>;
     readonly totalSteps: ColumnBuilder<number, "integer", true>;
     /** 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", boolean>;
+    readonly humanResponse: ColumnBuilder<HumanResponse | null, "json", boolean>;
     /** Staged follow-up when the chain requires confirmation. */
-    readonly chainPending: ColumnBuilder<{
-        readonly status: "pending" | "confirmed" | "dismissed";
-        readonly input: {
-            readonly [x: string]: unknown;
-        };
-        readonly flowRef: string;
-    } | null, "json", boolean>;
+    readonly chainPending: ColumnBuilder<ChainPending | null, "json", boolean>;
     /** Accumulated cost in micro-USD (app view projects to €/cents). */
     readonly costMicroUsd: ColumnBuilder<number, "integer", true>;
     readonly durationMs: ColumnBuilder<number | null, "integer", boolean>;
@@ -79,6 +68,12 @@ export declare const aiFlowRunsTable: Table<"_voltro_ai_flow_runs", FieldDefinit
     readonly updatedBy: ColumnDefinition<string | null, "reference", boolean>;
 }, true, never>;
 
+/** Tunables an `aiFlowsPlugin({...})` call can set from `app.config.ts`. */
+export declare interface AiFlowsDefaults {
+    /** Park bound for a `human` step, in ms. `0` = wait forever. */
+    readonly humanReviewTimeoutMs?: number;
+}
+
 /**
  * The AI-Flows plugin. Install it in `app.config.ts` `plugins: [...]`. It
  * contributes the canonical `ai_flows` + `ai_flow_runs` tables plus the
@@ -94,6 +89,59 @@ export declare const aiFlowsPlugin: (options?: AiFlowsPluginOptions) => VoltroPl
 export declare interface AiFlowsPluginOptions {
     /** Namespace for this plugin's routes / inspect endpoints. Default `aiFlows`. */
     readonly alias?: string;
+    /**
+     * Contribute this plugin's tables via `extendSchema.tables`. Default `true`.
+     *
+     * Set `false` when your app ALREADY declares equivalent tables and you want to
+     * keep them — the seam this exists for. The plugin then contributes no DDL and
+     * the declarative differ never proposes its tables; everything else (routes,
+     * inspect, interceptors) is unchanged.
+     *
+     * **What you take over, exactly:** `_voltro_ai_flows` (definitions) and
+     * `_voltro_ai_flow_runs` (runs). The retention sweep registered below still
+     * targets `_voltro_ai_flow_runs` by name, so your table inherits the same TTL
+     * — which is the intent, but say so to whoever owns that table.
+     *
+     * It is not offered on every plugin, and the omissions are deliberate rather
+     * than unfinished: a `tables: false` that quietly disables a table carrying an
+     * AUTHORIZATION or SAFETY decision — the SAML replay cache, SCIM provisioning
+     * state, billing's usage counters, cdc-out's outbox — is a security regression
+     * shipped as an ergonomics feature. Those plugins need a named store seam
+     * first, not a boolean.
+     */
+    readonly tables?: boolean;
+    /**
+     * How long a `human` step parks awaiting its review before the run fails, in
+     * ms. Default 7 days (`VOLTRO_AI_FLOW_HUMAN_REVIEW_TIMEOUT_HOURS` overrides at
+     * deploy time); `0` = wait forever. A flow's `humanTimeoutMs` and a step's own
+     * `timeoutMs` both outrank this.
+     */
+    readonly humanReviewTimeoutMs?: number;
+    /**
+     * How long a FINISHED flow run is kept, in ms. Default 90 days
+     * (`VOLTRO_AI_FLOW_RUNS_TTL_HOURS`).
+     *
+     * `_voltro_ai_flow_runs` stores every step's full output plus review payloads
+     * and grows with traffic, so it is registered with the framework retention
+     * sweep like every other run-family table. Two properties of that policy are
+     * deliberate:
+     *
+     * - **Only TERMINAL runs are swept.** The predicate is status-aware
+     *   (`succeeded | failed | cancelled`), so a run parked on a human review
+     *   survives regardless of age — a plain time-TTL would delete the pending
+     *   approvals this plugin exists to support.
+     * - **Media artifacts are NOT swept with the row.** A run's steps carry hosted
+     *   URLs whose blobs belong to the storage plugin; deleting the row orphans
+     *   them. Keep this TTL at or above the app's own media-purge window, or purge
+     *   by run id before the row ages out.
+     */
+    readonly runsTtlMs?: number;
+    /**
+     * Ceiling on rows ONE inspect call may return (`/flows`, `/runs`). Default
+     * 200. A run row carries every step's full output, so the page size is a real
+     * response-size knob, not a formality.
+     */
+    readonly inspectPageMax?: number;
 }
 
 /** `ai_flows` — a reusable flow DEFINITION (the data front door persists these;
@@ -115,33 +163,12 @@ export declare const aiFlowsTable: Table<"_voltro_ai_flows", FieldDefinitions<{
     /** The ordered plan (`FlowStep[]`); null ≡ empty. */
     readonly steps: ColumnBuilder<readonly FlowStep[] | null, "json", boolean>;
     /** 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", boolean>;
-    readonly chainTo: ColumnBuilder<{
-        readonly flowRef: string;
-        readonly mappings: readonly {
-            readonly sourceKey: string;
-            readonly targetKey: string;
-        }[];
-        readonly requireConfirmation?: boolean | undefined;
-    } | null, "json", boolean>;
-    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", boolean>;
+    readonly inputSchema: ColumnBuilder<readonly BriefField[] | null, "json", boolean>;
+    readonly chainTo: ColumnBuilder<FlowChain | null, "json", boolean>;
+    readonly cadence: ColumnBuilder<FlowCadence | null, "json", boolean>;
+    /** Flow-wide park bound for `human` steps, in ms (a step's own `timeoutMs`
+     *  wins). Null → the plugin default. `0` = wait forever. */
+    readonly humanTimeoutMs: ColumnBuilder<number | null, "integer", boolean>;
     /** Master on/off — gates scheduling. */
     readonly isEnabled: ColumnBuilder<boolean, "boolean", true>;
     readonly metadata: ColumnBuilder<Record<string, unknown> | null, "json", boolean>;
@@ -177,7 +204,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;
+}
 
 /**
  * Build the `flow.run` executor over a live `AppContext` + injected capabilities.
@@ -221,7 +258,12 @@ 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;
 
@@ -257,6 +299,9 @@ export declare interface DefineFlowInput {
     };
     readonly chain?: FlowChain;
     readonly cadence?: FlowCadence;
+    /** Flow-wide park bound for every `human` step that sets no `timeoutMs` of its
+     *  own, in ms. `0` = wait forever. */
+    readonly humanTimeoutMs?: number;
 }
 
 /** Hard-delete a flow row by id. Returns whether a row was removed. */
@@ -268,7 +313,8 @@ 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, unknown>;
-    /** Media generator for image/video/audio steps (task #31 plugs in here). */
+    /** Media generator for image/video/audio steps (`makeMediaGenerator` in
+     *  `mediaAdapter.ts` is the @voltro/ai-backed implementation). */
     readonly generateMedia?: MediaGenerator;
     /** Fallback model per modality when a step omits `model`. */
     readonly defaultModels?: {
@@ -288,11 +334,23 @@ export declare interface EngineDeps {
     /** 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, never, unknown>;
+    /** Default park bound for `human` steps in ms, for flows that set none. Sits
+     *  between the flow's own `humanTimeoutMs` and the `aiFlowsPlugin({...})`
+     *  option / `VOLTRO_AI_FLOW_HUMAN_REVIEW_TIMEOUT_HOURS` (see `defaults.ts`).
+     *  `0` = wait forever. */
+    readonly humanReviewTimeoutMs?: number;
 }
 
 /** The canonical name the launch action starts + the app re-export registers. */
 export declare const FLOW_RUN_WORKFLOW = "flow.run";
 
+/** Deploy-time override for {@link FLOW_RUNS_TTL_HOURS_DEFAULT}, in hours. */
+export declare const FLOW_RUNS_TTL_ENV = "VOLTRO_AI_FLOW_RUNS_TTL_HOURS";
+
+/** Framework default retention for `_voltro_ai_flow_runs`: 90 days of finished
+ *  runs. Only TERMINAL runs are swept — see `index.ts`. */
+export declare const FLOW_RUNS_TTL_HOURS_DEFAULT: number;
+
 /** A required brief field was blank at launch. */
 declare class FlowBriefIncomplete extends FlowBriefIncomplete_base {
 }
@@ -322,7 +380,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;
+}
 
 /** 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). */
@@ -347,7 +423,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). */
@@ -361,6 +445,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. */
@@ -376,6 +461,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;
 }
 
 /** A lifecycle event the host can turn into a notification (best-effort). */
@@ -479,6 +568,11 @@ export declare const FlowStep: Schema.Struct<{
         value: typeof Schema.String;
         label: 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>;
 }>;
 
 /**
@@ -519,6 +613,7 @@ export declare interface FlowStep {
     readonly schema?: Json | undefined;
     readonly reviewMode?: ReviewMode | undefined;
     readonly options?: ReadonlyArray<ReviewOption> | undefined;
+    readonly timeoutMs?: number | undefined;
 }
 
 /** Typed builders for each step kind — terser + safer than hand-writing the
@@ -566,7 +661,8 @@ export declare const flowStep: {
         prompt: string;
         outputKey?: string;
     }) => FlowStepDraft;
-    /** Pause for human review. */
+    /** Pause for human review. `timeoutMs` bounds the park (default: the flow's
+     *  `humanTimeoutMs`, then the plugin default — 7 days; `0` = wait forever). */
     human: (o: {
         title?: string;
         description?: string;
@@ -574,12 +670,16 @@ export declare const flowStep: {
         options?: ReadonlyArray<ReviewOption>;
         prompt?: string;
         outputKey?: string;
+        timeoutMs?: number;
     }) => FlowStepDraft;
 };
 
 /** A step without its `id` — `defineFlow` assigns stable index-based ids. */
 export declare type FlowStepDraft = Omit<FlowStep, 'id'>;
 
+/** The recorded `app.config.ts` tunables. */
+export declare const getAiFlowsDefaults: () => AiFlowsDefaults;
+
 /** One stored flow by id, or undefined (tenant-scoped by the runtime). */
 export declare const getFlow: (ctx: AppContext, args: {
     id: string;
@@ -588,8 +688,18 @@ export declare const getFlow: (ctx: AppContext, args: {
 /** 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";
+/** Namespace of the signal a `human` step parks on. Never used on its own —
+ *  the signal a step actually awaits is {@link humanResponseSignalName}. */
+export declare const HUMAN_RESPONSE_SIGNAL_PREFIX = "flow-human-response";
+
+/** Deploy-time override for {@link HUMAN_REVIEW_TIMEOUT_HOURS_DEFAULT}, in
+ *  hours. `0` (or a negative value) means WAIT FOREVER. */
+export declare const HUMAN_REVIEW_TIMEOUT_ENV = "VOLTRO_AI_FLOW_HUMAN_REVIEW_TIMEOUT_HOURS";
+
+/** Framework default park bound for a human review: 7 days. Long enough to
+ *  survive a weekend + a holiday Monday, short enough that an abandoned review
+ *  eventually settles instead of pinning a run forever. */
+export declare const HUMAN_REVIEW_TIMEOUT_HOURS_DEFAULT: number;
 
 /** The HITL answer, written by `respond`. */
 export declare const HumanResponse: Schema.Struct<{
@@ -599,7 +709,38 @@ 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;
+}
+
+/**
+ * The signal name ONE human step parks on, derived from that step's position in
+ * the (journal-pinned) plan.
+ *
+ * **Why this is per-step and not one constant.** `awaitSignalSuspending` derives
+ * its `DurableDeferred` from workflow-name + signal-name per execution, so a
+ * single `'flow-human-response'` for every human step in a flow meant the SECOND
+ * review awaited the deferred the FIRST answer had already completed — it
+ * resolved instantly, with the first reviewer's payload, and the run finished
+ * carrying an approval nobody gave. Measured before the fix: a two-review flow,
+ * one answer, `status: 'succeeded'`, `output: { first: 'answer-one', second:
+ * 'answer-one' }`. The same collision aliased the wait's durable timeout clock
+ * (`await-signal-timeout/<name>`), so the second park inherited the first's
+ * expiry too.
+ *
+ * **Why the INDEX is the identity.** It must be identical on every replay and
+ * derivable by the responder without re-resolving the flow definition (which may
+ * have been edited mid-run). The step list is pinned in the run's journal at
+ * step 0, so a step's index is fixed for the life of the run; the responder
+ * reads it back off the run row's live timeline. A counter, a clock, or a
+ * `randomUUID` would all break replay; the authored step `id` would break the
+ * moment a definition is re-ordered under a live run.
+ */
+export declare const humanResponseSignalName: (stepIndex: number) => string;
 
 /** Replace `{{key}}` with `context[key]` (objects/arrays JSON-stringified; an
  *  absent/null value renders empty). */
@@ -610,6 +751,25 @@ export declare const Json: Schema.Record$<typeof Schema.String, typeof Schema.Un
 
 export declare type Json = typeof Json.Type;
 
+/** A JSON-Schema node as stored on a `structured` step. */
+export declare type JsonSchemaNode = Record<string, unknown>;
+
+/**
+ * Adapt a `structured` step's JSON Schema to the Effect `Schema` the engine
+ * hands `generateObject`. An absent / unusable schema falls back to the open
+ * record, so a step authored without one behaves exactly as before.
+ *
+ * ```ts
+ * jsonSchemaToEffectSchema({
+ *   type: 'object',
+ *   properties: { title: { type: 'string' }, tags: { type: 'array', items: { type: 'string' } } },
+ *   required: ['title'],
+ * })
+ * // ≡ Schema.Struct({ title: Schema.String, tags: Schema.optional(Schema.Array(Schema.String)) })
+ * ```
+ */
+export declare const jsonSchemaToEffectSchema: (jsonSchema: JsonSchemaNode | undefined) => Schema.Schema<unknown, unknown>;
+
 /** 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: {
@@ -745,16 +905,38 @@ export declare const normalizeFlow: (def: FlowDefinitionInput) => FlowIR;
  *  `defineFlow` when the module is loaded. */
 export declare const registerFlow: (ir: FlowIR) => void;
 
+/** Test seam — forget the recorded tunables. */
+export declare const resetAiFlowsDefaults: () => void;
+
+/**
+ * Resolve a human step's park bound down the precedence ladder. Pure — the env
+ * read is passed in so a test can drive it without touching `process.env`.
+ */
+export declare const resolveHumanReviewTimeoutMs: (input: {
+    readonly step?: {
+        readonly timeoutMs?: number | undefined;
+    };
+    readonly flow?: {
+        readonly humanTimeoutMs?: number | undefined;
+    };
+    readonly deps?: {
+        readonly humanReviewTimeoutMs?: number | undefined;
+    };
+    readonly env?: NodeJS.ProcessEnv;
+}) => number;
+
 /** 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.) */
+ *  resume. The signal is addressed to THAT STEP's own durable deferred — one
+ *  shared name meant a later review resolved with an earlier answer. */
 export declare const respondToFlow: (ctx: AppContext, args: {
     runId: string;
     response: HumanResponse;
 }) => Effect.Effect<{
     runId: string;
+    stepIndex: number;
 }, FlowRunNotFound | FlowNotAwaitingResponse, never>;
 
 /** Re-run a run from its first unfinished step. Reuses the SAME requestId so the
@@ -871,6 +1053,9 @@ export declare type RunStepStatus = typeof RunStepStatus.Type;
 /** Sanitize an outputKey to the `{{ref}}`-safe charset. */
 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;
+
 /** The five step types. `generate` fans out to four modalities. */
 export declare const StepType: Schema.Literal<["agent", "generate", "structured", "note", "human"]>;
 
@@ -905,4 +1090,16 @@ export declare const Visibility: Schema.Literal<["private", "organization", "sha
 
 export declare type Visibility = typeof Visibility.Type;
 
+/**
+ * Which human step a `waiting` run is parked on — the index the engine used to
+ * derive the step's signal name.
+ *
+ * Read from the LIVE TIMELINE the engine wrote when it parked (`steps[i].status
+ * === 'waiting'`), with `currentStep` as the fallback for a row whose timeline
+ * hasn't been written yet. Deliberately NOT re-resolved from the flow definition:
+ * a definition edited mid-run would hand back a different plan than the one the
+ * run's journal pinned, and the answer would be delivered to the wrong step.
+ */
+export declare const waitingStepIndex: (row: Record<string, unknown>) => number;
+
 export { }