import type { ConversationSetupMessage } from '@repo/agent-domain/src/public/conversation/start-conversation-service/ConversationInputMessage';
import { type ConversationEndedBy, type ConversationId } from '@repo/agent-domain/src/public/conversation/Conversation';
import { type Unbrand } from '@repo/shared-utils/src/zod/Unbrand';
/**
 * Configuration object for connecting to an agent.
 */
export interface ConnectAgentConfig extends ConnectAgentConfigForWSSetupMessage {
    /**
     * Callbacks for conversation events, such as onUserTranscript or onHangup.
     */
    listeners?: ListenersParams;
    /**
     * Indicates whether debug logging is enabled in the browser console.
     */
    debug?: boolean;
}
/**
 * Configuration values that map directly to the WebSocket setup message
 * used to start the agent conversation.
 */
interface ConnectAgentConfigForWSSetupMessage {
    /**
     * Custom greeting message that the agent will use to start the conversation. It overrides the agent's default greeting.
     */
    customGreeting?: ConversationSetupMessage['customGreeting'];
    /**
     * Prompt to provide additional instructions to the agent. It's appended to the agent's prompt.
     */
    prompt?: ConversationSetupMessage['prompt'];
    events?: ConversationSetupMessage['events'];
    /**
     * Whether to continue a previously started conversation session on the server.
     */
    continueConversation?: ConversationSetupMessage['continueConversation'];
    utteranceEndThreshold?: ConversationSetupMessage['utteranceEndThreshold'];
    /**
     * The desired output format for agent audio responses. E.g., 'mp3' or 'mulaw'.
     */
    outputFormat?: ConversationSetupMessage['outputFormat'];
    outputSampleRate?: ConversationSetupMessage['outputSampleRate'];
}
/**
 * Object containing all default agent callback functions.
 */
interface ListenersParams {
    /**
     * Fires each time the user's transcript is recognized.
     */
    onUserTranscript?: (transcript: string) => void;
    /**
     * Fires when the agent's transcript is generated.
     */
    onAgentTranscript?: (transcript: string) => void;
    /**
     * Fires when the agent's speech is complete.
     */
    onAgentSpeechCompleted?: (transcript: string, jobId: number) => void;
    /**
     * Fires when user speech is detected.
     */
    onUserStartedSpeaking?: () => void;
    /**
     * Fires when user speech is no longer detected.
     */
    onUserStoppedSpeaking?: () => void;
    /**
     * Fires when the agent starts outputting audio.
     */
    onAgentStartedSpeaking?: () => void;
    /**
     * Fires when the agent stops outputting audio.
     */
    onAgentStoppedSpeaking?: () => void;
    /**
     * Fires when the agent decides to speak. This is a signal the agent considers the user has stopped speaking,
     * and it's their turn to talk. This marks the beginning of the agent's response generation.
     */
    onAgentDecidedToSpeak?: () => void;
    /**
     * Fired after the conversation ends or the connection is closed.
     */
    onHangup?: (endedBy: ConversationEndedBy) => void;
    /**
     * Fired when a recoverable or fatal error occurs during the conversation.
     */
    onError?: (ev: ErrorDuringConversation) => void;
}
/**
 * The shape of errors that can occur during the conversation.
 */
interface ErrorDuringConversation {
    /**
     * Human-readable description of the error.
     */
    description: string;
    /**
     * Whether this error caused the conversation to end.
     */
    isFatal: boolean;
    /**
     * Error code returned by WebSocket close event, if present.
     */
    serverCode?: number;
    /**
     * The raw WebSocket error event, if present.
     */
    wsEvent?: Event;
    /**
     * The underlying JS error, if present.
     */
    cause?: Error;
}
/**
 * An object containing data about the conversation that has started and functions to control it.
 */
export interface AgentConnectionController {
    /**
     * The conversation ID for this session.
     */
    conversationId: ConversationId;
    /**
     * Mute outgoing audio from the user's microphone. The agent will receive silence data.
     */
    mute: () => void;
    /**
     * Unmute the user's audio stream.
     */
    unmute: () => void;
    /**
     * Hang up (end) the conversation from the user's side.
     */
    hangup: () => void;
}
/**
 * Establishes and returns an active connection controller to an agent via WebSocket,
 * setting up microphone capture, VAD, and a media player for agent audio responses.
 *
 * @param agentWebId - The agent's identifier (WebID) used to connect to the agent.
 * @param options - Configuration object for the connection, including listeners and debug flag.
 * @returns A promise that resolves with an {@link AgentConnectionController}.
 *
 * @throws Will throw an error if any required initialization fails at any step.
 */
export declare function connectAgent(agentId: string, options?: Unbrand<ConnectAgentConfig>): Promise<AgentConnectionController>;
export {};