@voltro/ai 0.56.0 → 0.58.0

package/dist/index.d.ts

@@ -23,6 +23,7 @@ import { SpeechModelV4 } from '@ai-sdk/provider';
 import { Stream } from 'effect';
 import { Table } from '@voltro/database';
 import { ToolSet } from 'ai';
+import { TranscriptionModelV4 } from '@ai-sdk/provider';
 
 /** Count of in-flight streams (diagnostics / leak detection). */
 export declare const activeStreamCount: () => number;
@@ -580,9 +581,33 @@ export declare const buildSdkTools: (tools: Record<string, AnyTool>, ctx?: ToolC
  */
 export declare const cancelStream: (streamId: string) => boolean;
 
+/**
+ * Can this runtime run this model?
+ *
+ * The finer form, for the common case of filtering a catalog. It answers about
+ * the MODALITY — whether the framework has a primitive at all — and not about
+ * whether a particular model is healthy, in the caller's region, or affordable.
+ * Those are different questions with different answers and different owners.
+ */
+export declare const canExecute: (model: Pick<GatewayModelInfo, "modality">) => boolean;
+
+/**
+ * Union the three overlapping fields into one answer per capability.
+ *
+ * Each source is half-right on its own: `tags` is editorial and lags, and
+ * `supported_parameters` / `modalities` are mechanical and sometimes omit what
+ * the model plainly does. Taking either alone produces false negatives — and a
+ * false "cannot" is worse than a false "can" here, because it removes a model
+ * from a picker with no way for the user to discover why.
+ */
+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 clearSpeechProviders: () => void;
+
 export declare interface ConsumeOptions {
     /** Replay events with `seq` strictly greater than this (default 0 = from the
      *  start). A reconnecting client passes the last `seq` it rendered. */
@@ -603,6 +628,8 @@ export declare interface ConsumeOptions {
  */
 export declare const consumeResumableStream: (streamId: string, store: ResumableStreamStore, opts?: ConsumeOptions) => Stream.Stream<SeqEvent>;
 
+export declare const contextWindowOf: (raw: RawGatewayModel) => number | undefined;
+
 /** Hard cap on rows — a copilot query never returns an unbounded set. */
 export declare const COPILOT_MAX_LIMIT = 200;
 
@@ -727,6 +754,8 @@ export declare interface DataCopilotDeps {
     }) => Promise<CopilotProposal>;
 }
 
+export declare const dataPolicyOf: (raw: RawGatewayModel) => ModelDataPolicy;
+
 /**
  * Durable, multi-node resumable-stream store backed by the framework's own
  * `DataStore` — works on every dialect the framework supports. The producer
@@ -734,11 +763,24 @@ export declare interface DataCopilotDeps {
  * `streamId`, comparing the returned row's id to ours: we inserted ⇒ we won.
  * That is the same at-most-once arbiter `_voltro_idempotency` uses.
  *
- * The two tables (`streamEventsTable`, `streamStateTable`) register into the
- * app's migration set like the agent/usage tables — add them to the database
- * barrel (or they ride along with a `*.agent.tsx` app). Building this store
- * BOUNDS them (see `registerStreamLogRetention`); `gcResumableStreams` remains
- * for a tighter, done-aware collection an app can run on its own schedule.
+ * The two tables (`streamEventsTable`, `streamStateTable`) are created for you:
+ * the framework's table assembly adds them for any app that DEPENDS on
+ * `@voltro/ai`, so `voltro dev` / `voltro db apply` / `voltro migrate` all plan
+ * them. Nothing to add anywhere.
+ *
+ * This sentence used to say the opposite — "add them to the database barrel (or
+ * they ride along with a `*.agent.tsx` app)" — and both halves were wrong.
+ * Discovery is FILE-based (`*.entity.ts`), so a re-export from a barrel changes
+ * no plan; and this store is an ordinary call reachable from an action, so an
+ * agent file is not the gate either. The tables were simply missing from the
+ * assembly. What that cost is worth stating, because it is the failure shape of
+ * every "the app adds it" contract: `voltro db plan` answered *schema is up to
+ * date* while two tables the feature cannot run without were absent, and the
+ * first user's turn died inside the store instead of at boot.
+ *
+ * Building this store BOUNDS them (see `registerStreamLogRetention`);
+ * `gcResumableStreams` remains for a tighter, done-aware collection an app can
+ * run on its own schedule.
  */
 export declare const dataStoreResumableStreamStore: (store: DataStore) => ResumableStreamStore;
 
@@ -1089,6 +1131,15 @@ export declare interface EvalReport {
 /** Run every assertion against one output; return only the failures. Pure. */
 export declare const evaluateAssertions: (out: EvalReplayOutput, assertions: ReadonlyArray<EvalAssertion>) => ReadonlyArray<AssertionFailure>;
 
+/**
+ * The modalities this build can execute.
+ *
+ * A model whose modality is not in here must not be offered: selecting it
+ * produces a control that cannot run. When a primitive ships, the set grows and
+ * an app that asked this question needs no change — which is the point.
+ */
+export declare const executableModalities: () => ReadonlySet<ModelModality>;
+
 declare const EXECUTOR_BRAND: "@voltro/ai/AgentExecutor";
 
 /** The `exposeAsTool` annotation shape (mirrors @voltro/protocol's, structural
@@ -1111,6 +1162,9 @@ export { extractReasoningMiddleware }
  */
 export declare const flattenMcpContent: (result: Record<string, unknown>, maxBytes: number) => string;
 
+/** One raw entry → the shape callers read. Exported for the parser's tests. */
+export declare const fromRaw: (raw: RawGatewayModel) => GatewayModelInfo;
+
 /**
  * Pull the ACTUAL per-call cost (USD) out of an AI-SDK result's provider
  * metadata, when the Vercel AI Gateway reported it. The gateway attaches
@@ -1142,6 +1196,29 @@ export declare interface GatewayModelInfo {
         readonly outputPer1M: number;
         readonly cachedInputPer1M?: number;
     };
+    /** What the model can do, unioned from `tags`, `supported_parameters` and
+     *  `modalities` — the three fields that each half-say it and regularly
+     *  disagree. */
+    readonly capabilities?: ModelCapabilities;
+    /** What it accepts and produces, verbatim from the response. */
+    readonly modalities?: {
+        readonly input: ReadonlyArray<string>;
+        readonly output: ReadonlyArray<string>;
+    };
+    readonly contextWindow?: number;
+    readonly maxOutputTokens?: number;
+    /** ISO 8601. The wire carries UNIX seconds; see `gatewayCatalog.ts` for why
+     *  that is converted here rather than passed along. */
+    readonly releasedAt?: string;
+    readonly knowledgeCutoff?: string;
+    /**
+     * Whether the provider retains or trains on what is sent.
+     *
+     * It decides whether a model may see customer text, and it was the clearest
+     * casualty of reading the provider type: a field the framework does not pass
+     * through is a decision nobody makes.
+     */
+    readonly dataPolicy?: ModelDataPolicy;
 }
 
 /**
@@ -1309,10 +1386,6 @@ export declare interface GenerateObjectWithToolsOptions<A, I> {
     readonly toolContext?: ToolContext;
 }
 
-/**
- * Synthesize speech audio from text. Returns the audio bytes + media type and
- * provider metadata; provider failures surface as `AiError`.
- */
 export declare const generateSpeech: (options: GenerateSpeechOptions) => Effect.Effect<GenerateSpeechResult, AiError>;
 
 export declare interface GenerateSpeechOptions {
@@ -1320,7 +1393,7 @@ export declare interface GenerateSpeechOptions {
     readonly text: string;
     /** Override the provider/model (defaults to `providerFromEnv()`). `anthropic`
      *  has no speech model; use `openai` or `gateway`. */
-    readonly provider?: ProviderConfig;
+    readonly provider?: ProviderConfig | RegisteredSpeechConfig;
     /** Provider voice id. */
     readonly voice?: string;
     /** Desired audio container, e.g. `'mp3'` / `'wav'`. */
@@ -1504,6 +1577,18 @@ export declare interface HttpMcpTransportOptions {
 
 export declare interface InferenceDispatchDeps {
     readonly store: DataStore;
+    /**
+     * Resolve a transcription `storageRef` to bytes.
+     *
+     * Injected here for the same reason `transcribe` injects it: this package must
+     * not learn about buckets, and the read carries the app's tenancy and signing.
+     * Required only when an offloaded transcription used a ref — a queued call
+     * with a `url` or inline bytes needs nothing.
+     */
+    readonly resolveTranscriptionRef?: (ref: string) => Promise<{
+        bytes: Uint8Array;
+        mediaType: string;
+    }>;
     /**
      * Resume the parked run with the call's outcome.
      *
@@ -1610,6 +1695,8 @@ export declare interface JudgeVerdict {
     readonly reason: string;
 }
 
+export declare const knowledgeCutoffOf: (raw: RawGatewayModel) => string | undefined;
+
 /**
  * The real LLM judge: asks the model for a structured `{ pass, score, reason }`
  * verdict via `generateObject` (schema-constrained, so a malformed grade surfaces
@@ -1643,6 +1730,8 @@ export declare const loggingMiddleware: (opts?: {
  */
 export declare const makeMcpTool: (server: McpServer, tool: McpToolInfo, policy: McpToolPolicy, bounds: McpBounds) => AnyTool;
 
+export declare const maxOutputTokensOf: (raw: RawGatewayModel) => number | undefined;
+
 export declare const MCP_BOUNDS_DEFAULTS: McpBounds;
 
 /** Identity this client reports in `initialize`. No version literal here — the
@@ -2014,6 +2103,20 @@ export declare interface MockTurn {
     };
 }
 
+export declare const modalitiesOf: (raw: RawGatewayModel) => {
+    readonly input: ReadonlyArray<string>;
+    readonly output: ReadonlyArray<string>;
+};
+
+/**
+ * The primitive that makes each modality runnable — the reason the entry is
+ * here, written down so a reader can check it rather than trust it.
+ */
+export declare const MODALITY_PRIMITIVE: Readonly<Partial<Record<ModelModality, string>>>;
+
+/** `model_type` on the wire; the same union `ModelModality` names. */
+export declare const modalityOf: (raw: RawGatewayModel) => ModelModality;
+
 /**
  * Built-in published list prices (USD per 1M tokens) for the major providers.
  *
@@ -2038,6 +2141,29 @@ export declare interface MockTurn {
  */
 export declare const MODEL_PRICING_DEFAULTS: Record<string, ModelPrice>;
 
+/** What a model can do, unioned from the three fields that each half-say it. */
+export declare interface ModelCapabilities {
+    readonly vision: boolean;
+    readonly reasoning: boolean;
+    readonly toolUse: boolean;
+    readonly structuredOutput: boolean;
+    readonly webSearch: boolean;
+    readonly caching: boolean;
+    readonly imageOut: boolean;
+    readonly audioOut: boolean;
+    readonly videoOut: boolean;
+    readonly audioIn: boolean;
+    readonly videoIn: boolean;
+    readonly fileInput: boolean;
+}
+
+export declare interface ModelDataPolicy {
+    /** Zero data retention. */
+    readonly zeroRetention: PolicyCoverage;
+    /** The provider does not train on what is sent. */
+    readonly noTraining: PolicyCoverage;
+}
+
 export declare type ModelModality = 'language' | 'embedding' | 'image' | 'video' | 'realtime' | 'reranking' | 'speech' | 'transcription' | 'unknown';
 
 export declare interface ModelPrice {
@@ -2100,6 +2226,9 @@ export declare const passesPolicy: (tag: string, policy: AppToolPolicy) => boole
  */
 export declare const patchStreamingMessage: (store: DataStore, id: string, parts: ReadonlyArray<MessagePart>) => Effect.Effect<void>;
 
+/** How much of a provider's retention promise applies. */
+export declare type PolicyCoverage = 'all' | 'some' | 'none';
+
 /**
  * The effective {@link ModelPrice} for a model id, or `undefined` if unknown.
  * Looks up the merged map (overrides over defaults); a gateway `creator/model`
@@ -2262,6 +2391,9 @@ export declare type ProviderConfig = {
         /** base64 the mock video model yields INSTEAD of a URL — exercises the
          *  bytes branch of `generateVideo`. Takes precedence over `videoUrl`. */
         readonly videoBase64?: string;
+        /** The text the mock transcription model returns. Lets a test assert on
+         *  an exact transcript without a provider. */
+        readonly transcript?: string;
     };
 } | {
     readonly name: 'anthropic';
@@ -2327,7 +2459,7 @@ export declare interface QueuedInference {
     readonly runId: string | null;
     readonly signalName: string;
     readonly stepName: string;
-    readonly kind: 'text' | 'object';
+    readonly kind: 'text' | 'object' | 'transcription';
     readonly provider: string;
     readonly model: string;
     readonly prompt: string;
@@ -2339,9 +2471,52 @@ export declare interface QueuedInference {
     readonly maxTokens: number | null;
     readonly providerOptions: unknown;
     readonly jsonSchema: Record<string, unknown> | null;
+    /** The source + options for a `transcription` call. */
+    readonly transcription: Record<string, unknown> | null;
     readonly attempts: number;
 }
 
+/** One entry of the raw `/v1/models` response, every field optional — the
+ *  gateway adds fields, and a parser that requires one is a parser that breaks
+ *  on a Tuesday. */
+export declare interface RawGatewayModel {
+    readonly id?: unknown;
+    readonly name?: unknown;
+    readonly description?: unknown;
+    readonly model_type?: unknown;
+    readonly tags?: unknown;
+    readonly supported_parameters?: unknown;
+    readonly modalities?: unknown;
+    readonly context_window?: unknown;
+    readonly max_tokens?: unknown;
+    readonly released?: unknown;
+    readonly knowledge?: unknown;
+    readonly zdr?: unknown;
+    readonly no_training?: unknown;
+    readonly pricing?: unknown;
+}
+
+/**
+ * The catalog, read from `/v1/models` directly.
+ *
+ * `getAvailableModels` asks `@ai-sdk/gateway`'s provider, whose entry type
+ * carries six of the response's twenty-one fields — so the other fifteen never
+ * arrive, and an app that needs them fetches the endpoint a second time and
+ * writes its own parser. This reads the response.
+ *
+ * The provider path is kept and still used when a `gatewayProvider` is injected
+ * (tests) or a fetch fails: a catalog with fewer fields is worth more than no
+ * catalog, and the fields that were always there stay there. A degraded read is
+ * VISIBLE rather than silent — the entries simply carry no `capabilities`, which
+ * is the difference between "not known" and "no".
+ */
+export declare const readGatewayCatalog: (opts?: {
+    readonly apiKey?: string;
+    readonly baseURL?: string;
+    readonly modality?: ModelModality;
+    readonly fetchImpl?: typeof fetch;
+}) => Promise<ReadonlyArray<GatewayModelInfo>>;
+
 /** 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> {
@@ -2418,6 +2593,38 @@ export declare const redisResumableStreamStore: (redis: ResumableRedis, opts?: {
  */
 export declare const refreshMcpToolset: (server: McpServer, policy: McpToolPolicy) => Effect.Effect<McpToolset, McpError>;
 
+/**
+ * Synthesize speech audio from text. Returns the audio bytes + media type and
+ * provider metadata; provider failures surface as `AiError`.
+ */
+/**
+ * A provider registered with `registerSpeechProvider` — named, not enumerated.
+ *
+ * The gateway serves nine speech models; a real voice catalog runs to hundreds
+ * behind vendors it does not carry (Cartesia, ElevenLabs, Google Cloud TTS). An
+ * app with its own adapter had nowhere to plug it in, so it called its own
+ * synthesizer and skipped this primitive entirely — losing the shared error type
+ * and the shared cost path with it.
+ */
+export declare interface RegisteredSpeechConfig {
+    readonly name: string;
+    readonly model?: string;
+    readonly voice?: string;
+}
+
+/** Every registered name — what a picker asks for. */
+export declare const registeredSpeechProviders: () => ReadonlyArray<string>;
+
+/**
+ * Register a speech provider under a name.
+ *
+ * The name then works in `generateSpeech({ provider: { name, model, voice } })`.
+ * It must not collide with a built-in (`mock`, `openai`, `gateway`,
+ * `anthropic`): silently shadowing one would make a config mean something
+ * different depending on import order.
+ */
+export declare const registerSpeechProvider: (name: string, provider: SpeechProvider) => void;
+
 /**
  * Register (or reuse) the `AbortController` for `streamId`. `streamText` calls
  * this when given a `streamId`; it threads the returned controller's `signal`
@@ -2427,6 +2634,8 @@ export declare const refreshMcpToolset: (server: McpServer, policy: McpToolPolic
  */
 export declare const registerStream: (streamId: string) => AbortController;
 
+export declare const releasedAtOf: (raw: RawGatewayModel) => string | undefined;
+
 /** What `.render(vars)` produces — a stamp plus the text to send. */
 export declare interface RenderedPrompt extends PromptStamp {
     readonly prompt: string;
@@ -2489,8 +2698,21 @@ export declare interface RerankOptions<T> {
     readonly getText?: (doc: T) => string;
     /** Rerank model id. e.g. 'rerank-english-v3.0' (cohere) / 'rerank-2' (voyage). */
     readonly model?: string;
-    /** Provider. Default 'mock' (lexical overlap; deterministic). */
-    readonly provider?: 'mock' | 'cohere' | 'voyage';
+    /**
+     * Where to rerank. Default `'mock'` (lexical overlap; deterministic).
+     *
+     * A `ProviderConfig` — the shape every other primitive in this package takes
+     * — routes through the gateway, so one `AI_GATEWAY_API_KEY` reaches
+     * `cohere/rerank-v4-pro`, `voyage/rerank-2.5` and the rest of the catalog.
+     * This was the one primitive that could not do that: it wanted the vendors'
+     * own keys and had no way to express the gateway at all.
+     *
+     * The string shorthands stay for the direct-key route. They are NOT folded
+     * into `ProviderConfig`: that union is shared with `generateText` and friends,
+     * and adding `cohere` there would let somebody name a provider that has no
+     * language model — a config error the type currently catches.
+     */
+    readonly provider?: 'mock' | 'cohere' | 'voyage' | ProviderConfig;
     /** Return only the top-N after reranking. Default: all. */
     readonly topN?: number;
 }
@@ -2544,6 +2766,15 @@ export declare const resolveSystem: (exec: AnyAgentExecutor, input: unknown) =>
  */
 export declare const resolveToolModuleHandlers: (mod: Record<string, unknown>) => number;
 
+/**
+ * The transcription model for a provider config.
+ *
+ * Mirrors `resolveSpeechModel` deliberately — the two are the same seam in
+ * opposite directions, and the gateway exposes both (`.transcription(id)`), so
+ * one key reaches all nine transcription models in the catalog.
+ */
+export declare const resolveTranscriptionModel: (config: ProviderConfig) => TranscriptionModelV4;
+
 export declare const resolveVideoModel: (config: ProviderConfig) => Experimental_VideoModelV4;
 
 /**
@@ -2625,6 +2856,43 @@ export declare const resumableStreamText: (args: {
     readonly idleTimeoutMs?: number;
 }) => Stream.Stream<SeqEvent>;
 
+/**
+ * Search, rerank, truncate — with the two numbers named.
+ *
+ * ```ts
+ * const docs = yield* retrieveReranked({
+ *   search: (limit) => Effect.promise(() => searchDocs(q, limit)),
+ *   query: q,
+ *   getText: (d) => d.body,
+ *   provider: { name: 'gateway', model: 'cohere/rerank-v4-pro' },
+ * })
+ * ```
+ *
+ * Returns the documents, not `{ document, score }` — the score is the second
+ * stage's working, and a caller that wants it calls `rerank` directly. Handing
+ * back a wrapper would make every consumer unwrap it.
+ */
+export declare const retrieveReranked: <T, E>(options: RetrieveRerankedOptions<T, E>) => Effect.Effect<ReadonlyArray<T>, E | AiError>;
+
+export declare interface RetrieveRerankedOptions<T, E> {
+    /**
+     * The app's own first stage, given a limit.
+     *
+     * A function rather than a value, so the helper decides how DEEP to go: the
+     * candidate count is the parameter being traded against accuracy, and a
+     * caller that had already run the search would have chosen it.
+     */
+    readonly search: (limit: number) => Effect.Effect<ReadonlyArray<T>, E>;
+    readonly query: string;
+    readonly getText: (doc: T) => string;
+    /** How many the first stage fetches. Default 50 — cheap and shallow. */
+    readonly candidates?: number;
+    /** How many survive the rerank. Default 8. */
+    readonly topN?: number;
+    readonly provider?: RerankOptions<T>['provider'];
+    readonly model?: string;
+}
+
 /**
  * The synthesized `<name>.send` body. Appends the user turn at `order`, then
  * drives a streaming assistant turn at `order + 1` via `runAssistant` (which
@@ -2899,6 +3167,29 @@ export declare const setProviderOverride: (config: ProviderConfig | null) => Pro
 
 export { simulateStreamingMiddleware }
 
+export declare interface SpeechProvider {
+    /** The voices this provider offers, for a picker. Optional: a provider with a
+     *  fixed voice set the app already knows needs no listing. */
+    readonly listVoices?: () => Effect.Effect<ReadonlyArray<VoiceInfo>, AiError>;
+    readonly synthesize: (request: SpeechSynthesisRequest) => Effect.Effect<GenerateSpeechResult, AiError>;
+}
+
+/** The provider registered under `name`, or `undefined`. */
+export declare const speechProvider: (name: string) => SpeechProvider | undefined;
+
+/** What `generateSpeech` hands a registered provider. Mirrors its own options
+ *  minus the parts the framework resolves. */
+export declare interface SpeechSynthesisRequest {
+    readonly text: string;
+    readonly model?: string;
+    readonly voice?: string;
+    readonly outputFormat?: string;
+    readonly instructions?: string;
+    readonly speed?: number;
+    readonly language?: string;
+    readonly providerOptions?: AiProviderOptions;
+}
+
 /**
  * Run the underlying stream ONCE and persist every event. Assigns a monotonic
  * `seq`, appends each event, and marks the stream done at the end — even if a
@@ -3135,6 +3426,99 @@ export declare type ToolHandler<A, O> = (input: A, ctx: ToolContext) => Effect.E
 
 export declare const toQueuedInference: (row: Record<string, unknown>) => QueuedInference;
 
+/**
+ * Transcribe audio to text.
+ *
+ * ```ts
+ * const { text, segments } = yield* transcribe({
+ *   source: { storageRef: recording.ref },
+ *   resolveRef: (ref) => ctx.storage.read(ref),
+ *   timestamps: 'segment',
+ * })
+ * ```
+ */
+export declare const transcribe: (options: TranscribeOptions) => Effect.Effect<TranscriptionResult, AiError>;
+
+export declare interface TranscribeOptions {
+    readonly source: TranscriptionSource;
+    /** Override the provider/model. `anthropic` has no transcription model. */
+    readonly provider?: ProviderConfig;
+    /** ISO 639-1. Given rather than detected — detection costs a pass and is
+     *  wrong on short or accented audio. */
+    readonly language?: string;
+    /** Vocabulary, proper nouns, spellings the model would otherwise guess. */
+    readonly prompt?: string;
+    readonly timestamps?: TranscriptionTimestamps;
+    /** Separate speakers. Not every provider can; one that cannot returns
+     *  segments without `speaker` rather than failing. */
+    readonly diarize?: boolean;
+    readonly translateToEnglish?: boolean;
+    /**
+     * Resolve a `storageRef` to bytes.
+     *
+     * Injected, and required only when the source IS a ref — so an app that
+     * passes a url or bytes wires nothing, and `@voltro/ai` never imports storage.
+     */
+    readonly resolveRef?: (ref: string) => Promise<{
+        bytes: Uint8Array;
+        mediaType: string;
+    }>;
+    readonly providerOptions?: AiProviderOptions;
+}
+
+export declare interface TranscriptionResult {
+    readonly text: string;
+    readonly language?: string;
+    readonly durationSec?: number;
+    readonly segments?: ReadonlyArray<TranscriptionSegment>;
+    /**
+     * Usage, for the SAME ledger every other primitive reports to.
+     *
+     * Transcription is the one modality billed by DURATION rather than by tokens,
+     * which is exactly why it must not be the one modality missing from the
+     * budget: a spend limit that silently excludes the long-running thing is not
+     * a spend limit.
+     */
+    readonly usage?: MediaUsage;
+    readonly providerMetadata?: unknown;
+}
+
+export declare interface TranscriptionSegment {
+    readonly start: number;
+    readonly end: number;
+    readonly text: string;
+    /** Present only when `diarize` was asked for AND the provider supports it. */
+    readonly speaker?: string;
+}
+
+/**
+ * Where the audio is.
+ *
+ * `storageRef` is the one to reach for: the file is already in the app's
+ * storage, and resolving it there keeps tenancy, signing and lifetime with the
+ * component that owns them. The resolver is injected rather than imported so
+ * this module stays free of a storage dependency — `@voltro/ai` must not learn
+ * about buckets to transcribe a file.
+ */
+export declare type TranscriptionSource = 
+/** Resolved by the app's own storage — the case to reach for. */
+    {
+    readonly storageRef: string;
+}
+/** Fetched by this function. Convenient, but the bytes do pass through this
+*  process: the SDK takes bytes or base64 and never a location. */
+| {
+    readonly url: string;
+}
+/** Already in hand. The one that costs memory by construction. */
+| {
+    readonly bytes: Uint8Array;
+    readonly mediaType: string;
+};
+
+/** How much timestamp detail to ask for. Providers charge for it. */
+export declare type TranscriptionTimestamps = 'none' | 'segment' | 'word';
+
 /**
  * Drop a stream's controller. `streamText` calls this in its finaliser when the
  * stream ends — success, error, cancel, or consumer interrupt. Idempotent.
@@ -3149,6 +3533,17 @@ export declare const unregisterStream: (streamId: string) => void;
  */
 export declare const validateCopilotProposal: (proposal: CopilotProposal, schema: CopilotSchema) => CopilotValidation;
 
+/** One voice a registered provider offers. */
+export declare interface VoiceInfo {
+    readonly id: string;
+    readonly name: string;
+    readonly language?: string;
+    /** Free-form, provider-shaped: gender, accent, age, whatever it publishes.
+     *  Not normalised — every vendor's taxonomy is different, and flattening them
+     *  would lose the half a picker actually shows. */
+    readonly labels?: Readonly<Record<string, string>>;
+}
+
 /**
  * Wrap an `Effect`-returning generate call with a `voltro.ai.call` span +
  * per-call metrics (count, error count, duration histogram, token + cost