@voltro/ai 0.29.0 → 0.30.0

package/dist/index.d.ts

@@ -16,6 +16,7 @@ import { QueryDescriptor } from '@voltro/database';
 import { QueryProcedureDescriptor } from '@voltro/protocol';
 import { Runtime } from 'effect';
 import { Schema } from 'effect';
+import { SchemaTable } from '@voltro/database';
 import { SemanticCacheShape } from '@voltro/cache';
 import { simulateStreamingMiddleware } from 'ai';
 import { SpeechModelV4 } from '@ai-sdk/provider';
@@ -231,6 +232,8 @@ export declare const agentThreadsTable: Table<typeof AGENT_THREADS_TABLE, Record
 
 export declare const AI_BUDGET_TABLE = "_voltro_ai_budget";
 
+export declare const AI_INFERENCES_TABLE = "_voltro_ai_inferences";
+
 export declare const AI_USAGE_TABLE = "_voltro_ai_usage";
 
 /** Thrown when an AI call would push a tenant over its USD budget. */
@@ -299,6 +302,15 @@ declare const AiError_base: Schema.TaggedErrorClass<AiError, "AiError", {
     message: typeof Schema.String;
 }>;
 
+/**
+ * One offloaded model call.
+ *
+ * The row IS the wait. A run parked on `awaitSignalSuspending` holds nothing;
+ * everything needed to perform the call, resume the right run, and explain the
+ * outcome afterwards is here.
+ */
+export declare const aiInferencesTable: SchemaTable;
+
 /** 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
@@ -653,6 +665,38 @@ export declare interface DataCopilotDeps {
  */
 export declare const dataStoreResumableStreamStore: (store: DataStore) => ResumableStreamStore;
 
+export declare const decideInferenceFailure: (input: {
+    readonly attempts: number;
+    readonly maxAttempts: number;
+    readonly baseDelayMs: number;
+    readonly maxDelayMs: number;
+    /** Milliseconds the provider itself asked us to wait, when it said so. */
+    readonly retryAfterMs?: number | undefined;
+}) => InferenceFailureAction;
+
+/** Attempts before a queued call is reported as failed to its waiting run. */
+export declare const DEFAULT_INFERENCE_ATTEMPTS = 4;
+
+/** How many queued calls one dispatcher performs concurrently.
+ *
+ *  This is the number offloading exists to make explicit: inline, the ceiling
+ *  is "however many runs happen to be waiting". Here it is declared, and it is
+ *  the knob to turn when a provider starts rate-limiting. */
+export declare const DEFAULT_INFERENCE_CONCURRENCY = 4;
+
+/** How long a dispatcher's claim survives with nothing completing it.
+ *
+ *  Generous relative to a model call, for the asymmetry the admission lease
+ *  documents: reclaiming early performs a paid call twice, reclaiming late
+ *  delays one call. */
+export declare const DEFAULT_INFERENCE_LEASE_MS: number;
+
+/** How often the dispatcher looks for work. Fast, because it sits directly in
+ *  the latency of every offloaded call — a suspend/resume round trip already
+ *  costs one engine wake, and there is no reason to add a second of polling on
+ *  top of it. */
+export declare const DEFAULT_INFERENCE_POLL_MS = 250;
+
 declare const DEFAULT_INPUT: Schema.Struct<{
     prompt: typeof Schema.String;
 }>;
@@ -739,6 +783,15 @@ export declare const defineTool: <A, I, O>(def: {
     readonly timeoutMs?: number;
 }) => AnyTool;
 
+/**
+ * One dispatch tick. Never throws.
+ *
+ * A tick that threw would stop every offloaded call in the deployment until
+ * somebody noticed, and every run parked on one would sit there. Failures are
+ * collected and reported.
+ */
+export declare const dispatchInferences: (deps: InferenceDispatchDeps, options?: InferenceDispatchOptions) => Promise<InferenceDispatchResult>;
+
 /**
  * Embed a single string to a vector. Returns the embedding through Effect's
  * success channel; provider failures surface as a typed
@@ -1005,6 +1058,30 @@ export declare interface GenerateImageResult {
 
 export declare const generateObject: <A, I>(options: GenerateObjectOptions<A, I>) => Effect.Effect<GenerateObjectResult<A>, AiError>;
 
+/**
+ * Structured output against an already-rendered JSON Schema, WITHOUT the decode
+ * step.
+ *
+ * Extracted from `generateObject` rather than written beside it: an offloaded
+ * inference is performed by a dispatcher that has the stored JSON Schema and no
+ * access to the caller's Effect Schema (a closure cannot be journaled), and the
+ * awaiting workflow decodes on resume. Two implementations of "ask the model for
+ * JSON matching this shape" would have been two sets of provider-option
+ * handling, fallback behaviour and span attributes.
+ */
+export declare const generateObjectJson: (options: GenerateObjectJsonOptions) => Effect.Effect<GenerateObjectResult<unknown>, AiError>;
+
+export declare interface GenerateObjectJsonOptions {
+    /** A JSON Schema, already rendered. */
+    readonly jsonSchema: Record<string, unknown>;
+    readonly prompt: string;
+    readonly system?: string;
+    readonly provider?: ProviderConfig;
+    readonly fallbacks?: ProviderFallbacks;
+    readonly maxTokens?: number;
+    readonly providerOptions?: AiProviderOptions;
+}
+
 export declare interface GenerateObjectOptions<A, I> {
     /** Effect Schema the model output must satisfy. Converted to JSON
      *  Schema for the SDK, then decoded back through this schema so the
@@ -1245,6 +1322,74 @@ export declare const hashToVector: (text: string, dim: number) => number[];
  */
 export declare const historyToModelMessages: (history: ReadonlyArray<AgentMessage>) => ModelMessage[];
 
+export declare interface InferenceDispatchDeps {
+    readonly store: DataStore;
+    /**
+     * Resume the parked run with the call's outcome.
+     *
+     * MUST be idempotent — completing an already-resolved durable deferred is a
+     * no-op, which is what makes the perform → resume → mark ordering safe.
+     */
+    readonly resume: (input: {
+        readonly executionId: string;
+        readonly workflowName: string;
+        readonly signalName: string;
+        readonly payload: unknown;
+    }) => Promise<void>;
+    /** Runs an `@voltro/ai` Effect. Injected so this module needs no runtime. */
+    readonly run: <A>(effect: Effect.Effect<A, unknown>) => Promise<A>;
+    readonly now?: () => number;
+    readonly replicaId?: string;
+    readonly log?: {
+        readonly info: (message: string, meta?: Record<string, unknown>) => void;
+        readonly warn: (message: string, meta?: Record<string, unknown>) => void;
+    };
+}
+
+export declare interface InferenceDispatchOptions {
+    readonly batch?: number;
+    readonly concurrency?: number;
+    readonly leaseMs?: number;
+    readonly maxAttempts?: number;
+    readonly baseDelayMs?: number;
+    readonly maxDelayMs?: number;
+}
+
+export declare interface InferenceDispatchResult {
+    /** `false` when nothing was claimed AND nothing was waiting — so an empty
+     *  tick and a tick that could not read are never the same report. */
+    readonly examined: boolean;
+    readonly claimed: number;
+    readonly succeeded: number;
+    readonly failed: number;
+    readonly retried: number;
+    readonly reclaimed: number;
+    readonly failures: ReadonlyArray<{
+        readonly id: string;
+        readonly detail: string;
+    }>;
+}
+
+/**
+ * What the dispatcher should do with a call that just failed.
+ *
+ * PURE, and separated for the usual reason: the interesting cases here are
+ * "when do we give up" and "does the waiting run learn about it", and neither
+ * needs a store, a clock or a provider to decide.
+ */
+export declare type InferenceFailureAction = {
+    readonly kind: 'retry';
+    readonly attempts: number;
+    readonly delayMs: number;
+} | {
+    readonly kind: 'give-up';
+    readonly attempts: number;
+};
+
+/** The signal name a parked run awaits for one queued call. Derived from the
+ *  row id, so the run and the dispatcher agree without sharing anything. */
+export declare const inferenceSignalName: (inferenceId: string) => string;
+
 /** Discovery predicate for `*.agent.tsx` exports. */
 export declare const isAgentDescriptor: (x: unknown) => x is AnyAgentDescriptor;
 
@@ -1454,8 +1599,26 @@ export declare const modelPricing: () => Record<string, ModelPrice>;
  */
 export declare const observeStream: (attributes: AiCallAttributes, stream: Stream.Stream<AgentEvent>) => Stream.Stream<AgentEvent>;
 
+/**
+ * The DETERMINISTIC row id for an offloaded call.
+ *
+ * Keyed on the execution + step, not on a generated id, so a replay that
+ * reaches the enqueue before the first attempt's journal entry is durable
+ * cannot queue — and pay for — the same call twice. `insertIgnore` on this id
+ * is what makes the enqueue idempotent.
+ *
+ * Hashed for LENGTH, exactly like `pendingSlotId`: `id()` is VARCHAR(64) on
+ * MySQL/MariaDB and a step name is app-chosen text.
+ */
+export declare const offloadedInferenceId: (executionId: string, stepName: string) => string;
+
 export declare type OpenAIModel = 'gpt-5.5' | 'gpt-4o' | 'gpt-4o-mini' | (string & {});
 
+/** The JSON Schema a `generateObject` output schema renders to. Exported
+ *  because an OFFLOADED inference has to store it: a JavaScript Schema object
+ *  cannot be journaled, and its JSON rendering can. */
+export declare const outputJsonSchema: (schema: Schema.Schema.Any, fn: string) => Effect.Effect<Record<string, unknown>, AiError>;
+
 /** Does this tag pass the allow/deny policy? deny wins; allow (when set) gates. */
 export declare const passesPolicy: (tag: string, policy: AppToolPolicy) => boolean;
 
@@ -1572,6 +1735,26 @@ export declare interface QueryableStore {
     } & Record<string, unknown>): Promise<ReadonlyArray<Record<string, unknown>>>;
 }
 
+/** A queued call in domain shape. */
+export declare interface QueuedInference {
+    readonly id: string;
+    readonly tenantId: string | null;
+    readonly executionId: string;
+    readonly workflowName: string;
+    readonly runId: string | null;
+    readonly signalName: string;
+    readonly stepName: string;
+    readonly kind: 'text' | 'object';
+    readonly provider: string;
+    readonly model: string;
+    readonly prompt: string;
+    readonly system: string | null;
+    readonly maxTokens: number | null;
+    readonly providerOptions: unknown;
+    readonly jsonSchema: Record<string, unknown> | null;
+    readonly attempts: number;
+}
+
 /** A store wrapper that records the dependency set of everything read through
  *  it — the provenance the semantic cache tags entries with. */
 export declare interface ReadRecorder<S extends QueryableStore> {
@@ -2244,6 +2427,8 @@ export declare interface ToolDef<A, I, O> {
  *  a Promise; `buildSdkTools` normalises both. */
 export declare type ToolHandler<A, O> = (input: A, ctx: ToolContext) => Effect.Effect<O, never, unknown> | Promise<O>;
 
+export declare const toQueuedInference: (row: Record<string, unknown>) => QueuedInference;
+
 /**
  * Drop a stream's controller. `streamText` calls this in its finaliser when the
  * stream ends — success, error, cancel, or consumer interrupt. Idempotent.