interface AgentConfig {
  initialState?: {
    systemPrompt?: string;        // 系统提示词
    model?: string;               // 模型标识符，如 "anthropic/claude-sonnet-4"
    tools?: Tool[];               // 可用工具定义数组
    thinkingLevel?: number;       // 思考深度（0 = 禁用，数字越大思考越多）
    messages?: Message[];         // 初始消息历史（用于恢复已有会话）
  };

  convertToLlm?: (messages: Message[]) => LlmInput;
  // 将 Pi 内部消息格式转换为 LLM 供应商接受的格式
  // 默认实现将 system / user / assistant / tool_result 消息映射为
  // OpenAI Chat Completions 格式（由 pi-ai 进一步适配到各供应商）

  transformContext?: (messages: Message[]) => Promise<Message[]>;
  // 异步消息修剪/压缩函数
  // 在每次发送给 LLM 之前调用，用于控制上下文窗口大小
  // 典型实现：保留前 N 条消息 + 当前对话窗口 + 系统提示词快照

  toolExecution?: "parallel" | "sequential";
  // 工具执行策略，默认为 "parallel"
  // "parallel"：LLM 一次返回的所有工具调用并发执行
  // "sequential"：LLM 一次返回的工具调用按顺序逐个执行
  // 注意：无论哪种模式，工具内部的执行（如 bash 命令）总是异步的

  beforeToolCall?: (event: ToolCallEvent) => Promise<ToolCallEvent | void>;
  // 工具执行前钩子
  // 可以修改工具参数（如路径规范化）、注入额外参数、或阻止调用（返回 void 等价于跳过）
  // 典型用途：权限检查、路径沙箱、审计日志

  afterToolCall?: (event: ToolResultEvent) => Promise<ToolResultEvent | void>;
  // 工具执行后钩子
  // 可以修改工具返回结果（如裁剪过长输出）、注入结果摘要、或完全替换结果
  // 典型用途：敏感信息脱敏、输出截断、结果缓存

  abortController?: AbortController;
  // 可选的外部 AbortController，用于从外部取消 Agent 的当前操作
}

await agent.prompt("帮我重命名这个函数，把所有调用处一起改掉");

// 场景：Agent 请求确认删除操作
// 用户在 UI 上点击"确认"后：
await agent.continue();

// 模型开始无休止的"让我仔细想想……"循环
agent.abort();
// Agent 回到 Idle 状态，消息历史保留

await agent.prompt("分析这个目录下的所有文件");
await agent.waitForIdle(); // 等待 Agent 完成分析
console.log("分析完成，可以查看结果了");

interface AgentState {
  systemPrompt: string;         // 当前系统提示词
  model: string;                // 当前使用的模型标识符
  tools: Tool[];                // 当前注册的工具列表
  messages: Message[];          // 完整消息历史（包含 system/user/assistant/tool_result）
  status: "idle" | "running";  // Agent 当前运行状态
  error?: Error;                // 如果上次运行失败，此处存储错误对象
}

console.log(`当前模型：${agent.state.model}`);
console.log(`消息数量：${agent.state.messages.length}`);
console.log(`Agent 状态：${agent.state.status}`);

// 遍历工具列表
for (const tool of agent.state.tools) {
  console.log(`  - ${tool.name}: ${tool.description}`);
}

// 完全重置：清空消息、恢复初始 systemPrompt/model/tools
agent.reset();

// 重置但更换模型
agent.reset({ model: "anthropic/claude-opus-4" });

// 重置但更换系统提示词和工具集
agent.reset({
  systemPrompt: "你是一个 Python 代码审查专家。",
  tools: [readTool, grepTool],
});

// Steering：立即中断
await agent.steer({
  role: "user",
  content: "等等，先别改——我刚才说错了，应该改成 getCwd，不是 getcwd",
  timestamp: Date.now(),
});

// Follow-up：排队等当前任务完成
await agent.followUp({
  role: "user",
  content: "另外，别忘了更新 README 里的用法示例",
  timestamp: Date.now(),
});

interface AgentConfig {
  // ...

  steeringMode?: "replace" | "append";
  // "replace"（默认）：新 steering 消息替换队列中的旧 steering 消息
  // "append"：新 steering 消息追加到队列末尾
  // 绝大多数场景用 "replace"——你只关心最新的控制指令

  followUpMode?: "interleave" | "sequential";
  // "interleave"（默认）：follow-up 消息可以在 Agent 循环中间插入
  // "sequential"：follow-up 消息严格在当前轮次完成后才处理
}

const unsubscribe = agent.subscribe((event) => {
  switch (event.type) {
    case "tool_call":
      console.log(`[${event.type}] 调用工具: ${event.toolName}`);
      break;
    case "tool_result":
      console.log(`[${event.type}] 工具返回: ${event.toolName}`);
      break;
    case "assistant_message":
      console.log(`[${event.type}] 助手响应: ${event.content.substring(0, 50)}...`);
      break;
  }
});

// 当你不再需要监听时：
unsubscribe();

type AgentEvent =
  | { type: "status_change"; status: "idle" | "running" }
  // Agent 状态变更（idle ↔ running）

  | { type: "user_message"; message: Message }
  // 用户消息被注入到消息历史中（prompt / steer / followUp）

  | { type: "assistant_message_delta"; content: string; index: number }
  // 流式助手响应的增量（delta）——每个 token 或几个 token 触发一次
  // index 指示这是第几个 choice（通常为 0，除非模型返回多个候选）

  | { type: "assistant_message"; content: string }
  // 助手消息流式输出完成，content 为完整文本

  | { type: "thinking_delta"; content: string }
  // 模型思考过程的增量（thinking trace）——仅支持 thinking 的模型会发出此事件

  | { type: "thinking_done"; content: string }
  // 模型思考过程完成

  | { type: "tool_call"; toolCallId: string; toolName: string; input: Record<string, unknown> }
  // 模型发起了工具调用（参数已解析完毕，尚未执行）

  | { type: "tool_result"; toolCallId: string; toolName: string; result: ToolResult; error?: string }
  // 工具执行完成，result 为工具返回内容，error 为执行错误（如果有）

  | { type: "llm_request_start"; messages: Message[]; model: string }
  // 即将向 LLM 发送请求（消息已通过 transformContext + convertToLlm 处理）
  // 这是扩展开发者最常用的事件之一——检查发给 LLM 的完整 payload

  | { type: "llm_request_end"; usage?: { inputTokens: number; outputTokens: number; cost: number } }
  // LLM 请求返回，usage 包含 token 和成本信息（如果供应商提供）

  | { type: "error"; error: Error; recoverable: boolean }
  // Agent 运行中出现错误
  // recoverable 标识 Agent 能否自动恢复（如网络错误可重试，API 认证错误不可恢复）

  | { type: "reset" }
  // Agent 被重置（agent.reset() 被调用）

  | { type: "loop_start" }
  // Agent Loop 的一轮迭代开始

  | { type: "loop_end"; reason: "task_complete" | "user_abort" | "error" }
  // Agent Loop 的一轮迭代结束，reason 指示结束原因

async function agentLoop(config: AgentConfig, state: AgentState): Promise<void> {
  state.status = "running";

  while (true) {
    emit({ type: "loop_start" });

    // 1. 检查是否存在待处理的 steering / follow-up 消息
    const pendingMessage = checkQueues();
    if (pendingMessage) {
      state.messages.push(pendingMessage);
      emit({ type: "user_message", message: pendingMessage });
    } else if (isFirstIteration) {
      // 第一次迭代：已经有用户 prompt（由 prompt() 注入）
    } else {
      // 没有更多消息要处理 → 任务完成
      emit({ type: "loop_end", reason: "task_complete" });
      break;
    }

    // 2. 应用 transformContext（消息修剪/压缩）
    const contextMessages = config.transformContext
      ? await config.transformContext(state.messages)
      : state.messages;

    // 3. 转换为 LLM 格式
    const llmInput = config.convertToLlm
      ? config.convertToLlm(contextMessages)
      : contextMessages;

    // 4. 调用 LLM，获取流式响应
    emit({ type: "llm_request_start", messages: contextMessages, model: state.model });

    const stream = await callLlm(state.model, llmInput, config.abortController);

    // 5. 流式处理响应
    let textResponse = "";
    let toolCalls: ToolCall[] = [];
    let thinking = "";

    for await (const chunk of stream) {
      if (chunk.type === "text_delta") {
        textResponse += chunk.content;
        emit({ type: "assistant_message_delta", content: chunk.content, index: 0 });
      } else if (chunk.type === "thinking_delta") {
        thinking += chunk.content;
        emit({ type: "thinking_delta", content: chunk.content });
      } else if (chunk.type === "tool_call") {
        toolCalls.push(chunk.toolCall);
      }
    }

    if (thinking) {
      emit({ type: "thinking_done", content: thinking });
    }

    emit({ type: "assistant_message", content: textResponse });

    // 6. 如果模型要求调用工具
    if (toolCalls.length > 0) {
      const toolResults = await executeToolCalls(toolCalls, config);
      // 将工具调用和结果追加到消息历史
      state.messages.push({
        role: "assistant",
        content: textResponse,
        tool_calls: toolCalls,
      });
      for (const result of toolResults) {
        state.messages.push({
          role: "tool",
          tool_call_id: result.toolCallId,
          content: result.content,
        });
      }
      // 循环继续：下次迭代 LLM 会收到工具结果并继续思考
      continue;
    }

    // 7. 没有工具调用 → 本轮完成
    state.messages.push({
      role: "assistant",
      content: textResponse,
    });

    emit({ type: "llm_request_end", usage: stream.usage });
    emit({ type: "loop_end", reason: "task_complete" });
    break;
  }

  state.status = "idle";
}

async function agentLoopContinue(config: AgentConfig, state: AgentState): Promise<void> {
  // 直接进入循环——假设消息历史中已有待处理的 tool_result
  while (true) {
    // ... 与 agentLoop() 中的步骤 2-7 完全相同
  }
}

try {
  // LLM 调用 + 工具执行
} catch (error) {
  if (isRetryable(error)) {
    // 可恢复错误（网络超时、速率限制 429、临时服务不可用 503）
    retryCount++;
    if (retryCount <= maxRetries) {
      await sleep(retryDelay * Math.pow(2, retryCount)); // 指数退避
      continue; // 重试本轮循环
    }
  }
  // 不可恢复错误或重试耗尽
  emit({ type: "error", error, recoverable: false });
  state.status = "idle";
  state.error = error;
  break;
}

async function executeToolCalls(toolCalls: ToolCall[], config: AgentConfig) {
  const executionPromises = toolCalls.map(async (tc) => {
    // beforeToolCall 钩子（同步等待）
    const modifiedTc = config.beforeToolCall
      ? (await config.beforeToolCall({
          type: "tool_call",
          toolCallId: tc.id,
          toolName: tc.function.name,
          input: tc.function.arguments,
        })) ?? tc
      : tc;

    // 参数验证（TypeBox + AJV）
    const tool = config.initialState?.tools?.find(t => t.name === tc.function.name);
    if (!tool) throw new Error(`未知工具: ${tc.function.name}`);
    const validInput = validateParams(tool.parameters, tc.function.arguments);

    emit({ type: "tool_call", toolCallId: tc.id, toolName: tc.function.name, input: validInput });

    // 执行工具
    let result: ToolResult;
    try {
      result = await tool.execute(tc.id, validInput);
    } catch (err) {
      result = { content: [], error: err.message };
    }

    // afterToolCall 钩子
    const modifiedResult = config.afterToolCall
      ? (await config.afterToolCall({
          type: "tool_result",
          toolCallId: tc.id,
          toolName: tc.function.name,
          result,
          error: result.error,
        })) ?? { result, error: result.error }
      : { result, error: result.error };

    emit({
      type: "tool_result",
      toolCallId: tc.id,
      toolName: tc.function.name,
      result: modifiedResult.result,
      error: modifiedResult.error,
    });

    return { toolCallId: tc.id, result: modifiedResult.result, error: modifiedResult.error };
  });

  return await Promise.all(executionPromises);
}

for (const tc of toolCalls) {
  // ... 和并行模式一样的单工具执行逻辑
  const result = await executeTool(tc, config);
  results.push(result);
}

// beforeToolCall 示例：路径沙箱
agent = new Agent({
  beforeToolCall: async (event) => {
    if (event.toolName === "write" || event.toolName === "edit") {
      const path = event.input.path as string;
      if (!path.startsWith("/safe/workdir/")) {
        // 阻止写入安全目录之外的文件
        return void 0; // 返回 void = 跳过此工具调用
      }
      // 路径规范化
      event.input.path = path.replace(/\/{2,}/g, "/");
      return event;
    }
  },
});

// afterToolCall 示例：敏感信息脱敏
agent = new Agent({
  afterToolCall: async (event) => {
    if (event.toolName === "bash") {
      // 脱敏输出中的 API Key
      const content = event.result.content;
      if (content && typeof content === "string") {
        event.result.content = content.replace(
          /(sk-[a-zA-Z0-9]{20,})/g,
          "[REDACTED]",
        );
      }
      return event;
    }
  },
});

interface ToolResult {
  content: string | Array<{
    type: "text" | "image";
    text?: string;
    image?: {
      url?: string;
      base64?: string;
      mediaType?: string;
    };
  }>;
  error?: string;
  details?: Record<string, unknown>; // 附加元数据，不发送给 LLM
}

transformContext?: (messages: Message[]) => Promise<Message[]>;

const transformContext = async (messages: Message[]) => {
  const MAX_MESSAGES = 20; // 保留最近 20 条消息

  // 找到最后一条 system 消息（系统提示词快照）
  const systemIndex = messages.findLastIndex(
    (m) => m.role === "system",
  );
  const systemMessage = systemIndex >= 0 ? [messages[systemIndex]] : [];

  // 取最后 N 条非 system 消息
  const recentMessages = messages
    .filter((m) => m.role !== "system")
    .slice(-MAX_MESSAGES);

  return [...systemMessage, ...recentMessages];
};

convertToLlm?: (messages: Message[]) => LlmInput;

interface Message {
  role: "system" | "user" | "assistant" | "tool";
  content: string;
  tool_calls?: Array<{
    id: string;
    type: "function";
    function: { name: string; arguments: Record<string, unknown> };
  }>;
  tool_call_id?: string;
}

const agent = new Agent({
  convertToLlm: (messages) => {
    // 自定义转换逻辑，例如针对 vLLM 的自部署模型做特殊处理
    return {
      model: agent.state.model,
      messages: messages.map((m) => {
        // 自定义映射逻辑...
      }),
      // 注入自定义参数
      extra_body: { repetition_penalty: 1.1 },
    };
  },
});

const agent = new Agent({
  initialState: {
    systemPrompt: "你是一个编码助手。",
  },
  transformContext: async (messages) => {
    const now = new Date().toISOString();
    // 动态注入当前时间到系统提示词
    const dynamicSystem = {
      role: "system",
      content: `${agent.state.systemPrompt}\n\n当前时间：${now}\n当前工作目录：${process.cwd()}`,
    };
    return [dynamicSystem, ...messages.filter((m) => m.role !== "system")];
  },
});

interface StreamProxy {
  // 发起 LLM 请求，返回可读流
  request(
    messages: Message[],
    model: string,
    tools: Tool[],
    signal?: AbortSignal,
  ): Promise<ReadableStream<LlmChunk>>;
}

import { createTestAgent, MockTool } from "@earendil-works/pi-agent-core/harness";

// 创建一个测试用的 Agent 实例
const agent = createTestAgent({
  systemPrompt: "你是一个测试助手。",
  model: "mock-model", // 使用 mock 模型，不产生实际 API 调用
  tools: [
    MockTool({
      name: "greet",
      description: "按名称问候",
      parameters: Type.Object({ name: Type.String() }),
      // mockedResponses：预定义的"LLM 会生成什么工具调用"
      // 以及"工具应该返回什么结果"
    }),
  ],
});

// 监听事件
const events: AgentEvent[] = [];
agent.subscribe((event) => events.push(event));

// 发送 prompt
await agent.prompt("测试");

// 验证事件序列
assert(events.some((e) => e.type === "tool_call"));
assert(events.some((e) => e.type === "tool_result"));

// 验证消息历史
assert(agent.state.messages.length > 0);

const readFileTool = MockTool({
  name: "read",
  description: "读取文件",
  parameters: Type.Object({
    path: Type.String(),
  }),
  // 预定义行为：对于给定的路径，返回指定的内容
  responses: new Map([
    ["/src/main.ts", { content: "console.log('hello');" }],
    ["/src/utils.ts", { content: "export const add = (a, b) => a + b;" }],
  ]),
  // 工具执行耗时模拟（ms）
  delay: 50,
});

const agent = createTestAgent({
  // ...
  tools: [readFileTool],
  // 模拟模型的多轮响应
  mockedResponses: [
    // 第 1 轮：模型要求读取两个文件
    {
      type: "assistant",
      content: "让我看看这两个文件。",
      tool_calls: [
        { id: "tc1", function: { name: "read", arguments: { path: "/src/main.ts" } } },
        { id: "tc2", function: { name: "read", arguments: { path: "/src/utils.ts" } } },
      ],
    },
    // 第 2 轮：模型得到工具结果后给出最终回答
    {
      type: "assistant",
      content: "文件分析完毕，建议如下……",
      tool_calls: [],
    },
  ],
});