await client.messages.create(...)

// ModelAdapter = 模型供应商适配器统一接口。
// QueryEngine 只依赖这个接口，不直接依赖 OpenAI/Anthropic/本地模型 SDK。
export interface ModelAdapter {
  name: string;              // 适配器名字，例如 anthropic、openai-compatible、mock。
  supportsTools: boolean;    // 是否支持 tool calling。
  supportsStreaming: boolean;// 是否支持流式输出。

  // 非流式调用：一次性返回文本或工具调用。
  complete(request: UnifiedModelRequest): Promise<UnifiedModelResponse>;

  // 流式调用：逐个产出 text_delta/tool_call_delta 等事件。
  stream?(
    request: UnifiedModelRequest
  ): AsyncGenerator<UnifiedModelEvent>;
}

// UnifiedModelRequest = Agent 内部统一的模型请求。
// 不同供应商字段名不同，但进入 adapter 前都用这个形状。
export type UnifiedModelRequest = {
  model: string;             // 模型名或逻辑别名。
  messages: Message[];       // 当前上下文。
  tools: ToolSchema[];       // 可用工具 schema。
  temperature?: number;      // 随机性参数。
  maxOutputTokens?: number;  // 最大输出 token。
  abortSignal?: AbortSignal; // 支持用户取消/超时取消。
};

// UnifiedModelResponse = 非流式模型响应。
// 要么是最终文本，要么是一次工具调用请求。
export type UnifiedModelResponse =
  | {
      type: "text";
      text: string;       // 模型回答文本。
      usage?: TokenUsage; // token 用量。
    }
  | {
      type: "tool_call";
      id: string;         // 工具调用 ID。
      name: string;       // 工具名。
      input: unknown;     // 工具参数，仍需 schema 校验。
      usage?: TokenUsage; // token 用量。
    };

// UnifiedModelEvent = 流式模型事件。
// adapter 把供应商原始事件转换成这些统一事件。
export type UnifiedModelEvent =
  | { type: "text_delta"; text: string } // 文本增量。
  | { type: "tool_call_start"; id: string; name: string } // 开始一个工具调用。
  | { type: "tool_call_delta"; id: string; partialInput: string } // 工具参数 JSON 片段。
  | { type: "tool_call_done"; id: string; name: string; input: unknown } // 工具调用拼装完成。
  | { type: "usage"; usage: TokenUsage } // token 用量。
  | { type: "done" }; // 流结束。

// Message = Agent 内部统一 message。
// tool message 是工具结果，不同供应商对它的格式要求差异很大。
export type Message =
  | { role: "system" | "user" | "assistant"; content: string }
  | { role: "tool"; toolCallId: string; content: string };

// toProviderMessages = 把内部 message 转成某个供应商接受的 message。
// 这是适配器职责，不应该散落在 QueryEngine 里。
function toProviderMessages(messages: Message[]) {
  return messages.map(message => {
    // 如果供应商没有原生 tool result 格式，可以退化成 user 文本。
    if (message.role === "tool") {
      return {
        role: "user",
        content: `Tool result (${message.toolCallId}):\n${message.content}`
      };
    }

    // system/user/assistant 可以直接映射。
    return {
      role: message.role,
      content: message.content
    };
  });
}

// ToolSchema = Agent 内部统一工具 schema。
type ToolSchema = {
  name: string;              // 工具名。
  description: string;       // 工具说明。
  input_schema: JsonSchema;  // 参数 schema。
};

// toProviderTools = 把内部 ToolSchema 转成供应商工具格式。
// 教学版假设供应商也叫 input_schema，真实供应商可能叫 parameters。
function toProviderTools(tools: ToolSchema[]) {
  return tools.map(tool => ({
    name: tool.name,
    description: tool.description,
    input_schema: tool.input_schema
  }));
}

{
  "type": "tool_call",
  "name": "read_file",
  "input": {"path":"src/main.ts"}
}

tool_call_start: read_file
tool_call_delta: {"path"
tool_call_delta: :"src/
tool_call_delta: main.ts"}
tool_call_done

// ToolCallAccumulator = 流式工具调用参数拼装器。
// 模型可能把 {"path":"src/main.ts"} 分成很多 delta，需要累积后再 JSON.parse。
class ToolCallAccumulator {
  // key 是 tool call id，value 保存该工具调用的名字和已收到的 input 文本。
  private calls = new Map<string, {
    id: string;
    name: string;
    inputText: string;
  }>();

  // start = 收到 tool_call_start 时初始化一条记录。
  start(id: string, name: string) {
    this.calls.set(id, { id, name, inputText: "" });
  }

  // append = 收到 tool_call_delta 时追加参数片段。
  append(id: string, delta: string) {
    const call = this.calls.get(id);
    if (!call) {
      // delta 到了但没有 start，说明流事件顺序异常或丢包。
      throw new Error(`Unknown tool call stream id: ${id}`);
    }

    // 只拼字符串，不要中途 JSON.parse，因为中间片段不是完整 JSON。
    call.inputText += delta;
  }

  // done = 收到 tool_call_done 后，把累积文本解析成 ToolCall。
  done(id: string): ToolCall {
    const call = this.calls.get(id);
    if (!call) {
      throw new Error(`Unknown tool call stream id: ${id}`);
    }

    // 完成后删除，避免内存泄漏。
    this.calls.delete(id);

    return {
      id: call.id,
      name: call.name,
      // 这里才 parse JSON。真实系统要捕获 parse 错误并转成 MODEL_BAD_RESPONSE。
      input: JSON.parse(call.inputText),
      sessionId: "current" // 教学版写死，真实系统应传当前 sessionId。
    };
  }
}

// queryStreaming = 流式版 Agent 主循环。
// 它消费模型流事件，并在遇到工具调用时暂停模型输出、执行工具、再继续下一轮。
export async function* queryStreaming(userInput: string): AsyncGenerator<AgentEvent> {
  // 构建初始上下文。
  const messages = await buildContext(userInput);

  // 用 accumulator 拼装流式 tool call。
  const accumulator = new ToolCallAccumulator();

  // model.stream 产出统一 UnifiedModelEvent。
  for await (const event of model.stream!({
    model: "default",
    messages,
    tools: getToolSchemas()
  })) {
    // 普通文本增量直接转成 AgentEvent。
    if (event.type === "text_delta") {
      yield { type: "text_delta", text: event.text };
    }

    // 工具调用开始：记录 id/name。
    if (event.type === "tool_call_start") {
      accumulator.start(event.id, event.name);
    }

    // 工具参数片段：追加到 accumulator。
    if (event.type === "tool_call_delta") {
      accumulator.append(event.id, event.partialInput);
    }

    // 工具调用完成：解析完整 input，开始执行工具。
    if (event.type === "tool_call_done") {
      const call = accumulator.done(event.id);

      // 通知 UI 工具开始。
      yield { type: "tool_start", call };

      // 执行工具。内部负责权限、timeout、审计等。
      const result = await executeToolCall(call);

      // 通知 UI 工具完成。
      yield { type: "tool_result", call, result };

      // 把工具结果回填 messages，供下一轮模型调用使用。
      messages.push({
        role: "tool",
        toolCallId: call.id,
        content: result.content
      });

      // 工具结果回填后，需要开启下一轮模型调用。
      // yield* 表示把另一个 generator 的事件继续向外转发。
      yield* continueAfterTool(messages);
      return;
    }
  }
}

// normalizeUsage = 把不同供应商的 usage 字段归一化。
// 有的叫 input_tokens，有的叫 prompt_tokens；输出同理。
function normalizeUsage(raw: unknown): TokenUsage | undefined {
  // 没有 usage 就返回 undefined，不要伪造数据。
  if (!raw) return undefined;

  // 教学版用 any 简化，真实系统要做 schema 校验。
  const usage = raw as any;

  return {
    model: usage.model ?? "unknown", // 供应商没给就填 unknown。
    inputTokens: usage.input_tokens ?? usage.prompt_tokens ?? 0,
    outputTokens: usage.output_tokens ?? usage.completion_tokens ?? 0,
    // 如果供应商没有 total，就自己相加。
    totalTokens:
      usage.total_tokens ??
      (usage.input_tokens ?? usage.prompt_tokens ?? 0) +
      (usage.output_tokens ?? usage.completion_tokens ?? 0)
  };
}

// normalizeModelError = 把供应商错误转成 AgentError。
// QueryEngine 不应该关心每个供应商的原始错误格式。
function normalizeModelError(error: unknown): AgentError {
  // 先拿到可读 message。
  const message = error instanceof Error ? error.message : String(error);

  // 鉴权失败通常不能 fallback，必须修 key 或账号。
  if (message.includes("401") || message.includes("Unauthorized")) {
    return new AgentError("MODEL_AUTH_FAILED", message);
  }

  // 限流可以重试或切备用模型。
  if (message.includes("rate limit") || message.includes("429")) {
    return new AgentError("MODEL_RATE_LIMITED", message);
  }

  // 超时也可能 fallback 或重试。
  if (message.includes("timeout")) {
    return new AgentError("MODEL_TIMEOUT", message);
  }

  // 其他都归到 bad response。
  return new AgentError("MODEL_BAD_RESPONSE", message);
}

// callWithFallback = 模型调用 fallback 策略。
// primary 失败后尝试 backup/small，但不是所有错误都该 fallback。
export async function callWithFallback(request: UnifiedModelRequest) {
  // 候选模型/适配器按优先级排列。
  const candidates = [
    getAdapter("primary"),
    getAdapter("backup"),
    getAdapter("small")
  ];

  let lastError: unknown;

  for (const adapter of candidates) {
    try {
      // 尝试当前 adapter。
      return await adapter.complete(request);
    } catch (error) {
      // 记录最后一个错误，最后全部失败时抛出。
      lastError = error;

      // 错误归一化后再判断是否继续 fallback。
      const normalized = normalizeModelError(error);

      // 鉴权失败通常说明配置错，换模型也大概率没用，直接停止。
      if (normalized.code === "MODEL_AUTH_FAILED") break;
    }
  }

  // 所有候选都失败后，抛最后一个错误的归一化结果。
  throw normalizeModelError(lastError);
}

// ModelStreamEvent = 模型流式输出的内部标准事件。
// QueryEngine 只处理这些事件，不直接依赖 OpenAI/Claude/本地模型的原始 chunk。
type ModelStreamEvent =
  | {
      type: "text_delta";       // 普通文本增量，用于终端实时展示。
      text: string;             // 本次新增文本，不是完整答案。
      index: number;            // 增量序号，用于检测乱序或重复。
    }
  | {
      type: "tool_call_delta";  // 工具调用参数增量，通常要多片拼成完整 JSON。
      callId: string;           // 工具调用 ID，跨多个 delta 保持一致。
      name?: string;            // 工具名可能只在第一片出现。
      argumentsDelta: string;   // 参数 JSON 片段，不能直接执行。
    }
  | {
      type: "stop";             // 模型结束事件。
      reason: "end" | "tool_call" | "length" | "cancelled"; // 结束原因决定下一状态。
    }
  | {
      type: "usage";            // token 用量，可能最后才到。
      inputTokens: number;      // 输入 token。
      outputTokens: number;     // 输出 token。
    };

// MockAdapter = 测试用模型适配器。
// 不真的调模型，而是按顺序返回预设响应。
class MockAdapter implements ModelAdapter {
  name = "mock";
  supportsTools = true;
  supportsStreaming = false;

  // responses 是测试预设的模型输出队列。
  constructor(private responses: UnifiedModelResponse[]) {}

  async complete() {
    // 每调用一次就取出一个响应。
    const next = this.responses.shift();
    if (!next) {
      // 没有预设响应说明测试写错或 Agent 多调用了模型。
      throw new Error("No mock response left.");
    }
    return next;
  }
}

const model = new MockAdapter([
  {
    type: "tool_call",             // 第一段模拟模型要调用工具，而不是直接回答。
    id: "1",                       // 工具调用 ID，用于把后续 tool_result 对回这次调用。
    name: "read_file",             // 要触发的工具名，测试 QueryEngine 的工具路由。
    input: { path: "README.md" }   // 工具参数，测试 schema 校验和文件读取链路。
  },
  {
    type: "text",                  // 第二段模拟模型读完工具结果后的最终回答。
    text: "README says this project is an Agent CLI."
  }
]);