From 3d1d9b4f7334993166f1dde941a1abd355e26a6f Mon Sep 17 00:00:00 2001
From: Robin Newhouse <robin@cline.bot>
Date: Fri, 15 May 2026 09:46:39 -0700
Subject: [PATCH] Add compaction budget projection contract

---
 .../context/budget-projection/index.ts        | 14 +++
 .../context/budget-projection/types.ts        | 88 +++++++++++++++++++
 2 files changed, 102 insertions(+)
 create mode 100644 sdk/packages/core/src/extensions/context/budget-projection/index.ts
 create mode 100644 sdk/packages/core/src/extensions/context/budget-projection/types.ts

diff --git a/sdk/packages/core/src/extensions/context/budget-projection/index.ts b/sdk/packages/core/src/extensions/context/budget-projection/index.ts
new file mode 100644
index 0000000000..42b7641dcf
--- /dev/null
+++ b/sdk/packages/core/src/extensions/context/budget-projection/index.ts
@@ -0,0 +1,14 @@
+export type {
+	BlockBudgetClass,
+	BudgetAction,
+	BudgetActionKind,
+	BudgetActionReason,
+	BudgetPath,
+	BudgetPolicyIntent,
+	BudgetProjectionOptions,
+	BudgetProjectionResult,
+	BudgetProjectionWarning,
+	ContentBlockBudgetClassification,
+	LiveTailHandling,
+} from "./types";
+
diff --git a/sdk/packages/core/src/extensions/context/budget-projection/types.ts b/sdk/packages/core/src/extensions/context/budget-projection/types.ts
new file mode 100644
index 0000000000..4f58d874b1
--- /dev/null
+++ b/sdk/packages/core/src/extensions/context/budget-projection/types.ts
@@ -0,0 +1,88 @@
+import type { ContentBlock, MessageWithMetadata } from "@cline/shared";
+
+export type BudgetPolicyIntent =
+	| "agentic_summary"
+	| "basic_compaction_projection"
+	| "normal_provider_request";
+
+export type BudgetActionKind =
+	| "truncated_text"
+	| "dropped_block"
+	| "dropped_message"
+	| "preserved";
+
+export type BudgetActionReason =
+	| "over_budget"
+	| "unsafe_to_truncate"
+	| "tool_pair_boundary"
+	| "protected_live_tail";
+
+export type LiveTailHandling =
+	| "included_verbatim"
+	| "included_degraded"
+	| "summarized_as_context"
+	| "omitted_with_warning"
+	| "preserved_out_of_band";
+
+export type BlockBudgetClass =
+	| "text"
+	| "thinking"
+	| "tool_use"
+	| "tool_result"
+	| "unsafe_binary"
+	| "unsafe_encrypted"
+	| "opaque";
+
+export interface BudgetPath {
+	messageIndex: number;
+	blockIndex?: number;
+}
+
+interface BaseBudgetAction {
+	path: BudgetPath;
+	originalSize: number;
+	finalSize: number;
+}
+
+export interface BudgetMutationAction extends BaseBudgetAction {
+	kind: Exclude<BudgetActionKind, "preserved">;
+	reason: BudgetActionReason;
+}
+
+export interface BudgetPreservedAction extends BaseBudgetAction {
+	kind: "preserved";
+	reason: Extract<
+		BudgetActionReason,
+		"protected_live_tail" | "tool_pair_boundary"
+	>;
+}
+
+export type BudgetAction = BudgetMutationAction | BudgetPreservedAction;
+
+export interface BudgetProjectionWarning {
+	code: string;
+	message: string;
+	path?: BudgetPath;
+}
+
+export interface BudgetProjectionOptions {
+	messages: MessageWithMetadata[];
+	targetTokens: number;
+	policyIntent: BudgetPolicyIntent;
+	estimateMessageTokens: (message: MessageWithMetadata) => number;
+}
+
+export interface BudgetProjectionResult {
+	messages: MessageWithMetadata[];
+	actions: BudgetAction[];
+	liveTailHandling: LiveTailHandling;
+	estimatedTokens: number;
+	warnings: BudgetProjectionWarning[];
+}
+
+export interface ContentBlockBudgetClassification {
+	block: ContentBlock;
+	budgetClass: BlockBudgetClass;
+	canStringTruncate: boolean;
+	canDropWholeBlock: boolean;
+}