// 这是最粗糙的 Agent loop 伪代码。
// 它表达的是“模型 -> 工具 -> 模型”的循环，不是最终工程写法。
while (!done) {
  // 1. 把当前 messages 和工具列表发给模型。
  const response = await callModel(messages, tools);

  // 2. 如果模型直接回答文本，本轮结束。
  if (response.text) return response.text;

  // 3. 如果模型请求工具，执行工具并把结果回填。
  if (response.toolCall) {
    const result = await executeTool(response.toolCall);
    messages.push(result);
  }
}

// TurnContext = 一次用户任务的运行时状态。
// 状态机里的每个 state 都会读写这个 ctx。
export type TurnContext = {
  sessionId: string; // 串联 transcript、trace、audit。
  userInput: string; // 用户原始任务。
  messages: Message[]; // 当前模型上下文。

  turn: number; // 当前模型轮次。
  maxTurns: number; // 最大模型轮次。

  toolCallCount: number; // 当前已执行工具次数。
  maxToolCalls: number; // 最大工具调用次数。

  startedAt: number; // 本轮开始时间。
  timeoutMs: number; // 总超时时间。

  abortSignal?: AbortSignal; // 用户取消或系统取消信号。
};

// EngineState = QueryEngine 状态机的状态集合。
// 每个状态只携带自己需要的数据。
export type EngineState =
  | { name: "build_context" } // 构建初始 messages。
  | { name: "call_model" } // 调模型。
  | { name: "validate_tool"; call: ToolCall } // 校验工具名和参数。
  | { name: "ask_permission"; call: ToolCall } // 权限确认。
  | { name: "execute_tool"; call: ToolCall } // 执行工具。
  | { name: "append_tool_result"; call: ToolCall; result: ToolResult } // 回填工具结果。
  | { name: "recover"; error: AgentError } // 错误恢复。
  | { name: "done"; reason: StopReason }; // 结束。

// StopReason = 本轮停止原因。
// 用于最终提示、trace、eval，而不是只写 done。
export type StopReason =
  | "final_answer"      // 正常回答完成。
  | "max_turns"         // 模型轮次超限。
  | "max_tool_calls"    // 工具调用超限。
  | "timeout"           // 总耗时超时。
  | "user_abort"        // 用户取消。
  | "permission_denied" // 权限拒绝。
  | "tool_error"        // 工具错误。
  | "model_error";      // 模型错误。

// query = 状态机主循环。
// 它只负责初始化 ctx、推进 state、产出事件。
export async function* query(userInput: string): AsyncGenerator<AgentEvent> {
  // 初始化本轮上下文。
  const ctx: TurnContext = {
    sessionId: crypto.randomUUID(),
    userInput,
    messages: [],
    turn: 0,
    maxTurns: 8,
    toolCallCount: 0,
    maxToolCalls: 12,
    startedAt: Date.now(),
    timeoutMs: 120_000
  };

  // 初始状态：构建上下文。
  let state: EngineState = { name: "build_context" };

  // 不断推进状态，直到 done。
  while (state.name !== "done") {
    // 把状态暴露成事件，方便 UI 和 trace。
    yield { type: "state", name: state.name };
    await appendTrace(ctx.sessionId, state);

    // 具体状态逻辑放在 step。
    state = await step(state, ctx, event => {
      // 复杂实现里可以把内部事件推到队列
    });
  }

  // done 状态里包含 reason。
  yield { type: "turn_end", reason: state.reason };
}

// step = 状态转移函数。
// 给定当前 state 和 ctx，返回下一个 state。
async function step(
  state: EngineState,
  ctx: TurnContext,
  emit: (event: AgentEvent) => void
): Promise<EngineState> {
  // 用户取消优先。
  if (ctx.abortSignal?.aborted) {
    return { name: "done", reason: "user_abort" };
  }

  // 总耗时超限。
  if (Date.now() - ctx.startedAt > ctx.timeoutMs) {
    return { name: "done", reason: "timeout" };
  }

  switch (state.name) {
    case "build_context":
      // 构建模型可见上下文。
      ctx.messages = await buildContext(ctx);
      return { name: "call_model" };

    case "call_model":
      // 调模型并判断返回文本还是工具调用。
      return callModelState(ctx, emit);

    case "validate_tool":
      // 工具存在性和参数校验。
      return validateToolState(state.call);

    case "ask_permission":
      // 权限判断。
      return askPermissionState(state.call);

    case "execute_tool":
      // 执行工具。
      return executeToolState(state.call, ctx, emit);

    case "append_tool_result":
      // 工具结果回填 messages，模型下一轮才能看到。
      ctx.messages.push({
        role: "tool",
        toolCallId: state.call.id,
        content: state.result.content
      });
      // 完成一次工具观察后，模型轮次 +1。
      ctx.turn++;
      return { name: "call_model" };

    case "recover":
      // 错误恢复。
      return recoverState(state.error, ctx);
  }
}

// callModelState = 调模型状态。
async function callModelState(
  ctx: TurnContext,
  emit: (event: AgentEvent) => void
): Promise<EngineState> {
  // 模型轮次超限就停止。
  if (ctx.turn >= ctx.maxTurns) {
    return { name: "done", reason: "max_turns" };
  }

  // 发起模型请求。
  const response = await callModel({
    messages: ctx.messages,
    tools: getToolSchemas(),
    abortSignal: ctx.abortSignal
  });

  // 记录 token usage。
  if (response.usage) {
    await recordUsage(ctx.sessionId, response.usage);
  }

  // 文本响应：输出并结束。
  if (response.type === "text") {
    emit({ type: "text_delta", text: response.text });
    await appendTranscript(ctx.sessionId, {
      role: "assistant",
      content: response.text
    });
    return { name: "done", reason: "final_answer" };
  }

  // 工具调用响应：进入 validate_tool，而不是直接执行。
  return {
    name: "validate_tool",
    call: {
      id: response.id,
      name: response.name,
      input: response.input,
      sessionId: ctx.sessionId
    }
  };
}

// validateToolState = 校验工具调用。
async function validateToolState(call: ToolCall): Promise<EngineState> {
  // 工具必须存在于注册表。
  const tool = findTool(call.name);

  if (!tool) {
    return {
      name: "recover",
      error: new AgentError("TOOL_NOT_FOUND", `Unknown tool: ${call.name}`, call)
    };
  }

  // 模型给的 input 必须符合工具 schema。
  const valid = validateJson(call.input, tool.inputSchema);

  if (!valid.ok) {
    return {
      name: "recover",
      error: new AgentError("TOOL_INPUT_INVALID", valid.message, {
        call,
        schema: tool.inputSchema
      })
    };
  }

  // 校验通过，进入权限判断。
  return { name: "ask_permission", call };
}

Tool "read" not found. Available tools: read_file, grep, glob.

// askPermissionState = 权限阶段。
async function askPermissionState(call: ToolCall): Promise<EngineState> {
  // 重新查工具，避免注册表异常或状态不一致。
  const tool = findTool(call.name);
  if (!tool) {
    return {
      name: "recover",
      error: new AgentError("TOOL_NOT_FOUND", `Unknown tool: ${call.name}`)
    };
  }

  // checkPermission 返回 allow/deny/ask。
  const decision = await checkPermission(tool, call.input);

  if (decision.type === "allow") {
    return { name: "execute_tool", call };
  }

  if (decision.type === "deny") {
    return { name: "done", reason: "permission_denied" };
  }

  // ask 表示需要用户明确批准。
  const approved = await askUser(decision.prompt);

  if (!approved) {
    return { name: "done", reason: "permission_denied" };
  }

  // 用户批准后执行工具。
  return { name: "execute_tool", call };
}

// executeToolState = 工具执行阶段。
async function executeToolState(
  call: ToolCall,
  ctx: TurnContext,
  emit: (event: AgentEvent) => void
): Promise<EngineState> {
  // 工具调用次数也要限制。
  if (ctx.toolCallCount >= ctx.maxToolCalls) {
    return { name: "done", reason: "max_tool_calls" };
  }

  // 计数 + 发开始事件。
  ctx.toolCallCount++;
  emit({ type: "tool_start", call });

  try {
    // 真正执行工具。
    const result = await executeToolCall(call);

    // 发工具结果事件。
    emit({ type: "tool_result", call, result });

    // 成功审计。
    await appendToolAudit({
      sessionId: ctx.sessionId,
      call,
      result,
      ok: true
    });

    // 成功后进入回填状态。
    return {
      name: "append_tool_result",
      call,
      result
    };
  } catch (error) {
    // 工具失败统一归一化。
    const agentError = normalizeToolError(error, call);

    // 失败也要审计。
    await appendToolAudit({
      sessionId: ctx.sessionId,
      call,
      error: agentError,
      ok: false
    });

    // 交给 recover 判断能否恢复。
    return { name: "recover", error: agentError };
  }
}

// recoverState = 错误恢复策略。
function recoverState(error: AgentError, ctx: TurnContext): EngineState {
  // 快到 maxTurns 时不再恢复，直接停止。
  if (ctx.turn >= ctx.maxTurns - 1) {
    return { name: "done", reason: "max_turns" };
  }

  // 参数错误：把错误回填给模型，让模型按 schema 重试。
  if (error.code === "TOOL_INPUT_INVALID") {
    ctx.messages.push({
      role: "tool",
      toolCallId: "validation-error",
      content: `Tool input invalid: ${error.message}. Retry with valid JSON.`
    });
    ctx.turn++;
    return { name: "call_model" };
  }

  // 工具不存在：告诉模型可用工具列表。
  if (error.code === "TOOL_NOT_FOUND") {
    ctx.messages.push({
      role: "tool",
      toolCallId: "tool-not-found",
      content: `Tool not found. Available tools: ${getToolSchemas().map(t => t.name).join(", ")}`
    });
    ctx.turn++;
    return { name: "call_model" };
  }

  // 其他错误默认不可恢复。
  return { name: "done", reason: "tool_error" };
}

// 状态机测试示例：验证一次工具调用链路存在。
it("runs tool then returns final answer", async () => {
  // 收集 query 产出的所有事件。
  const events = await collectEvents(query("read README"));

  // 应该出现工具开始和工具完成。
  expect(events.map(e => e.type)).toContain("tool_start");
  expect(events.map(e => e.type)).toContain("tool_result");

  // 最后应该正常结束。
  expect(last(events)).toEqual({
    type: "turn_end",
    reason: "final_answer"
  });
});