@omnivoice/page-agent 0.4.0 → 0.6.0

package/dist/voice/index.d.ts

@@ -0,0 +1,533 @@
+export declare interface AudioPlayback {
+    push(pcm16: Int16Array): void;
+    mark(mark: PlaybackMark): void;
+    clear(): void;
+    close(): Promise<void>;
+}
+
+export declare const browserSocket: SocketFactory;
+
+export declare type Capability = typeof TEXT_INPUT | typeof MUTE | typeof REPLAY | string;
+
+export declare const CAPTURE_BLOCK = 512;
+
+/**
+ * Áudio do navegador para o modo realtime: captura do microfone e reprodução da resposta.
+ *
+ * Nada aqui roda ao importar o módulo. O microfone só é pedido quando `startBrowserMicrophone`
+ * é chamado, e isso só acontece dentro de `RealtimeEngine.enter()`.
+ *
+ * Formato do protocolo do servidor de áudio:
+ * - captura: blocos de 512 amostras int16 a 16 kHz (32 ms), contados a partir de 0;
+ * - reprodução: PCM int16 na taxa anunciada pelo servidor (`ready.rate`).
+ */
+export declare const CAPTURE_RATE = 16000;
+
+export declare function createBrowserVoice(language: string, listenTimeoutMs?: number): LocalVoice;
+
+export declare function createEngine(settings: VoiceSettings, deps?: EngineDeps): VoiceEngine;
+
+/**
+ * Cria a sessão e abre a engine escolhida por `settings.speechMode`.
+ * É aqui — e só aqui — que o microfone/conexão são pedidos; importar o módulo ou criar `VoiceSession` não os liga.
+ */
+export declare function createVoiceSession(settings: VoiceSettings, deps?: EngineDeps): Promise<VoiceSession>;
+
+export declare function createVoiceSettings(overrides?: Partial<VoiceSettings>): VoiceSettings;
+
+/** Tipo de efeito observável após ação. */
+export declare type EffectKind = "notification" | "navigation" | "loading";
+
+/** Resultado da observação de efeito. */
+export declare type EffectOutcome = {
+    status: "observed";
+    kind: EffectKind;
+    detail: string;
+} | {
+    status: "unknown";
+    detail: string;
+};
+
+export declare interface EngineDeps {
+    realtime?: RealtimeDeps;
+    local?: LocalDeps;
+}
+
+/**
+ * Distribuição de eventos para vários consumidores. Cada `subscribe()` recebe a sua própria fila,
+ * então um consumidor lento não perde eventos nem rouba os dos outros. Sem dependência de Node.
+ */
+export declare class EventHub<T> {
+    private readonly subscribers;
+    private closed;
+    get isClosed(): boolean;
+    emit(event: T): void;
+    /** Encerra todos os iteradores: quem espera recebe `done`, quem tem fila a consome antes. */
+    close(): void;
+    subscribe(): AsyncIterable<T>;
+}
+
+/** Canal ativo de entrada: voz (microfone) ou chat (texto). */
+export declare type InputChannel = "voice" | "chat";
+
+/** Junta a origem do servidor (que pode ter um prefixo, ex.: `/t/abc`) com um caminho relativo a ela. */
+export declare function joinServerUrl(base: string, endpoint: string): URL;
+
+export declare interface LocalDeps {
+    voice?: LocalVoice;
+}
+
+export declare class LocalEngine implements VoiceEngine {
+    readonly capabilities: ReadonlySet<Capability>;
+    private readonly settings;
+    private readonly deps;
+    private readonly hub;
+    private voice;
+    private muted;
+    private running;
+    private turn;
+    private lastError;
+    private unmute;
+    constructor(settings: VoiceSettings, deps?: LocalDeps);
+    enter(): Promise<void>;
+    exit(): Promise<void>;
+    snapshot(): VoiceSnapshot;
+    setMuted(muted: boolean): void;
+    submit(text: string): void;
+    /** Fala um texto com a síntese do navegador (a resposta do agente, por exemplo). */
+    speak(text: string): void;
+    events(): AsyncIterable<VoiceEvent>;
+    private waitUnmuted;
+    private listenLoop;
+}
+
+/**
+ * Voz do próprio navegador (Web Speech API): reconhecimento e síntese locais, sem servidor de áudio.
+ * Só toca no microfone quando `listen()` é chamado.
+ */
+export declare interface LocalVoice {
+    /** O navegador oferece reconhecimento de fala. */
+    readonly supportsInput: boolean;
+    /** Escuta uma fala e resolve com a transcrição final; resolve `""` quando ninguém falou. */
+    listen(): Promise<string>;
+    stopListening(): void;
+    speak(text: string): void;
+    stopSpeaking(): void;
+}
+
+/** Uma mensagem no histórico de conversa. */
+export declare type Message = {
+    role: "user" | "assistant";
+    content: string;
+    timestamp: number;
+    channel: InputChannel;
+    confidence?: number;
+};
+
+export declare interface MicrophoneCapture {
+    stop(): Promise<void>;
+}
+
+/** Abre o microfone e entrega blocos até `stop()`. */
+export declare type MicrophoneFactory = (onFrame: (frame: MicrophoneFrame) => void) => Promise<MicrophoneCapture>;
+
+export declare interface MicrophoneFrame {
+    readonly block: number;
+    readonly pcm: Int16Array;
+    /** Instante (ms) no relógio do AudioContext em que o bloco ficou completo. `performance` não existe no escopo do AudioWorklet. */
+    readonly at: number;
+}
+
+export declare const MUTE = "mute";
+
+/** Aceita "1"/"local" e "2"/"realtime" (sem diferenciar maiúsculas); qualquer outra coisa vira `local`. */
+export declare function parseSpeechMode(choice: string): SpeechMode;
+
+export declare type PlaybackFactory = (rate: number, onReport: (report: PlaybackReport) => void) => Promise<AudioPlayback>;
+
+export declare interface PlaybackMark {
+    readonly id: number;
+    readonly label: string;
+    readonly offset: number;
+}
+
+/** Relato do reprodutor ao servidor: `reached`, `rendered` ou `underrun` (a forma que o servidor lê). */
+export declare type PlaybackReport = Readonly<Record<string, unknown>> & {
+    readonly type: string;
+};
+
+/**
+ * Lê a configuração de um objeto de ambiente. O argumento é obrigatório de propósito: o módulo roda
+ * no navegador, onde não existe `process`. Em Node passe `process.env`; no Vite, `import.meta.env`.
+ */
+export declare function readVoiceSettings(env: VoiceEnv): VoiceSettings;
+
+/** Pontos de substituição (testes, ambientes sem DOM). O padrão usa as APIs do navegador. */
+export declare interface RealtimeDeps {
+    fetch?: typeof fetch;
+    socket?: SocketFactory;
+    microphone?: MicrophoneFactory;
+    playback?: PlaybackFactory;
+}
+
+export declare class RealtimeEngine implements VoiceEngine {
+    readonly capabilities: ReadonlySet<Capability>;
+    private readonly settings;
+    private readonly deps;
+    private readonly hub;
+    private socket;
+    private playback;
+    private playbackRate;
+    private microphone;
+    private microphoneStarting;
+    private muted;
+    private opened;
+    private ready;
+    private closing;
+    private turn;
+    private proxySessionId;
+    private lastError;
+    private settle;
+    constructor(settings: VoiceSettings, deps?: RealtimeDeps);
+    enter(): Promise<void>;
+    exit(): Promise<void>;
+    snapshot(): VoiceSnapshot;
+    setMuted(muted: boolean): void;
+    submit(_text: string): void;
+    events(): AsyncIterable<VoiceEvent>;
+    private lease;
+    private onMessage;
+    private onState;
+    private startAudio;
+    private startPlayback;
+    private ensureMicrophone;
+    private stopMicrophone;
+    private sendFrame;
+    private sendPlaybackReport;
+    private sendJson;
+    private onClose;
+    /** Falha durante a abertura rejeita `enter()`; depois dela vira evento de erro. */
+    private fail;
+    private report;
+    private emit;
+    private trace;
+    private teardown;
+}
+
+export declare const REPLAY = "replay";
+
+export declare type SocketFactory = (url: string, handlers: SocketHandlers) => SocketLike;
+
+export declare interface SocketHandlers {
+    onOpen(): void;
+    onMessage(data: string | ArrayBuffer): void;
+    onError(): void;
+    onClose(code: number, reason: string): void;
+}
+
+export declare interface SocketLike {
+    readonly isOpen: boolean;
+    send(data: string | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+}
+
+/**
+ * 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 declare type SpeechMode = "local" | "realtime";
+
+/** Microfone real: `getUserMedia` + AudioWorklet a 16 kHz. Só pede permissão quando chamado. */
+export declare const startBrowserMicrophone: MicrophoneFactory;
+
+/** Reprodutor real: AudioWorklet na taxa pedida; devolve ao servidor onde a reprodução está. */
+export declare const startBrowserPlayback: PlaybackFactory;
+
+/** Capacidades oferecidas pela engine de voz. */
+export declare const TEXT_INPUT = "text_input";
+
+/** Estado de um turno: agente escutando, processando, falando. */
+export declare type TurnState = "idle" | "listening" | "processing" | "speaking";
+
+/**
+ * Entrada de um usuário: voz transcrita ou texto digitado.
+ * Ambos são normalizados para "utterance" (enunciado).
+ */
+export declare type UserInput = {
+    utterance: string;
+    channel: InputChannel;
+    confidence?: number;
+    timestamp: number;
+};
+
+/** Mensagem de erro se a configuração não serve para o modo escolhido; `undefined` se está ok. */
+export declare function validateSettings(settings: VoiceSettings): string | undefined;
+
+export declare const VOICE_DEFAULTS: Omit<VoiceSettings, "sessionId">;
+
+/**
+ * Ponte entre a sessão e quem a consome.
+ *
+ * - Texto digitado entra por `onUserText`, que só o enfileira na sessão.
+ * - Os eventos públicos da sessão entram por `onVoiceEvent`, que REGISTRA o que a sessão aceitou
+ *   (`turn.heard`) e o que o agente respondeu (`agent.finished`). Ele nunca reenfileira: a sessão
+ *   já absorveu a fala do motor, e reenfileirar o `turn.heard` público criaria um ciclo infinito.
+ *
+ * Exemplo de uso:
+ *   const bridge = new VoiceBridge(voiceSession);
+ *   chatInput.onSubmit((text) => bridge.onUserText(text));
+ *   for await (const ev of voiceSession.events()) bridge.onVoiceEvent(ev);
+ */
+export declare class VoiceBridge {
+    private session;
+    private messageBuffer;
+    constructor(session: VoiceSessionReader);
+    /**
+     * Entrada de texto do usuário (chat): vira UserInput e é enfileirada na sessão.
+     * O registro no histórico da ponte acontece quando a sessão publicar o `turn.heard` correspondente.
+     */
+    onUserText(text: string): void;
+    /**
+     * Evento público da sessão. `turn.heard` e `agent.finished` entram no histórico da ponte;
+     * nenhum evento aqui cria entrada nova na sessão.
+     */
+    onVoiceEvent(event: VoiceEvent): void;
+    /**
+     * Contexto atual: tudo o que o page-agent precisa saber sobre voz.
+     * Leitura apenas; nunca muta.
+     */
+    get context(): VoiceContext;
+    /**
+     * Snapshot para o painel.
+     */
+    get snapshot(): VoiceSnapshot;
+    /**
+     * Histórico de mensagens: construído incrementalmente
+     * conforme entradas chegam e respostas são produzidas.
+     */
+    get messages(): readonly Message[];
+    /**
+     * Muta/desmuta o microfone.
+     */
+    setMuted(muted: boolean): void;
+    /**
+     * Registra uma mensagem no histórico local do bridge.
+     * Não persiste (isso é job do store se necessário).
+     */
+    private recordMessage;
+    /**
+     * Reset para testes ou novo começo de conversa.
+     */
+    clearHistory(): void;
+}
+
+/** Estado compartilhado entre voz e navegação. */
+export declare type VoiceContext = {
+    mode: SpeechMode;
+    channel: InputChannel;
+    turn: TurnState;
+    sessionId: string;
+    conversationHistory: Message[];
+    muted: boolean;
+    lastTurnTime?: number;
+};
+
+/**
+ * Protocol para uma engine de voz (Local ou Realtime).
+ * Baseado no EngineLike de NoStopPageTest.
+ */
+export declare 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>;
+}
+
+/** Variáveis de ambiente/`import.meta.env`: valores podem faltar. */
+export declare type VoiceEnv = Readonly<Record<string, string | undefined>>;
+
+export declare class VoiceError extends Error {
+    readonly code: VoiceErrorCode;
+    constructor(code: VoiceErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+
+/** Erros da voz com um `code` estável para quem precisa decidir o que fazer (não depender do texto). */
+export declare type VoiceErrorCode = "INVALID_SETTINGS" | "UNSUPPORTED" | "LEASE_FAILED" | "CONNECTION_FAILED" | "REFUSED" | "TIMEOUT" | "CLOSED" | "MICROPHONE";
+
+/** Evento emitido pela sessão de voz. */
+export declare type VoiceEvent = {
+    kind: "session.ready";
+    data: VoiceSnapshot;
+} | {
+    kind: "user.started";
+    data: {
+        channel: InputChannel;
+    };
+} | {
+    kind: "turn.heard";
+    data: {
+        text: string;
+        confidence?: number;
+        channel?: InputChannel;
+    };
+} | {
+    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;
+    };
+};
+
+export declare class VoiceSession implements VoiceSessionReader {
+    readonly sessionId: string;
+    readonly context: VoiceContext;
+    private engine;
+    private readonly settings;
+    private readonly inputQueue;
+    private readonly hub;
+    private isClosed;
+    /** Flag para ativar/desativar mutação de estado. Padrão: true (ativado). */
+    private allowMutations;
+    constructor(settings: VoiceSettings, allowMutations?: boolean);
+    /** Abre a sessão: abre a engine e passa a repassar os eventos dela. */
+    abrir(engine: VoiceEngine): Promise<void>;
+    /** Fecha a sessão. */
+    fechar(): Promise<void>;
+    /** Snapshot atual para o painel. */
+    snapshot(): VoiceSnapshot;
+    /** Habilita/desabilita mutação de estado. Padrão: true (ativado). false = modo auditoria (read-only). */
+    setMutationsAllowed(allowed: boolean): void;
+    /** Enfileira entrada do usuário (voz transcrita ou texto). Sem efeito se mutações desabilitadas. */
+    enqueueInput(input: UserInput): void;
+    /** Muta/desmuta o microfone. Sem efeito se mutações desabilitadas. */
+    setMuted(muted: boolean): void;
+    /** Eventos públicos a partir de agora, até a sessão fechar. Cada chamada tem a sua fila. */
+    events(): AsyncIterable<VoiceEvent>;
+    /**
+     * 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;
+    /** Processa a fila: atualiza histórico e avisa o bridge. */
+    private processNextInput;
+    /** Repassa os eventos da engine enquanto a sessão estiver aberta. */
+    private processEngineEvents;
+    private handleEngineEvent;
+    private emitPublic;
+}
+
+/**
+ * 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 declare class VoiceSessionController {
+    private session;
+    private bridge;
+    constructor(session: VoiceSessionReader, bridge: VoiceBridge);
+    /**
+     * 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;
+    /**
+     * Contexto atual (apenas leitura).
+     */
+    get context(): VoiceContext;
+    /**
+     * Muta/desmuta.
+     */
+    setMuted(muted: boolean): void;
+}
+
+/**
+ * Contrato que a sessão de voz expõe para o bridge.
+ * Apenas leitura: o bridge nunca escreve no estado da sessão.
+ */
+export declare 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;
+}
+
+export declare interface VoiceSettings {
+    /** `realtime`: áudio full-duplex pelo servidor (proxy). `local`: reconhecimento/síntese do navegador. */
+    readonly speechMode: SpeechMode;
+    /** Idioma BCP-47 usado pelo modo local. */
+    readonly language: string;
+    /** Origem do servidor de áudio, ex.: `http://localhost:8765` ou `https://voz.exemplo.com/t/abc`. */
+    readonly proxyServerUrl: string;
+    /** Caminho (relativo à origem) que entrega o `session_id`. */
+    readonly proxyLeaseEndpoint: string;
+    /** Caminho (relativo à origem) do WebSocket de áudio. */
+    readonly proxyWebSocketEndpoint: string;
+    /** `session_id` já obtido por outro meio; vazio = pedir ao endpoint de lease. */
+    readonly proxySessionId: string;
+    /** Tempo máximo para o servidor aceitar a conexão e avisar que está pronto. */
+    readonly connectTimeoutMs: number;
+    /** Microfone ligado quando a sessão abre (`false` = abre mutado). */
+    readonly mic: boolean;
+    /** Identificador local da sessão (histórico, eventos). */
+    readonly sessionId: string;
+    readonly trace: boolean;
+}
+
+/** Snapshot do estado de voz para o painel. */
+export declare type VoiceSnapshot = {
+    mode: SpeechMode;
+    channel: InputChannel;
+    state: TurnState;
+    muted: boolean;
+    sessionId: string;
+    messageCount: number;
+    lastMessageTime?: number;
+    error?: string;
+};
+
+export { }