@crossworks/voice-client 0.230.43

package/src/catalog.ts

@@ -0,0 +1,237 @@
+/**
+ * Catalog of TTS / STT models + voices, per provider.
+ *
+ * Why a static catalog at all: OpenAI does NOT expose a programmatic
+ * endpoint to list voices. `/v1/audio/voices` doesn't exist; the voice
+ * list is documentation-only and changes when OpenAI ships new models.
+ * We keep the mapping in code so the UI can render a smart dropdown
+ * (model selected → voices for that model appear) without each page
+ * load having to scrape docs.
+ *
+ * What IS queryable: `/v1/models` returns the model ids the key has
+ * access to (alongside chat/embedding models). We cross-reference our
+ * catalog with that list to show ONLY the models the user can
+ * actually use — accounts on the free tier, or older keys, don't
+ * always have every model available.
+ *
+ * Maintenance: when OpenAI releases a new TTS model, add it here. The
+ * UI doesn't need a code change as long as the catalog is current.
+ *
+ * Other providers (ElevenLabs, Deepgram) get their own catalog entries
+ * when we implement them. ElevenLabs unlike OpenAI HAS a /v1/voices
+ * endpoint that returns the full list (including user-cloned voices),
+ * so for that provider we'd skip the static catalog and query live.
+ */
+
+import type { TtsVoice } from './types';
+
+/** Every voice OpenAI has ever shipped (across all TTS models). Kept
+ *  as the source-of-truth string union so other modules don't have to
+ *  reconcile names. */
+export const ALL_OPENAI_VOICES = [
+  // Original 6 (tts-1, tts-1-hd).
+  'alloy',
+  'echo',
+  'fable',
+  'nova',
+  'onyx',
+  'shimmer',
+  // Added with later expansions — usable by tts-1, tts-1-hd, gpt-4o-mini-tts.
+  'ash',
+  'coral',
+  'sage',
+  // Newer voices — only on gpt-4o-mini-tts.
+  'ballad',
+  'verse',
+  // "Best quality" voices — gpt-4o-mini-tts only.
+  'marin',
+  'cedar',
+] as const;
+
+export type OpenAiVoice = (typeof ALL_OPENAI_VOICES)[number];
+
+/** Short, human-readable description per voice. Used in the UI
+ *  dropdown so the operator doesn't have to test all 13 to find the
+ *  warm female voice. Pulled from OpenAI's published descriptions. */
+export const VOICE_DESCRIPTIONS: Record<OpenAiVoice, string> = {
+  alloy: 'neutral, balanced',
+  ash: 'warm, expressive',
+  ballad: 'reflective, narrative',
+  cedar: 'high-quality, natural (recommended)',
+  coral: 'warm, friendly female',
+  echo: 'male, calm',
+  fable: 'British, warm',
+  marin: 'high-quality, natural (recommended)',
+  nova: 'warm, female (Saskia default)',
+  onyx: 'deep male, grounded',
+  sage: 'measured, thoughtful',
+  shimmer: 'soft, female',
+  verse: 'expressive, emotive',
+};
+
+/** A model entry: what it is, which voices it supports, and which
+ *  feature flags are on. */
+export type TtsModelInfo = {
+  id: string;
+  label: string;
+  description: string;
+  /** Voice ids the model accepts. OpenAI ships a narrow named union
+   *  (alloy/nova/shimmer/…); xAI ships their own (eve/ara/rex/sal/leo);
+   *  Gemini ships 30 (Kore/Puck/Zephyr/…); ElevenLabs ships UUIDs and
+   *  per-account clones. We type this as `readonly string[]` so each
+   *  provider's adapter can return its own list without union-widening
+   *  the framework. Consumers treating these as `OpenAiVoice` for
+   *  type-narrowing have always known to runtime-check anyway. */
+  voices: readonly string[];
+  /** Whether the model accepts a free-form `instructions` parameter for
+   *  style steering ("speak warmly", "be calm"). Only true for
+   *  gpt-4o-mini-tts at the moment. */
+  supportsInstructions: boolean;
+  /** Tier hint for cost display. */
+  tier: 'low-latency' | 'high-quality' | 'steerable';
+};
+
+/** TTS catalog. Order matters — list shown to users in this order in
+ *  the dropdown. */
+export const OPENAI_TTS_MODELS: readonly TtsModelInfo[] = [
+  {
+    id: 'gpt-4o-mini-tts',
+    label: 'gpt-4o-mini-tts',
+    description:
+      'Newest TTS model. 13 voices, accepts style instructions ("speak warmly"). Recommended.',
+    voices: [
+      'alloy',
+      'ash',
+      'ballad',
+      'coral',
+      'echo',
+      'fable',
+      'nova',
+      'onyx',
+      'sage',
+      'shimmer',
+      'verse',
+      'marin',
+      'cedar',
+    ],
+    supportsInstructions: true,
+    tier: 'steerable',
+  },
+  {
+    id: 'tts-1',
+    label: 'tts-1',
+    description: 'Original TTS model. 9 voices, low latency. Cheaper than gpt-4o-mini-tts.',
+    voices: ['alloy', 'ash', 'coral', 'echo', 'fable', 'nova', 'onyx', 'sage', 'shimmer'],
+    supportsInstructions: false,
+    tier: 'low-latency',
+  },
+  {
+    id: 'tts-1-hd',
+    label: 'tts-1-hd',
+    description: 'Higher-quality variant of tts-1. Same 9 voices, higher fidelity, ~2× cost.',
+    voices: ['alloy', 'ash', 'coral', 'echo', 'fable', 'nova', 'onyx', 'sage', 'shimmer'],
+    supportsInstructions: false,
+    tier: 'high-quality',
+  },
+] as const;
+
+export type SttModelInfo = {
+  id: string;
+  label: string;
+  description: string;
+  /** Whether this model accepts the `language` hint param. */
+  supportsLanguageHint: boolean;
+  /** Whether this model returns word-level timestamps. */
+  supportsTimestamps: boolean;
+};
+
+/** STT catalog. As of May 2026 OpenAI ships whisper-1 alongside the
+ *  newer gpt-4o-mini-transcribe / gpt-4o-transcribe variants which
+ *  are higher-quality but cost more. */
+export const OPENAI_STT_MODELS: readonly SttModelInfo[] = [
+  {
+    id: 'whisper-1',
+    label: 'whisper-1',
+    description: 'Stable, cheap. Excellent multilingual support including Afrikaans.',
+    supportsLanguageHint: true,
+    supportsTimestamps: true,
+  },
+  {
+    id: 'gpt-4o-mini-transcribe',
+    label: 'gpt-4o-mini-transcribe',
+    description: 'Newer transcription model. Better accuracy than whisper-1, similar price.',
+    supportsLanguageHint: true,
+    supportsTimestamps: false,
+  },
+  {
+    id: 'gpt-4o-transcribe',
+    label: 'gpt-4o-transcribe',
+    description: 'Highest-accuracy transcription. Costs more; best for difficult audio.',
+    supportsLanguageHint: true,
+    supportsTimestamps: false,
+  },
+] as const;
+
+/** Look up a TTS model by id. Returns null if we don't know about it
+ *  (e.g. user typed a custom model name in the form). Callers should
+ *  fall back to a permissive default voice list in that case. */
+export function getTtsModel(id: string): TtsModelInfo | null {
+  return OPENAI_TTS_MODELS.find((m) => m.id === id) ?? null;
+}
+
+export function getSttModel(id: string): SttModelInfo | null {
+  return OPENAI_STT_MODELS.find((m) => m.id === id) ?? null;
+}
+
+/** Type-narrowing helper: is this voice valid for OpenAI? Used by the
+ *  form validator and the synth call. */
+export function isOpenAiVoice(v: string): v is OpenAiVoice {
+  return (ALL_OPENAI_VOICES as readonly string[]).includes(v);
+}
+
+/** All voices, with descriptions, for a given model. Returned in a
+ *  stable order matching the catalog. If the model isn't in the
+ *  catalog, returns an empty array (caller decides whether to fall
+ *  back to the legacy 6-voice list from @mantle/voice/types). */
+export function voicesForModel(modelId: string): Array<{ id: OpenAiVoice; description: string }> {
+  const model = getTtsModel(modelId);
+  if (!model) return [];
+  // OPENAI_TTS_MODELS only lists OpenAI voice ids by construction —
+  // the runtime cast is safe because we narrow via getTtsModel which
+  // only returns OpenAI catalog entries.
+  return model.voices.map((v) => ({
+    id: v as OpenAiVoice,
+    description: VOICE_DESCRIPTIONS[v as OpenAiVoice] ?? '',
+  }));
+}
+
+// Bridge to the existing TtsVoice union in types.ts — keeps backward
+// compat with code already using that narrower type. New code should
+// prefer OpenAiVoice for forward-compat with the expanded voice set.
+void ([] as TtsVoice[]);
+
+export type DiscoveryResult<T> = {
+  /** The catalog entries the key can actually use, in catalog order. */
+  available: T[];
+  /** True if the live filter succeeded; false if we fell back to the
+   *  full catalog because the API call failed. The UI surfaces a hint
+   *  in that case ("couldn't verify; showing everything"). */
+  filtered: boolean;
+  /** When `filtered=false`, the reason. Null on success. */
+  error: string | null;
+  /**
+   * EVERY model id the provider reported, before we intersected it with our
+   * catalog. Optional: only the adapters that curate a static catalog and
+   * filter it need to set this.
+   *
+   * It exists because `available` answers "which of OUR models are live?" and
+   * deliberately discards the other half of the answer — "which of THEIRS
+   * aren't ours?" That discarded half is the only automatic signal that a
+   * catalog has gone stale, and we were computing it on every discovery call
+   * and dropping it. grok-4.5 shipped, our dropdown never mentioned it, and
+   * nothing anywhere could have said so.
+   *
+   * Consumed by `pnpm -C server/web models:drift`. See {@link catalogDrift}.
+   */
+  liveIds?: string[];
+};

package/src/catalogs/anthropic.ts

@@ -0,0 +1,135 @@
+/**
+ * Anthropic (Claude) static catalog.
+ *
+ * Anthropic's API is NOT OpenAI-compatible. It uses its own message
+ * format (system is a separate top-level field, messages contain only
+ * user/assistant roles) at `https://api.anthropic.com/v1/messages`.
+ * The adapter handles translation to/from the unified ChatDispatcher
+ * interface so callers don't have to care.
+ *
+ * Auth: `x-api-key` header + a required `anthropic-version` header
+ * (we pin to 2023-06-01 since that's the stable API). The Models API
+ * at GET /v1/messages/../v1/models returns the live model list with
+ * capabilities — we use it for discovery but the catalog below is
+ * the source of truth for rich UI metadata.
+ *
+ * Maintenance: when Anthropic ships a new Claude generation (e.g.
+ * 4.8 or 5.0), add it here. Anthropic uses dateless aliases for
+ * 4.6+ (no more 'claude-3-5-sonnet-20241022' style), so model ids
+ * stay readable.
+ */
+
+import type { ChatModelInfo, VisionModelInfo } from '../adapters/types';
+
+export const ANTHROPIC_BASE_URL = 'https://api.anthropic.com';
+/** Required header value on all Anthropic API calls. */
+export const ANTHROPIC_API_VERSION = '2023-06-01';
+
+export const ANTHROPIC_CHAT_MODELS: readonly ChatModelInfo[] = [
+  // ── Current generation (4.6/4.7) ─────────────────────────────────
+  {
+    id: 'claude-opus-4-7',
+    label: 'Claude Opus 4.7',
+    description: 'Anthropic flagship. Best for complex reasoning + agentic coding. 1M context.',
+    contextTokens: 1_000_000,
+    capabilities: ['vision', 'reasoning', 'function_calling'],
+    inputPricePer1M: 5,
+    outputPricePer1M: 25,
+  },
+  {
+    id: 'claude-sonnet-5',
+    label: 'Claude Sonnet 5',
+    description:
+      'Best speed/intelligence balance — newer and cheaper than 4.6. 1M context, supports extended thinking. Default choice.',
+    contextTokens: 1_000_000,
+    capabilities: ['vision', 'reasoning', 'function_calling'],
+    inputPricePer1M: 2,
+    outputPricePer1M: 10,
+  },
+  {
+    id: 'claude-sonnet-4-6',
+    label: 'Claude Sonnet 4.6',
+    description: 'Previous-generation Sonnet. 1M context, supports extended thinking.',
+    contextTokens: 1_000_000,
+    capabilities: ['vision', 'reasoning', 'function_calling'],
+    inputPricePer1M: 3,
+    outputPricePer1M: 15,
+  },
+  {
+    id: 'claude-haiku-4-5',
+    label: 'Claude Haiku 4.5',
+    description:
+      'Fastest model with near-frontier intelligence. 200k context. Great for cheap, fast jobs.',
+    contextTokens: 200_000,
+    capabilities: ['vision', 'reasoning', 'function_calling'],
+    inputPricePer1M: 1,
+    outputPricePer1M: 5,
+  },
+
+  // ── Legacy (still available, slightly cheaper or different trade-offs) ──
+  {
+    id: 'claude-opus-4-6',
+    label: 'Claude Opus 4.6 (legacy)',
+    description: 'Previous Opus generation. Migrate to 4.7 for best results.',
+    contextTokens: 1_000_000,
+    capabilities: ['vision', 'reasoning', 'function_calling'],
+    inputPricePer1M: 5,
+    outputPricePer1M: 25,
+  },
+  {
+    id: 'claude-sonnet-4-5',
+    label: 'Claude Sonnet 4.5 (legacy)',
+    description: 'Previous Sonnet generation. Still capable; 200k context.',
+    contextTokens: 200_000,
+    capabilities: ['vision', 'reasoning', 'function_calling'],
+    inputPricePer1M: 3,
+    outputPricePer1M: 15,
+  },
+];
+
+/** Vision-capable Claude models. Every current Claude model accepts
+ *  image content blocks, but we surface a smaller curated set for the
+ *  vision-worker dropdown — Haiku for cheap high-volume OCR, Sonnet
+ *  for balanced quality, Opus when accuracy on hard handwriting
+ *  matters more than cost. Opus is over-the-top for printed text. */
+export const ANTHROPIC_VISION_MODELS: readonly VisionModelInfo[] = [
+  {
+    id: 'claude-haiku-4-5',
+    label: 'Claude Haiku 4.5',
+    description:
+      'Cheap, fast vision. Solid on printed text and clean handwriting. Default choice for high-volume OCR.',
+    contextTokens: 200_000,
+    inputPricePer1M: 1,
+    outputPricePer1M: 5,
+    tier: 'fast',
+  },
+  {
+    id: 'claude-sonnet-5',
+    label: 'Claude Sonnet 5',
+    description:
+      'Best balance. Strong on messy handwriting + multi-column layouts. Recommended for note photos.',
+    contextTokens: 1_000_000,
+    inputPricePer1M: 2,
+    outputPricePer1M: 10,
+    tier: 'balanced',
+  },
+  {
+    id: 'claude-sonnet-4-6',
+    label: 'Claude Sonnet 4.6',
+    description: 'Previous-generation Sonnet vision. Still strong on documents.',
+    contextTokens: 1_000_000,
+    inputPricePer1M: 3,
+    outputPricePer1M: 15,
+    tier: 'balanced',
+  },
+  {
+    id: 'claude-opus-4-7',
+    label: 'Claude Opus 4.7',
+    description:
+      'Frontier. Use when Sonnet misreads cursive or you need diagram comprehension alongside text. Pricey.',
+    contextTokens: 1_000_000,
+    inputPricePer1M: 5,
+    outputPricePer1M: 25,
+    tier: 'quality',
+  },
+];

package/src/catalogs/assemblyai.ts

@@ -0,0 +1,54 @@
+/**
+ * AssemblyAI static catalog.
+ *
+ * AssemblyAI's transcription API is a two-step async job:
+ *   1. POST /v2/upload   — binary body, returns a temporary upload URL.
+ *   2. POST /v2/transcript with `{audio_url, speech_model, language_code}`
+ *      — returns a transcript id with status='queued' or 'processing'.
+ *   3. Poll GET /v2/transcript/{id} until status='completed' (or 'error').
+ *
+ * Because of step 3, AssemblyAI is unsuitable for ultra-low-latency
+ * use cases — the round trip for a short voice note is 2-5 seconds
+ * even when the model itself is fast. We use it when the operator
+ * specifically wants diarization or sentiment, which AssemblyAI
+ * exposes alongside the base transcript.
+ *
+ * Speech models (May 2026): the "universal" tier is the current
+ * default; "best" and "nano" are documented but billing tiers vary by
+ * account. We surface the documented values; the adapter passes the
+ * id through to AssemblyAI as `speech_model` in the request body.
+ */
+
+import type { SttModelInfo } from '../catalog';
+
+export const ASSEMBLYAI_BASE_URL = 'https://api.assemblyai.com';
+
+/** Hard cap on polling — if the transcript isn't done after this many
+ *  seconds, the adapter gives up rather than blocking the test action
+ *  forever. AssemblyAI's docs say 95% of jobs finish in under 35s for
+ *  audio under 5 minutes, so 60s is a generous upper bound. */
+export const ASSEMBLYAI_POLL_TIMEOUT_SECONDS = 60;
+
+export const ASSEMBLYAI_STT_MODELS: readonly SttModelInfo[] = [
+  {
+    id: 'universal',
+    label: 'Universal',
+    description: 'Default tier. Balanced accuracy + speed, 99 languages.',
+    supportsLanguageHint: true,
+    supportsTimestamps: true,
+  },
+  {
+    id: 'best',
+    label: 'Best',
+    description: 'Highest-accuracy tier. Slower + pricier than universal; good for hard audio.',
+    supportsLanguageHint: true,
+    supportsTimestamps: true,
+  },
+  {
+    id: 'nano',
+    label: 'Nano',
+    description: 'Cheap, fast, lower accuracy. Use for clean audio at scale.',
+    supportsLanguageHint: true,
+    supportsTimestamps: true,
+  },
+] as const;

package/src/catalogs/copilot.ts

@@ -0,0 +1,63 @@
+/**
+ * GitHub Copilot static catalog.
+ *
+ * Copilot exposes an OpenAI-compatible `/chat/completions` endpoint at
+ * `api.githubcopilot.com` that fronts a rotating roster of frontier models
+ * (GPT, Claude, Gemini, o-series) under one subscription. The adapter at
+ * `../adapters/copilot-chat.ts` reuses the shared openai-compat helpers and
+ * adds Copilot's token exchange + editor headers (see `copilot-auth.ts`).
+ *
+ * Auth: the worker's "API key" is a GitHub OAuth token (the Copilot device-flow
+ * token, `gho_…`); the adapter exchanges it for a short-lived Copilot token.
+ *
+ * The roster changes often and is gated by the account's Copilot plan, so live
+ * discovery (`GET /models`) is authoritative — this list is just what the model
+ * dropdown shows before discovery returns. Reasoning models carry the
+ * 'reasoning' capability; the adapter requests reasoning via `reasoning_effort`
+ * when the thinking budget is set. Prices are omitted (Copilot bills by
+ * subscription / request quota, not per-token).
+ */
+
+import type { ChatModelInfo } from '../adapters/types';
+
+export const COPILOT_BASE_URL = 'https://api.githubcopilot.com';
+
+export const COPILOT_CHAT_MODELS: readonly ChatModelInfo[] = [
+  {
+    id: 'gpt-5',
+    label: 'GPT-5 (Copilot)',
+    description:
+      'OpenAI GPT-5 via GitHub Copilot. Reasoning model — depth set by reasoning_effort.',
+    contextTokens: 264_000,
+    capabilities: ['reasoning', 'function_calling', 'vision'],
+  },
+  {
+    id: 'gpt-5-mini',
+    label: 'GPT-5 mini (Copilot)',
+    description: 'Faster, cheaper GPT-5 tier via Copilot. Reasoning-capable.',
+    contextTokens: 264_000,
+    capabilities: ['reasoning', 'function_calling'],
+  },
+  {
+    id: 'claude-sonnet-4.5',
+    label: 'Claude Sonnet 4.5 (Copilot)',
+    description:
+      'Anthropic Claude Sonnet 4.5 via Copilot. Strong agentic + tool use, reasoning-capable.',
+    contextTokens: 200_000,
+    capabilities: ['reasoning', 'function_calling', 'vision'],
+  },
+  {
+    id: 'o4-mini',
+    label: 'o4-mini (Copilot)',
+    description: 'OpenAI o4-mini reasoning model via Copilot. Fast reasoning for tool-heavy work.',
+    contextTokens: 200_000,
+    capabilities: ['reasoning', 'function_calling'],
+  },
+  {
+    id: 'gemini-2.5-pro',
+    label: 'Gemini 2.5 Pro (Copilot)',
+    description: 'Google Gemini 2.5 Pro via Copilot. Large context, reasoning-capable.',
+    contextTokens: 1_000_000,
+    capabilities: ['reasoning', 'function_calling', 'vision'],
+  },
+];

package/src/catalogs/deepgram.ts

@@ -0,0 +1,61 @@
+/**
+ * Deepgram static catalog.
+ *
+ * Deepgram's transcription API is shaped quite differently from
+ * OpenAI's:
+ *   - Endpoint: POST https://api.deepgram.com/v1/listen
+ *   - Auth: `Authorization: Token <api-key>` (not Bearer)
+ *   - Body: raw audio bytes (NOT multipart) — Content-Type header
+ *     carries the mime so Deepgram knows the codec.
+ *   - Model + language + features go as URL query params, not body
+ *     fields. E.g. `?model=nova-3&language=en&smart_format=true`.
+ *
+ * Models below mirror the documented "general" line as of May 2026.
+ * Nova-3 is the current flagship. Older nova-2 is kept around for
+ * cost-sensitive callers; enhanced/base are legacy tiers some
+ * accounts still default to.
+ *
+ * Discovery: Deepgram has a `/v1/projects/{id}/models` endpoint, but
+ * it requires the project id alongside the API key — and the project
+ * id isn't carried by api_keys today (just the key string). We skip
+ * live discovery and ship the static catalog. Operators can type a
+ * custom model id in the form if a new variant ships before the
+ * catalog is updated.
+ */
+
+import type { SttModelInfo } from '../catalog';
+
+export const DEEPGRAM_BASE_URL = 'https://api.deepgram.com';
+
+export const DEEPGRAM_STT_MODELS: readonly SttModelInfo[] = [
+  {
+    id: 'nova-3',
+    label: 'Nova 3',
+    description:
+      'Current flagship. Best accuracy across 36 languages, lowest latency in the lineup.',
+    supportsLanguageHint: true,
+    supportsTimestamps: true,
+  },
+  {
+    id: 'nova-2',
+    label: 'Nova 2',
+    description:
+      'Previous-gen flagship. Slightly lower accuracy than Nova 3 but cheaper per minute.',
+    supportsLanguageHint: true,
+    supportsTimestamps: true,
+  },
+  {
+    id: 'enhanced',
+    label: 'Enhanced',
+    description: 'Legacy tier. Use Nova 3 unless you have a contract reason to pin this.',
+    supportsLanguageHint: true,
+    supportsTimestamps: true,
+  },
+  {
+    id: 'base',
+    label: 'Base',
+    description: 'Cheapest tier; lowest accuracy. Fine for clean studio audio.',
+    supportsLanguageHint: true,
+    supportsTimestamps: true,
+  },
+] as const;

package/src/catalogs/deepseek.ts

@@ -0,0 +1,85 @@
+/**
+ * DeepSeek static catalog.
+ *
+ * DeepSeek's API is OpenAI-compatible — same `/chat/completions` shape,
+ * snake_case fields, tool_calls + tool_call_id, image_url for vision.
+ * The adapter at `../adapters/deepseek-chat.ts` reuses the shared
+ * `toOpenAICompatMessages` / `extractOpenAICompatToolCalls` helpers
+ * from openai-compat.ts.
+ *
+ * **One non-standard quirk worth flagging here:** DeepSeek surfaces
+ * prompt-cache hits as TOP-LEVEL `usage.prompt_cache_hit_tokens` and
+ * `usage.prompt_cache_miss_tokens` fields — NOT the OpenAI-compat
+ * `usage.prompt_tokens_details.cached_tokens` shape that xAI / HF
+ * sub-providers use. The adapter handles this in its own usage
+ * extraction; can't reuse a shared helper for this part. Reference:
+ * https://api-docs.deepseek.com/guides/kv_cache.
+ *
+ * Caching is AUTOMATIC: no cache_control markers needed. Prefix
+ * matches trigger cache hits server-side, billed at ~2% of the
+ * fresh-input rate (an enormous discount vs. Anthropic's ~10%).
+ *
+ * Maintenance: when DeepSeek deprecates `deepseek-chat` /
+ * `deepseek-reasoner` (announced for 2026-07-24), drop them from this
+ * list — they're kept here for now so existing workers that picked
+ * them keep showing in the dropdown.
+ */
+
+import type { ChatModelInfo } from '../adapters/types';
+
+export const DEEPSEEK_BASE_URL = 'https://api.deepseek.com';
+
+export const DEEPSEEK_CHAT_MODELS: readonly ChatModelInfo[] = [
+  // ── Current generation (V4) ──────────────────────────────────────
+  {
+    id: 'deepseek-v4-pro',
+    label: 'DeepSeek V4 Pro',
+    description:
+      'DeepSeek flagship. Strong reasoning + tool use, 1M context. ' +
+      'Automatic prompt caching surfaces ~2% cache-hit rate (extreme ' +
+      'savings on re-sent prefixes). Promo pricing through 2026-05-31.',
+    contextTokens: 1_000_000,
+    capabilities: ['reasoning', 'function_calling'],
+    inputPricePer1M: 0.435,
+    outputPricePer1M: 0.87,
+  },
+  {
+    id: 'deepseek-v4-flash',
+    label: 'DeepSeek V4 Flash',
+    description:
+      'DeepSeek fast/cheap. 1M context, automatic prompt caching. ' +
+      'Bargain pricing — fits well for high-volume extractor / ' +
+      'summarizer workloads.',
+    contextTokens: 1_000_000,
+    capabilities: ['function_calling'],
+    inputPricePer1M: 0.14,
+    outputPricePer1M: 0.28,
+  },
+  // ── Legacy aliases (deprecated 2026-07-24) ───────────────────────
+  // Kept so existing workers configured for these slugs keep working
+  // until the deprecation date. New workers should pick a V4 model
+  // above instead.
+  {
+    id: 'deepseek-chat',
+    label: 'DeepSeek Chat (legacy)',
+    description:
+      'Legacy alias for deepseek-v4-flash non-thinking mode. ' +
+      'Deprecated 2026-07-24 — migrate to deepseek-v4-flash.',
+    contextTokens: 1_000_000,
+    capabilities: ['function_calling'],
+    inputPricePer1M: 0.14,
+    outputPricePer1M: 0.28,
+  },
+  {
+    id: 'deepseek-reasoner',
+    label: 'DeepSeek Reasoner (legacy)',
+    description:
+      'Legacy alias for deepseek-v4-flash thinking mode. ' +
+      'Deprecated 2026-07-24 — migrate to deepseek-v4-pro for ' +
+      'reasoning workloads.',
+    contextTokens: 1_000_000,
+    capabilities: ['reasoning', 'function_calling'],
+    inputPricePer1M: 0.14,
+    outputPricePer1M: 0.28,
+  },
+];