# 两步转换各管一段：先裁剪上下文，再转成模型格式
AgentMessage[] → transformContext() → AgentMessage[] → convertToLlm() → Message[] → LLM

// 最权威的钩子：用权威来源整体替换上下文
agent.prepareRequest = async ({ context }) => ({
	// 必须返回 { context }；返回 undefined 表示保持不变
	context: { ...context, messages: await session.loadModelContext() },
});

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

// 保留最近多少条原文；中段其余部分被压成一条占位消息
const KEEP_RECENT = 12;

const { session } = await createAgentSession();

session.agent.transformContext = async (messages) => {
	// 系统消息承载提示与工具声明，永远保留
	const system = messages.filter((m) => m.role === "system");
	const rest = messages.filter((m) => m.role !== "system");

	// 还没超阈值就原样返回：裁剪本身会让模型丢掉信息
	if (rest.length <= KEEP_RECENT) return messages;

	const head = rest.slice(0, rest.length - KEEP_RECENT);
	const tail = rest.slice(rest.length - KEEP_RECENT);

	// 中段只留一条提示，让模型知道这里被裁过
	const placeholder = {
		role: "user" as const,
		content: `[已裁剪 ${head.length} 条早期消息：包含初始任务与历史工具输出]`,
		timestamp: Date.now(),
	};

	// 注意这里只影响这一次请求，不写进会话
	return [...system, placeholder, ...tail];
};

try {
	await session.prompt("修复 src/types.ts 里 UserProfile 的类型错误");
	console.log("完成");
} finally {
	session.dispose();
}

# 自动压缩的触发条件：剩余可用窗口不足以再塞一条消息时就该压缩
contextTokens > contextWindow - reserveTokens

{
	"compaction": {
		"enabled": true,
		"reserveTokens": 16384,
		"keepRecentTokens": 20000
	}
}

{
	"compaction": {
		"reserveTokens": 16384,
		"keepRecentTokens": 20000,
		"modelOverrides": {
			"some-provider/big-model": {
				"reserveTokens": 400000
			}
		}
	}
}

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
	pi.on("session_before_compact", async (event) => {
		const { preparation, reason, willRetry } = event;

		// preparation.messagesToSummarize —— 待摘要的消息
		// preparation.firstKeptEntryId —— 保留区从哪里开始
		// preparation.tokensBefore —— 压缩前的上下文 token 数
		// reason 是 "manual" | "threshold" | "overflow"

		// 拒绝压缩：这次压缩不该发生
		if (reason === "threshold" && preparation.tokensBefore < 50_000) {
			return { cancel: true };
		}

		return {
			compaction: {
				summary: `## Goal\n继续修复类型错误\n\n## Next Steps\n1. 重跑 tsc 确认`,
				firstKeptEntryId: preparation.firstKeptEntryId,
				tokensBefore: preparation.tokensBefore,
			},
		};
	});

	pi.on("session_compact_failed", async (event) => {
		// reason / errorMessage / aborted / willRetry / fromExtension
		// 把失败和取消都记进你自己的遥测
	});
}

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

const { session } = await createAgentSession();

// 保留原有的钩子，先跑它再叠加我们的逻辑
const previousPrepareRequest = session.agent.prepareRequest;

session.agent.prepareRequest = async (request, signal) => {
	const result = await previousPrepareRequest?.(request, signal);
	const context = result?.context ?? request.context;

	// 从权威来源重建：会话投影 + 当前项目状态
	const projection = session.sessionManager.buildSessionProjection();
	// 每次请求都重新读：prepareRequest 不轮询队列，但每次请求都会触发
	const projectState = await loadProjectState(signal);

	const messages: AgentMessage[] = [
		...projection.messages,
		{
			// 用 XML 标签包起来，让模型能分辨哪段是注入的外部状态
			role: "user",
			content: `<project-state>\n${projectState}\n</project-state>`,
			timestamp: Date.now(),
		},
	];

	// 必须返回 { context }：返回 undefined 表示保持原上下文不变
	return { ...result, context: { ...context, messages } };
};

async function loadProjectState(signal?: AbortSignal): Promise<string> {
	// 实际项目里这里读数据库、读配置文件或调用内部 API
	return "分支: feature/fix-types\n已修改文件: src/types.ts";
}

try {
	await session.prompt("继续修复类型错误");
} finally {
	session.dispose();
}