/**
 * 内部 provider 类型 —— 与 packages/agent-protocol/src/provider.ts 1:1 对齐。
 *
 * 复制而非 import 原因：当前仓库没配 pnpm/turbo workspaces，
 * `@ffai/agent-protocol` 在 backend 的 NestJS + ts-node-dev 解析链里有 import 边界问题。
 * PR15.5 抽 monorepo workspace 时统一切回直接 import。
 */

export interface ProviderMessage {
  readonly role: 'system' | 'user' | 'assistant' | 'tool';
  readonly content: string;
  readonly name?: string;
  /** 当 role='tool' 时，关联的 tool_call_id（OpenAI 协议要求） */
  readonly toolCallId?: string;
  /** 当 role='assistant' 且发起了 tool_calls 时附带，给下一轮 invoke 拼上下文用 */
  readonly toolCalls?: ProviderToolCall[];
}

/**
 * PR4a tool_use 协议（OpenAI / Qwen 兼容格式）。
 */
export interface ProviderToolDescriptor {
  readonly type: 'function';
  readonly function: {
    readonly name: string;
    readonly description: string;
    readonly parameters: {
      type: 'object';
      properties: Record<string, { type: string; description?: string }>;
      required?: string[];
    };
  };
}

export interface ProviderToolCall {
  readonly id: string;
  readonly type: 'function';
  readonly function: {
    readonly name: string;
    /** JSON-string arguments（按 OpenAI 协议是 string，不是对象） */
    readonly arguments: string;
  };
}

export interface ProviderRequest {
  readonly model: string;
  readonly messages: ProviderMessage[];
  readonly maxTokens?: number;
  readonly temperature?: number;
  readonly stopSequences?: readonly string[];
  readonly routingDecisionId?: string;
  /** PR4a：可调用的 tool 列表（OpenAI 格式） */
  readonly tools?: ProviderToolDescriptor[];
}

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

export type ProviderStopReason =
  | 'end_turn'
  | 'max_tokens'
  | 'stop_sequence'
  | 'tool_use'
  | 'error';

export interface ProviderResponse {
  readonly id: string;
  readonly model: string;
  readonly text: string;
  readonly stopReason: ProviderStopReason;
  readonly usage: ProviderUsage;
  readonly resolvedModel?: string;
  /** PR4a：stopReason='tool_use' 时携带 */
  readonly toolCalls?: ProviderToolCall[];
}

/**
 * PR4a SSE 流式块。
 *   text_delta：assistant 增量文本
 *   tool_call_delta：tool_call 增量（id/name 头一次出 + arguments 文本累积）
 *   stop：终态（带 finishReason + 完整 usage + 完整 toolCalls 如有）
 */
export type ProviderStreamChunk =
  | { readonly type: 'text_delta'; readonly text: string }
  | { readonly type: 'tool_call_delta'; readonly index: number; readonly id?: string; readonly name?: string; readonly argumentsDelta?: string }
  | {
      readonly type: 'stop';
      readonly stopReason: ProviderStopReason;
      readonly usage: ProviderUsage;
      readonly toolCalls?: ProviderToolCall[];
      readonly text: string;
      readonly resolvedModel?: string;
    };

export interface ModelProvider {
  readonly name: string;
  readonly supportedModels: readonly string[];
  isAvailable(): boolean;
  invoke(request: ProviderRequest): Promise<ProviderResponse>;
  /** PR4a streaming —— 实现可选；未实现则 ProviderRegistry 走 invoke() 包装单块 */
  invokeStream?(request: ProviderRequest): AsyncGenerator<ProviderStreamChunk, void, void>;
}