@voltro/plugin-ai-flows 0.71.0 → 0.72.0

package/dist/errors.js

@@ -28,6 +28,11 @@ var t = class extends e.TaggedError()("FlowNotFound", {
 }) {}, c = class extends e.TaggedError()("FlowCapabilityMissing", {
 	capability: e.String,
 	message: e.String
+}) {}, l = class extends e.TaggedError()("FlowAgentUnavailable", {
+	agentRef: e.String,
+	reason: e.Literal("not-found", "access-revoked", "model-unusable"),
+	message: e.String,
+	publicMessage: e.optional(e.String)
 }) {};
 //#endregion
-export { a as FlowBriefIncomplete, c as FlowCapabilityMissing, i as FlowDependencyError, o as FlowNotAwaitingResponse, t as FlowNotFound, s as FlowReviewDeliveryError, n as FlowRunNotFound, r as FlowValidationError };
+export { l as FlowAgentUnavailable, a as FlowBriefIncomplete, c as FlowCapabilityMissing, i as FlowDependencyError, o as FlowNotAwaitingResponse, t as FlowNotFound, s as FlowReviewDeliveryError, n as FlowRunNotFound, r as FlowValidationError };

package/dist/index.d.ts

@@ -12,6 +12,11 @@ import { TableLike } from '@voltro/database';
 import { VoltroPlugin } from '@voltro/protocol';
 import { WorkflowEngine } from '@effect/workflow/WorkflowEngine';
 import { WorkflowInstance } from '@effect/workflow/WorkflowEngine';
+import { WorkflowRunHandle } from '@voltro/protocol';
+
+/** The handle a flow row records for an ADMITTED start: the execution the
+ *  engine owns. `id` is that execution too — the stable handle callers pass on. */
+export declare const admittedStartHandle: (executionId: string) => WorkflowRunHandle;
 
 /** An `agent` step's resolved persona. */
 export declare interface AgentResolution {
@@ -76,6 +81,8 @@ export declare const aiFlowRunsTable: Table<"_voltro_ai_flow_runs", FieldDefinit
     readonly chainRefusal: ColumnBuilder<string | null, "text", boolean>;
     /** Accumulated cost in micro-USD (app view projects to €/cents). */
     readonly costMicroUsd: ColumnBuilder<number, "integer", true>;
+    /** `actual` | `estimated` | `incomplete` | `unknown` — whether `costMicroUsd` can be booked as spend, or only read as a floor. */
+    readonly costCompleteness: ColumnBuilder<string, "text", true>;
     readonly durationMs: ColumnBuilder<number | null, "integer", boolean>;
     readonly error: ColumnBuilder<string | null, "text", boolean>;
     readonly errorMessage: ColumnBuilder<string | null, "text", boolean>;
@@ -285,13 +292,25 @@ export declare const buildFlowRunExecute: (ctx: AppContext, deps?: EngineDeps) =
  */
 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). */
+/**
+ * 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.
+ *
+ * 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`.
+ */
 export declare const cancelFlow: (ctx: AppContext, args: {
     runId: string;
 }) => Effect.Effect<{
     runId: string;
     status: RunStatus;
+    engine: "unreachable" | "cancelled";
 }, FlowRunNotFound, never>;
 
 /** Staged follow-up when `chainTo.requireConfirmation` is set. */
@@ -321,6 +340,16 @@ export declare const ConditionOp: Schema.Literal<["truthy", "falsy", "eq", "neq"
 
 export declare type ConditionOp = typeof ConditionOp.Type;
 
+/** A run's cost verdict over its steps: every step gateway-priced → `actual`; none unpriced → `estimated`; any unpriced → `incomplete`; no priced step → `unknown`. */
+export declare const CostCompleteness: Schema.Literal<["actual", "estimated", "incomplete", "unknown"]>;
+
+export declare type CostCompleteness = typeof CostCompleteness.Type;
+
+/** Where a cost figure came from. `unpriced` means the number beside it is a placeholder, not a price. */
+export declare const CostSource: Schema.Literal<["gateway", "estimated", "unpriced"]>;
+
+export declare type CostSource = typeof CostSource.Type;
+
 /** 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>;
@@ -364,13 +393,27 @@ export declare const describeCondition: (condition: StepCondition) => string;
 export declare interface EngineDeps {
     /** Resolve an agent in the durable run's tenant, in deterministic steps AND
      *  the agentic `run_agent` tool. Do not infer tenancy from the current subject:
-     *  a crash resume may run as system. Absent → FlowCapabilityMissing. */
-    readonly resolveAgent?: (agentRef: string, run: MediaRunContext) => Effect.Effect<AgentResolution, FlowNotFound, unknown>;
+     *  a crash resume may run as system. Absent → FlowCapabilityMissing.
+     *
+     *  Refuse with `FlowAgentUnavailable` for anything that is not "no such
+     *  agent" — revoked access, a model the host cannot serve. Its `message` is
+     *  for the HOST (the step's error, the run's log); what the MODEL sees in the
+     *  agentic planner is `publicMessage`, or a generic "agent unavailable" — a
+     *  resolver's words are tool output, so never say anything private in
+     *  `publicMessage`. */
+    readonly resolveAgent?: (agentRef: string, run: FlowRunContext) => Effect.Effect<AgentResolution, FlowNotFound | FlowAgentUnavailable, unknown>;
     /** Additional tools for the agentic planner, resolved inside its durable step.
      *  The original flow reference and durable tenant are scope, not authorization.
      *  Enforce current access in this callback and the tools. Internal planner names
-     *  cannot be replaced. Deterministic agent tools belong to AgentResolution. */
-    readonly resolveTools?: (flowRef: string, run: MediaRunContext) => Effect.Effect<Record<string, AnyTool>, FlowCapabilityMissing, unknown>;
+     *  cannot be replaced. Deterministic agent tools belong to AgentResolution.
+     *  `planner.provider()` is the provider the planner will run on — a host that
+     *  offers a provider-native search (web search on OpenAI, Google, Anthropic)
+     *  picks the matching tool from it. A thunk: resolved only when asked, so a
+     *  resolver that fails never resolves the model. A failure here fails the planner with
+     *  the resolver's own message. */
+    readonly resolveTools?: (flowRef: string, run: FlowRunContext, planner: {
+        readonly provider: () => ProviderConfig | undefined;
+    }) => Effect.Effect<Record<string, AnyTool>, FlowCapabilityMissing, unknown>;
     /** Media generator for image/video/audio steps (`makeMediaGenerator` in
      *  `mediaAdapter.ts` is the @voltro/ai-backed implementation). */
     readonly generateMedia?: MediaGenerator;
@@ -425,6 +468,24 @@ export declare const FLOW_RUNS_TTL_ENV = "VOLTRO_AI_FLOW_RUNS_TTL_HOURS";
  *  runs. Only TERMINAL runs are swept — see `index.ts`. */
 export declare const FLOW_RUNS_TTL_HOURS_DEFAULT: number;
 
+/**
+ * An agent the host will not serve for this run: access revoked, a model it
+ * cannot run, or nothing under that reference. `message` is for the host —
+ * the step's error and the run's log. `publicMessage` is the ONLY sentence
+ * the agentic planner's model sees; leave it out for a generic line.
+ */
+declare class FlowAgentUnavailable extends FlowAgentUnavailable_base {
+}
+
+declare const FlowAgentUnavailable_base: Schema.TaggedErrorClass<FlowAgentUnavailable, "FlowAgentUnavailable", {
+    readonly _tag: Schema.tag<"FlowAgentUnavailable">;
+} & {
+    agentRef: typeof Schema.String;
+    reason: Schema.Literal<["not-found", "access-revoked", "model-unusable"]>;
+    message: typeof Schema.String;
+    publicMessage: Schema.optional<typeof Schema.String>;
+}>;
+
 /** A required brief field was blank at launch. */
 declare class FlowBriefIncomplete extends FlowBriefIncomplete_base {
 }
@@ -618,6 +679,24 @@ export declare const FlowReviewReceipt: Schema.Struct<{
 
 export declare type FlowReviewReceipt = typeof FlowReviewReceipt.Type;
 
+/** The run an agent or media step executes within, resolved from the durable RUN ROW —
+ *  not the caller subject. This is the difference between a normal call and a
+ *  resume: a BOOTSTRAP/crash resume runs under a tenant-less `SYSTEM_SUBJECT`,
+ *  so a host that persists artifacts per tenant cannot read the tenant from
+ *  `ctx.request.subject` (it isn't there) and would either fail closed or, worse
+ *  under the old fallback, write into the wrong tenant. The engine reads the run
+ *  row it already loads and hands the original tenant down here, so persistence
+ *  continues in the right place on replay. */
+export declare interface FlowRunContext {
+    readonly runId: string;
+    /** The run's tenant as stamped when it was created, or `null` for a
+     *  single-tenant app. Authoritative on resume, where the subject has none. */
+    readonly tenantId: string | null;
+    /** The run's owner as stored on its row, or `null`. Every host used to load
+     *  the row again for this; a cadence run has none. */
+    readonly ownerId: string | null;
+}
+
 /** A flow run row could not be found. */
 declare class FlowRunNotFound extends FlowRunNotFound_base {
 }
@@ -684,6 +763,22 @@ export declare const FlowStartReceipt: Schema.Struct<{
 
 export declare type FlowStartReceipt = typeof FlowStartReceipt.Type;
 
+export declare interface FlowStartReconciliation {
+    /** Rows read with a queued handle. */
+    readonly examined: number;
+    /** Rows now `running` under the execution the engine accepted. */
+    readonly accepted: number;
+    /** Rows now `failed` because their start will never run. */
+    readonly notExecuted: number;
+    /** Rows still queued. */
+    readonly pending: number;
+    /** Per-row read or write failures; the other rows were still reconciled. */
+    readonly failures: ReadonlyArray<{
+        readonly runId: string;
+        readonly cause: unknown;
+    }>;
+}
+
 /** Flow-definition lifecycle. */
 export declare const FlowStatus: Schema.Literal<["draft", "active", "archived"]>;
 
@@ -711,6 +806,7 @@ export declare const FlowStep: Schema.Struct<{
     mediaInputs: Schema.optional<Schema.Record$<typeof Schema.String, Schema.Union<[Schema.Struct<{
         from: Schema.Literal<["upload"]>;
         url: typeof Schema.String;
+        mediaType: Schema.optional<typeof Schema.NonEmptyString>;
     }>, Schema.Struct<{
         from: Schema.Literal<["step"]>;
         ref: typeof Schema.String;
@@ -1038,14 +1134,21 @@ export declare type MediaGenerator = (args: {
     readonly prompt: string;
     readonly params?: Record<string, unknown>;
     readonly inputs?: ResolvedMediaInputs;
+    /** The same slots as TYPED references, for the models that require one
+     *  (`inputReferences: [{ type: 'url', url, mediaType }]`): an upload that
+     *  declared its `mediaType`, and a prior step's artifact, whose type the
+     *  engine already knows. A slot without a known type is in `inputs` only —
+     *  a type is never guessed from a URL. */
+    readonly inputRefs?: ResolvedMediaInputRefs;
     /** The run this artifact belongs to — pin persistence to `run.tenantId` rather
      *  than the current subject, so a system/bootstrap resume stores it correctly. */
-    readonly run: MediaRunContext;
+    readonly run: FlowRunContext;
 }) => Effect.Effect<MediaResult, FlowCapabilityMissing, unknown>;
 
 export declare const MediaInputs: Schema.Record$<typeof Schema.String, Schema.Union<[Schema.Struct<{
     from: Schema.Literal<["upload"]>;
     url: typeof Schema.String;
+    mediaType: Schema.optional<typeof Schema.NonEmptyString>;
 }>, Schema.Struct<{
     from: Schema.Literal<["step"]>;
     ref: typeof Schema.String;
@@ -1060,6 +1163,7 @@ export declare type MediaInputs = typeof MediaInputs.Type;
 export declare const MediaInputSlot: Schema.Union<[Schema.Struct<{
     from: Schema.Literal<["upload"]>;
     url: typeof Schema.String;
+    mediaType: Schema.optional<typeof Schema.NonEmptyString>;
 }>, Schema.Struct<{
     from: Schema.Literal<["step"]>;
     ref: typeof Schema.String;
@@ -1071,7 +1175,7 @@ export declare type MediaInputSlot = typeof MediaInputSlot.Type;
 /** Host-supplied persistence (from @voltro/plugin-storage's StorageService).
  *
  *  Both hooks receive the `run` — its `tenantId` is the durable, resume-safe
- *  tenant (see `MediaRunContext`). Pass it to `storage.put`/`ingestUrl` as the
+ *  tenant (see `FlowRunContext`). Pass it to `storage.put`/`ingestUrl` as the
  *  scope so a BOOTSTRAP resume, whose subject has no tenant, still writes into
  *  the run's own tenant instead of failing or defaulting. */
 export declare interface MediaPersist {
@@ -1079,11 +1183,11 @@ export declare interface MediaPersist {
     readonly put: (args: {
         data: Uint8Array | string;
         mediaType: string;
-        run: MediaRunContext;
+        run: FlowRunContext;
     }) => Effect.Effect<StoredMedia, unknown, unknown>;
     /** Re-host a provider URL (StorageService.ingestUrl). If absent, a provider
      *  video URL is used as-is (no re-hosting). */
-    readonly ingestUrl?: (url: string, run: MediaRunContext) => Effect.Effect<StoredMedia, unknown, unknown>;
+    readonly ingestUrl?: (url: string, run: FlowRunContext) => Effect.Effect<StoredMedia, unknown, unknown>;
 }
 
 export declare const MediaResult: Schema.Struct<{
@@ -1095,27 +1199,13 @@ export declare const MediaResult: Schema.Struct<{
         providerMetadata: Schema.optional<typeof Schema.Unknown>;
     }>>>;
     costMicroUsd: Schema.optional<Schema.filter<typeof Schema.Finite>>;
+    costSource: Schema.optional<Schema.Literal<["gateway", "estimated", "unpriced"]>>;
     /** A provider/usage correlation only, never a storage reference. */
     requestId: Schema.optional<typeof Schema.NonEmptyString>;
 }>;
 
 export declare type MediaResult = typeof MediaResult.Type;
 
-/** The run an agent or media step executes within, resolved from the durable RUN ROW —
- *  not the caller subject. This is the difference between a normal call and a
- *  resume: a BOOTSTRAP/crash resume runs under a tenant-less `SYSTEM_SUBJECT`,
- *  so a host that persists artifacts per tenant cannot read the tenant from
- *  `ctx.request.subject` (it isn't there) and would either fail closed or, worse
- *  under the old fallback, write into the wrong tenant. The engine reads the run
- *  row it already loads and hands the original tenant down here, so persistence
- *  continues in the right place on replay. */
-export declare interface MediaRunContext {
-    readonly runId: string;
-    /** The run's tenant as stamped when it was created, or `null` for a
-     *  single-tenant app. Authoritative on resume, where the subject has none. */
-    readonly tenantId: string | null;
-}
-
 export declare const Modality: Schema.Literal<["text", "image", "video", "audio"]>;
 
 export declare type Modality = typeof Modality.Type;
@@ -1137,6 +1227,15 @@ export declare const nonContiguousGroups: (segments: ReadonlyArray<FlowSegment>)
  */
 export declare const normalizeFlow: (def: FlowDefinitionInput) => FlowIR;
 
+/**
+ * Converge every pending flow run whose start was recorded as `queued` onto
+ * what that start has become. Bounded by `take` (newest-first is not needed:
+ * a pending row is pending until it converges, so any order visits it).
+ */
+export declare const reconcileFlowStarts: (ctx: AppContext, options?: {
+    readonly take?: number;
+}) => Promise<FlowStartReconciliation>;
+
 /** 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;
@@ -1144,6 +1243,13 @@ export declare const registerFlow: (ir: FlowIR) => void;
 /** Test seam — forget the recorded tunables. */
 export declare const resetAiFlowsDefaults: () => void;
 
+declare const ResolvedMediaInputRefs: Schema.Record$<typeof Schema.String, Schema.Struct<{
+    url: Schema.filter<typeof Schema.String>;
+    mediaType: typeof Schema.NonEmptyString;
+}>>;
+
+declare type ResolvedMediaInputRefs = typeof ResolvedMediaInputRefs.Type;
+
 declare const ResolvedMediaInputs: Schema.Record$<typeof Schema.String, Schema.filter<typeof Schema.String>>;
 
 declare type ResolvedMediaInputs = typeof ResolvedMediaInputs.Type;
@@ -1236,6 +1342,7 @@ export declare type ReviewOption = typeof ReviewOption.Type;
 export declare const runCadenceTick: (ctx: AppContext, now?: Date) => Promise<{
     readonly matched: number;
     readonly started: ReadonlyArray<string>;
+    readonly reconciled: FlowStartReconciliation;
 }>;
 
 /** Human-review config projected onto a `waiting` run step. */
@@ -1272,6 +1379,9 @@ export declare const RunStep: Schema.Struct<{
     completedAt: Schema.optional<typeof Schema.String>;
     /** Per-step cost in micro-USD (the app view projects to €/cents). */
     costMicroUsd: Schema.optional<typeof Schema.Number>;
+    /** Where that number came from — the gateway's actual charge, a price-table
+     *  estimate, or nothing (`unpriced`: the 0 above is not a price). */
+    costSource: Schema.optional<Schema.Literal<["gateway", "estimated", "unpriced"]>>;
     /** Links a media step to its generation/usage record. */
     requestId: Schema.optional<typeof Schema.String>;
     /** Hosted media artifact URL (image/video/audio), via storage. */
@@ -1314,6 +1424,7 @@ export declare interface RunStep {
     readonly startedAt?: string | undefined;
     readonly completedAt?: string | undefined;
     readonly costMicroUsd?: number | undefined;
+    readonly costSource?: CostSource | undefined;
     readonly requestId?: string | undefined;
     readonly url?: string | undefined;
     readonly artifacts?: ReadonlyArray<MediaArtifact> | undefined;