@voltro/ai 0.74.0 → 0.75.0

package/dist/index.d.ts

@@ -16,6 +16,7 @@ import { LanguageModelV4 } from '@ai-sdk/provider';
 import { LanguageModelV4Source } from '@ai-sdk/provider';
 import { ModelMessage } from 'ai';
 import { PluginMediaPersistCapability } from '@voltro/protocol';
+import { PluginMediaPersistMetadata } from '@voltro/protocol';
 import { QueryDescriptor } from '@voltro/database';
 import { QueryProcedureDescriptor } from '@voltro/protocol';
 import { Runtime } from 'effect';
@@ -28,6 +29,8 @@ import { Stream } from 'effect';
 import { Table } from '@voltro/database';
 import { ToolSet } from 'ai';
 import { TranscriptionModelV4 } from '@ai-sdk/provider';
+import { VoidIfEmpty } from 'effect/Types';
+import { YieldableError } from 'effect/Cause';
 
 /** Count of in-flight streams (diagnostics / leak detection). */
 export declare const activeStreamCount: () => number;
@@ -405,6 +408,29 @@ declare const AiError_base: Schema.TaggedErrorClass<AiError, "AiError", {
     }>>;
 }>;
 
+/**
+ * The one way a CAUGHT provider failure becomes an `AiError`.
+ *
+ * Every call site used to write `new AiError({ message: String(e.message) })`,
+ * which kept the top message and dropped `cause`. For a network failure that
+ * leaves `fetch failed` with nothing under it — no `ECONNREFUSED`, no TLS code —
+ * so the one fact that says what to fix was gone. Two sites were worse and
+ * dropped the provider's message too (`structured provider call failed`).
+ *
+ * Two things carry the cause now, deliberately split by audience:
+ *   - the CODES of the cause chain (`ECONNREFUSED`, `CERT_HAS_EXPIRED`, …) join
+ *     the message. Codes only: a nested message can carry an internal host or
+ *     address, and `message` is a schema field — it is encoded, and it reaches a
+ *     browser whenever a procedure declares `AiError` in its error union;
+ *   - the raw failure stays on the instance as `cause`, NOT enumerable, so a
+ *     server log or `error.cause` has the whole chain and the encoder never
+ *     sees it.
+ */
+export declare const aiGenerationError: (cause: unknown, options?: {
+    readonly prefix?: string;
+    readonly evidence?: AiCallEvidence;
+}) => AiError;
+
 /**
  * One offloaded model call.
  *
@@ -469,6 +495,18 @@ export declare interface AiUsage {
     readonly totalTokens?: number | undefined;
 }
 
+/** The usage ledger could not be written — the call it describes is not booked. */
+export declare class AiUsageLedgerError extends AiUsageLedgerError_base<{
+    readonly receiptKey: string;
+    readonly cause: unknown;
+}> {
+    get message(): string;
+}
+
+declare const AiUsageLedgerError_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
+    readonly _tag: "AiUsageLedgerError";
+} & Readonly<A>;
+
 /**
  * Price a usage tally and write a ledger row. Returns the computed
  * `CostBreakdown` so the caller can surface the cost without a re-query.
@@ -476,6 +514,40 @@ export declare interface AiUsage {
 /** What `recordAiUsage` did with the receipt: wrote it, or found it already written. */
 export declare type AiUsageReceipt = 'recorded' | 'replayed';
 
+/**
+ * A receipt was recorded again with DIFFERENT values than the row already
+ * written under it.
+ *
+ * A replay is the same paid call recorded twice, so its values are the same by
+ * definition. Different values under one receipt mean one of them is wrong — a
+ * second call billed under the first one's identity, or a caller whose receipt
+ * key is not the identity it thinks it is. Before this existed the second
+ * recording answered `replayed` and handed back the values it was GIVEN, so the
+ * caller saw a charge that was never booked and no sign of the disagreement.
+ */
+export declare class AiUsageReceiptConflict extends AiUsageReceiptConflict_base<{
+    readonly receiptKey: string;
+    readonly recorded: AiUsageReceiptFacts;
+    readonly attempted: AiUsageReceiptFacts;
+}> {
+    get message(): string;
+}
+
+declare const AiUsageReceiptConflict_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
+    readonly _tag: "AiUsageReceiptConflict";
+} & Readonly<A>;
+
+/** The facts of one usage row that a replay must agree with. */
+export declare interface AiUsageReceiptFacts {
+    readonly tenantId: string | null;
+    readonly provider: string;
+    readonly model: string;
+    readonly operation: string;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly costMicroUsd: number;
+}
+
 export declare interface AiUsageRecordInput {
     readonly tenantId?: string | null;
     readonly provider: ProviderName | string;
@@ -690,6 +762,9 @@ export declare const buildCopilotSystemPrompt: (schema: CopilotSchema) => string
  *  `execute` tools ignore it. */
 export declare const buildSdkTools: (tools: Record<string, AnyTool>, ctx?: ToolContext) => ToolSet;
 
+/** The names the built-in generators resolve without a registration. */
+export declare const BUILTIN_MEDIA_PROVIDERS: ReadonlyArray<string>;
+
 /** The names `generateSpeech` resolves without a registration. */
 export declare const BUILTIN_SPEECH_PROVIDERS: ReadonlyArray<string>;
 
@@ -725,6 +800,9 @@ export declare const capabilitiesOf: (raw: RawGatewayModel) => ModelCapabilities
 /** Clear the global middleware stack. */
 export declare const clearAiMiddleware: () => void;
 
+/** Test seam: forget every registration. */
+export declare const clearMediaTaskProviders: () => void;
+
 /** Test seam: forget every registration. */
 export declare const clearSpeechProviders: () => void;
 
@@ -1865,6 +1943,10 @@ export declare interface InferenceDispatchOptions {
     readonly maxAttempts?: number;
     readonly baseDelayMs?: number;
     readonly maxDelayMs?: number;
+    /** Between polls of a task-provider media job. Default {@link DEFAULT_MEDIA_TASK_POLL_MS}. */
+    readonly taskPollMs?: number;
+    /** A task still pending this long after submission is failed. Default {@link DEFAULT_MEDIA_TASK_TIMEOUT_MS}. */
+    readonly taskTimeoutMs?: number;
 }
 
 export declare interface InferenceDispatchResult {
@@ -1876,6 +1958,9 @@ export declare interface InferenceDispatchResult {
     readonly failed: number;
     readonly retried: number;
     readonly reclaimed: number;
+    /** Task-provider media jobs asked once and found still pending — released
+     *  back to the queue for a later claim, without a lease held across the job. */
+    readonly polled: number;
     readonly failures: ReadonlyArray<{
         readonly id: string;
         readonly detail: string;
@@ -2245,6 +2330,105 @@ export declare interface McpTransport {
     readonly close: () => Effect.Effect<void>;
 }
 
+/** One artifact a finished task produced — a URL the dispatcher re-hosts, or
+ *  bytes (raw or base64) it stores. Same shape the built-in generators hand
+ *  over, so both paths persist identically. */
+export declare interface MediaTaskArtifact {
+    readonly url?: string;
+    readonly data?: Uint8Array | string;
+    readonly mediaType: string;
+}
+
+/**
+ * The provider's handle for one submitted task.
+ *
+ * Stored on the queue row VERBATIM as JSON and handed back to `poll`, so it
+ * may carry whatever the provider needs to find the task again — a request
+ * id, the endpoint it was submitted to, a region. It must survive
+ * `JSON.stringify`: a handle that does not is refused before it is stored,
+ * because a handle that came back different would poll a task that does not
+ * exist.
+ */
+export declare type MediaTaskHandle = Readonly<Record<string, unknown>>;
+
+export declare interface MediaTaskProvider {
+    /** Submit the job; return the provider's handle as soon as it has one. */
+    readonly submit: (request: MediaTaskSubmitRequest) => Effect.Effect<MediaTaskHandle, AiError>;
+    /** Ask the provider about one handle. Called once per dispatcher claim. */
+    readonly poll: (handle: MediaTaskHandle, request: MediaTaskSubmitRequest) => Effect.Effect<MediaTaskStatus, AiError>;
+    /**
+     * The provider de-duplicates on `idempotencyKey`: a second `submit` with the
+     * same key returns the SAME task's handle rather than starting a second job.
+     *
+     * This closes the one window the handle cannot: a worker lost between the
+     * provider accepting the job and the handle reaching the row. Without this
+     * flag such a row is resumed with `AiOffloadError.outcome === 'unknown'` —
+     * the job may have run and been charged for, and nothing can find it. With
+     * it, the reclaiming worker submits again under the same key, receives the
+     * same handle, and polls it.
+     *
+     * Say it only when the provider guarantees it. A `true` over a provider that
+     * ignores the key turns the lost-worker case into a second paid job — the
+     * exact outcome the `unknown` report exists to avoid.
+     */
+    readonly idempotentSubmit?: boolean;
+}
+
+/** The task provider registered under `name`, or `undefined`. */
+export declare const mediaTaskProvider: (name: string) => MediaTaskProvider | undefined;
+
+export declare type MediaTaskStatus = {
+    readonly status: 'pending';
+    /** How long to wait before asking again, when the provider says. Bounded
+     *  below by the dispatcher's own poll interval. */
+    readonly retryAfterMs?: number;
+} | {
+    readonly status: 'succeeded';
+    readonly artifacts: ReadonlyArray<MediaTaskArtifact>;
+    /** What the task consumed, in the provider's unit — seconds of video,
+     *  characters of text, or tokens. Recorded in the usage ledger under
+     *  the job's row and attempt. */
+    readonly usage?: MediaUsage | MeteredUsage;
+    readonly providerMetadata?: unknown;
+} | {
+    readonly status: 'failed';
+    /** The provider's own message. It is what the parked run is told. */
+    readonly message: string;
+    /**
+     * Whether a fresh submission could succeed. Default `false`: a task the
+     * provider ran and failed is a paid job, and re-submitting it is a second
+     * charge, not a retry. Say `true` for a transient failure the provider
+     * itself names as such (capacity, an upstream outage) — then the job is
+     * re-submitted under the next attempt, with the dispatcher's backoff.
+     */
+    readonly retryable?: boolean;
+};
+
+/**
+ * What the dispatcher hands `submit`.
+ *
+ * `idempotencyKey` is derived from the queue row and the attempt — the same
+ * two things the artifacts are stored under — so it is stable across a lost
+ * worker and different for a deliberate re-submission. Forward it to the
+ * provider when the provider takes one: see `MediaTaskProvider.idempotentSubmit`
+ * for what that buys.
+ */
+export declare interface MediaTaskSubmitRequest {
+    readonly modality: 'image' | 'video' | 'speech';
+    readonly prompt: string;
+    readonly model?: string;
+    /** The job's `params`, as declared on `mediaStep`. */
+    readonly params: Readonly<Record<string, unknown>>;
+    /** URL inputs, as declared on `mediaStep`. Never bytes. */
+    readonly inputs: Readonly<Record<string, unknown>>;
+    readonly providerOptions?: AiProviderOptions;
+    readonly tenantId: string | null;
+    /** `<queue row id>#<attempt>`. */
+    readonly idempotencyKey: string;
+    /** Aborted on Effect interruption; pass to provider I/O. */
+    readonly abortSignal?: AbortSignal;
+}
+
 /** Token tally, mirroring `GenerateTextResult['usage']`. Only `generateImage`
  *  reports one (the speech + video model specs carry no usage), which is why
  *  it's optional on every media result. */
@@ -2739,6 +2923,9 @@ export declare interface QueuedInference {
     readonly transcription: Record<string, unknown> | null;
     /** The media job for a `media` call. */
     readonly media: QueuedMediaJob | null;
+    /** The stored provider handle of a task-provider media job, or `null`. */
+    readonly taskHandle: Record<string, unknown> | null;
+    readonly taskSubmittedAt: Date | null;
     readonly attempts: number;
     readonly fence: number;
 }
@@ -2748,6 +2935,8 @@ export declare interface QueuedMediaJob {
     readonly modality: 'image' | 'video' | 'speech';
     readonly params: Record<string, unknown>;
     readonly inputs: Record<string, unknown>;
+    /** Owner, visibility and tags for the stored artifacts — see `PluginMediaPersistMetadata`. */
+    readonly persist?: PluginMediaPersistMetadata;
 }
 
 /** What a media job resumes its run with: hosted artifacts, never bytes. */
@@ -2818,7 +3007,20 @@ export declare interface ReadRecorder<S extends QueryableStore> {
 
 export declare const recordAiUsage: (store: DataStore, record: AiUsageRecordInput) => Effect.Effect<CostBreakdown & {
     readonly receipt: AiUsageReceipt;
-}>;
+}, AiUsageReceiptConflict | AiUsageLedgerError>;
+
+/**
+ * `recordAiUsage` for a call that has ALREADY been paid for, where failing the
+ * caller would lose a finished answer over a ledger row. Never fails — and never
+ * silent: a ledger failure or a receipt conflict is logged at error level with
+ * everything needed to reconcile it by hand.
+ *
+ * The framework's three callers each swallowed the failure outright
+ * (`.catch(() => {})`, `catchAllCause(() => Effect.void)` twice). "Do not fail
+ * the call" was right; "leave no trace" was not — an unbooked charge that
+ * nothing reports is found only when the invoice disagrees with the ledger.
+ */
+export declare const recordAiUsageBestEffort: (store: DataStore, record: AiUsageRecordInput) => Effect.Effect<void>;
 
 /**
  * Register a prompt version, idempotently, and return it.
@@ -2876,6 +3078,18 @@ export declare const redisResumableStreamStore: (redis: ResumableRedis, opts?: {
  */
 export declare const refreshMcpToolset: (server: McpServer, policy: McpToolPolicy) => Effect.Effect<McpToolset, McpError>;
 
+/**
+ * The provider config `mediaStep` accepts for a registered task provider —
+ * named, not enumerated, exactly like `RegisteredSpeechConfig`.
+ */
+export declare interface RegisteredMediaTaskConfig {
+    readonly name: string;
+    readonly model?: string;
+}
+
+/** Every registered name. */
+export declare const registeredMediaTaskProviders: () => ReadonlyArray<string>;
+
 /**
  * Synthesize speech audio from text. Returns the audio bytes + media type and
  * provider metadata; provider failures surface as `AiError`.
@@ -2898,6 +3112,29 @@ export declare interface RegisteredSpeechConfig {
 /** Every registered name — what a picker asks for. */
 export declare const registeredSpeechProviders: () => ReadonlyArray<string>;
 
+/**
+ * Register an external-task media provider under a name.
+ *
+ * The name then works in `mediaStep({ provider: { name, model } })`: the
+ * dispatcher submits through the provider, keeps the handle on the queue row,
+ * polls it once per claim, and resumes the run with the hosted artifacts.
+ * Taking over a built-in name needs `{ replaceBuiltin: true }`.
+ */
+export declare const registerMediaTaskProvider: (name: string, provider: MediaTaskProvider, options?: RegisterMediaTaskProviderOptions) => void;
+
+export declare interface RegisterMediaTaskProviderOptions {
+    /**
+     * Take over a BUILT-IN name (`openai`, `gateway`, `anthropic`, `mock`).
+     *
+     * A registration under a built-in name routes every `mediaStep` that names
+     * it through the task contract instead of the generator. Refused unless the
+     * intent is in the call, for the reason the speech registry gives: a silent
+     * shadow makes the same config mean different things depending on which
+     * module loaded first.
+     */
+    readonly replaceBuiltin?: boolean;
+}
+
 /**
  * Register a speech provider under a name.
  *