@hadooppei/hwcode 0.1.0 → 0.2.1

package/.pi/lib/cloud-providers.ts

@@ -0,0 +1,263 @@
+export type CloudVendorId = "aws" | "azure" | "gcp" | "huawei" | "alibaba" | "tencent";
+export type CloudOperation = "read" | "change" | "delete";
+
+export interface CredentialField {
+	key: string;
+	label: string;
+	secret?: boolean;
+	optional?: boolean;
+	fileContents?: boolean;
+	placeholder?: string;
+}
+
+export interface CloudProvider {
+	id: CloudVendorId;
+	label: string;
+	cli: string;
+	versionArgs: string[];
+	credentialFields: CredentialField[];
+}
+
+export type CloudCredentials = Record<string, string>;
+
+export const CLOUD_PROVIDERS: readonly CloudProvider[] = [
+	{
+		id: "aws",
+		label: "Amazon Web Services (AWS)",
+		cli: "aws",
+		versionArgs: ["--version"],
+		credentialFields: [
+			{ key: "accessKeyId", label: "Access Key ID" },
+			{ key: "secretAccessKey", label: "Secret Access Key", secret: true },
+			{ key: "sessionToken", label: "Session Token（临时凭据可选）", secret: true, optional: true },
+			{ key: "region", label: "默认 Region", placeholder: "us-east-1" },
+		],
+	},
+	{
+		id: "azure",
+		label: "Microsoft Azure",
+		cli: "az",
+		versionArgs: ["version"],
+		credentialFields: [
+			{ key: "tenantId", label: "Tenant ID" },
+			{ key: "subscriptionId", label: "Subscription ID" },
+			{ key: "clientId", label: "Service Principal Client ID" },
+			{ key: "clientSecret", label: "Service Principal Client Secret", secret: true },
+		],
+	},
+	{
+		id: "gcp",
+		label: "Google Cloud",
+		cli: "gcloud",
+		versionArgs: ["version"],
+		credentialFields: [
+			{ key: "serviceAccountJson", label: "Service Account JSON 文件路径", fileContents: true },
+			{ key: "projectId", label: "Project ID（留空则读取 JSON）", optional: true },
+		],
+	},
+	{
+		id: "huawei",
+		label: "华为云 (Huawei Cloud)",
+		cli: "hcloud",
+		versionArgs: ["version"],
+		credentialFields: [
+			{ key: "accessKey", label: "Access Key (AK)" },
+			{ key: "secretKey", label: "Secret Access Key (SK)", secret: true },
+			{ key: "securityToken", label: "Security Token（临时凭据可选）", secret: true, optional: true },
+			{ key: "region", label: "Region", placeholder: "cn-north-4" },
+			{ key: "projectId", label: "Project ID（可选）", optional: true },
+			{ key: "domainId", label: "Domain ID（全局服务可选）", optional: true },
+		],
+	},
+	{
+		id: "alibaba",
+		label: "阿里云 (Alibaba Cloud)",
+		cli: "aliyun",
+		versionArgs: ["version"],
+		credentialFields: [
+			{ key: "accessKeyId", label: "AccessKey ID" },
+			{ key: "accessKeySecret", label: "AccessKey Secret", secret: true },
+			{ key: "securityToken", label: "STS Security Token（可选）", secret: true, optional: true },
+			{ key: "region", label: "默认 Region", placeholder: "cn-hangzhou" },
+		],
+	},
+	{
+		id: "tencent",
+		label: "腾讯云 (Tencent Cloud)",
+		cli: "tccli",
+		versionArgs: ["version"],
+		credentialFields: [
+			{ key: "secretId", label: "SecretId" },
+			{ key: "secretKey", label: "SecretKey", secret: true },
+			{ key: "token", label: "临时凭据 Token（可选）", secret: true, optional: true },
+			{ key: "region", label: "默认 Region", placeholder: "ap-guangzhou" },
+		],
+	},
+] as const;
+
+const PROVIDER_BY_ID = new Map(CLOUD_PROVIDERS.map((provider) => [provider.id, provider]));
+const OPERATION_RANK: Record<CloudOperation, number> = { read: 0, change: 1, delete: 2 };
+
+const DELETE_PATTERNS = [
+	/^(delete|destroy|terminate|remove|revoke|purge|uninstall|decommission)/u,
+	/^(delete|destroy|terminate|remove|revoke|purge|uninstall)[-_]/u,
+];
+const CHANGE_PATTERNS = [
+	/^(create|update|set|apply|deploy|put|add|attach|detach|start|stop|restart|scale|patch|replace|run|launch|authorize|import|move|copy|enable|disable|install|upgrade)/u,
+	/^(create|update|set|apply|deploy|put|add|attach|detach|start|stop|restart|scale|patch|replace|run|launch|authorize|import|move|copy|enable|disable|install|upgrade)[-_]/u,
+];
+
+export const CLOUD_EXECUTABLES = new Set([
+	...CLOUD_PROVIDERS.map((provider) => provider.cli),
+	"terraform",
+	"tofu",
+	"pulumi",
+	"kubectl",
+	"helm",
+]);
+
+export function getCloudProvider(id: CloudVendorId): CloudProvider {
+	const provider = PROVIDER_BY_ID.get(id);
+	if (!provider) throw new Error(`Unsupported cloud provider: ${id}`);
+	return provider;
+}
+
+export function missingCloudCliMessage(id: CloudVendorId): string {
+	const provider = getCloudProvider(id);
+	const base = `未找到 ${provider.label} CLI 可执行文件 \"${provider.cli}\"。请先安装它并确保其位于 PATH 中，然后重新启动 HWCode。`;
+	if (id !== "huawei") return `${base}\n可先在终端运行 \`${provider.cli} ${provider.versionArgs.join(" ")}\` 验证安装。`;
+	return [
+		base,
+		"华为云官方工具名称为 KooCLI；macOS 安装文档：https://support.huaweicloud.com/qs-hcli/hcli_02_003_03.html",
+		"安装后请先在终端运行 `hcloud version`，确认成功后再执行 `/hwcode-cloud`。",
+	].join("\n");
+}
+
+export function inaccessibleCloudCliMessage(id: CloudVendorId): string {
+	const provider = getCloudProvider(id);
+	const base = `无法执行 ${provider.label} CLI \"${provider.cli}\"：文件存在，但当前用户没有执行权限。`;
+	if (id !== "huawei") return `${base}\n请检查 \`command -v ${provider.cli}\` 返回文件的所有者和执行权限。`;
+	return [
+		base,
+		"如果 KooCLI 位于 /usr/local/bin/hcloud，请在系统终端执行：",
+		"`sudo chmod 755 /usr/local/bin/hcloud`",
+		"然后运行 `hcloud version` 验证，再重新执行 `/hwcode-cloud`。",
+	].join("\n");
+}
+
+export function isCloudVendorId(value: string): value is CloudVendorId {
+	return PROVIDER_BY_ID.has(value as CloudVendorId);
+}
+
+export function cloudEnvironment(vendor: CloudVendorId, credentials: CloudCredentials): Record<string, string> {
+	switch (vendor) {
+		case "aws":
+			return compactEnvironment({
+				AWS_ACCESS_KEY_ID: credentials.accessKeyId,
+				AWS_SECRET_ACCESS_KEY: credentials.secretAccessKey,
+				AWS_SESSION_TOKEN: credentials.sessionToken,
+				AWS_DEFAULT_REGION: credentials.region,
+				AWS_REGION: credentials.region,
+			});
+		case "azure":
+			return compactEnvironment({
+				AZURE_TENANT_ID: credentials.tenantId,
+				AZURE_SUBSCRIPTION_ID: credentials.subscriptionId,
+				AZURE_CLIENT_ID: credentials.clientId,
+				AZURE_CLIENT_SECRET: credentials.clientSecret,
+				ARM_TENANT_ID: credentials.tenantId,
+				ARM_SUBSCRIPTION_ID: credentials.subscriptionId,
+				ARM_CLIENT_ID: credentials.clientId,
+				ARM_CLIENT_SECRET: credentials.clientSecret,
+			});
+		case "gcp":
+			return compactEnvironment({
+				GOOGLE_CLOUD_PROJECT: credentials.projectId,
+				CLOUDSDK_CORE_PROJECT: credentials.projectId,
+			});
+		case "huawei":
+			return compactEnvironment({
+				HW_ACCESS_KEY: credentials.accessKey,
+				HW_SECRET_KEY: credentials.secretKey,
+				HW_REGION_NAME: credentials.region,
+				HW_PROJECT_ID: credentials.projectId,
+				HW_DOMAIN_ID: credentials.domainId,
+				HUAWEICLOUD_SDK_AK: credentials.accessKey,
+				HUAWEICLOUD_SDK_SK: credentials.secretKey,
+				HUAWEICLOUD_SDK_SECURITY_TOKEN: credentials.securityToken,
+			});
+		case "alibaba":
+			return compactEnvironment({
+				ALIBABA_CLOUD_ACCESS_KEY_ID: credentials.accessKeyId,
+				ALIBABA_CLOUD_ACCESS_KEY_SECRET: credentials.accessKeySecret,
+				ALIBABA_CLOUD_SECURITY_TOKEN: credentials.securityToken,
+				ALIBABA_CLOUD_REGION_ID: credentials.region,
+				ALIBABA_CLOUD_IGNORE_PROFILE: "TRUE",
+			});
+		case "tencent":
+			return compactEnvironment({
+				TENCENTCLOUD_SECRET_ID: credentials.secretId,
+				TENCENTCLOUD_SECRET_KEY: credentials.secretKey,
+				TENCENTCLOUD_TOKEN: credentials.token,
+				TENCENTCLOUD_REGION: credentials.region,
+			});
+	}
+}
+
+export function classifyCloudOperation(
+	command: string,
+	args: readonly string[],
+	requested: CloudOperation,
+): CloudOperation {
+	let detected = requested;
+	for (const token of [command, ...args]) {
+		const normalized = token.toLowerCase().replace(/[^a-z0-9_-]/gu, "");
+		if (DELETE_PATTERNS.some((pattern) => pattern.test(normalized))) return "delete";
+		if (CHANGE_PATTERNS.some((pattern) => pattern.test(normalized))
+			&& OPERATION_RANK[detected] < OPERATION_RANK.change) detected = "change";
+	}
+	return detected;
+}
+
+export function containsCloudCommand(shellCommand: string): boolean {
+	const executablePattern = [...CLOUD_EXECUTABLES]
+		.map((name) => name.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"))
+		.join("|");
+	return new RegExp(`(?:^|[;&|()\\s])(?:[^\\s;&|()]+/)?(?:${executablePattern})(?=$|\\s)`, "u").test(shellCommand);
+}
+
+export function redactCredentialValues(text: string, credentials: CloudCredentials): string {
+	let redacted = text;
+	const sensitiveValues = new Set(Object.values(credentials));
+	for (const value of Object.values(credentials)) {
+		if (!value.trim().startsWith("{")) continue;
+		try {
+			collectStringValues(JSON.parse(value), sensitiveValues);
+		} catch {
+			// Non-JSON credential values are already included verbatim.
+		}
+	}
+	for (const value of [...sensitiveValues].sort((left, right) => right.length - left.length)) {
+		if (value.length < 4) continue;
+		redacted = redacted.split(value).join("[REDACTED]");
+	}
+	return redacted;
+}
+
+function collectStringValues(value: unknown, output: Set<string>): void {
+	if (typeof value === "string") {
+		output.add(value);
+		return;
+	}
+	if (Array.isArray(value)) {
+		for (const entry of value) collectStringValues(entry, output);
+		return;
+	}
+	if (value && typeof value === "object") {
+		for (const entry of Object.values(value)) collectStringValues(entry, output);
+	}
+}
+
+function compactEnvironment(values: Record<string, string | undefined>): Record<string, string> {
+	return Object.fromEntries(Object.entries(values).filter((entry): entry is [string, string] => Boolean(entry[1])));
+}

package/.pi/lib/cloud-vault.ts

@@ -0,0 +1,209 @@
+import {
+	createCipheriv,
+	createDecipheriv,
+	randomBytes,
+	randomUUID,
+	scryptSync,
+} from "node:crypto";
+import {
+	chmodSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { isCloudVendorId, type CloudCredentials, type CloudVendorId } from "./cloud-providers.ts";
+
+const AAD = Buffer.from("hwcode-cloud-credentials-v1", "utf8");
+const KEY_LENGTH = 32;
+const SCRYPT_OPTIONS = { N: 16_384, r: 8, p: 1, maxmem: 64 * 1024 * 1024 } as const;
+
+export interface CloudCredentialProfile {
+	id: string;
+	credentials: CloudCredentials;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface VaultPayload {
+	version: 2;
+	providers: Partial<Record<CloudVendorId, CloudCredentialProfile[]>>;
+}
+
+interface EncryptedVault {
+	version: 1;
+	kdf: "scrypt";
+	cipher: "aes-256-gcm";
+	salt: string;
+	iv: string;
+	tag: string;
+	ciphertext: string;
+}
+
+export function defaultCloudVaultPath(home = homedir()): string {
+	return join(home, ".hwcode", "cloud", "credentials.enc");
+}
+
+export function cloudVaultExists(path = defaultCloudVaultPath()): boolean {
+	return existsSync(path);
+}
+
+export function createEmptyVault(): VaultPayload {
+	return { version: 2, providers: {} };
+}
+
+function cloneCredentials(value: unknown): CloudCredentials | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const entries = Object.entries(value);
+	if (entries.some(([, field]) => typeof field !== "string")) return undefined;
+	return Object.fromEntries(entries) as CloudCredentials;
+}
+
+export function normalizeCloudVaultPayload(value: unknown): VaultPayload {
+	if (!value || typeof value !== "object") throw new Error("invalid vault payload");
+	const payload = value as Record<string, unknown>;
+	if (!payload.providers || typeof payload.providers !== "object" || Array.isArray(payload.providers)) {
+		throw new Error("invalid vault payload");
+	}
+	const providers: VaultPayload["providers"] = {};
+	for (const [vendor, stored] of Object.entries(payload.providers)) {
+		if (!isCloudVendorId(vendor)) throw new Error("unsupported cloud provider in vault");
+		if (payload.version === 1) {
+			const credentials = cloneCredentials(stored);
+			if (!credentials) throw new Error("invalid legacy credential profile");
+			providers[vendor] = [{
+				id: `legacy-${vendor}`,
+				credentials,
+				createdAt: "1970-01-01T00:00:00.000Z",
+				updatedAt: "1970-01-01T00:00:00.000Z",
+			}];
+			continue;
+		}
+		if (payload.version !== 2 || !Array.isArray(stored)) throw new Error("unsupported vault payload");
+		providers[vendor] = stored.map((profile) => {
+			if (!profile || typeof profile !== "object") throw new Error("invalid credential profile");
+			const data = profile as Record<string, unknown>;
+			const credentials = cloneCredentials(data.credentials);
+			if (typeof data.id !== "string" || !data.id || !credentials
+				|| typeof data.createdAt !== "string" || typeof data.updatedAt !== "string") {
+				throw new Error("invalid credential profile");
+			}
+			return { id: data.id, credentials, createdAt: data.createdAt, updatedAt: data.updatedAt };
+		});
+	}
+	if (payload.version !== 1 && payload.version !== 2) throw new Error("unsupported vault payload");
+	return { version: 2, providers };
+}
+
+export function readCloudVault(password: string, path = defaultCloudVaultPath()): VaultPayload {
+	try {
+		const envelope = JSON.parse(readFileSync(path, "utf8")) as EncryptedVault;
+		if (envelope.version !== 1 || envelope.kdf !== "scrypt" || envelope.cipher !== "aes-256-gcm") {
+			throw new Error("unsupported vault format");
+		}
+		const salt = Buffer.from(envelope.salt, "base64");
+		const key = scryptSync(password, salt, KEY_LENGTH, SCRYPT_OPTIONS);
+		const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(envelope.iv, "base64"));
+		decipher.setAAD(AAD);
+		decipher.setAuthTag(Buffer.from(envelope.tag, "base64"));
+		const plaintext = Buffer.concat([
+			decipher.update(Buffer.from(envelope.ciphertext, "base64")),
+			decipher.final(),
+		]);
+		return normalizeCloudVaultPayload(JSON.parse(plaintext.toString("utf8")));
+	} catch {
+		throw new Error("无法解锁云凭据：主密码错误或凭据文件已损坏");
+	}
+}
+
+export function writeCloudVault(payload: VaultPayload, password: string, path = defaultCloudVaultPath()): void {
+	const directory = dirname(path);
+	mkdirSync(directory, { recursive: true, mode: 0o700 });
+	chmodSync(directory, 0o700);
+
+	const salt = randomBytes(16);
+	const iv = randomBytes(12);
+	const key = scryptSync(password, salt, KEY_LENGTH, SCRYPT_OPTIONS);
+	const cipher = createCipheriv("aes-256-gcm", key, iv);
+	cipher.setAAD(AAD);
+	const ciphertext = Buffer.concat([
+		cipher.update(JSON.stringify(payload), "utf8"),
+		cipher.final(),
+	]);
+	const envelope: EncryptedVault = {
+		version: 1,
+		kdf: "scrypt",
+		cipher: "aes-256-gcm",
+		salt: salt.toString("base64"),
+		iv: iv.toString("base64"),
+		tag: cipher.getAuthTag().toString("base64"),
+		ciphertext: ciphertext.toString("base64"),
+	};
+
+	const temporaryPath = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+	writeFileSync(temporaryPath, `${JSON.stringify(envelope, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+	chmodSync(temporaryPath, 0o600);
+	renameSync(temporaryPath, path);
+	chmodSync(path, 0o600);
+}
+
+export function setCloudCredentials(
+	payload: VaultPayload,
+	vendor: CloudVendorId,
+	credentials: CloudCredentials,
+): VaultPayload {
+	const first = payload.providers[vendor]?.[0];
+	return saveCloudCredentialProfile(payload, vendor, credentials, first?.id);
+}
+
+export function getCloudCredentials(
+	payload: VaultPayload,
+	vendor: CloudVendorId,
+): CloudCredentials | undefined {
+	const credentials = payload.providers[vendor]?.[0]?.credentials;
+	return credentials ? { ...credentials } : undefined;
+}
+
+export function listCloudCredentialProfiles(
+	payload: VaultPayload,
+	vendor: CloudVendorId,
+): CloudCredentialProfile[] {
+	return (payload.providers[vendor] ?? []).map((profile) => ({
+		...profile,
+		credentials: { ...profile.credentials },
+	}));
+}
+
+export function saveCloudCredentialProfile(
+	payload: VaultPayload,
+	vendor: CloudVendorId,
+	credentials: CloudCredentials,
+	profileId?: string,
+): VaultPayload {
+	const now = new Date().toISOString();
+	const profiles = listCloudCredentialProfiles(payload, vendor);
+	const existingIndex = profileId ? profiles.findIndex((profile) => profile.id === profileId) : -1;
+	const profile: CloudCredentialProfile = {
+		id: existingIndex >= 0 ? profiles[existingIndex].id : randomUUID(),
+		credentials: { ...credentials },
+		createdAt: existingIndex >= 0 ? profiles[existingIndex].createdAt : now,
+		updatedAt: now,
+	};
+	if (existingIndex >= 0) profiles[existingIndex] = profile;
+	else profiles.push(profile);
+	return { version: 2, providers: { ...payload.providers, [vendor]: profiles } };
+}
+
+export function cloudCredentialProfileLabel(
+	profile: CloudCredentialProfile,
+	index: number,
+	total: number,
+): string {
+	const number = total > 1 ? ` ${index + 1}` : "";
+	const region = profile.credentials.region?.trim() || "未配置";
+	return `使用已有凭据${number} · Region: ${region}`;
+}

package/.pi/lib/command-filter.ts

@@ -13,6 +13,7 @@ export const DEFAULT_HIDDEN_COMMANDS = [
 	"llama",
 	"skill:hwcode-vibe",
 	"skill:hwcode-sdd",
+	"skill:hwcode-cloud",
 ] as const;
 
 interface ProjectSettings {

package/.pi/lib/context/compaction.ts

@@ -0,0 +1,113 @@
+import {
+  estimateTokens,
+  findCutPoint,
+  sessionEntryToContextMessages,
+  type SessionBeforeCompactEvent,
+  type SessionEntry,
+} from "@earendil-works/pi-coding-agent";
+
+import { calculateCompactionBudgets, type ContextPolicy } from "../context-policy.ts";
+
+function entryMessage(entry: SessionEntry) {
+  if (entry.type === "compaction") return undefined;
+  return sessionEntryToContextMessages(entry)[0];
+}
+
+function addFileOperations(
+  message: ReturnType<typeof sessionEntryToContextMessages>[number],
+  fileOps: SessionBeforeCompactEvent["preparation"]["fileOps"],
+): void {
+  if (message.role !== "assistant" || !Array.isArray(message.content)) return;
+  for (const block of message.content) {
+    if (block.type !== "toolCall") continue;
+    const path = typeof block.arguments?.path === "string" ? block.arguments.path : undefined;
+    if (!path) continue;
+    if (block.name === "read") fileOps.read.add(path);
+    if (block.name === "write") fileOps.written.add(path);
+    if (block.name === "edit") fileOps.edited.add(path);
+  }
+}
+
+function prepareWithKeepBudget(
+  event: SessionBeforeCompactEvent,
+  reserveTokens: number,
+  keepRecentTokens: number,
+): SessionBeforeCompactEvent["preparation"] | undefined {
+  const entries = event.branchEntries;
+  let previousCompactionIndex = -1;
+  for (let index = entries.length - 1; index >= 0; index--) {
+    if (entries[index].type === "compaction") { previousCompactionIndex = index; break; }
+  }
+
+  let boundaryStart = 0;
+  if (previousCompactionIndex >= 0) {
+    const previousCompaction = entries[previousCompactionIndex];
+    if (previousCompaction.type === "compaction") {
+      const previousFirstKept = entries.findIndex((entry) => entry.id === previousCompaction.firstKeptEntryId);
+      boundaryStart = previousFirstKept >= 0 ? previousFirstKept : previousCompactionIndex + 1;
+    }
+  }
+
+  const cutPoint = findCutPoint(entries, boundaryStart, entries.length, keepRecentTokens);
+  const firstKeptEntry = entries[cutPoint.firstKeptEntryIndex];
+  if (!firstKeptEntry?.id) return undefined;
+  const historyEnd = cutPoint.isSplitTurn ? cutPoint.turnStartIndex : cutPoint.firstKeptEntryIndex;
+  const messagesToSummarize = entries.slice(boundaryStart, historyEnd)
+    .map(entryMessage).filter((message): message is NonNullable<typeof message> => Boolean(message));
+  const turnPrefixMessages = cutPoint.isSplitTurn
+    ? entries.slice(cutPoint.turnStartIndex, cutPoint.firstKeptEntryIndex)
+      .map(entryMessage).filter((message): message is NonNullable<typeof message> => Boolean(message))
+    : [];
+  if (messagesToSummarize.length === 0 && turnPrefixMessages.length === 0) return undefined;
+
+  const fileOps = {
+    read: new Set(event.preparation.fileOps.read),
+    written: new Set(event.preparation.fileOps.written),
+    edited: new Set(event.preparation.fileOps.edited),
+  };
+  for (const message of [...messagesToSummarize, ...turnPrefixMessages]) addFileOperations(message, fileOps);
+  return {
+    ...event.preparation,
+    firstKeptEntryId: firstKeptEntry.id,
+    messagesToSummarize,
+    turnPrefixMessages,
+    isSplitTurn: cutPoint.isSplitTurn,
+    fileOps,
+    settings: { ...event.preparation.settings, reserveTokens, keepRecentTokens },
+  };
+}
+
+function estimateKeptTokens(entries: SessionEntry[], firstKeptEntryId: string): number {
+  const firstKeptIndex = entries.findIndex((entry) => entry.id === firstKeptEntryId);
+  if (firstKeptIndex < 0) return Number.POSITIVE_INFINITY;
+  return entries.slice(firstKeptIndex).reduce(
+    (total, entry) => total + sessionEntryToContextMessages(entry)
+      .reduce((entryTotal, message) => entryTotal + estimateTokens(message), 0),
+    0,
+  );
+}
+
+export function tightenPreparation(
+  event: SessionBeforeCompactEvent,
+  policy: ContextPolicy,
+  contextWindow: number,
+  systemPrompt: string,
+): { estimatedTokensAfter: number; targetTokens: number } | undefined {
+  const budgets = calculateCompactionBudgets(policy, contextWindow, systemPrompt);
+  let keepRecentTokens = budgets.keepRecentTokens;
+  let selected = prepareWithKeepBudget(event, budgets.reserveTokens, keepRecentTokens);
+  if (!selected) return undefined;
+
+  let keptTokens = estimateKeptTokens(event.branchEntries, selected.firstKeptEntryId);
+  for (let attempt = 0; keptTokens > budgets.keepRecentTokens && keepRecentTokens > 1 && attempt < 16; attempt++) {
+    const next = Math.max(1, keepRecentTokens - (keptTokens - budgets.keepRecentTokens) - 1);
+    if (next === keepRecentTokens) break;
+    const candidate = prepareWithKeepBudget(event, budgets.reserveTokens, next);
+    if (!candidate) break;
+    selected = candidate;
+    keepRecentTokens = next;
+    keptTokens = estimateKeptTokens(event.branchEntries, selected.firstKeptEntryId);
+  }
+  Object.assign(event.preparation, selected);
+  return { estimatedTokensAfter: keptTokens + budgets.overheadTokens, targetTokens: budgets.targetTokens };
+}