@crossworks/voice-client 0.230.43

package/src/audio-tags.test.ts

@@ -0,0 +1,221 @@
+/**
+ * Tests for the audio-tag composition + stripping helpers.
+ *
+ * Why these exist:
+ *   1. `composeAudioTagInstructions` is what makes Saskia use the
+ *      right tags — if the paragraph it produces is malformed, the
+ *      LLM either ignores it or hallucinates fake tags. Locking down
+ *      the output shape catches future regressions.
+ *
+ *   2. `stripAudioTags` is the safety net that keeps bracketed tags
+ *      out of text-mode replies. It must:
+ *        - Remove `[laughs]` / `[whispers]` / `[strong british accent]`
+ *        - NEVER touch markdown links `[label](url)` (these are not
+ *          audio tags; stripping them would break formatted replies)
+ *        - NEVER touch citation markers `[1]`, `[2,3]` (digits/commas
+ *          excluded by the pattern)
+ *        - Clean up whitespace so the strip doesn't leave double
+ *          spaces or stranded line breaks
+ */
+
+import { describe, expect, it } from 'vitest';
+import { composeAudioTagInstructions, stripAudioTags } from './audio-tags';
+import { ELEVENLABS_V3_AUDIO_TAGS } from './catalogs/elevenlabs';
+import { XAI_WRAPPING_TAGS } from './catalogs/xai';
+
+describe('composeAudioTagInstructions', () => {
+  it('returns empty string for an empty tag list', () => {
+    // No-op when the active TTS has no tags — caller concatenates
+    // unconditionally, so this MUST be exactly '' (not whitespace).
+    expect(composeAudioTagInstructions([])).toBe('');
+  });
+
+  it('includes every tag passed in', () => {
+    const out = composeAudioTagInstructions(ELEVENLABS_V3_AUDIO_TAGS);
+    for (const t of ELEVENLABS_V3_AUDIO_TAGS) {
+      expect(out).toContain(t.tag);
+      expect(out).toContain(t.description);
+    }
+  });
+
+  it('groups by category — emotion / reaction / delivery etc.', () => {
+    // The prompt's readability comes from grouping. Lock in that
+    // each category we use shows up as a section header.
+    const out = composeAudioTagInstructions(ELEVENLABS_V3_AUDIO_TAGS);
+    expect(out).toContain('reaction:');
+    expect(out).toContain('emotion:');
+    expect(out).toContain('delivery:');
+    expect(out).toContain('cognitive:');
+    expect(out).toContain('tone:');
+  });
+
+  it('includes the "use sparingly" guidance', () => {
+    // Saskia tends to over-use new affordances. The prompt explicitly
+    // tells her one or two tags per voice reply is plenty. Without
+    // this guidance she peppers every line.
+    const out = composeAudioTagInstructions(ELEVENLABS_V3_AUDIO_TAGS);
+    expect(out).toMatch(/sparingly|one or two/i);
+  });
+
+  it('mentions the auto-strip behaviour for text replies', () => {
+    // Tells the LLM it's safe to use tags even if she ends up routed
+    // text-out. Otherwise she'd hedge and skip them.
+    const out = composeAudioTagInstructions(ELEVENLABS_V3_AUDIO_TAGS);
+    expect(out).toMatch(/strip|text/i);
+  });
+
+  it('returns empty string when both inline and wrapping are empty', () => {
+    expect(composeAudioTagInstructions([], [])).toBe('');
+  });
+
+  it('renders a wrapping-tag section with <name>…</name> forms', () => {
+    const out = composeAudioTagInstructions([], XAI_WRAPPING_TAGS);
+    // The open/close form is derived from the bare name.
+    expect(out).toContain('<whisper>…</whisper>');
+    expect(out).toContain('<soft>…</soft>');
+    // Every wrapping tag's description lands in the prompt.
+    for (const t of XAI_WRAPPING_TAGS) {
+      expect(out).toContain(t.description);
+    }
+  });
+
+  it('groups wrapping tags by their categories (volume/pitch/pacing/style)', () => {
+    const out = composeAudioTagInstructions([], XAI_WRAPPING_TAGS);
+    expect(out).toContain('volume:');
+    expect(out).toContain('pitch:');
+    expect(out).toContain('pacing:');
+    expect(out).toContain('style:');
+  });
+
+  it('renders both vocabularies together when both are passed', () => {
+    const out = composeAudioTagInstructions(ELEVENLABS_V3_AUDIO_TAGS, XAI_WRAPPING_TAGS);
+    expect(out).toContain('['); // an inline tag
+    expect(out).toContain('<whisper>…</whisper>'); // a wrapping tag
+    // One combined paragraph — single header, not two.
+    expect(out.match(/## Voice expression/g)?.length).toBe(1);
+  });
+});
+
+describe('stripAudioTags', () => {
+  it('strips a single-word tag', () => {
+    const { text, stripped } = stripAudioTags('Hey [laughs] that was funny.');
+    expect(text).toBe('Hey that was funny.');
+    expect(stripped).toBe(1);
+  });
+
+  it('strips multi-word tags', () => {
+    // ElevenLabs has tags like [strong British accent] and
+    // [resigned tone] — multi-word; the pattern allows spaces.
+    const { text } = stripAudioTags('[resigned tone] Fine.');
+    expect(text).toBe('Fine.');
+  });
+
+  it('strips multiple tags in one string', () => {
+    const { text, stripped } = stripAudioTags(
+      '[whispers] keep it quiet — [laughs] not THAT quiet.',
+    );
+    expect(text).toBe('keep it quiet — not THAT quiet.');
+    expect(stripped).toBe(2);
+  });
+
+  it('preserves markdown links — [label](url) is NOT a tag', () => {
+    // The negative lookahead on `(` is the critical mechanism. If
+    // this breaks, replies with markdown links lose their visible
+    // text.
+    const { text, stripped } = stripAudioTags('See the [docs](https://example.com) for details.');
+    expect(text).toBe('See the [docs](https://example.com) for details.');
+    expect(stripped).toBe(0);
+  });
+
+  it('preserves citation markers — [1] [2,3] are NOT tags', () => {
+    // Citation markers contain digits/commas; our pattern requires
+    // letters only. Lock down the behaviour.
+    const { text, stripped } = stripAudioTags('Per [1] and [2,3], the result holds.');
+    expect(text).toBe('Per [1] and [2,3], the result holds.');
+    expect(stripped).toBe(0);
+  });
+
+  it('handles an empty / null input gracefully', () => {
+    expect(stripAudioTags('').text).toBe('');
+    expect(stripAudioTags('').stripped).toBe(0);
+  });
+
+  it('counts tags removed in the return value', () => {
+    // The agent runtime puts this on the trace step meta so we can
+    // tell, post-hoc, whether the LLM was using tags this turn.
+    const { stripped } = stripAudioTags('[laughs] [sighs] [whispers] hi');
+    expect(stripped).toBe(3);
+  });
+
+  it('does not introduce double spaces after stripping', () => {
+    const { text } = stripAudioTags('Hey [laughs] there.');
+    // Should be one space between 'Hey' and 'there.', not two.
+    expect(text).not.toMatch(/ {2}/);
+  });
+
+  it('handles tags at the start of a line cleanly', () => {
+    const { text } = stripAudioTags('[whispers] secret message.');
+    expect(text).toBe('secret message.');
+  });
+
+  it('does not match unbracketed text that looks tag-shaped', () => {
+    // `laughs` without brackets is just a word.
+    const { text } = stripAudioTags('She laughs a lot.');
+    expect(text).toBe('She laughs a lot.');
+  });
+
+  it('caps the matchable token length (defensive)', () => {
+    // A very long bracketed string (e.g. 200 chars) shouldn't be
+    // treated as a tag — the pattern caps token length at 40 chars
+    // to avoid eating long-bracketed editorial inserts. Test this
+    // by passing a long bracketed phrase.
+    const long = '[' + 'word '.repeat(20).trim() + ']'; // ~100 chars
+    const { text } = stripAudioTags(`prefix ${long} suffix`);
+    // The long bracketed string should be preserved (NOT stripped).
+    expect(text).toContain(long);
+  });
+
+  // ─── Wrapping tags (<whisper>…</whisper>) ─────────────────────────
+
+  it('strips wrapping tag markers but keeps the inner text', () => {
+    const { text } = stripAudioTags("I'll tell you. <whisper>it's a secret</whisper>");
+    expect(text).toBe("I'll tell you. it's a secret");
+  });
+
+  it('counts each wrapping marker removed', () => {
+    // open + close = 2 markers for one pair.
+    const { stripped } = stripAudioTags('<soft>quietly</soft>');
+    expect(stripped).toBe(2);
+  });
+
+  it('strips every documented xAI wrapping name', () => {
+    for (const t of XAI_WRAPPING_TAGS) {
+      const { text } = stripAudioTags(`<${t.name}>hello</${t.name}>`);
+      expect(text).toBe('hello');
+    }
+  });
+
+  it('is case-insensitive on wrapping tag names', () => {
+    const { text } = stripAudioTags('<Whisper>psst</WHISPER>');
+    expect(text).toBe('psst');
+  });
+
+  it('handles inline and wrapping tags mixed in one reply', () => {
+    const { text } = stripAudioTags('[sigh] fine. <whisper>but keep it quiet</whisper> [laughs]');
+    expect(text).toBe('fine. but keep it quiet');
+  });
+
+  it('does NOT touch autolinks or generic HTML — only known speech names', () => {
+    // `<https://…>` autolinks, emails, and arbitrary HTML must survive;
+    // the stripper matches an explicit name allowlist, not any `<word>`.
+    const samples = [
+      'See <https://example.com> for more.',
+      'Email <jason@schoeman.me> if stuck.',
+      'A <div> and a <span> walk in.',
+      'Markdown *em* and _underscore_ stay.',
+    ];
+    for (const s of samples) {
+      expect(stripAudioTags(s).text).toBe(s);
+    }
+  });
+});

package/src/audio-tags.ts

@@ -0,0 +1,191 @@
+/**
+ * Helpers for audio-tag composition and sanitisation.
+ *
+ * Two jobs:
+ *   1. Build the system-prompt paragraph that tells the chat agent
+ *      which tags the active TTS will honour. Saskia uses this to
+ *      emit `[laughs]` / `[whispers]` / `[sighs]` etc. in voice
+ *      replies — but only when the configured TTS actually renders
+ *      them (ElevenLabs v3 does; OpenAI tts-1 doesn't; the tag
+ *      adapter is the source of truth).
+ *
+ *   2. Strip audio tags from text-mode replies before they go out
+ *      on the chat surface. The LLM doesn't always know in advance
+ *      whether the reply will go as text or voice (`[VOICE]` opt-in
+ *      is decided AFTER the LLM finishes), so we let her use tags
+ *      freely and pull them out if she ends up routed to sendMessage.
+ *
+ * Both helpers are pure (no I/O, no DB, no provider calls), so they
+ * test cleanly and can be called from either runtime or the web's
+ * server-action layer.
+ */
+
+import type { AudioTag, WrappingTag } from './adapters/types';
+
+/** Group a tag list by its `category`, preserving first-seen order. */
+function groupByCategory<T extends { category?: string }>(tags: readonly T[]): Map<string, T[]> {
+  const byCategory = new Map<string, T[]>();
+  for (const t of tags) {
+    const cat = t.category ?? 'other';
+    if (!byCategory.has(cat)) byCategory.set(cat, []);
+    byCategory.get(cat)!.push(t);
+  }
+  return byCategory;
+}
+
+/**
+ * Render a system-prompt paragraph listing the supported voice tags.
+ * The paragraph is appended to the agent's base system_prompt before
+ * the chat call. Returns an empty string when both lists are empty, so
+ * the caller can unconditionally concatenate the result without
+ * churning the prompt for tag-less TTS providers.
+ *
+ * Two vocabularies, one paragraph:
+ *   - `inline` — point-in-time `[bracket]` cues (`[laughs]`, `[pause]`).
+ *   - `wrapping` — angle-bracket pairs that style a span
+ *     (`<whisper>…</whisper>`, `<soft>…</soft>`). xAI Grok voice today.
+ *
+ * `wrapping` defaults to `[]` so existing callers that only pass inline
+ * tags keep their exact output.
+ */
+export function composeAudioTagInstructions(
+  inline: readonly AudioTag[],
+  wrapping: readonly WrappingTag[] = [],
+): string {
+  if (inline.length === 0 && wrapping.length === 0) return '';
+
+  // Group by category so the prompt is readable. The model handles
+  // long flat lists fine but grouped lists land more reliably in our
+  // testing — and humans editing the prompt later find it easier.
+  const inlineSections: string[] = [];
+  for (const [cat, list] of groupByCategory(inline)) {
+    const items = list.map((t) => `  ${t.tag} — ${t.description}`).join('\n');
+    inlineSections.push(`${cat}:\n${items}`);
+  }
+
+  const wrappingSections: string[] = [];
+  for (const [cat, list] of groupByCategory(wrapping)) {
+    const items = list.map((t) => `  <${t.name}>…</${t.name}> — ${t.description}`).join('\n');
+    wrappingSections.push(`${cat}:\n${items}`);
+  }
+
+  const lines: string[] = [
+    '',
+    '## Voice expression — speech tags',
+    '',
+    'When your reply will be spoken aloud (voice-in or [VOICE] opt-in),',
+    'you can use speech tags to add warmth, beats, and emotion. These',
+    'tags ONLY work with the currently-configured voice model; using',
+    'them sparingly is more effective than using them often.',
+    '',
+  ];
+
+  if (inlineSections.length > 0) {
+    lines.push(
+      'Inline tags — written verbatim with square brackets, they fire at',
+      'the point they sit (e.g. [laughs] becomes a chuckle right there):',
+      '',
+      ...inlineSections,
+      '',
+    );
+  }
+
+  if (wrappingSections.length > 0) {
+    lines.push(
+      'Wrapping tags — angle-bracket pairs that style the whole phrase',
+      'they surround (e.g. <whisper>keep this quiet</whisper>). Always',
+      'close the tag you open:',
+      '',
+      ...wrappingSections,
+      '',
+    );
+  }
+
+  lines.push(
+    'Rules of thumb:',
+    '- One or two tags per voice reply is usually plenty.',
+    '- Place an inline tag right before the line it should affect;',
+    '  wrap only the exact words a wrapping tag should style.',
+    '- If the reply ends up text rather than voice, the tags are',
+    '  stripped automatically — feel free to use them and not worry.',
+    '',
+  );
+
+  return lines.join('\n');
+}
+
+/**
+ * The wrapping-tag names the stripper recognises. This is a curated
+ * superset of every provider's wrapping vocabulary (xAI Grok today)
+ * plus a few defensive synonyms — used ONLY by {@link stripAudioTags}
+ * as the safety net for text-out replies. We match by explicit name
+ * rather than "any `<word>`" so we never touch autolinks
+ * (`<https://…>`), email brackets, or real HTML/markdown the model may
+ * legitimately emit. Keep it conservative: only add names that are
+ * unambiguously speech-delivery styles.
+ */
+const WRAPPING_TAG_NAMES = [
+  'whisper',
+  'soft',
+  'loud',
+  'quiet',
+  'slow',
+  'fast',
+  'high',
+  'low',
+  'emphasis',
+  'singing',
+  'sing-song',
+  'shout',
+] as const;
+
+/**
+ * Strip voice tags from a reply that's going out as plain text. Two
+ * vocabularies are removed:
+ *
+ *   - Inline `[word]` / `[word phrase]` cues (`[laughs]`, `[pause]`).
+ *     Permissive pattern so a not-yet-catalogued bracket tag still gets
+ *     stripped. Intentionally does NOT strip:
+ *       · Markdown link text `[label](url)` — the `(` after `]` excludes it.
+ *       · Citation markers `[1]` / `[2,3]` — digits/commas excluded.
+ *       · Code blocks with brackets — this runs on chat content, not
+ *         tool output. Add a fence-aware variant if that changes.
+ *
+ *   - Wrapping `<name>…</name>` markers (`<whisper>`, `<soft>`, …). The
+ *     INNER TEXT is kept; only the angle-bracket markers are removed,
+ *     so `<whisper>it's a secret</whisper>` → `it's a secret`. Matched
+ *     against {@link WRAPPING_TAG_NAMES} so generic angle-bracket
+ *     content (autolinks, HTML) is left alone.
+ *
+ * Returns the cleaned text plus a count of markers removed (inline tags
+ * + wrapping markers) so callers can log or surface the strip.
+ */
+export function stripAudioTags(text: string): { text: string; stripped: number } {
+  if (!text) return { text: '', stripped: 0 };
+  let stripped = 0;
+
+  // Inline `[token]` — letters/spaces only (so `[laughs softly]` works),
+  // no digits/commas, not followed by `(` (markdown link). The negative
+  // lookahead on `(` is the distinguishing trick.
+  const inlinePattern = /\[([a-zA-Z][a-zA-Z\s]{0,40})\](?!\()/g;
+  let cleaned = text.replace(inlinePattern, () => {
+    stripped++;
+    return '';
+  });
+
+  // Wrapping `<name>` / `</name>` for the known speech-style names.
+  // Case-insensitive; removes the markers, keeps the inner text.
+  const wrappingPattern = new RegExp(`</?(?:${WRAPPING_TAG_NAMES.join('|')})\\s*>`, 'gi');
+  cleaned = cleaned.replace(wrappingPattern, () => {
+    stripped++;
+    return '';
+  });
+
+  // Collapse runs of whitespace introduced by the strip, then trim
+  // leading/trailing space without losing inline structure.
+  const tidied = cleaned
+    .replace(/[ \t]+/g, ' ')
+    .replace(/ ?\n ?/g, '\n')
+    .trim();
+  return { text: tidied, stripped };
+}

package/src/catalog.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Tests for the static TTS/STT catalogue.
+ *
+ * Why these tests exist: the catalogue is hand-maintained (OpenAI has
+ * no `/v1/audio/voices` endpoint) and feeds the agent-settings UI. If
+ * a model→voices mapping is wrong, the dropdown shows voices that
+ * the API will refuse at runtime. These tests lock down the
+ * documented model/voice combinations as of May 2026 so a typo or
+ * accidental drop is caught at PR time, not at the next voice
+ * message.
+ *
+ * The DISCOVERY layer (live `/v1/models` filtering) is integration-
+ * shaped — it needs a real OpenAI key — so it's not tested here.
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  ALL_OPENAI_VOICES,
+  OPENAI_STT_MODELS,
+  OPENAI_TTS_MODELS,
+  VOICE_DESCRIPTIONS,
+  getSttModel,
+  getTtsModel,
+  isOpenAiVoice,
+  voicesForModel,
+} from './catalog';
+
+describe('OPENAI_TTS_MODELS', () => {
+  it('contains all currently-published TTS models', () => {
+    const ids = OPENAI_TTS_MODELS.map((m) => m.id);
+    // Lock down the exact set so a model rename or drop is loud.
+    expect(new Set(ids)).toEqual(new Set(['gpt-4o-mini-tts', 'tts-1', 'tts-1-hd']));
+  });
+
+  it('lists gpt-4o-mini-tts first (recommended)', () => {
+    // The UI relies on catalog order — gpt-4o-mini-tts is the
+    // recommended default, so it must lead the dropdown.
+    expect(OPENAI_TTS_MODELS[0]?.id).toBe('gpt-4o-mini-tts');
+  });
+
+  it('marks gpt-4o-mini-tts as the only model supporting instructions', () => {
+    // `instructions` is the "speak warmly" style-steering parameter.
+    // It's silently ignored by tts-1 / tts-1-hd; the UI greys out the
+    // input when those models are selected, so this flag must be
+    // accurate.
+    const flags = Object.fromEntries(OPENAI_TTS_MODELS.map((m) => [m.id, m.supportsInstructions]));
+    expect(flags['gpt-4o-mini-tts']).toBe(true);
+    expect(flags['tts-1']).toBe(false);
+    expect(flags['tts-1-hd']).toBe(false);
+  });
+
+  it('gpt-4o-mini-tts ships the full 13 voices', () => {
+    const m = getTtsModel('gpt-4o-mini-tts');
+    expect(m).not.toBeNull();
+    expect(m!.voices.length).toBe(13);
+    // The signature additions over tts-1 must be present.
+    expect(m!.voices).toContain('ballad');
+    expect(m!.voices).toContain('verse');
+    expect(m!.voices).toContain('marin');
+    expect(m!.voices).toContain('cedar');
+  });
+
+  it('tts-1 and tts-1-hd ship the same 9 voices (no instructions support)', () => {
+    const a = getTtsModel('tts-1');
+    const b = getTtsModel('tts-1-hd');
+    expect(a).not.toBeNull();
+    expect(b).not.toBeNull();
+    expect(a!.voices.length).toBe(9);
+    expect(b!.voices.length).toBe(9);
+    expect(new Set(a!.voices)).toEqual(new Set(b!.voices));
+    // The expansion-only voices must NOT be in the older models.
+    for (const exp of ['ballad', 'verse', 'marin', 'cedar']) {
+      expect(a!.voices).not.toContain(exp);
+      expect(b!.voices).not.toContain(exp);
+    }
+  });
+});
+
+describe('OPENAI_STT_MODELS', () => {
+  it('contains whisper-1 + the gpt-4o transcription variants', () => {
+    const ids = OPENAI_STT_MODELS.map((m) => m.id);
+    expect(new Set(ids)).toEqual(
+      new Set(['whisper-1', 'gpt-4o-mini-transcribe', 'gpt-4o-transcribe']),
+    );
+  });
+
+  it('lists whisper-1 first (stable, cheapest)', () => {
+    // We default to whisper-1 for new STT workers because it's the
+    // longest-stable variant. Catalog order drives that default.
+    expect(OPENAI_STT_MODELS[0]?.id).toBe('whisper-1');
+  });
+});
+
+describe('voicesForModel', () => {
+  it('returns the model-specific voice list with descriptions', () => {
+    const voices = voicesForModel('gpt-4o-mini-tts');
+    expect(voices.length).toBe(13);
+    const nova = voices.find((v) => v.id === 'nova');
+    expect(nova?.description).toContain('Saskia');
+  });
+
+  it('returns 9 voices for tts-1', () => {
+    expect(voicesForModel('tts-1').length).toBe(9);
+  });
+
+  it('returns an empty array for an unknown model (caller decides fallback)', () => {
+    // If the operator types a custom model id (e.g. a fine-tuned one),
+    // we don't have a voice list. Return [] and let the caller decide
+    // whether to fall back to the full catalogue or refuse.
+    expect(voicesForModel('made-up-model')).toEqual([]);
+  });
+});
+
+describe('isOpenAiVoice', () => {
+  it('accepts every voice in ALL_OPENAI_VOICES', () => {
+    for (const v of ALL_OPENAI_VOICES) {
+      expect(isOpenAiVoice(v)).toBe(true);
+    }
+  });
+
+  it('rejects typos and unknown names', () => {
+    expect(isOpenAiVoice('novah')).toBe(false);
+    expect(isOpenAiVoice('Nova')).toBe(false);
+    expect(isOpenAiVoice('')).toBe(false);
+  });
+});
+
+describe('VOICE_DESCRIPTIONS', () => {
+  it('has a description for every voice in ALL_OPENAI_VOICES (no gaps)', () => {
+    // The UI dropdown reads from this; a missing entry would render
+    // as "voice — undefined" and look broken.
+    for (const v of ALL_OPENAI_VOICES) {
+      expect(VOICE_DESCRIPTIONS[v]).toBeTruthy();
+      expect(VOICE_DESCRIPTIONS[v]?.length ?? 0).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe('getSttModel / getTtsModel', () => {
+  it('returns null for unknown ids (no nil-throwing)', () => {
+    expect(getTtsModel('tts-99')).toBeNull();
+    expect(getSttModel('whisper-99')).toBeNull();
+  });
+});