@bytexbyte/nxtlinq-ai-agent-core-development 0.2.0

package/dist/agent/ChatOrchestrator.d.ts

@@ -0,0 +1,48 @@
+import type { CoreAITApi } from '../api/nxtlinq-api';
+import type { Attachment, Message } from '../types/ait-api';
+import type { AgentConfig } from '../types/agent-config';
+export type SendMessageOptions = {
+    text: string;
+    attachments?: Attachment[];
+    /** Defaults to `config.defaultModel` or `open-ai`. */
+    model?: string;
+    /** Skip appending a user bubble (retries / preset messages). */
+    skipUserMessage?: boolean;
+    isRetry?: boolean;
+    clientPipelineTimings?: Array<{
+        name: string;
+        durationMs: number;
+    }>;
+};
+/**
+ * Platform-agnostic text chat orchestration (no wallet UI, no TTS, no PII UI).
+ */
+export declare class ChatOrchestrator {
+    private readonly config;
+    private readonly api;
+    private readonly onUpdate;
+    private messages;
+    private isLoading;
+    constructor(config: AgentConfig, api: CoreAITApi, onUpdate: () => void);
+    getMessages(): Message[];
+    getIsLoading(): boolean;
+    setMessages(messages: Message[]): void;
+    private emit;
+    private requirePseudoId;
+    private resolveModel;
+    private patchMessage;
+    private appendMessage;
+    loadHistory(options?: {
+        last?: number;
+    }): Promise<void>;
+    /**
+     * Fetch the latest voice-turn rows from the server and merge by message id
+     * (same behavior as web SDK `refreshMessageHistory`).
+     */
+    syncVoiceTurnHistory(options?: {
+        last?: number;
+    }): Promise<void>;
+    sendMessage(options: SendMessageOptions): Promise<void>;
+    private handleToolCall;
+}
+//# sourceMappingURL=ChatOrchestrator.d.ts.map

package/dist/agent/ChatOrchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatOrchestrator.d.ts","sourceRoot":"","sources":["../../src/agent/ChatOrchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAOrD,OAAO,KAAK,EAAiB,UAAU,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,KAAK,EAAE,WAAW,EAAW,MAAM,uBAAuB,CAAC;AAGlE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qBAAqB,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrE,CAAC;AAUF;;GAEG;AACH,qBAAa,gBAAgB;IAKzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAN3B,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,SAAS,CAAS;gBAGP,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,UAAU,EACf,QAAQ,EAAE,MAAM,IAAI;IAGvC,WAAW,IAAI,OAAO,EAAE;IAIxB,YAAY,IAAI,OAAO;IAIvB,WAAW,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI;IAKtC,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,aAAa;IAMf,WAAW,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB7D;;;OAGG;IACG,oBAAoB,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBhE,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;YAwL/C,cAAc;CAoE7B"}

package/dist/agent/ChatOrchestrator.js

@@ -0,0 +1,311 @@
+import { appendServerHistoryIntoMessages, mapServerHistoryToMessages, VOICE_TURN_SYNC_LAST, } from '../history/messageHistory';
+import { extractReplyText } from './extractReplyText';
+/**
+ * Platform-agnostic text chat orchestration (no wallet UI, no TTS, no PII UI).
+ */
+export class ChatOrchestrator {
+    constructor(config, api, onUpdate) {
+        this.config = config;
+        this.api = api;
+        this.onUpdate = onUpdate;
+        this.messages = [];
+        this.isLoading = false;
+    }
+    getMessages() {
+        return this.messages;
+    }
+    getIsLoading() {
+        return this.isLoading;
+    }
+    setMessages(messages) {
+        this.messages = messages;
+        this.onUpdate();
+    }
+    emit() {
+        this.onUpdate();
+    }
+    requirePseudoId() {
+        const id = this.config.pseudoId;
+        if (!id) {
+            throw new Error('pseudoId is required — set AgentConfig.pseudoId before chatting');
+        }
+        return id;
+    }
+    resolveModel(model) {
+        return model ?? this.config.defaultModel ?? 'open-ai';
+    }
+    patchMessage(id, patch) {
+        this.messages = this.messages.map((m) => m.id === id ? { ...m, ...patch } : m);
+        this.emit();
+    }
+    appendMessage(message) {
+        this.messages = [...this.messages, message];
+        this.config.onMessage?.(message);
+        this.emit();
+    }
+    async loadHistory(options) {
+        const pseudoId = this.requirePseudoId();
+        const result = await this.api.agent.getMessageHistory({
+            apiKey: this.config.apiKey,
+            apiSecret: this.config.apiSecret,
+            pseudoId,
+            externalId: this.config.externalId,
+            last: options?.last,
+        });
+        if (result && typeof result === 'object' && 'error' in result && result.error) {
+            throw new Error(String(result.error));
+        }
+        const rows = result.messages ?? [];
+        this.messages = mapServerHistoryToMessages(rows);
+        this.emit();
+    }
+    /**
+     * Fetch the latest voice-turn rows from the server and merge by message id
+     * (same behavior as web SDK `refreshMessageHistory`).
+     */
+    async syncVoiceTurnHistory(options) {
+        const pseudoId = this.requirePseudoId();
+        const result = await this.api.agent.getMessageHistory({
+            apiKey: this.config.apiKey,
+            apiSecret: this.config.apiSecret,
+            pseudoId,
+            externalId: this.config.externalId,
+            last: options?.last ?? VOICE_TURN_SYNC_LAST,
+        });
+        if (result && typeof result === 'object' && 'error' in result && result.error) {
+            throw new Error(String(result.error));
+        }
+        const rows = result.messages ?? [];
+        this.messages = appendServerHistoryIntoMessages(this.messages, rows);
+        this.emit();
+    }
+    async sendMessage(options) {
+        const text = options.text?.trim() ?? '';
+        const hasContent = Boolean(text || (options.attachments && options.attachments.length > 0));
+        if (!hasContent || this.isLoading)
+            return;
+        const model = this.resolveModel(options.model);
+        const pseudoId = this.requirePseudoId();
+        if (!options.skipUserMessage && !options.isRetry) {
+            this.appendMessage({
+                id: `${Date.now()}`,
+                content: text
+                    || (options.attachments?.length
+                        ? `Uploaded ${options.attachments.length} file(s)`
+                        : ''),
+                role: 'user',
+                timestamp: new Date().toISOString(),
+                attachments: options.attachments,
+                metadata: { model },
+            });
+        }
+        this.isLoading = true;
+        this.emit();
+        const isStreamModel = model.endsWith('-stream');
+        let streamAssistantId = null;
+        let streamedReplyBuffer = '';
+        if (isStreamModel && !options.isRetry) {
+            streamAssistantId = `stream-assistant-${Date.now()}`;
+            this.appendMessage({
+                id: streamAssistantId,
+                role: 'assistant',
+                content: '',
+                partialContent: '',
+                isStreaming: true,
+                timestamp: new Date().toISOString(),
+                metadata: { model, agentLlmStream: true },
+            });
+        }
+        try {
+            const apiAttachments = options.attachments?.map((att) => ({
+                type: att.type,
+                url: att.url,
+                name: att.name,
+                mimeType: att.mimeType,
+            }));
+            const response = (await this.api.agent.sendMessage({
+                model,
+                apiKey: this.config.apiKey,
+                apiSecret: this.config.apiSecret,
+                pseudoId,
+                externalId: this.config.externalId,
+                customUserInfo: this.config.customUserInfo,
+                customUsername: this.config.customUsername,
+                message: text
+                    || (options.attachments?.length
+                        ? `Uploaded ${options.attachments.length} file(s)`
+                        : ''),
+                attachments: apiAttachments,
+                isRetry: options.isRetry,
+                ...(options.clientPipelineTimings?.length
+                    ? { clientPipelineTimings: options.clientPipelineTimings }
+                    : {}),
+                onStreamDelta: streamAssistantId
+                    ? (delta) => {
+                        streamedReplyBuffer += delta;
+                        const current = this.messages.find((m) => m.id === streamAssistantId);
+                        this.patchMessage(streamAssistantId, {
+                            partialContent: `${current?.partialContent ?? ''}${delta}`,
+                        });
+                        if (delta) {
+                            this.isLoading = false;
+                            this.emit();
+                        }
+                    }
+                    : undefined,
+            }));
+            const actualModel = response.model ?? model;
+            if (response.error || response.result === 'error') {
+                if (response.requiresWalletConnection || response.requiresPermissionUpdate) {
+                    const msg = response.message
+                        ?? response.error
+                        ?? 'Additional setup is required before continuing.';
+                    this.appendMessage({
+                        id: `${Date.now()}-err`,
+                        content: msg,
+                        role: 'assistant',
+                        timestamp: new Date().toISOString(),
+                        metadata: {
+                            model: actualModel,
+                            toolName: response.toolName,
+                            requiredPermission: response.requiredPermission,
+                        },
+                    });
+                    return;
+                }
+                throw new Error(response.error ?? response.message ?? 'Failed to send message');
+            }
+            if (streamAssistantId && response.toolCall?.toolUse) {
+                this.messages = this.messages.filter((m) => m.id !== streamAssistantId);
+                streamAssistantId = null;
+                this.emit();
+            }
+            if (streamAssistantId && !response.toolCall?.toolUse) {
+                const replyText = extractReplyText(response, streamedReplyBuffer);
+                this.patchMessage(streamAssistantId, {
+                    content: replyText,
+                    isStreaming: false,
+                    partialContent: undefined,
+                    metadata: { model: actualModel, agentLlmStream: true },
+                    piiProtection: response.piiProtection?.anonymizedReply
+                        ? {
+                            anonymizedContent: response.piiProtection.anonymizedReply ?? undefined,
+                            mapping: response.piiProtection.mapping ?? undefined,
+                        }
+                        : undefined,
+                });
+                return;
+            }
+            if (response.toolCall?.toolUse) {
+                await this.handleToolCall(response, actualModel);
+                return;
+            }
+            const replyText = extractReplyText(response, streamedReplyBuffer);
+            this.appendMessage({
+                id: `${Date.now() + 1}`,
+                content: replyText,
+                role: 'assistant',
+                timestamp: new Date().toISOString(),
+                metadata: { model: actualModel },
+                piiProtection: response.piiProtection?.anonymizedReply
+                    ? {
+                        anonymizedContent: response.piiProtection.anonymizedReply ?? undefined,
+                        mapping: response.piiProtection.mapping ?? undefined,
+                    }
+                    : undefined,
+            });
+            if (response.piiProtection?.anonymizedUserMessage) {
+                for (let i = this.messages.length - 1; i >= 0; i--) {
+                    if (this.messages[i].role === 'user') {
+                        this.patchMessage(this.messages[i].id, {
+                            piiProtection: {
+                                anonymizedContent: response.piiProtection.anonymizedUserMessage,
+                                mapping: response.piiProtection.mapping ?? undefined,
+                            },
+                            piiStatus: 'complete',
+                        });
+                        break;
+                    }
+                }
+            }
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.config.onError?.(err);
+            if (streamAssistantId) {
+                this.messages = this.messages.filter((m) => m.id !== streamAssistantId);
+            }
+            this.appendMessage({
+                id: `${Date.now()}-err`,
+                content: err.message,
+                role: 'assistant',
+                timestamp: new Date().toISOString(),
+                error: err.message,
+            });
+        }
+        finally {
+            this.isLoading = false;
+            this.emit();
+        }
+    }
+    async handleToolCall(response, actualModel) {
+        const toolUse = response.toolCall.toolUse;
+        const streamingId = `streaming-${Date.now()}`;
+        this.appendMessage({
+            id: streamingId,
+            content: '',
+            role: 'assistant',
+            timestamp: new Date().toISOString(),
+            isStreaming: true,
+            streamingToolName: toolUse.name,
+            streamingStatus: `Starting ${toolUse.name}...`,
+            streamingProgress: 0,
+            metadata: { model: actualModel, toolUse },
+        });
+        let finalContent = `Tool ${toolUse.name} executed successfully`;
+        if (this.config.onToolUse) {
+            const toolResult = await this.config.onToolUse(toolUse, (update) => {
+                const current = this.messages.find((m) => m.id === streamingId);
+                this.patchMessage(streamingId, {
+                    content: update.partialResult ?? current?.content ?? '',
+                    partialContent: update.partialContent,
+                    streamingProgress: update.progress,
+                    streamingStatus: update.status,
+                    streamingSteps: update.steps ?? current?.streamingSteps,
+                });
+            });
+            if (toolResult?.content) {
+                finalContent = toolResult.content;
+            }
+        }
+        const replyText = extractReplyText(response);
+        if (replyText && replyText !== 'Sorry, I cannot understand your question') {
+            finalContent = `${finalContent}\n\n${replyText}`;
+        }
+        this.patchMessage(streamingId, {
+            content: finalContent,
+            isStreaming: false,
+            streamingProgress: 100,
+            metadata: { model: actualModel, toolUse },
+            piiProtection: response.piiProtection?.anonymizedReply
+                ? {
+                    anonymizedContent: response.piiProtection.anonymizedReply ?? undefined,
+                    mapping: response.piiProtection.mapping ?? undefined,
+                }
+                : undefined,
+        });
+        if (response.assistantMessageId) {
+            try {
+                await this.api.agent.updateMessageContent({
+                    apiKey: this.config.apiKey,
+                    apiSecret: this.config.apiSecret,
+                    messageId: response.assistantMessageId,
+                    content: finalContent,
+                });
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
+}

package/dist/agent/NxtlinqAgent.d.ts

@@ -0,0 +1,65 @@
+import type { CoreAITApi } from '../api/nxtlinq-api';
+import type { PlatformPorts } from '../ports/PlatformPorts';
+import type { Message } from '../types/ait-api';
+import type { AgentConfig } from '../types/agent-config';
+import { type PostTextTtsResult } from '../api/tts';
+import type { StartVoiceSessionOptions, VoiceGreetingOptions, VoiceSession, VoiceStatus, VoiceUserInputOptions } from '../voice/types';
+import { type SendMessageOptions } from './ChatOrchestrator';
+export type { SendMessageOptions };
+export type NxtlinqAgentSnapshot = {
+    messages: Message[];
+    isLoading: boolean;
+    voiceStatus: VoiceStatus;
+    voiceSessionId: string | null;
+};
+type Listener = () => void;
+/**
+ * Platform-agnostic agent entry (text + voice via {@link PlatformPorts.webrtc}).
+ */
+export declare class NxtlinqAgent {
+    private readonly config;
+    private readonly ports;
+    readonly api: CoreAITApi;
+    private readonly chat;
+    private voiceStatus;
+    private voiceSession;
+    private voiceStartInFlight;
+    private voiceHistoryRefreshInFlight;
+    private readonly listeners;
+    private snapshotCache;
+    constructor(config: AgentConfig, ports: PlatformPorts);
+    getSnapshot(): NxtlinqAgentSnapshot;
+    getVoiceSession(): VoiceSession | null;
+    subscribe(listener: Listener): () => void;
+    private emit;
+    setMessages(messages: Message[]): void;
+    loadHistory(options?: {
+        last?: number;
+    }): Promise<void>;
+    /** Merge latest persisted voice-turn messages (default last 2) by message id. */
+    syncVoiceTurnHistory(options?: {
+        last?: number;
+    }): Promise<void>;
+    private refreshVoiceTurnHistory;
+    private finishVoiceTurnSync;
+    private shouldSyncVoiceTurnFromDone;
+    sendMessage(text: string, options?: Omit<SendMessageOptions, 'text'>): Promise<void>;
+    startVoice(options?: Partial<StartVoiceSessionOptions>): Promise<VoiceSession>;
+    stopVoice(reason?: string): Promise<void>;
+    /** Berify-compatible text TTS (`POST /api/tts/openai`). */
+    postTextTts(text: string): Promise<PostTextTtsResult>;
+    /** Data URI for RN `Video` / web `<audio>` playback. */
+    buildTextTtsPlaybackUri(result: PostTextTtsResult): string;
+    getOutputAudioLevel(): number;
+    sendVoiceUserInput(options: VoiceUserInputOptions): void;
+    /**
+     * Auto-greet during voice mode (synthetic user turn + optional product image).
+     * Waits for app data channel when `waitForChannel` is true (default).
+     */
+    triggerVoiceGreeting(options: VoiceGreetingOptions, greetOptions?: {
+        waitForChannel?: boolean;
+        timeoutMs?: number;
+    }): Promise<void>;
+    destroy(): void;
+}
+//# sourceMappingURL=NxtlinqAgent.d.ts.map

package/dist/agent/NxtlinqAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NxtlinqAgent.d.ts","sourceRoot":"","sources":["../../src/agent/NxtlinqAgent.ts"],"names":[],"mappings":"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"}

package/dist/agent/NxtlinqAgent.js

@@ -0,0 +1,256 @@
+import { createNxtlinqApiWithDeps } from '../api/nxtlinq-api';
+import { getAiAgentApiHost, setApiHosts } from '../api/hosts';
+import { STORAGE_KEYS } from '../constants/storageKeys';
+import { VoiceNotSupportedError } from '../ports/WebRTCPort';
+import { buildTextTtsDataUri } from '../api/tts';
+import { startVoiceSessionWithPort } from '../voice/start-voice-session';
+import { triggerVoiceGreeting as runVoiceGreeting } from '../voice/trigger-voice-greeting';
+import { ChatOrchestrator } from './ChatOrchestrator';
+/**
+ * Platform-agnostic agent entry (text + voice via {@link PlatformPorts.webrtc}).
+ */
+export class NxtlinqAgent {
+    constructor(config, ports) {
+        this.voiceStatus = 'idle';
+        this.voiceSession = null;
+        this.voiceStartInFlight = null;
+        this.voiceHistoryRefreshInFlight = null;
+        this.listeners = new Set();
+        this.snapshotCache = null;
+        this.config = config;
+        this.ports = ports;
+        if (config.environment) {
+            setApiHosts(config.environment);
+        }
+        this.api = createNxtlinqApiWithDeps(config.apiKey, config.apiSecret, {
+            storage: ports.storage,
+            http: ports.http,
+            getTimezone: ports.getTimezone,
+        });
+        this.chat = new ChatOrchestrator(config, this.api, () => this.emit());
+    }
+    getSnapshot() {
+        if (this.snapshotCache) {
+            return this.snapshotCache;
+        }
+        this.snapshotCache = {
+            messages: this.chat.getMessages(),
+            isLoading: this.chat.getIsLoading(),
+            voiceStatus: this.voiceStatus,
+            voiceSessionId: this.voiceSession?.id ?? null,
+        };
+        return this.snapshotCache;
+    }
+    getVoiceSession() {
+        return this.voiceSession;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    emit() {
+        this.snapshotCache = null;
+        for (const listener of this.listeners) {
+            listener();
+        }
+    }
+    setMessages(messages) {
+        this.chat.setMessages(messages);
+    }
+    async loadHistory(options) {
+        return this.chat.loadHistory(options);
+    }
+    /** Merge latest persisted voice-turn messages (default last 2) by message id. */
+    async syncVoiceTurnHistory(options) {
+        return this.chat.syncVoiceTurnHistory(options);
+    }
+    refreshVoiceTurnHistory() {
+        if (this.voiceHistoryRefreshInFlight) {
+            return this.voiceHistoryRefreshInFlight;
+        }
+        const run = this.syncVoiceTurnHistory()
+            .catch((err) => {
+            this.config.onError?.(err instanceof Error ? err : new Error(String(err)));
+        })
+            .finally(() => {
+            this.voiceHistoryRefreshInFlight = null;
+        });
+        this.voiceHistoryRefreshInFlight = run;
+        return run;
+    }
+    finishVoiceTurnSync() {
+        void this.refreshVoiceTurnHistory();
+    }
+    shouldSyncVoiceTurnFromDone(event) {
+        return !event.guardrailsBlocked && !event.billingBlocked && !event.error;
+    }
+    async sendMessage(text, options) {
+        return this.chat.sendMessage({ text, ...options });
+    }
+    async startVoice(options) {
+        if (this.voiceSession) {
+            return this.voiceSession;
+        }
+        if (this.voiceStartInFlight) {
+            return this.voiceStartInFlight;
+        }
+        if (!this.ports.webrtc?.isSupported()) {
+            throw new VoiceNotSupportedError();
+        }
+        const pseudoId = this.config.pseudoId;
+        if (!pseudoId) {
+            throw new Error('pseudoId is required — set AgentConfig.pseudoId before startVoice');
+        }
+        const walletAddress = await this.ports.storage.getItem(STORAGE_KEYS.WALLET_ADDRESS);
+        const aitTokenRaw = await this.ports.storage.getItem(STORAGE_KEYS.AIT_SERVICE_ACCESS_TOKEN);
+        let aitToken;
+        if (aitTokenRaw) {
+            try {
+                aitToken = JSON.parse(aitTokenRaw);
+            }
+            catch {
+                aitToken = aitTokenRaw;
+            }
+        }
+        const merged = {
+            apiKey: this.config.apiKey,
+            apiSecret: this.config.apiSecret,
+            pseudoId,
+            externalId: this.config.externalId,
+            walletAddress: walletAddress ?? undefined,
+            aitToken,
+            metadata: options?.metadata ?? this.config.customUserInfo,
+            voiceMode: options?.voiceMode ?? this.config.voiceMode,
+            ...options,
+            onOpen: () => {
+                this.voiceStatus = 'listening';
+                this.emit();
+                options?.onOpen?.();
+            },
+            onStatus: (status, ts) => {
+                const prev = this.voiceStatus;
+                this.voiceStatus = status;
+                this.emit();
+                if (status === 'listening' && prev === 'speaking') {
+                    this.finishVoiceTurnSync();
+                }
+                options?.onStatus?.(status, ts);
+            },
+            onDone: (event) => {
+                if (this.shouldSyncVoiceTurnFromDone(event)) {
+                    this.finishVoiceTurnSync();
+                }
+                options?.onDone?.(event);
+            },
+            onClose: (reason) => {
+                const session = this.voiceSession;
+                this.voiceStatus = 'idle';
+                this.voiceSession = null;
+                this.emit();
+                if (session &&
+                    reason !== 'peerconnection_closed' &&
+                    reason !== 'datachannel_closed') {
+                    void session.stop(typeof reason === 'string' ? reason : 'channel_closed');
+                }
+                options?.onClose?.(reason);
+            },
+            onError: (err) => {
+                const session = this.voiceSession;
+                this.voiceStatus = 'idle';
+                this.voiceSession = null;
+                this.emit();
+                if (session) {
+                    void session.stop('voice_error');
+                }
+                this.config.onError?.(err);
+                options?.onError?.(err);
+            },
+        };
+        this.voiceStartInFlight = startVoiceSessionWithPort({
+            baseUrl: getAiAgentApiHost(),
+            webrtc: this.ports.webrtc,
+            fetchFn: this.ports.http.fetch,
+        }, merged).then((session) => {
+            this.voiceSession = session;
+            this.emit();
+            return session;
+        });
+        try {
+            return await this.voiceStartInFlight;
+        }
+        finally {
+            this.voiceStartInFlight = null;
+        }
+    }
+    async stopVoice(reason) {
+        const session = this.voiceSession;
+        this.voiceSession = null;
+        this.voiceStatus = 'idle';
+        this.emit();
+        if (session) {
+            await session.stop(reason ?? 'client_stop');
+        }
+    }
+    /** Berify-compatible text TTS (`POST /api/tts/openai`). */
+    async postTextTts(text) {
+        return this.api.tts.postTextTts(text);
+    }
+    /** Data URI for RN `Video` / web `<audio>` playback. */
+    buildTextTtsPlaybackUri(result) {
+        return buildTextTtsDataUri(result.audio, result.mimeType);
+    }
+    getOutputAudioLevel() {
+        return this.voiceSession?.getOutputAudioLevel() ?? 0;
+    }
+    sendVoiceUserInput(options) {
+        const session = this.voiceSession;
+        if (!session) {
+            throw new Error('No active voice session — call startVoice() first');
+        }
+        session.sendVoiceUserInput(options);
+    }
+    /**
+     * Auto-greet during voice mode (synthetic user turn + optional product image).
+     * Waits for app data channel when `waitForChannel` is true (default).
+     */
+    async triggerVoiceGreeting(options, greetOptions) {
+        const session = this.voiceSession;
+        if (!session) {
+            throw new Error('No active voice session — call startVoice() first');
+        }
+        const waitForChannel = greetOptions?.waitForChannel !== false;
+        const timeoutMs = greetOptions?.timeoutMs ?? 8000;
+        if (waitForChannel && !session.isAppChannelOpen()) {
+            await new Promise((resolve, reject) => {
+                const started = Date.now();
+                const tick = () => {
+                    if (session.isAppChannelOpen()) {
+                        resolve();
+                        return;
+                    }
+                    if (Date.now() - started >= timeoutMs) {
+                        reject(new Error('Voice app channel did not open in time'));
+                        return;
+                    }
+                    setTimeout(tick, 50);
+                };
+                tick();
+            });
+        }
+        const appendLocal = options.skipUserMessage
+            ? undefined
+            : (message) => {
+                const existing = this.chat.getMessages();
+                this.chat.setMessages([...existing, message]);
+            };
+        runVoiceGreeting({
+            session,
+            options,
+            appendLocalUserMessage: appendLocal,
+        });
+    }
+    destroy() {
+        void this.stopVoice('destroy');
+        this.listeners.clear();
+    }
+}