@voltro/ai 0.29.0 → 0.30.0

package/dist/workflow.d.ts

@@ -0,0 +1,304 @@
+import { DataStore } from '@voltro/database';
+import { Effect } from 'effect';
+import { Schema } from 'effect';
+import { StepRetryPolicy } from '@voltro/workflow';
+
+/** The provider-call retry default for an INLINE call.
+ *
+ *  A rate limit and a 5xx are how a model call fails, and both are transient.
+ *  Left to itself an unretried call fails the whole durable run for a condition
+ *  that resolves in two seconds. Overridable per step; `retry: { maxAttempts:
+ *  1 }` opts out. An OFFLOADED call retries in the dispatcher instead, on the
+ *  same rules — see `decideInferenceFailure`. */
+export declare const AI_STEP_RETRY: StepRetryPolicy;
+
+/** Provider-specific knobs forwarded verbatim to the Vercel AI SDK's
+ *  `providerOptions` on generateText / streamText / generateObject. The outer
+ *  key is the provider id, the inner record its options. The headline use is
+ *  REASONING EFFORT on reasoning models — `gpt-5.x` defaults to a high effort
+ *  that costs many seconds per call even for a one-line answer, so a routing/
+ *  help agent should pin it low:
+ *
+ *    providerOptions: { openai: { reasoningEffort: 'low' } }   // or 'minimal'
+ *    providerOptions: { anthropic: { thinking: { type: 'disabled' } } }
+ *
+ *  Shape matches the SDK's `ProviderOptions` (Record<provider, Record<key,
+ *  JSONValue>>). The value is the standard JSON value (mutable object + array,
+ *  so it stays assignable to the SDK's `SharedV2ProviderOptions` under
+ *  `exactOptionalPropertyTypes`) — NOT `unknown`, which the SDK rejects. */
+declare type AiJsonValue = null | boolean | number | string | {
+    [key: string]: AiJsonValue;
+} | AiJsonValue[];
+
+/**
+ * A schema-constrained completion as a durable step.
+ *
+ * The schema is the step's success schema too, so the journaled value is
+ * decoded on replay exactly as it was on the first run — a structured result
+ * that only validated the first time through would be the worst kind of replay
+ * bug.
+ *
+ * Offloaded, the schema is rendered to JSON Schema for the dispatcher (a
+ * JavaScript Schema cannot be journaled) and the DECODE still happens here,
+ * where the real schema exists.
+ */
+export declare const aiObjectStep: <A, I>(options: AiObjectStepOptions<A, I>) => Effect.Effect<A, unknown>;
+
+export declare interface AiObjectStepOptions<A, I> extends AiStepBaseOptions {
+    readonly schema: Schema.Schema<A, I>;
+}
+
+export declare class AiOffloadError extends Error {
+    readonly attempts: number;
+    constructor(stepName: string, message: string, attempts: number);
+}
+
+export declare class AiOffloadMisuseError extends Error {
+    constructor(stepName: string);
+}
+
+declare type AiProviderOptions = Record<string, Record<string, AiJsonValue>>;
+
+/**
+ * A text completion as a durable step.
+ *
+ * ```ts
+ * const summary = yield* aiStep({
+ *   name: 'summarise-thread',
+ *   prompt: `Summarise:\n${thread}`,
+ *   store: ctx.store,
+ *   offload: true,
+ * })
+ * ```
+ *
+ * On replay the journal answers and the model is not called again.
+ */
+export declare const aiStep: (options: AiStepOptions) => Effect.Effect<AiStepResult, unknown>;
+
+export declare interface AiStepBaseOptions {
+    /** Step name, as it appears in the journal and the dashboard. It also keys
+     *  the offloaded call's row, so it has to be stable across a replay — which
+     *  it is, being a literal in the body. */
+    readonly name: string;
+    readonly prompt: string;
+    readonly system?: string;
+    readonly provider?: ProviderConfig;
+    readonly fallbacks?: ProviderFallbacks;
+    readonly maxTokens?: number;
+    readonly providerOptions?: AiProviderOptions;
+    readonly retry?: StepRetryPolicy;
+    readonly recordPrompt?: PromptRecording;
+    /**
+     * The app's store.
+     *
+     * Used for the spend ledger, and REQUIRED for `offload` — that is where the
+     * queue lives. Omitting it on an inline call records no usage, which is a
+     * legitimate choice for a throwaway call and is reported as such rather than
+     * silently assumed.
+     */
+    readonly store?: DataStore;
+    /** Carried onto the usage row so spend can be split per tenant. */
+    readonly tenantId?: string | null;
+    /**
+     * Suspend the run while the model thinks, instead of holding a worker.
+     *
+     * The run parks on a durable deferred and a dispatcher performs the call.
+     * Costs one suspend/resume round trip; buys back a worker for the length of
+     * the call. Requires `store`.
+     */
+    readonly offload?: boolean;
+    /** End-to-end ceiling on an offloaded call. Default one hour. */
+    readonly offloadTimeoutMs?: number;
+}
+
+export declare interface AiStepOptions extends AiStepBaseOptions {
+}
+
+/** What an `aiStep` returns. The usage tally is part of the RESULT, not only of
+ *  the ledger — a workflow that wants to branch on token count should not have
+ *  to query a table to see what it just spent. */
+export declare interface AiStepResult {
+    readonly text: string;
+    readonly inputTokens: number | null;
+    readonly outputTokens: number | null;
+    readonly totalTokens: number | null;
+}
+
+declare type AnthropicModel = 'claude-opus-4-8' | 'claude-sonnet-4-6' | 'claude-haiku-4-5-20251001' | (string & {});
+
+/** Default ceiling on an offloaded call, end to end — one hour. Generous
+ *  because the wait itself is free (no worker is held), and a run that gives up
+ *  on a slow provider at ten minutes is a run somebody has to re-drive by hand. */
+export declare const DEFAULT_OFFLOAD_TIMEOUT_MS: number;
+
+/** Creator namespaces the Vercel AI Gateway routes to. Open union — the named
+ *  arms are autocomplete, any other creator string still works. */
+declare type GatewayCreator = 'openai' | 'anthropic' | 'google' | (string & {});
+
+/** The gateway addresses models as `creator/model` ids. The template-literal
+ *  type enforces that shape at COMPILE time — what `providerFromEnv` otherwise
+ *  only catches as a runtime throw (`{ name: 'gateway', model: 'gpt-5.5' }` is
+ *  now a type error, not a boot crash). */
+declare type GatewayModel = `${GatewayCreator}/${string}`;
+
+/** A scripted inline file the mock model emits on a turn (usually an image).
+ *  `data` is base64 (a short ascii string works for assertions). */
+declare interface MockFile {
+    readonly mediaType: string;
+    readonly data: string;
+}
+
+/** A consumable sequence of model turns, plus a recorder for asserting on
+ *  what the model was asked. Each `doGenerate`/`doStream` advances the
+ *  cursor by one turn; running past the end repeats the last turn's text
+ *  (or empties) so a loop that over-steps doesn't hang. */
+declare class MockScript {
+    private readonly turns;
+    private cursor;
+    readonly calls: Array<{
+        readonly prompt: unknown;
+        readonly tools: ReadonlyArray<string>;
+    }>;
+    constructor(turns: ReadonlyArray<MockTurn>);
+    record(prompt: unknown, tools: ReadonlyArray<string>): void;
+    next(): MockTurn;
+    reset(): void;
+}
+
+/** A scripted citation the mock model emits on a turn (RAG grounding). */
+declare interface MockSource {
+    readonly sourceType?: 'url' | 'document';
+    readonly id?: string;
+    readonly url?: string;
+    readonly title?: string;
+    readonly mediaType?: string;
+    readonly filename?: string;
+}
+
+/** A scripted tool call the mock model emits on a turn. */
+declare interface MockToolCall {
+    readonly name: string;
+    readonly input: unknown;
+}
+
+/** One model turn. A turn can carry text (streamed word-by-word), scripted
+ *  tool calls (which trigger the SDK's tool loop), cited sources, inline files,
+ *  or an error. A turn with tool calls + no text drives one LLM↔tool
+ *  round-trip. */
+declare interface MockTurn {
+    readonly text?: string;
+    /** Reasoning ("thinking") the mock streams before the answer text. */
+    readonly reasoning?: string;
+    readonly toolCalls?: ReadonlyArray<MockToolCall>;
+    readonly sources?: ReadonlyArray<MockSource>;
+    readonly files?: ReadonlyArray<MockFile>;
+    readonly error?: {
+        readonly message: string;
+    };
+}
+
+declare type OpenAIModel = 'gpt-5.5' | 'gpt-4o' | 'gpt-4o-mini' | (string & {});
+
+/** The digest form. A prefix, not the whole hash: this is a correlation handle,
+ *  and a full sha256 in a dashboard cell is a wall of hex nobody reads. */
+export declare const promptDigest: (prompt: string) => string;
+
+/**
+ * What gets written to `_voltro_workflow_run_steps.input` for a prompt.
+ *
+ * Exported because it is the security-relevant half of this module and it must
+ * be assertable on its own: "the raw prompt is not in the recorded input" is a
+ * property about a string, and testing it through a live model call would test
+ * the mock instead.
+ */
+export declare const promptRecordFor: (prompt: string, system: string | undefined, mode: PromptRecording) => Record<string, unknown>;
+
+/**
+ * How the prompt is written to the step row the dashboard renders.
+ *
+ * `'digest'` (default) — a sha256 prefix plus the character count. Enough to
+ * tell two runs apart, to spot a prompt that ballooned, and to correlate a
+ * cached result; not enough to leak the content of one.
+ *
+ * `'full'` — the prompt verbatim. Right for a prompt built from constants and
+ * a row id; wrong for one built from a customer's message, and typing it out is
+ * the point.
+ *
+ * `'none'` — record nothing about the prompt.
+ */
+export declare type PromptRecording = 'digest' | 'full' | 'none';
+
+/**
+ * A resolved provider choice — a DISCRIMINATED UNION on `name`. Each provider
+ * only carries the fields that apply to it: the mock-only `mockText` / `script`
+ * cannot appear on a real provider, and a real provider always carries a
+ * `model` typed to that provider's ids. `apiKey` / `baseURL` switch
+ * `resolveModel` to a per-config provider instance (per-agent key / BYOK);
+ * omit them to fall back to the provider's standard env var (OPENAI_API_KEY /
+ * ANTHROPIC_API_KEY / AI_GATEWAY_API_KEY).
+ */
+declare type ProviderConfig = {
+    readonly name: 'mock';
+    /** Optional for mock — defaults to `'mock'`. */
+    readonly model?: string;
+    /** The exact text the mock returns (instead of echoing the prompt).
+     *  Lets tests/demos drive `generateObject` with canned JSON. */
+    readonly mockText?: string;
+    /** A multi-turn script. Takes precedence over `mockText` — each
+     *  `doGenerate`/`doStream` consumes the next turn, so the SDK's tool
+     *  loop runs deterministically. */
+    readonly script?: MockScript;
+    /** Provider metadata the mock attaches to its `doGenerate` result — lets a
+     *  test exercise the gateway-cost path (`gatewayCostUsd`) deterministically
+     *  by faking `{ gateway: { cost } }`. Also surfaced by the mock speech +
+     *  video media models. */
+    readonly providerMetadata?: AiProviderOptions;
+    /** Canned output for the media models (`resolveImageModel` /
+     *  `resolveSpeechModel` / `resolveVideoModel`). Every field is optional and
+     *  falls back to a deterministic default, so `useMockAi` yields valid media
+     *  without configuration; set a field to assert on exact bytes / URL. */
+    readonly mockMedia?: {
+        /** base64 image payload `generateImage` decodes to bytes (default: a
+         *  1×1 PNG header, so media-type detection resolves to `image/png`). */
+        readonly imageBase64?: string;
+        /** base64 audio payload `generateSpeech` decodes to bytes. */
+        readonly audioBase64?: string;
+        /** URL the mock video model yields (the default branch — most video
+         *  providers return a URL rather than inline bytes). */
+        readonly videoUrl?: string;
+        /** base64 the mock video model yields INSTEAD of a URL — exercises the
+         *  bytes branch of `generateVideo`. Takes precedence over `videoUrl`. */
+        readonly videoBase64?: string;
+    };
+} | {
+    readonly name: 'anthropic';
+    readonly model: AnthropicModel;
+    readonly apiKey?: string;
+    readonly baseURL?: string;
+} | {
+    readonly name: 'openai';
+    readonly model: OpenAIModel;
+    readonly apiKey?: string;
+    readonly baseURL?: string;
+} | {
+    readonly name: 'gateway';
+    /** A `creator/model` id, e.g. 'openai/gpt-5.5'. */
+    readonly model: GatewayModel;
+    readonly apiKey?: string;
+    readonly baseURL?: string;
+};
+
+/**
+ * An ordered provider/model fallback chain. When a call FAILS on the primary
+ * provider (`provider ?? providerFromEnv()`) — after that provider's OWN
+ * SDK-level retries — the call re-runs against `fallbacks[0]`, then
+ * `fallbacks[1]`, … until one succeeds. Exhausting every option surfaces the
+ * LAST provider's typed error (an `AiError({ reason: 'generation' })`). Only a
+ * `generation` failure (the provider call itself) falls through — a `decode`
+ * failure (the model answered but the output didn't satisfy the schema) is a
+ * prompt/schema problem another provider won't fix, so it surfaces immediately.
+ * An empty / absent chain leaves behavior unchanged.
+ */
+declare type ProviderFallbacks = ReadonlyArray<ProviderConfig>;
+
+export { }

package/dist/workflow.js

@@ -0,0 +1,153 @@
+import { r as e } from "./provider-BOC5wBxx.js";
+import { O as t, f as n, g as r, h as i, j as a, o, s, t as c } from "./inferenceQueue-B25RTJZ4.js";
+import { Effect as l, Schema as u } from "effect";
+import { eq as d } from "@voltro/database";
+import { createHash as f } from "node:crypto";
+import { CurrentWorkflowExecutionId as p, awaitSignalSuspending as m, step as h } from "@voltro/workflow";
+//#region src/inferStep.ts
+var g = {
+	maxAttempts: 4,
+	strategy: "exponential",
+	baseDelay: "1 second",
+	maxDelay: "30 seconds",
+	jitter: !0,
+	respectRetryAfter: !0
+}, _ = 60 * 6e4, v = (e) => `sha256:${f("sha256").update(e).digest("hex").slice(0, 16)}`, y = (e, t, n) => n === "none" ? {} : n === "full" ? {
+	prompt: e,
+	...t === void 0 ? {} : { system: t }
+} : {
+	promptDigest: v(e),
+	promptChars: e.length,
+	...t === void 0 ? {} : {
+		systemDigest: v(t),
+		systemChars: t.length
+	}
+}, b = (e) => ({
+	provider: String(e.provider ?? "unknown"),
+	model: String(e.model ?? "unknown")
+}), x = (e, n, r, i) => {
+	let o = e.store;
+	if (o === void 0) return l.void;
+	let { provider: s, model: c } = b(n), u = t(i.providerMetadata);
+	return a(o, {
+		provider: s,
+		model: c,
+		operation: r,
+		agent: e.name,
+		usage: i.usage,
+		...e.tenantId === void 0 ? {} : { tenantId: e.tenantId },
+		...u === void 0 ? {} : { actualCostUsd: u }
+	}).pipe(l.asVoid, l.catchAllCause(() => l.void));
+}, S = u.Struct({
+	text: u.String,
+	inputTokens: u.NullOr(u.Number),
+	outputTokens: u.NullOr(u.Number),
+	totalTokens: u.NullOr(u.Number)
+}), C = (e) => typeof e == "object" && !!e && e.__voltro_ai_error === !0, w = class extends Error {
+	attempts;
+	constructor(e, t, n) {
+		super(`aiStep('${e}'): the offloaded model call gave up after ${n} attempt(s): ${t}. The queued call is in _voltro_ai_inferences with status 'failed' — the Flow tab shows it with the provider's own message.`), this.name = "AiOffloadError", this.attempts = n;
+	}
+}, T = class extends Error {
+	constructor(e) {
+		super(`aiStep('${e}'): offload: true needs \`store\` — the queued call lives in a table and the dispatcher reads it from there. Pass ctx.store.`), this.name = "AiOffloadMisuseError";
+	}
+}, E = (e, t, n, r) => l.gen(function* () {
+	let i = e.store;
+	if (i === void 0) return yield* l.die(new T(e.name));
+	let a = yield* p;
+	if (a === void 0) return yield* l.die(/* @__PURE__ */ Error(`aiStep('${e.name}'): offload: true is only valid inside a workflow body — there is no execution to suspend here.`));
+	let { provider: u, model: f } = b(t), m = s(a, e.name), h = yield* l.promise(() => i.query({
+		table: "_voltro_workflow_runs",
+		predicate: d("executionId", a),
+		order: [],
+		take: 1,
+		skip: void 0,
+		projection: void 0
+	})), g = String(h[0]?.tag ?? ""), _ = h[0]?.id;
+	return yield* l.promise(() => i.insertIgnore(c, {
+		id: m,
+		tenantId: e.tenantId ?? null,
+		executionId: a,
+		workflowName: g,
+		runId: typeof _ == "string" ? _ : null,
+		signalName: o(m),
+		stepName: e.name,
+		status: "pending",
+		kind: n,
+		provider: u,
+		model: f,
+		prompt: e.prompt,
+		system: e.system ?? null,
+		maxTokens: e.maxTokens ?? null,
+		providerOptions: e.providerOptions ?? null,
+		jsonSchema: r,
+		attempts: 0,
+		enqueuedAt: /* @__PURE__ */ new Date()
+	}, { conflictColumns: ["id"] })), m;
+}), D = (e, t, n, r, i) => l.gen(function* () {
+	let a = yield* h({
+		name: `${e.name}:enqueue`,
+		success: u.String,
+		input: i,
+		execute: E(e, t, n, r)
+	}), s = yield* m({ store: e.store }, {
+		name: o(a),
+		schema: u.Unknown,
+		timeoutMs: e.offloadTimeoutMs ?? 36e5
+	});
+	return C(s) ? yield* l.die(new w(e.name, s.message, s.attempts)) : s;
+}), O = (t) => {
+	let n = t.provider ?? e(), r = {
+		...b(n),
+		operation: "generateText",
+		offloaded: t.offload === !0,
+		...y(t.prompt, t.system, t.recordPrompt ?? "digest")
+	};
+	return t.offload === !0 ? D(t, n, "text", null, r) : h({
+		name: t.name,
+		success: S,
+		input: r,
+		retry: t.retry ?? g,
+		execute: i({
+			prompt: t.prompt,
+			provider: n,
+			...t.system === void 0 ? {} : { system: t.system },
+			...t.fallbacks === void 0 ? {} : { fallbacks: t.fallbacks },
+			...t.maxTokens === void 0 ? {} : { maxTokens: t.maxTokens },
+			...t.providerOptions === void 0 ? {} : { providerOptions: t.providerOptions }
+		}).pipe(l.tap((e) => x(t, n, "generateText", e)), l.map((e) => ({
+			text: e.text,
+			inputTokens: e.usage.inputTokens ?? null,
+			outputTokens: e.usage.outputTokens ?? null,
+			totalTokens: e.usage.totalTokens ?? null
+		})))
+	});
+}, k = (t) => {
+	let i = t.provider ?? e(), a = {
+		...b(i),
+		operation: "generateObject",
+		offloaded: t.offload === !0,
+		...y(t.prompt, t.system, t.recordPrompt ?? "digest")
+	};
+	return t.offload === !0 ? l.gen(function* () {
+		let e = yield* r(t.schema, "aiObjectStep"), n = yield* D(t, i, "object", e, a);
+		return yield* u.decodeUnknown(t.schema)(n);
+	}) : h({
+		name: t.name,
+		success: t.schema,
+		input: a,
+		retry: t.retry ?? g,
+		execute: n({
+			prompt: t.prompt,
+			schema: t.schema,
+			provider: i,
+			...t.system === void 0 ? {} : { system: t.system },
+			...t.fallbacks === void 0 ? {} : { fallbacks: t.fallbacks },
+			...t.maxTokens === void 0 ? {} : { maxTokens: t.maxTokens },
+			...t.providerOptions === void 0 ? {} : { providerOptions: t.providerOptions }
+		}).pipe(l.tap((e) => x(t, i, "generateObject", e)), l.map((e) => e.object))
+	});
+};
+//#endregion
+export { g as AI_STEP_RETRY, w as AiOffloadError, T as AiOffloadMisuseError, _ as DEFAULT_OFFLOAD_TIMEOUT_MS, k as aiObjectStep, O as aiStep, v as promptDigest, y as promptRecordFor };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/ai",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Effect-native AI primitives — generateText / generateObject / streamText, tools, agents, media generation, cost tracking + budgets, and provider fallback.",
   "keywords": [
     "voltro",
@@ -37,6 +37,11 @@
       "types": "./dist/test.d.ts",
       "import": "./dist/test.js",
       "default": "./dist/test.js"
+    },
+    "./workflow": {
+      "types": "./dist/workflow.d.ts",
+      "import": "./dist/workflow.js",
+      "default": "./dist/workflow.js"
     }
   },
   "main": "./dist/index.js",
@@ -51,9 +56,10 @@
     "@ai-sdk/gateway": "^4.0.30",
     "@ai-sdk/openai": "^4.0.22",
     "@ai-sdk/provider": "^4.0.4",
-    "@voltro/cache": "0.29.0",
-    "@voltro/database": "0.29.0",
-    "@voltro/protocol": "0.29.0",
+    "@voltro/cache": "0.30.0",
+    "@voltro/database": "0.30.0",
+    "@voltro/protocol": "0.30.0",
+    "@voltro/workflow": "0.30.0",
     "ai": "^7.0.40"
   },
   "peerDependencies": {