# 一个回合的官方生命周期顺序，箭头方向就是执行顺序
selected input events
→ prepareRequest
→ provider response
→ tool results
→ finishTurn
→ turn_end
→ existing continuation scheduling or agent_end

# Agent Core 事件循环的双层结构
┌─ 外层循环：负责 follow-up 消息和显式续跑
│
│  ┌─ 内层循环：一次 provider 回合
│  │
│  │  ① 若上一轮已完成：
│  │     prepareNextTurn()          ← 可替换上下文/模型/思考级别，追加消息
│  │     （steering 轮询，仅当没有待处理消息时）
│  │     emit turn_start
│  │
│  │  ② 追加待处理消息，逐条 emit message_start / message_end
│  │
│  │  ③ prepareRequest()             ← 本回合唯一的请求准备点
│  │
│  │  ④ provider 响应 → 助手消息
│  │     若 stopReason 是 error / aborted：
│  │        finishTurn()（决策被忽略）
│  │        emit turn_end → emit agent_end → 结束
│  │
│  │  ⑤ 执行工具调用 → 工具结果消息
│  │
│  │  ⑥ finishTurn()                 ← 正常响应的决策点
│  │
│  │  ⑦ emit turn_end
│  │
│  │  ⑧ 决策分流：
│  │     action === "end"    → emit agent_end → 结束
│  │     action === "continue" → 记下显式续跑
│  │     undefined           → 保持默认调度
│  │
│  │  ⑨ steering 轮询
│  └─ 内层循环结束
│
│  ⑩ follow-up 消息轮询
│  ⑪ 若有显式续跑标记 → 再来一个回合
└─ 外层循环结束 → emit agent_end

// Agent Core 事件循环里的实际调用点：每回合一次，在消息追加之后、provider 请求发出之前
const requestUpdate = await config.prepareRequest?.(
	{
		context: currentContext,
		model: config.model,
		thinkingLevel: config.reasoning ?? "off",
	},
	signal,
);
if (requestUpdate) {
	// 返回的上下文替换当前值，并对这次运行剩下的所有回合继续生效
	currentContext = requestUpdate.context ?? currentContext;
	config = {
		...config,
		// 不返回 model 就保留原值（?? 的语义），显式返回更清楚
		model: requestUpdate.model ?? config.model,
		// "off" 表示不要推理，循环把 reasoning 设成 undefined 而不是字符串 "off"
		reasoning:
			requestUpdate.thinkingLevel === undefined
				? config.reasoning
				: requestUpdate.thinkingLevel === "off"
					? undefined
					: requestUpdate.thinkingLevel,
	};
}

// prepare.ts
import type { Agent } from "@earendil-works/pi-agent-core";

// 把「权威上下文」的装载挂到每一次请求前
export function installCanonicalContext(agent: Agent, load: () => Promise<unknown[]>) {
	agent.prepareRequest = async ({ context, model, thinkingLevel }) => {
		// 每回合重新装载权威上下文：压缩、分支、外部修改都能在下一回合生效
		const messages = await load();
		// 返回的 context 替换接下来用的上下文，并对后续回合继续生效
		return { context: { ...context, messages }, model, thinkingLevel };
	};
}

// 源码里有 finishTurn 的两个调用点，返回值的待遇完全不同
// 路径一：错误和中止（Agent Core 事件循环里）
if (message.stopReason === "error" || message.stopReason === "aborted") {
	lastCompletedTurn = { message, toolResults: [], context: currentContext, newMessages };
	await config.finishTurn?.(lastCompletedTurn, signal);   // ← 返回值被丢弃
	// 错误路径上工具一个都没跑，所以 toolResults 是空数组
	await emit({ type: "turn_end", message, toolResults: [] });
	await emit({ type: "agent_end", messages: newMessages });
	return;
}

// 路径二：正常响应（Agent Core 事件循环里）
lastCompletedTurn = { message, toolResults, context: currentContext, newMessages };
// 正常响应才拿到决策，但决策作用于 turn_end 之后的调度
const decision = await config.finishTurn?.(lastCompletedTurn, signal);
await emit({ type: "turn_end", message, toolResults });

// "continue" 只是保底：工具结果或 steering 已经安排了请求时，显式续跑作废
explicitContinuation = decision?.action === "continue";
pendingMessages = (await config.getSteeringMessages?.()) || [];
if (hasMoreToolCalls || pendingMessages.length > 0) {
	explicitContinuation = false;   // 已经被别的东西安排了，显式续跑作废
}

// 迁移前：shouldStopAfterTurn 已在 Agent Core 里被移除
agent.shouldStopAfterTurn = async (turn, signal) => {
	return shouldStop(turn, signal);
};

// 迁移后：谓词搬进 finishTurn，并补上错误和中止的守卫
agent.finishTurn = async (turn, signal) => {
	// shouldStopAfterTurn 以前只在正常响应上运行
	if (turn.message.stopReason === "error" || turn.message.stopReason === "aborted") return;
	// 谓词返回 true 才结束；否则交回 undefined 保持默认调度
	return (await shouldStop(turn, signal)) ? { action: "end" } : undefined;
};

// 计数放在 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;
};

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

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

// 模型连续三轮都要求调工具
faux.setResponses([
	fauxAssistantMessage([fauxToolCall("noop", {})], { stopReason: "toolUse" }),
]);
faux.appendResponses([
	fauxAssistantMessage([fauxToolCall("noop", {})], { stopReason: "toolUse" }),
]);
faux.appendResponses([
	fauxAssistantMessage([fauxToolCall("noop", {})], { stopReason: "toolUse" }),
]);
faux.appendResponses([fauxAssistantMessage([fauxText("好了")])]);

const agent = new Agent({
	initialState: {
		systemPrompt: "你是测试助手。",
		model,
		tools: [
			{
				name: "noop",
				label: "空操作",
				description: "什么都不做",
				parameters: Type.Object({}),
				execute: async () => ({ content: [{ type: "text", text: "ok" }], details: {} }),
			},
		],
	},
	streamFn: models.streamSimple.bind(models),
});

let requestCount = 0;
let turnCount = 0;

agent.prepareRequest = async ({ context, model: m, thinkingLevel }) => {
	requestCount += 1;
	// prepareRequest 不轮询队列，这里也不该去碰队列
	return { context, model: m, thinkingLevel };
};

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

	turnCount += 1;
	// 有界的终止条件：跑满两轮就收工
	return turnCount >= 2 ? { action: "end" } : undefined;
};

const turnStarts: number[] = [];
const unsubscribe = agent.subscribe((event) => {
	if (event.type === "turn_start") turnStarts.push(turnStarts.length);
});

try {
	await agent.prompt("开始");

	console.error("[统计] provider 请求次数 =", requestCount);
	console.error("[统计] finishTurn 调用次数 =", turnCount);
	console.error("[统计] turn_start 次数 =", turnStarts.length);
	console.error("[统计] 消息数 =", agent.state.messages.length);
} finally {
	unsubscribe();
	agent.abort();
	await agent.waitForIdle();
}

[统计] provider 请求次数 = 2
[统计] finishTurn 调用次数 = 2
[统计] turn_start 次数 = 2
[统计] 消息数 = 5