/**
 * Metona IR — 请求标准类型定义
 *
 * 本文件是项目内所有 AI 交互请求的统一类型定义。
 * 无论底层对接 DeepSeek、Ollama、Agnes 还是其他 LLM，
 * Agent Loop、UI、记忆系统均读写此标准格式。
 *
 * @see docs/MetonaAI-Desktop 内部API请求与响应标准.html
 */

// ===== 请求元信息 =====

export interface MetonaRequestMeta {
  /** 会话 ID */
  sessionId: string;
  /** 当前 ReAct 迭代轮次（从 1 开始） */
  iteration: number;
  /** 本次请求的唯一 ID */
  requestId: string;
  /** Unix 毫秒时间戳 */
  timestamp: number;
  /** Agent 引擎版本 */
  agentVersion: string;
}

// ===== System Prompt =====

export interface MetonaSystemPrompt {
  /** 角色定义（静态区，利用 LLM 缓存） */
  roleDefinition: string;
  /** 输出格式约束 */
  outputConstraints: string;
  /** 安全准则 */
  safetyGuidelines: string;
  /** 动态注入的尾部提醒 */
  dynamicReminders?: string;
}

// ===== 生成参数 =====

export interface MetonaGenerationParams {
  /** 最大生成 token 数 */
  maxTokens?: number;
  /** 温度（默认 0.0，Agent 需要确定性） */
  temperature?: number;
  /** 核采样 */
  topP?: number;
  /** 是否流式输出 */
  stream?: boolean;
  /** 停止序列 */
  stopSequences?: string[];
  /** 是否启用思考模式 */
  thinkingEnabled?: boolean;
  /** 思考强度（替代 thinkingBudget，各 Provider 映射见 Adapter 规范） */
  thinkingEffort?: 'low' | 'medium' | 'high' | 'max';
  /** 上下文窗口大小（仅 Ollama 支持 num_ctx） */
  contextLength?: number;
}

// ===== 安全约束 =====

export interface MetonaConstraints {
  /** 本迭代允许使用的工具白名单 */
  allowedTools?: string[];
  /** 单轮最大工具调用数 */
  maxToolCalls?: number;
  /** 本请求整体超时 */
  timeoutMs?: number;
}

// ===== 消息格式 =====

export interface MetonaMessage {
  role: 'system' | 'user' | 'assistant' | 'tool';

  /**
   * 文本内容（纯文本或 Markdown）
   *
   * C-6 修复: 允许 null — assistant 消息仅有 tool_calls 时 content 必须为 null
   * @see project_memory.md — Assistant messages with tool_calls must set content to null
   */
  content: string | null;

  /** （仅 assistant）思考/推理内容 */
  reasoningContent?: string;

  /** （仅 assistant）工具调用请求 */
  toolCalls?: MetonaToolCall[];

  /** （仅 tool）工具执行结果 */
  toolResult?: MetonaToolResult;

  /** 时间戳 */
  timestamp: number;

  /** 所属迭代轮次 */
  iteration?: number;

  /** 图片内容（可选，用于多模态） */
  images?: MetonaImageContent[];
}

export interface MetonaImageContent {
  /** 图片公网 URL 或 base64 data URI */
  url: string;
  detail?: 'low' | 'high' | 'auto';
}

// ===== 工具定义 =====

export interface MetonaToolDef {
  /** 工具唯一名称 */
  name: string;
  /** 功能描述（供 LLM 阅读） */
  description: string;
  /** 参数 JSON Schema */
  parameters: MetonaToolParams;
  /** 分类 */
  category: MetonaToolCategory;
  /** 风险等级 */
  riskLevel: MetonaRiskLevel;
  /** 是否需要用户授权 */
  requiresPermission: boolean;
  /** 超时时间 */
  timeoutMs: number;
}

export interface MetonaToolParams {
  type: 'object';
  properties: Record<string, MetonaParamField>;
  required?: string[];
}

export interface MetonaParamField {
  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
  description: string;
  enum?: string[];
  items?: MetonaParamField;
}

export enum MetonaToolCategory {
  FILESYSTEM = 'filesystem',
  SEARCH = 'search',
  CALCULATION = 'calculation',
  CODE_EXECUTION = 'code_execution',
  NETWORK = 'network',
  DATABASE = 'database',
  MCP = 'mcp',
  CUSTOM = 'custom',
}

export enum MetonaRiskLevel {
  SAFE = 'safe',
  LOW = 'low',
  MEDIUM = 'medium',
  HIGH = 'high',
  CRITICAL = 'critical',
}

// ===== 工具调用 =====

export interface MetonaToolCall {
  /** 工具调用唯一 ID */
  id: string;
  /** 工具名称 */
  name: string;
  /** 调用参数 */
  args: Record<string, unknown>;
  /** 所属 ReAct 迭代 */
  iteration: number;
  timestamp: number;
}

export interface MetonaToolResult {
  toolCallId: string;
  toolName: string;
  /** 工具原始返回值 */
  result: unknown;
  /** 人工可读摘要（用于 LLM 上下文注入） */
  summary?: string;
  success: boolean;
  error?: string;
  durationMs: number;
  timestamp: number;
}

// ===== 完整请求 =====

export interface MetonaRequest {
  /** 请求元信息 */
  meta: MetonaRequestMeta;
  /** System Prompt（行为宪法） */
  systemPrompt: MetonaSystemPrompt;
  /** 消息列表（含历史 + 当前用户输入 + 工具结果） */
  messages: MetonaMessage[];
  /** 本轮可用的工具定义列表 */
  tools?: MetonaToolDef[];
  /** 生成参数 */
  params: MetonaGenerationParams;
  /** 安全约束 */
  constraints?: MetonaConstraints;
}
