@voltro/plugin-ai-flows 0.32.0 → 0.34.0

package/dist/ir.d.ts

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

package/dist/ir.js

@@ -29,7 +29,8 @@ var t = e.Literal("deterministic", "agentic"), n = e.Literal("draft", "active",
 	agentRef: e.optional(e.String),
 	schema: e.optional(f),
 	reviewMode: e.optional(c),
-	options: e.optional(e.Array(l))
+	options: e.optional(e.Array(l)),
+	timeoutMs: e.optional(e.Number)
 }), m = e.Struct({
 	key: e.String,
 	label: e.String,
@@ -95,7 +96,8 @@ var t = e.Literal("deterministic", "agentic"), n = e.Literal("draft", "active",
 		brief: e.brief ?? [],
 		...n ? { orchestrator: n } : {},
 		...e.chain ? { chain: e.chain } : {},
-		...e.cadence ? { cadence: e.cadence } : {}
+		...e.cadence ? { cadence: e.cadence } : {},
+		...e.humanTimeoutMs != null && Number.isFinite(e.humanTimeoutMs) ? { humanTimeoutMs: e.humanTimeoutMs } : {}
 	};
 };
 //#endregion

package/dist/web.d.ts

@@ -9,7 +9,17 @@ export declare const BriefField: Schema.Struct<{
     placeholder: Schema.optional<typeof Schema.String>;
 }>;
 
-export declare type BriefField = typeof BriefField.Type;
+/** An INTERFACE for the same reason as {@link FlowStep} — it is reached from an
+ *  exported table (`aiFlows.inputSchema`), so an alias to a mapped type gets
+ *  expanded structurally into the api report, in an order that is not stable
+ *  across build scopes. The `Equals` pin below fails to compile on any drift. */
+export declare interface BriefField {
+    readonly key: string;
+    readonly label: string;
+    readonly type: 'text' | 'textarea' | 'number' | 'boolean';
+    readonly required?: boolean | undefined;
+    readonly placeholder?: string | undefined;
+}
 
 /**
  * Does `cadence` fire at wall-clock `now`? True only on a 15-min slot matching
@@ -18,6 +28,8 @@ export declare type BriefField = typeof BriefField.Type;
  */
 export declare const cadenceMatches: (cadence: FlowCadence, now: Date) => boolean;
 
+export declare const DEFAULT_FLOW_RPC_TAGS: FlowRpcTags;
+
 /** 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<{
@@ -36,7 +48,25 @@ export declare const FlowCadence: Schema.Struct<{
     defaultInput: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
 }>;
 
-export declare type FlowCadence = typeof FlowCadence.Type;
+/**
+ * An INTERFACE — reached from `aiFlows.cadence`; see {@link BriefField}.
+ *
+ * This one is not hypothetical: a single-package `api:report` and a
+ * full-monorepo build emitted `hour`/`minute` in DIFFERENT positions inside the
+ * structurally-expanded alias, so the api-surface gate rejected a file nobody
+ * had touched, showing the same members moving. That is the exact failure
+ * {@link FlowStep}'s comment describes.
+ */
+export declare interface FlowCadence {
+    readonly frequency?: 'weekly' | 'monthly' | undefined;
+    readonly repeats: ReadonlyArray<number>;
+    readonly intervalWeeks?: number | undefined;
+    readonly anchorDate?: string | undefined;
+    readonly weekOfMonth?: 1 | 2 | 3 | 4 | 'last' | undefined;
+    readonly hour?: number | undefined;
+    readonly minute?: 0 | 15 | 30 | 45 | undefined;
+    readonly defaultInput?: Json | undefined;
+}
 
 /** Follow-up flow spec. On success, map source → the child's brief. */
 export declare const FlowChain: Schema.Struct<{
@@ -49,7 +79,23 @@ 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;
+}
+
+/** Per-hook wiring: which api, and which tags if the app renamed them. */
+export declare interface FlowHookOptions {
+    /** Framework api name. Default `'app'`. */
+    readonly apiName?: string;
+    /** Override any subset of {@link DEFAULT_FLOW_RPC_TAGS}. */
+    readonly tags?: Partial<FlowRpcTags>;
+}
 
 /** Execution mode. Replaces the legacy `allowDeviation` boolean — a mode is not
  *  a boolean. `deterministic` runs the plan verbatim (resumable per step);
@@ -58,6 +104,54 @@ export declare const FlowMode: Schema.Literal<["deterministic", "agentic"]>;
 
 export declare type FlowMode = typeof FlowMode.Type;
 
+/** The rpc tags the hooks call. Defaults match the convention the docs wire up
+ *  (`api/flows/aiFlows.<verb>.{action,query}.server.ts`). */
+export declare interface FlowRpcTags {
+    readonly launch: string;
+    readonly retry: string;
+    readonly cancel: string;
+    readonly respond: string;
+    /** Query returning ONE run row by id. */
+    readonly run: string;
+    /** Query returning the caller's recent runs. */
+    readonly runs: string;
+    /** Query returning the flow DEFINITIONS the caller may launch. */
+    readonly flows: string;
+}
+
+/** What `useFlowRun` hands a timeline component. */
+export declare interface FlowRunState {
+    readonly run: FlowRunView | undefined;
+    readonly steps: ReadonlyArray<RunStep>;
+    readonly status: RunStatus | undefined;
+    /** `true` while the run is parked on a human step. */
+    readonly awaitingReview: boolean;
+    /** The review the run is parked on (prompt + mode + options), if any. */
+    readonly review: RunReview | undefined;
+    /** Index of the step being executed / reviewed. */
+    readonly currentStep: number;
+    /** `true` once the run can no longer change. */
+    readonly done: boolean;
+    readonly loading: boolean;
+}
+
+/** The run row shape the hooks project — the reactive columns a timeline needs. */
+export declare interface FlowRunView {
+    readonly id: string;
+    readonly flowRef?: string;
+    readonly flowName?: string | null;
+    readonly status?: RunStatus;
+    readonly steps?: ReadonlyArray<RunStep> | null;
+    readonly currentStep?: number;
+    readonly totalSteps?: number;
+    readonly output?: Record<string, unknown> | null;
+    readonly humanResponse?: HumanResponse | null;
+    readonly costMicroUsd?: number;
+    readonly errorMessage?: string | null;
+    readonly startedAt?: string | null;
+    readonly completedAt?: string | null;
+}
+
 /** Flow-definition lifecycle. */
 export declare const FlowStatus: Schema.Literal<["draft", "active", "archived"]>;
 
@@ -99,6 +193,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>;
 }>;
 
 /**
@@ -139,6 +238,23 @@ export declare interface FlowStep {
     readonly schema?: Json | undefined;
     readonly reviewMode?: ReviewMode | undefined;
     readonly options?: ReadonlyArray<ReviewOption> | undefined;
+    readonly timeoutMs?: number | undefined;
+}
+
+/** 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>;
+}>;
+
+/** 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;
 }
 
 /** A JSON value (for `params` / `input` / a `structured` step's JSON Schema). */
@@ -146,6 +262,18 @@ declare const Json: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
 
 declare type Json = typeof Json.Type;
 
+export declare interface LaunchFlowInput {
+    readonly flowRef: string;
+    readonly input?: Record<string, unknown>;
+    readonly source?: 'manual' | 'cron';
+}
+
+export declare interface LaunchFlowResult {
+    readonly runId: string;
+    readonly requestId: string;
+    readonly status: RunStatus;
+}
+
 declare const MediaInputs: Schema.Record$<typeof Schema.String, Schema.Union<[Schema.Struct<{
     from: Schema.Literal<["upload"]>;
     url: typeof Schema.String;
@@ -179,7 +307,7 @@ export declare const ReviewOption: Schema.Struct<{
 export declare type ReviewOption = typeof ReviewOption.Type;
 
 /** Human-review config projected onto a `waiting` run step. */
-declare const RunReview: Schema.Struct<{
+export declare const RunReview: Schema.Struct<{
     mode: Schema.Literal<["approve", "choice", "text"]>;
     options: Schema.optional<Schema.Array$<Schema.Struct<{
         value: typeof Schema.String;
@@ -188,7 +316,7 @@ declare const RunReview: Schema.Struct<{
     prompt: typeof Schema.String;
 }>;
 
-declare type RunReview = typeof RunReview.Type;
+export declare type RunReview = typeof RunReview.Type;
 
 /** Run status — ONE canonical set (the legacy vocabulary; the Voltro-port
  *  additions `awaiting_human`/`completed`/`rejected` are collapsed: `waiting`
@@ -256,6 +384,131 @@ export declare const StepType: Schema.Literal<["agent", "generate", "structured"
 
 export declare type StepType = typeof StepType.Type;
 
+/** Cooperatively cancel a run (the engine stops before its next step). */
+export declare const useCancelFlow: (options?: FlowHookOptions) => {
+    cancel: (runId: string) => Promise<{
+        runId: string;
+        status: RunStatus;
+    }>;
+    pending: boolean;
+    error: unknown;
+};
+
+/**
+ * The whole review widget in one hook: the live run + the answer callbacks,
+ * with the pending review's prompt/options already unwrapped.
+ */
+export declare const useFlowReview: (runId: string | undefined, options?: FlowHookOptions) => {
+    prompt: string | undefined;
+    mode: "text" | "approve" | "choice" | undefined;
+    options: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+    /** `true` when there is a review this caller can answer right now. */
+    canRespond: boolean;
+    respond: (runId: string, response: HumanResponse) => Promise<{
+        runId: string;
+        stepIndex?: number;
+    }>;
+    approve: (runId: string, text?: string) => Promise<{
+        runId: string;
+        stepIndex?: number;
+    }>;
+    reject: (runId: string, text?: string) => Promise<{
+        runId: string;
+        stepIndex?: number;
+    }>;
+    /** Pick one of a `choice` review's options. */
+    choose: (runId: string, value: string) => Promise<{
+        runId: string;
+        stepIndex?: number;
+    }>;
+    /** Answer a `text` review. */
+    submitText: (runId: string, text: string) => Promise<{
+        runId: string;
+        stepIndex?: number;
+    }>;
+    pending: boolean;
+    error: unknown;
+    run: FlowRunView | undefined;
+    steps: ReadonlyArray<RunStep>;
+    status: RunStatus | undefined;
+    awaitingReview: boolean;
+    review: RunReview | undefined;
+    currentStep: number;
+    done: boolean;
+    loading: boolean;
+};
+
+/**
+ * Live view of ONE flow run. The run row is reactive, so the timeline streams:
+ * every step transition the engine writes shows up without a refetch.
+ *
+ * ```tsx
+ * const { steps, awaitingReview, review } = useFlowRun(runId)
+ * ```
+ */
+export declare const useFlowRun: (runId: string | undefined, options?: FlowHookOptions) => FlowRunState;
+
+/** The caller's recent runs (whatever the app's `runs` query returns). */
+export declare const useFlowRuns: (filter?: Readonly<Record<string, unknown>>, options?: FlowHookOptions) => ReadonlyArray<FlowRunView>;
+
+/** The flow DEFINITIONS the caller can launch (the gallery / picker). */
+export declare const useFlows: <T = Record<string, unknown>>(filter?: Readonly<Record<string, unknown>>, options?: FlowHookOptions) => ReadonlyArray<T>;
+
+/** Start a run. Returns the `runId` to hand `useFlowRun`. */
+export declare const useLaunchFlow: (options?: FlowHookOptions) => {
+    launch: (input: LaunchFlowInput) => Promise<LaunchFlowResult>;
+    pending: boolean;
+    error: unknown;
+    lastRun: LaunchFlowResult | undefined;
+};
+
+/**
+ * Answer the review a run is parked on. The server resolves WHICH human step the
+ * answer belongs to from the run's live timeline, so the UI never has to track a
+ * step index — and a flow with several reviews gets one answer per review.
+ *
+ * ```tsx
+ * const { approve, reject, choose, submitText } = useRespondToFlow()
+ * <button onClick={() => approve(runId)}>Approve</button>
+ * ```
+ */
+export declare const useRespondToFlow: (options?: FlowHookOptions) => {
+    respond: (runId: string, response: HumanResponse) => Promise<{
+        runId: string;
+        stepIndex?: number;
+    }>;
+    approve: (runId: string, text?: string) => Promise<{
+        runId: string;
+        stepIndex?: number;
+    }>;
+    reject: (runId: string, text?: string) => Promise<{
+        runId: string;
+        stepIndex?: number;
+    }>;
+    /** Pick one of a `choice` review's options. */
+    choose: (runId: string, value: string) => Promise<{
+        runId: string;
+        stepIndex?: number;
+    }>;
+    /** Answer a `text` review. */
+    submitText: (runId: string, text: string) => Promise<{
+        runId: string;
+        stepIndex?: number;
+    }>;
+    pending: boolean;
+    error: unknown;
+};
+
+/** Re-run a run from its first unfinished step (same requestId → journal replay). */
+export declare const useRetryFlow: (options?: FlowHookOptions) => {
+    retry: (runId: string) => Promise<LaunchFlowResult>;
+    pending: boolean;
+    error: unknown;
+};
+
 /** Gallery scope. `shared` → per-subject share list; `organization` → tenant. */
 export declare const Visibility: Schema.Literal<["private", "organization", "shared"]>;
 

package/dist/web.js

@@ -1,2 +1,97 @@
 import { n as e, t } from "./cadence-Bt6dPelT.js";
-export { t as cadenceMatches, e as nextRuns };
+import { useAction as n, useSubscription as r } from "@voltro/client";
+//#region src/web.ts
+var i = {
+	launch: "aiFlows.launch",
+	retry: "aiFlows.retry",
+	cancel: "aiFlows.cancel",
+	respond: "aiFlows.respond",
+	run: "aiFlows.run",
+	runs: "aiFlows.runs",
+	flows: "aiFlows.flows"
+}, a = (e) => e?.tags === void 0 ? i : {
+	...i,
+	...e.tags
+}, o = (e) => e?.apiName ?? "app", s = [
+	"succeeded",
+	"failed",
+	"cancelled"
+], c = (e, t) => {
+	let n = r(o(t), a(t).run, { id: e ?? "" }, { skip: e === void 0 || e === "" }), i = "data" in n ? n.data : void 0, c = (Array.isArray(i) ? i[0] : i) ?? void 0, l = c?.steps ?? [], u = l.find((e) => e.status === "waiting");
+	return {
+		run: c,
+		steps: l,
+		status: c?.status,
+		awaitingReview: c?.status === "waiting",
+		review: u?.review,
+		currentStep: c?.currentStep ?? 0,
+		done: c?.status !== void 0 && s.includes(c.status),
+		loading: c === void 0
+	};
+}, l = (e = {}, t) => {
+	let n = r(o(t), a(t).runs, e);
+	return ("data" in n ? n.data : void 0) ?? [];
+}, u = (e = {}, t) => {
+	let n = r(o(t), a(t).flows, e);
+	return ("data" in n ? n.data : void 0) ?? [];
+}, d = (e) => {
+	let t = n(o(e), a(e).launch);
+	return {
+		launch: (e) => t.run(e),
+		pending: t.pending,
+		error: t.error,
+		lastRun: t.lastResult
+	};
+}, f = (e) => {
+	let t = n(o(e), a(e).retry);
+	return {
+		retry: (e) => t.run({ runId: e }),
+		pending: t.pending,
+		error: t.error
+	};
+}, p = (e) => {
+	let t = n(o(e), a(e).cancel);
+	return {
+		cancel: (e) => t.run({ runId: e }),
+		pending: t.pending,
+		error: t.error
+	};
+}, m = (e) => {
+	let t = n(o(e), a(e).respond), r = (e, n) => t.run({
+		runId: e,
+		response: n
+	});
+	return {
+		respond: r,
+		approve: (e, t) => r(e, {
+			decision: "approve",
+			...t === void 0 ? {} : { text: t }
+		}),
+		reject: (e, t) => r(e, {
+			decision: "reject",
+			...t === void 0 ? {} : { text: t }
+		}),
+		choose: (e, t) => r(e, {
+			decision: "approve",
+			value: t
+		}),
+		submitText: (e, t) => r(e, {
+			decision: "approve",
+			text: t
+		}),
+		pending: t.pending,
+		error: t.error
+	};
+}, h = (e, t) => {
+	let n = c(e, t), r = m(t), i = n.review?.options ?? [];
+	return {
+		...n,
+		...r,
+		prompt: n.review?.prompt,
+		mode: n.review?.mode,
+		options: i,
+		canRespond: n.awaitingReview && e !== void 0
+	};
+};
+//#endregion
+export { i as DEFAULT_FLOW_RPC_TAGS, t as cadenceMatches, e as nextRuns, p as useCancelFlow, h as useFlowReview, c as useFlowRun, l as useFlowRuns, u as useFlows, d as useLaunchFlow, m as useRespondToFlow, f as useRetryFlow };

package/dist/workflow.d.ts

@@ -36,10 +36,35 @@ export declare const flowRunWorkflow: Workflow<"flow.run", Schema.Struct<{
 }>, typeof Schema.Never> & WorkflowMessagesCarrier<{
     readonly signals: {};
     readonly updates: {};
-    readonly queries: {};
 }>;
 
-/** 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";
+
+/**
+ * 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;
 
 export { }

package/dist/workflow.js

@@ -1,7 +1,7 @@
 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({
+var n = "flow.run", r = "flow-human-response", i = (e) => `${r}:${e}`, a = t({
 	name: n,
 	payload: {
 		runId: e.String,
@@ -20,4 +20,4 @@ var n = "flow.run", r = "flow-human-response", i = t({
 	idempotencyKey: ({ requestId: e }) => `flow-run:${e}`
 });
 //#endregion
-export { n as FLOW_RUN_WORKFLOW, r as HUMAN_RESPONSE_SIGNAL, i as flowRunWorkflow };
+export { n as FLOW_RUN_WORKFLOW, r as HUMAN_RESPONSE_SIGNAL_PREFIX, a as flowRunWorkflow, i as humanResponseSignalName };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-ai-flows",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "AI Flows — durable multi-step AI pipelines (deterministic + agentic) with human-in-the-loop, chaining, and cadence. Author flows in code (defineFlow) or as data (visual editor rows); one engine runs both on @voltro/workflow durability, @voltro/ai generation, storage artifacts, and notifications.",
   "keywords": [
     "voltro",
@@ -47,7 +47,8 @@
       "types": "./dist/web.d.ts",
       "import": "./dist/web.js",
       "default": "./dist/web.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -57,15 +58,16 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/ai": "0.32.0",
-    "@voltro/database": "0.32.0",
-    "@voltro/env": "0.32.0",
-    "@voltro/plugin-audit": "0.32.0",
-    "@voltro/plugin-multitenancy": "0.32.0",
-    "@voltro/plugin-soft-delete": "0.32.0",
-    "@voltro/protocol": "0.32.0",
-    "@voltro/runtime": "0.32.0",
-    "@voltro/workflow": "0.32.0"
+    "@voltro/ai": "0.34.0",
+    "@voltro/client": "0.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/env": "0.34.0",
+    "@voltro/plugin-audit": "0.34.0",
+    "@voltro/plugin-multitenancy": "0.34.0",
+    "@voltro/plugin-soft-delete": "0.34.0",
+    "@voltro/protocol": "0.34.0",
+    "@voltro/runtime": "0.34.0",
+    "@voltro/workflow": "0.34.0"
   },
   "peerDependencies": {
     "effect": "^3.22.0"