/**
 * Metona IR — 响应标准类型定义
 *
 * @see docs/MetonaAI-Desktop 内部API请求与响应标准.html
 */

import type { MetonaToolCall, MetonaToolResult } from './metona-request';

// ===== 响应元信息 =====

export interface MetonaResponseMeta {
  /** 对应的请求 ID */
  requestId: string;
  /** Provider 标识（如 'deepseek'） */
  provider: string;
  /** 实际使用的模型名称 */
  model: string;
  /** 端到端延迟 */
  latencyMs: number;
  /** 响应时间戳 */
  timestamp: number;

  /** Provider 原生性能统计（可选，主要用于 Ollama） */
  perfStats?: {
    /** 模型加载耗时 */
    loadDurationMs?: number;
    /** Prompt 评估耗时 */
    promptEvalDurationMs?: number;
    /** 生成耗时 */
    evalDurationMs?: number;
    /** 生成速率 */
    tokensPerSecond?: number;
  };
}

// ===== Token 使用统计 =====

export interface MetonaTokenUsage {
  inputTokens: number;
  outputTokens: number;
  totalTokens: number;
  /** Thinking 模式专用 */
  reasoningTokens?: number;
  cacheHitTokens?: number;
  cacheMissTokens?: number;
}

// ===== 停止原因 =====

export enum MetonaFinishReason {
  STOP = 'stop',
  LENGTH = 'length',
  TOOL_CALLS = 'tool_calls',
  CONTENT_FILTER = 'content_filter',
  ERROR = 'error',
}

// ===== 完整响应 =====

export interface MetonaResponse {
  /** 响应元信息 */
  meta: MetonaResponseMeta;
  /** 模型输出（完整文本） */
  content: string;
  /** 思考/推理内容（Thinking 模式） */
  reasoningContent?: string;
  /** 结构化输出（如果模型原生支持 JSON Schema） */
  structuredOutput?: unknown;
  /** 工具调用请求列表 */
  toolCalls?: MetonaToolCall[];
  /** Token 使用统计 */
  usage: MetonaTokenUsage;
  /** 停止原因 */
  finishReason: MetonaFinishReason;
  /** 错误信息（如果出错） */
  error?: MetonaError;
}

// ===== 流式事件 =====

export enum MetonaStreamEventType {
  // H-1 修复: 补齐 THINKING_START / THINKING_END — 用于显式标记思考阶段的边界
  // 规范来源: docs/MetonaAI-Desktop 内部API请求与响应标准.html
  // 时序: THINKING_START → REASONING_DELTA* → THINKING_END → TEXT_DELTA*
  THINKING_START = 'thinking_start',
  THINKING_END = 'thinking_end',
  TEXT_DELTA = 'text_delta',
  REASONING_DELTA = 'reasoning_delta',
  TOOL_CALL_DELTA = 'tool_call_delta',
  TOOL_CALL_COMPLETE = 'tool_call_complete',
  TOOL_RESULT = 'tool_result',
  ERROR = 'error',
  DONE = 'done',
  USAGE = 'usage',
}

export interface MetonaStreamEvent {
  type: MetonaStreamEventType;
  requestId: string;
  sessionId: string;
  iteration: number;
  /** 序列号 */
  seq: number;
  timestamp: number;
  /** 当前 run 的唯一标识（前端用于过滤旧流事件，abort 后重发场景） */
  runId?: string;

  /** 根据 type 使用不同字段 */
  /** TEXT_DELTA / REASONING_DELTA */
  delta?: string;

  /** TOOL_CALL_DELTA */
  toolCallDelta?: {
    /** 工具调用索引（同一轮可能有多个） */
    index: number;
    /** 工具名称片段（首个事件携带） */
    name?: string;
    /** 参数 JSON 增量片段 */
    argsDelta?: string;
  };

  /** TOOL_CALL_COMPLETE（拼接完成后的完整调用） */
  toolCall?: MetonaToolCall;

  /** TOOL_RESULT */
  toolResult?: MetonaToolResult;

  /** USAGE */
  usage?: MetonaTokenUsage;

  /** ERROR */
  error?: MetonaError;

  /** DONE — 终止原因（前端可据此区分正常完成/错误/中断） */
  terminationReason?: string;
}

// ===== 思考内容 =====

export interface MetonaThinking {
  /** 思考内容文本 */
  content: string;
  /** 思考状态 */
  status: 'thinking' | 'complete';
  /** 思考耗时 (ms) */
  durationMs: number;
  /** 思考消耗的 token 数 */
  tokensUsed: number;
}

// ===== 错误格式 =====

export interface MetonaError {
  /** 错误码 */
  code: MetonaErrorCode;
  /** 人类可读的错误描述 */
  message: string;
  /** 出错的 Provider */
  provider?: string;
  /** Provider 原始错误码 */
  providerCode?: string;
  /** 是否可重试 */
  retryable: boolean;
  /** 建议重试等待时间 */
  retryAfterMs?: number;
}

export enum MetonaErrorCode {
  // 网络层
  NETWORK_TIMEOUT = 'network_timeout',
  NETWORK_ERROR = 'network_error',

  // 认证层
  AUTH_INVALID = 'auth_invalid',
  AUTH_EXPIRED = 'auth_expired',

  // 频率限制
  RATE_LIMITED = 'rate_limited',
  QUOTA_EXCEEDED = 'quota_exceeded',

  // 模型层
  MODEL_OVERLOADED = 'model_overloaded',
  MODEL_NOT_FOUND = 'model_not_found',
  CONTEXT_LENGTH_EXCEEDED = 'context_length_exceeded',
  OUTPUT_LENGTH_EXCEEDED = 'output_length_exceeded',

  // 内容层
  CONTENT_FILTERED = 'content_filtered',

  // 解析层
  PARSE_ERROR = 'parse_error',
  INVALID_RESPONSE = 'invalid_response',

  // Agent 层
  MAX_ITERATIONS = 'max_iterations',
  USER_ABORTED = 'user_aborted',
  TIMEOUT = 'timeout',
  UNKNOWN = 'unknown',

  // H-11 修复: Engine 内部使用的伪错误码，用于重试时通知前端清空已累积的 delta 缓冲区
  // 注意：这不是真正的错误，仅作为 ERROR 事件的特殊标记，engine 会过滤此事件不转发到 UI
  // 之前使用 'RETRY' as never 绕过类型检查，现在改为正式枚举值以确保类型安全
  RETRY = 'retry',
}
