@andypai/orb 0.1.1

package/src/services/tts.ts

@@ -0,0 +1,309 @@
+import { Buffer } from 'node:buffer'
+import { URL } from 'node:url'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { unlink } from 'node:fs/promises'
+import { TTSError, type AppConfig, type TTSErrorType, type Voice } from '../types'
+import { cleanTextForSpeech } from '../ui/utils/markdown'
+
+export { cleanTextForSpeech }
+
+export const DEFAULT_SERVER_URL = 'http://localhost:8000'
+const DEFAULT_SAY_RATE_WPM = 175
+const SAY_VOICE_BY_ORB_VOICE: Record<Voice, string> = {
+  alba: 'Samantha',
+  marius: 'Daniel',
+  jean: 'Eddy (English (US))',
+}
+
+function categorizeTTSError(err: unknown, context: 'generate' | 'playback'): TTSError {
+  if (err instanceof TTSError) return err
+
+  const error = err instanceof Error ? err : new Error(String(err))
+  const nodeError = error as Error & { code?: string }
+
+  if (nodeError.code === 'ENOENT') {
+    const cmd = context === 'generate' ? 'say' : 'afplay'
+    return new TTSError(`Command not found: ${cmd}`, 'command_not_found', error)
+  }
+
+  const type: TTSErrorType = context === 'generate' ? 'generation_failed' : 'audio_playback'
+  return new TTSError(error.message, type, error)
+}
+
+let currentPlayProcess: Bun.Subprocess | null = null
+let playbackStoppedManually = false
+
+export function wasPlaybackStopped(): boolean {
+  return playbackStoppedManually
+}
+
+export function resetPlaybackStoppedFlag(): void {
+  playbackStoppedManually = false
+}
+
+function splitIntoSentences(text: string): string[] {
+  const sentences: string[] = []
+  let current = ''
+
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i]
+    if (char === undefined) continue
+
+    current += char
+
+    if (['.', '!', '?'].includes(char)) {
+      const next = text[i + 1]
+      if (next === undefined || next === ' ' || next === '\n') {
+        const trimmed = current.trim()
+        if (trimmed.length > 0) {
+          sentences.push(trimmed)
+        }
+        current = ''
+      }
+    }
+  }
+
+  const trimmed = current.trim()
+  if (trimmed.length > 0) {
+    sentences.push(trimmed)
+  }
+
+  return sentences
+}
+
+function normalizeServerUrl(rawUrl: string): string {
+  const trimmed = rawUrl.trim() || DEFAULT_SERVER_URL
+
+  let url: URL
+  try {
+    url = new URL(trimmed)
+  } catch {
+    throw new TTSError('Invalid TTS server URL', 'generation_failed')
+  }
+
+  if (!url.pathname || url.pathname === '/') {
+    url.pathname = '/tts'
+  }
+
+  return url.toString()
+}
+
+async function readErrorMessage(response: { text: () => Promise<string> }): Promise<string | null> {
+  try {
+    const text = await response.text()
+    return text.trim() || null
+  } catch {
+    return null
+  }
+}
+
+function isValidSpeed(speed: number | undefined): speed is number {
+  return typeof speed === 'number' && Number.isFinite(speed) && speed > 0
+}
+
+function getTempAudioExtension(mode: AppConfig['ttsMode']): string {
+  return mode === 'generate' ? 'aiff' : 'wav'
+}
+
+function mapVoiceToSayVoice(voice: Voice): string {
+  return SAY_VOICE_BY_ORB_VOICE[voice]
+}
+
+function mapSpeedToSayRate(speed: number): number | undefined {
+  if (!isValidSpeed(speed)) return undefined
+  return Math.max(90, Math.round(DEFAULT_SAY_RATE_WPM * speed))
+}
+
+function buildSpeechFormData(
+  text: string,
+  voice: string | undefined,
+  speed: number,
+): globalThis.FormData {
+  const formData = new globalThis.FormData()
+  formData.append('text', text)
+  if (voice) {
+    formData.append('voice', voice)
+  }
+  if (isValidSpeed(speed)) {
+    formData.append('speed', String(speed))
+  }
+  return formData
+}
+
+async function requestServerSpeech(
+  serverUrl: string,
+  text: string,
+  voice: string,
+  speed: number,
+  signal?: globalThis.AbortSignal,
+): Promise<Buffer> {
+  async function postSpeech(formData: globalThis.FormData): Promise<Response> {
+    return await fetch(serverUrl, {
+      method: 'POST',
+      body: formData,
+      signal,
+    })
+  }
+
+  let response = await postSpeech(buildSpeechFormData(text, voice, speed))
+  if (!response.ok && voice) {
+    // Some tts-gateway providers use a different voice namespace than Orb's voice presets.
+    // Retry once without an explicit voice so the server can fall back to its default.
+    response = await postSpeech(buildSpeechFormData(text, undefined, speed))
+  }
+
+  if (!response.ok) {
+    const message = await readErrorMessage(response)
+    const details = message ? `: ${message}` : ''
+    throw new TTSError(`TTS server error (${response.status})${details}`, 'generation_failed')
+  }
+
+  const audioBuffer = await response.arrayBuffer()
+  return Buffer.from(audioBuffer)
+}
+
+async function runGenerateCommand(
+  text: string,
+  voice: Voice,
+  speed: number,
+  outputPath: string,
+): Promise<void> {
+  if (process.platform !== 'darwin') {
+    throw new TTSError(
+      'Generate mode requires macOS say. Use serve mode with tts-gateway on this platform.',
+      'command_not_found',
+    )
+  }
+
+  async function runSay(voiceName?: string): Promise<number> {
+    const cmd = ['say', '-o', outputPath]
+    if (voiceName) {
+      cmd.push('-v', voiceName)
+    }
+
+    const rate = mapSpeedToSayRate(speed)
+    if (rate) {
+      cmd.push('-r', String(rate))
+    }
+
+    cmd.push(text)
+
+    const proc = Bun.spawn(cmd, { stdout: 'ignore', stderr: 'ignore' })
+    return await proc.exited
+  }
+
+  const sayVoice = mapVoiceToSayVoice(voice)
+  let exitCode = await runSay(sayVoice)
+  if (exitCode !== 0 && sayVoice) {
+    exitCode = await runSay()
+  }
+
+  if (exitCode !== 0) {
+    throw new TTSError(`say exited with code ${exitCode}`, 'generation_failed')
+  }
+}
+
+export async function generateAudio(
+  text: string,
+  config: AppConfig,
+  outputPath: string,
+  signal?: globalThis.AbortSignal,
+): Promise<void> {
+  try {
+    if (config.ttsMode === 'serve') {
+      const serverUrl = normalizeServerUrl(config.ttsServerUrl ?? DEFAULT_SERVER_URL)
+      const audio = await requestServerSpeech(
+        serverUrl,
+        text,
+        config.ttsVoice,
+        config.ttsSpeed,
+        signal,
+      )
+      await Bun.write(outputPath, audio)
+      return
+    }
+
+    await runGenerateCommand(text, config.ttsVoice, config.ttsSpeed, outputPath)
+  } catch (err) {
+    throw categorizeTTSError(err, 'generate')
+  }
+}
+
+export async function playAudio(path: string, speed?: number): Promise<void> {
+  const args = isValidSpeed(speed) ? [path, '-r', String(speed)] : [path]
+
+  try {
+    currentPlayProcess = Bun.spawn(['afplay', ...args], { stdout: 'ignore', stderr: 'ignore' })
+  } catch (err) {
+    currentPlayProcess = null
+    throw categorizeTTSError(err, 'playback')
+  }
+
+  const proc = currentPlayProcess
+  if (!proc) {
+    throw new TTSError('Audio playback failed to start', 'audio_playback')
+  }
+
+  const exitCode = await proc.exited
+  currentPlayProcess = null
+
+  const wasManualStop = playbackStoppedManually
+  if (wasManualStop) {
+    resetPlaybackStoppedFlag()
+  }
+
+  if (exitCode !== 0 && !wasManualStop) {
+    throw new TTSError(`afplay exited with code ${exitCode}`, 'audio_playback')
+  }
+}
+
+export function stopSpeaking(): void {
+  if (currentPlayProcess) {
+    playbackStoppedManually = true
+    currentPlayProcess.kill()
+    currentPlayProcess = null
+  }
+}
+
+export async function speak(text: string, config: AppConfig): Promise<void> {
+  if (!config.ttsEnabled) return
+
+  const cleanText = cleanTextForSpeech(text)
+  if (!cleanText) return
+
+  const sentences = splitIntoSentences(cleanText)
+  let spokenCount = 0
+  let firstError: TTSError | null = null
+
+  for (const [i, sentence] of sentences.entries()) {
+    const audioPath = join(
+      tmpdir(),
+      `tts-${Date.now()}-${i}.${getTempAudioExtension(config.ttsMode)}`,
+    )
+
+    try {
+      await generateAudio(sentence, config, audioPath)
+      await playAudio(audioPath, config.ttsSpeed)
+      spokenCount += 1
+    } catch (err) {
+      if (err instanceof TTSError) {
+        if (err.type === 'command_not_found') {
+          throw err // Fatal - no point continuing
+        }
+        firstError ??= err
+        if (config.ttsMode === 'serve') {
+          throw err
+        }
+      } else {
+        firstError ??= categorizeTTSError(err, 'generate')
+      }
+    } finally {
+      await unlink(audioPath).catch(() => {})
+    }
+  }
+
+  if (spokenCount === 0 && firstError) {
+    throw firstError
+  }
+}

package/src/setup.ts

@@ -0,0 +1,234 @@
+import { cancel, confirm, intro, isCancel, outro, select, text } from '@clack/prompts'
+import { Command } from 'commander'
+import {
+  getGlobalConfigPath,
+  loadGlobalConfig,
+  writeGlobalConfig,
+  type OrbGlobalConfig,
+} from './services/global-config'
+import { DEFAULT_MODEL_BY_PROVIDER } from './config'
+import { VOICES, type LlmProvider, type Voice } from './types'
+
+const SETUP_CANCELED = 'Setup canceled.'
+const KOKORO_SPACY_INSTALL =
+  '~/.local/share/uv/tools/tts-gateway/bin/python -m spacy download en_core_web_sm'
+
+interface RunSetupOptions {
+  configPath?: string
+}
+
+function ensureInteractiveTerminal(): void {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error('Interactive setup requires a TTY.')
+  }
+}
+
+function throwIfCanceled<T>(value: T | symbol): T {
+  if (isCancel(value)) {
+    cancel(SETUP_CANCELED)
+    throw new Error(SETUP_CANCELED)
+  }
+
+  return value
+}
+
+async function promptText(args: {
+  message: string
+  initialValue?: string
+  placeholder?: string
+  validate?: (value: string) => string | undefined
+}): Promise<string> {
+  const value = await text({
+    message: args.message,
+    initialValue: args.initialValue,
+    placeholder: args.placeholder,
+    validate: args.validate ? (raw) => args.validate?.((raw ?? '').toString().trim()) : undefined,
+  })
+
+  return String(throwIfCanceled(value)).trim()
+}
+
+function defaultModelFor(provider: LlmProvider, current?: string): string {
+  if (!current?.trim()) return DEFAULT_MODEL_BY_PROVIDER[provider]
+  return current
+}
+
+function mergeSetupConfig(base: OrbGlobalConfig, updates: OrbGlobalConfig): OrbGlobalConfig {
+  return {
+    ...base,
+    ...updates,
+    tts: {
+      ...base.tts,
+      ...updates.tts,
+    },
+  }
+}
+
+function printTtsSetupNextSteps(config: OrbGlobalConfig): void {
+  if (!config.tts?.enabled) return
+
+  console.info('')
+
+  if (config.tts.mode === 'generate') {
+    console.info('Generate mode uses macOS `say` and `afplay`; no tts-gateway server is required.')
+    return
+  }
+
+  const serverUrl = config.tts.serverUrl ?? 'http://localhost:8000'
+
+  console.info('Serve mode quick start:')
+  console.info('  uv tool install tts-gateway[kokoro]')
+  console.info('  # Required once for Kokoro inside uv tool environments')
+  console.info(`  ${KOKORO_SPACY_INSTALL}`)
+  console.info('  tts serve --provider kokoro --port 8000')
+  console.info(`Orb will send speech requests to ${serverUrl}.`)
+  console.info('Use --tts-server-url or tts.server_url if your gateway runs elsewhere.')
+}
+
+export async function runSetup(options: RunSetupOptions = {}): Promise<void> {
+  ensureInteractiveTerminal()
+
+  const configPath = options.configPath ?? getGlobalConfigPath()
+  const existing = await loadGlobalConfig(configPath)
+  for (const warning of existing.warnings) {
+    console.warn(`[orb] ${warning}`)
+  }
+
+  const current = existing.config
+  const currentProvider = current.provider ?? 'anthropic'
+  const currentModel = defaultModelFor(currentProvider, current.model)
+
+  intro('orb setup')
+  console.info(`Orb will save your defaults to ${configPath}.`)
+
+  const provider = throwIfCanceled(
+    await select({
+      message: 'Default provider',
+      initialValue: currentProvider,
+      options: [
+        { value: 'anthropic', label: 'Anthropic' },
+        { value: 'openai', label: 'OpenAI' },
+      ],
+    }),
+  ) as LlmProvider
+
+  const model = await promptText({
+    message: 'Default model',
+    initialValue:
+      current.provider === provider ? currentModel : DEFAULT_MODEL_BY_PROVIDER[provider],
+    validate: (value) => (value.length === 0 ? 'Model is required.' : undefined),
+  })
+
+  const skipIntro = throwIfCanceled(
+    await confirm({
+      message: 'Skip the welcome animation by default?',
+      initialValue: current.skipIntro ?? false,
+    }),
+  ) as boolean
+
+  const ttsEnabled = throwIfCanceled(
+    await confirm({
+      message: 'Enable text-to-speech by default?',
+      initialValue: current.tts?.enabled ?? true,
+    }),
+  ) as boolean
+
+  const streamingEnabled = throwIfCanceled(
+    await confirm({
+      message: 'Enable streaming TTS by default?',
+      initialValue: current.tts?.streaming ?? true,
+    }),
+  ) as boolean
+
+  const ttsMode = throwIfCanceled(
+    await select({
+      message: 'Default TTS mode',
+      initialValue: current.tts?.mode ?? 'serve',
+      options: [
+        { value: 'serve', label: 'Serve (HTTP TTS server)' },
+        { value: 'generate', label: 'Generate (local macOS say fallback)' },
+      ],
+    }),
+  ) as 'serve' | 'generate'
+
+  const serverUrl =
+    ttsMode === 'serve'
+      ? await promptText({
+          message: 'Default TTS server URL',
+          initialValue: current.tts?.serverUrl ?? 'http://localhost:8000',
+          validate: (value) =>
+            value.length === 0 ? 'Server URL is required in serve mode.' : undefined,
+        })
+      : undefined
+
+  const voice = throwIfCanceled(
+    await select({
+      message: 'Default voice',
+      initialValue: current.tts?.voice ?? 'alba',
+      options: VOICES.map((value) => ({ value, label: value })),
+    }),
+  ) as Voice
+
+  const speedRaw = await promptText({
+    message: 'Default speech speed',
+    initialValue: String(current.tts?.speed ?? 1.5),
+    validate: (value) => {
+      const num = Number(value)
+      return Number.isFinite(num) && num > 0 ? undefined : 'Enter a positive number.'
+    },
+  })
+
+  const nextConfig = mergeSetupConfig(current, {
+    provider,
+    model,
+    skipIntro,
+    tts: {
+      enabled: ttsEnabled,
+      streaming: streamingEnabled,
+      mode: ttsMode,
+      serverUrl: serverUrl ?? current.tts?.serverUrl,
+      voice,
+      speed: Number(speedRaw),
+    },
+  })
+
+  if (ttsMode !== 'serve' && nextConfig.tts) {
+    delete nextConfig.tts.serverUrl
+  }
+
+  if (existing.exists) {
+    const shouldWrite = throwIfCanceled(
+      await confirm({
+        message: `Overwrite ${configPath}?`,
+        initialValue: true,
+      }),
+    ) as boolean
+
+    if (!shouldWrite) {
+      outro('No changes made.')
+      return
+    }
+  }
+
+  await writeGlobalConfig(nextConfig, configPath)
+  outro(`Saved config to ${configPath}`)
+  printTtsSetupNextSteps(nextConfig)
+}
+
+export async function runSetupCommand(
+  args: string[],
+  options: RunSetupOptions = {},
+): Promise<void> {
+  const program = new Command()
+    .name('orb setup')
+    .description('Create or update ~/.orb/config.toml')
+    .exitOverride()
+    .allowExcessArguments(false)
+    .configureOutput({
+      writeOut: (str) => process.stdout.write(str),
+      writeErr: (str) => process.stderr.write(str),
+    })
+
+  program.parse(args, { from: 'user' })
+  await runSetup(options)
+}

package/src/types/index.ts

@@ -0,0 +1,108 @@
+export type AppState = 'idle' | 'processing' | 'processing_speaking' | 'speaking'
+
+export type DetailMode = 'compact' | 'expanded'
+
+export type TTSErrorType = 'command_not_found' | 'audio_playback' | 'generation_failed'
+
+export class TTSError extends Error {
+  constructor(
+    message: string,
+    public readonly type: TTSErrorType,
+    public readonly originalError?: Error,
+  ) {
+    super(message)
+    this.name = 'TTSError'
+  }
+}
+
+export interface ToolCall {
+  id: string
+  index: number
+  name: string
+  input: Record<string, unknown>
+  status: 'running' | 'complete' | 'error'
+  result?: string
+}
+
+export interface HistoryEntry {
+  id: string
+  question: string
+  toolCalls: ToolCall[]
+  answer: string
+  error?: string | null
+}
+
+export type LlmProvider = 'anthropic' | 'openai'
+
+export const ANTHROPIC_MODELS = [
+  'claude-haiku-4-5-20251001',
+  'claude-sonnet-4-6',
+  'claude-opus-4-6',
+  'claude-opus-4-5-20251101',
+  'claude-sonnet-4-5-20250929',
+  'claude-opus-4-1-20250805',
+  'claude-opus-4-20250514',
+  'claude-sonnet-4-20250514',
+  'claude-3-haiku-20240307',
+] as const
+
+export const VOICES = ['alba', 'marius', 'jean'] as const
+
+export type AnthropicModel = (typeof ANTHROPIC_MODELS)[number]
+export type LlmModelId = string
+export type Voice = (typeof VOICES)[number]
+
+export interface OpenAiSession {
+  provider: 'openai'
+  previousResponseId: string
+}
+
+export type AgentSession = { provider: 'anthropic'; sessionId: string } | OpenAiSession
+
+export interface SavedSession {
+  version: 2
+  projectPath: string
+  llmProvider: LlmProvider
+  llmModel: LlmModelId
+  agentSession?: AgentSession
+  lastModified: string
+  history: HistoryEntry[]
+}
+
+export interface AppConfig {
+  projectPath: string
+  llmProvider: LlmProvider
+  llmModel: LlmModelId
+  openaiApiKey?: string
+  ttsVoice: Voice
+  ttsMode: 'generate' | 'serve'
+  ttsServerUrl?: string
+  ttsSpeed: number
+  ttsEnabled: boolean
+  ttsStreamingEnabled: boolean
+  ttsBufferSentences: number
+  ttsClauseBoundaries: boolean
+  ttsMinChunkLength: number
+  ttsMaxWaitMs: number
+  ttsGraceWindowMs: number
+  startFresh: boolean
+  skipIntro: boolean
+}
+
+export const DEFAULT_CONFIG: AppConfig = {
+  projectPath: process.cwd(),
+  llmProvider: 'anthropic',
+  llmModel: 'claude-haiku-4-5-20251001',
+  ttsVoice: 'alba',
+  ttsMode: 'serve',
+  ttsSpeed: 1.5,
+  ttsEnabled: true,
+  ttsStreamingEnabled: true,
+  ttsBufferSentences: 1,
+  ttsClauseBoundaries: false,
+  ttsMinChunkLength: 15,
+  ttsMaxWaitMs: 150,
+  ttsGraceWindowMs: 50,
+  startFresh: false,
+  skipIntro: false,
+}