@voltro/ai 0.71.1 → 0.72.0

package/dist/index.d.ts

@@ -15,6 +15,7 @@ import { LanguageModelMiddleware } from 'ai';
 import { LanguageModelV4 } from '@ai-sdk/provider';
 import { LanguageModelV4Source } from '@ai-sdk/provider';
 import { ModelMessage } from 'ai';
+import { PluginMediaPersistCapability } from '@voltro/protocol';
 import { QueryDescriptor } from '@voltro/database';
 import { QueryProcedureDescriptor } from '@voltro/protocol';
 import { Runtime } from 'effect';
@@ -468,6 +469,13 @@ export declare interface AiUsage {
     readonly totalTokens?: number | undefined;
 }
 
+/**
+ * Price a usage tally and write a ledger row. Returns the computed
+ * `CostBreakdown` so the caller can surface the cost without a re-query.
+ */
+/** What `recordAiUsage` did with the receipt: wrote it, or found it already written. */
+export declare type AiUsageReceipt = 'recorded' | 'replayed';
+
 export declare interface AiUsageRecordInput {
     readonly tenantId?: string | null;
     readonly provider: ProviderName | string;
@@ -488,6 +496,14 @@ export declare interface AiUsageRecordInput {
     readonly prompt?: PromptStamp;
     /** Override the timestamp (tests; default `new Date()`). */
     readonly calledAt?: Date;
+    /** The request this call belongs to (a queued inference id, a message id, a
+     *  workflow step's request id) and which attempt of it. Together they name
+     *  the receipt, so a replayed recording writes one row. */
+    readonly requestId?: string;
+    readonly attempt?: number;
+    /** The receipt's idempotency key outright, when the caller has one that is
+     *  not `requestId#attempt`. */
+    readonly receiptKey?: string;
 }
 
 /**
@@ -1443,6 +1459,10 @@ export declare interface GenerateImageOptions {
     readonly aspectRatio?: `${number}:${number}`;
     /** Provider-specific options forwarded to the SDK. */
     readonly providerOptions?: AiProviderOptions;
+    /** Retries of a failed provider call (the SDK's default is 2). A charged call
+     *  that fails with a retryable status is paid again on every retry — set 0
+     *  where the caller retries on its own terms. */
+    readonly maxRetries?: number;
 }
 
 export declare interface GenerateImageResult {
@@ -1542,6 +1562,8 @@ export declare interface GenerateObjectWithToolsOptions<A, I> {
     readonly prompt: string;
     readonly system?: string;
     readonly provider?: ProviderConfig;
+    /** Abort the turn — the provider call and every tool, through one signal. */
+    readonly abortSignal?: AbortSignal;
     /** Ordered provider/model fallback chain — see {@link ProviderFallbacks}. */
     readonly fallbacks?: ProviderFallbacks;
     readonly maxTokens?: number;
@@ -1620,6 +1642,10 @@ export declare interface GenerateTextOptions {
     readonly maxSteps?: number;
     /** Request context threaded into the tool executors. */
     readonly toolContext?: ToolContext;
+    /** Abort the turn: the provider call is interrupted AND every tool sees the
+     *  same signal (`ctx.abortSignal`), so a tool call the model emitted just
+     *  before the abort does not run after it. */
+    readonly abortSignal?: AbortSignal;
     /** The user prompt. The SDK auto-wraps it as the single user message. */
     readonly prompt?: string;
     /** Complete conversation, including the latest user message. Supply instead of prompt. */
@@ -1702,7 +1728,8 @@ export declare interface GenerateVideoOptions {
 }
 
 export declare interface GenerateVideoParams {
-    readonly aspectRatio?: `${number}:${number}`;
+    /** `{width}:{height}`, or `adaptive` where the model derives it from the reference input. */
+    readonly aspectRatio?: `${number}:${number}` | 'adaptive';
     readonly durationSeconds?: number;
     readonly resolution?: `${number}x${number}`;
     readonly fps?: number;
@@ -1802,6 +1829,13 @@ export declare interface InferenceDispatchDeps {
         bytes: Uint8Array;
         mediaType: string;
     }>;
+    /**
+     * Persist a media artifact a provider produced — the storage plugin's
+     * `mediaPersist` capability, handed over by the host. Required for a `media`
+     * job; a queued media job with no persistence is failed with the reason,
+     * never resumed with bytes in the payload.
+     */
+    readonly persistMedia?: PluginMediaPersistCapability;
     /**
      * Resume the parked run with the call's outcome.
      *
@@ -2689,7 +2723,7 @@ export declare interface QueuedInference {
     readonly runId: string | null;
     readonly signalName: string;
     readonly stepName: string;
-    readonly kind: 'text' | 'object' | 'transcription';
+    readonly kind: 'text' | 'object' | 'transcription' | 'media';
     readonly provider: string;
     readonly model: string;
     readonly prompt: string;
@@ -2703,7 +2737,28 @@ export declare interface QueuedInference {
     readonly jsonSchema: Record<string, unknown> | null;
     /** The source + options for a `transcription` call. */
     readonly transcription: Record<string, unknown> | null;
+    /** The media job for a `media` call. */
+    readonly media: QueuedMediaJob | null;
     readonly attempts: number;
+    readonly fence: number;
+}
+
+/** What a `media` row carries. Inputs are URLs; bytes never enter the queue. */
+export declare interface QueuedMediaJob {
+    readonly modality: 'image' | 'video' | 'speech';
+    readonly params: Record<string, unknown>;
+    readonly inputs: Record<string, unknown>;
+}
+
+/** What a media job resumes its run with: hosted artifacts, never bytes. */
+export declare interface QueuedMediaResult {
+    readonly artifacts: ReadonlyArray<{
+        readonly url: string;
+        readonly refId: string | null;
+        readonly mediaType: string;
+    }>;
+    readonly usage: unknown;
+    readonly providerMetadata: unknown;
 }
 
 /** One entry of the raw `/v1/models` response, every field optional — the
@@ -2761,11 +2816,9 @@ export declare interface ReadRecorder<S extends QueryableStore> {
     reset(): void;
 }
 
-/**
- * Price a usage tally and write a ledger row. Returns the computed
- * `CostBreakdown` so the caller can surface the cost without a re-query.
- */
-export declare const recordAiUsage: (store: DataStore, record: AiUsageRecordInput) => Effect.Effect<CostBreakdown>;
+export declare const recordAiUsage: (store: DataStore, record: AiUsageRecordInput) => Effect.Effect<CostBreakdown & {
+    readonly receipt: AiUsageReceipt;
+}>;
 
 /**
  * Register a prompt version, idempotently, and return it.