/**
 * Metona IR — Provider Adapter 接口定义
 *
 * 所有 LLM Provider 适配器必须实现此接口。
 *
 * H-2 修复: 接口对齐规范
 * @see docs/MetonaAI-Desktop 内部API请求与响应标准.html
 * - provider → providerId（规范要求）
 * - chat → send（规范要求）
 * - chatStream → sendStream（规范要求）
 * - 新增 getContextWindow()（规范要求）
 * - listModels 返回 MetonaModelInfo[]（规范要求）
 */

import type { MetonaRequest, MetonaResponse, MetonaStreamEvent } from './index';

/**
 * H-2 修复: 新增 MetonaModelInfo 类型 — 规范要求的模型元信息
 */
export interface MetonaModelInfo {
  /** 模型 ID（如 'deepseek-v4-pro'） */
  id: string;
  /** 模型显示名称（如 'DeepSeek V4 Pro'） */
  name?: string;
  /** 上下文窗口大小（token 数） */
  contextWindow?: number;
  /** 最大输出 token 数 */
  maxOutputTokens?: number;
  /** 是否支持 Tool Calling */
  supportsToolCalling?: boolean;
  /** 是否支持 Thinking / Reasoning */
  supportsThinking?: boolean;
  /** 模型描述 */
  description?: string;
}

/**
 * Provider 适配器配置
 */
export interface AdapterConfig {
  /** Provider 标识（如 'deepseek'、'agnes'、'mimo'、'ollama'） */
  provider: string;
  /** API 基础 URL */
  baseURL: string;
  /** API 密钥（Ollama 等本地 Provider 可为空） */
  apiKey?: string;
  /** 默认模型名 */
  defaultModel: string;
  /** 请求超时（ms） */
  timeoutMs?: number;
  /** 自定义请求头 */
  headers?: Record<string, string>;
  /**
   * 上下文窗口大小（用于 Engine 压缩判断和 UI 显示）
   *
   * v0.3.1 新增：DeepSeek/Agnes 不再写死 1M，可通过配置注入。
   * - Ollama: 不使用此字段（使用 contextLength/num_ctx 传给 API）
   * - DeepSeek/Agnes: OpenAI 兼容 API 不支持 context_window 参数，
   *   此值仅用于 Engine 压缩判断和前端显示，不传给 API
   */
  contextWindow?: number;
}

/**
 * Provider 适配器统一接口
 *
 * 职责：
 * 1. 将 MetonaRequest 转换为目标 Provider 原生请求格式
 * 2. 调用外部 API
 * 3. 将原生响应转换为 MetonaResponse / MetonaStreamEvent
 *
 * 铁律：外部 API 原始类型不得穿透到此接口之外
 */
export interface IMetonaProviderAdapter {
  /** H-2 修复: Provider 标识（规范要求使用 providerId） */
  readonly providerId: string;

  /** 支持的模型列表（保留作为便捷访问） */
  readonly supportedModels: string[];

  /** 是否支持 Tool Calling */
  readonly supportsToolCalling: boolean;

  /** 是否支持 Thinking / Reasoning 模式 */
  readonly supportsThinking: boolean;

  /**
   * H-2 修复: 获取上下文窗口大小（token 数）
   * 规范要求的方法，用于 Engine 估算上下文使用率
   * @returns 上下文窗口大小（token 数）
   */
  getContextWindow(): number;

  /**
   * H-2 修复: 发送非流式请求（规范要求使用 send）
   */
  send(request: MetonaRequest): Promise<MetonaResponse>;

  /**
   * H-2 修复: 发送流式请求（规范要求使用 sendStream）
   * @returns AsyncIterable 逐事件推送 MetonaStreamEvent
   */
  sendStream(request: MetonaRequest): AsyncIterable<MetonaStreamEvent>;

  /**
   * C-2 修复: 注入外部 AbortSignal，用于关联 Engine 的 abortController
   *
   * Engine 在调用 send/sendStream 前注入 signal，使用户 abort 能中断正在进行的 fetch，
   * 避免资源泄漏。Adapter 应将此 signal 与自身的 timeout signal 合并。
   *
   * @see project_memory.md — engine must use AbortController to avoid resource leaks on abort()
   */
  setAbortSignal?(signal: AbortSignal | undefined): void;

  /**
   * 检查 Provider 可用性
   */
  healthCheck(): Promise<boolean>;

  /**
   * H-2 修复: 列出可用模型（规范要求返回 MetonaModelInfo[]）
   */
  listModels?(): Promise<MetonaModelInfo[]>;
}
