Voice Agents

// ============================================
// VOICE PIPELINE CONFIGURATION (Agent-Level)
// ============================================

/**
 * Voice configuration stored on the agent.
 * Set via POST/PATCH /agents endpoints.
 *
 * Discriminated union on `pipelineMode`:
 * - 'batch': Full audio capture -> STT -> LLM -> TTS -> play (sequential)
 * - 'streaming': Streaming LLM + sentence-chunked TTS (lower latency)
 * - 'sts': Speech-to-speech (future, not yet implemented)
 */
type AgentVoiceConfig =
  | BatchStreamingVoiceConfig
  | StsVoiceConfig;

interface BatchStreamingVoiceConfig {
  /** Pipeline mode */
  pipelineMode: 'batch' | 'streaming';
  /**
   * ElevenLabs voice ID for TTS.
   * If omitted, uses platform default voice.
   */
  voiceId?: string;
}

interface StsVoiceConfig {
  /** Speech-to-speech mode (not yet implemented) */
  pipelineMode: 'sts';
  /** STS provider */
  stsProvider: 'openai' | 'gemini';
}

// ============================================
// CONNECT_AGENT NODE CONFIGURATION
// ============================================

/**
 * Configuration for the CONNECT_AGENT call flow node.
 * This is NOT an API endpoint - it's the node config schema
 * used in the call flow builder UI.
 */
interface ConnectAgentNodeConfig {
  /** Agent UUID (required). Must reference an 'active' agent. */
  agentId: string;

  /**
   * Maximum conversation turns before forced exit.
   * Default: 10 | Min: 1 | Max: 50
   */
  maxTurns?: number;

  /**
   * Total conversation timeout in milliseconds.
   * Default: 300000 (5 min) | Min: 30000 (30s) | Max: 600000 (10 min)
   */
  conversationTimeout?: number;

  /**
   * Per-turn timeout in milliseconds (how long to wait for user speech).
   * Default: 10000 (10s) | Min: 3000 (3s) | Max: 30000 (30s)
   */
  turnTimeout?: number;

  /**
   * Phrases that trigger conversation exit (checked every turn in both exit modes).
   * Default: ['goodbye', 'bye', 'thank you goodbye']
   * Max: 10 phrases | Max length per phrase: 100 chars
   */
  exitPhrases?: string[];

  /**
   * How the agent determines when to end the conversation.
   * Default: 'function_call'
   *
   * - 'function_call': LLM calls end_conversation tool (recommended)
   * - 'phrase_match': Pattern matching against agent response for [COMPLETE]
   *
   * See end-call-tool.md for full details.
   */
  exitMode?: 'function_call' | 'phrase_match';

  /**
   * Map flow state variables into the agent's conversation context.
   * Max: 20 mappings
   *
   * Example: Map the caller's name from flow state into the agent context
   * { flowVariable: "caller_name", contextKey: "customerName" }
   */
  contextVariables?: ContextVariableMapping[];

  /**
   * Extract variables from the conversation into flow state.
   * Max: 10 extractions
   *
   * Supported methods: 'last_response', 'pattern'
   * ('semantic' is defined but NOT implemented - rejected at validation)
   */
  extractVariables?: VariableExtractionConfig[];

  /**
   * Voice configuration override for this node.
   * Accepted by the schema but NOT yet applied in v0 — the agent's own
   * voiceConfig is always used. Reserved for future implementation.
   */
  voiceConfig?: VoiceProviderConfig;

  /**
   * Message spoken by the agent before the conversation loop starts.
   * Max: 1000 chars
   * Example: "Hello! How can I help you today?"
   */
  initialMessage?: string;

  /**
   * Whether to record the full conversation audio.
   * Default: false
   */
  recordConversation?: boolean;
}

// ============================================
// CONTEXT VARIABLE MAPPING
// ============================================

interface ContextVariableMapping {
  /** Variable name in flow state (source) */
  flowVariable: string;
  /** Key name in agent context (target) */
  contextKey: string;
  /** Optional description for the agent's context */
  description?: string;
}

// ============================================
// VARIABLE EXTRACTION (Discriminated Union)
// ============================================

/**
 * Extract values from the conversation into flow state variables.
 *
 * Note: The type includes SemanticExtraction but it is NOT implemented.
 * Validation rejects 'semantic' method at flow validation time.
 * Only 'last_response' and 'pattern' methods are usable.
 */
type VariableExtractionConfig =
  | LastResponseExtraction
  | PatternExtraction
  | SemanticExtraction;

interface LastResponseExtraction {
  /** Target flow variable name */
  variableName: string;
  /** Extracts the agent's last response text */
  method: 'last_response';
}

interface PatternExtraction {
  /** Target flow variable name */
  variableName: string;
  /** Extracts using regex pattern */
  method: 'pattern';
  /** Regex pattern. Uses first capture group, or full match if no groups. */
  pattern: string;
}

interface SemanticExtraction {
  /** Target flow variable name */
  variableName: string;
  /** NOT IMPLEMENTED - rejected at validation */
  method: 'semantic';
  /** Prompt for semantic extraction */
  prompt: string;
}

// ============================================
// VOICE PROVIDER CONFIG (Node-Level Override)
// ============================================

/**
 * Voice config override at the node level.
 *
 * Note: In v0, node-level overrides are accepted by the schema but NOT
 * applied at runtime — the agent's voiceConfig is always used.
 * This is reserved for future implementation.
 *
 * STT and TTS providers are hardcoded in v0:
 *   STT: Deepgram (Nova-3, prerecorded API — used in both batch and streaming modes)
 *   TTS: ElevenLabs (Flash v2.5, pcm_8000 output)
 */
interface VoiceProviderConfig {
  /** Pipeline mode override ('batch' or 'streaming') */
  pipelineMode?: 'batch' | 'streaming';
  /** ElevenLabs voice ID override */
  voiceId?: string;
}

// ============================================
// NODE OUTPUTS (Flow Routing)
// ============================================

/**
 * Output paths for the CONNECT_AGENT node.
 * Determines which node executes next based on how the conversation ended.
 */
interface ConnectAgentNodeOutputs {
  /** Required. Next node when conversation completes normally. */
  onComplete: string;
  /** Next node when an exit phrase is detected */
  onExitPhrase?: string;
  /** Next node when max turns is reached */
  onMaxTurns?: string;
  /** Next node when conversation times out */
  onTimeout?: string;
  /** Next node when the caller hangs up */
  onHangup?: string;
  /** Next node when an error occurs */
  onError?: string;
  /** Fallback node (used for unhandled errors if onError is not set) */
  default?: string;
}