@crossworks/voice-client 0.230.43

package/src/catalogs/xai.ts

@@ -0,0 +1,330 @@
+/**
+ * xAI (Grok) static catalog.
+ *
+ * The xAI docs don't officially publish a /v1/models programmatic
+ * listing — operators have to consult the console. We mirror what's
+ * documented at https://docs.x.ai/developers/models so the dropdown
+ * has rich descriptions and capability flags. The adapter still
+ * attempts a live `GET /v1/models` call (the API is OpenAI-compatible
+ * so it almost always implements it), and if that succeeds we
+ * intersect with this catalog to narrow to "what this key can use."
+ *
+ * Maintenance: when xAI ships a new Grok variant, add an entry here.
+ * Anything missing falls through to plain text-input ("Custom model
+ * id — make sure your key has access") rather than blocking the user.
+ * `pnpm -C server/web models:drift` reports what xAI serves that this
+ * file doesn't list — grok-4.5 went unlisted long enough to be found by
+ * reading @ai-sdk/xai's model union, which is what prompted that task.
+ *
+ * ⚠️ Pricing here is the SUB-200k-prompt tier. xAI doubles both rates
+ * once the prompt crosses 200k tokens, and `ChatModelInfo` carries one
+ * rate per direction, so a long-context turn costs twice what the cost
+ * dashboard attributes to it. Noted per-model where the window makes
+ * that reachable.
+ *
+ * Pricing reference (August 2026 docs, https://docs.x.ai/docs/models):
+ * grok-4.5 = $2.00/$6.00 per 1M, 500k context. grok-4.3 = $1.25/$2.50,
+ * 1M context. Older grok-3 variants redirect to grok-4.3 since May 15.
+ */
+
+import type { ChatModelInfo } from '../adapters/types';
+
+export const XAI_CHAT_MODELS: readonly ChatModelInfo[] = [
+  {
+    id: 'grok-4.5',
+    label: 'Grok 4.5',
+    description:
+      "xAI's most capable model. reasoning_effort steers depth here and cannot be disabled. Rates DOUBLE above a 200k-token prompt ($4.00/$12.00), which its 500k window makes easy to reach.",
+    contextTokens: 500_000,
+    capabilities: ['vision', 'function_calling', 'json_mode', 'reasoning'],
+    inputPricePer1M: 2.0,
+    outputPricePer1M: 6.0,
+  },
+  {
+    id: 'grok-4.3',
+    label: 'Grok 4.3',
+    description:
+      'Aliased from any deprecated grok-3/4 model id. Rates double above a 200k-token prompt ($2.50/$5.00).',
+    contextTokens: 1_000_000,
+    capabilities: ['vision', 'function_calling', 'json_mode'],
+    inputPricePer1M: 1.25,
+    outputPricePer1M: 2.5,
+  },
+  {
+    id: 'grok-4.20-0309-reasoning',
+    label: 'Grok 4.20 (reasoning)',
+    description:
+      'Reasoning variant — depth is fixed by the model id, not steerable with reasoning_effort.',
+    contextTokens: 1_000_000,
+    capabilities: ['reasoning', 'function_calling', 'json_mode'],
+    inputPricePer1M: 1.25,
+    outputPricePer1M: 2.5,
+  },
+  {
+    id: 'grok-4.20-0309-non-reasoning',
+    label: 'Grok 4.20 (no reasoning)',
+    description: 'Faster, cheaper variant of 4.20 without reasoning tokens.',
+    contextTokens: 1_000_000,
+    capabilities: ['function_calling', 'json_mode'],
+    inputPricePer1M: 1.25,
+    outputPricePer1M: 2.5,
+  },
+  {
+    id: 'grok-4.20-multi-agent-0309',
+    label: 'Grok 4.20 (multi-agent)',
+    description:
+      '2M context, designed for multi-agent workflows with shared state. reasoning_effort selects the agent COUNT here (4 or 16), not depth.',
+    contextTokens: 2_000_000,
+    capabilities: ['function_calling', 'json_mode'],
+    inputPricePer1M: 1.25,
+    outputPricePer1M: 2.5,
+  },
+  {
+    id: 'grok-3',
+    label: 'Grok 3 (alias)',
+    description:
+      'Alias — requests redirect to grok-4.3 and bill at grok-4.3 rates as of May 15, 2026.',
+    contextTokens: 1_000_000,
+    capabilities: ['vision', 'function_calling'],
+    inputPricePer1M: 1.25,
+    outputPricePer1M: 2.5,
+  },
+];
+
+export const XAI_BASE_URL = 'https://api.x.ai/v1';
+
+// ─── xAI TTS (Grok voice) ────────────────────────────────────────────
+//
+// Endpoint: POST {XAI_BASE_URL}/tts
+// Auth:     Authorization: Bearer $XAI_API_KEY
+// Body:     {text, voice_id, language, output_format: {codec, sample_rate, bit_rate}}
+//
+// 5 voices, 20+ languages auto-detected, inline + wrapping speech tags.
+
+import type { AudioTag, WrappingTag } from '../adapters/types';
+
+/** Grok TTS model — xAI publishes "grok-voice-latest" as the alias. */
+export const XAI_TTS_MODEL_ID = 'grok-voice-latest';
+
+/** Voice catalog for Grok TTS. 5 voices, gender/character hints from
+ *  the xAI launch blog. Operators see these in the worker form. */
+export const XAI_TTS_VOICES = [
+  { id: 'eve', description: 'female, warm — Grok default' },
+  { id: 'ara', description: 'female, clear and bright' },
+  { id: 'rex', description: 'male, deep and grounded' },
+  { id: 'sal', description: 'male, neutral and friendly' },
+  { id: 'leo', description: 'male, animated and energetic' },
+] as const;
+
+/**
+ * Inline speech tags Grok TTS honours. Square-bracket form, same shape
+ * as ElevenLabs's `[laughs]`. Pulled from
+ *   https://docs.x.ai/developers/rest-api-reference/inference/voice
+ *
+ * Wrapping (span-styling) tags live separately — see
+ * {@link XAI_WRAPPING_TAGS} below.
+ */
+export const XAI_AUDIO_TAGS: readonly AudioTag[] = [
+  // Reactions / human sounds.
+  { tag: '[laugh]', description: 'a hearty laugh', category: 'reaction' },
+  { tag: '[chuckle]', description: 'a short, dry amusement', category: 'reaction' },
+  { tag: '[giggle]', description: 'a light, playful laugh', category: 'reaction' },
+  { tag: '[sigh]', description: 'a resigned or reflective exhale', category: 'reaction' },
+  { tag: '[cry]', description: 'a sob or weeping; use rarely', category: 'reaction' },
+  { tag: '[tsk]', description: 'a disapproving cluck', category: 'reaction' },
+  {
+    tag: '[tongue-click]',
+    description: 'a sharp tongue cluck — punctuation',
+    category: 'reaction',
+  },
+  { tag: '[lip-smack]', description: 'a soft mouth sound; thoughtful beat', category: 'reaction' },
+  { tag: '[hum-tune]', description: 'a short hummed melody', category: 'reaction' },
+
+  // Breath.
+  { tag: '[breath]', description: 'a soft audible breath', category: 'reaction' },
+  {
+    tag: '[inhale]',
+    description: 'a sharp inhale; surprise or anticipation',
+    category: 'reaction',
+  },
+  { tag: '[exhale]', description: 'a deliberate exhale; release', category: 'reaction' },
+
+  // Pacing.
+  { tag: '[pause]', description: 'a short pause', category: 'cognitive' },
+  { tag: '[long-pause]', description: 'a longer pause for emphasis', category: 'cognitive' },
+];
+
+/**
+ * Returns the tag set for a given Grok TTS model. xAI publishes one
+ * voice model today (grok-voice-latest); future variants would branch
+ * here.
+ */
+export function audioTagsForXaiTtsModel(modelId: string): readonly AudioTag[] {
+  if (modelId === XAI_TTS_MODEL_ID || modelId === 'grok-voice') {
+    return XAI_AUDIO_TAGS;
+  }
+  return [];
+}
+
+/**
+ * Wrapping speech tags Grok TTS honours. Angle-bracket pairs that style
+ * the whole phrase they surround, e.g. `<whisper>it's a secret</whisper>`.
+ * Distinct from the inline `[bracket]` cues above — these apply a
+ * delivery style across a span rather than firing at a point.
+ *
+ * Source: https://docs.x.ai/developers/model-capabilities/audio/text-to-speech
+ * (the "speech tags" section — wrapping tags). Keep this list in sync
+ * with the docs; the names map directly to `<name>…</name>`.
+ */
+export const XAI_WRAPPING_TAGS: readonly WrappingTag[] = [
+  // Volume.
+  { name: 'loud', description: 'speak the wrapped phrase loudly', category: 'volume' },
+  { name: 'soft', description: 'speak the wrapped phrase quietly and gently', category: 'volume' },
+  {
+    name: 'whisper',
+    description: 'whisper the wrapped phrase — for secrets / asides',
+    category: 'volume',
+  },
+  // Pitch.
+  { name: 'high', description: 'raise the pitch across the wrapped phrase', category: 'pitch' },
+  // Pacing.
+  { name: 'slow', description: 'slow the delivery of the wrapped phrase down', category: 'pacing' },
+  // Style.
+  {
+    name: 'singing',
+    description: 'sing the wrapped phrase rather than speak it; use rarely',
+    category: 'style',
+  },
+];
+
+/**
+ * Returns the wrapping-tag set for a given Grok TTS model. Mirrors
+ * {@link audioTagsForXaiTtsModel} — one voice model today; future
+ * variants branch here.
+ */
+export function wrappingTagsForXaiTtsModel(modelId: string): readonly WrappingTag[] {
+  if (modelId === XAI_TTS_MODEL_ID || modelId === 'grok-voice') {
+    return XAI_WRAPPING_TAGS;
+  }
+  return [];
+}
+
+// ─── xAI STT (Grok transcribe) ───────────────────────────────────────
+//
+// Endpoint: POST {XAI_BASE_URL}/stt
+// Auth:     Authorization: Bearer $XAI_API_KEY
+// Body:     multipart/form-data — `format`=true, `language`=<iso>, `file` LAST.
+// Response: { text }
+//
+// Accepts WAV, MP3, WebM, OGG, M4A, MP4. 500 MB max per file.
+// Docs: https://docs.x.ai/developers/model-capabilities/audio/speech-to-text
+
+import type { SttModelInfo } from '../catalog';
+
+/** xAI publishes a single transcription model today ("grok-stt"
+ *  alias). When variants ship, add entries here — the adapter passes
+ *  the model id through but xAI's STT API doesn't take a `model` field
+ *  in the multipart body. We surface the id for traces only. */
+export const XAI_STT_MODELS: readonly SttModelInfo[] = [
+  {
+    id: 'grok-stt',
+    label: 'grok-stt',
+    description:
+      'xAI Speech-to-Text. Accepts WAV/MP3/WebM/OGG/M4A/MP4 up to 500 MB, returns formatted text.',
+    supportsLanguageHint: true,
+    supportsTimestamps: false,
+  },
+] as const;
+
+// ─── xAI Image Generation ────────────────────────────────────────────
+//
+// Endpoint: POST {XAI_BASE_URL}/images/generations
+// Auth:     Bearer
+// Body:     OpenAI-compatible (prompt + model + n + response_format).
+//           xAI returns urls by default; we request response_format=
+//           'b64_json' so the adapter gets bytes uniformly.
+//
+// Model history:
+//   - `grok-2-image-1212` — original launch model, DEPRECATED
+//     2026-02-24. The API returns 404 "no longer accessible via the
+//     API. Please use grok-imagine-image instead." Removed from this
+//     catalog so the dropdown can't suggest it; the adapter
+//     translates lingering-config 404s into a migration hint.
+//   - `grok-imagine-image` — current model (Feb 2026 →). Same
+//     endpoint shape, slightly improved photo-realism.
+
+import type { ImageGenModelInfo } from '../adapters/types';
+
+export const XAI_IMAGE_MODELS: readonly ImageGenModelInfo[] = [
+  {
+    id: 'grok-imagine-image',
+    label: 'Grok Imagine',
+    description:
+      'xAI image generator (Feb 2026+). Photo-realistic and editorial styles. Reuses your chat key.',
+    // Grok Imagine steers by ASPECT RATIO, not pixel size (docs.x.ai, image
+    // generation, checked 2026-08). An earlier entry here claimed a fixed
+    // 1024x1024 and no steering at all, which is why the adapter forwarded
+    // nothing.
+    supportedAspectRatios: [
+      'auto',
+      '1:1',
+      '3:4',
+      '4:3',
+      '9:16',
+      '16:9',
+      '2:3',
+      '3:2',
+      '1:2',
+      '2:1',
+    ],
+    pricePerImage: 0.07,
+    tier: 'balanced',
+  },
+];
+
+export const XAI_IMAGE_DEFAULT_MODEL = 'grok-imagine-image';
+/** Old id we still recognise solely to rewrite its API-error
+ *  message into a useful migration hint. The catalog no longer
+ *  surfaces this id; only the adapter looks at it. */
+export const XAI_IMAGE_DEPRECATED_MODELS: readonly string[] = ['grok-2-image-1212'];
+
+// ─── xAI Vision ──────────────────────────────────────────────────────
+//
+// xAI's chat completions endpoint is OpenAI-compatible — vision is
+// just messages[].content with image_url parts. As of May 2026 the
+// grok-4.x line is multimodal; grok-3 was image-input-only for vision.
+// Discovery cross-references against the chat /v1/models response,
+// same as XAI_CHAT_MODELS.
+
+import type { VisionModelInfo } from '../adapters/types';
+
+export const XAI_VISION_MODELS: readonly VisionModelInfo[] = [
+  {
+    id: 'grok-4.3',
+    label: 'Grok 4.3',
+    description:
+      'Current default. Multimodal across text + image. Reuses your chat key. Recommended.',
+    contextTokens: 1_000_000,
+    inputPricePer1M: 1.25,
+    outputPricePer1M: 2.5,
+    tier: 'balanced',
+  },
+  {
+    id: 'grok-4.20-0309-non-reasoning',
+    label: 'Grok 4.20 (no reasoning)',
+    description:
+      'Faster, cheaper variant. Good when the task is plain OCR and you don’t need reasoning over the image.',
+    contextTokens: 1_000_000,
+    inputPricePer1M: 1.25,
+    outputPricePer1M: 2.5,
+    tier: 'fast',
+  },
+  {
+    id: 'grok-3',
+    label: 'Grok 3 (alias)',
+    description:
+      'Alias — redirects to grok-4.3. Listed so existing workers configured for it still resolve.',
+    contextTokens: 1_000_000,
+    tier: 'balanced',
+  },
+];

package/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Browser-safe surface of @mantle/voice.
+ *
+ * The main barrel (`index.ts`) does `export * from './adapters'`, which pulls
+ * the network adapter layer (undici → node:crypto) — fine on the server, fatal
+ * in a client bundle ("Module parse failed" / node builtin in the browser).
+ * The UI settings pages only need *catalog data + provider metadata + pure
+ * helpers*, all of which live in adapter-free modules. Import those from HERE
+ * (`@mantle/voice/client`) instead of the barrel so the server adapters never
+ * reach the browser. Mirrors the `@mantle/content/contacts-format` leaf pattern.
+ *
+ * Keep this list adapter-free: only re-export modules whose value imports are
+ * empty (catalogs/*, catalog, providers, audio-tags) or pure metadata
+ * (adapters/registry's `isProviderWired` / `wiredCapabilitiesFor`).
+ */
+
+// Provider catalogue + capability metadata (pure data + helpers).
+export * from './providers';
+
+// Voice/model catalogs + helpers.
+export * from './catalog';
+export * from './audio-tags';
+
+// Per-provider model catalogs (data only).
+export * from './catalogs/anthropic';
+export * from './catalogs/google';
+export * from './catalogs/xai';
+export * from './catalogs/huggingface';
+export * from './catalogs/openai-image';
+export * from './catalogs/openai-vision';
+export * from './catalogs/openrouter';
+export * from './catalogs/elevenlabs';
+export * from './catalogs/deepgram';
+export * from './catalogs/assemblyai';
+export * from './catalogs/deepseek';
+
+// Pure wiring metadata (no adapter modules pulled — registry.ts only imports
+// the retry helper, which is itself dependency-free).
+export { isProviderWired, wiredCapabilitiesFor, WIRED_PROVIDERS } from './adapters/registry';
+export type { WiredCapability } from './adapters/registry';
+
+// Shared types.
+export { TTS_VOICES } from './types';
+export type { TtsVoice } from './types';
+// adapters/types.ts is type-only (no value imports), so re-exporting its whole
+// type surface is browser-safe and covers ChatModelInfo / VisionModelInfo /
+// ImageGenModelInfo / AudioTag / WrappingTag that the worker form needs.
+export type * from './adapters/types';

package/src/providers.test.ts

@@ -0,0 +1,172 @@
+/**
+ * Tests for the canonical providers catalog.
+ *
+ * Why these tests exist: the `api_keys.service` column and
+ * `ai_workers.provider` column are free text that the runtime
+ * dispatch matches by exact string. Once a value is persisted, the
+ * UI catalog and the runtime have to agree forever — renaming
+ * 'openai' to 'open-ai' would orphan every saved key. These tests
+ * lock the ids so a rename is loud at PR time.
+ *
+ * Tests also catch the easy mistakes: capability mismatches (an STT
+ * provider without 'stt' in its capabilities), missing signup/docs
+ * URLs (the UI uses them as links), the kind→capability map
+ * accidentally drifting from the ai_workers.kind enum.
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  CAPABILITY_FOR_KIND,
+  SUPPORTED_PROVIDERS,
+  getProvider,
+  isProviderId,
+  providersForCapability,
+} from './providers';
+
+describe('SUPPORTED_PROVIDERS catalog', () => {
+  it('lists openrouter first (default chat path)', () => {
+    // Catalog order = dropdown order. OpenRouter is the entry-point
+    // for new users; if it slips down the list, the UX gets worse.
+    expect(SUPPORTED_PROVIDERS[0]?.id).toBe('openrouter');
+  });
+
+  it('lists openai second (required audio path)', () => {
+    // OpenAI is the only provider currently catalogued for TTS/STT, so it
+    // should be the second option new users see.
+    expect(SUPPORTED_PROVIDERS[1]?.id).toBe('openai');
+  });
+
+  it('every provider has a non-empty label, description, signupUrl, docsUrl', () => {
+    // Each of these is rendered in the UI. Missing values produce
+    // a broken-looking row, so we lock them down.
+    for (const p of SUPPORTED_PROVIDERS) {
+      expect(p.label.length, `${p.id}.label`).toBeGreaterThan(0);
+      expect(p.description.length, `${p.id}.description`).toBeGreaterThan(20);
+      expect(p.signupUrl.startsWith('http'), `${p.id}.signupUrl`).toBe(true);
+      expect(p.docsUrl.startsWith('http'), `${p.id}.docsUrl`).toBe(true);
+    }
+  });
+
+  it('every provider declares at least one capability', () => {
+    for (const p of SUPPORTED_PROVIDERS) {
+      expect(p.capabilities.length, `${p.id} should have ≥1 capability`).toBeGreaterThan(0);
+    }
+  });
+
+  it('ids are unique', () => {
+    // A duplicate id would silently shadow the earlier entry, breaking
+    // the canonical lookup. Lock it down.
+    const ids = SUPPORTED_PROVIDERS.map((p) => p.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it('the providers catalogued for audio (tts/stt) include openai', () => {
+    // OpenAI is the only currently-catalogued audio provider. If a refactor
+    // drops it from the catalogue, voice in/out goes dark.
+    expect(providersForCapability('tts').some((p) => p.id === 'openai')).toBe(true);
+    expect(providersForCapability('stt').some((p) => p.id === 'openai')).toBe(true);
+  });
+
+  it('openrouter covers chat + audio (tts/stt) + image_gen via its multimodal APIs', () => {
+    // OpenRouter now proxies audio (/audio/speech, /audio/transcriptions) and
+    // image generation (chat modalities) in addition to chat/embedding/vision —
+    // so one OpenRouter key powers every capability. The adapters
+    // (openrouter-tts/stt/image) back these.
+    const or = getProvider('openrouter')!;
+    expect(or.capabilities).toContain('chat');
+    expect(or.capabilities).toContain('tts');
+    expect(or.capabilities).toContain('stt');
+    expect(or.capabilities).toContain('image_gen');
+  });
+});
+
+describe('providersForCapability', () => {
+  it('returns providers in catalog order', () => {
+    // The dropdown reads in this order. OpenRouter is listed first in the
+    // catalog and now covers chat + tts + stt + image_gen + vision, so it sits
+    // at the top for each — the "one key powers everything" default.
+    const chat = providersForCapability('chat');
+    expect(chat[0]?.id).toBe('openrouter');
+    const tts = providersForCapability('tts');
+    expect(tts[0]?.id).toBe('openrouter');
+    const stt = providersForCapability('stt');
+    expect(stt[0]?.id).toBe('openrouter');
+  });
+
+  it('returns ONLY providers that declared the capability', () => {
+    // Defensive: catch any future provider that has the capability
+    // in its description but forgot to list it in `capabilities`.
+    for (const p of providersForCapability('tts')) {
+      expect(p.capabilities, `${p.id} listed as tts-capable`).toContain('tts');
+    }
+    for (const p of providersForCapability('image_gen')) {
+      expect(p.capabilities, `${p.id} listed as image_gen-capable`).toContain('image_gen');
+    }
+  });
+});
+
+describe('getProvider / isProviderId', () => {
+  it('looks up by id', () => {
+    expect(getProvider('openai')?.label).toBe('OpenAI');
+    expect(getProvider('openrouter')?.label).toBe('OpenRouter');
+  });
+
+  it('returns null for unknown ids (no nil-throwing)', () => {
+    // The api_keys.service column accepts any string, so legacy rows
+    // or hand-edited DBs can carry ids we don't know about. We must
+    // not crash the page on those.
+    expect(getProvider('made-up-provider')).toBeNull();
+  });
+
+  it('isProviderId narrows correctly', () => {
+    expect(isProviderId('openai')).toBe(true);
+    expect(isProviderId('openrouter')).toBe(true);
+    expect(isProviderId('made-up-provider')).toBe(false);
+    expect(isProviderId('')).toBe(false);
+  });
+});
+
+describe('CAPABILITY_FOR_KIND map', () => {
+  it('covers every ai_workers.kind value', () => {
+    // The ai_workers.kind enum (in @mantle/db) and this map must stay
+    // in sync — otherwise the worker form for a new kind has no
+    // provider dropdown filter and shows an EMPTY dropdown
+    // (`providersForCapability(undefined)` returns []). This list is
+    // hand-maintained because @mantle/voice doesn't depend on
+    // @mantle/db (and shouldn't, just for a test). When you add a new
+    // ai_worker_kind enum value, add it here AND to CAPABILITY_FOR_KIND
+    // in providers.ts. The original 'embedding' miss is why this test
+    // is louder about the contract.
+    const kinds = [
+      'reflector',
+      'extractor',
+      'summarizer',
+      'tts',
+      'stt',
+      'vision',
+      'image_gen',
+      'embedding',
+      'search',
+      'search_advanced',
+      'narrator',
+      'suggester',
+    ];
+    for (const k of kinds) {
+      expect(CAPABILITY_FOR_KIND[k], `kind '${k}' has no capability mapping`).toBeTruthy();
+    }
+  });
+
+  it('chat-shaped workers map to the chat capability', () => {
+    // reflector, extractor, summarizer all make chat-completion calls.
+    expect(CAPABILITY_FOR_KIND.reflector).toBe('chat');
+    expect(CAPABILITY_FOR_KIND.extractor).toBe('chat');
+    expect(CAPABILITY_FOR_KIND.summarizer).toBe('chat');
+  });
+
+  it('media-shaped workers map to their own capability', () => {
+    expect(CAPABILITY_FOR_KIND.tts).toBe('tts');
+    expect(CAPABILITY_FOR_KIND.stt).toBe('stt');
+    expect(CAPABILITY_FOR_KIND.vision).toBe('vision');
+    expect(CAPABILITY_FOR_KIND.image_gen).toBe('image_gen');
+  });
+});