export type KnownApi =  
    | "openai-completions"  
    | "openai-responses"  
    | "azure-openai-responses"  
    | "openai-codex-responses"  
    | "anthropic-messages"  
    | "bedrock-converse-stream"  
    | "google-generative-ai"  
    | "google-gemini-cli"  
    | "google-vertex";  
  
export type Api = KnownApi | (string & {});

export type KnownProvider =  
    | "amazon-bedrock"  
    | "anthropic"  
    | "google"  
    | "google-gemini-cli"  
    | "google-antigravity"  
    | "google-vertex"  
    | "openai"  
    | "azure-openai-responses"  
    | "openai-codex"  
    | "github-copilot"  
    | "xai"  
    | "groq"  
    | "cerebras"  
    | "openrouter"  
    | "vercel-ai-gateway"  
    | "zai"  
    | "mistral"  
    | "minimax"  
    | "minimax-cn"  
    | "huggingface"  
    | "opencode"  
    | "kimi-coding";  
export type Provider = KnownProvider | (string & {});

export type AssistantMessageEvent =  
    | { type: "start"; partial: AssistantMessage }  
    | { type: "text_start"; contentIndex: number; partial: AssistantMessage }  
    | { type: "text_delta"; contentIndex: number; delta: string; partial: AssistantMessage }  
    | { type: "text_end"; contentIndex: number; content: string; partial: AssistantMessage }  
    | { type: "thinking_start"; contentIndex: number; partial: AssistantMessage }  
    | { type: "thinking_delta"; contentIndex: number; delta: string; partial: AssistantMessage }  
    | { type: "thinking_end"; contentIndex: number; content: string; partial: AssistantMessage }  
    | { type: "toolcall_start"; contentIndex: number; partial: AssistantMessage }  
    | { type: "toolcall_delta"; contentIndex: number; delta: string; partial: AssistantMessage }  
    | { type: "toolcall_end"; contentIndex: number; toolCall: ToolCall; partial: AssistantMessage }  
    | { type: "done"; reason: Extract<StopReason, "stop" | "length" | "toolUse">; message: AssistantMessage }  
    | { type: "error"; reason: Extract<StopReason, "aborted" | "error">; error: AssistantMessage };

export interface UserMessage {  
    role: "user";  
    content: string | (TextContent | ImageContent)[];  
    timestamp: number; // Unix timestamp in milliseconds  
}

export interface AssistantMessage {  
    role: "assistant";  
    content: (TextContent | ThinkingContent | ToolCall)[];  
    api: Api;  
    provider: Provider;  
    model: string;  
    usage: Usage;  
    stopReason: StopReason;  
    errorMessage?: string;  
    timestamp: number; // Unix timestamp in milliseconds  
}

export interface ToolResultMessage<TDetails = any> {  
    role: "toolResult";  
    toolCallId: string;  
    toolName: string;  
    content: (TextContent | ImageContent)[]; // Supports text and images  
    details?: TDetails;  
    isError: boolean;  
    timestamp: number; // Unix timestamp in milliseconds  
}

/**
 * Extensible interface for custom app messages.
 * Apps can extend via declaration merging:
 *
 * @example
 * ```typescript
 * declare module "@mariozechner/agent" {
 *   interface CustomAgentMessages {
 *     artifact: ArtifactMessage;
 *     notification: NotificationMessage;
 *   }
 * }
 * ```
*/
export interface CustomAgentMessages {
// Empty by default - apps extend via declaration merging
}

/**
* AgentMessage: Union of LLM messages + custom messages.
* This abstraction allows apps to add custom message types while maintaining
* type safety and compatibility with the base LLM messages.
  */
  export type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];

/**
 * Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.
 *
 * Each AgentMessage must be converted to a UserMessage, AssistantMessage, or ToolResultMessage
 * that the LLM can understand. AgentMessages that cannot be converted (e.g., UI-only notifications,
 * status messages) should be filtered out.
 *
 * @example
 * ```typescript
 * convertToLlm: (messages) => messages.flatMap(m => {
 *   if (m.role === "custom") {
 *     // Convert custom message to user message
 *     return [{ role: "user", content: m.content, timestamp: m.timestamp }];
 *   }
 *   if (m.role === "notification") {
 *     // Filter out UI-only messages
 *     return [];
 *   }
 *   // Pass through standard LLM messages
 *   return [m];
 * })
 * ```
 */
convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;

export interface AgentToolResult<T> {  
    // Content blocks supporting text and images  
    content: (TextContent | ImageContent)[];  
    // Details to be displayed in a UI or logged  
    details: T;  
}  
  
// Callback for streaming tool execution updates  
export type AgentToolUpdateCallback<T = any> = (partialResult: AgentToolResult<T>) => void;  
  
// AgentTool extends Tool but adds the execute function  
export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any> extends Tool<TParameters> {  
    // A human-readable label for the tool to be displayed in UI  
    label: string;  
    execute: (  
       toolCallId: string,  
       params: Static<TParameters>,  
       signal?: AbortSignal,  
       onUpdate?: AgentToolUpdateCallback<TDetails>,  
    ) => Promise<AgentToolResult<TDetails>>;  
}

/**
 * Events emitted by the Agent for UI updates.
 * These events provide fine-grained lifecycle information for messages, turns, and tool executions.
 */
export type AgentEvent =
	// Agent lifecycle
	| { type: "agent_start" }
	| { type: "agent_end"; messages: AgentMessage[] }
	// Turn lifecycle - a turn is one assistant response + any tool calls/results
	| { type: "turn_start" }
	| { type: "turn_end"; message: AgentMessage; toolResults: ToolResultMessage[] }
	// Message lifecycle - emitted for user, assistant, and toolResult messages
	| { type: "message_start"; message: AgentMessage }
	// Only emitted for assistant messages during streaming
	| { type: "message_update"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }
	| { type: "message_end"; message: AgentMessage }
	// Tool execution lifecycle
	| { type: "tool_execution_start"; toolCallId: string; toolName: string; args: any }
	| { type: "tool_execution_update"; toolCallId: string; toolName: string; args: any; partialResult: any }
	| { type: "tool_execution_end"; toolCallId: string; toolName: string; result: any; isError: boolean };

/**
 * Returns steering messages to inject into the conversation mid-run.
 *
 * Called after each tool execution to check for user interruptions.
 * If messages are returned, remaining tool calls are skipped and
 * these messages are added to the context before the next LLM call.
 *
 * Use this for "steering" the agent while it's working.
 */
getSteeringMessages?: () => Promise<AgentMessage[]>;

/**
 * Returns follow-up messages to process after the agent would otherwise stop.
 *
 * Called when the agent has no more tool calls and no steering messages.
 * If messages are returned, they're added to the context and the agent
 * continues with another turn.
 *
 * Use this for follow-up messages that should wait until the agent finishes.
 */
getFollowUpMessages?: () => Promise<AgentMessage[]>;

外层 while(true) {                    ← 处理 follow-up 消息
  内层 while(hasMoreToolCalls || pendingMessages) {  ← 处理工具调用 + steering
    1. 注入 pending messages（发射 message_start/end 事件）
    2. streamAssistantResponse()  → 拿到 AssistantMessage
    3. 如果 error/aborted → agent_end，返回
    4. 如果有 tool calls → executeToolCalls()
       - 每个工具执行后检查 steering 队列
       - 如果有 steering → 跳过剩余工具（标记为 "Skipped"）
    5. 发射 turn_end
    6. 再次检查 steering 队列
  }
  检查 follow-up 队列 → 如果有 → 设为 pending → continue 外层
  没有了 → break
}