@omnivoice/page-agent 0.2.0 → 0.3.0

package/src/voice/session.ts

@@ -0,0 +1,309 @@
+/**
+ * Sessão de voz: gerencia o contexto compartilhado, enfileira inputs,
+ * emite eventos públicos e coordena alternância entre voz e chat.
+ *
+ * Desenho:
+ * - Estado mutável fica tudo aqui (contexto, histórico, turno).
+ * - Um dono por estado: só VoiceSession muda VoiceContext.
+ * - Eventos públicos são propagados via AsyncIterator.
+ * - Bridge e controlador observam; nunca escrevem direto.
+ * - Controle opcional de mutação (padrão: true / ativado).
+ *   Pode ser desativado para modo read-only (debug/auditoria).
+ */
+
+import { EventEmitter } from "node:events";
+import type {
+  VoiceContext,
+  VoiceEvent,
+  VoiceSnapshot,
+  InputChannel,
+  TurnState,
+  Message,
+  SpeechMode,
+} from "./types.ts";
+import type { UserInput, VoiceSessionReader } from "./bridge.ts";
+import type { VoiceEngine } from "./types.ts";
+import type { VoiceSettings } from "./config.ts";
+
+/**
+ * Sessão de voz: o coração do sistema.
+ * Implementa VoiceSessionReader para o bridge.
+ */
+export class VoiceSession implements VoiceSessionReader {
+  readonly sessionId: string;
+  readonly context: VoiceContext;
+
+  private engine: VoiceEngine | null = null;
+  private settings: VoiceSettings;
+  private inputQueue: UserInput[] = [];
+  private eventEmitter: EventEmitter = new EventEmitter();
+  private isClosed = false;
+
+  /** Flag para ativar/desativar mutação de estado. Padrão: true (ativado). */
+  private allowMutations = true;
+
+  constructor(settings: VoiceSettings, allowMutations: boolean = true) {
+    this.settings = settings;
+    this.sessionId = settings.sessionId;
+    this.allowMutations = allowMutations;
+
+    this.context = {
+      mode: settings.speechMode,
+      channel: "voice", // começa com voz
+      turn: "idle",
+      sessionId: this.sessionId,
+      conversationHistory: [],
+      muted: !settings.mic,
+      lastTurnTime: undefined,
+    };
+  }
+
+  /**
+   * Abre a sessão: inicializa a engine, começa a escutar eventos.
+   */
+  async abrir(engine: VoiceEngine): Promise<void> {
+    if (this.engine) throw new Error("sessão já está aberta");
+
+    this.engine = engine;
+    this.isClosed = false;
+
+    await engine.enter();
+
+    // Emite evento "pronto"
+    this.emitPublic({
+      kind: "session.ready",
+      data: this.snapshot(),
+    });
+
+    // Loop de eventos da engine: transforma em públicos (se aplicável)
+    // e processa inputs enfileirados.
+    this.processEngineEvents();
+  }
+
+  /**
+   * Fecha a sessão.
+   */
+  async fechar(): Promise<void> {
+    this.isClosed = true;
+
+    if (this.engine) {
+      try {
+        await this.engine.exit();
+      } catch (err) {
+        console.error("[VoiceSession.fechar]", err);
+      }
+      this.engine = null;
+    }
+
+    this.eventEmitter.removeAllListeners();
+  }
+
+  /**
+   * Snapshot atual para o painel.
+   */
+  snapshot(): VoiceSnapshot {
+    return {
+      mode: this.context.mode,
+      channel: this.context.channel,
+      state: this.context.turn,
+      muted: this.context.muted,
+      sessionId: this.sessionId,
+      messageCount: this.context.conversationHistory.length,
+      lastMessageTime: this.context.lastTurnTime,
+    };
+  }
+
+  /**
+   * Habilita/desabilita mutação de estado.
+   * Padrão: true (ativado). false = modo auditoria (read-only).
+   */
+  setMutationsAllowed(allowed: boolean): void {
+    this.allowMutations = allowed;
+  }
+
+  /**
+   * Enfileira entrada do usuário (voz transcrita ou texto).
+   * Sem efeito se mutações desabilitadas.
+   */
+  enqueueInput(input: UserInput): void {
+    if (!this.allowMutations) return;
+
+    this.inputQueue.push(input);
+
+    // Sinaliza ao loop que há nova entrada
+    this.processNextInput();
+  }
+
+  /**
+   * Muta/desmuta o microfone.
+   * Sem efeito se mutações desabilitadas.
+   */
+  setMuted(muted: boolean): void {
+    if (!this.allowMutations) return;
+
+    this.context.muted = muted;
+    if (this.engine) {
+      this.engine.setMuted(muted);
+    }
+  }
+
+  /**
+   * Itera eventos públicos até fechar.
+   */
+  async *events(): AsyncIterable<VoiceEvent> {
+    const iterator = this.eventEmitter;
+
+    while (!this.isClosed) {
+      const event: VoiceEvent = await new Promise((resolve) => {
+        iterator.once("public-event", (ev: VoiceEvent) => resolve(ev));
+        if (this.isClosed) resolve({ kind: "error", data: { message: "sessão fechada", code: "CLOSED" } });
+      });
+
+      yield event;
+
+      if (event.kind === "error") break;
+    }
+  }
+
+  /**
+   * Processa entrada do fila.
+   * Atualiza histórico, emite evento ao bridge, passa ao agente.
+   * Sem efeito se mutações desabilitadas.
+   */
+  private async processNextInput(): Promise<void> {
+    if (!this.allowMutations || this.inputQueue.length === 0) return;
+
+    const input = this.inputQueue.shift()!;
+
+    // Atualiza turno
+    this.context.turn = "listening";
+    this.context.channel = input.channel;
+    this.context.lastTurnTime = input.timestamp;
+
+    // Registra no histórico
+    this.context.conversationHistory.push({
+      role: "user",
+      content: input.utterance,
+      timestamp: input.timestamp,
+      channel: input.channel,
+      confidence: input.confidence,
+    });
+
+    // Emite evento público
+    this.emitPublic({
+      kind: "turn.heard",
+      data: {
+        text: input.utterance,
+        confidence: input.confidence,
+      },
+    });
+
+    // Marca turno como "processando" (o agente vai responder)
+    this.context.turn = "processing";
+  }
+
+  /**
+   * Processa eventos da engine (Local ou Realtime) e transforma em públicos.
+   * Roda em background enquanto a sessão está aberta.
+   */
+  private async processEngineEvents(): Promise<void> {
+    if (!this.engine) return;
+
+    try {
+      for await (const engineEvent of this.engine.events()) {
+        if (this.isClosed) break;
+
+        // Transforma evento internal em público (se aplicável)
+        this.handleEngineEvent(engineEvent);
+      }
+    } catch (err) {
+      this.emitPublic({
+        kind: "error",
+        data: {
+          message: err instanceof Error ? err.message : "erro desconhecido",
+          code: "ENGINE_ERROR",
+        },
+      });
+    }
+  }
+
+  /**
+   * Transforma evento da engine em público.
+   */
+  private handleEngineEvent(event: VoiceEvent): void {
+    // Apenas certos eventos são públicos; ver types.ts
+    if (
+      [
+        "session.ready",
+        "user.started",
+        "turn.heard",
+        "agent.started",
+        "agent.finished",
+        "sound.started",
+        "speaker.idle",
+        "error",
+      ].includes(event.kind)
+    ) {
+      this.emitPublic(event);
+    }
+
+    // Registra resposta do agente no histórico
+    if (event.kind === "agent.finished") {
+      const { text } = event.data;
+      this.context.conversationHistory.push({
+        role: "assistant",
+        content: text,
+        timestamp: Date.now(),
+        channel: this.context.channel,
+      });
+      this.context.turn = "idle";
+    }
+
+    // Atualiza turno conforme eventos
+    if (event.kind === "agent.started") {
+      this.context.turn = "speaking";
+    }
+  }
+
+  /**
+   * Emite evento público (para bridge e painel).
+   */
+  private emitPublic(event: VoiceEvent): void {
+    this.eventEmitter.emit("public-event", event);
+  }
+
+  /**
+   * Alterna entre voz e chat.
+   * O histórico é preservado; apenas a origem do próximo input muda.
+   * Sem efeito se mutações desabilitadas.
+   */
+  switchToChannel(channel: InputChannel): void {
+    if (!this.allowMutations) return;
+    if (this.context.channel === channel) return;
+
+    const from = this.context.channel;
+    this.context.channel = channel;
+
+    this.emitPublic({
+      kind: "channel.switched",
+      data: { from, to: channel },
+    });
+  }
+}
+
+/**
+ * Factory: cria e abre uma sessão de voz com a engine apropriada.
+ *
+ * Usa o settings.speechMode para escolher Local ou Realtime,
+ * e carrega a engine correspondente.
+ */
+export async function createVoiceSession(settings: VoiceSettings): Promise<VoiceSession> {
+  const session = new VoiceSession(settings);
+
+  const { createEngine } = await import("./engines.ts");
+  const engine = await createEngine(settings);
+
+  await session.abrir(engine);
+
+  return session;
+}

package/src/voice/types.ts

@@ -0,0 +1,98 @@
+/**
+ * Types compartilhados para a integração de voz.
+ * Baseado no pattern Conversation + Engine de NoStopPageTest.
+ */
+
+/** Modo de fala: local (modelos no device) ou realtime (OpenAI full-duplex). */
+export type SpeechMode = "local" | "realtime";
+
+/** Canal ativo de entrada: voz (microfone) ou chat (texto). */
+export type InputChannel = "voice" | "chat";
+
+/** Tipo de efeito observável após ação. */
+export type EffectKind = "notification" | "navigation" | "loading";
+
+/** Resultado da observação de efeito. */
+export type EffectOutcome =
+  | { status: "observed"; kind: EffectKind; detail: string }
+  | { status: "unknown"; detail: string };
+
+/** Uma mensagem no histórico de conversa. */
+export type Message = {
+  role: "user" | "assistant";
+  content: string;
+  timestamp: number; // milliseconds since epoch
+  channel: InputChannel; // voz ou chat
+  confidence?: number; // 0-1, para speech-to-text
+};
+
+/** Estado de um turno: agente escutando, processando, falando. */
+export type TurnState = "idle" | "listening" | "processing" | "speaking";
+
+/** Snapshot do estado de voz para o painel. */
+export type VoiceSnapshot = {
+  mode: SpeechMode;
+  channel: InputChannel;
+  state: TurnState;
+  muted: boolean;
+  sessionId: string;
+  messageCount: number;
+  lastMessageTime?: number;
+  error?: string;
+};
+
+/** Estado compartilhado entre voz e navegação. */
+export type VoiceContext = {
+  mode: SpeechMode;
+  channel: InputChannel;
+  turn: TurnState;
+  sessionId: string;
+  conversationHistory: Message[];
+  muted: boolean;
+  lastTurnTime?: number;
+};
+
+/** Evento emitido pela sessão de voz. */
+export type VoiceEvent =
+  | { kind: "session.ready"; data: VoiceSnapshot }
+  | { kind: "user.started"; data: { channel: InputChannel } }
+  | { kind: "turn.heard"; data: { text: string; confidence?: number } }
+  | { kind: "agent.started"; data: { turn: TurnState } }
+  | { kind: "agent.finished"; data: { text: string } }
+  | { kind: "sound.started"; data: object }
+  | { kind: "speaker.idle"; data: object }
+  | { kind: "channel.switched"; data: { from: InputChannel; to: InputChannel } }
+  | { kind: "error"; data: { message: string; code: string } };
+
+/** Capacidades oferecidas pela engine de voz. */
+export const TEXT_INPUT = "text_input";
+export const MUTE = "mute";
+export const REPLAY = "replay";
+
+export type Capability = typeof TEXT_INPUT | typeof MUTE | typeof REPLAY | string;
+
+/**
+ * Protocol para uma engine de voz (Local ou Realtime).
+ * Baseado no EngineLike de NoStopPageTest.
+ */
+export interface VoiceEngine {
+  readonly capabilities: ReadonlySet<Capability>;
+
+  /** Abre a engine (inicializa modelos, conexões, etc). */
+  enter(): Promise<void>;
+
+  /** Fecha a engine. */
+  exit(exc?: Error): Promise<void>;
+
+  /** Snapshot atual para o painel. */
+  snapshot(): VoiceSnapshot;
+
+  /** Muta ou desmuta o microfone. */
+  setMuted(muted: boolean): void;
+
+  /** Submete texto como se tivesse sido ouvido (se TEXT_INPUT). */
+  submit(text: string): void;
+
+  /** Itera eventos públicos até fecha. */
+  events(): AsyncIterable<VoiceEvent>;
+}

package/LICENSE

@@ -1,22 +0,0 @@
-MIT License
-
-Copyright (c) 2026 SimonLuvRamen
-Copyright (c) 2026 Alibaba Group Holding Limited
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/dist/esm/PageAgent.d.ts

@@ -1,160 +0,0 @@
-import { AgentConfig } from '@omnivoice/core';
-import { ExecutionResult } from '@omnivoice/core';
-import { PageAgentCore } from '@omnivoice/core';
-import { PageControllerConfig } from '@omnivoice/page-controller';
-import { Panel } from '@omnivoice/ui';
-import { PanelConfig } from '@omnivoice/ui';
-
-export declare function createVoice(options?: VoiceOptions): Voice;
-
-export declare function mountWidget(options?: WidgetOptions): Widget;
-
-export declare class PageAgent extends PageAgentCore {
-    panel: Panel;
-    constructor(config: PageAgentConfig);
-}
-
-export declare type PageAgentConfig = AgentConfig & PageControllerConfig & Omit<PanelConfig, 'language'>;
-
-export declare interface Voice {
-    /** O que o navegador realmente oferece. A UI usa isto para mostrar/ocultar controles. */
-    readonly supported: {
-        input: boolean;
-        output: boolean;
-    };
-    /**
-     * Escuta uma vez e resolve com a transcrição final. Rejeita em erro real; resolve com ""
-     * quando o usuário não fala nada ('no-speech') — não é falha, é "nada foi dito".
-     */
-    listen(): Promise<string>;
-    /** Interrompe a escuta em andamento. */
-    stopListening(): void;
-    /** Fala um texto. `interrupt` corta o que estiver sendo dito antes de começar. */
-    speak(text: string, opts?: {
-        interrupt?: boolean;
-    }): void;
-    /** Para a síntese em andamento. */
-    stopSpeaking(): void;
-    /** Observa transições de estado (a UI mostra o indicador de "ouvindo/falando"). */
-    onStatus(cb: (status: VoiceStatus) => void): () => void;
-}
-
-export declare interface VoiceOptions {
-    /** Idioma BCP-47 do reconhecimento e da síntese. @default 'pt-BR' */
-    lang?: string;
-    /** Habilita o reconhecimento de fala (botão de microfone). @default true */
-    input?: boolean;
-    /** Habilita a síntese de fala (agente fala o resultado). @default false */
-    output?: boolean;
-    /** URI de uma voz específica do speechSynthesis (deixa o módulo escolher quando ausente). */
-    voiceURI?: string;
-    /** Velocidade da síntese (0.1–10). @default 1 */
-    rate?: number;
-    /** Tom da síntese (0–2). @default 1 */
-    pitch?: number;
-    /** Trava de segurança para `listen()`: ms até rejeitar se o reconhecimento não terminar. @default 30000 */
-    listenTimeoutMs?: number;
-}
-
-/**
- * FORK: módulo de voz do widget. Zero dependências — usa apenas a Web Speech API nativa do
- * navegador (reconhecimento + síntese), o que mantém o bundle leve e funciona offline/sem rede
- * além das chamadas do próprio agente.
- *
- * Filosofia (regras do laboratório):
- * - Degrada sem quebrar: se o navegador não tem mic nem síntese, `supported` informa e os
- *   métodos viram no-op silenciosos — a UI decide esconder os botões, o agente segue funcionando.
- * - Espera por condição, nunca por relógio: `listen()` resolve quando chega o resultado final;
- *   o timeout é só uma trava de segurança contra um reconhecimento que "prende" a UI.
- * - Nada de rede própria: o reconhecimento/síntese são do navegador (Chrome/Edge/Safari enviam
- *   apenas o áudio necessário para o serviço de voz do SO; em rede limitada isso é mínimo).
- */
-declare type VoiceStatus = 'idle' | 'listening' | 'speaking';
-
-export declare interface Widget {
-    /** Agente centralizado (mesma instância que o painel controla). `null` até a primeira abertura. */
-    readonly agent: PageAgent | null;
-    /** Voz centralizada (reconhecimento + síntese). `null` até a primeira abertura. */
-    readonly voice: Voice | null;
-    /** Posição do botão-lançador. */
-    readonly launcher: HTMLElement;
-    /** Garante config (busca o `configUrl`) + voz + agente prontos. Idempotente; devolve o agente. */
-    ready(): Promise<PageAgent>;
-    /** Executa uma tarefa programaticamente. */
-    run(task: string): Promise<ExecutionResult>;
-    /** Para a tarefa em andamento (o agente segue reutilizável). */
-    stop(): Promise<void>;
-    /** Abre o painel (propaga erro de config). `hide()`/`toggle()` para fechar/alternar. */
-    show(): Promise<void>;
-    hide(): void;
-    toggle(): void;
-    /** Atualiza config em runtime (recria o agente quando muda algo de LLM/agente). */
-    setConfig(patch: Partial<WidgetOptions>): void;
-    /** Remove launcher, painel e voz da página. */
-    unmount(): void;
-}
-
-export declare interface WidgetOptions {
-    /** Modelo. Ex.: "gpt-4o-mini". */
-    model?: string;
-    /** Endpoint OpenAI-compatible. */
-    baseURL?: string;
-    /**
-     * Chave da API. Só para uso local/sem gateway (ex.: laboratório). Em produção, prefira
-     * `configUrl` + gateway: a chave fica no servidor e não aparece no front-end.
-     */
-    apiKey?: string;
-    /**
-     * URL de uma config pública servida pelo gateway do projeto (ex.: "/api/agent/config").
-     * O widget busca model/idioma/passos/voz DE LÁ — o front nunca precisa da chave. O gateway
-     * é a autoridade: ele injeta a `apiKey` no servidor e força o modelo configurado.
-     */
-    configUrl?: string;
-    /** Customiza o corpo da request (providers específicos). */
-    transformRequestBody?: PageAgentConfig['transformRequestBody'];
-    /** `fetch` custom (proxy, credentials, baixa latência). */
-    customFetch?: PageAgentConfig['customFetch'];
-    maxRetries?: number;
-    /** Idioma da interface e do raciocínio. @default 'pt-BR' */
-    language?: PageAgentConfig['language'];
-    /** Máximo de passos por tarefa. @default 30 */
-    maxSteps?: number;
-    /** Instruções globais/por página. */
-    instructions?: PageAgentConfig['instructions'];
-    /** Ferramentas customizadas. */
-    customTools?: PageAgentConfig['customTools'];
-    /** Máscula sobre a página durante a execução. @default true */
-    enableMask?: boolean;
-    /** Expansão da viewport ao enumerar elementos. @default 0 (só o que está visível) */
-    viewportExpansion?: number;
-    /** Pergunta pela próxima tarefa ao concluir. @default true */
-    promptForNextTask?: boolean;
-    /** Posição do botão-lançador. @default 'bottom-right' */
-    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
-    /** Rótulo acessível do botão-lançador. @default 'Abrir assistente da página' */
-    launcherLabel?: string;
-    /** Começa com o painel aberto (em vez de só o botão). @default false */
-    open?: boolean;
-    voice?: WidgetVoiceOptions;
-}
-
-export declare interface WidgetVoiceOptions extends VoiceOptions {
-    /** Fala o resultado quando a tarefa termina (requer `output: true`). @default true */
-    speakOnComplete?: boolean;
-    /** Fala o próximo objetivo a cada passo (mais falante; útil para mãos-livres). @default false */
-    speakSteps?: boolean;
-}
-
-
-export * from "@omnivoice/core";
-
-export { }
-
-
-
-declare global {
-	interface Window {
-		pageAgent?: PageAgent
-		PageAgent: typeof PageAgent
-	}
-}