Voice

export type AudioFormat = "pcm16" | "g711_ulaw" | "g711_alaw";

export declare function audioFormatToGa(fmt?: AudioFormat): {
    type: string;
    rate?: number;
};

/** Whether user speech cancels the current spoken reply. */
export type BargeInPolicy = "always" | "never";

/** GA `session.update` body (`session.type: "realtime"`). */
export declare function buildOpenAIRealtimeSession(modelId: string, config: RealtimeSessionConfig): Record<string, unknown>;

/**
 * OpenAI Realtime REST helpers — ephemeral browser keys and WebRTC call creation.
 * https://developers.openai.com/api/docs/guides/realtime
 */
export interface ClientSecretOpts {
    apiKey?: string;
    signal?: AbortSignal;
    baseURL?: string;
    model?: string;
    /** Hashed end-user id for OpenAI safety enforcement. */
    safetyIdentifier?: string;
    expiresAfterSeconds?: number;
}

export interface ClientSecretResult {
    value: string;
    expiresAt?: number;
    raw: unknown;
}

export declare function createRealtimeCall(opts?: RealtimeCallOpts): Promise<{
    id: string;
    sdp: string;
    raw: unknown;
}>;

export declare function createRealtimeClientSecret(opts?: ClientSecretOpts): Promise<ClientSecretResult>;

export interface CreateResponseOpts {
    instructions?: string;
    /** `"none"` = out-of-band (not stored on the conversation). */
    conversation?: "none" | "auto";
    modalities?: Array<"text" | "audio">;
}

export declare const DEFAULT_REALTIME_MODEL = "gpt-realtime-2.1";

export declare const DEFAULT_TRANSCRIPTION_MODEL = "gpt-transcribe";

export interface GoogleLiveConfig {
    apiKey?: string;
}

export declare class GoogleLiveProvider implements RealtimeProvider {
    readonly providerId = "google-live";
    readonly capabilities: {
        manualCommit: boolean;
        images: boolean;
        asyncTools: boolean;
        transcripts: boolean;
        resume: boolean;
        recovery: "session-resumption";
        inputSampleRateHz: number;
        outputSampleRateHz: number;
    };
    readonly modelId: string;
    constructor(modelId?: string, config?: GoogleLiveConfig);
    connect(config: RealtimeSessionConfig): Promise<RealtimeConnection>;
}

export interface NoiseReductionConfig {
    type: "near_field" | "far_field";
}

export interface OpenAIRealtimeConfig {
    apiKey?: string;
    baseURL?: string;
}

export declare class OpenAIRealtimeProvider implements RealtimeProvider {
    readonly providerId = "openai-realtime";
    readonly capabilities: {
        manualCommit: boolean;
        images: boolean;
        asyncTools: boolean;
        transcripts: boolean;
        resume: boolean;
        recovery: "fresh";
        inputSampleRateHz: number;
        outputSampleRateHz: number;
    };
    readonly modelId: string;
    constructor(modelId?: string, config?: OpenAIRealtimeConfig);
    connect(config: RealtimeSessionConfig): Promise<RealtimeConnection>;
}

export interface RealtimeCallOpts {
    apiKey?: string;
    signal?: AbortSignal;
    baseURL?: string;
    model?: string;
    /** @deprecated Unsupported by the Realtime create-call endpoint; SIP uses a separate lifecycle. */
    sipUri?: string;
    sdp?: string;
    safetyIdentifier?: string;
}

export interface RealtimeConnection {
    /** Native transports expose closure so a connect/close race cannot return an already dead session. */
    readonly connectionState?: "open" | "closed";
    /** Client owns OpenAI continuation; Gemini resumes when a tool response arrives. */
    readonly toolContinuation?: "client" | "provider";
    sendAudio(data: Buffer): void;
    sendText(text: string): void;
    sendImage(image: Buffer | string, opts?: {
        mimeType?: string;
        text?: string;
    }): void;
    sendToolResult(callId: string, result: string): void;
    createResponse(opts?: CreateResponseOpts): void;
    commitAudio(): void;
    interrupt(): void;
    close(): Promise<void>;
    on<K extends RealtimeEvent>(event: K, handler: (data: RealtimeEventMap[K]) => void): void;
    off<K extends RealtimeEvent>(event: K, handler: (data: RealtimeEventMap[K]) => void): void;
}

export type RealtimeEvent = keyof RealtimeEventMap;

export type RealtimeEventMap = {
    audio: {
        data: Buffer;
        mimeType?: string;
        generationId?: string;
    };
    text: {
        text: string;
    };
    transcript: {
        text: string;
        role: "user" | "assistant";
        segmentId?: string;
        kind?: "partial" | "final";
        generationId?: string;
    };
    tool_call: RealtimeToolCall;
    usage: {
        promptTokens: number;
        completionTokens: number;
        totalTokens: number;
    };
    interrupted: {};
    error: {
        error: Error;
    };
    connected: {};
    disconnected: {};
    idle: {};
    generation_start: {
        generationId: string;
    };
    turn_complete: {
        generationId?: string;
    };
    go_away: {
        timeLeft?: string;
    };
    session_resume: {
        handle?: string;
        resumable: boolean;
    };
    recovery: RealtimeRecoveryState;
};

export interface RealtimeMcpServer {
    serverLabel: string;
    serverUrl: string;
    headers?: Record<string, string>;
}

export interface RealtimeProvider {
    readonly capabilities?: {
        manualCommit: boolean;
        images: boolean;
        asyncTools: boolean;
        transcripts: boolean;
        resume: boolean;
        /** Advertised recovery contract; absent means recovery is unsupported. */
        recovery?: "session-resumption" | "fresh";
        inputSampleRateHz: number;
        outputSampleRateHz: number;
    };
    readonly providerId: string;
    readonly modelId: string;
    connect(config: RealtimeSessionConfig): Promise<RealtimeConnection>;
}

export type RealtimeRecoveryContinuity = "session-resumption" | "fresh";

/** Opt-in, bounded recovery. No audio, user input, or tool results are resent. */
export interface RealtimeRecoveryPolicy {
    /** Default: stop when a safe provider checkpoint is unavailable. Fresh loses conversation context. */
    fallback?: "stop" | "fresh";
    /** Total reconnect attempts over this logical session, including successful reconnects. Default: 3. */
    maxAttempts?: number;
    initialDelayMs?: number;
    maxDelayMs?: number;
    connectTimeoutMs?: number;
    /** Maximum elapsed time for one recovery incident, including backoff. Default: 30 seconds. */
    maxElapsedMs?: number;
}

export interface RealtimeRecoveryState {
    status: "recovering" | "recovered" | "failed";
    attempt: number;
    continuity?: RealtimeRecoveryContinuity;
    reason: "disconnected" | "go-away" | "unsafe-checkpoint" | "uncertain-tools" | "exhausted";
    /** Replacement sessions never replay output and require new user input before forwarding output. */
    requiresInput: boolean;
}

export interface RealtimeSessionConfig {
    signal?: AbortSignal;
    /** Provider session checkpoint. Gemini only; handles must stay with their original owner/configuration. */
    sessionResumption?: {
        handle?: string;
    };
    instructions?: string;
    voice?: string;
    tools?: ToolDefinition[];
    inputAudioFormat?: AudioFormat;
    outputAudioFormat?: AudioFormat;
    turnDetection?: TurnDetectionConfig | null;
    temperature?: number;
    maxResponseOutputTokens?: number | "inf";
    apiKey?: string;
    reasoningEffort?: ReasoningEffort;
    transcriptionModel?: string;
    transcriptionContext?: OpenAITranscriptionContext;
    noiseReduction?: NoiseReductionConfig;
    mcpServers?: RealtimeMcpServer[];
    safetyIdentifier?: string;
    translation?: VoiceTranslationConfig;
}

export interface RealtimeToolCall {
    id: string;
    name: string;
    arguments: string;
}

export type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh";

export interface SemanticVadConfig {
    type: "semantic_vad";
    eagerness?: SemanticVadEagerness;
    createResponse?: boolean;
    interruptResponse?: boolean;
}

export type SemanticVadEagerness = "low" | "medium" | "high" | "auto";

export interface ServerVadConfig {
    type: "server_vad";
    threshold?: number;
    prefixPaddingMs?: number;
    silenceDurationMs?: number;
    createResponse?: boolean;
    interruptResponse?: boolean;
    /** After this idle (ms) the model speaks (“still there?”). */
    idleTimeoutMs?: number;
}

/** When to talk around a tool call. Long tools (browse_web) should not go silent. */
export type ToolCallBehavior = "silent" | "speakBefore" | "speakAfter" | "speakBeforeAndAfter";

export type TurnDetectionConfig = ServerVadConfig | SemanticVadConfig;

export declare function turnDetectionToGa(td: TurnDetectionConfig | null | undefined): Record<string, unknown> | null | undefined;

export declare class VoiceAgent {
    readonly name: string;
    readonly approvalManager: ApprovalManager | null;
    get audioFormats(): {
        input: SpeechFormat;
        output: SpeechFormat;
    };
    get memory(): MemoryManager | null;
    constructor(config: VoiceAgentConfig);
    connect(opts?: {
        apiKey?: string;
        signal?: AbortSignal;
        tenantId?: string;
        runMode?: RunMode;
        sessionId?: string;
        userId?: string;
        /** Prior call transcript — appended to instructions (warm transfer). */
        resumeTranscript?: string;
    }): Promise<VoiceSession>;
    /**
     * Warm-transfer: close `from`, open a session on this agent with the same transcript.
     */
    handoff(from: VoiceSession, opts?: {
        apiKey?: string;
        userId?: string;
    }): Promise<VoiceSession>;
}

export interface VoiceAgentConfig {
    approval?: ApprovalConfig;
    approvalManager?: ApprovalManager;
    executionPolicy?: ExecutionPolicy;
    name: string;
    provider: RealtimeProvider;
    /** Off by default. Recovery state is emitted on the VoiceSession `recovery` event. */
    recovery?: RealtimeRecoveryPolicy;
    instructions?: string;
    tools?: ToolDef[];
    voice?: string;
    /**
     * Turn detection. Default: `{ type: "semantic_vad", eagerness: "low" }`.
     * Pass `{ type: "server_vad" }` for silence-based VAD, or `null` for push-to-talk.
     */
    turnDetection?: TurnDetectionConfig | null;
    inputAudioFormat?: AudioFormat;
    outputAudioFormat?: AudioFormat;
    temperature?: number;
    maxResponseOutputTokens?: number | "inf";
    eventBus?: EventBus;
    logLevel?: LogLevel;
    memory?: UnifiedMemoryConfig;
    model?: ModelProvider;
    sessionId?: string;
    userId?: string;
    skills?: Array<Skill | string>;
    costTracker?: CostTracker;
    /** Realtime 2.x thinking depth. Default: `low`. */
    reasoningEffort?: ReasoningEffort;
    /** Input transcription model. Default: `gpt-transcribe` (native WebSocket sessions). */
    transcriptionModel?: string;
    transcriptionContext?: OpenAITranscriptionContext;
    noiseReduction?: NoiseReductionConfig;
    /** Remote MCP servers attached to the OpenAI Realtime session. */
    mcpServers?: RealtimeMcpServer[];
    safetyIdentifier?: string;
    translation?: VoiceTranslationConfig;
    /**
     * One client-owned continuation follows completed OpenAI tool calls.
     * Legacy speakBefore variants no longer create competing out-of-band responses.
     */
    toolCallBehavior?: ToolCallBehavior;
    /** User speech cancels the current reply. Default: `always`. */
    bargeIn?: BargeInPolicy;
    recording?: VoiceRecordingConfig;
}

export declare class VoicePipeline {
    get migrationDiagnostics(): VoiceMigrationDiagnostic[];
    constructor(config: VoicePipelineConfig);
    transcribe(audio: Buffer, mimeType?: string, signal?: AbortSignal): Promise<string>;
    speak(text: string, signal?: AbortSignal): Promise<Buffer>;
    turn(audio: Buffer, mimeType?: string, signal?: AbortSignal): Promise<VoicePipelineTurn>;
}

/**
 * Chained STT → LLM → TTS turn. Use when you do not want a single
 * speech-to-speech realtime model (Deepgram/Cartesia-style stack).
 * Talks to OpenAI's file transcription + speech endpoints.
 */
export interface VoicePipelineConfig {
    llm: ModelProvider;
    apiKey?: string;
    baseURL?: string;
    sttModel?: string;
    transcriptionContext?: OpenAITranscriptionContext;
    fetch?: typeof fetch;
    ttsModel?: string;
    voice?: string;
    instructions?: string;
}

export interface VoicePipelineTurn {
    transcript: string;
    reply: string;
    audio: Buffer;
}

export interface VoiceRecording {
    output: Buffer;
    input: Buffer;
}

export interface VoiceRecordingConfig {
    output?: boolean;
    input?: boolean;
}

export interface VoiceSession {
    sendAudio(data: Buffer): void;
    sendText(text: string): void;
    sendImage(image: Buffer | string, opts?: {
        mimeType?: string;
        text?: string;
    }): void;
    commitAudio(): void;
    interrupt(): void;
    close(): Promise<void>;
    /** Playback-confirmed projection; unacknowledged generated text is marked unknown. */
    acknowledgePlayback?(ack: PlaybackAck): void;
    getTranscript(): string;
    getRecording(): VoiceRecording;
    on<K extends VoiceSessionEvent>(event: K, handler: (data: VoiceSessionEventMap[K]) => void): this;
    off<K extends VoiceSessionEvent>(event: K, handler: (data: VoiceSessionEventMap[K]) => void): this;
}

export type VoiceSessionEvent = keyof VoiceSessionEventMap;

export type VoiceSessionEventMap = RealtimeEventMap & {
    tool_call_start: {
        name: string;
        args: unknown;
    };
    tool_result: {
        name: string;
        result: string;
    };
};

export interface VoiceTranslationConfig {
    /** Hint the model to translate speech into this language (BCP-47 or name). */
    targetLanguage: string;
}

/** Context for the current GPT transcription models, not conversation instructions. */
export interface OpenAITranscriptionContext {
    prompt?: string;
    keywords?: readonly string[];
    languages?: readonly string[];
}

export interface SpeechFormat {
    encoding: SpeechEncoding;
    sampleRateHz: number;
    channels: 1;
}

export type SpeechEncoding = "pcm_s16le" | "mulaw" | "alaw";

export interface VoiceMigrationDiagnostic {
    code: "transcription-model-deprecated" | "tts-snapshot-deprecated" | "prompt-object-deprecated";
    message: string;
    shutdownDate: string;
    source: string;
    verifiedAt: string;
}

export interface PlaybackAck {
    generationId: string;
    playedCharacters?: number;
    complete?: boolean;
}