@voltro/plugin-ai-flows 0.70.0 → 0.71.0

package/dist/web.d.ts

@@ -109,6 +109,31 @@ export declare const FlowMode: Schema.Literal<["deterministic", "agentic"]>;
 
 export declare type FlowMode = typeof FlowMode.Type;
 
+/** Bind the answer to the review actually displayed, not the latest waiting step. */
+export declare const FlowReviewInput: Schema.Struct<{
+    runId: typeof Schema.NonEmptyString;
+    stepIndex: Schema.filter<typeof Schema.Int>;
+    response: 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 FlowReviewInput = typeof FlowReviewInput.Type;
+
+/** Delivery accepted; consumption and the run's eventual outcome remain reactive state. */
+export declare const FlowReviewReceipt: Schema.Struct<{
+    runId: typeof Schema.NonEmptyString;
+    stepIndex: Schema.filter<typeof Schema.Int>;
+    executionId: typeof Schema.NonEmptyString;
+    eventId: typeof Schema.NonEmptyString;
+    status: Schema.Literal<["accepted"]>;
+}>;
+
+export declare type FlowReviewReceipt = typeof FlowReviewReceipt.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 {
@@ -133,6 +158,8 @@ export declare interface FlowRunState {
     readonly awaitingReview: boolean;
     /** The review the run is parked on (prompt + mode + options), if any. */
     readonly review: RunReview | undefined;
+    /** Identity of the displayed waiting review; pass it with every answer. */
+    readonly reviewStepIndex: number | undefined;
     /** Index of the step being executed / reviewed. */
     readonly currentStep: number;
     /** `true` once the run can no longer change. */
@@ -157,6 +184,26 @@ export declare interface FlowRunView {
     readonly completedAt?: string | null;
 }
 
+/** Submission evidence, separate from the flow run's execution status. */
+declare const FlowStartReceipt: Schema.Struct<{
+    runId: typeof Schema.NonEmptyString;
+    requestId: typeof Schema.NonEmptyString;
+    admission: Schema.Struct<{
+        id: typeof Schema.String;
+        workflowName: typeof Schema.String;
+        executionId: Schema.NullOr<typeof Schema.String>;
+        status: Schema.Literal<["running", "succeeded", "queued", "dropped", "skipped", "replayed"]>;
+        deferral: Schema.optional<Schema.Struct<{
+            mode: typeof Schema.String;
+            dueAt: Schema.NullOr<typeof Schema.Number>;
+            retryAfterMs: Schema.NullOr<typeof Schema.Number>;
+            intentId: Schema.NullOr<typeof Schema.String>;
+        }>>;
+    }>;
+}>;
+
+declare type FlowStartReceipt = typeof FlowStartReceipt.Type;
+
 /** Flow-definition lifecycle. */
 export declare const FlowStatus: Schema.Literal<["draft", "active", "archived"]>;
 
@@ -187,11 +234,11 @@ export declare const FlowStep: Schema.Struct<{
     }>, Schema.Struct<{
         from: Schema.Literal<["step"]>;
         ref: typeof Schema.String;
+        artifact: Schema.optional<Schema.filter<typeof Schema.Int>>;
     }>]>>>;
-    /** Allowed sub-agent id/name. The framework resolves a real id; any
-     *  legacy-numeric bridge stays in the consumer app's mapping. */
+    /** Allowed sub-agent id/name, resolved and authorized by the host. */
     agentRef: Schema.optional<typeof Schema.String>;
-    /** JSON Schema of the desired object (adapted to an Effect Schema at run). */
+    /** JSON Schema of the desired object, preserved and validated 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<{
@@ -266,7 +313,7 @@ export declare interface FlowStep {
     readonly timeoutMs?: number | undefined;
 }
 
-/** The HITL answer, written by `respond`. */
+/** The HITL answer; the engine projects it after consuming the durable signal. */
 export declare const HumanResponse: Schema.Struct<{
     decision: Schema.optional<Schema.Literal<["approve", "reject"]>>;
     value: Schema.optional<typeof Schema.String>;
@@ -293,11 +340,19 @@ export declare interface LaunchFlowInput {
     readonly source?: 'manual' | 'cron';
 }
 
-export declare interface LaunchFlowResult {
-    readonly runId: string;
-    readonly requestId: string;
-    readonly status: RunStatus;
-}
+export declare type LaunchFlowResult = FlowStartReceipt;
+
+/** One persisted media artifact. Storage identity is not a provider request ID.
+ *  Exactly one artifact per result has role `primary`; other roles are host-defined. */
+declare const MediaArtifact: Schema.Struct<{
+    url: typeof Schema.NonEmptyString;
+    mediaType: typeof Schema.NonEmptyString;
+    role: typeof Schema.NonEmptyString;
+    storageRefId: Schema.optional<typeof Schema.NonEmptyString>;
+    providerMetadata: Schema.optional<typeof Schema.Unknown>;
+}>;
+
+declare type MediaArtifact = typeof MediaArtifact.Type;
 
 declare const MediaInputs: Schema.Record$<typeof Schema.String, Schema.Union<[Schema.Struct<{
     from: Schema.Literal<["upload"]>;
@@ -305,6 +360,7 @@ declare const MediaInputs: Schema.Record$<typeof Schema.String, Schema.Union<[Sc
 }>, Schema.Struct<{
     from: Schema.Literal<["step"]>;
     ref: typeof Schema.String;
+    artifact: Schema.optional<Schema.filter<typeof Schema.Int>>;
 }>]>>;
 
 declare type MediaInputs = typeof MediaInputs.Type;
@@ -364,6 +420,14 @@ export declare const RunStep: Schema.Struct<{
     requestId: Schema.optional<typeof Schema.String>;
     /** Hosted media artifact URL (image/video/audio), via storage. */
     url: Schema.optional<typeof Schema.String>;
+    /** All media variants, including roles and storage references; url projects the primary artifact. */
+    artifacts: Schema.optional<Schema.filter<Schema.Array$<Schema.Struct<{
+        url: typeof Schema.NonEmptyString;
+        mediaType: typeof Schema.NonEmptyString;
+        role: typeof Schema.NonEmptyString;
+        storageRefId: Schema.optional<typeof Schema.NonEmptyString>;
+        providerMetadata: Schema.optional<typeof Schema.Unknown>;
+    }>>>>;
     /** Inline text output (rendered as markdown). */
     output: Schema.optional<Schema.Struct<{
         text: typeof Schema.String;
@@ -396,6 +460,7 @@ export declare interface RunStep {
     readonly costMicroUsd?: number | undefined;
     readonly requestId?: string | undefined;
     readonly url?: string | undefined;
+    readonly artifacts?: ReadonlyArray<MediaArtifact> | undefined;
     readonly output?: {
         readonly text: string;
     } | undefined;
@@ -453,27 +518,42 @@ export declare const useFlowReview: (runId: string | undefined, options?: FlowHo
     }[];
     /** `true` when there is a review this caller can answer right now. */
     canRespond: boolean;
-    respond: (runId: string, response: HumanResponse) => Promise<{
-        runId: string;
-        stepIndex?: number;
+    respond: (runId: string, stepIndex: number, response: HumanResponse) => Promise<{
+        readonly status: "accepted";
+        readonly executionId: string;
+        readonly runId: string;
+        readonly eventId: string;
+        readonly stepIndex: number;
     }>;
-    approve: (runId: string, text?: string) => Promise<{
-        runId: string;
-        stepIndex?: number;
+    approve: (runId: string, stepIndex: number, text?: string) => Promise<{
+        readonly status: "accepted";
+        readonly executionId: string;
+        readonly runId: string;
+        readonly eventId: string;
+        readonly stepIndex: number;
     }>;
-    reject: (runId: string, text?: string) => Promise<{
-        runId: string;
-        stepIndex?: number;
+    reject: (runId: string, stepIndex: number, text?: string) => Promise<{
+        readonly status: "accepted";
+        readonly executionId: string;
+        readonly runId: string;
+        readonly eventId: string;
+        readonly stepIndex: number;
     }>;
     /** Pick one of a `choice` review's options. */
-    choose: (runId: string, value: string) => Promise<{
-        runId: string;
-        stepIndex?: number;
+    choose: (runId: string, stepIndex: number, value: string) => Promise<{
+        readonly status: "accepted";
+        readonly executionId: string;
+        readonly runId: string;
+        readonly eventId: string;
+        readonly stepIndex: number;
     }>;
     /** Answer a `text` review. */
-    submitText: (runId: string, text: string) => Promise<{
-        runId: string;
-        stepIndex?: number;
+    submitText: (runId: string, stepIndex: number, text: string) => Promise<{
+        readonly status: "accepted";
+        readonly executionId: string;
+        readonly runId: string;
+        readonly eventId: string;
+        readonly stepIndex: number;
     }>;
     pending: boolean;
     error: unknown;
@@ -482,6 +562,7 @@ export declare const useFlowReview: (runId: string | undefined, options?: FlowHo
     status: RunStatus | undefined;
     awaitingReview: boolean;
     review: RunReview | undefined;
+    reviewStepIndex: number | undefined;
     currentStep: number;
     done: boolean;
     loading: boolean;
@@ -505,52 +586,111 @@ export declare const useFlows: <T = Record<string, unknown>>(filter?: Readonly<R
 
 /** Start a run. Returns the `runId` to hand `useFlowRun`. */
 export declare const useLaunchFlow: (options?: FlowHookOptions) => {
-    launch: (input: LaunchFlowInput) => Promise<LaunchFlowResult>;
+    launch: (input: LaunchFlowInput) => Promise<{
+        readonly runId: string;
+        readonly requestId: string;
+        readonly admission: {
+            readonly status: "dropped" | "skipped" | "running" | "succeeded" | "queued" | "replayed";
+            readonly id: string;
+            readonly executionId: string | null;
+            readonly workflowName: string;
+            readonly deferral?: {
+                readonly mode: string;
+                readonly retryAfterMs: number | null;
+                readonly dueAt: number | null;
+                readonly intentId: string | null;
+            } | undefined;
+        };
+    }>;
     pending: boolean;
     error: unknown;
-    lastRun: LaunchFlowResult | undefined;
+    lastRun: {
+        readonly runId: string;
+        readonly requestId: string;
+        readonly admission: {
+            readonly status: "dropped" | "skipped" | "running" | "succeeded" | "queued" | "replayed";
+            readonly id: string;
+            readonly executionId: string | null;
+            readonly workflowName: string;
+            readonly deferral?: {
+                readonly mode: string;
+                readonly retryAfterMs: number | null;
+                readonly dueAt: number | null;
+                readonly intentId: string | null;
+            } | undefined;
+        };
+    } | 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.
+ * Answer the displayed review. Carry its step index so a delayed click cannot
+ * answer a later review of the same run. The server verifies it still waits.
  *
  * ```tsx
  * const { approve, reject, choose, submitText } = useRespondToFlow()
- * <button onClick={() => approve(runId)}>Approve</button>
+ * <button onClick={() => approve(runId, reviewStepIndex)}>Approve</button>
  * ```
  */
 export declare const useRespondToFlow: (options?: FlowHookOptions) => {
-    respond: (runId: string, response: HumanResponse) => Promise<{
-        runId: string;
-        stepIndex?: number;
+    respond: (runId: string, stepIndex: number, response: HumanResponse) => Promise<{
+        readonly status: "accepted";
+        readonly executionId: string;
+        readonly runId: string;
+        readonly eventId: string;
+        readonly stepIndex: number;
     }>;
-    approve: (runId: string, text?: string) => Promise<{
-        runId: string;
-        stepIndex?: number;
+    approve: (runId: string, stepIndex: number, text?: string) => Promise<{
+        readonly status: "accepted";
+        readonly executionId: string;
+        readonly runId: string;
+        readonly eventId: string;
+        readonly stepIndex: number;
     }>;
-    reject: (runId: string, text?: string) => Promise<{
-        runId: string;
-        stepIndex?: number;
+    reject: (runId: string, stepIndex: number, text?: string) => Promise<{
+        readonly status: "accepted";
+        readonly executionId: string;
+        readonly runId: string;
+        readonly eventId: string;
+        readonly stepIndex: number;
     }>;
     /** Pick one of a `choice` review's options. */
-    choose: (runId: string, value: string) => Promise<{
-        runId: string;
-        stepIndex?: number;
+    choose: (runId: string, stepIndex: number, value: string) => Promise<{
+        readonly status: "accepted";
+        readonly executionId: string;
+        readonly runId: string;
+        readonly eventId: string;
+        readonly stepIndex: number;
     }>;
     /** Answer a `text` review. */
-    submitText: (runId: string, text: string) => Promise<{
-        runId: string;
-        stepIndex?: number;
+    submitText: (runId: string, stepIndex: number, text: string) => Promise<{
+        readonly status: "accepted";
+        readonly executionId: string;
+        readonly runId: string;
+        readonly eventId: string;
+        readonly stepIndex: number;
     }>;
     pending: boolean;
     error: unknown;
 };
 
-/** Re-run a run from its first unfinished step (same requestId → journal replay). */
+/** Resubmit the stored request. Inspect admission before claiming a new start. */
 export declare const useRetryFlow: (options?: FlowHookOptions) => {
-    retry: (runId: string) => Promise<LaunchFlowResult>;
+    retry: (runId: string) => Promise<{
+        readonly runId: string;
+        readonly requestId: string;
+        readonly admission: {
+            readonly status: "dropped" | "skipped" | "running" | "succeeded" | "queued" | "replayed";
+            readonly id: string;
+            readonly executionId: string | null;
+            readonly workflowName: string;
+            readonly deferral?: {
+                readonly mode: string;
+                readonly retryAfterMs: number | null;
+                readonly dueAt: number | null;
+                readonly intentId: string | null;
+            } | undefined;
+        };
+    }>;
     pending: boolean;
     error: unknown;
 };

package/dist/web.js

@@ -24,6 +24,7 @@ var i = {
 		status: c?.status,
 		awaitingReview: c?.status === "waiting",
 		review: u?.review,
+		reviewStepIndex: u?.id,
 		currentStep: c?.currentStep ?? 0,
 		done: c?.status !== void 0 && s.includes(c.status),
 		loading: c === void 0
@@ -57,27 +58,28 @@ var i = {
 		error: t.error
 	};
 }, m = (e) => {
-	let t = n(o(e), a(e).respond), r = (e, n) => t.run({
+	let t = n(o(e), a(e).respond), r = (e, n, r) => t.run({
 		runId: e,
-		response: n
+		stepIndex: n,
+		response: r
 	});
 	return {
 		respond: r,
-		approve: (e, t) => r(e, {
+		approve: (e, t, n) => r(e, t, {
 			decision: "approve",
-			...t === void 0 ? {} : { text: t }
+			...n === void 0 ? {} : { text: n }
 		}),
-		reject: (e, t) => r(e, {
+		reject: (e, t, n) => r(e, t, {
 			decision: "reject",
-			...t === void 0 ? {} : { text: t }
+			...n === void 0 ? {} : { text: n }
 		}),
-		choose: (e, t) => r(e, {
+		choose: (e, t, n) => r(e, t, {
 			decision: "approve",
-			value: t
+			value: n
 		}),
-		submitText: (e, t) => r(e, {
+		submitText: (e, t, n) => r(e, t, {
 			decision: "approve",
-			text: t
+			text: n
 		}),
 		pending: t.pending,
 		error: t.error
@@ -90,7 +92,7 @@ var i = {
 		prompt: n.review?.prompt,
 		mode: n.review?.mode,
 		options: i,
-		canRespond: n.awaitingReview && e !== void 0
+		canRespond: n.awaitingReview && n.reviewStepIndex !== void 0 && e !== void 0
 	};
 };
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-ai-flows",
-  "version": "0.70.0",
+  "version": "0.71.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",
@@ -58,16 +58,16 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/ai": "0.70.0",
-    "@voltro/client": "0.70.0",
-    "@voltro/database": "0.70.0",
-    "@voltro/env": "0.70.0",
-    "@voltro/plugin-audit": "0.70.0",
-    "@voltro/plugin-multitenancy": "0.70.0",
-    "@voltro/plugin-soft-delete": "0.70.0",
-    "@voltro/protocol": "0.70.0",
-    "@voltro/runtime": "0.70.0",
-    "@voltro/workflow": "0.70.0"
+    "@voltro/ai": "0.71.0",
+    "@voltro/client": "0.71.0",
+    "@voltro/database": "0.71.0",
+    "@voltro/env": "0.71.0",
+    "@voltro/plugin-audit": "0.71.0",
+    "@voltro/plugin-multitenancy": "0.71.0",
+    "@voltro/plugin-soft-delete": "0.71.0",
+    "@voltro/protocol": "0.71.0",
+    "@voltro/runtime": "0.71.0",
+    "@voltro/workflow": "0.71.0"
   },
   "peerDependencies": {
     "effect": "^3.22.1"