Agents

// ============================================
// ENUMS
// ============================================

/** Agent lifecycle status */
type AgentStatus = 'draft' | 'active' | 'archived';

/** Voice pipeline mode for call flow usage */
type PipelineMode = 'batch' | 'streaming' | 'sts';

/** Speech-to-speech provider (future, not yet implemented) */
type StsProvider = 'openai' | 'gemini';

type SortOrder = 'asc' | 'desc';

// ============================================
// MODEL CONFIGURATION
// ============================================

/**
 * LLM model configuration for agents.
 *
 * Model format: "provider/model-name"
 * Supported providers: openai, anthropic
 *
 * @example "openai/gpt-4o-mini"
 * @example "anthropic/claude-sonnet-4-20250514"
 */
interface AgentModelConfig {
  /** Model identifier in "provider/model-name" format */
  model: string;

  /** Model generation settings */
  modelSettings?: {
    /** Temperature (0-2). Default: 0.7 */
    temperature?: number;
    /** Maximum tokens to generate */
    maxTokens?: number;
    /** Top P nucleus sampling (0-1) */
    topP?: number;
    /** Top K sampling */
    topK?: number;
    /** Stop sequences */
    stopSequences?: string[];
  };

  /** Provider-specific options */
  providerOptions?: {
    openai?: {
      reasoningEffort?: 'low' | 'medium' | 'high';
      responseFormat?: 'text' | 'json_object';
      frequencyPenalty?: number;
      presencePenalty?: number;
    };
    anthropic?: {
      cacheControl?: { type: 'ephemeral' };
      maxTokens?: number;
    };
  };
}

// ============================================
// VOICE CONFIGURATION
// ============================================

/**
 * Voice configuration for agents used in call flows.
 * Applied when the agent is connected via a CONNECT_AGENT node.
 *
 * Discriminated union on `pipelineMode`:
 * - 'batch': STT -> LLM -> TTS sequential pipeline
 * - 'streaming': Streaming LLM + sentence-chunked TTS for lower latency
 * - 'sts' (future): Speech-to-speech via OpenAI Realtime or Gemini Live
 */
type AgentVoiceConfig =
  | BatchStreamingVoiceConfig
  | StsVoiceConfig;

interface BatchStreamingVoiceConfig {
  /** Pipeline mode: 'batch' or 'streaming' */
  pipelineMode: 'batch' | 'streaming';
  /** ElevenLabs voice ID. Uses platform default if omitted */
  voiceId?: string;
}

interface StsVoiceConfig {
  /** Pipeline mode: speech-to-speech (future - not yet implemented) */
  pipelineMode: 'sts';
  /** STS provider */
  stsProvider: StsProvider;
}

// ============================================
// MEMORY CONFIGURATION
// ============================================

/**
 * Memory configuration for conversation context.
 * Uses Mastra Memory with PostgresStore backend.
 */
interface AgentMemoryConfig {
  /** Enable conversation memory. Default: true */
  enabled: boolean;
  /** Number of recent messages to include (1-100). Default: 20 */
  lastMessages?: number;
  /** Enable semantic recall (future feature). Default: false */
  semanticRecall?: boolean;
}

// ============================================
// KNOWLEDGE BASE CONFIGURATION
// ============================================

/**
 * Links an agent to a knowledge base for RAG-powered responses.
 * When set, the agent retrieves relevant document chunks before
 * each response (both in playground and voice calls).
 *
 * See knowledge-base.md for full KB API documentation.
 */
interface AgentKnowledgeBaseConfig {
  /** UUID of the knowledge base to query */
  knowledgeBaseId: string;
  /** Document groups to include. null/undefined = all groups */
  documentGroups?: string[];
  /** Number of chunks to retrieve per query (1-20). Default: 5 */
  topK?: number;
  /** Minimum similarity score (0-1). Default: 0.7 */
  similarityThreshold?: number;
}

// ============================================
// AGENT METADATA (OPTIONAL FIELDS)
// ============================================

/**
 * The `metadata` field is a freeform JSON object. The following keys
 * are recognized by the master prompt system when the agent is used
 * in voice call flows:
 *
 * - scope (string): Agent's operational scope.
 *     Default: "general customer assistance"
 *     Example: "technical support for billing issues"
 *
 * - toneStyle (string): Tone and communication style.
 *     Default: "professional, warm, and helpful"
 *     Example: "casual, friendly, and upbeat"
 *
 * All other keys are stored as-is and available in the API response.
 */
type AgentMetadata = Record<string, unknown>;

// ============================================
// REQUEST TYPES
// ============================================

interface CreateAgentRequest {
  /** Agent display name (1-128 chars) */
  name: string;
  /** Agent description (max 2000 chars) */
  description?: string;
  /** Agent instructions / system prompt (1-10000 chars) */
  instructions: string;
  /** Agent policy — business rules auto-injected into the prompt, hidden from callers (max 10000 chars) */
  policy?: string;
  /** LLM model configuration. Defaults to openai/gpt-4o-mini */
  modelConfig?: AgentModelConfig;
  /** Voice pipeline configuration for call flows */
  voiceConfig?: AgentVoiceConfig;
  /** Conversation memory settings */
  memoryConfig?: AgentMemoryConfig;
  /** Knowledge base RAG configuration */
  knowledgeBaseConfig?: AgentKnowledgeBaseConfig;
  /** Freeform metadata (see AgentMetadata) */
  metadata?: AgentMetadata;
  /**
   * Resolution criteria for evaluating conversation outcomes (max 5).
   * See resolution-criteria.md for full documentation.
   */
  resolutionCriteria?: Array<{ label: string; description: string }>;
}

interface UpdateAgentRequest {
  /**
   * All fields are optional - only provided fields are updated.
   * The `metadata` field uses shallow merge: provided keys are added/updated,
   * existing keys not in the request are preserved.
   *
   * Version is incremented when `instructions`, `policy`, `modelConfig`,
   * `memoryConfig`, or `resolutionCriteria` are changed.
   */
  name?: string;
  description?: string;
  instructions?: string;
  /** Agent policy — business rules auto-injected into the prompt (set to null to clear) */
  policy?: string | null;
  modelConfig?: AgentModelConfig;
  voiceConfig?: AgentVoiceConfig;
  memoryConfig?: AgentMemoryConfig;
  /** Knowledge base RAG configuration (set to null to detach) */
  knowledgeBaseConfig?: AgentKnowledgeBaseConfig | null;
  metadata?: AgentMetadata;
  /**
   * Resolution criteria (max 5). Declarative replace: replaces all existing
   * criteria when provided. Omit to leave unchanged. Set to [] to clear.
   * See resolution-criteria.md for full documentation.
   */
  resolutionCriteria?: Array<{ label: string; description: string }>;
}

interface TestAgentRequest {
  /** Message to send to the agent (1-10000 chars) */
  message: string;
}

// ============================================
// QUERY PARAMETERS
// ============================================

interface AgentQueryParams {
  /** Page number (default: 1) */
  page?: number;
  /** Items per page (default: 20, max: 100) */
  limit?: number;
  /** Search by name or description (partial match, max 100 chars) */
  search?: string;
  /** Sort field */
  sortBy?: 'name' | 'createdAt' | 'updatedAt' | 'status';
  /** Sort order (default: 'desc') */
  sortOrder?: SortOrder;
  /** Filter by status */
  status?: AgentStatus;
}

// ============================================
// RESPONSE TYPES
// ============================================

interface AgentResponse {
  /** Agent UUID */
  id: string;
  /** Organization UUID */
  organizationId: string;
  /** Agent display name */
  name: string;
  /** Agent description */
  description: string | null;
  /** Agent instructions / system prompt */
  instructions: string;
  /** Agent policy — business rules (null if not set) */
  policy: string | null;
  /** Current lifecycle status */
  status: AgentStatus;
  /** Version number. Incremented when instructions, policy, modelConfig, or memoryConfig change */
  version: number;
  /** LLM model configuration */
  modelConfig: AgentModelConfig;
  /** Voice pipeline configuration (null if not set) */
  voiceConfig: AgentVoiceConfig | null;
  /** Memory configuration. Defaults applied on create (never null for new agents) */
  memoryConfig: AgentMemoryConfig | null;
  /** Knowledge base RAG configuration (null if not linked) */
  knowledgeBaseConfig: AgentKnowledgeBaseConfig | null;
  /** Freeform metadata */
  metadata: Record<string, unknown>;
  /** ISO 8601 timestamp */
  createdAt: string;
  /** ISO 8601 timestamp */
  updatedAt: string;
  /** UUID of the user who created the agent (null if system-created) */
  createdBy: string | null;
}

interface TestAgentResponse {
  /** Agent's text response */
  response: string;
  /** Token usage for this generation */
  usage?: {
    inputTokens?: number;
    outputTokens?: number;
  };
}

interface PaginationMeta {
  page: number;
  limit: number;
  total: number;
  totalPages: number;
  hasNextPage: boolean;
  hasPreviousPage: boolean;
}

interface AgentListResponse {
  data: AgentResponse[];
  meta: PaginationMeta;
}