End Call Tool

// ============================================
// EXIT MODES
// ============================================

/**
 * How the agent determines when to end the conversation.
 * Set in ConnectAgentNodeConfig.exitMode
 */
type ExitMode = 'function_call' | 'phrase_match';

// ============================================
// EXIT REASONS
// ============================================

/**
 * Why the conversation ended.
 * Determines which output path the flow follows after the CONNECT_AGENT node.
 */
type ConnectAgentExitReason =
  | 'completed'           // Normal completion via [COMPLETE] phrase (phrase_match mode)
  | 'function_call_exit'  // Agent called end_conversation tool (function_call mode)
  | 'exit_phrase'         // User said an exit phrase
  | 'max_turns'           // Max turns reached
  | 'timeout'             // Conversation timeout exceeded
  | 'user_hangup'         // Caller hung up
  | 'error';              // An error occurred

// ============================================
// END_CONVERSATION TOOL
// ============================================

/**
 * The end_conversation tool is automatically injected into agents
 * when exitMode is 'function_call'.
 *
 * The LLM calls this tool when it determines the conversation
 * should end. The tool's farewell_message is spoken to the caller
 * via TTS before the call exits.
 */
interface EndConversationToolInput {
  /**
   * Why the conversation is ending.
   * Used for analytics and reporting.
   */
  reason: 'user_goodbye' | 'issue_resolved' | 'user_request';

  /**
   * Natural farewell message to speak to the caller before ending.
   * This is synthesized via TTS and played to the caller.
   *
   * Example: "Thank you for calling! Have a great day!"
   */
  farewell_message: string;

  /**
   * Brief one-sentence summary of what was discussed.
   * Stored in the conversation record as `summary`.
   *
   * Example: "Customer inquired about return policy for order #12345."
   */
  summary: string;

  /**
   * Resolution criteria evaluations (only present when agent has criteria configured).
   * The LLM must evaluate EVERY criterion. Array length must match criteria count.
   * See resolution-criteria.md for full documentation.
   */
  resolution?: Array<{
    /** Criterion UUID from the injected criteria list */
    criterion_id: string;
    /** Whether this criterion was met during the conversation */
    met: boolean;
    /** Brief evidence from the conversation supporting the judgment (min 1 char) */
    evidence: string;
  }>;
}

/** Tool output (internal, not user-facing) */
interface EndConversationToolOutput {
  ended: boolean; // Always true
}

// ============================================
// EXIT CONTEXT
// ============================================

/**
 * Additional context about why the conversation ended.
 * Available in the ConversationResult and analytics.
 */
interface ExitContext {
  /** The exit phrase that was matched (for exit_phrase reason) */
  phrase?: string;
  /** The turn index where exit was triggered */
  turnIndex?: number;
  /** Error type (for error reason) */
  errorType?: string;
  /** Error message (for error reason) */
  errorMessage?: string;
  /** The reason provided by the LLM tool call (for completed via function_call) */
  toolExitReason?: string;
  /** The summary provided by the LLM tool call (for completed via function_call) */
  toolExitSummary?: string;
  /**
   * Per-criterion resolution results (only present when agent has criteria).
   * Maps criterion_id → criterionId (camelCase in output).
   */
  resolutionResults?: Array<{
    criterionId: string;
    met: boolean;
    evidence: string;
  }>;
  /** Denormalized resolution: true = all met, false = any not met, undefined = no criteria */
  resolved?: boolean;
}

// ============================================
// TURN RESULT (Tool Call Signal)
// ============================================

/**
 * When the LLM calls a tool instead of returning text,
 * the turn result includes a toolCallSignal.
 */
interface TurnResult {
  // ... other fields (see voice-agents.md) ...

  /**
   * Present when the LLM called a tool instead of generating text.
   * For end_conversation, toolName is 'end_conversation' and
   * args contains { reason, farewell_message, summary }.
   */
  toolCallSignal?: {
    toolName: string;
    args: Record<string, unknown>;
  };
}