/**
 * LLM Provider abstraction for the local proxy.
 *
 * When the proxy intercepts tool calls, it can optionally route them
 * through an LLM provider for autonomous tool use, summarization,
 * or other processing before forwarding to the upstream MCP server.
 */

export interface ChatMessage {
  role: 'system' | 'user' | 'assistant' | 'tool';
  content: string;
  toolCallId?: string;
  name?: string;
}

export interface ToolDefinition {
  name: string;
  description: string;
  inputSchema: Record<string, unknown>;
}

export interface ToolCall {
  id: string;
  name: string;
  arguments: Record<string, unknown>;
}

export interface CompletionResult {
  content: string;
  toolCalls: ToolCall[];
  usage: {
    promptTokens: number;
    completionTokens: number;
    totalTokens: number;
  };
  finishReason: 'stop' | 'tool_calls' | 'length' | 'error';
}

export interface CompletionOptions {
  messages: ChatMessage[];
  tools?: ToolDefinition[];
  temperature?: number;
  maxTokens?: number;
  model?: string;
  /** Cancel the in-flight request (fetch-based providers forward it to fetch). */
  signal?: AbortSignal;
}

/** LLM provider tier. 'fast' = local inference, 'heavy' = cloud reasoning. */
export type Tier = 'fast' | 'heavy';

export interface LlmProvider {
  /** Provider identifier (e.g., 'openai', 'anthropic', 'ollama') */
  readonly name: string;
  /** Create a chat completion */
  complete(options: CompletionOptions): Promise<CompletionResult>;
  /** List available models */
  listModels(): Promise<string[]>;
  /** Check if the provider is configured and reachable */
  isAvailable(): Promise<boolean>;
  /** Optional cleanup for providers with persistent resources (e.g., subprocesses). */
  dispose?(): void;
  /** Optional eager startup for providers that manage subprocesses (e.g., vLLM). */
  warmup?(): void;
}
