@omnivoice/page-agent 0.1.0 → 0.3.0

package/src/voice/bridge.ts

@@ -0,0 +1,230 @@
+/**
+ * O PLUGUE DE VOZ. Conecta a sessão de voz ao page-agent e ao cérebro.
+ *
+ * Desenho (seção 5.1 da spec de voz):
+ * - Este módulo é o ÚNICO que conhece tanto VoiceSession quanto page-agent.
+ * - Abaixo dele fica a sessão de voz: testável sem navegador, sem LLM, sem page-agent.
+ * - Acima ficam observadores (painel, brain, rotina-executor) que consomem eventos.
+ *
+ * O que conecta: OBSERVAÇÃO (leitura) apenas.
+ * - Entrada de voz → prepara e passa ao agente como "input do usuário"
+ * - Resposta do agente → transforma em fala (não está aqui; é na sessão)
+ * - Contexto compartilhado: histórico de mensagens + estado do agente
+ *
+ * Um dono por estado mutável: VoiceSessionController é quem gerencia
+ * alternância voz ↔ chat, e ninguém mais mexe no state de turno.
+ */
+
+import type { VoiceContext, Message, InputChannel, VoiceEvent, VoiceSnapshot } from "./types.ts";
+
+/**
+ * Entrada de um usuário: voz transcrita ou texto digitado.
+ * Ambos são normalizados para "utterance" (enunciado).
+ */
+export type UserInput = {
+  utterance: string;
+  channel: InputChannel;
+  confidence?: number; // 0-1 para transcrição de fala
+  timestamp: number;
+};
+
+/**
+ * Contrato que a sessão de voz expõe para o bridge.
+ * Apenas leitura: o bridge nunca escreve no estado da sessão.
+ */
+export interface VoiceSessionReader {
+  readonly sessionId: string;
+  readonly context: VoiceContext;
+  readonly snapshot: () => VoiceSnapshot;
+
+  /** Enfileira entrada do usuário (voz ou texto). */
+  enqueueInput(input: UserInput): void;
+
+  /** Itera eventos públicos. */
+  events(): AsyncIterable<VoiceEvent>;
+
+  /** Muta/desmuta. */
+  setMuted(muted: boolean): void;
+}
+
+/**
+ * Observador de entrada: o bridge escuta eventos de voz e input de texto,
+ * normaliza para UserInput, e passa à sessão.
+ *
+ * Exemplo de uso:
+ *   const bridge = new VoiceBridge(voiceSession, pageAgent);
+ *   pageAgent.onUserInput((text) => bridge.onUserText(text));
+ *   voiceSession.events().forEach((ev) => bridge.onVoiceEvent(ev));
+ */
+export class VoiceBridge {
+  private session: VoiceSessionReader;
+  private messageBuffer: Message[] = [];
+
+  constructor(session: VoiceSessionReader) {
+    this.session = session;
+  }
+
+  /**
+   * Entrada de texto do usuário (chat).
+   * Normalizada para UserInput e enfileirada.
+   */
+  onUserText(text: string): void {
+    if (!text.trim()) return;
+
+    const input: UserInput = {
+      utterance: text.trim(),
+      channel: "chat",
+      timestamp: Date.now(),
+    };
+
+    this.session.enqueueInput(input);
+    this.recordMessage({
+      role: "user",
+      content: text,
+      channel: "chat",
+      timestamp: input.timestamp,
+    });
+  }
+
+  /**
+   * Evento de voz: transcrição + confiança.
+   * Normaliza e enfileira se for um evento de "turno ouvido".
+   */
+  onVoiceEvent(event: VoiceEvent): void {
+    if (event.kind === "turn.heard") {
+      const { text, confidence } = event.data;
+      if (!text.trim()) return;
+
+      const input: UserInput = {
+        utterance: text.trim(),
+        channel: "voice",
+        confidence,
+        timestamp: Date.now(),
+      };
+
+      this.session.enqueueInput(input);
+      this.recordMessage({
+        role: "user",
+        content: text,
+        channel: "voice",
+        confidence,
+        timestamp: input.timestamp,
+      });
+    }
+
+    if (event.kind === "agent.finished") {
+      const { text } = event.data;
+      this.recordMessage({
+        role: "assistant",
+        content: text,
+        channel: this.session.context.channel,
+        timestamp: Date.now(),
+      });
+    }
+
+    if (event.kind === "channel.switched") {
+      const { from, to } = event.data;
+      // Nada a fazer aqui: o histórico não muda.
+      // O contexto já foi atualizado pela sessão.
+      console.debug(`[VoiceBridge] canais alternados: ${from} → ${to}`);
+    }
+  }
+
+  /**
+   * Contexto atual: tudo o que o page-agent precisa saber sobre voz.
+   * Leitura apenas; nunca muta.
+   */
+  get context(): VoiceContext {
+    return this.session.context;
+  }
+
+  /**
+   * Snapshot para o painel.
+   */
+  get snapshot(): VoiceSnapshot {
+    return this.session.snapshot();
+  }
+
+  /**
+   * Histórico de mensagens: construído incrementalmente
+   * conforme entradas chegam e respostas são produzidas.
+   */
+  get messages(): readonly Message[] {
+    return this.messageBuffer;
+  }
+
+  /**
+   * Muta/desmuta o microfone.
+   */
+  setMuted(muted: boolean): void {
+    this.session.setMuted(muted);
+  }
+
+  /**
+   * Registra uma mensagem no histórico local do bridge.
+   * Não persiste (isso é job do store se necessário).
+   */
+  private recordMessage(msg: Omit<Message, "timestamp"> & { timestamp: number }): void {
+    this.messageBuffer.push(msg as Message);
+
+    // Keeps recent history: discard older than 2 hours
+    const cutoff = Date.now() - 2 * 60 * 60 * 1000;
+    this.messageBuffer = this.messageBuffer.filter((m) => m.timestamp > cutoff);
+  }
+
+  /**
+   * Reset para testes ou novo começo de conversa.
+   */
+  clearHistory(): void {
+    this.messageBuffer = [];
+  }
+}
+
+/**
+ * Controlador de sessão: gerencia transições de canal (voz ↔ chat)
+ * e manutenção de estado.
+ *
+ * Um dono por estado mutável: só aqui muda de "voice" para "chat".
+ * Ninguém mais muda VoiceContext.channel.
+ */
+export class VoiceSessionController {
+  private session: VoiceSessionReader;
+  private bridge: VoiceBridge;
+
+  constructor(session: VoiceSessionReader, bridge: VoiceBridge) {
+    this.session = session;
+    this.bridge = bridge;
+  }
+
+  /**
+   * Muda de canal (voz → chat ou chat → voz).
+   * O contexto é preservado: histórico segue intacto.
+   * Só muda a ORIGEM do próximo input.
+   *
+   * Implementação: sinaliza à sessão e deixa ela gerir o event loop.
+   */
+  switchChannel(to: InputChannel): void {
+    const from = this.session.context.channel;
+    if (from === to) return; // noop
+
+    // A sessão trata essa mudança: emite event "channel.switched"
+    // e atualiza seu próprio context.channel.
+    // O bridge recebe e registra no histórico se necessário.
+    // (Implementação fica em session.ts)
+    console.debug(`[Controller] solicitando mudança: ${from} → ${to}`);
+  }
+
+  /**
+   * Contexto atual (apenas leitura).
+   */
+  get context(): VoiceContext {
+    return this.session.context;
+  }
+
+  /**
+   * Muta/desmuta.
+   */
+  setMuted(muted: boolean): void {
+    this.bridge.setMuted(muted);
+  }
+}

package/src/voice/config.ts

@@ -0,0 +1,200 @@
+/**
+ * Configuração de voz lida do .env e environment.
+ * Padrão: tudo é imutável após criação (frozen dataclass).
+ * Semelhante a duplex/config.py de NoStopPageTest.
+ */
+
+import type { SpeechMode } from "./types.ts";
+
+/** Provedores de LLM disponíveis. */
+export type LLMProvider = "openai" | "typesafe" | "local";
+
+/** Backend de ASR local. */
+export type ASRBackend = "auto" | "cpu" | "gpu" | "wasm";
+
+/**
+ * Configuração de voz congelada após criação.
+ * Todos os valores sensíveis (.repr = false) nunca são logados.
+ */
+export interface VoiceSettings {
+  readonly speechMode: SpeechMode;
+
+  // OpenAI Realtime
+  readonly openaiApiKey: string; // repr=false
+  readonly realtimeVoice: string; // e.g., "marin"
+  readonly nostopServerUrl: string; // URL do servidor NoStopPageTest (proxy para Realtime)
+
+  // LLM (rápida decisão + agente)
+  readonly quickProvider: LLMProvider;
+  readonly quickApiKey: string; // repr=false
+  readonly quickBaseUrl: string;
+  readonly quickModel: string;
+  readonly agentModel: string;
+
+  // LLM alternativo: TypeSafe
+  readonly jevApiKey: string; // repr=false
+  readonly jevBaseUrl: string;
+  readonly jevModel: string;
+
+  // ASR local (Nemotron)
+  readonly asrModel: string; // path ou identificador
+  readonly asrBackend: ASRBackend;
+  readonly asrLanguage: string; // e.g., "pt-BR"
+
+  // TTS local (Supertonic)
+  readonly tts: "supertonic" | "off";
+  readonly superttonicVoice: string; // e.g., "F4"
+  readonly superttonicThreads: number;
+  readonly superttonicSteps: number;
+
+  // Áudio
+  readonly mic: boolean;
+  readonly micFile?: string;
+  readonly endSilenceMs: number;
+  readonly duck: number; // 0-1, ganho enquanto usuário fala
+
+  // Sessão
+  readonly sessionId: string;
+  readonly sessionStore: "memory" | "sqlite" | "redis";
+  readonly maxSessions: number;
+
+  // Debug
+  readonly trace: boolean;
+  readonly mock: boolean;
+}
+
+/**
+ * Padrões globais: todos ficam aqui. Environment pode sobrescrever.
+ */
+const DEFAULTS: Readonly<Omit<VoiceSettings, "sessionId">> = {
+  speechMode: "local",
+
+  openaiApiKey: "",
+  realtimeVoice: "marin",
+  nostopServerUrl: "http://localhost:8000",
+
+  quickProvider: "openai",
+  quickApiKey: "",
+  quickBaseUrl: "https://api.openai.com/v1",
+  quickModel: "gpt-4.5-mini",
+  agentModel: "gpt-4-turbo",
+
+  jevApiKey: "",
+  jevBaseUrl: "https://api.typesafe.ai/v1",
+  jevModel: "jev-latest",
+
+  asrModel: "models/nemotron-3.5-asr-streaming-0.6b-q8_0.gguf",
+  asrBackend: "auto",
+  asrLanguage: "pt-BR",
+
+  tts: "supertonic",
+  superttonicVoice: "F4",
+  superttonicThreads: 4,
+  superttonicSteps: 6,
+
+  mic: true,
+  endSilenceMs: 250,
+  duck: 0.0,
+
+  sessionStore: "memory",
+  maxSessions: 8,
+
+  trace: false,
+  mock: false,
+};
+
+/**
+ * Lê configuração do .env e environment, validando backends conhecidos.
+ * Se um backend não é reconhecido, mantém o default em vez de rejeitar.
+ */
+export function readVoiceSettings(env: Record<string, string> = process.env): VoiceSettings {
+  const get = (key: string, fallback: string = ""): string => env[key] ?? fallback;
+  const getBool = (key: string, fallback: boolean = false): boolean => {
+    const val = get(key);
+    return val === "1" || val === "true" ? true : val === "0" || val === "false" ? false : fallback;
+  };
+  const getInt = (key: string, fallback: number = 0): number => {
+    const val = parseInt(get(key), 10);
+    return Number.isNaN(val) ? fallback : Math.max(1, val);
+  };
+  const getFloat = (key: string, fallback: number = 0): number => {
+    const val = parseFloat(get(key));
+    return Number.isNaN(val) ? fallback : val;
+  };
+
+  const speechMode = getSpeechChoice(get("SPEECH_MODE", get("SPEECH", DEFAULTS.speechMode)));
+  const sessionStore = (["memory", "sqlite", "redis"].includes(get("SESSION_STORE")) ? get("SESSION_STORE") : DEFAULTS.sessionStore) as VoiceSettings["sessionStore"];
+  const asrBackend = (["auto", "cpu", "gpu", "wasm"].includes(get("ASR_BACKEND")) ? get("ASR_BACKEND") : DEFAULTS.asrBackend) as ASRBackend;
+  const tts = (get("TTS") === "off" ? "off" : "supertonic") as "supertonic" | "off";
+  const quickProvider = (["openai", "typesafe", "local"].includes(get("QUICK_PROVIDER")) ? get("QUICK_PROVIDER") : DEFAULTS.quickProvider) as LLMProvider;
+
+  return Object.freeze({
+    speechMode,
+
+    openaiApiKey: get("OPENAI_API_KEY"),
+    realtimeVoice: get("REALTIME_VOICE", DEFAULTS.realtimeVoice),
+    nostopServerUrl: get("NOSTOP_SERVER_URL", DEFAULTS.nostopServerUrl),
+
+    quickProvider,
+    quickApiKey: get("QUICK_API_KEY", get("OPENAI_API_KEY")),
+    quickBaseUrl: get("QUICK_BASE_URL", DEFAULTS.quickBaseUrl),
+    quickModel: get("QUICK_MODEL", DEFAULTS.quickModel),
+    agentModel: get("AGENT_MODEL", DEFAULTS.agentModel),
+
+    jevApiKey: get("JEV_API_KEY", get("TYPESAFE_JEV_APIKEY")),
+    jevBaseUrl: get("JEV_BASE_URL", DEFAULTS.jevBaseUrl),
+    jevModel: get("JEV_MODEL", DEFAULTS.jevModel),
+
+    asrModel: get("ASR_MODEL", DEFAULTS.asrModel),
+    asrBackend,
+    asrLanguage: get("ASR_LANGUAGE", DEFAULTS.asrLanguage),
+
+    tts,
+    superttonicVoice: get("SUPERTONIC_VOICE", DEFAULTS.superttonicVoice),
+    superttonicThreads: getInt("SUPERTONIC_THREADS", DEFAULTS.superttonicThreads),
+    superttonicSteps: getInt("SUPERTONIC_STEPS", DEFAULTS.superttonicSteps),
+
+    mic: getBool("MIC", DEFAULTS.mic),
+    micFile: get("MIC_FILE"),
+    endSilenceMs: getInt("END_SILENCE_MS", DEFAULTS.endSilenceMs),
+    duck: getFloat("DUCK", DEFAULTS.duck),
+
+    sessionId: get("SESSION_ID", `session-${Date.now()}`),
+    sessionStore,
+    maxSessions: getInt("MAX_SESSIONS", DEFAULTS.maxSessions),
+
+    trace: getBool("TRACE"),
+    mock: getBool("MOCK"),
+  });
+}
+
+/**
+ * Normaliza escolha de fala: aceita "1"/"local"/"realtime"/"2", case-insensitive.
+ * Qualquer coisa desconhecida vira "local".
+ */
+function getSpeechChoice(choice: string): SpeechMode {
+  const normalized = choice.trim().toLowerCase();
+  if (normalized === "1" || normalized === "local") return "local";
+  if (normalized === "2" || normalized === "realtime") return "realtime";
+  return "local";
+}
+
+/**
+ * Valida se a configuração está pronta para rodar em um modo específico.
+ * Retorna mensagem de erro, ou undefined se está ok.
+ */
+export function validateSettings(settings: VoiceSettings): string | undefined {
+  if (settings.speechMode === "realtime" && !settings.openaiApiKey) {
+    return "realtime mode requires OPENAI_API_KEY";
+  }
+
+  if (settings.quickProvider === "openai" && !settings.quickApiKey) {
+    return "OpenAI quick provider requires OPENAI_API_KEY or QUICK_API_KEY";
+  }
+
+  if (settings.quickProvider === "typesafe" && !settings.jevApiKey) {
+    return "TypeSafe quick provider requires TYPESAFE_JEV_APIKEY or JEV_API_KEY";
+  }
+
+  return undefined;
+}

package/src/voice/engines.ts

@@ -0,0 +1,161 @@
+/**
+ * Factory de engines de voz: seleciona entre local e realtime (OpenAI full-duplex).
+ * O RealtimeEngine entra via WebSocket para o servidor NoStopPageTest.
+ */
+
+import type { VoiceEngine, SpeechMode } from "./types.ts";
+import type { VoiceSettings } from "./config.ts";
+
+/**
+ * Stub do LocalEngine: os modelos rodam no device.
+ * Implementação completa vem do POC NoStopPageTest/duplex/local_engine.py,
+ * mas aqui é um wrapper mínimo para manter a interface.
+ */
+class LocalEngine implements VoiceEngine {
+  private settings: VoiceSettings;
+  private muted = false;
+
+  constructor(settings: VoiceSettings) {
+    this.settings = settings;
+  }
+
+  async enter(): Promise<void> {
+    console.log("[LocalEngine] Abrindo motor local (stub)");
+    // Implementar integração com Nemotron ASR + Supertonic TTS aqui
+  }
+
+  async exit(): Promise<void> {
+    console.log("[LocalEngine] Fechando motor local");
+  }
+
+  setMuted(muted: boolean): void {
+    this.muted = muted;
+  }
+
+  isMuted(): boolean {
+    return this.muted;
+  }
+}
+
+/**
+ * RealtimeEngine: conecta ao OpenAI Realtime API full-duplex via servidor NoStopPageTest.
+ * O servidor faz proxy: navegador → servidor → OpenAI Realtime.
+ */
+class RealtimeEngine implements VoiceEngine {
+  private settings: VoiceSettings;
+  private muted = false;
+  private socket: WebSocket | null = null;
+  private sessionId: string | null = null;
+
+  constructor(settings: VoiceSettings) {
+    this.settings = settings;
+  }
+
+  async enter(): Promise<void> {
+    console.log("[RealtimeEngine] Abrindo conexão OpenAI Realtime full-duplex");
+
+    // Obter session_id do servidor NoStopPageTest
+    const baseUrl = this.settings.nostopServerUrl || "http://localhost:8000";
+
+    try {
+      const leaseResponse = await fetch(`${baseUrl}/lease`, {
+        method: "GET",
+        credentials: "include",
+      });
+
+      if (!leaseResponse.ok) {
+        throw new Error(`Falha ao obter lease: ${leaseResponse.status}`);
+      }
+
+      const leaseData = await leaseResponse.json();
+      this.sessionId = leaseData.session_id;
+
+      if (!this.sessionId) {
+        throw new Error("Nenhum session_id retornado do servidor");
+      }
+
+      // Conectar ao WebSocket do Realtime
+      const wsUrl = new URL(`${baseUrl}/realtime`);
+      wsUrl.searchParams.set("session", this.sessionId);
+
+      this.socket = new WebSocket(wsUrl.href);
+
+      return new Promise((resolve, reject) => {
+        if (!this.socket) {
+          reject(new Error("WebSocket não foi criado"));
+          return;
+        }
+
+        const onOpen = () => {
+          console.log("[RealtimeEngine] WebSocket conectado");
+          this.socket?.removeEventListener("open", onOpen);
+          this.socket?.removeEventListener("error", onError);
+          resolve();
+        };
+
+        const onError = (event: Event) => {
+          console.error("[RealtimeEngine] Erro ao conectar", event);
+          this.socket?.removeEventListener("open", onOpen);
+          this.socket?.removeEventListener("error", onError);
+          reject(new Error("Falha ao conectar WebSocket"));
+        };
+
+        this.socket.addEventListener("open", onOpen);
+        this.socket.addEventListener("error", onError);
+      });
+    } catch (error) {
+      console.error("[RealtimeEngine.enter]", error);
+      throw error;
+    }
+  }
+
+  async exit(): Promise<void> {
+    console.log("[RealtimeEngine] Fechando conexão");
+    if (this.socket) {
+      this.socket.close();
+      this.socket = null;
+    }
+    this.sessionId = null;
+  }
+
+  setMuted(muted: boolean): void {
+    this.muted = muted;
+    // Sinalizar ao servidor que o mic está mutado
+    if (this.socket && this.socket.readyState === WebSocket.OPEN) {
+      this.socket.send(
+        JSON.stringify({
+          type: "mute",
+          muted,
+        })
+      );
+    }
+  }
+
+  isMuted(): boolean {
+    return this.muted;
+  }
+
+  getSocket(): WebSocket | null {
+    return this.socket;
+  }
+
+  getSessionId(): string | null {
+    return this.sessionId;
+  }
+}
+
+/**
+ * Factory: seleciona e cria a engine correta.
+ */
+export async function createEngine(settings: VoiceSettings): Promise<VoiceEngine> {
+  if (settings.speechMode === "realtime") {
+    if (!settings.openaiApiKey) {
+      throw new Error(
+        "Realtime mode requer OPENAI_API_KEY. Configure a variável de ambiente."
+      );
+    }
+    return new RealtimeEngine(settings);
+  }
+
+  return new LocalEngine(settings);
+}

package/src/voice/index.ts

@@ -0,0 +1,17 @@
+/**
+ * PageAgent Voice Module: OpenAI Realtime full-duplex integration
+ *
+ * Export the complete voice system: session management, engines, config, and types.
+ */
+
+export { VoiceSession, createVoiceSession } from "./session.ts";
+export type { VoiceSessionReader, UserInput } from "./bridge.ts";
+
+export { createEngine, LocalEngine, RealtimeEngine } from "./engines.ts";
+export type { VoiceEngine, SpeechMode, InputChannel, TurnState, Message, VoiceContext, VoiceSnapshot, VoiceEvent } from "./types.ts";
+
+export { readVoiceSettings, validateSettings } from "./config.ts";
+export type { VoiceSettings, LLMProvider, ASRBackend } from "./config.ts";
+
+export { createVoiceBridge } from "./bridge.ts";
+export type { VoiceBridge } from "./bridge.ts";