@voltro/ai 0.74.0 → 0.76.0

package/dist/index.d.ts

@@ -5,6 +5,8 @@ import { DataStore } from '@voltro/database';
 import { defaultSettingsMiddleware } from 'ai';
 import { Effect } from 'effect';
 import { EmbeddingModelV4 } from '@ai-sdk/provider';
+import { Experimental_RealtimeModelV4 } from '@ai-sdk/provider';
+import { Experimental_RealtimeModelV4SessionConfig } from '@ai-sdk/provider';
 import { Experimental_VideoModelV4 } from '@ai-sdk/provider';
 import { Experimental_VideoModelV4File } from '@ai-sdk/provider';
 import { extractReasoningMiddleware } from 'ai';
@@ -16,6 +18,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';
@@ -25,9 +28,13 @@ import { SemanticCacheShape } from '@voltro/cache';
 import { simulateStreamingMiddleware } from 'ai';
 import { SpeechModelV4 } from '@ai-sdk/provider';
 import { Stream } from 'effect';
+import { Subject } from '@voltro/protocol';
 import { Table } from '@voltro/database';
 import { ToolSet } from 'ai';
 import { TranscriptionModelV4 } from '@ai-sdk/provider';
+import { VoidIfEmpty } from 'effect/Types';
+import { WebSocketGatewayRoute } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
 
 /** Count of in-flight streams (diagnostics / leak detection). */
 export declare const activeStreamCount: () => number;
@@ -302,6 +309,8 @@ export declare const AI_INFERENCES_TABLE = "_voltro_ai_inferences";
 
 export declare const AI_USAGE_TABLE = "_voltro_ai_usage";
 
+export declare type AiBudgetError = AiBudgetExceeded | AiBudgetInvalidInput | AiBudgetReservationConflict;
+
 /** A refused reservation, not evidence of a provider charge. */
 export declare class AiBudgetExceeded extends AiBudgetExceeded_base {
 }
@@ -315,6 +324,17 @@ declare const AiBudgetExceeded_base: Schema.TaggedErrorClass<AiBudgetExceeded, "
     attemptedUsd: typeof Schema.Number;
 }>;
 
+/** Invalid caller configuration, without echoing the supplied value. */
+export declare class AiBudgetInvalidInput extends AiBudgetInvalidInput_base {
+}
+
+declare const AiBudgetInvalidInput_base: Schema.TaggedErrorClass<AiBudgetInvalidInput, "AiBudgetInvalidInput", {
+    readonly _tag: Schema.tag<"AiBudgetInvalidInput">;
+} & {
+    field: Schema.Literal<["limitUsd", "addUsd", "since", "reservationId", "tenantId"]>;
+    message: typeof Schema.String;
+}>;
+
 export declare interface AiBudgetReservation {
     readonly reservationId: string;
     readonly tenantId: string | null;
@@ -322,6 +342,17 @@ export declare interface AiBudgetReservation {
     readonly status: 'reserved' | 'replayed';
 }
 
+/** A durable reservation identity cannot be rebound or spent after release. */
+export declare class AiBudgetReservationConflict extends AiBudgetReservationConflict_base {
+}
+
+declare const AiBudgetReservationConflict_base: Schema.TaggedErrorClass<AiBudgetReservationConflict, "AiBudgetReservationConflict", {
+    readonly _tag: Schema.tag<"AiBudgetReservationConflict">;
+} & {
+    reason: Schema.Literal<["identity-bound", "already-released"]>;
+    message: typeof Schema.String;
+}>;
+
 /** Receipt and release tombstone. A receipt and its counter change commit together. */
 export declare const aiBudgetReservationsTable: Table<typeof AI_BUDGET_RESERVATIONS_TABLE, Record<string, ColumnDefinition<unknown>>, true>;
 
@@ -405,6 +436,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 +523,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 +542,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 +790,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 +828,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;
 
@@ -1068,6 +1174,14 @@ export declare interface DefineEvalInput {
  */
 export declare const definePrompt: (definition: PromptDefinition) => DefinedPrompt;
 
+/**
+ * Declare an authenticated, server-owned voice/text relay as a *.ws.ts route.
+ * This uses the gateway listener, not the physical RPC subscription socket.
+ * Credentials, provider configuration and raw provider events stay server-side.
+ * No reconnection or replay is attempted: a new connection is a new paid session.
+ */
+export declare const defineRealtimeSession: (options: RealtimeSessionOptions) => WebSocketGatewayRoute;
+
 export declare const defineTool: <A, I, O>(def: {
     readonly name: string;
     readonly description: string;
@@ -1865,6 +1979,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 +1994,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 +2366,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. */
@@ -2425,7 +2645,7 @@ export declare interface ModelDataPolicy {
     readonly noTraining: PolicyCoverage;
 }
 
-export declare type ModelModality = 'language' | 'embedding' | 'image' | 'video' | 'realtime' | 'reranking' | 'speech' | 'transcription' | 'unknown';
+export declare type ModelModality = 'language' | 'embedding' | 'image' | 'video' | 'realtime' | 'reranking' | 'speech' | 'transcription' | 'evaluation' | 'unknown';
 
 export declare interface ModelPrice {
     /** USD per 1,000,000 input (prompt) tokens. */
@@ -2739,6 +2959,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 +2971,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. */
@@ -2816,9 +3041,122 @@ export declare interface ReadRecorder<S extends QueryableStore> {
     reset(): void;
 }
 
+/** Browser-safe input allowlist. Session configuration and provider credentials
+ * belong to the server, never to events received from the browser. */
+export declare const RealtimeClientEvent: Schema.Union<[Schema.Struct<{
+    type: Schema.Literal<["input-audio-append"]>;
+    audio: Schema.filter<typeof Schema.String>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["input-audio-commit", "input-audio-clear", "response-create", "response-cancel"]>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["conversation-item-create"]>;
+    item: Schema.Struct<{
+        type: Schema.Literal<["text-message"]>;
+        role: Schema.Literal<["user"]>;
+        text: typeof Schema.String;
+    }>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["conversation-item-truncate"]>;
+    itemId: typeof Schema.String;
+    contentIndex: Schema.filter<Schema.filter<Schema.filter<typeof Schema.Number>>>;
+    audioEndMs: Schema.filter<Schema.filter<typeof Schema.Number>>;
+}>]>;
+
+export declare type RealtimeClientEvent = typeof RealtimeClientEvent.Type;
+
+/** Safe, normalized server events. No raw provider payload, client secret,
+ * arbitrary conversation item or provider error message crosses this surface. */
+export declare const RealtimeServerEvent: Schema.Union<[Schema.Struct<{
+    type: Schema.Literal<["ready"]>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["session-created"]>;
+    sessionId: Schema.optional<typeof Schema.String>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["session-updated"]>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["speech-started", "speech-stopped"]>;
+    itemId: Schema.optional<typeof Schema.String>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["audio-committed"]>;
+    itemId: Schema.optional<typeof Schema.String>;
+    previousItemId: Schema.optional<typeof Schema.String>;
+}>, Schema.Struct<{
+    itemId: typeof Schema.String;
+    type: Schema.Literal<["conversation-item-added"]>;
+}>, Schema.Struct<{
+    transcript: typeof Schema.String;
+    itemId: typeof Schema.String;
+    type: Schema.Literal<["input-transcription-completed"]>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["response-created"]>;
+    responseId: typeof Schema.String;
+}>, Schema.Struct<{
+    type: Schema.Literal<["response-done"]>;
+    responseId: typeof Schema.String;
+    status: typeof Schema.String;
+}>, Schema.Struct<{
+    itemId: typeof Schema.String;
+    responseId: typeof Schema.String;
+    type: Schema.Literal<["output-item-added", "output-item-done", "content-part-added", "content-part-done", "audio-done"]>;
+}>, Schema.Struct<{
+    delta: Schema.filter<typeof Schema.String>;
+    itemId: typeof Schema.String;
+    responseId: typeof Schema.String;
+    type: Schema.Literal<["audio-delta"]>;
+}>, Schema.Struct<{
+    delta: typeof Schema.String;
+    itemId: typeof Schema.String;
+    responseId: typeof Schema.String;
+    type: Schema.Literal<["text-delta", "audio-transcript-delta"]>;
+}>, Schema.Struct<{
+    text: Schema.optional<typeof Schema.String>;
+    itemId: typeof Schema.String;
+    responseId: typeof Schema.String;
+    type: Schema.Literal<["text-done"]>;
+}>, Schema.Struct<{
+    transcript: Schema.optional<typeof Schema.String>;
+    itemId: typeof Schema.String;
+    responseId: typeof Schema.String;
+    type: Schema.Literal<["audio-transcript-done"]>;
+}>]>;
+
+export declare type RealtimeServerEvent = typeof RealtimeServerEvent.Type;
+
+export declare interface RealtimeSessionOptions {
+    readonly path: `/${string}`;
+    readonly model: Experimental_RealtimeModelV4;
+    /** Runs before minting/opening. Authentication alone does not authorize AI spend. */
+    readonly authorize: (subject: Subject, model: {
+        readonly provider: string;
+        readonly modelId: string;
+    }) => Effect.Effect<boolean, unknown>;
+    /** Server-owned configuration. Tool execution is not supported by this relay. */
+    readonly sessionConfig: Omit<Experimental_RealtimeModelV4SessionConfig, 'tools'>;
+    readonly limits?: {
+        readonly maxMessageBytes?: number;
+        readonly maxPendingBytes?: number;
+        readonly maxPendingMessages?: number;
+        readonly setupTimeoutMs?: number;
+        readonly maxDurationMs?: number;
+    };
+}
+
 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 +3214,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 +3248,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.
  *
@@ -2942,7 +3315,7 @@ export declare const registerStream: (streamId: string) => AbortController;
 export declare const releaseAiBudget: (store: DataStore, opts: {
     readonly reservationId: string;
     readonly tenantId: string | null;
-}) => Effect.Effect<"released" | "already-released" | "not-found">;
+}) => Effect.Effect<"released" | "already-released" | "not-found", AiBudgetInvalidInput>;
 
 export declare const releasedAtOf: (raw: RawGatewayModel) => string | undefined;
 
@@ -2962,7 +3335,8 @@ export declare interface RenderedPrompt extends PromptStamp {
 export declare const replacesBuiltinSpeechProvider: (name: string) => boolean;
 
 /** Reserve before provider I/O. Reuse reservationId only for the same logical
- * spend, tenant, amount and window. Zero is check-only and returns null.
+ * spend, tenant, amount and window. Zero checks for strictly positive headroom
+ * and returns null; it never creates a free reservation.
  * Call outside another transaction; the receipt and counter need one commit.
  * A provider failure does not automatically release possibly billed spend. */
 export declare const requireAiBudget: (store: DataStore, opts: {
@@ -2971,7 +3345,7 @@ export declare const requireAiBudget: (store: DataStore, opts: {
     readonly addUsd?: number;
     readonly since?: Date;
     readonly reservationId?: string;
-}) => Effect.Effect<AiBudgetReservation | null, AiBudgetExceeded>;
+}) => Effect.Effect<AiBudgetReservation | null, AiBudgetError>;
 
 /**
  * Rerank `documents` by relevance to `query`, highest score first. Returns
@@ -3037,6 +3411,9 @@ export declare const resolveMcpBounds: (overrides: Partial<McpBounds> | undefine
 
 export declare const resolveModel: (config: ProviderConfig, middleware?: AiMiddleware | ReadonlyArray<AiMiddleware>) => LanguageModelV4;
 
+/** Resolve supported server-owned provider configuration to the SDK codec. */
+export declare const resolveRealtimeModel: (config: ProviderConfig) => Experimental_RealtimeModelV4;
+
 export declare const resolveSpeechModel: (config: ProviderConfig) => SpeechModelV4;
 
 /** Resolve the system prompt for a given decoded input. */
@@ -3678,6 +4055,20 @@ export declare const streamTextWithFallback: (options: StreamTextOptions) => Str
  */
 export declare const streamTextWithRetry: (options: StreamTextOptions, retry?: StreamRetryOptions) => Stream.Stream<AgentEvent>;
 
+/** Live partial transcription, not container decoding or a durable workflow journal.
+ * No automatic retry: replaying audio can duplicate transcript segments and charges.
+ * Raw provider chunks, headers and private metadata are never emitted. */
+export declare const streamTranscribe: (options: StreamTranscribeOptions) => Stream.Stream<TranscriptionStreamEvent, TranscriptionStreamError>;
+
+export declare interface StreamTranscribeOptions {
+    /** Single-use raw audio source. Scope interruption cancels it and the provider. */
+    readonly audio: ReadableStream<Uint8Array>;
+    readonly inputAudioFormat: TranscriptionAudioFormat;
+    readonly provider?: ProviderConfig;
+    readonly providerOptions?: AiProviderOptions;
+    readonly signal?: AbortSignal;
+}
+
 /** A synthesized tool's metadata (the discovery/inventory view). */
 export declare interface SynthesizedTool {
     readonly name: string;
@@ -3738,7 +4129,7 @@ export declare interface ToolContext {
     readonly runtime?: Runtime.Runtime<unknown>;
     /** SDK tool-call identity for this execution, not a durable application idempotency key. */
     readonly invocationId?: string;
-    /** The SDK's cancellation signal; Promise handlers must pass it to their I/O. */
+    /** Cancellation from either the caller's turn or SDK invocation; Promise handlers must pass it to their I/O. */
     readonly abortSignal?: AbortSignal;
 }
 
@@ -3818,6 +4209,13 @@ export declare interface TranscribeOptions {
     readonly providerOptions?: AiProviderOptions;
 }
 
+/** Raw audio only. Container files must be decoded before entering this stream. */
+export declare interface TranscriptionAudioFormat {
+    readonly type: 'audio/pcm' | 'audio/pcmu' | 'audio/pcma';
+    /** Required for PCM; other formats may declare their provider-supported rate. */
+    readonly rate?: number;
+}
+
 export declare interface TranscriptionResult {
     readonly text: string;
     readonly language?: string;
@@ -3868,6 +4266,50 @@ export declare type TranscriptionSource =
     readonly mediaType: string;
 };
 
+/** Browser-safe error contract for a declared transcription stream. */
+export declare class TranscriptionStreamError extends TranscriptionStreamError_base {
+}
+
+declare const TranscriptionStreamError_base: Schema.TaggedErrorClass<TranscriptionStreamError, "TranscriptionStreamError", {
+    readonly _tag: Schema.tag<"TranscriptionStreamError">;
+} & {
+    reason: Schema.Literal<["input", "unsupported", "provider", "cancelled"]>;
+    message: typeof Schema.String;
+}>;
+
+/** Partial text is replaceable, delta text is append-only, and final text seals a segment. */
+export declare const TranscriptionStreamEvent: Schema.Union<[Schema.Struct<{
+    delta: typeof Schema.String;
+    id: Schema.optional<typeof Schema.String>;
+    type: Schema.Literal<["transcript-delta"]>;
+}>, Schema.Struct<{
+    text: typeof Schema.String;
+    startSecond: Schema.optional<typeof Schema.Number>;
+    durationInSeconds: Schema.optional<typeof Schema.Number>;
+    channelIndex: Schema.optional<typeof Schema.Number>;
+    id: Schema.optional<typeof Schema.String>;
+    type: Schema.Literal<["transcript-partial"]>;
+}>, Schema.Struct<{
+    text: typeof Schema.String;
+    startSecond: Schema.optional<typeof Schema.Number>;
+    endSecond: Schema.optional<typeof Schema.Number>;
+    channelIndex: Schema.optional<typeof Schema.Number>;
+    id: Schema.optional<typeof Schema.String>;
+    type: Schema.Literal<["transcript-final"]>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["finish"]>;
+    text: typeof Schema.String;
+    segments: Schema.Array$<Schema.Struct<{
+        text: typeof Schema.String;
+        start: typeof Schema.Number;
+        end: typeof Schema.Number;
+    }>>;
+    language: Schema.optional<typeof Schema.String>;
+    durationSec: Schema.optional<typeof Schema.Number>;
+}>]>;
+
+export declare type TranscriptionStreamEvent = typeof TranscriptionStreamEvent.Type;
+
 /** How much timestamp detail to ask for. Providers charge for it. */
 export declare type TranscriptionTimestamps = 'none' | 'segment' | 'word';