// FFAI ModelProvider 契约（PR3 骨架）
//
// 任何 LLM 后端（Anthropic / OpenAI / Mock / 未来 LiteLLM 兜底）都实现 ModelProvider。
// ProviderRegistry 路由请求到具体实现；PR3.5 ModelRouter 会前置决策 model 选择。
//
// 详见 docs/modules/agent/02-architecture.md §1.6 LLM 抽象层。

/**
 * 跨 provider 归一化的消息块（IR）。
 * 上游 SDKMessage 经 Adapter 翻译成本 IR 喂给 provider，避免每个 provider 自带格式。
 */
export interface ProviderMessage {
  readonly role: "system" | "user" | "assistant" | "tool";
  readonly content: string;
  readonly name?: string;
}

export interface ProviderRequest {
  readonly model: string;
  readonly messages: ProviderMessage[];
  readonly maxTokens?: number;
  readonly temperature?: number;
  readonly stopSequences?: readonly string[];
  /**
   * 路由元数据（PR3.5 ModelRouter 决策结果）；PR3 阶段为空。
   */
  readonly routingDecisionId?: string;
}

export interface ProviderUsage {
  readonly inputTokens: number;
  readonly outputTokens: number;
}

export interface ProviderResponse {
  readonly id: string;
  readonly model: string;
  readonly text: string;
  readonly stopReason: "end_turn" | "max_tokens" | "stop_sequence" | "error";
  readonly usage: ProviderUsage;
  /**
   * provider 自报实际跑的 model（可能跟 request.model 不同——provider 内部 alias 解析）。
   */
  readonly resolvedModel?: string;
}

/**
 * 流式块。PR3 同步实现里以单块结束 + 一次性 text 返回；
 * 真实 streaming 在 PR3 后期补 SSE 流式时启用。
 */
export interface ProviderStreamChunk {
  readonly type: "text_delta" | "stop";
  readonly textDelta?: string;
  readonly stopReason?: ProviderResponse["stopReason"];
  readonly usage?: ProviderUsage;
}

export interface ModelProvider {
  readonly name: string; // 'mock' / 'anthropic' / 'openai'
  /**
   * 返回 provider 支持的 model 别名列表（用于 Registry/Resolver 路由）。
   */
  readonly supportedModels: readonly string[];

  /**
   * 是否可用：provider 自己决定（key 配置 / 法务合规 / 区域可达性等）。
   * unavailable provider 会被 Resolver 跳过到下一个候选。
   */
  isAvailable(): boolean;

  /**
   * 非流式调用。PR3 阶段所有 provider 走这条；PR3 后期补 stream()。
   */
  invoke(request: ProviderRequest): Promise<ProviderResponse>;
}