@omnivoice/page-agent 0.1.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,26 +0,0 @@
-import { AgentConfig } 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 class PageAgent extends PageAgentCore {
-    panel: Panel;
-    constructor(config: PageAgentConfig);
-}
-
-export declare type PageAgentConfig = AgentConfig & PageControllerConfig & Omit<PanelConfig, 'language'>;
-
-
-export * from "@omnivoice/core";
-
-export { }
-
-
-
-declare global {
-	interface Window {
-		pageAgent?: PageAgent
-		PageAgent: typeof PageAgent
-	}
-}

package/dist/esm/page-agent.js

@@ -1,30 +0,0 @@
-import { PageAgentCore } from "@omnivoice/core";
-import { PageController } from "@omnivoice/page-controller";
-import { Panel } from "@omnivoice/ui";
-export * from "@omnivoice/core";
-//#region src/PageAgent.ts
-/**
-* Copyright (C) 2025 Alibaba Group Holding Limited
-* All rights reserved.
-*/
-var PageAgent = class extends PageAgentCore {
-	panel;
-	constructor(config) {
-		const pageController = new PageController({
-			...config,
-			enableMask: config.enableMask ?? true
-		});
-		super({
-			...config,
-			pageController
-		});
-		this.panel = new Panel(this, {
-			language: config.language,
-			promptForNextTask: config.promptForNextTask
-		});
-	}
-};
-//#endregion
-export { PageAgent };
-
-//# sourceMappingURL=page-agent.js.map

package/dist/esm/page-agent.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"page-agent.js","names":[],"sources":["../../src/PageAgent.ts"],"sourcesContent":["/**\n * Copyright (C) 2025 Alibaba Group Holding Limited\n * All rights reserved.\n */\nimport { type AgentConfig, PageAgentCore } from '@omnivoice/core'\nimport { PageController, type PageControllerConfig } from '@omnivoice/page-controller'\nimport { Panel, type PanelConfig } from '@omnivoice/ui'\n\nexport * from '@omnivoice/core'\n\nexport type PageAgentConfig = AgentConfig & PageControllerConfig & Omit<PanelConfig, 'language'>\n\nexport class PageAgent extends PageAgentCore {\n\tpanel: Panel\n\n\tconstructor(config: PageAgentConfig) {\n\t\tconst pageController = new PageController({\n\t\t\t...config,\n\t\t\tenableMask: config.enableMask ?? true,\n\t\t})\n\n\t\tsuper({ ...config, pageController })\n\n\t\tthis.panel = new Panel(this, {\n\t\t\tlanguage: config.language,\n\t\t\tpromptForNextTask: config.promptForNextTask,\n\t\t})\n\t}\n}\n"],"mappings":";;;;;;;;;AAYA,IAAa,YAAb,cAA+B,cAAc;CAC5C;CAEA,YAAY,QAAyB;EACpC,MAAM,iBAAiB,IAAI,eAAe;GACzC,GAAG;GACH,YAAY,OAAO,cAAc;EAClC,CAAC;EAED,MAAM;GAAE,GAAG;GAAQ;EAAe,CAAC;EAEnC,KAAK,QAAQ,IAAI,MAAM,MAAM;GAC5B,UAAU,OAAO;GACjB,mBAAmB,OAAO;EAC3B,CAAC;CACF;AACD"}