@voltro/ai 0.57.0 → 0.59.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;
@@ -372,7 +373,7 @@ export declare interface AiUsageRecordInput {
     readonly model: string;
     readonly operation: string;
     readonly agent?: string | null;
-    readonly usage: AiUsage;
+    readonly usage: AiUsage | MeteredUsage;
     /** Override the price table (negotiated/volume pricing or unknown model). */
     readonly price?: ModelPrice;
     /** The ACTUAL per-call cost reported by the provider/gateway (USD). When set,
@@ -572,6 +573,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 `generateSpeech` resolves without a registration. */
+export declare const BUILTIN_SPEECH_PROVIDERS: ReadonlyArray<string>;
+
 /**
  * Cancel an in-flight stream by id. Aborts its controller (the SDK call stops +
  * the stream emits a terminal `cancelled` error). Returns `true` if a live
@@ -580,9 +584,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 +631,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;
 
@@ -707,7 +737,9 @@ export declare interface CostBreakdown {
      *  the ACTUAL per-call cost (authoritative); `estimated` = derived from the
      *  static price table (or zero for an unknown model). Analytics can flag
      *  estimated rows + a model that priced at zero. */
-    readonly costSource: 'gateway' | 'estimated';
+    readonly costSource: 'gateway' | 'estimated' | 'unpriced';
+    /** What `inputTokens`/`outputTokens` are counts OF. */
+    readonly unit: UsageUnit;
 }
 
 /** Open a new thread (the store generates the id). */
@@ -727,6 +759,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
@@ -989,7 +1023,7 @@ export declare const embedMany: (texts: ReadonlyArray<string>, config?: Embeddin
  * unknown model (or the `mock` provider) resolves to zero cost rather
  * than throwing, so cost accounting never breaks a call.
  */
-export declare const estimateCostUsd: (usage: AiUsage, opts: {
+export declare const estimateCostUsd: (usage: AiUsage | MeteredUsage, opts: {
     readonly model: string;
     readonly price?: ModelPrice;
     readonly actualCostUsd?: number;
@@ -1102,6 +1136,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
@@ -1124,6 +1167,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
@@ -1155,6 +1201,49 @@ 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;
+    /**
+     * The entry exactly as it came over the wire.
+     *
+     * The normalised fields above are the shared answer to the questions every
+     * app on the gateway asks. `raw` is for the ones only one app asks — a chips
+     * row built from `tags`, a pricing display that shows the vendor's own
+     * structure, `zdr` and `no_training` kept apart rather than folded into
+     * `dataPolicy`.
+     *
+     * Without it, an app with its own display fetches `/v1/models` a SECOND time
+     * and maintains a SECOND parser of the same response — and then has to decide
+     * again, at every new field the gateway adds, whether to wait for us. That is
+     * the decision this field removes, which is why it is one field and not three
+     * more normalised ones.
+     *
+     * Absent on the injected-provider path for the same reason `capabilities` is:
+     * that seam never saw a response, and inventing an empty object would turn
+     * "no wire data" into the claim "the wire carried nothing".
+     */
+    readonly raw?: RawGatewayModel;
 }
 
 /**
@@ -1322,10 +1411,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 {
@@ -1333,7 +1418,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'`. */
@@ -1350,8 +1435,21 @@ export declare interface GenerateSpeechOptions {
 
 export declare interface GenerateSpeechResult {
     readonly audio: GeneratedAudio;
-    /** The speech model spec reports no usage; present for surface parity. */
-    readonly usage?: MediaUsage;
+    /**
+     * What the call consumed.
+     *
+     * The speech model SPEC reports none, so a gateway-routed call still leaves
+     * this undefined. A REGISTERED provider is the other case, and it is not a
+     * property of the model any more: an app's own adapter knows the billed
+     * quantity, because its vendor invoices on it — characters for ElevenLabs,
+     * Cartesia and OpenAI, seconds for others.
+     *
+     * So it takes a `MeteredUsage` too, and that is what makes speech spend
+     * reachable: without a shape that can say "4200 characters", the number the
+     * adapter already has has nowhere to go, and `recordAiUsage` never sees the
+     * call at all. Not un-priced — absent from the ledger.
+     */
+    readonly usage?: MediaUsage | MeteredUsage;
     readonly providerMetadata?: unknown;
 }
 
@@ -1517,6 +1615,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.
      *
@@ -1604,6 +1714,8 @@ export declare const isEvalDefinition: (value: unknown) => value is EvalDefiniti
  */
 export declare const isExternalWrite: (tool: McpToolInfo, namespace: string, policy: McpToolPolicy) => boolean;
 
+export declare const isMeteredUsage: (u: AiUsage | MeteredUsage) => u is MeteredUsage;
+
 /** Is this a rendered prompt or a bare string? The discriminator `aiStep` uses
  *  so `prompt:` can accept either without a wrapper type at every call site. */
 export declare const isRenderedPrompt: (value: unknown) => value is RenderedPrompt;
@@ -1623,6 +1735,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
@@ -1656,6 +1770,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
@@ -1971,6 +2087,23 @@ export declare type MessagePart = {
     readonly data: string;
 };
 
+/**
+ * A tally in a unit that is not tokens.
+ *
+ * Deliberately NOT `AiUsage` with a unit tacked on. Writing a character count
+ * into a field called `inputTokens` puts a lie in a ledger row that someone
+ * reads later, and a dashboard summing that column across units is wrong in a
+ * way nothing reports. The token shape is left exactly as it was — it is what
+ * the AI SDK returns, and text callers change nothing.
+ */
+export declare interface MeteredUsage {
+    readonly unit: Exclude<UsageUnit, 'tokens'>;
+    /** What went in — characters of text, say. */
+    readonly input?: number | undefined;
+    /** What came out — seconds of audio, say. */
+    readonly output?: number | undefined;
+}
+
 /** A scripted inline file the mock model emits on a turn (usually an image).
  *  `data` is base64 (a short ascii string works for assertions). */
 export declare interface MockFile {
@@ -2027,6 +2160,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.
  *
@@ -2051,6 +2198,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 {
@@ -2063,6 +2233,13 @@ export declare interface ModelPrice {
 /** The current merged price map (defaults + installed overrides). Overrides win. */
 export declare const modelPricing: () => Record<string, ModelPrice>;
 
+/** Both shapes, flattened to the two counts + the unit they are counts of. */
+export declare const normaliseUsage: (usage: AiUsage | MeteredUsage) => {
+    readonly unit: UsageUnit;
+    readonly input: number;
+    readonly output: number;
+};
+
 /**
  * Wrap a `streamText` `Stream<AgentEvent>` with the same `voltro.ai.call` span +
  * metrics. The stream never fails — usage arrives on the terminal `done` event,
@@ -2113,6 +2290,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`
@@ -2275,6 +2455,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';
@@ -2340,7 +2523,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;
@@ -2352,9 +2535,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> {
@@ -2431,6 +2657,58 @@ 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 } })`.
+ * Taking over a built-in name needs `{ replaceBuiltin: true }` — see the option.
+ */
+export declare const registerSpeechProvider: (name: string, provider: SpeechProvider, options?: RegisterSpeechProviderOptions) => void;
+
+export declare interface RegisterSpeechProviderOptions {
+    /**
+     * Take over a BUILT-IN name (`openai`, `gateway`, `anthropic`, `mock`).
+     *
+     * Refusing these outright was wrong, and the case that showed it is one the
+     * refusal could not see: a provider name is not always an alias the app
+     * chooses. `openai` is the value the GATEWAY puts in its model ids, so it is
+     * what an app's stored catalog rows carry and what its picker submits. Told
+     * to pick another name, such an app cannot — it would have to rewrite
+     * persisted rows and live sessions — so it keeps its own dispatch instead,
+     * and the primitive stays unused for every provider, not just the colliding
+     * one.
+     *
+     * What the refusal was actually protecting is worth keeping: a SILENT shadow,
+     * where the same config means different things depending on which module
+     * loaded first. This flag keeps that property by putting the intent in the
+     * call. An override is then a decision someone wrote down, not an accident of
+     * import order.
+     */
+    readonly replaceBuiltin?: boolean;
+}
+
 /**
  * Register (or reuse) the `AbortController` for `streamId`. `streamText` calls
  * this when given a `streamId`; it threads the returned controller's `signal`
@@ -2440,6 +2718,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;
@@ -2452,6 +2732,9 @@ export declare interface RenderedPrompt extends PromptStamp {
     readonly definition: PromptDefinition;
 }
 
+/** Whether `name` is a registration standing in front of a built-in. */
+export declare const replacesBuiltinSpeechProvider: (name: string) => boolean;
+
 /**
  * Gate an AI call against a per-tenant USD budget with an ATOMIC reservation —
  * the cap precedent is billing's `requireEntitlement` / storage's
@@ -2502,8 +2785,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;
 }
@@ -2557,6 +2853,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;
 
 /**
@@ -2638,6 +2943,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
@@ -2912,6 +3254,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
@@ -3148,12 +3513,115 @@ 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.
  */
 export declare const unregisterStream: (streamId: string) => void;
 
+/**
+ * What a call was billed in.
+ *
+ * Text is tokens. Speech is not: every speech vendor meters CHARACTERS of input
+ * or SECONDS of audio, and none of them meters tokens. A ledger that only knows
+ * tokens therefore cannot hold a speech call at all — which is why speech spend
+ * was invisible rather than merely un-priced.
+ */
+export declare type UsageUnit = 'tokens' | 'characters' | 'seconds';
+
 /**
  * Validate a proposal against the schema and (on success) build a read-only
  * `QueryDescriptor`. EVERY table/column the proposal names must exist in the
@@ -3162,6 +3630,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