@openpalm/channel-voice 0.9.0

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@openpalm/channel-voice",
+  "version": "0.9.0",
+  "type": "module",
+  "license": "MPL-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/itlackey/openpalm",
+    "directory": "packages/channel-voice"
+  },
+  "main": "src/index.ts",
+  "files": [
+    "src",
+    "web"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "export CHANNEL_VOICE_SECRET=105a158d326fa54e569b234d4458ada2 && export PORT=8090 && bun --watch run src/index.ts",
+    "dev:unset": "unset  STT_API_KEY && unset OPENAI_API_KEY && export CHANNEL_VOICE_SECRET=105a158d326fa54e569b234d4458ada2 && export PORT=8090 && bun --watch run src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test src/",
+    "test:e2e": "npx playwright test --config=playwright.config.ts"
+  },
+  "peerDependencies": {
+    "@openpalm/channels-sdk": ">=0.8.0 <1.0.0"
+  },
+  "devDependencies": {
+    "@openpalm/channels-sdk": ">=0.8.0 <1.0.0",
+    "@playwright/test": "^1.58.2"
+  }
+}

package/src/config.ts

@@ -0,0 +1,59 @@
+/**
+ * Typed environment configuration for the voice channel.
+ * Bun loads .env automatically. Uses Bun.env, not process.env.
+ */
+
+import { resolve } from 'node:path'
+
+interface Config {
+  server: { webRoot: string }
+  stt: { baseUrl: string; apiKey: string; model: string; timeoutMs: number }
+  tts: { baseUrl: string; apiKey: string; model: string; voice: string; timeoutMs: number }
+  llm: { baseUrl: string; apiKey: string; model: string; timeoutMs: number; systemPrompt: string }
+}
+
+function env(key: string, fallback = ''): string {
+  return Bun.env[key] || fallback
+}
+
+function envInt(key: string, fallback: number): number {
+  const v = Bun.env[key]
+  if (!v) return fallback
+  const n = parseInt(v, 10)
+  return Number.isNaN(n) ? fallback : n
+}
+
+// Resolve API key: check dedicated key first, then shared OPENAI_API_KEY.
+// Only use OPENAI_API_KEY if the dedicated key is truly unset (not present in env at all),
+// to avoid shell-inherited vars overriding .env values unexpectedly.
+function resolveApiKey(dedicatedKey: string): string {
+  const dedicated = Bun.env[dedicatedKey]
+  if (dedicated !== undefined && dedicated !== '') return dedicated
+  return Bun.env.OPENAI_API_KEY || ''
+}
+
+export const config: Config = {
+  server: {
+    webRoot: resolve(env('WEB_ROOT', new URL('../web', import.meta.url).pathname)),
+  },
+  stt: {
+    baseUrl: env('STT_BASE_URL', 'https://api.openai.com').replace(/\/$/, ''),
+    apiKey: resolveApiKey('STT_API_KEY'),
+    model: env('STT_MODEL', 'whisper-1'),
+    timeoutMs: envInt('STT_TIMEOUT_MS', 30_000),
+  },
+  tts: {
+    baseUrl: env('TTS_BASE_URL', 'https://api.openai.com').replace(/\/$/, ''),
+    apiKey: resolveApiKey('TTS_API_KEY'),
+    model: env('TTS_MODEL', 'tts-1'),
+    voice: env('TTS_VOICE', 'alloy'),
+    timeoutMs: envInt('TTS_TIMEOUT_MS', 30_000),
+  },
+  llm: {
+    baseUrl: env('LLM_BASE_URL', 'http://localhost:11434').replace(/\/$/, ''),
+    apiKey: env('LLM_API_KEY', 'ollama'),
+    model: env('LLM_MODEL', 'qwen2.5:3b'),
+    timeoutMs: envInt('LLM_TIMEOUT_MS', 60_000),
+    systemPrompt: env('LLM_SYSTEM_PROMPT', 'You are a helpful voice assistant. Respond conversationally and concisely. Do not use markdown formatting.'),
+  },
+}

package/src/index.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "bun:test";
+import VoiceChannel from "./index";
+
+function mockGuardianFetch() {
+  const mockFetch = async () => {
+    return new Response(JSON.stringify({ answer: "hello back", sessionId: "s1" }), { status: 200 });
+  };
+  return mockFetch as unknown as typeof fetch;
+}
+
+function createHandler() {
+  const channel = new VoiceChannel();
+  Object.defineProperty(channel, "secret", { get: () => "test-secret" });
+  return channel.createFetch(mockGuardianFetch());
+}
+
+describe("voice channel health", () => {
+  it("GET /api/health returns 200 with STT/TTS config", async () => {
+    const handler = createHandler();
+    const resp = await handler(new Request("http://voice/api/health"));
+    expect(resp.status).toBe(200);
+    const body = (await resp.json()) as Record<string, unknown>;
+    expect(body.ok).toBe(true);
+    expect(body.service).toBe("channel-voice");
+    expect(body.stt).toBeDefined();
+    expect(body.tts).toBeDefined();
+    const stt = body.stt as Record<string, unknown>;
+    const tts = body.tts as Record<string, unknown>;
+    expect(stt.model).toBe("whisper-1");
+    expect(tts.model).toBe("tts-1");
+    expect(tts.voice).toBe("alloy");
+  });
+});
+
+describe("voice channel pipeline validation", () => {
+  it("POST /api/pipeline with no audio returns 400", async () => {
+    const handler = createHandler();
+    const form = new FormData();
+    const resp = await handler(
+      new Request("http://voice/api/pipeline", {
+        method: "POST",
+        body: form,
+      })
+    );
+    expect(resp.status).toBe(400);
+    const body = (await resp.json()) as Record<string, unknown>;
+    expect(body.error).toBe("Missing audio file or text");
+  });
+
+  it("POST /api/pipeline rejects oversized audio (>25MB)", async () => {
+    const handler = createHandler();
+    const form = new FormData();
+    // Create a file slightly over 25MB
+    const bigBuffer = new Uint8Array(26 * 1024 * 1024);
+    form.append("audio", new File([bigBuffer], "big.wav", { type: "audio/wav" }));
+    const resp = await handler(
+      new Request("http://voice/api/pipeline", {
+        method: "POST",
+        body: form,
+      })
+    );
+    expect(resp.status).toBe(413);
+    const body = (await resp.json()) as Record<string, unknown>;
+    expect(body.error).toContain("max 25MB");
+  });
+});
+
+describe("voice channel static files", () => {
+  it("GET / returns index.html", async () => {
+    const handler = createHandler();
+    const resp = await handler(new Request("http://voice/"));
+    expect(resp.status).toBe(200);
+    expect(resp.headers.get("Content-Type")).toContain("text/html");
+  });
+
+  it("GET /nonexistent returns 404", async () => {
+    const handler = createHandler();
+    const resp = await handler(new Request("http://voice/nonexistent.xyz"));
+    expect(resp.status).toBe(404);
+  });
+
+  it("GET with path traversal returns 403", async () => {
+    // URL parser normalizes ".." out of paths, so we call route() directly
+    // with a crafted URL to test the defense-in-depth traversal guard.
+    const channel = new VoiceChannel();
+    Object.defineProperty(channel, "secret", { get: () => "test-secret" });
+    const req = new Request("http://voice/etc/passwd", { method: "GET" });
+    const url = new URL("http://voice/../../etc/passwd");
+    // Override pathname to contain traversal (URL normalizes it away)
+    Object.defineProperty(url, "pathname", { value: "/../../etc/passwd" });
+    const resp = await channel.route(req, url);
+    expect(resp).not.toBeNull();
+    expect(resp!.status).toBe(403);
+  });
+});

package/src/index.ts

@@ -0,0 +1,193 @@
+/**
+ * OpenPalm Channel Voice — Voice-driven conversational channel.
+ *
+ * Receives audio, transcribes it (STT), forwards the transcript to the
+ * guardian via the channels SDK, gets the LLM response, synthesizes it
+ * to audio (TTS), and returns everything.
+ *
+ * Endpoints:
+ *   POST /api/pipeline  — Full voice pipeline (audio in -> text + audio out)
+ *   GET  /api/health    — Health check with STT/TTS config info
+ *   GET  /*             — Static file serving from web/ directory
+ */
+
+import { extname, join, resolve } from 'node:path'
+import { BaseChannel, type HandleResult, createLogger } from '@openpalm/channels-sdk'
+import type { GuardianSuccessResponse } from '@openpalm/channels-sdk'
+import { config } from './config'
+import { transcribe, synthesize, chatCompletion } from './providers'
+
+// ── MIME types for static file serving ──────────────────────────────────
+
+const MIME_TYPES: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.webmanifest': 'application/manifest+json; charset=utf-8',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml; charset=utf-8',
+  '.ico': 'image/x-icon',
+}
+
+// ── Channel ─────────────────────────────────────────────────────────────
+
+export default class VoiceChannel extends BaseChannel {
+  name = 'voice'
+
+  async route(req: Request, url: URL): Promise<Response | null> {
+    // POST /api/pipeline — full voice pipeline
+    if (url.pathname === '/api/pipeline' && req.method === 'POST') {
+      return this.handlePipeline(req)
+    }
+
+    // GET /api/health — health check with provider info
+    if (url.pathname === '/api/health' && req.method === 'GET') {
+      return this.json(200, {
+        ok: true,
+        service: 'channel-voice',
+        stt: { model: config.stt.model, configured: !!config.stt.apiKey },
+        tts: { model: config.tts.model, voice: config.tts.voice, configured: !!config.tts.apiKey },
+        llm: { model: config.llm.model, configured: !!config.llm.apiKey },
+      })
+    }
+
+    // GET /* — serve static files from web/ directory
+    if (req.method === 'GET' || req.method === 'HEAD') {
+      return this.serveStatic(req, url)
+    }
+
+    return null
+  }
+
+  // ── Pipeline ────────────────────────────────────────────────────────
+
+  private async handlePipeline(req: Request): Promise<Response> {
+    // Parse FormData
+    let form: FormData
+    try {
+      form = await req.formData()
+    } catch {
+      return this.json(400, { error: 'Invalid form data' })
+    }
+
+    const audioFile = form.get('audio') ?? form.get('file')
+    const textField = form.get('text')
+
+    // Must provide either audio or text
+    if (!(audioFile instanceof File) && !textField) {
+      return this.json(400, { error: 'Missing audio file or text' })
+    }
+    if (audioFile instanceof File && audioFile.size > 25 * 1024 * 1024) {
+      return this.json(413, { error: 'Audio too large (max 25MB)' })
+    }
+
+    const userId = req.headers.get('x-forwarded-for')
+      || req.headers.get('x-real-ip')
+      || 'voice-user'
+
+    // Step 1: STT — transcribe audio, or use provided text (browser STT fallback)
+    let transcript: string
+    if (typeof textField === 'string' && textField.trim()) {
+      transcript = textField.trim()
+    } else if (audioFile instanceof File) {
+      if (!config.stt.apiKey) {
+        return this.json(400, { error: 'STT not configured', code: 'stt_not_configured' })
+      }
+      try {
+        transcript = await transcribe(audioFile)
+      } catch (err) {
+        this.log('error', 'STT failed', { error: (err as Error).message })
+        return this.json(502, { error: `Transcription failed: ${(err as Error).message}`, code: 'stt_error' })
+      }
+    } else {
+      transcript = ''
+    }
+
+    if (!transcript.trim()) {
+      return this.json(200, { transcript: '', response: '', audio: null })
+    }
+
+    // Step 2: Forward transcript to guardian, fall back to direct LLM
+    let answer: string
+    try {
+      const guardianResp = await this.forward({ userId, text: transcript })
+
+      if (!guardianResp.ok) {
+        this.log('error', 'Guardian error', { status: guardianResp.status })
+        throw new Error(`Guardian error (${guardianResp.status})`)
+      }
+
+      const data = (await guardianResp.json()) as GuardianSuccessResponse
+      answer = data.answer ?? ''
+    } catch (err) {
+      this.log('warn', 'Guardian unavailable, trying direct LLM', { error: (err as Error).message })
+      try {
+        answer = await chatCompletion(transcript)
+      } catch (llmErr) {
+        this.log('error', 'LLM fallback also failed', { error: (llmErr as Error).message })
+        return this.json(502, { error: 'No LLM available (guardian down, no direct LLM key configured)' })
+      }
+    }
+
+    // Step 3: TTS — synthesize response to audio (non-fatal)
+    const audio = await synthesize(answer).catch((err) => {
+      this.log('warn', 'TTS failed', { error: (err as Error).message })
+      return null
+    })
+
+    return this.json(200, { transcript, response: answer, audio })
+  }
+
+  // ── Static file serving ─────────────────────────────────────────────
+
+  private async serveStatic(_req: Request, url: URL): Promise<Response> {
+    const pathname = url.pathname === '/' ? '/index.html' : url.pathname
+    const filePath = resolve(join(config.server.webRoot, pathname.replace(/^\/+/, '')))
+
+    // Prevent path traversal
+    if (!filePath.startsWith(config.server.webRoot)) {
+      return new Response('Forbidden', { status: 403 })
+    }
+
+    const file = Bun.file(filePath)
+    if (!(await file.exists())) {
+      // SPA fallback: serve index.html for HTML navigation requests
+      if (_req.headers.get('accept')?.includes('text/html')) {
+        const indexPath = join(config.server.webRoot, 'index.html')
+        const indexFile = Bun.file(indexPath)
+        if (await indexFile.exists()) {
+          return new Response(indexFile, {
+            headers: { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-cache' },
+          })
+        }
+      }
+      return new Response('Not found', { status: 404 })
+    }
+
+    const ext = extname(filePath).toLowerCase()
+    const contentType = MIME_TYPES[ext] || 'application/octet-stream'
+    const isVolatile = ext === '.html' || ext === '.webmanifest' || pathname === '/sw.js'
+    const cacheControl = isVolatile ? 'no-cache' : 'public, max-age=31536000, immutable'
+
+    return new Response(file, {
+      headers: { 'Content-Type': contentType, 'Cache-Control': cacheControl },
+    })
+  }
+
+  // handleRequest is not used — all logic is in route()
+  async handleRequest(_req: Request): Promise<HandleResult | null> {
+    return null
+  }
+}
+
+// Self-start when run directly (not via channel entrypoint)
+if (import.meta.main) {
+  const log = createLogger('channel-voice')
+  log.info('config', {
+    stt: config.stt.apiKey ? `${config.stt.baseUrl} (${config.stt.model})` : 'not configured — browser fallback',
+    tts: config.tts.apiKey ? `${config.tts.baseUrl} (${config.tts.model}, ${config.tts.voice})` : 'not configured — browser fallback',
+  })
+  const channel = new VoiceChannel()
+  channel.start()
+}

package/src/providers.ts

@@ -0,0 +1,156 @@
+/**
+ * STT and TTS API calls. Both use OpenAI-compatible APIs.
+ */
+
+import { createLogger } from '@openpalm/channels-sdk'
+import { config } from './config'
+
+const log = createLogger('channel-voice')
+
+// ── Timeout helper ──────────────────────────────────────────────────────
+
+async function fetchWithTimeout(url: string, init: RequestInit, timeoutMs: number): Promise<Response> {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    return await fetch(url, { ...init, signal: controller.signal })
+  } catch (err) {
+    if ((err as Error).name === 'AbortError') {
+      throw new Error(`Request timed out after ${timeoutMs}ms`)
+    }
+    throw err
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+// ── STT ─────────────────────────────────────────────────────────────────
+
+/**
+ * Transcribe audio via OpenAI-compatible STT API.
+ * Accepts the raw File from the client's FormData.
+ */
+export async function transcribe(audioFile: File): Promise<string> {
+  const form = new FormData()
+  form.set('model', config.stt.model)
+  form.set('file', audioFile, audioFile.name || 'audio.webm')
+
+  const res = await fetchWithTimeout(
+    `${config.stt.baseUrl}/v1/audio/transcriptions`,
+    {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${config.stt.apiKey}` },
+      body: form,
+    },
+    config.stt.timeoutMs,
+  )
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '')
+    throw new Error(`STT failed (${res.status}): ${body || res.statusText}`)
+  }
+
+  const data = (await res.json()) as { text?: string }
+  return data.text || ''
+}
+
+// ── TTS ─────────────────────────────────────────────────────────────────
+
+/**
+ * Synthesize text to audio via OpenAI-compatible TTS API.
+ * Returns base64-encoded mp3 string, or null if TTS is not configured or fails.
+ * TTS failure is non-fatal — the client still gets the text response.
+ */
+/** Strip markdown syntax so TTS reads clean prose. */
+function stripMarkdown(text: string): string {
+  return text
+    .replace(/```[\s\S]*?```/g, '')       // remove code blocks
+    .replace(/`([^`]+)`/g, '$1')          // inline code → plain text
+    .replace(/\*\*([^*]+)\*\*/g, '$1')    // bold → plain
+    .replace(/\*([^*]+)\*/g, '$1')        // italic → plain
+    .replace(/^#{1,6}\s+/gm, '')          // headings → plain
+    .replace(/^\s*[-*+]\s+/gm, '')        // list markers → plain
+    .replace(/^\s*\d+\.\s+/gm, '')        // numbered lists → plain
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') // links → text only
+    .replace(/\n{3,}/g, '\n\n')           // collapse excess newlines
+    .trim()
+}
+
+export async function synthesize(text: string): Promise<string | null> {
+  if (!text.trim() || !config.tts.apiKey) return null
+
+  const cleanText = stripMarkdown(text)
+  if (!cleanText) return null
+
+  let res: Response
+  try {
+    res = await fetchWithTimeout(
+      `${config.tts.baseUrl}/v1/audio/speech`,
+      {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${config.tts.apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          model: config.tts.model,
+          input: cleanText,
+          voice: config.tts.voice,
+          response_format: 'mp3',
+        }),
+      },
+      config.tts.timeoutMs,
+    )
+  } catch (err) {
+    log.error('TTS request error', { error: (err as Error).message })
+    return null
+  }
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '')
+    log.error('TTS API error', { status: res.status, body: body || res.statusText })
+    return null
+  }
+
+  const buffer = await res.arrayBuffer()
+  return Buffer.from(buffer).toString('base64')
+}
+
+// ── LLM (direct fallback when guardian is unavailable) ─────────────────
+
+/**
+ * Direct LLM call via OpenAI-compatible chat completions API.
+ * Used as fallback when the guardian/assistant pipeline is unreachable.
+ */
+export async function chatCompletion(prompt: string): Promise<string> {
+  if (!config.llm.apiKey) throw new Error('No LLM API key configured and guardian unavailable')
+
+  const res = await fetchWithTimeout(
+    `${config.llm.baseUrl}/v1/chat/completions`,
+    {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${config.llm.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        model: config.llm.model,
+        messages: [
+          { role: 'system', content: config.llm.systemPrompt },
+          { role: 'user', content: prompt },
+        ],
+      }),
+    },
+    config.llm.timeoutMs,
+  )
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '')
+    throw new Error(`LLM failed (${res.status}): ${body || res.statusText}`)
+  }
+
+  const data = (await res.json()) as { choices?: Array<{ message?: { content?: string } }> }
+  const text = data.choices?.[0]?.message?.content
+  if (!text) throw new Error('Empty response from LLM')
+  return text
+}