# 一次 prompt() 的事件序列，缩进表示嵌套层级
prompt("Hello")
├─ agent_start
├─ turn_start
├─ message_start   { message: userMessage }      // 你的输入
├─ message_end     { message: userMessage }
├─ message_start   { message: assistantMessage } // 模型开始响应
├─ message_update  { message: partial... }       // 流式分片
├─ message_end     { message: assistantMessage } // 完整回复
├─ turn_end        { message, toolResults: [] }
└─ agent_end       { messages: [...] }

# 第一个 turn 结束（turn_end）之后循环不会停，而是接着开第二个 turn
prompt("Read config.json")
├─ agent_start
├─ turn_start
├─ message_start/end  { userMessage }
├─ message_start      { assistantMessage with toolCall }
├─ message_update...
├─ message_end        { assistantMessage }
├─ tool_execution_start  { toolCallId, toolName, args }
├─ tool_execution_update { partialResult }           // 工具自己流式上报时才有
├─ tool_execution_end    { toolCallId, result }
├─ message_start/end  { toolResultMessage }
├─ turn_end           { message, toolResults: [toolResult] }
│
├─ turn_start                                        // 下一轮
├─ message_start      { assistantMessage }           // 模型看到工具结果后回答
├─ message_update...
├─ message_end
├─ turn_end
└─ agent_end

// 工具内部的失败路径：抛异常而不是把错误文本当成正常结果返回
execute: async (toolCallId, params, signal, onUpdate) => {
  if (!existsSync(params.path)) {
    throw new Error(`File not found: ${params.path}`);
  }
  // 成功时才返回 content，运行时只在这里补 details
  return { content: [{ type: "text", text: "..." }] };
}

// finishTurn 是宿主对循环走向的正式控制点，返回 undefined 表示保持默认调度
agent.finishTurn = async ({ message }) => {
  // 错误和中止是硬退出，这里返回 undefined 也轮不到它们，先显式挡掉
  if (message.stopReason === "error" || message.stopReason === "aborted") return;
  return shouldStop(message) ? { action: "end" } : undefined;
};

// loop.ts
import { Agent, type AgentTool } from "@earendil-works/pi-agent-core";
import {
	createModels,
	fauxAssistantMessage,
	fauxProvider,
	fauxText,
	fauxToolCall,
	Type,
} from "@earendil-works/pi-ai";

const readFileParameters = Type.Object({
	path: Type.String({ description: "相对工作目录的文件路径" }),
});

const readFileTool: AgentTool<typeof readFileParameters> = {
	name: "read_file",
	label: "读取文件",
	description: "读取工作目录下的文本文件",
	parameters: readFileParameters,
	execute: async (_toolCallId, params) => {
		// 失败要抛异常，运行时才会把它作为 isError: true 回给模型
		if (!params.path.endsWith(".md")) {
			throw new Error(`只支持读取 .md 文件，收到：${params.path}`);
		}
		return {
			content: [{ type: "text", text: `# ${params.path}\n（示例内容）` }],
			details: { path: params.path },
		};
	},
};

const faux = fauxProvider();
const models = createModels();
models.setProvider(faux.provider);
const model = faux.getModel();

// 第一轮：模型要求读文件
faux.setResponses([
	fauxAssistantMessage([fauxToolCall("read_file", { path: "README.md" })], { stopReason: "toolUse" }),
]);
// 第二轮：模型看到工具结果后给出最终回答
faux.appendResponses([fauxAssistantMessage([fauxText("README.md 的内容是……")])]);

const agent = new Agent({
	initialState: {
		systemPrompt: "你是一个仓库助手，需要文件内容时调用 read_file。",
		model,
		tools: [readFileTool],
	},
	streamFn: models.streamSimple.bind(models),
	toolExecution: "parallel",
});

const events: string[] = [];
const unsubscribe = agent.subscribe((event) => {
	events.push(event.type);
	if (event.type === "tool_execution_end") {
		console.error(`[工具] ${event.toolName} isError=${event.isError}`);
	}
});

try {
	await agent.prompt("读一下 README.md");
	console.error("[事件]", events.join(" -> "));
	const last = agent.state.messages.at(-1);
	if (last?.role === "assistant") {
		console.log(last.content.map((b) => (b.type === "text" ? b.text : "")).join(""));
	}
} finally {
	unsubscribe();
	agent.abort();
	await agent.waitForIdle();
}

agent_start -> turn_start -> message_start -> message_end -> message_start
-> message_update -> message_end -> tool_execution_start -> tool_execution_end
-> message_start -> message_end -> turn_end -> turn_start -> message_start
-> message_update -> message_end -> turn_end -> agent_end

// 计数放在 Agent 外部：finishTurn 每次调用都要能读到上一轮的累计值
let turnCount = 0;

agent.finishTurn = async ({ message }) => {
	// 错误和中止是硬退出，决策会被忽略，这里先挡掉
	if (message.stopReason === "error" || message.stopReason === "aborted") return;

	turnCount += 1;
	// 跑满两轮就收工：条件有界，所以不会造成无限继续
	return turnCount >= 2 ? { action: "end" } : undefined;
};

// 第一轮脚本化成一次注定失败的工具调用：路径后缀不对，工具会抛异常
faux.setResponses([
	fauxAssistantMessage([fauxToolCall("read_file", { path: "notes.txt" })], { stopReason: "toolUse" }),
]);
// 第二轮模拟模型读到错误后自己纠正，这里直接给出最终文本
faux.appendResponses([
	fauxAssistantMessage([fauxText("这个文件不是 .md，我换一个。")]),
]);

// 用「工具名 + 参数」当 key 统计次数：同一参数反复试探才会被识别出来
const callCounts = new Map<string, number>();

agent.beforeToolCall = async ({ toolCall, args }) => {
	const key = `${toolCall.name}:${JSON.stringify(args)}`;
	const count = (callCounts.get(key) ?? 0) + 1;
	callCounts.set(key, count);

	// 超过阈值就挡下：execute 一次都不会跑
	if (count > 2) {
		// block 之后结果按错误处理；terminate 提示这一批之后不要再发请求
		return { block: true, reason: "同一参数调用次数过多", terminate: true };
	}
	// 返回 undefined 表示放行，钩子跑在参数校验之后、执行之前
	return undefined;
};

// 工具还在跑的时候
agent.steer({ role: "user", content: "停，先看 config.json。", timestamp: Date.now() });

// 等智能体做完手上的事
agent.followUp({ role: "user", content: "做完再总结一下。", timestamp: Date.now() });

// 宿主自己准备一个 AbortController，超时和用户取消都走同一条路
const controller = new AbortController();
// 交给宿主自己的超时逻辑
setTimeout(() => controller.abort(), 30_000);

try {
	// prompt 会一直等到这次运行真正结束，中途的取消由 agent.abort() 触发
	await agent.prompt("做一个很长的任务");
} finally {
	agent.abort();          // 停掉当前操作
	await agent.waitForIdle(); // 等到真正空闲：只调 abort 不等，状态可能还没落定
	unsubscribe();
}