@broberg/ai-sdk 0.26.0 → 0.28.0

package/README.md

@@ -87,6 +87,56 @@ const ai = createAI({
 Sinks: `upmetricsSink` (canonical), `discordSink`, `sqliteSink`, `multiSink`,
 `noopSink`. A failing sink never crashes a call.
 
+### Cost-tracking is on by default (v0.24+)
+
+You don't have to wire a sink. If `UPMETRICS_API_KEY` is in the env, a bare
+`createAI()` auto-attaches the upmetrics sink — this exists because most
+call-sites passed no sink, leaving ~91% of Mistral spend invisible. No key in
+the env → no sink, no crash (ship-dark).
+
+```ts
+createAI();                      // key in env → tracked; no key → nothing happens
+createAI({ costSink: mySink });  // explicit sink wins
+createAI({ costSink: null });    // explicit OPT-OUT — see below
+```
+
+| Env var | Effect |
+|---|---|
+| `UPMETRICS_API_KEY` | **The only switch.** Present → tracking on. |
+| `UPMETRICS_AGENT_NAME` | Row label. Set it — the fallback is `npm_package_name`, which is empty for a process not started via an npm/bun script (a `node dist/…` or Docker service logs as `unknown`). |
+| `UPMETRICS_BASE_URL` | Ingest host. Defaults to `https://upmetrics.org`. |
+| `UPMETRICS_COMPLIANCE` | `1` sets compliance mode. `Usage` carries no prompt/response text either way. |
+
+**Adopting it in a repo — two things to do first, or the adoption corrupts the
+numbers it was meant to reveal:**
+
+1. **Opt out wherever you already report your own costs.** Pass
+   `costSink: null`. Otherwise the SDK adds a *second* reporting path on top of
+   yours and every call is counted **twice**, in production, with no error
+   anywhere. (Found by `buddy`, who aggregates to `cli_usage` and pushes hourly.)
+
+2. **Keep the key out of your test run.** Test runners auto-load `.env` (Bun
+   does; Vitest with a dotenv setup does), so any suite that reaches a
+   `createAI()` will POST **fabricated usage into production telemetry**. Note
+   the trigger is *importing* a module that builds the client — a module-level
+   `createAI()` arms it without anything calling it. Strip the whole prefix:
+
+   ```ts
+   // test-setup.ts  — bunfig.toml: [test] preload = ["./test-setup.ts"]
+   for (const k of Object.keys(process.env)) {
+     if (k.startsWith("UPMETRICS_")) delete process.env[k];
+   }
+   ```
+
+   Strip the **prefix**, not a list of names — a guard you must remember to
+   update is one that silently rots. And assert the *effect* (no `UPMETRICS_*`
+   visible to a test) with a control proving the probe can go red; a test that
+   checks "the key is undefined" passes while protecting nothing on a machine
+   that never had the key.
+
+Adoption is **per repo, opt-in** — there is no fleet-wide push. Turn it on when
+a repo has spend worth watching, with both guards in place.
+
 ## License
 
 FSL-1.1-Apache-2.0

package/dist/{chunk-IZG5UZH5.js → chunk-LUPUAAHZ.js}

@@ -67,6 +67,12 @@ var PRICING = {
   "gemini:gemini-2.5-flash": { inputPer1M: 0.3, outputPer1M: 2.5, version: V },
   // flash-lite is the default `video` tier (F019) — cheap native video understanding.
   "gemini:gemini-2.5-flash-lite": { inputPer1M: 0.1, outputPer1M: 0.4, version: "2026-06-04-or-xref" },
+  // Vertex AI (F038) — the EU-resident route to the SAME Gemini models, so Google's
+  // published Gemini token prices apply. Listed separately because cost lookups key on
+  // `provider:model`: without these rows an EU vision/video call would silently log
+  // $0, which is worse than no tracking (a confident wrong number).
+  "vertex:gemini-2.5-flash": { inputPer1M: 0.3, outputPer1M: 2.5, version: V },
+  "vertex:gemini-2.5-flash-lite": { inputPer1M: 0.1, outputPer1M: 0.4, version: "2026-06-04-or-xref" },
   // Mistral (direct, La Plateforme). Official prices from mistral.ai/pricing
   // (2026-06-04, per Christian's CD report). EU/Paris-hosted — the designated
   // GDPR-safe provider for client/personal-data workloads (see F015). NB:
@@ -105,4 +111,4 @@ export {
   PRICING,
   getPrice
 };
-//# sourceMappingURL=chunk-IZG5UZH5.js.map
+//# sourceMappingURL=chunk-LUPUAAHZ.js.map

package/dist/chunk-LUPUAAHZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cost/pricing.ts"],"sourcesContent":["// Versioned per-(provider, model) pricing. F3.6 populates the table + adds tests\n// + MiniMax coverage. F3.1 ships the type + lookup with an empty table, so\n// computeCost returns 0 for every model until F3.6 lands (calls still complete).\nexport interface PricingEntry {\n  /** USD per 1M input tokens. */\n  inputPer1M: number;\n  /** USD per 1M output tokens. */\n  outputPer1M: number;\n  /** USD per 1M cache-read tokens (falls back to input rate if unset). */\n  cacheReadPer1M?: number;\n  /** USD per 1M cache-write/creation tokens (falls back to input rate if unset). */\n  cacheWritePer1M?: number;\n  /** Pricing snapshot version (date or tag) so stale entries are detectable. */\n  version: string;\n}\n\n// USD per 1M tokens. Anthropic cache multipliers follow the standard model:\n// cache-read ≈ 0.1× input, cache-write ≈ 1.25× input. Verified against the\n// pricing tables in cms (packages/cms-ai/src/providers) + trail (model-lab).\n// MiniMax M2.7 is an estimate pending confirmation against OpenRouter's live\n// price page — flagged in its version string.\nconst V = \"2026-06-02\";\n// Mistral prices come straight from mistral.ai/pricing (per Christian's CD report).\nconst MS = \"2026-06-04-mistral.ai\";\n\n/** Keyed `${provider}:${model}`. Exported so the catalogue-research job (F014)\n *  can enumerate every priced entry and diff it against the live provider lists. */\nexport const PRICING: Record<string, PricingEntry> = {\n  // Anthropic (direct API). DEFAULT_TIER_MAP: fast/cheap=haiku, smart/vision=sonnet, powerful=opus.\n  \"anthropic:claude-haiku-4-5\": {\n    inputPer1M: 0.8,\n    outputPer1M: 4.0,\n    cacheReadPer1M: 0.08,\n    cacheWritePer1M: 1.0,\n    version: V,\n  },\n  \"anthropic:claude-sonnet-4-6\": {\n    inputPer1M: 3.0,\n    outputPer1M: 15.0,\n    cacheReadPer1M: 0.3,\n    cacheWritePer1M: 3.75,\n    version: V,\n  },\n  \"anthropic:claude-opus-4-8\": {\n    inputPer1M: 15.0,\n    outputPer1M: 75.0,\n    cacheReadPer1M: 1.5,\n    cacheWritePer1M: 18.75,\n    version: V,\n  },\n\n  // OpenAI. embedding default tier = text-embedding-3-small (no output tokens).\n  \"openai:text-embedding-3-small\": { inputPer1M: 0.02, outputPer1M: 0, version: V },\n  \"openai:text-embedding-3-large\": { inputPer1M: 0.13, outputPer1M: 0, version: V },\n  \"openai:gpt-4o\": { inputPer1M: 2.5, outputPer1M: 10.0, version: V },\n  \"openai:gpt-4o-mini\": { inputPer1M: 0.15, outputPer1M: 0.6, version: V },\n  // Whisper is priced per minute, not per token — not representable here; transcribe\n  // (F5.6) computes its own cost. Listed as 0 so token-based compute never charges it.\n  \"openai:whisper-1\": { inputPer1M: 0, outputPer1M: 0, version: V },\n\n  // OpenRouter (meta-router — model slugs include the upstream vendor). Slugs use\n  // dots (claude-sonnet-4.6) to match OpenRouter's live ids; the dashed forms\n  // never matched a real call. Caught by the F014 catalogue research.\n  \"openrouter:anthropic/claude-sonnet-4.6\": { inputPer1M: 3.0, outputPer1M: 15.0, version: V },\n  // OpenRouter ground-truth $1/$5 — a markup over Anthropic-direct's $0.8/$4\n  // (the `anthropic:` entry above). Was masked while the slug used dashes.\n  \"openrouter:anthropic/claude-haiku-4.5\": { inputPer1M: 1.0, outputPer1M: 5.0, version: \"2026-06-04\" },\n  \"openrouter:google/gemini-2.5-flash\": { inputPer1M: 0.3, outputPer1M: 2.5, version: V },\n  // Ground-truth from OpenRouter /api/v1/models (was a 0.3 estimate; now 0.279).\n  \"openrouter:minimax/minimax-m2.7\": {\n    inputPer1M: 0.279,\n    outputPer1M: 1.2,\n    version: \"2026-06-04\",\n  },\n  // DeepSeek V4 (CN-hosted — NOT GDPR-safe; non-personal-data workloads only).\n  // On 2026-05-22 DeepSeek made the \"75% off\" promo the permanent official price.\n  // V4-Pro $0.435/$0.87 is ~34x cheaper than GPT-5.5 on output; flash is cheaper\n  // still. Numbers match OpenRouter /api/v1/models 1:1 (no router markup). A strong\n  // cheap route for fleet background work once `claude -p` is API-billed (15 Jun).\n  \"openrouter:deepseek/deepseek-v4-pro\": { inputPer1M: 0.435, outputPer1M: 0.87, version: \"2026-05-22-deepseek-official\" },\n  \"openrouter:deepseek/deepseek-v4-flash\": { inputPer1M: 0.0983, outputPer1M: 0.1966, version: \"2026-05-22-deepseek-official\" },\n  // DeepSeek DIRECT API (provider \"deepseek\", F030 non-PII secondary). Rates from\n  // api-docs.deepseek.com 2026-06-30 ($0.14/$0.28 per 1M; both map to deepseek-v4-flash).\n  // `deepseek-chat` (non-thinking) + `deepseek-reasoner` (thinking) DEPRECATE 2026-07-24.\n  // (The bare `deepseek-v4-flash` basename is already priced via the openrouter entry\n  // above — kept distinct here to avoid a basename collision in the F027 pricing-API.)\n  // Verify against a real key when it lands.\n  \"deepseek:deepseek-chat\": { inputPer1M: 0.14, outputPer1M: 0.28, version: \"2026-06-30-deepseek-direct\" },\n  \"deepseek:deepseek-reasoner\": { inputPer1M: 0.14, outputPer1M: 0.28, version: \"2026-06-30-deepseek-direct\" },\n\n  // Google Gemini (direct). Provider key is \"gemini\" — matches the adapter's\n  // usage.provider + the override.provider callers pass. (Image-gen models are\n  // priced per-image in the adapter, not here.)\n  \"gemini:gemini-2.5-flash\": { inputPer1M: 0.3, outputPer1M: 2.5, version: V },\n  // flash-lite is the default `video` tier (F019) — cheap native video understanding.\n  \"gemini:gemini-2.5-flash-lite\": { inputPer1M: 0.1, outputPer1M: 0.4, version: \"2026-06-04-or-xref\" },\n\n  // Vertex AI (F038) — the EU-resident route to the SAME Gemini models, so Google's\n  // published Gemini token prices apply. Listed separately because cost lookups key on\n  // `provider:model`: without these rows an EU vision/video call would silently log\n  // $0, which is worse than no tracking (a confident wrong number).\n  \"vertex:gemini-2.5-flash\": { inputPer1M: 0.3, outputPer1M: 2.5, version: V },\n  \"vertex:gemini-2.5-flash-lite\": { inputPer1M: 0.1, outputPer1M: 0.4, version: \"2026-06-04-or-xref\" },\n\n  // Mistral (direct, La Plateforme). Official prices from mistral.ai/pricing\n  // (2026-06-04, per Christian's CD report). EU/Paris-hosted — the designated\n  // GDPR-safe provider for client/personal-data workloads (see F015). NB:\n  // medium-3.5 is the premium \"Vibe\" coding tier ($1.5/$7.5); Large 3 ($0.5/$1.5)\n  // is the cheaper frontier general-purpose model despite the higher number.\n  \"mistral:mistral-large-latest\": { inputPer1M: 0.5, outputPer1M: 1.5, version: MS },\n  \"mistral:mistral-large-2512\": { inputPer1M: 0.5, outputPer1M: 1.5, version: MS },\n  \"mistral:mistral-medium-latest\": { inputPer1M: 1.5, outputPer1M: 7.5, version: MS },\n  \"mistral:mistral-medium-3.5\": { inputPer1M: 1.5, outputPer1M: 7.5, version: MS },\n  \"mistral:mistral-medium-3\": { inputPer1M: 0.4, outputPer1M: 2.0, version: \"2026-06-04-or-xref\" },\n  \"mistral:mistral-small-latest\": { inputPer1M: 0.1, outputPer1M: 0.3, version: MS },\n  \"mistral:mistral-small-2603\": { inputPer1M: 0.1, outputPer1M: 0.3, version: MS },\n  \"mistral:ministral-3b-latest\": { inputPer1M: 0.1, outputPer1M: 0.1, version: MS },\n  \"mistral:ministral-8b-latest\": { inputPer1M: 0.15, outputPer1M: 0.15, version: MS },\n  \"mistral:ministral-14b-latest\": { inputPer1M: 0.2, outputPer1M: 0.2, version: MS },\n  \"mistral:magistral-medium-latest\": { inputPer1M: 2.0, outputPer1M: 5.0, version: MS },\n  \"mistral:magistral-small-latest\": { inputPer1M: 0.5, outputPer1M: 1.5, version: MS },\n  \"mistral:devstral-latest\": { inputPer1M: 0.4, outputPer1M: 2.0, version: MS },\n  \"mistral:codestral-latest\": { inputPer1M: 0.3, outputPer1M: 0.9, version: MS },\n  \"mistral:open-mistral-nemo\": { inputPer1M: 0.15, outputPer1M: 0.15, version: MS },\n  // Moderation (F016.4) — per input token; output 0. (OCR is per-page in the adapter.)\n  \"mistral:mistral-moderation-latest\": { inputPer1M: 0.1, outputPer1M: 0, version: MS },\n  // Embeddings (F016.5) — per input token.\n  \"mistral:mistral-embed\": { inputPer1M: 0.1, outputPer1M: 0, version: MS },\n  \"mistral:codestral-embed\": { inputPer1M: 0.15, outputPer1M: 0, version: MS },\n};\n\nexport function getPrice(provider: string, model: string): PricingEntry | undefined {\n  const exact = PRICING[`${provider}:${model}`];\n  if (exact) return exact;\n  // Providers ship dated model snapshots, e.g. \"claude-haiku-4-5-20251001\".\n  // Strip a trailing -YYYYMMDD and retry the base lookup so a dated variant\n  // prices the same as its base model instead of falling through to 0 — a real\n  // paid call must never be logged as $0 (F012). Covers openrouter slugs too.\n  const base = model.replace(/-\\d{8}$/, \"\");\n  if (base !== model) return PRICING[`${provider}:${base}`];\n  return undefined;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -1640,6 +1640,9 @@ declare const ttsInputSchema: z.ZodObject<{
     labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     text: z.ZodString;
     voice: z.ZodString;
+    /** F037: voice to use if `voice` is one we know the provider has retired. Without
+     *  it a retired voice throws VoiceUnavailableError rather than reaching the API. */
+    voiceFallback: z.ZodOptional<z.ZodString>;
     lang: z.ZodOptional<z.ZodString>;
     format: z.ZodOptional<z.ZodString>;
     rate: z.ZodOptional<z.ZodNumber>;
@@ -1660,6 +1663,7 @@ declare const ttsInputSchema: z.ZodObject<{
     })[] | undefined;
     labels?: Record<string, string> | undefined;
     format?: string | undefined;
+    voiceFallback?: string | undefined;
     lang?: string | undefined;
     rate?: number | undefined;
 }, {
@@ -1679,6 +1683,7 @@ declare const ttsInputSchema: z.ZodObject<{
     })[] | undefined;
     labels?: Record<string, string> | undefined;
     format?: string | undefined;
+    voiceFallback?: string | undefined;
     lang?: string | undefined;
     rate?: number | undefined;
 }>;
@@ -2048,8 +2053,8 @@ declare const falStubAdapter: ProviderAdapter;
  *  wires the live adapters. */
 declare const stubProviders: Record<string, ProviderAdapter>;
 
-declare const VERSION: "0.26.0";
-declare const SDK_TAG: "@broberg/ai-sdk@0.26.0";
+declare const VERSION: "0.28.0";
+declare const SDK_TAG: "@broberg/ai-sdk@0.28.0";
 
 /** Built-in defaults. Every entry is overridable via AiConfig.defaults or a
  *  per-call override.
@@ -2102,6 +2107,88 @@ declare function refreshAvailability(opts?: RefreshOptions): Promise<RefreshResu
 /** Reset the overlay back to the curated defaults. For tests. */
 declare function resetRegistry(): void;
 
+type VoiceStatus = "available" | "retired" | "unknown";
+type VoiceProvider = "elevenlabs" | "azure";
+/** One row of the shared voice read — what a UI voice-picker renders. */
+interface VoiceInfo {
+    /** Full provider voice id, e.g. "da-DK-ChristelNeural" / "4RklGmuxoAskAbGXplXN". */
+    id: string;
+    /** Curated friendly name a caller passes as `voice`, e.g. "christel". */
+    name: string;
+    provider: VoiceProvider;
+    /** BCP-47 locale of the voice itself, e.g. "da-DK". NB: an Azure multilingual
+     *  voice speaking Danish reports its own locale ("de-DE" for Seraphina) — that
+     *  is what the adapter actually sends as xml:lang. */
+    locale: string;
+    /** Only where the provider publishes it — absent is "we do not know", never a
+     *  guess from the first name. */
+    gender?: "female" | "male";
+    available: boolean;
+    status: VoiceStatus;
+    /** Why it is unavailable, or any caveat worth showing in a picker. */
+    note?: string;
+    /** ISO date this row's status was last confirmed AGAINST THE PROVIDER. Exposed
+     *  on purpose (the F034.1 lesson): a registry that cannot be seen to go stale
+     *  is worse than one that can, because nobody knows when to re-check it. */
+    checkedAt: string;
+}
+/** Result of checkVoice — deliberately the same shape as ResolveResult (F022) so
+ *  a consumer learns one idiom for models and voices. */
+interface VoiceResolveResult {
+    /** True when the requested voice itself is usable. */
+    ok: boolean;
+    /** The id to actually send: the requested voice's id when ok, else the
+     *  fallback's. When there is no usable fallback this is the dead id and `ok`
+     *  is false — mirroring resolveModel, the caller must read `ok`. */
+    voiceId: string;
+    /** What the caller asked for, verbatim. */
+    requested: string;
+    provider?: VoiceProvider;
+    /** True when `voiceId` differs from what was requested because we fell back. */
+    fellBack: boolean;
+    status: VoiceStatus;
+    /** Why it degraded / why it is unavailable. */
+    reason?: string;
+}
+/** Thrown when the requested voice is retired and no usable fallback exists.
+ *  Callers flag on `.code === "voice_unavailable"`. */
+declare class VoiceUnavailableError extends Error {
+    readonly code = "voice_unavailable";
+    readonly requested: string;
+    readonly provider?: VoiceProvider;
+    readonly note?: string;
+    constructor(requested: string, note?: string, provider?: VoiceProvider);
+}
+
+interface CheckVoiceOptions {
+    /** One name/id or an ordered chain to try when `requested` is retired. */
+    fallback?: string | string[];
+    /** Throw VoiceUnavailableError instead of returning ok:false when nothing in the
+     *  chain is usable. For callers that want to fail loudly rather than degrade. */
+    throwIfUnavailable?: boolean;
+}
+/**
+ * The shared voice read — a UI picker greys out `available:false` rows and can show
+ * `checkedAt` so a stale registry is visible rather than silently trusted.
+ *
+ * NB: distinct from `elevenlabsAdapter().listVoices()`, which is an async call to
+ * ElevenLabs' live API. This one is synchronous, cross-provider, and reads only the
+ * curated registry.
+ */
+declare function listVoices(opts?: {
+    provider?: VoiceProvider;
+}): VoiceInfo[];
+/**
+ * Resolve a requested voice (curated name or raw provider id) to one that is
+ * actually usable. Synchronous + offline by contract.
+ *
+ * - Available → pass through ({ ok:true, fellBack:false }).
+ * - Retired + a usable fallback → swap ({ ok:false, fellBack:true }).
+ * - Retired + no usable fallback → throw (throwIfUnavailable) or return ok:false.
+ * - Untracked id → treated usable ({ status:"unknown" }), passed through verbatim.
+ */
+declare function checkVoice(requested: string, opts?: CheckVoiceOptions): VoiceResolveResult;
+
 /**
  * Cost in USD for a call. cache-read/creation tokens are priced separately when
  * the pricing entry defines rates for them; otherwise they fall back to the
@@ -2376,4 +2463,4 @@ interface StreamTransportRequest extends TransportRequest {
  */
 declare function streamTransport(req: StreamTransportRequest): AsyncIterable<string>;
 
-export { AZURE_DANISH_VOICES, AZURE_DANISH_VOICE_LIST, type AiClient, type AiConfig, type AzureVoiceInfo, type BatchJob, type BatchRequestItem, type BatchResultItem, type BflAdapterConfig, type BflCredits, type BudgetConfig, BudgetExceededError, BudgetGuard, type BudgetStore, type CallOptions, type Capability, type ChatInput, type ChatRequest, type ChatResult, type ChatStreamEvent, type ClassifyInput, type ClassifyResult, type ContentPart, type Contracts, type CostQuery, type CostSink, type CostSummary, type CostSummaryQuery, type CostTimeseriesQuery, DEFAULT_TIER_MAP, type DesignInput, type DesignResult, type DialogueRequest, type DialogueTurn, type DiscordSinkConfig, ELEVENLABS_DANISH_VOICES, type EmbeddingInput, type EmbeddingRequest, type EmbeddingResult, type ExtractInput, type ExtractResult, type FalAdapterConfig, type HttpResponse, type ImageInput, type ImageRequest, type ImageResult, type LoraWeight, type Message, type MockupInput, type MockupResult, type ModerationInput, type ModerationItem, type ModerationRequest, type ModerationResult, type OcrInput, type OcrPage, type OcrRequest, type OcrResult, type OpenAICompatibleConfig, type PodcastInput, type PodcastResult, type PricingEntry, type ProviderAdapter, type RefreshOptions, type RefreshResult, type RerankInput, type RerankResult, type Role, SDK_TAG, type SqliteBudgetStoreConfig, type SqliteSinkConfig, StreamHttpError, type SubprocessResponse, type Tier, type TierSpec, type Tool, type ToolCall, type TrainStyleInput, type TrainStyleRequest, type TrainStyleResult, type TranscribeInput, type TranscribeRequest, type TranscribeResult, type TranslateInput, type TranslateResult, type Transport, type TransportRequest, type TransportResponse, type TtsInput, type TtsRequest, type UpmetricsCostClientConfig, UpmetricsCostError, type UpmetricsCostRow, type UpmetricsCostSummary, type UpmetricsCostTimeseries, type UpmetricsSinkConfig, type Usage, VERSION, type VideoInput, type VisionInput, aiConfigSchema, anthropicAdapter, anthropicApiAdapter, anthropicSubprocessAdapter, azureAdapter, bflAdapter, bflCredits, chatInputSchema, computeCost, createAI, deepinfraAdapter, deeplAdapter, deepseekAdapter, defaultProviders, discordSink, elevenlabsAdapter, embeddingInputSchema, falAdapter, falStubAdapter, freshUsage, fromProviderToolCall, geminiAdapter, getCostSummary, getPrice, httpTransport, imageInputSchema, listAzureDanishVoices, makeContracts, makeOpenAICompatibleAdapter, messageSchema, mistralAdapter, mistralStubAdapter, multiSink, noopSink, openaiAdapter, openaiStubAdapter, openrouterAdapter, parseClaudeCliJson, parseJsonLoose, refreshAvailability, requestyAdapter, resetRefreshState, resetRegistry, resolveAzureVoice, resolveTier, resolveVoice, sqliteBudgetStore, sqliteSink, streamTransport, stubProviders, subprocessTransport, tierSpecSchema, toProviderTools, toolSchema, translateInputSchema, upmetricsCostClient, upmetricsSink, usdFromMicro, vertexAdapter, visionInputSchema };
+export { AZURE_DANISH_VOICES, AZURE_DANISH_VOICE_LIST, type AiClient, type AiConfig, type AzureVoiceInfo, type BatchJob, type BatchRequestItem, type BatchResultItem, type BflAdapterConfig, type BflCredits, type BudgetConfig, BudgetExceededError, BudgetGuard, type BudgetStore, type CallOptions, type Capability, type ChatInput, type ChatRequest, type ChatResult, type ChatStreamEvent, type CheckVoiceOptions, type ClassifyInput, type ClassifyResult, type ContentPart, type Contracts, type CostQuery, type CostSink, type CostSummary, type CostSummaryQuery, type CostTimeseriesQuery, DEFAULT_TIER_MAP, type DesignInput, type DesignResult, type DialogueRequest, type DialogueTurn, type DiscordSinkConfig, ELEVENLABS_DANISH_VOICES, type EmbeddingInput, type EmbeddingRequest, type EmbeddingResult, type ExtractInput, type ExtractResult, type FalAdapterConfig, type HttpResponse, type ImageInput, type ImageRequest, type ImageResult, type LoraWeight, type Message, type MockupInput, type MockupResult, type ModerationInput, type ModerationItem, type ModerationRequest, type ModerationResult, type OcrInput, type OcrPage, type OcrRequest, type OcrResult, type OpenAICompatibleConfig, type PodcastInput, type PodcastResult, type PricingEntry, type ProviderAdapter, type RefreshOptions, type RefreshResult, type RerankInput, type RerankResult, type Role, SDK_TAG, type SqliteBudgetStoreConfig, type SqliteSinkConfig, StreamHttpError, type SubprocessResponse, type Tier, type TierSpec, type Tool, type ToolCall, type TrainStyleInput, type TrainStyleRequest, type TrainStyleResult, type TranscribeInput, type TranscribeRequest, type TranscribeResult, type TranslateInput, type TranslateResult, type Transport, type TransportRequest, type TransportResponse, type TtsInput, type TtsRequest, type UpmetricsCostClientConfig, UpmetricsCostError, type UpmetricsCostRow, type UpmetricsCostSummary, type UpmetricsCostTimeseries, type UpmetricsSinkConfig, type Usage, VERSION, type VideoInput, type VisionInput, type VoiceInfo, type VoiceProvider, type VoiceResolveResult, type VoiceStatus, VoiceUnavailableError, aiConfigSchema, anthropicAdapter, anthropicApiAdapter, anthropicSubprocessAdapter, azureAdapter, bflAdapter, bflCredits, chatInputSchema, checkVoice, computeCost, createAI, deepinfraAdapter, deeplAdapter, deepseekAdapter, defaultProviders, discordSink, elevenlabsAdapter, embeddingInputSchema, falAdapter, falStubAdapter, freshUsage, fromProviderToolCall, geminiAdapter, getCostSummary, getPrice, httpTransport, imageInputSchema, listAzureDanishVoices, listVoices, makeContracts, makeOpenAICompatibleAdapter, messageSchema, mistralAdapter, mistralStubAdapter, multiSink, noopSink, openaiAdapter, openaiStubAdapter, openrouterAdapter, parseClaudeCliJson, parseJsonLoose, refreshAvailability, requestyAdapter, resetRefreshState, resetRegistry, resolveAzureVoice, resolveTier, resolveVoice, sqliteBudgetStore, sqliteSink, streamTransport, stubProviders, subprocessTransport, tierSpecSchema, toProviderTools, toolSchema, translateInputSchema, upmetricsCostClient, upmetricsSink, usdFromMicro, vertexAdapter, visionInputSchema };

package/dist/index.js

@@ -8,7 +8,7 @@ import {
 } from "./chunk-IT7HNKLY.js";
 import {
   getPrice
-} from "./chunk-IZG5UZH5.js";
+} from "./chunk-LUPUAAHZ.js";
 
 // src/routing/tier-map.ts
 var DEFAULT_TIER_MAP = {
@@ -1390,13 +1390,13 @@ function elevenlabsAdapter(config = {}) {
     const audio = new Uint8Array(await res.arrayBuffer());
     return { audio, mimeType: "audio/mpeg", usage: priceFor(req.text.length, model) };
   }
-  async function listVoices() {
+  async function listVoices2() {
     const res = await fetchImpl(`${baseUrl}/voices`, { headers: { "xi-api-key": key() } });
     if (!res.ok) throw new Error(`elevenlabs voices ${res.status}`);
     const data = await res.json();
     return (data.voices ?? []).map((v) => ({ voiceId: v.voice_id, name: v.name, language: v.labels?.language }));
   }
-  return { name: "elevenlabs", dialogue, tts, listVoices };
+  return { name: "elevenlabs", dialogue, tts, listVoices: listVoices2 };
 }
 
 // src/providers/azure.ts
@@ -1633,8 +1633,8 @@ function vertexAdapter(config = {}) {
     return config.region ?? process.env.GOOGLE_VERTEX_REGION ?? DEFAULT_REGION2;
   }
   function project() {
-    const p = config.project ?? process.env.GOOGLE_VERTEX_PROJECT;
-    if (!p) throw new Error("vertex adapter: project not set (config.project or env GOOGLE_VERTEX_PROJECT)");
+    const p = config.project ?? process.env.GOOGLE_VERTEX_PROJECT ?? resolveCredentials(config).project_id;
+    if (!p) throw new Error("vertex adapter: project not set (config.project, env GOOGLE_VERTEX_PROJECT, or project_id in the credentials)");
     return p;
   }
   async function accessToken() {
@@ -1710,7 +1710,47 @@ function vertexAdapter(config = {}) {
     usage.costUsd = perSec * (req.durationSec ?? 8);
     return { url: `vertex://${op.name}`, bytes: Buffer.from(videoB64, "base64"), mimeType: videoMime, usage };
   }
-  return { name: "vertex", animate };
+  async function vision(req) {
+    const token = await accessToken();
+    const proj = project();
+    const reg = region();
+    const systemParts = [];
+    const contents = [];
+    for (const m of req.messages) {
+      if (m.role === "system") systemParts.push(...partsFrom(m.content));
+      else contents.push({ role: m.role === "assistant" ? "model" : "user", parts: partsFrom(m.content) });
+    }
+    const body = { contents };
+    if (systemParts.length > 0) body.systemInstruction = { parts: systemParts };
+    const genConfig = {};
+    if (req.maxTokens !== void 0) genConfig.maxOutputTokens = req.maxTokens;
+    if (req.temperature !== void 0) genConfig.temperature = req.temperature;
+    if (Object.keys(genConfig).length > 0) body.generationConfig = genConfig;
+    const url = `https://${reg}-aiplatform.googleapis.com/v1/projects/${proj}/locations/${reg}/publishers/google/models/${req.spec.model}:generateContent`;
+    const res = await fetchImpl(url, {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      throw new Error(`vertex vision ${res.status}: ${(await res.text().catch(() => "")).slice(0, 300)}`);
+    }
+    const data = await res.json();
+    const text = (data.candidates?.[0]?.content?.parts ?? []).map((p) => p.text ?? "").join("").trim();
+    const inputTokens = data.usageMetadata?.promptTokenCount ?? 0;
+    const outputTokens = data.usageMetadata?.candidatesTokenCount ?? 0;
+    const usage = freshUsage({
+      provider: "vertex",
+      model: req.spec.model,
+      transport: "http",
+      capability: "vision",
+      inputTokens,
+      outputTokens
+    });
+    usage.costUsd = computeCost("vertex", req.spec.model, inputTokens, outputTokens);
+    return { text, usage };
+  }
+  return { name: "vertex", animate, vision };
 }
 
 // src/providers/deepl.ts
@@ -2409,6 +2449,143 @@ ${JSON.stringify(input.items)}`,
   };
 }
 
+// src/voices/registry.ts
+var CHECKED_AT = {
+  // All 5 curated ids confirmed by SYNTHESIS — POST /v1/text-to-speech/{id} returned
+  // 200 with distinct audio per voice (5 distinct sha256), and a fabricated id
+  // returned 404, so a 200 means something.
+  //
+  // NB: GET /v1/voices/{id} is NOT a liveness test and must not be used as one. It
+  // answers "is this voice saved in our account", and returns voice_not_found for a
+  // public/shared voice that synthesizes perfectly well. Using it cost us a false
+  // retirement (see the note on `mads` below) — the only honest liveness check for
+  // ElevenLabs is a real synthesis call, which is exactly why v1 does no live check.
+  elevenlabs: "2026-08-11",
+  // F026 (6ca38c4) verified the 6 curated names against Azure's voices/list. Not
+  // re-probed since: this machine has no Azure Speech key, and inventing a fresher
+  // date than the last real check is exactly the lie checkedAt exists to prevent.
+  azure: "2026-06-23"
+};
+var RETIRED_DEFAULT = {};
+var RETIRED = RETIRED_DEFAULT;
+var ELEVENLABS_GENDER = {
+  soren: "male",
+  jesper: "male",
+  noam: "male",
+  camilla: "female"
+};
+var NOTES = {
+  mads: "usable, but not saved to the ElevenLabs account, so the voices endpoint publishes no metadata for it (verified by synthesis 2026-08-11)"
+};
+function build() {
+  const rows = [];
+  for (const [name, id] of Object.entries(ELEVENLABS_DANISH_VOICES)) {
+    const retired = RETIRED[name];
+    rows.push({
+      id,
+      name,
+      provider: "elevenlabs",
+      // The curated ElevenLabs roster IS the Danish one (see the constant's name
+      // + F020); the multilingual model speaks it as da-DK.
+      locale: "da-DK",
+      gender: ELEVENLABS_GENDER[name],
+      available: retired === void 0,
+      status: retired === void 0 ? "available" : "retired",
+      note: retired ?? NOTES[name],
+      checkedAt: CHECKED_AT.elevenlabs
+    });
+  }
+  for (const v of AZURE_DANISH_VOICE_LIST) {
+    const retired = RETIRED[v.name];
+    rows.push({
+      id: v.voiceId,
+      name: v.name,
+      provider: "azure",
+      locale: localeOf(v.voiceId),
+      gender: v.gender,
+      available: retired === void 0,
+      status: retired === void 0 ? "available" : "retired",
+      note: retired ?? NOTES[v.name],
+      checkedAt: CHECKED_AT.azure
+    });
+  }
+  return rows;
+}
+var ROWS = build();
+function allVoices(provider) {
+  return provider ? ROWS.filter((v) => v.provider === provider) : [...ROWS];
+}
+function getVoice(nameOrId) {
+  return ROWS.find((v) => v.name === nameOrId || v.id === nameOrId);
+}
+
+// src/voices/types.ts
+var VoiceUnavailableError = class extends Error {
+  code = "voice_unavailable";
+  requested;
+  provider;
+  note;
+  constructor(requested, note, provider) {
+    super(`voice "${requested}" is unavailable${note ? ` (${note})` : ""}`);
+    this.name = "VoiceUnavailableError";
+    this.requested = requested;
+    this.note = note;
+    this.provider = provider;
+  }
+};
+
+// src/voices/resolve.ts
+function listVoices(opts = {}) {
+  return allVoices(opts.provider);
+}
+function usable(nameOrId) {
+  const v = getVoice(nameOrId);
+  return v ? v.available : true;
+}
+function idFor(nameOrId) {
+  return getVoice(nameOrId)?.id ?? nameOrId;
+}
+function checkVoice(requested, opts = {}) {
+  const entry = getVoice(requested);
+  const provider = entry?.provider;
+  if (usable(requested)) {
+    return {
+      ok: true,
+      voiceId: idFor(requested),
+      requested,
+      provider,
+      fellBack: false,
+      status: entry?.status ?? "unknown"
+    };
+  }
+  const chain = opts.fallback === void 0 ? [] : Array.isArray(opts.fallback) ? opts.fallback : [opts.fallback];
+  for (const fb of chain) {
+    if (usable(fb)) {
+      return {
+        ok: false,
+        voiceId: idFor(fb),
+        requested,
+        provider: getVoice(fb)?.provider ?? provider,
+        fellBack: true,
+        status: entry?.status ?? "retired",
+        reason: entry?.note ?? `${requested} is unavailable`
+      };
+    }
+  }
+  if (opts.throwIfUnavailable) {
+    throw new VoiceUnavailableError(requested, entry?.note, provider);
+  }
+  return {
+    ok: false,
+    voiceId: idFor(requested),
+    requested,
+    provider,
+    fellBack: false,
+    status: entry?.status ?? "retired",
+    reason: entry?.note ?? `${requested} is unavailable`
+  };
+}
+
 // src/schema/inputs.ts
 import { z } from "zod";
 var transportSchema = z.enum(["http", "subprocess"]);
@@ -2583,6 +2760,9 @@ var podcastInputSchema = z.object({
 var ttsInputSchema = z.object({
   text: z.string(),
   voice: z.string(),
+  /** F037: voice to use if `voice` is one we know the provider has retired. Without
+   *  it a retired voice throws VoiceUnavailableError rather than reaching the API. */
+  voiceFallback: z.string().optional(),
   lang: z.string().optional(),
   format: z.string().optional(),
   rate: z.number().positive().optional(),
@@ -2610,8 +2790,8 @@ var aiConfigSchema = z.object({
 });
 
 // src/version.ts
-var VERSION = "0.26.0";
-var SDK_TAG = "@broberg/ai-sdk@0.26.0";
+var VERSION = "0.28.0";
+var SDK_TAG = "@broberg/ai-sdk@0.28.0";
 
 // src/cost/sinks/upmetrics.ts
 function upmetricsSink(config) {
@@ -3093,7 +3273,9 @@ function createAI(config = {}) {
       const inputs = input.script.map((turn) => {
         const mapped = input.voices[turn.speaker];
         if (!mapped) throw new Error(`ai.podcast: no voice mapped for speaker "${turn.speaker}"`);
-        return { text: turn.text, voiceId: resolveVoice(mapped) };
+        const res = checkVoice(mapped);
+        if (!res.ok) throw new VoiceUnavailableError(mapped, `${res.reason} \u2014 speaker "${turn.speaker}"`, res.provider);
+        return { text: turn.text, voiceId: res.voiceId };
       });
       const chars = input.script.reduce((n, t) => n + t.text.length, 0);
       return runCapability({
@@ -3114,6 +3296,7 @@ function createAI(config = {}) {
     },
     async tts(input) {
       input = ttsInputSchema.parse(input);
+      const { voiceId } = checkVoice(input.voice, { fallback: input.voiceFallback, throwIfUnavailable: true });
       return runCapability({
         primary: { ...DEFAULT_TTS_SPEC, ...input.override },
         fallback: input.fallback,
@@ -3126,7 +3309,7 @@ function createAI(config = {}) {
         invoke: async (spec) => {
           const adapter = pickProvider(spec.provider);
           if (!adapter.tts) throw new Error(`createAI: provider "${spec.provider}" does not support tts`);
-          return adapter.tts({ text: input.text, voiceId: resolveVoice(input.voice), lang: input.lang, format: input.format, rate: input.rate, spec });
+          return adapter.tts({ text: input.text, voiceId, lang: input.lang, format: input.format, rate: input.rate, spec });
         }
       });
     },
@@ -3574,6 +3757,7 @@ export {
   StreamHttpError,
   UpmetricsCostError,
   VERSION,
+  VoiceUnavailableError,
   aiConfigSchema,
   anthropicAdapter,
   anthropicApiAdapter,
@@ -3582,6 +3766,7 @@ export {
   bflAdapter,
   bflCredits,
   chatInputSchema,
+  checkVoice,
   computeCost,
   createAI,
   deepinfraAdapter,
@@ -3602,6 +3787,7 @@ export {
   imageInputSchema,
   listAzureDanishVoices,
   listModels,
+  listVoices,
   makeContracts,
   makeOpenAICompatibleAdapter,
   messageSchema,