@voltro/plugin-ai-flows 0.75.0 → 0.77.0

package/dist/index.d.ts

@@ -38,7 +38,8 @@ export declare const aiFlowRunsTable: Table<"_voltro_ai_flow_runs", FieldDefinit
     readonly flowName: ColumnBuilder<string | null, "text", boolean>;
     /** Snapshot of the mode this run executes in. */
     readonly mode: ColumnBuilder<string, "text", true>;
-    /** pending | running | waiting | succeeded | failed | cancelled. */
+    /** pending | running | waiting | cancelling | succeeded | failed | cancelled.
+     * `cancelling` is a recorded request the engine has not yet confirmed. */
     readonly status: ColumnBuilder<string, "text", true>;
     /** manual | cron. */
     readonly source: ColumnBuilder<string | null, "text", boolean>;
@@ -293,24 +294,43 @@ export declare const buildFlowRunExecute: (ctx: AppContext, deps?: EngineDeps) =
 export declare const cadenceMatches: (cadence: FlowCadence, now: Date) => boolean;
 
 /**
- * Cancel a run on BOTH sides in one operation: the row (what the UI and the
- * cadence read) and the workflow execution (what actually runs, or waits at a
- * human step). Either half alone drifts — a row marked cancelled over a
- * suspended execution, or a cancelled execution under a row that still says
- * `waiting` — and a reader of one side never learns about the other.
+ * Request cancellation on both sides: the row records the request, which stops
+ * further cooperative steps, and the workflow facade interrupts a running or
+ * suspended execution. The row status carries the request's uncertainty: a
+ * live row moves to `cancelling` first and reads `cancelled` only once the
+ * engine confirmed — here through a confirmed cancelled snapshot, or later
+ * through the engine honouring the request cooperatively, the change tap
+ * seeing the engine's own run row cancelled, or a repeated confirmed request.
+ * Accepted, unknown and unreachable outcomes leave the row `cancelling`, so a
+ * later reader cannot mistake an unheard request for a stopped run.
  *
- * The row is patched first, so a cooperative check between steps sees it even
- * if the engine's interrupt is slow; the execution's own interrupt handler
- * (`buildFlowRunExecute`) writes the same terminal fields again, harmlessly.
- * An execution that cannot be reached (no runtime, not started) leaves the row
- * cancelled and says so in `engine`.
+ * Terminal rows (succeeded, failed, cancelled) are not rewritten and are not
+ * resubmitted to the engine. The conditional row update also protects a
+ * completion committed after the initial read. Repeated `cancelling` requests
+ * retain the original request timestamp and retry engine cancellation.
  */
 export declare const cancelFlow: (ctx: AppContext, args: {
     runId: string;
 }) => Effect.Effect<{
-    runId: string;
-    status: RunStatus;
-    engine: "unreachable" | "cancelled";
+    readonly status: "failed" | "pending" | "cancelled" | "running" | "succeeded" | "waiting" | "cancelling";
+    readonly runId: string;
+    readonly control: {
+        readonly snapshot: {
+            readonly status: "unknown" | "failed" | "cancelled" | "running" | "succeeded" | "suspended";
+            readonly id: string;
+            readonly error?: {
+                readonly message: string;
+                readonly tag: string | null;
+            } | undefined;
+            readonly output?: unknown;
+            readonly executionId: string;
+            readonly workflowName: string;
+        };
+        readonly kind: "unknown" | "accepted" | "confirmed" | "already-terminal";
+        readonly operation: "resume" | "cancel";
+        readonly requestId: string | null;
+    } | null;
+    readonly engine: "unknown" | "unreachable" | "cancelled" | "accepted" | "already-terminal" | "not-requested";
 }, FlowRunNotFound, never>;
 
 /** Staged follow-up when `chainTo.requireConfirmation` is set. */
@@ -535,6 +555,35 @@ export declare interface FlowCadence {
     readonly defaultInput?: Json | undefined;
 }
 
+/** Row state and engine acknowledgement are separate observations. Retain the
+ * control request identity so an accepted/unknown request can be observed.
+ * The row never claims `cancelled` on its own: a confirmed engine cancellation
+ * is the only receipt that reports a `cancelled` row, every other request
+ * outcome leaves the row `cancelling` (or a completion that won a race). */
+export declare const FlowCancelReceipt: Schema.filter<Schema.Struct<{
+    runId: typeof Schema.NonEmptyString;
+    status: Schema.Literal<["pending", "running", "waiting", "cancelling", "succeeded", "failed", "cancelled"]>;
+    engine: Schema.Literal<["cancelled", "accepted", "unknown", "already-terminal", "unreachable", "not-requested"]>;
+    control: Schema.NullOr<Schema.filter<Schema.Struct<{
+        operation: Schema.Literal<["cancel", "resume"]>;
+        kind: Schema.Literal<["accepted", "confirmed", "unknown", "already-terminal"]>;
+        requestId: Schema.NullOr<typeof Schema.NonEmptyString>;
+        snapshot: Schema.Struct<{
+            id: typeof Schema.String;
+            workflowName: typeof Schema.String;
+            executionId: typeof Schema.String;
+            status: Schema.Union<[Schema.Literal<["running", "succeeded", "failed", "cancelled", "suspended"]>, Schema.Literal<["unknown"]>]>;
+            output: Schema.optional<typeof Schema.Unknown>;
+            error: Schema.optional<Schema.Struct<{
+                tag: Schema.NullOr<typeof Schema.String>;
+                message: typeof Schema.String;
+            }>>;
+        }>;
+    }>>>;
+}>>;
+
+export declare type FlowCancelReceipt = typeof FlowCancelReceipt.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 {
@@ -1406,8 +1455,12 @@ 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"]>;
+ *  covers the human pause, `succeeded` is the single terminal-success literal).
+ *  `cancelling` is a recorded cancellation request the engine has not
+ *  confirmed: the row carries that uncertainty until the engine stops the run
+ *  (cooperatively, by interruption, or through a later confirmed request).
+ *  Only `succeeded`, `failed` and `cancelled` are terminal. */
+export declare const RunStatus: Schema.Literal<["pending", "running", "waiting", "cancelling", "succeeded", "failed", "cancelled"]>;
 
 export declare type RunStatus = typeof RunStatus.Type;