# 事件循环的主循环结构：四个轮询点决定排队消息在第几轮被取走
外层循环
├─ 取一次引导消息（启动时的初始轮询）
└─ 内层循环（还有工具调用 或 还有待处理消息）
   ├─ 准备消息（prepareNextTurn）
   ├─ 若待处理消息为空，再取一次引导消息
   ├─ 发出 turn_start，注入准备好的和取到的消息
   ├─ provider 请求 → 工具执行
   ├─ finishTurn → turn_end
   └─ 取一次引导消息 → 若有工具调用或取到消息，继续内层循环
└─ 取一次后续消息 → 若取到，继续外层循环

# 引导队列压住后续队列：第 3 点取到引导消息就回到内层循环，根本走不到第 4 点
内层循环结束
  ↓
取引导消息（第 3 点）
  ├─ 取到了 → 回到内层循环，继续跑
  │            （后续队列根本没被看）
  └─ 没取到 → 取后续消息（第 4 点）
               ├─ 取到了 → 回到外层循环，再跑一轮
               └─ 没取到 → 运行结束

// 取出和移除是同一个操作的两个半步，中间没有别的路径能改数组
class PendingMessageQueue {
	private messages: AgentMessage[] = [];
	public mode: QueueMode;

	enqueue(message: AgentMessage): void {
		this.messages.push(message);
	}

	hasItems(): boolean {
		return this.messages.length > 0;
	}

	// 按模式决定这次能看到几条："all" 全部，"one-at-a-time" 只看队首一条
	peek(): AgentMessage[] {
		if (this.mode === "all") return this.messages.slice();
		const first = this.messages[0];
		return first ? [first] : [];
	}

	// drain = peek + 移除
	drain(): AgentMessage[] {
		const drained = this.peek();
		this.messages = this.messages.slice(drained.length);
		return drained;
	}

	clear(): void {
		this.messages = [];
	}
}

// 预览下一轮会被取走的消息：优先看引导队列
// peek 不消费，可以安全地反复调用
peekQueuedMessages(): AgentMessage[] {
	const steering = this.steeringQueue.peek();
	return steering.length > 0 ? steering : this.followUpQueue.peek();
}

// 返回被清掉的内容——SDK 的 abort() 不会退回消息，宿主要自己接住
clearQueue(): { steering: string[]; followUp: string[] } {
	// 先拷贝再清空：直接返回原数组的话，调用方拿到的会是已经被清空的那个
	const steering = [...this._steeringMessages];
	const followUp = [...this._followUpMessages];
	this._steeringMessages = [];
	this._followUpMessages = [];
	// agent 层也要清：会话层和 agent 层各存一份
	this.agent.clearAllQueues();
	// 发出 queue_update，界面上的"N 条待处理"提示才会更新
	this._emitQueueUpdate();
	return { steering, followUp };
}

// continue() 从已有上下文继续
async continue(): Promise<void> {
	if (this.activeRun) {
		throw new Error("Agent is already processing. Wait for completion before continuing.");
	}

	const lastMessage = this._state.messages[this._state.messages.length - 1];
	// 空或全是 system 消息：抛错且不碰队列
	if (!lastMessage || this._state.messages.every((message) => message.role === "system")) {
		throw new Error("No messages to continue from");
	}

	if (lastMessage.role === "assistant") {
		// 尾部是 assistant：必须靠队列里的消息启动，先看引导队列
		const queuedSteering = this.steeringQueue.drain();
		if (queuedSteering.length > 0) {
			// skipInitialSteeringPoll 很关键：消息已经被 drain 出来了，
			// 循环启动时再轮询一次引导队列会造成重复消费
			await this.runPromptMessages(queuedSteering, { skipInitialSteeringPoll: true });
			return;
		}

		const queuedFollowUps = this.followUpQueue.drain();
		if (queuedFollowUps.length > 0) {
			await this.runPromptMessages(queuedFollowUps);
			return;
		}

		// 两个队列都空：抛错
		throw new Error("Cannot continue from message role: assistant");
	}

	// 非 assistant 尾部（user 或 toolResult）：从现有上下文直接继续
	await this.runContinuation();
}

// 先清队列拿到内容，再中止运行
const { steering, followUp } = session.clearQueue();
await session.abort();
// 把 steering 和 followUp 的文本交还给用户界面

import { createAgentSession, SessionManager } from "@earendil-works/pi-coding-agent";

const { session } = await createAgentSession({
	sessionManager: SessionManager.inMemory(),
});

const unsubscribe = session.subscribe((event) => {
	// 队列变化：宿主用它更新"有 N 条待处理消息"的提示
	if (event.type === "queue_update") {
		const total = event.steering.length + event.followUp.length;
		console.error(`[queue] steering=${event.steering.length} followUp=${event.followUp.length}`);
		if (total > 0) {
			// peek 不会消费，可以安全地反复调用
			const next = session.agent.peekQueuedMessages();
			console.error(`[queue] 下一轮会看到 ${next.length} 条`);
		}
	}
	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
		process.stdout.write(event.assistantMessageEvent.delta);
	}
});

try {
	const run = session.prompt("读一下 package.json 并总结依赖");

	// 运行中排两条：一条引导，一条后续
	await new Promise((r) => setTimeout(r, 200));
	console.error("steer ->", await session.steer("先看 pnpm-lock.yaml"));
	await new Promise((r) => setTimeout(r, 200));
	console.error("followUp ->", await session.followUp("最后再总结一下两个文件"));

	await run;

	// 用户改主意：取回还没送出的内容
	const leftover = session.clearQueue();
	if (leftover.steering.length || leftover.followUp.length) {
		console.error("退回编辑器：", leftover);
	}
} finally {
	unsubscribe();
	session.dispose();
}

// 引导和后续同时排入，观察模型先回应哪一条
await session.steer("这是引导：先改 README");
await session.followUp("这是后续：再改 CHANGELOG");

// 在下一次 provider 请求前打印队列预览
const next = session.agent.peekQueuedMessages();
console.error("下一轮先看到：", next.map((m) => m.content));
// 只会看到引导那条：peek 优先看引导队列