@thevinci/web 1.0.0

package/server/lib/terminal/runtime.test.js

@@ -0,0 +1,96 @@
+import { EventEmitter } from 'node:events';
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+import { createTerminalRuntime } from './runtime.js';
+
+function createResponse() {
+  return {
+    statusCode: 200,
+    body: null,
+    status(code) {
+      this.statusCode = code;
+      return this;
+    },
+    json(payload) {
+      this.body = payload;
+      return this;
+    },
+  };
+}
+
+function createRuntime(server, overrides = {}) {
+  const app = overrides.app ?? {
+    post() {},
+    get() {},
+    delete() {},
+  };
+
+  return createTerminalRuntime({
+    app,
+    server,
+    express: { text: () => (_req, _res, next) => next?.() },
+    fs,
+    path,
+    uiAuthController: null,
+    buildAugmentedPath: () => process.env.PATH || '',
+    searchPathFor: () => null,
+    isExecutable: () => false,
+    isRequestOriginAllowed: async () => true,
+    rejectWebSocketUpgrade() {},
+    TERMINAL_INPUT_WS_HEARTBEAT_INTERVAL_MS: 30_000,
+    TERMINAL_INPUT_WS_REBIND_WINDOW_MS: 1_000,
+    TERMINAL_INPUT_WS_MAX_REBINDS_PER_WINDOW: 3,
+    ...overrides,
+  });
+}
+
+describe('terminal runtime', () => {
+  it('rejects regular files as terminal working directories', async () => {
+    const postRoutes = new Map();
+    const app = {
+      post(route, ...handlers) {
+        postRoutes.set(route, handlers.at(-1));
+      },
+      get() {},
+      delete() {},
+    };
+    const server = new EventEmitter();
+    const runtime = createRuntime(server, {
+      app,
+      fs: {
+        promises: {
+          stat: async () => ({ isDirectory: () => false }),
+        },
+      },
+      uiAuthController: { enabled: false },
+      buildAugmentedPath: () => '',
+      TERMINAL_INPUT_WS_HEARTBEAT_INTERVAL_MS: 1000,
+      TERMINAL_INPUT_WS_REBIND_WINDOW_MS: 1000,
+    });
+
+    try {
+      const createRoute = postRoutes.get('/api/terminal/create');
+      const res = createResponse();
+
+      await createRoute({ body: { cwd: '/tmp/not-a-directory' } }, res);
+
+      expect(res.statusCode).toBe(400);
+      expect(res.body).toEqual({ error: 'Invalid working directory' });
+    } finally {
+      await runtime.shutdown();
+    }
+  });
+
+  it('removes its websocket upgrade listener on shutdown', async () => {
+    const server = new EventEmitter();
+    const runtime = createRuntime(server);
+
+    expect(server.listenerCount('upgrade')).toBe(1);
+
+    await runtime.shutdown();
+
+    expect(server.listenerCount('upgrade')).toBe(0);
+  });
+});

package/server/lib/terminal/terminal-ws-protocol.js

@@ -0,0 +1,68 @@
+export const TERMINAL_WS_PATH = '/api/terminal/ws';
+export const TERMINAL_WS_CONTROL_TAG_JSON = 0x01;
+export const TERMINAL_WS_MAX_PAYLOAD_BYTES = 64 * 1024;
+
+export const parseRequestPathname = (requestUrl) => {
+  if (typeof requestUrl !== 'string' || requestUrl.length === 0) {
+    return '';
+  }
+
+  try {
+    return new URL(requestUrl, 'http://localhost').pathname;
+  } catch {
+    return '';
+  }
+};
+
+export const isTerminalWsPathname = (pathname) => pathname === TERMINAL_WS_PATH;
+
+export const normalizeTerminalWsMessageToBuffer = (rawData) => {
+  if (Buffer.isBuffer(rawData)) {
+    return rawData;
+  }
+
+  if (Array.isArray(rawData)) {
+    return Buffer.concat(rawData.map((chunk) => (Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))));
+  }
+
+  return Buffer.from(rawData);
+};
+
+export const normalizeTerminalWsMessageToText = (rawData) => {
+  if (typeof rawData === 'string') {
+    return rawData;
+  }
+
+  return normalizeTerminalWsMessageToBuffer(rawData).toString('utf8');
+};
+
+export const readTerminalWsControlFrame = (rawData) => {
+  if (!rawData) {
+    return null;
+  }
+
+  const buffer = normalizeTerminalWsMessageToBuffer(rawData);
+  if (buffer.length < 2 || buffer[0] !== TERMINAL_WS_CONTROL_TAG_JSON) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(buffer.subarray(1).toString('utf8'));
+    if (!parsed || typeof parsed !== 'object') {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+};
+
+export const createTerminalWsControlFrame = (payload) => {
+  const jsonBytes = Buffer.from(JSON.stringify(payload), 'utf8');
+  return Buffer.concat([Buffer.from([TERMINAL_WS_CONTROL_TAG_JSON]), jsonBytes]);
+};
+
+export const pruneRebindTimestamps = (timestamps, now, windowMs) =>
+  timestamps.filter((timestamp) => now - timestamp < windowMs);
+
+export const isRebindRateLimited = (timestamps, maxPerWindow) => timestamps.length >= maxPerWindow;

package/server/lib/terminal/terminal-ws-protocol.test.js

@@ -0,0 +1,145 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  TERMINAL_WS_PATH,
+  TERMINAL_WS_CONTROL_TAG_JSON,
+  createTerminalWsControlFrame,
+  isTerminalWsPathname,
+  isRebindRateLimited,
+  normalizeTerminalWsMessageToBuffer,
+  normalizeTerminalWsMessageToText,
+  parseRequestPathname,
+  pruneRebindTimestamps,
+  readTerminalWsControlFrame,
+} from './terminal-ws-protocol.js';
+
+describe('terminal websocket protocol', () => {
+  it('uses fixed websocket paths', () => {
+    expect(TERMINAL_WS_PATH).toBe('/api/terminal/ws');
+  });
+
+  it('matches supported websocket pathnames', () => {
+    expect(isTerminalWsPathname('/api/terminal/ws')).toBe(true);
+    expect(isTerminalWsPathname('/api/terminal/input-ws')).toBe(false);
+    expect(isTerminalWsPathname('/api/terminal/other')).toBe(false);
+  });
+
+  it('encodes control frames with control tag prefix', () => {
+    const frame = createTerminalWsControlFrame({ t: 'ok', v: 1 });
+    expect(frame[0]).toBe(TERMINAL_WS_CONTROL_TAG_JSON);
+  });
+
+  it('roundtrips control frame payload', () => {
+    const payload = { t: 'b', s: 'abc123', v: 1 };
+    const frame = createTerminalWsControlFrame(payload);
+    expect(readTerminalWsControlFrame(frame)).toEqual(payload);
+  });
+
+  it('rejects control frame without protocol tag', () => {
+    const frame = Buffer.from(JSON.stringify({ t: 'b', s: 'abc123' }), 'utf8');
+    expect(readTerminalWsControlFrame(frame)).toBeNull();
+  });
+
+  it('rejects malformed control json', () => {
+    const frame = Buffer.concat([
+      Buffer.from([TERMINAL_WS_CONTROL_TAG_JSON]),
+      Buffer.from('{not json', 'utf8'),
+    ]);
+    expect(readTerminalWsControlFrame(frame)).toBeNull();
+  });
+
+  it('rejects empty control payloads', () => {
+    expect(readTerminalWsControlFrame(null)).toBeNull();
+    expect(readTerminalWsControlFrame(undefined)).toBeNull();
+    expect(readTerminalWsControlFrame(Buffer.alloc(0))).toBeNull();
+  });
+
+  it('rejects control json that is not object', () => {
+    const frame = Buffer.concat([
+      Buffer.from([TERMINAL_WS_CONTROL_TAG_JSON]),
+      Buffer.from('"str"', 'utf8'),
+    ]);
+    expect(readTerminalWsControlFrame(frame)).toBeNull();
+  });
+
+  it('parses control frame from chunk arrays', () => {
+    const frame = createTerminalWsControlFrame({ t: 'bok', v: 1 });
+    const chunks = [frame.subarray(0, 2), frame.subarray(2)];
+    expect(readTerminalWsControlFrame(chunks)).toEqual({ t: 'bok', v: 1 });
+  });
+
+  it('normalizes buffer passthrough', () => {
+    const raw = Buffer.from('abc', 'utf8');
+    const normalized = normalizeTerminalWsMessageToBuffer(raw);
+    expect(normalized).toBe(raw);
+    expect(normalized.toString('utf8')).toBe('abc');
+  });
+
+  it('normalizes uint8 arrays', () => {
+    const normalized = normalizeTerminalWsMessageToBuffer(new Uint8Array([97, 98, 99]));
+    expect(normalized.toString('utf8')).toBe('abc');
+  });
+
+  it('normalizes array buffer payloads', () => {
+    const source = new Uint8Array([97, 98, 99]).buffer;
+    const normalized = normalizeTerminalWsMessageToBuffer(source);
+    expect(normalized.toString('utf8')).toBe('abc');
+  });
+
+  it('normalizes chunk array payloads', () => {
+    const normalized = normalizeTerminalWsMessageToBuffer([
+      Buffer.from('ab', 'utf8'),
+      Buffer.from('c', 'utf8'),
+    ]);
+    expect(normalized.toString('utf8')).toBe('abc');
+  });
+
+  it('normalizes text payload from string', () => {
+    expect(normalizeTerminalWsMessageToText('\u001b[A')).toBe('\u001b[A');
+  });
+
+  it('normalizes text payload from binary data', () => {
+    expect(normalizeTerminalWsMessageToText(Buffer.from('\r', 'utf8'))).toBe('\r');
+  });
+
+  it('parses relative request pathname', () => {
+    expect(parseRequestPathname('/api/terminal/ws?x=1')).toBe('/api/terminal/ws');
+  });
+
+  it('parses absolute request pathname', () => {
+    expect(parseRequestPathname('http://localhost:3000/api/terminal/ws')).toBe('/api/terminal/ws');
+  });
+
+  it('returns empty pathname for non-string request url', () => {
+    expect(parseRequestPathname(null)).toBe('');
+  });
+
+  it('returns empty pathname for invalid request url', () => {
+    expect(parseRequestPathname('http://')).toBe('');
+    expect(parseRequestPathname('')).toBe('');
+  });
+
+  it('prunes stale rebind timestamps', () => {
+    const now = 1_000;
+    const pruned = pruneRebindTimestamps([100, 200, 950, 999], now, 100);
+    expect(pruned).toEqual([950, 999]);
+  });
+
+  it('keeps rebind timestamps within active window', () => {
+    const now = 1_000;
+    const pruned = pruneRebindTimestamps([920, 950, 999], now, 100);
+    expect(pruned).toEqual([920, 950, 999]);
+  });
+
+  it('does not rate limit below threshold', () => {
+    expect(isRebindRateLimited([1, 2, 3], 4)).toBe(false);
+  });
+
+  it('does not rate limit empty window', () => {
+    expect(isRebindRateLimited([], 1)).toBe(false);
+  });
+
+  it('rate limits at threshold', () => {
+    expect(isRebindRateLimited([1, 2, 3, 4], 4)).toBe(true);
+  });
+});

package/server/lib/text/DOCUMENTATION.md

@@ -0,0 +1,35 @@
+# Text Module Documentation
+
+## Purpose
+This module provides shared text transformation helpers that are not owned by a single product surface. It previously proxied model-backed summarization through the opencode.ai Zen provider; that provider is no longer available for this use, so summarization now returns local sanitized/distilled fallback text only.
+
+## Entrypoints and structure
+- `packages/web/server/lib/text/summarization.js`: Shared summarize stub + sanitize helpers. It performs no external model calls.
+
+## Public exports
+
+### Summarization (summarization.js)
+- `summarizeText({ text, threshold, maxLength, zenModel, mode })`: Retired summarization entrypoint retained as an API-compatible stub. `zenModel` is ignored.
+- `sanitizeForTTS(text)`: Sanitizes text for speech output.
+- `sanitizeForNotification(text)`: Sanitizes text for compact notification output.
+- `sanitizeForNote(text)`: Sanitizes text for short note/distillation output.
+
+## Modes
+- `tts`: Speakable summary for TTS flows.
+- `notification`: Short plain-text summary for notification bodies.
+- `note`: Distilled short project-memory note.
+
+## Response contract
+
+### `summarizeText`
+Returns object with:
+- `summary`: Local sanitized/distilled fallback text.
+- `summarized`: Always `false` while the model provider is unavailable.
+- `reason`: Skip reason, usually `Model summarization provider unavailable` for text above threshold.
+- `originalLength`: Optional original text length.
+- `summaryLength`: Optional final summary length.
+
+## Notes for contributors
+- Keep this module neutral. Do not re-couple it to TTS-specific naming or routing.
+- Add new mode semantics here when multiple product surfaces need the same text pipeline.
+- Prefer mode-specific prompt and sanitize behavior over creating duplicated summarizers in unrelated modules.

package/server/lib/text/summarization.js

@@ -0,0 +1,138 @@
+/**
+ * Shared text summarization service.
+ *
+ * Modes:
+ * - tts: concise speakable text
+ * - notification: concise notification text
+ * - note: distilled project note
+ */
+
+export function sanitizeForTTS(text) {
+  if (!text || typeof text !== 'string') return '';
+
+  return text
+    .replace(/[*_~`#]/g, '')
+    .replace(/```[\s\S]*?```/g, '')
+    .replace(/`[^`]*`/g, '')
+    .replace(/^\s*[$#>]\s*/gm, '')
+    .replace(/[|&;<>]/g, ' ')
+    .replace(/\\/g, '')
+    .replace(/[\[\]{}()]/g, '')
+    .replace(/["']/g, '')
+    .replace(/https?:\/\/[^\s]+/g, ' a link ')
+    .replace(/\/[\w\-./]+/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+export function sanitizeForNotification(text) {
+  if (!text || typeof text !== 'string') return '';
+
+  return text
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`([^`]*)`/g, '$1')
+    .replace(/^[\t ]*[-*+]\s+/gm, '')
+    .replace(/^#{1,6}\s+/gm, '')
+    .replace(/\*\*(.*?)\*\*/g, '$1')
+    .replace(/__(.*?)__/g, '$1')
+    .replace(/\*(.*?)\*/g, '$1')
+    .replace(/_(.*?)_/g, '$1')
+    .replace(/\[(.*?)\]\((.*?)\)/g, '$1')
+    .replace(/\s*\n\s*/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+export function sanitizeForNote(text) {
+  if (!text || typeof text !== 'string') return '';
+
+  return text
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`([^`]*)`/g, '$1')
+    .replace(/^\s*[-*+]\s+/gm, '')
+    .replace(/^#{1,6}\s+/gm, '')
+    .replace(/\*\*(.*?)\*\*/g, '$1')
+    .replace(/__(.*?)__/g, '$1')
+    .replace(/\*(.*?)\*/g, '$1')
+    .replace(/_(.*?)_/g, '$1')
+    .replace(/\[(.*?)\]\((.*?)\)/g, '$1')
+    .replace(/https?:\/\/[^\s]+/g, '')
+    .replace(/["']/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function sanitizeByMode(text, mode) {
+  if (mode === 'note') return sanitizeForNote(text);
+  if (mode === 'notification') return sanitizeForNotification(text);
+  return sanitizeForTTS(text);
+}
+
+function distillNoteFallback(text, maxLength) {
+  const sanitized = sanitizeForNote(text);
+  if (!sanitized) return '';
+
+  const normalized = sanitized
+    .replace(/^In summary[:,]?\s*/i, '')
+    .replace(/^Here(?:s| is) (?:a )?note[:,]?\s*/i, '')
+    .trim();
+
+  const sentences = normalized
+    .split(/(?<=[.!?])\s+/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+
+  const best = (sentences[0] || normalized)
+    .split(/[;:()-]\s+/)[0]
+    .split(/,\s+/)[0]
+    .trim();
+  const idealLimit = Math.min(maxLength, Math.max(32, Math.floor(normalized.length * 0.65)));
+
+  if (best.length <= idealLimit) return best;
+
+  const clipped = best.slice(0, Math.max(0, idealLimit - 1)).trim();
+  return clipped ? `${clipped}…` : best.slice(0, idealLimit).trim();
+}
+
+function distillNotificationFallback(text, maxLength) {
+  const sanitized = sanitizeForNotification(text);
+  if (!sanitized) return '';
+
+  const sentences = sanitized
+    .split(/(?<=[.!?])\s+/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+  const candidate = sentences.find((sentence) => sentence.length >= 20) || sentences[0] || sanitized;
+  const limit = Number.isFinite(maxLength) ? Math.max(20, Math.floor(maxLength)) : 100;
+  if (candidate.length <= limit) return candidate;
+
+  const clipped = candidate.slice(0, Math.max(0, limit - 1)).trim();
+  return clipped ? `${clipped}…` : candidate.slice(0, limit).trim();
+}
+
+function fallbackByMode(text, maxLength, mode) {
+  if (mode === 'note') return distillNoteFallback(text, maxLength);
+  if (mode === 'notification') return distillNotificationFallback(text, maxLength);
+  return sanitizeByMode(text, mode);
+}
+
+export async function summarizeText({ text, threshold = 200, maxLength = 500, zenModel, mode = 'tts' }) {
+  void zenModel;
+
+  const summary = fallbackByMode(text || '', maxLength, mode);
+  if (!text || text.length <= threshold) {
+    return {
+      summary,
+      summarized: false,
+      reason: text ? 'Text under threshold' : 'No text provided',
+    };
+  }
+
+  return {
+    summary,
+    summarized: false,
+    reason: 'Model summarization provider unavailable',
+    originalLength: text.length,
+    summaryLength: summary.length,
+  };
+}

package/server/lib/text/summarization.test.js

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+
+import { summarizeText } from './summarization.js';
+
+describe('text summarization stubs', () => {
+  it('does not call the retired zen provider', async () => {
+    const result = await summarizeText({
+      text: 'The implementation now correctly loads notification templates before dispatching the notification. It also fetches the latest assistant message when the event payload does not include message parts. This should make completion notifications match user settings.',
+      threshold: 0,
+      maxLength: 80,
+      zenModel: 'gpt-5-nano',
+      mode: 'notification',
+    });
+
+    expect(result.summarized).toBe(false);
+    expect(result.reason).toBe('Model summarization provider unavailable');
+    expect(result.summary).toBe('The implementation now correctly loads notification templates before dispatchin…');
+  });
+
+  it('returns local note fallback while provider is unavailable', async () => {
+    const result = await summarizeText({
+      text: 'First sentence. Second sentence with the useful insight.',
+      threshold: 0,
+      maxLength: 100,
+      mode: 'note',
+    });
+
+    expect(result).toMatchObject({
+      summary: 'First sentence.',
+      summarized: false,
+      reason: 'Model summarization provider unavailable',
+    });
+  });
+});

package/server/lib/tts/DOCUMENTATION.md

@@ -0,0 +1,146 @@
+# TTS Module Documentation
+
+## Purpose
+This module provides server-side Text-to-Speech services using OpenAI's TTS API. The historical shared text summarization endpoint now lives in `packages/web/server/lib/text/` as an API-compatible stub because the previous Zen model provider is unavailable.
+
+## Entrypoints and structure
+- `packages/web/server/lib/tts/index.js`: Public entrypoint imported by `packages/web/server/index.js`.
+- `packages/web/server/lib/tts/routes.js`: Express route registration for `/api/voice/*`, `/api/tts/*`, and `/api/stt/*` endpoints.
+- `packages/web/server/lib/tts/capability-runtime.js`: runtime helper for probing local macOS `say` TTS voice capability.
+- `packages/web/server/lib/tts/service.js`: TTS service implementation with OpenAI integration.
+- `packages/web/server/lib/text/summarization.js`: Shared text summarization stub and sanitization utilities. It performs no external Zen calls.
+- `packages/web/server/lib/tts/stt.js`: STT proxy for OpenAI-compatible transcription endpoints.
+- `packages/web/server/lib/tts/base-url.js`: shared base URL validation and normalization for custom OpenAI-compatible endpoints.
+
+## Public exports
+
+### TTS Service (from service.js)
+- `ttsService`: Singleton instance of TTSService class.
+- `TTSService`: TTS service class for OpenAI audio generation.
+- `TTS_VOICES`: Array of supported OpenAI voice identifiers.
+
+### Shared text summarization (re-exported from ../text/summarization.js)
+- `summarizeText({ text, threshold, maxLength, zenModel, mode })`: Retired shared text summarizer retained as a stub. TTS uses `mode: 'tts'`; `zenModel` is ignored.
+- `sanitizeForTTS(text)`: Sanitizes text by removing markdown, URLs, file paths, and other non-speakable content.
+- `sanitizeForNote(text)`: Re-exported for note-mode callers that still import through the TTS surface.
+
+### Capability runtime (capability-runtime.js)
+- `detectSayTtsCapability(processLike)`: probes local `say -v "?"` support and returns `{ available, voices, reason }`.
+
+## Constants
+
+### Voice identifiers
+- `TTS_VOICES`: Array of supported OpenAI voices: `['alloy', 'ash', 'ballad', 'coral', 'echo', 'fable', 'nova', 'onyx', 'sage', 'shimmer', 'verse', 'marin', 'cedar']`.
+
+### Summarization defaults
+- No model request timeout is used; the summarization provider is disabled.
+
+### Default values
+- `summarizeText` defaults: `threshold` = 200, `maxLength` = 500, `mode` = 'tts'. `zenModel` is ignored.
+- `generateSpeechStream` defaults: `voice` = 'coral', `model` = 'gpt-4o-mini-tts', `speed` = 1.0.
+- `generateSpeechBuffer` defaults: `voice` = 'coral', `model` = 'gpt-4o-mini-tts', `speed` = 1.0.
+
+## TTSService methods
+
+### `isAvailable()`
+Returns boolean indicating whether OpenAI API key is configured (checks environment variable `OPENAI_API_KEY` or OpenCode auth file).
+
+### `generateSpeechStream(options)`
+Generates speech and returns as a web stream for direct streaming to clients.
+- Options: `text` (required), `voice`, `model`, `speed`, `instructions`, `apiKey`.
+- Returns: `{ stream: ReadableStream, contentType: 'audio/mpeg' }`.
+- Throws: Error if API key not configured or text is empty.
+
+### `generateSpeechBuffer(options)`
+Generates speech and returns as Buffer for caching purposes.
+- Options: `text` (required), `voice`, `model`, `speed`, `instructions`.
+- Returns: Buffer containing MP3 audio data.
+- Throws: Error if API key not configured or text is empty.
+
+## Response contracts
+
+### `summarizeText`
+Returns object with:
+- `summary`: Sanitized or locally distilled fallback text.
+- `summarized`: Always `false` while the model provider is unavailable.
+- `reason`: String explaining why summarization was skipped.
+- `originalLength`: Optional number for original text length.
+- `summaryLength`: Optional number for summarized text length.
+
+The route-level text summarize API is now `/api/text/summarize`.
+
+### `sanitizeForTTS`
+Returns sanitized string with markdown, URLs, file paths, and special characters removed.
+
+### `generateSpeechStream`
+Returns object with:
+- `stream`: ReadableStream of MP3 audio data.
+- `contentType`: Always 'audio/mpeg'.
+
+### `generateSpeechBuffer`
+Returns Buffer containing MP3 audio data.
+
+## API key resolution
+OpenAI API keys are resolved in order:
+1. Environment variable `OPENAI_API_KEY`.
+2. OpenCode auth file (`auth.openai`, `auth.codex`, or `auth.chatgpt`).
+3. Supports both string format (just token) and object format (with `access` or `token` fields).
+
+## Usage in web server
+The TTS module is used by `packages/web/server/index.js` for:
+- Generating speech streams for client playback.
+- Generating speech buffers for caching.
+- Sanitizing text before TTS synthesis. Historical summarization calls now return local fallback text.
+- Sanitizing text to remove non-speakable content.
+
+The historical summarization API is shared with notifications and notes, but currently acts as a no-model fallback/stub.
+
+The server-side TTS approach bypasses mobile Safari's audio context restrictions by generating audio on the server and streaming to clients.
+
+## Notes for contributors
+
+### Adding new TTS features
+1. Add new methods to `packages/web/server/lib/tts/service.js` TTSService class.
+2. Export public functions from `packages/web/server/lib/tts/index.js`.
+3. Follow existing patterns for API key resolution and error handling.
+4. Ensure all text is sanitized before TTS synthesis.
+5. Consider adding new voice options to `TTS_VOICES` constant.
+
+### Text sanitization
+- Always call `sanitizeForTTS` on text before passing to TTS generation.
+- The sanitization removes markdown, code blocks, URLs, file paths, shell commands, and special characters.
+- This prevents the TTS from reading out technical formatting that sounds unnatural.
+
+### Error handling
+- `generateSpeechStream` and `generateSpeechBuffer` throw descriptive errors for missing API keys or empty text.
+- `summarizeText` does not call Zen and returns mode-specific fallback text with `summarized: false`.
+- All errors are logged to console with `[TTSService]` or `[Summarize]` prefix.
+
+### API key management
+- TTSService caches OpenAI client instance and recreates when API key changes.
+- API key changes are detected by comparing with `_lastApiKey` property.
+- This allows dynamic API key updates without server restart.
+
+### Testing
+- Run `bun run type-check`, `bun run lint`, and `bun run build` before finalizing changes.
+- Test API key resolution with environment variable and auth file.
+- Test speech generation with various text lengths and voice options.
+- Test summarization stub behavior above and below threshold.
+- Test sanitization with markdown, URLs, and code blocks.
+- Verify streaming and buffer generation produce valid MP3 audio.
+
+## Verification notes
+
+### Manual verification
+1. Configure OpenAI API key via environment variable or OpenCode settings.
+2. Test `ttsService.isAvailable()` returns true.
+3. Call `ttsService.generateSpeechStream({ text: 'Hello world' })` and verify stream is returned.
+4. Call `ttsService.generateSpeechBuffer({ text: 'Hello world' })` and verify Buffer is returned.
+5. Test `summarizeText` with text above and below threshold.
+6. Test `sanitizeForTTS` with markdown, URLs, and code blocks.
+
+### API endpoint verification
+1. Start web server and access TTS endpoint via client.
+2. Verify audio plays correctly in browser.
+3. Test on mobile Safari to verify bypass of audio context restrictions.
+4. Test with long messages to verify summarization is triggered.