@yolk-sdk/agent 0.1.0-canary.15 → 0.1.0-canary.16

package/README.md

@@ -1,6 +1,6 @@
 # @yolk-sdk/agent
 
-Domain-free agent protocol, loop, runtime, client, tools, providers, OAuth, React, skillset, and voice primitives.
+Domain-free agent protocol, loop, runtime, client, compaction, tools, providers, OAuth, React, skillset, and voice primitives.
 
 Root export is intentionally tiny. Import feature APIs from explicit subpaths.
 
@@ -23,6 +23,7 @@ Canary APIs are unstable. Keep all `@yolk-sdk/*` packages on the same version.
 | `@yolk-sdk/agent/loop/testing` | Faux provider and tool executor test helpers                   |
 | `@yolk-sdk/agent/runtime`      | Transcript or append-backed runtime orchestration              |
 | `@yolk-sdk/agent/client`       | HTTP/NDJSON transport, HITL resume, and client state helpers   |
+| `@yolk-sdk/agent/compaction`   | Pure host-owned context budget, planning, and transformer utils |
 | `@yolk-sdk/agent/tools`        | Tool module registry, `makeTool`, task/question tool contracts |
 | `@yolk-sdk/agent/react`        | Headless React chat hook, reducer, selectors, and render model |
 | `@yolk-sdk/agent/oauth`        | Provider-neutral OAuth token and broker contracts              |
@@ -48,6 +49,11 @@ import {
 import { run } from '@yolk-sdk/agent/loop'
 import { runRuntime } from '@yolk-sdk/agent/runtime'
 import { initialAgentClientState, toolRunsFromHitlRequests } from '@yolk-sdk/agent/client'
+import {
+  makeContextBudget,
+  makePreviewSummaryMessage,
+  makeWindowCompactionTransformer
+} from '@yolk-sdk/agent/compaction'
 import {
   makeNonRecursiveTaskToolModule,
   makeTaskToolResult,
@@ -92,6 +98,33 @@ const program = run({
 // Provide LLM provider, loop config, context transformer, and tool executor layers in the host app.
 ```
 
+## Context compaction
+
+`@yolk-sdk/agent/compaction` provides pure scaffolding only. It does not call a model, persist
+checkpoints, or retry overflow. Hosts own thresholds, summary policy, and durable storage.
+
+```ts
+import {
+  makeContextBudget,
+  makePreviewSummaryMessage,
+  makeWindowCompactionTransformer
+} from '@yolk-sdk/agent/compaction'
+
+const budget = makeContextBudget({
+  contextWindowTokens: 200_000,
+  reservedOutputTokens: 20_000,
+  warningRatio: 0.8,
+  compactionRatio: 1
+})
+
+const ContextLayer = makeWindowCompactionTransformer({
+  strategy: 'window-summary-v1',
+  thresholdTokens: budget.compactionInputTokens,
+  tailMessageCount: 16,
+  makeSummaryMessage: messages => makePreviewSummaryMessage(messages)
+})
+```
+
 ## Protocol content
 
 `Content` is either plain text or ordered parts:
@@ -187,6 +220,7 @@ See `examples/next/lib/agents/workflow-runtime/text-response.ts` for host-owned
 ## Boundaries
 
 - Core loop/protocol/runtime/tools have no React, Next.js, provider SDKs, auth, storage drivers, or app concepts.
+- `@yolk-sdk/agent/compaction` is pure helper scaffolding; hosts own thresholds, summaries, checkpoints, and overflow retry.
 - `@yolk-sdk/agent/react` is headless and uses React as an optional peer.
 - Provider subpaths own vendor wire/auth mechanics only; hosts own token storage, refresh, routing, and policy.
 - Loop stays stateless: transcript in, events out.

package/dist/compaction/budget.d.mts

@@ -0,0 +1,21 @@
+//#region src/compaction/budget.d.ts
+type ContextBudget = {
+  readonly contextWindowTokens: number;
+  readonly reservedOutputTokens: number;
+  readonly usableInputTokens: number;
+  readonly warningInputTokens: number;
+  readonly compactionInputTokens: number;
+};
+type ContextBudgetInput = {
+  readonly contextWindowTokens: number;
+  readonly reservedOutputTokens: number;
+  readonly warningRatio: number;
+  readonly compactionRatio: number;
+};
+declare const makeContextBudget: (input: ContextBudgetInput) => ContextBudget;
+declare const contextBudgetUsageRatio: (tokens: number, budget: ContextBudget) => number;
+type ContextBudgetStatus = 'idle' | 'normal' | 'warning' | 'compact';
+declare const contextBudgetStatus: (tokens: number, budget: ContextBudget) => ContextBudgetStatus;
+//#endregion
+export { ContextBudget, ContextBudgetInput, ContextBudgetStatus, contextBudgetStatus, contextBudgetUsageRatio, makeContextBudget };
+//# sourceMappingURL=budget.d.mts.map

package/dist/compaction/budget.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.mts","names":[],"sources":["../../src/compaction/budget.ts"],"mappings":";KAAY,aAAA;EAAA,SACD,mBAAA;EAAA,SACA,oBAAA;EAAA,SACA,iBAAA;EAAA,SACA,kBAAA;EAAA,SACA,qBAAA;AAAA;AAAA,KAGC,kBAAA;EAAA,SACD,mBAAA;EAAA,SACA,oBAAA;EAAA,SACA,YAAA;EAAA,SACA,eAAA;AAAA;AAAA,cAGE,iBAAA,GAAqB,KAAA,EAAO,kBAAA,KAAqB,aAU7D;AAAA,cAEY,uBAAA,GAA2B,MAAA,UAAgB,MAAA,EAAQ,aAAa;AAAA,KAGjE,mBAAA;AAAA,cAEC,mBAAA,GAAuB,MAAA,UAAgB,MAAA,EAAQ,aAAA,KAAgB,mBAU3E"}

package/dist/compaction/budget.mjs

@@ -0,0 +1,21 @@
+//#region src/compaction/budget.ts
+const makeContextBudget = (input) => {
+	const usableInputTokens = Math.max(0, input.contextWindowTokens - input.reservedOutputTokens);
+	return {
+		contextWindowTokens: input.contextWindowTokens,
+		reservedOutputTokens: input.reservedOutputTokens,
+		usableInputTokens,
+		warningInputTokens: Math.floor(usableInputTokens * input.warningRatio),
+		compactionInputTokens: Math.floor(usableInputTokens * input.compactionRatio)
+	};
+};
+const contextBudgetUsageRatio = (tokens, budget) => budget.usableInputTokens === 0 ? 0 : tokens / budget.usableInputTokens;
+const contextBudgetStatus = (tokens, budget) => {
+	if (tokens <= 0) return "idle";
+	if (tokens >= budget.compactionInputTokens) return "compact";
+	return tokens >= budget.warningInputTokens ? "warning" : "normal";
+};
+//#endregion
+export { contextBudgetStatus, contextBudgetUsageRatio, makeContextBudget };
+
+//# sourceMappingURL=budget.mjs.map

package/dist/compaction/budget.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.mjs","names":[],"sources":["../../src/compaction/budget.ts"],"sourcesContent":["export type ContextBudget = {\n  readonly contextWindowTokens: number\n  readonly reservedOutputTokens: number\n  readonly usableInputTokens: number\n  readonly warningInputTokens: number\n  readonly compactionInputTokens: number\n}\n\nexport type ContextBudgetInput = {\n  readonly contextWindowTokens: number\n  readonly reservedOutputTokens: number\n  readonly warningRatio: number\n  readonly compactionRatio: number\n}\n\nexport const makeContextBudget = (input: ContextBudgetInput): ContextBudget => {\n  const usableInputTokens = Math.max(0, input.contextWindowTokens - input.reservedOutputTokens)\n\n  return {\n    contextWindowTokens: input.contextWindowTokens,\n    reservedOutputTokens: input.reservedOutputTokens,\n    usableInputTokens,\n    warningInputTokens: Math.floor(usableInputTokens * input.warningRatio),\n    compactionInputTokens: Math.floor(usableInputTokens * input.compactionRatio)\n  }\n}\n\nexport const contextBudgetUsageRatio = (tokens: number, budget: ContextBudget) =>\n  budget.usableInputTokens === 0 ? 0 : tokens / budget.usableInputTokens\n\nexport type ContextBudgetStatus = 'idle' | 'normal' | 'warning' | 'compact'\n\nexport const contextBudgetStatus = (tokens: number, budget: ContextBudget): ContextBudgetStatus => {\n  if (tokens <= 0) {\n    return 'idle'\n  }\n\n  if (tokens >= budget.compactionInputTokens) {\n    return 'compact'\n  }\n\n  return tokens >= budget.warningInputTokens ? 'warning' : 'normal'\n}\n"],"mappings":";AAeA,MAAa,qBAAqB,UAA6C;CAC7E,MAAM,oBAAoB,KAAK,IAAI,GAAG,MAAM,sBAAsB,MAAM,oBAAoB;CAE5F,OAAO;EACL,qBAAqB,MAAM;EAC3B,sBAAsB,MAAM;EAC5B;EACA,oBAAoB,KAAK,MAAM,oBAAoB,MAAM,YAAY;EACrE,uBAAuB,KAAK,MAAM,oBAAoB,MAAM,eAAe;CAC7E;AACF;AAEA,MAAa,2BAA2B,QAAgB,WACtD,OAAO,sBAAsB,IAAI,IAAI,SAAS,OAAO;AAIvD,MAAa,uBAAuB,QAAgB,WAA+C;CACjG,IAAI,UAAU,GACZ,OAAO;CAGT,IAAI,UAAU,OAAO,uBACnB,OAAO;CAGT,OAAO,UAAU,OAAO,qBAAqB,YAAY;AAC3D"}

package/dist/compaction/estimator.d.mts

@@ -0,0 +1,20 @@
+import { AgentMessage, Content } from "@yolk-sdk/agent/protocol";
+
+//#region src/compaction/estimator.d.ts
+type TokenEstimateOptions = {
+  readonly charactersPerToken?: number;
+  readonly mediaPartTokens?: number;
+  readonly messageOverheadTokens?: number;
+};
+type MessageTokenEstimator = (message: AgentMessage) => number;
+type TranscriptTokenEstimator = (messages: ReadonlyArray<AgentMessage>) => number;
+declare const defaultCharactersPerToken = 4;
+declare const defaultMediaPartTokens = 512;
+declare const defaultMessageOverheadTokens = 6;
+declare const estimateTextTokens: (text: string, options?: TokenEstimateOptions) => number;
+declare const estimateContentTokens: (content: Content, options?: TokenEstimateOptions) => number;
+declare const estimateAgentMessageTokens: (message: AgentMessage, options?: TokenEstimateOptions) => number;
+declare const estimateAgentMessagesTokens: (messages: ReadonlyArray<AgentMessage>, options?: TokenEstimateOptions) => number;
+//#endregion
+export { MessageTokenEstimator, TokenEstimateOptions, TranscriptTokenEstimator, defaultCharactersPerToken, defaultMediaPartTokens, defaultMessageOverheadTokens, estimateAgentMessageTokens, estimateAgentMessagesTokens, estimateContentTokens, estimateTextTokens };
+//# sourceMappingURL=estimator.d.mts.map

package/dist/compaction/estimator.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimator.d.mts","names":[],"sources":["../../src/compaction/estimator.ts"],"mappings":";;;KAQY,oBAAA;EAAA,SACD,kBAAA;EAAA,SACA,eAAA;EAAA,SACA,qBAAA;AAAA;AAAA,KAGC,qBAAA,IAAyB,OAAqB,EAAZ,YAAY;AAAA,KAC9C,wBAAA,IAA4B,QAAA,EAAU,aAAa,CAAC,YAAA;AAAA,cAEnD,yBAAA;AAAA,cACA,sBAAA;AAAA,cACA,4BAAA;AAAA,cAWA,kBAAA,GAAsB,IAAA,UAAc,OAAA,GAAS,oBAAyB;AAAA,cAGtE,qBAAA,GAAyB,OAAA,EAAS,OAAA,EAAS,OAAA,GAAS,oBAAyB;AAAA,cAiB7E,0BAAA,GACX,OAAA,EAAS,YAAA,EACT,OAAA,GAAS,oBAAyB;AAAA,cAuBvB,2BAAA,GACX,QAAA,EAAU,aAAA,CAAc,YAAA,GACxB,OAAA,GAAS,oBAAA"}

package/dist/compaction/estimator.mjs

@@ -0,0 +1,32 @@
+import { assistantContent, assistantHostToolCalls, assistantReasoningText } from "@yolk-sdk/agent/protocol";
+//#region src/compaction/estimator.ts
+const defaultCharactersPerToken = 4;
+const defaultMediaPartTokens = 512;
+const defaultMessageOverheadTokens = 6;
+const charactersPerToken = (options) => Math.max(1, options.charactersPerToken ?? 4);
+const mediaPartTokens = (options) => Math.max(0, options.mediaPartTokens ?? 512);
+const messageOverheadTokens = (options) => Math.max(0, options.messageOverheadTokens ?? 6);
+const estimateTextTokens = (text, options = {}) => Math.ceil(text.length / charactersPerToken(options));
+const estimateContentTokens = (content, options = {}) => {
+	if (typeof content === "string") return estimateTextTokens(content, options);
+	return content.reduce((total, part) => {
+		switch (part._tag) {
+			case "Text": return total + estimateTextTokens(part.text, options);
+			case "Image":
+			case "Document":
+			case "Audio": return total + mediaPartTokens(options);
+		}
+	}, 0);
+};
+const estimateAgentMessageTokens = (message, options = {}) => {
+	switch (message._tag) {
+		case "User":
+		case "ToolResult": return estimateContentTokens(message.content, options) + messageOverheadTokens(options);
+		case "Assistant": return estimateContentTokens(assistantContent(message), options) + estimateTextTokens(assistantReasoningText(message), options) + assistantHostToolCalls(message).reduce((total, call) => total + estimateTextTokens(call.id, options) + estimateTextTokens(call.name, options) + messageOverheadTokens(options), 0) + messageOverheadTokens(options);
+	}
+};
+const estimateAgentMessagesTokens = (messages, options = {}) => messages.reduce((total, message) => total + estimateAgentMessageTokens(message, options), 0);
+//#endregion
+export { defaultCharactersPerToken, defaultMediaPartTokens, defaultMessageOverheadTokens, estimateAgentMessageTokens, estimateAgentMessagesTokens, estimateContentTokens, estimateTextTokens };
+
+//# sourceMappingURL=estimator.mjs.map

package/dist/compaction/estimator.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimator.mjs","names":[],"sources":["../../src/compaction/estimator.ts"],"sourcesContent":["import {\n  assistantContent,\n  assistantHostToolCalls,\n  assistantReasoningText,\n  type AgentMessage,\n  type Content\n} from '@yolk-sdk/agent/protocol'\n\nexport type TokenEstimateOptions = {\n  readonly charactersPerToken?: number\n  readonly mediaPartTokens?: number\n  readonly messageOverheadTokens?: number\n}\n\nexport type MessageTokenEstimator = (message: AgentMessage) => number\nexport type TranscriptTokenEstimator = (messages: ReadonlyArray<AgentMessage>) => number\n\nexport const defaultCharactersPerToken = 4\nexport const defaultMediaPartTokens = 512\nexport const defaultMessageOverheadTokens = 6\n\nconst charactersPerToken = (options: TokenEstimateOptions) =>\n  Math.max(1, options.charactersPerToken ?? defaultCharactersPerToken)\n\nconst mediaPartTokens = (options: TokenEstimateOptions) =>\n  Math.max(0, options.mediaPartTokens ?? defaultMediaPartTokens)\n\nconst messageOverheadTokens = (options: TokenEstimateOptions) =>\n  Math.max(0, options.messageOverheadTokens ?? defaultMessageOverheadTokens)\n\nexport const estimateTextTokens = (text: string, options: TokenEstimateOptions = {}) =>\n  Math.ceil(text.length / charactersPerToken(options))\n\nexport const estimateContentTokens = (content: Content, options: TokenEstimateOptions = {}) => {\n  if (typeof content === 'string') {\n    return estimateTextTokens(content, options)\n  }\n\n  return content.reduce((total, part) => {\n    switch (part._tag) {\n      case 'Text':\n        return total + estimateTextTokens(part.text, options)\n      case 'Image':\n      case 'Document':\n      case 'Audio':\n        return total + mediaPartTokens(options)\n    }\n  }, 0)\n}\n\nexport const estimateAgentMessageTokens = (\n  message: AgentMessage,\n  options: TokenEstimateOptions = {}\n) => {\n  switch (message._tag) {\n    case 'User':\n    case 'ToolResult':\n      return estimateContentTokens(message.content, options) + messageOverheadTokens(options)\n    case 'Assistant':\n      return (\n        estimateContentTokens(assistantContent(message), options) +\n        estimateTextTokens(assistantReasoningText(message), options) +\n        assistantHostToolCalls(message).reduce(\n          (total, call) =>\n            total +\n            estimateTextTokens(call.id, options) +\n            estimateTextTokens(call.name, options) +\n            messageOverheadTokens(options),\n          0\n        ) +\n        messageOverheadTokens(options)\n      )\n  }\n}\n\nexport const estimateAgentMessagesTokens = (\n  messages: ReadonlyArray<AgentMessage>,\n  options: TokenEstimateOptions = {}\n) => messages.reduce((total, message) => total + estimateAgentMessageTokens(message, options), 0)\n"],"mappings":";;AAiBA,MAAa,4BAA4B;AACzC,MAAa,yBAAyB;AACtC,MAAa,+BAA+B;AAE5C,MAAM,sBAAsB,YAC1B,KAAK,IAAI,GAAG,QAAQ,sBAAA,CAA+C;AAErE,MAAM,mBAAmB,YACvB,KAAK,IAAI,GAAG,QAAQ,mBAAA,GAAyC;AAE/D,MAAM,yBAAyB,YAC7B,KAAK,IAAI,GAAG,QAAQ,yBAAA,CAAqD;AAE3E,MAAa,sBAAsB,MAAc,UAAgC,CAAC,MAChF,KAAK,KAAK,KAAK,SAAS,mBAAmB,OAAO,CAAC;AAErD,MAAa,yBAAyB,SAAkB,UAAgC,CAAC,MAAM;CAC7F,IAAI,OAAO,YAAY,UACrB,OAAO,mBAAmB,SAAS,OAAO;CAG5C,OAAO,QAAQ,QAAQ,OAAO,SAAS;EACrC,QAAQ,KAAK,MAAb;GACE,KAAK,QACH,OAAO,QAAQ,mBAAmB,KAAK,MAAM,OAAO;GACtD,KAAK;GACL,KAAK;GACL,KAAK,SACH,OAAO,QAAQ,gBAAgB,OAAO;EAC1C;CACF,GAAG,CAAC;AACN;AAEA,MAAa,8BACX,SACA,UAAgC,CAAC,MAC9B;CACH,QAAQ,QAAQ,MAAhB;EACE,KAAK;EACL,KAAK,cACH,OAAO,sBAAsB,QAAQ,SAAS,OAAO,IAAI,sBAAsB,OAAO;EACxF,KAAK,aACH,OACE,sBAAsB,iBAAiB,OAAO,GAAG,OAAO,IACxD,mBAAmB,uBAAuB,OAAO,GAAG,OAAO,IAC3D,uBAAuB,OAAO,EAAE,QAC7B,OAAO,SACN,QACA,mBAAmB,KAAK,IAAI,OAAO,IACnC,mBAAmB,KAAK,MAAM,OAAO,IACrC,sBAAsB,OAAO,GAC/B,CACF,IACA,sBAAsB,OAAO;CAEnC;AACF;AAEA,MAAa,+BACX,UACA,UAAgC,CAAC,MAC9B,SAAS,QAAQ,OAAO,YAAY,QAAQ,2BAA2B,SAAS,OAAO,GAAG,CAAC"}

package/dist/compaction/index.d.mts

@@ -0,0 +1,6 @@
+import { ContextBudget, ContextBudgetInput, ContextBudgetStatus, contextBudgetStatus, contextBudgetUsageRatio, makeContextBudget } from "./budget.mjs";
+import { MessageTokenEstimator, TokenEstimateOptions, TranscriptTokenEstimator, defaultCharactersPerToken, defaultMediaPartTokens, defaultMessageOverheadTokens, estimateAgentMessageTokens, estimateAgentMessagesTokens, estimateContentTokens, estimateTextTokens } from "./estimator.mjs";
+import { PreviewSummaryMessageOptions, defaultPreviewSummaryHeader, defaultSummaryPreviewMaxCharacters, makePreviewSummaryContent, makePreviewSummaryMessage, previewAgentMessage, truncateSummaryPreview } from "./summary.mjs";
+import { ApplyCompactionPlanOptions, CompactCompactionPlan, CompactionResult, CompactionSkipReason, CompletedCompactionResult, SkippedCompactionPlan, SkippedCompactionResult, WindowCompactionPlan, WindowCompactionPlanOptions, applyCompactionPlan, defaultCompactionTailMessageCount, defaultMinimumCompactionMessages, planWindowCompaction, windowTailStartIndex } from "./window.mjs";
+import { SummaryMessageFactory, WindowCompactionOptions, compactWindowMessages, makeWindowCompactionTransformer } from "./transformer.mjs";
+export { type ApplyCompactionPlanOptions, type CompactCompactionPlan, type CompactionResult, type CompactionSkipReason, type CompletedCompactionResult, type ContextBudget, type ContextBudgetInput, type ContextBudgetStatus, type MessageTokenEstimator, type PreviewSummaryMessageOptions, type SkippedCompactionPlan, type SkippedCompactionResult, type SummaryMessageFactory, type TokenEstimateOptions, type TranscriptTokenEstimator, type WindowCompactionOptions, type WindowCompactionPlan, type WindowCompactionPlanOptions, applyCompactionPlan, compactWindowMessages, contextBudgetStatus, contextBudgetUsageRatio, defaultCharactersPerToken, defaultCompactionTailMessageCount, defaultMediaPartTokens, defaultMessageOverheadTokens, defaultMinimumCompactionMessages, defaultPreviewSummaryHeader, defaultSummaryPreviewMaxCharacters, estimateAgentMessageTokens, estimateAgentMessagesTokens, estimateContentTokens, estimateTextTokens, makeContextBudget, makePreviewSummaryContent, makePreviewSummaryMessage, makeWindowCompactionTransformer, planWindowCompaction, previewAgentMessage, truncateSummaryPreview, windowTailStartIndex };

package/dist/compaction/index.mjs

@@ -0,0 +1,6 @@
+import { contextBudgetStatus, contextBudgetUsageRatio, makeContextBudget } from "./budget.mjs";
+import { defaultCharactersPerToken, defaultMediaPartTokens, defaultMessageOverheadTokens, estimateAgentMessageTokens, estimateAgentMessagesTokens, estimateContentTokens, estimateTextTokens } from "./estimator.mjs";
+import { defaultPreviewSummaryHeader, defaultSummaryPreviewMaxCharacters, makePreviewSummaryContent, makePreviewSummaryMessage, previewAgentMessage, truncateSummaryPreview } from "./summary.mjs";
+import { applyCompactionPlan, defaultCompactionTailMessageCount, defaultMinimumCompactionMessages, planWindowCompaction, windowTailStartIndex } from "./window.mjs";
+import { compactWindowMessages, makeWindowCompactionTransformer } from "./transformer.mjs";
+export { applyCompactionPlan, compactWindowMessages, contextBudgetStatus, contextBudgetUsageRatio, defaultCharactersPerToken, defaultCompactionTailMessageCount, defaultMediaPartTokens, defaultMessageOverheadTokens, defaultMinimumCompactionMessages, defaultPreviewSummaryHeader, defaultSummaryPreviewMaxCharacters, estimateAgentMessageTokens, estimateAgentMessagesTokens, estimateContentTokens, estimateTextTokens, makeContextBudget, makePreviewSummaryContent, makePreviewSummaryMessage, makeWindowCompactionTransformer, planWindowCompaction, previewAgentMessage, truncateSummaryPreview, windowTailStartIndex };

package/dist/compaction/summary.d.mts

@@ -0,0 +1,16 @@
+import { AgentMessage, UserMessage } from "@yolk-sdk/agent/protocol";
+
+//#region src/compaction/summary.d.ts
+type PreviewSummaryMessageOptions = {
+  readonly header?: string;
+  readonly maxCharacters?: number;
+};
+declare const defaultPreviewSummaryHeader = "Earlier conversation compacted. Preserve these facts and continue from the recent messages.";
+declare const defaultSummaryPreviewMaxCharacters = 180;
+declare const truncateSummaryPreview: (value: string, maxCharacters: number) => string;
+declare const previewAgentMessage: (message: AgentMessage, options?: PreviewSummaryMessageOptions) => string;
+declare const makePreviewSummaryContent: (messages: ReadonlyArray<AgentMessage>, options?: PreviewSummaryMessageOptions) => string;
+declare const makePreviewSummaryMessage: (messages: ReadonlyArray<AgentMessage>, options?: PreviewSummaryMessageOptions) => UserMessage;
+//#endregion
+export { PreviewSummaryMessageOptions, defaultPreviewSummaryHeader, defaultSummaryPreviewMaxCharacters, makePreviewSummaryContent, makePreviewSummaryMessage, previewAgentMessage, truncateSummaryPreview };
+//# sourceMappingURL=summary.d.mts.map

package/dist/compaction/summary.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.d.mts","names":[],"sources":["../../src/compaction/summary.ts"],"mappings":";;;KAQY,4BAAA;EAAA,SACD,MAAA;EAAA,SACA,aAAa;AAAA;AAAA,cAGX,2BAAA;AAAA,cAGA,kCAAA;AAAA,cAEA,sBAAA,GAA0B,KAAA,UAAe,aAAqB;AAAA,cAc9D,mBAAA,GACX,OAAA,EAAS,YAAA,EACT,OAAA,GAAS,4BAAiC;AAAA,cAuB/B,yBAAA,GACX,QAAA,EAAU,aAAA,CAAc,YAAA,GACxB,OAAA,GAAS,4BAAA;AAAA,cAOE,yBAAA,GACX,QAAA,EAAU,aAAA,CAAc,YAAA,GACxB,OAAA,GAAS,4BAAA,KAAiC,WAAA"}

package/dist/compaction/summary.mjs

@@ -0,0 +1,24 @@
+import { UserMessage, assistantContent, contentPreview, contentText } from "@yolk-sdk/agent/protocol";
+//#region src/compaction/summary.ts
+const defaultPreviewSummaryHeader = "Earlier conversation compacted. Preserve these facts and continue from the recent messages.";
+const defaultSummaryPreviewMaxCharacters = 180;
+const truncateSummaryPreview = (value, maxCharacters) => {
+	const normalized = value.replaceAll(/\s+/g, " ").trim();
+	if (maxCharacters <= 0) return "";
+	if (normalized.length <= maxCharacters) return normalized;
+	return `${normalized.slice(0, Math.max(0, maxCharacters - 1))}…`;
+};
+const previewAgentMessage = (message, options = {}) => {
+	const maxCharacters = options.maxCharacters ?? 180;
+	switch (message._tag) {
+		case "User": return `User: ${truncateSummaryPreview(contentText(message.content) || contentPreview(message.content), maxCharacters)}`;
+		case "Assistant": return `Assistant: ${truncateSummaryPreview(contentText(assistantContent(message)) || contentPreview(assistantContent(message)), maxCharacters)}`;
+		case "ToolResult": return `Tool ${message.toolCallId}: ${truncateSummaryPreview(contentText(message.content) || contentPreview(message.content), maxCharacters)}`;
+	}
+};
+const makePreviewSummaryContent = (messages, options = {}) => [options.header ?? "Earlier conversation compacted. Preserve these facts and continue from the recent messages.", ...messages.map((message) => previewAgentMessage(message, options))].join("\n");
+const makePreviewSummaryMessage = (messages, options = {}) => UserMessage.make({ content: makePreviewSummaryContent(messages, options) });
+//#endregion
+export { defaultPreviewSummaryHeader, defaultSummaryPreviewMaxCharacters, makePreviewSummaryContent, makePreviewSummaryMessage, previewAgentMessage, truncateSummaryPreview };
+
+//# sourceMappingURL=summary.mjs.map

package/dist/compaction/summary.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.mjs","names":[],"sources":["../../src/compaction/summary.ts"],"sourcesContent":["import {\n  UserMessage,\n  assistantContent,\n  contentPreview,\n  contentText,\n  type AgentMessage\n} from '@yolk-sdk/agent/protocol'\n\nexport type PreviewSummaryMessageOptions = {\n  readonly header?: string\n  readonly maxCharacters?: number\n}\n\nexport const defaultPreviewSummaryHeader =\n  'Earlier conversation compacted. Preserve these facts and continue from the recent messages.'\n\nexport const defaultSummaryPreviewMaxCharacters = 180\n\nexport const truncateSummaryPreview = (value: string, maxCharacters: number) => {\n  const normalized = value.replaceAll(/\\s+/g, ' ').trim()\n\n  if (maxCharacters <= 0) {\n    return ''\n  }\n\n  if (normalized.length <= maxCharacters) {\n    return normalized\n  }\n\n  return `${normalized.slice(0, Math.max(0, maxCharacters - 1))}…`\n}\n\nexport const previewAgentMessage = (\n  message: AgentMessage,\n  options: PreviewSummaryMessageOptions = {}\n) => {\n  const maxCharacters = options.maxCharacters ?? defaultSummaryPreviewMaxCharacters\n\n  switch (message._tag) {\n    case 'User':\n      return `User: ${truncateSummaryPreview(\n        contentText(message.content) || contentPreview(message.content),\n        maxCharacters\n      )}`\n    case 'Assistant':\n      return `Assistant: ${truncateSummaryPreview(\n        contentText(assistantContent(message)) || contentPreview(assistantContent(message)),\n        maxCharacters\n      )}`\n    case 'ToolResult':\n      return `Tool ${message.toolCallId}: ${truncateSummaryPreview(\n        contentText(message.content) || contentPreview(message.content),\n        maxCharacters\n      )}`\n  }\n}\n\nexport const makePreviewSummaryContent = (\n  messages: ReadonlyArray<AgentMessage>,\n  options: PreviewSummaryMessageOptions = {}\n) =>\n  [\n    options.header ?? defaultPreviewSummaryHeader,\n    ...messages.map(message => previewAgentMessage(message, options))\n  ].join('\\n')\n\nexport const makePreviewSummaryMessage = (\n  messages: ReadonlyArray<AgentMessage>,\n  options: PreviewSummaryMessageOptions = {}\n) => UserMessage.make({ content: makePreviewSummaryContent(messages, options) })\n"],"mappings":";;AAaA,MAAa,8BACX;AAEF,MAAa,qCAAqC;AAElD,MAAa,0BAA0B,OAAe,kBAA0B;CAC9E,MAAM,aAAa,MAAM,WAAW,QAAQ,GAAG,EAAE,KAAK;CAEtD,IAAI,iBAAiB,GACnB,OAAO;CAGT,IAAI,WAAW,UAAU,eACvB,OAAO;CAGT,OAAO,GAAG,WAAW,MAAM,GAAG,KAAK,IAAI,GAAG,gBAAgB,CAAC,CAAC,EAAE;AAChE;AAEA,MAAa,uBACX,SACA,UAAwC,CAAC,MACtC;CACH,MAAM,gBAAgB,QAAQ,iBAAA;CAE9B,QAAQ,QAAQ,MAAhB;EACE,KAAK,QACH,OAAO,SAAS,uBACd,YAAY,QAAQ,OAAO,KAAK,eAAe,QAAQ,OAAO,GAC9D,aACF;EACF,KAAK,aACH,OAAO,cAAc,uBACnB,YAAY,iBAAiB,OAAO,CAAC,KAAK,eAAe,iBAAiB,OAAO,CAAC,GAClF,aACF;EACF,KAAK,cACH,OAAO,QAAQ,QAAQ,WAAW,IAAI,uBACpC,YAAY,QAAQ,OAAO,KAAK,eAAe,QAAQ,OAAO,GAC9D,aACF;CACJ;AACF;AAEA,MAAa,6BACX,UACA,UAAwC,CAAC,MAEzC,CACE,QAAQ,UAAA,+FACR,GAAG,SAAS,KAAI,YAAW,oBAAoB,SAAS,OAAO,CAAC,CAClE,EAAE,KAAK,IAAI;AAEb,MAAa,6BACX,UACA,UAAwC,CAAC,MACtC,YAAY,KAAK,EAAE,SAAS,0BAA0B,UAAU,OAAO,EAAE,CAAC"}

package/dist/compaction/transformer.d.mts

@@ -0,0 +1,21 @@
+import { TranscriptTokenEstimator } from "./estimator.mjs";
+import { CompactionResult } from "./window.mjs";
+import { Layer } from "effect";
+import { AgentMessage } from "@yolk-sdk/agent/protocol";
+import { ContextTransformer } from "@yolk-sdk/agent/loop";
+
+//#region src/compaction/transformer.d.ts
+type SummaryMessageFactory = (messages: ReadonlyArray<AgentMessage>) => AgentMessage;
+type WindowCompactionOptions = {
+  readonly strategy: string;
+  readonly thresholdTokens: number;
+  readonly tailMessageCount?: number;
+  readonly minMessages?: number;
+  readonly estimateTokens?: TranscriptTokenEstimator;
+  readonly makeSummaryMessage: SummaryMessageFactory;
+};
+declare const compactWindowMessages: (messages: ReadonlyArray<AgentMessage>, options: WindowCompactionOptions) => CompactionResult;
+declare const makeWindowCompactionTransformer: (options: WindowCompactionOptions) => Layer.Layer<ContextTransformer, never, never>;
+//#endregion
+export { SummaryMessageFactory, WindowCompactionOptions, compactWindowMessages, makeWindowCompactionTransformer };
+//# sourceMappingURL=transformer.d.mts.map

package/dist/compaction/transformer.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformer.d.mts","names":[],"sources":["../../src/compaction/transformer.ts"],"mappings":";;;;;;;KAYY,qBAAA,IACV,QAAA,EAAU,aAAA,CAAc,YAAA,MACrB,YAAA;AAAA,KAEO,uBAAA;EAAA,SACD,QAAA;EAAA,SACA,eAAA;EAAA,SACA,gBAAA;EAAA,SACA,WAAA;EAAA,SACA,cAAA,GAAiB,wBAAA;EAAA,SACjB,kBAAA,EAAoB,qBAAqB;AAAA;AAAA,cAWvC,qBAAA,GACX,QAAA,EAAU,aAAA,CAAc,YAAA,GACxB,OAAA,EAAS,uBAAA,KACR,gBAAA;AAAA,cAcU,+BAAA,GAAmC,OAAA,EAAS,uBAAA,KAAuB,KAAA,CAAA,KAAA,CAAA,kBAAA"}

package/dist/compaction/transformer.mjs

@@ -0,0 +1,25 @@
+import { applyCompactionPlan, planWindowCompaction } from "./window.mjs";
+import { Effect, Layer } from "effect";
+import { ContextTransformer } from "@yolk-sdk/agent/loop";
+//#region src/compaction/transformer.ts
+const skippedCompactionResult = (plan) => ({
+	_tag: "Skipped",
+	reason: plan.reason,
+	messages: plan.messages,
+	events: [],
+	beforeTokens: plan.beforeTokens
+});
+const compactWindowMessages = (messages, options) => {
+	const plan = planWindowCompaction(messages, options);
+	if (plan._tag === "Skip") return skippedCompactionResult(plan);
+	return applyCompactionPlan(plan, {
+		strategy: options.strategy,
+		summaryMessage: options.makeSummaryMessage(plan.compactedMessages),
+		estimateTokens: options.estimateTokens
+	});
+};
+const makeWindowCompactionTransformer = (options) => Layer.succeed(ContextTransformer, ContextTransformer.of({ transform: (messages) => Effect.succeed(compactWindowMessages(messages, options)) }));
+//#endregion
+export { compactWindowMessages, makeWindowCompactionTransformer };
+
+//# sourceMappingURL=transformer.mjs.map

package/dist/compaction/transformer.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformer.mjs","names":[],"sources":["../../src/compaction/transformer.ts"],"sourcesContent":["import { Effect, Layer } from 'effect'\nimport type { AgentMessage } from '@yolk-sdk/agent/protocol'\nimport { ContextTransformer } from '@yolk-sdk/agent/loop'\nimport {\n  applyCompactionPlan,\n  planWindowCompaction,\n  type CompactionResult,\n  type SkippedCompactionPlan,\n  type SkippedCompactionResult\n} from './window.ts'\nimport type { TranscriptTokenEstimator } from './estimator.ts'\n\nexport type SummaryMessageFactory = (\n  messages: ReadonlyArray<AgentMessage>\n) => AgentMessage\n\nexport type WindowCompactionOptions = {\n  readonly strategy: string\n  readonly thresholdTokens: number\n  readonly tailMessageCount?: number\n  readonly minMessages?: number\n  readonly estimateTokens?: TranscriptTokenEstimator\n  readonly makeSummaryMessage: SummaryMessageFactory\n}\n\nconst skippedCompactionResult = (plan: SkippedCompactionPlan): SkippedCompactionResult => ({\n  _tag: 'Skipped',\n  reason: plan.reason,\n  messages: plan.messages,\n  events: [],\n  beforeTokens: plan.beforeTokens\n})\n\nexport const compactWindowMessages = (\n  messages: ReadonlyArray<AgentMessage>,\n  options: WindowCompactionOptions\n): CompactionResult => {\n  const plan = planWindowCompaction(messages, options)\n\n  if (plan._tag === 'Skip') {\n    return skippedCompactionResult(plan)\n  }\n\n  return applyCompactionPlan(plan, {\n    strategy: options.strategy,\n    summaryMessage: options.makeSummaryMessage(plan.compactedMessages),\n    estimateTokens: options.estimateTokens\n  })\n}\n\nexport const makeWindowCompactionTransformer = (options: WindowCompactionOptions) =>\n  Layer.succeed(\n    ContextTransformer,\n    ContextTransformer.of({\n      transform: messages => Effect.succeed(compactWindowMessages(messages, options))\n    })\n  )\n"],"mappings":";;;;AAyBA,MAAM,2BAA2B,UAA0D;CACzF,MAAM;CACN,QAAQ,KAAK;CACb,UAAU,KAAK;CACf,QAAQ,CAAC;CACT,cAAc,KAAK;AACrB;AAEA,MAAa,yBACX,UACA,YACqB;CACrB,MAAM,OAAO,qBAAqB,UAAU,OAAO;CAEnD,IAAI,KAAK,SAAS,QAChB,OAAO,wBAAwB,IAAI;CAGrC,OAAO,oBAAoB,MAAM;EAC/B,UAAU,QAAQ;EAClB,gBAAgB,QAAQ,mBAAmB,KAAK,iBAAiB;EACjE,gBAAgB,QAAQ;CAC1B,CAAC;AACH;AAEA,MAAa,mCAAmC,YAC9C,MAAM,QACJ,oBACA,mBAAmB,GAAG,EACpB,YAAW,aAAY,OAAO,QAAQ,sBAAsB,UAAU,OAAO,CAAC,EAChF,CAAC,CACH"}

package/dist/compaction/window.d.mts

@@ -0,0 +1,58 @@
+import { TranscriptTokenEstimator } from "./estimator.mjs";
+import { AgentEvent, AgentMessage } from "@yolk-sdk/agent/protocol";
+
+//#region src/compaction/window.d.ts
+declare const defaultCompactionTailMessageCount = 16;
+declare const defaultMinimumCompactionMessages = 2;
+type CompactionSkipReason = 'too_few_messages' | 'below_threshold' | 'empty_window' | 'not_smaller';
+type WindowCompactionPlanOptions = {
+  readonly thresholdTokens: number;
+  readonly tailMessageCount?: number;
+  readonly minMessages?: number;
+  readonly estimateTokens?: TranscriptTokenEstimator;
+};
+type SkippedCompactionPlan = {
+  readonly _tag: 'Skip';
+  readonly reason: CompactionSkipReason;
+  readonly messages: ReadonlyArray<AgentMessage>;
+  readonly beforeTokens: number;
+};
+type CompactCompactionPlan = {
+  readonly _tag: 'Compact';
+  readonly messages: ReadonlyArray<AgentMessage>;
+  readonly compactedMessages: ReadonlyArray<AgentMessage>;
+  readonly recentMessages: ReadonlyArray<AgentMessage>;
+  readonly tailStartIndex: number;
+  readonly beforeTokens: number;
+};
+type WindowCompactionPlan = SkippedCompactionPlan | CompactCompactionPlan;
+type SkippedCompactionResult = {
+  readonly _tag: 'Skipped';
+  readonly reason: CompactionSkipReason;
+  readonly messages: ReadonlyArray<AgentMessage>;
+  readonly events: ReadonlyArray<AgentEvent>;
+  readonly beforeTokens: number;
+};
+type CompletedCompactionResult = {
+  readonly _tag: 'Compacted';
+  readonly strategy: string;
+  readonly messages: ReadonlyArray<AgentMessage>;
+  readonly events: ReadonlyArray<AgentEvent>;
+  readonly beforeTokens: number;
+  readonly afterTokens: number;
+  readonly compactedMessages: ReadonlyArray<AgentMessage>;
+  readonly recentMessages: ReadonlyArray<AgentMessage>;
+  readonly summaryMessage: AgentMessage;
+};
+type CompactionResult = SkippedCompactionResult | CompletedCompactionResult;
+type ApplyCompactionPlanOptions = {
+  readonly strategy: string;
+  readonly summaryMessage: AgentMessage;
+  readonly estimateTokens?: TranscriptTokenEstimator;
+};
+declare const windowTailStartIndex: (messages: ReadonlyArray<AgentMessage>, tailMessageCount: number) => number;
+declare const planWindowCompaction: (messages: ReadonlyArray<AgentMessage>, options: WindowCompactionPlanOptions) => WindowCompactionPlan;
+declare const applyCompactionPlan: (plan: WindowCompactionPlan, options: ApplyCompactionPlanOptions) => CompactionResult;
+//#endregion
+export { ApplyCompactionPlanOptions, CompactCompactionPlan, CompactionResult, CompactionSkipReason, CompletedCompactionResult, SkippedCompactionPlan, SkippedCompactionResult, WindowCompactionPlan, WindowCompactionPlanOptions, applyCompactionPlan, defaultCompactionTailMessageCount, defaultMinimumCompactionMessages, planWindowCompaction, windowTailStartIndex };
+//# sourceMappingURL=window.d.mts.map

package/dist/compaction/window.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"window.d.mts","names":[],"sources":["../../src/compaction/window.ts"],"mappings":";;;;cAQa,iCAAA;AAAA,cACA,gCAAA;AAAA,KAED,oBAAA;AAAA,KAMA,2BAAA;EAAA,SACD,eAAA;EAAA,SACA,gBAAA;EAAA,SACA,WAAA;EAAA,SACA,cAAA,GAAiB,wBAAwB;AAAA;AAAA,KAGxC,qBAAA;EAAA,SACD,IAAA;EAAA,SACA,MAAA,EAAQ,oBAAA;EAAA,SACR,QAAA,EAAU,aAAA,CAAc,YAAA;EAAA,SACxB,YAAA;AAAA;AAAA,KAGC,qBAAA;EAAA,SACD,IAAA;EAAA,SACA,QAAA,EAAU,aAAA,CAAc,YAAA;EAAA,SACxB,iBAAA,EAAmB,aAAA,CAAc,YAAA;EAAA,SACjC,cAAA,EAAgB,aAAA,CAAc,YAAA;EAAA,SAC9B,cAAA;EAAA,SACA,YAAA;AAAA;AAAA,KAGC,oBAAA,GAAuB,qBAAA,GAAwB,qBAAqB;AAAA,KAEpE,uBAAA;EAAA,SACD,IAAA;EAAA,SACA,MAAA,EAAQ,oBAAA;EAAA,SACR,QAAA,EAAU,aAAA,CAAc,YAAA;EAAA,SACxB,MAAA,EAAQ,aAAA,CAAc,UAAA;EAAA,SACtB,YAAA;AAAA;AAAA,KAGC,yBAAA;EAAA,SACD,IAAA;EAAA,SACA,QAAA;EAAA,SACA,QAAA,EAAU,aAAA,CAAc,YAAA;EAAA,SACxB,MAAA,EAAQ,aAAA,CAAc,UAAA;EAAA,SACtB,YAAA;EAAA,SACA,WAAA;EAAA,SACA,iBAAA,EAAmB,aAAA,CAAc,YAAA;EAAA,SACjC,cAAA,EAAgB,aAAA,CAAc,YAAA;EAAA,SAC9B,cAAA,EAAgB,YAAA;AAAA;AAAA,KAGf,gBAAA,GAAmB,uBAAA,GAA0B,yBAAyB;AAAA,KAEtE,0BAAA;EAAA,SACD,QAAA;EAAA,SACA,cAAA,EAAgB,YAAA;EAAA,SAChB,cAAA,GAAiB,wBAAwB;AAAA;AAAA,cAkBvC,oBAAA,GACX,QAAA,EAAU,aAAa,CAAC,YAAA,GACxB,gBAAA;AAAA,cAaW,oBAAA,GACX,QAAA,EAAU,aAAA,CAAc,YAAA,GACxB,OAAA,EAAS,2BAAA,KACR,oBAAA;AAAA,cAkCU,mBAAA,GACX,IAAA,EAAM,oBAAA,EACN,OAAA,EAAS,0BAAA,KACR,gBAAA"}

package/dist/compaction/window.mjs

@@ -0,0 +1,78 @@
+import { estimateAgentMessagesTokens } from "./estimator.mjs";
+import { CompactionEnd, CompactionStart } from "@yolk-sdk/agent/protocol";
+//#region src/compaction/window.ts
+const defaultCompactionTailMessageCount = 16;
+const defaultMinimumCompactionMessages = 2;
+const estimator = (estimateTokens) => estimateTokens ?? estimateAgentMessagesTokens;
+const skippedCompactionResult = (reason, messages, beforeTokens) => ({
+	_tag: "Skipped",
+	reason,
+	messages,
+	events: [],
+	beforeTokens
+});
+const windowTailStartIndex = (messages, tailMessageCount) => {
+	const tailCount = Math.min(Math.max(0, tailMessageCount), Math.max(0, messages.length - 1));
+	let index = Math.max(1, messages.length - tailCount);
+	while (index > 1 && messages[index]?._tag === "ToolResult") index -= 1;
+	return index;
+};
+const planWindowCompaction = (messages, options) => {
+	const beforeTokens = estimator(options.estimateTokens)(messages);
+	const minMessages = options.minMessages ?? 2;
+	if (messages.length <= minMessages) return {
+		_tag: "Skip",
+		reason: "too_few_messages",
+		messages,
+		beforeTokens
+	};
+	if (beforeTokens < options.thresholdTokens) return {
+		_tag: "Skip",
+		reason: "below_threshold",
+		messages,
+		beforeTokens
+	};
+	const tailStart = windowTailStartIndex(messages, options.tailMessageCount ?? 16);
+	const compactedMessages = messages.slice(0, tailStart);
+	const recentMessages = messages.slice(tailStart);
+	if (compactedMessages.length === 0 || recentMessages.length === 0) return {
+		_tag: "Skip",
+		reason: "empty_window",
+		messages,
+		beforeTokens
+	};
+	return {
+		_tag: "Compact",
+		messages,
+		compactedMessages,
+		recentMessages,
+		tailStartIndex: tailStart,
+		beforeTokens
+	};
+};
+const applyCompactionPlan = (plan, options) => {
+	if (plan._tag === "Skip") return skippedCompactionResult(plan.reason, plan.messages, plan.beforeTokens);
+	const estimateTokens = estimator(options.estimateTokens);
+	const messages = [options.summaryMessage, ...plan.recentMessages];
+	const afterTokens = estimateTokens(messages);
+	if (afterTokens >= plan.beforeTokens) return skippedCompactionResult("not_smaller", plan.messages, plan.beforeTokens);
+	return {
+		_tag: "Compacted",
+		strategy: options.strategy,
+		messages,
+		events: [CompactionStart.make({ strategy: options.strategy }), CompactionEnd.make({
+			strategy: options.strategy,
+			beforeTokens: plan.beforeTokens,
+			afterTokens
+		})],
+		beforeTokens: plan.beforeTokens,
+		afterTokens,
+		compactedMessages: plan.compactedMessages,
+		recentMessages: plan.recentMessages,
+		summaryMessage: options.summaryMessage
+	};
+};
+//#endregion
+export { applyCompactionPlan, defaultCompactionTailMessageCount, defaultMinimumCompactionMessages, planWindowCompaction, windowTailStartIndex };
+
+//# sourceMappingURL=window.mjs.map

package/dist/compaction/window.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"window.mjs","names":[],"sources":["../../src/compaction/window.ts"],"sourcesContent":["import {\n  CompactionEnd,\n  CompactionStart,\n  type AgentEvent,\n  type AgentMessage\n} from '@yolk-sdk/agent/protocol'\nimport { estimateAgentMessagesTokens, type TranscriptTokenEstimator } from './estimator.ts'\n\nexport const defaultCompactionTailMessageCount = 16\nexport const defaultMinimumCompactionMessages = 2\n\nexport type CompactionSkipReason =\n  | 'too_few_messages'\n  | 'below_threshold'\n  | 'empty_window'\n  | 'not_smaller'\n\nexport type WindowCompactionPlanOptions = {\n  readonly thresholdTokens: number\n  readonly tailMessageCount?: number\n  readonly minMessages?: number\n  readonly estimateTokens?: TranscriptTokenEstimator\n}\n\nexport type SkippedCompactionPlan = {\n  readonly _tag: 'Skip'\n  readonly reason: CompactionSkipReason\n  readonly messages: ReadonlyArray<AgentMessage>\n  readonly beforeTokens: number\n}\n\nexport type CompactCompactionPlan = {\n  readonly _tag: 'Compact'\n  readonly messages: ReadonlyArray<AgentMessage>\n  readonly compactedMessages: ReadonlyArray<AgentMessage>\n  readonly recentMessages: ReadonlyArray<AgentMessage>\n  readonly tailStartIndex: number\n  readonly beforeTokens: number\n}\n\nexport type WindowCompactionPlan = SkippedCompactionPlan | CompactCompactionPlan\n\nexport type SkippedCompactionResult = {\n  readonly _tag: 'Skipped'\n  readonly reason: CompactionSkipReason\n  readonly messages: ReadonlyArray<AgentMessage>\n  readonly events: ReadonlyArray<AgentEvent>\n  readonly beforeTokens: number\n}\n\nexport type CompletedCompactionResult = {\n  readonly _tag: 'Compacted'\n  readonly strategy: string\n  readonly messages: ReadonlyArray<AgentMessage>\n  readonly events: ReadonlyArray<AgentEvent>\n  readonly beforeTokens: number\n  readonly afterTokens: number\n  readonly compactedMessages: ReadonlyArray<AgentMessage>\n  readonly recentMessages: ReadonlyArray<AgentMessage>\n  readonly summaryMessage: AgentMessage\n}\n\nexport type CompactionResult = SkippedCompactionResult | CompletedCompactionResult\n\nexport type ApplyCompactionPlanOptions = {\n  readonly strategy: string\n  readonly summaryMessage: AgentMessage\n  readonly estimateTokens?: TranscriptTokenEstimator\n}\n\nconst estimator = (estimateTokens?: TranscriptTokenEstimator) =>\n  estimateTokens ?? estimateAgentMessagesTokens\n\nconst skippedCompactionResult = (\n  reason: CompactionSkipReason,\n  messages: ReadonlyArray<AgentMessage>,\n  beforeTokens: number\n): SkippedCompactionResult => ({\n  _tag: 'Skipped',\n  reason,\n  messages,\n  events: [],\n  beforeTokens\n})\n\nexport const windowTailStartIndex = (\n  messages: ReadonlyArray<AgentMessage>,\n  tailMessageCount: number\n) => {\n  const tailCount = Math.min(Math.max(0, tailMessageCount), Math.max(0, messages.length - 1))\n  const initialIndex = Math.max(1, messages.length - tailCount)\n  let index = initialIndex\n\n  while (index > 1 && messages[index]?._tag === 'ToolResult') {\n    index -= 1\n  }\n\n  return index\n}\n\nexport const planWindowCompaction = (\n  messages: ReadonlyArray<AgentMessage>,\n  options: WindowCompactionPlanOptions\n): WindowCompactionPlan => {\n  const estimateTokens = estimator(options.estimateTokens)\n  const beforeTokens = estimateTokens(messages)\n  const minMessages = options.minMessages ?? defaultMinimumCompactionMessages\n\n  if (messages.length <= minMessages) {\n    return { _tag: 'Skip', reason: 'too_few_messages', messages, beforeTokens }\n  }\n\n  if (beforeTokens < options.thresholdTokens) {\n    return { _tag: 'Skip', reason: 'below_threshold', messages, beforeTokens }\n  }\n\n  const tailStart = windowTailStartIndex(\n    messages,\n    options.tailMessageCount ?? defaultCompactionTailMessageCount\n  )\n  const compactedMessages = messages.slice(0, tailStart)\n  const recentMessages = messages.slice(tailStart)\n\n  if (compactedMessages.length === 0 || recentMessages.length === 0) {\n    return { _tag: 'Skip', reason: 'empty_window', messages, beforeTokens }\n  }\n\n  return {\n    _tag: 'Compact',\n    messages,\n    compactedMessages,\n    recentMessages,\n    tailStartIndex: tailStart,\n    beforeTokens\n  }\n}\n\nexport const applyCompactionPlan = (\n  plan: WindowCompactionPlan,\n  options: ApplyCompactionPlanOptions\n): CompactionResult => {\n  if (plan._tag === 'Skip') {\n    return skippedCompactionResult(plan.reason, plan.messages, plan.beforeTokens)\n  }\n\n  const estimateTokens = estimator(options.estimateTokens)\n  const messages = [options.summaryMessage, ...plan.recentMessages]\n  const afterTokens = estimateTokens(messages)\n\n  if (afterTokens >= plan.beforeTokens) {\n    return skippedCompactionResult('not_smaller', plan.messages, plan.beforeTokens)\n  }\n\n  return {\n    _tag: 'Compacted',\n    strategy: options.strategy,\n    messages,\n    events: [\n      CompactionStart.make({ strategy: options.strategy }),\n      CompactionEnd.make({\n        strategy: options.strategy,\n        beforeTokens: plan.beforeTokens,\n        afterTokens\n      })\n    ],\n    beforeTokens: plan.beforeTokens,\n    afterTokens,\n    compactedMessages: plan.compactedMessages,\n    recentMessages: plan.recentMessages,\n    summaryMessage: options.summaryMessage\n  }\n}\n"],"mappings":";;;AAQA,MAAa,oCAAoC;AACjD,MAAa,mCAAmC;AA6DhD,MAAM,aAAa,mBACjB,kBAAkB;AAEpB,MAAM,2BACJ,QACA,UACA,kBAC6B;CAC7B,MAAM;CACN;CACA;CACA,QAAQ,CAAC;CACT;AACF;AAEA,MAAa,wBACX,UACA,qBACG;CACH,MAAM,YAAY,KAAK,IAAI,KAAK,IAAI,GAAG,gBAAgB,GAAG,KAAK,IAAI,GAAG,SAAS,SAAS,CAAC,CAAC;CAE1F,IAAI,QADiB,KAAK,IAAI,GAAG,SAAS,SAAS,SAC5B;CAEvB,OAAO,QAAQ,KAAK,SAAS,QAAQ,SAAS,cAC5C,SAAS;CAGX,OAAO;AACT;AAEA,MAAa,wBACX,UACA,YACyB;CAEzB,MAAM,eADiB,UAAU,QAAQ,cACP,EAAE,QAAQ;CAC5C,MAAM,cAAc,QAAQ,eAAA;CAE5B,IAAI,SAAS,UAAU,aACrB,OAAO;EAAE,MAAM;EAAQ,QAAQ;EAAoB;EAAU;CAAa;CAG5E,IAAI,eAAe,QAAQ,iBACzB,OAAO;EAAE,MAAM;EAAQ,QAAQ;EAAmB;EAAU;CAAa;CAG3E,MAAM,YAAY,qBAChB,UACA,QAAQ,oBAAA,EACV;CACA,MAAM,oBAAoB,SAAS,MAAM,GAAG,SAAS;CACrD,MAAM,iBAAiB,SAAS,MAAM,SAAS;CAE/C,IAAI,kBAAkB,WAAW,KAAK,eAAe,WAAW,GAC9D,OAAO;EAAE,MAAM;EAAQ,QAAQ;EAAgB;EAAU;CAAa;CAGxE,OAAO;EACL,MAAM;EACN;EACA;EACA;EACA,gBAAgB;EAChB;CACF;AACF;AAEA,MAAa,uBACX,MACA,YACqB;CACrB,IAAI,KAAK,SAAS,QAChB,OAAO,wBAAwB,KAAK,QAAQ,KAAK,UAAU,KAAK,YAAY;CAG9E,MAAM,iBAAiB,UAAU,QAAQ,cAAc;CACvD,MAAM,WAAW,CAAC,QAAQ,gBAAgB,GAAG,KAAK,cAAc;CAChE,MAAM,cAAc,eAAe,QAAQ;CAE3C,IAAI,eAAe,KAAK,cACtB,OAAO,wBAAwB,eAAe,KAAK,UAAU,KAAK,YAAY;CAGhF,OAAO;EACL,MAAM;EACN,UAAU,QAAQ;EAClB;EACA,QAAQ,CACN,gBAAgB,KAAK,EAAE,UAAU,QAAQ,SAAS,CAAC,GACnD,cAAc,KAAK;GACjB,UAAU,QAAQ;GAClB,cAAc,KAAK;GACnB;EACF,CAAC,CACH;EACA,cAAc,KAAK;EACnB;EACA,mBAAmB,KAAK;EACxB,gBAAgB,KAAK;EACrB,gBAAgB,QAAQ;CAC1B;AACF"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@yolk-sdk/agent",
-  "version": "0.1.0-canary.15",
-  "description": "Protocol, loop, runtime, client, tools, React, providers, OAuth, skillset, and voice primitives for building Yolk agents.",
+  "version": "0.1.0-canary.16",
+  "description": "Protocol, loop, runtime, client, compaction, tools, React, providers, OAuth, skillset, and voice primitives for building Yolk agents.",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -37,6 +37,11 @@
       "import": "./dist/client/index.mjs",
       "default": "./dist/client/index.mjs"
     },
+    "./compaction": {
+      "types": "./dist/compaction/index.d.mts",
+      "import": "./dist/compaction/index.mjs",
+      "default": "./dist/compaction/index.mjs"
+    },
     "./loop": {
       "types": "./dist/loop/index.d.mts",
       "import": "./dist/loop/index.mjs",

package/src/compaction/budget.ts

@@ -0,0 +1,43 @@
+export type ContextBudget = {
+  readonly contextWindowTokens: number
+  readonly reservedOutputTokens: number
+  readonly usableInputTokens: number
+  readonly warningInputTokens: number
+  readonly compactionInputTokens: number
+}
+
+export type ContextBudgetInput = {
+  readonly contextWindowTokens: number
+  readonly reservedOutputTokens: number
+  readonly warningRatio: number
+  readonly compactionRatio: number
+}
+
+export const makeContextBudget = (input: ContextBudgetInput): ContextBudget => {
+  const usableInputTokens = Math.max(0, input.contextWindowTokens - input.reservedOutputTokens)
+
+  return {
+    contextWindowTokens: input.contextWindowTokens,
+    reservedOutputTokens: input.reservedOutputTokens,
+    usableInputTokens,
+    warningInputTokens: Math.floor(usableInputTokens * input.warningRatio),
+    compactionInputTokens: Math.floor(usableInputTokens * input.compactionRatio)
+  }
+}
+
+export const contextBudgetUsageRatio = (tokens: number, budget: ContextBudget) =>
+  budget.usableInputTokens === 0 ? 0 : tokens / budget.usableInputTokens
+
+export type ContextBudgetStatus = 'idle' | 'normal' | 'warning' | 'compact'
+
+export const contextBudgetStatus = (tokens: number, budget: ContextBudget): ContextBudgetStatus => {
+  if (tokens <= 0) {
+    return 'idle'
+  }
+
+  if (tokens >= budget.compactionInputTokens) {
+    return 'compact'
+  }
+
+  return tokens >= budget.warningInputTokens ? 'warning' : 'normal'
+}

package/src/compaction/estimator.ts

@@ -0,0 +1,79 @@
+import {
+  assistantContent,
+  assistantHostToolCalls,
+  assistantReasoningText,
+  type AgentMessage,
+  type Content
+} from '@yolk-sdk/agent/protocol'
+
+export type TokenEstimateOptions = {
+  readonly charactersPerToken?: number
+  readonly mediaPartTokens?: number
+  readonly messageOverheadTokens?: number
+}
+
+export type MessageTokenEstimator = (message: AgentMessage) => number
+export type TranscriptTokenEstimator = (messages: ReadonlyArray<AgentMessage>) => number
+
+export const defaultCharactersPerToken = 4
+export const defaultMediaPartTokens = 512
+export const defaultMessageOverheadTokens = 6
+
+const charactersPerToken = (options: TokenEstimateOptions) =>
+  Math.max(1, options.charactersPerToken ?? defaultCharactersPerToken)
+
+const mediaPartTokens = (options: TokenEstimateOptions) =>
+  Math.max(0, options.mediaPartTokens ?? defaultMediaPartTokens)
+
+const messageOverheadTokens = (options: TokenEstimateOptions) =>
+  Math.max(0, options.messageOverheadTokens ?? defaultMessageOverheadTokens)
+
+export const estimateTextTokens = (text: string, options: TokenEstimateOptions = {}) =>
+  Math.ceil(text.length / charactersPerToken(options))
+
+export const estimateContentTokens = (content: Content, options: TokenEstimateOptions = {}) => {
+  if (typeof content === 'string') {
+    return estimateTextTokens(content, options)
+  }
+
+  return content.reduce((total, part) => {
+    switch (part._tag) {
+      case 'Text':
+        return total + estimateTextTokens(part.text, options)
+      case 'Image':
+      case 'Document':
+      case 'Audio':
+        return total + mediaPartTokens(options)
+    }
+  }, 0)
+}
+
+export const estimateAgentMessageTokens = (
+  message: AgentMessage,
+  options: TokenEstimateOptions = {}
+) => {
+  switch (message._tag) {
+    case 'User':
+    case 'ToolResult':
+      return estimateContentTokens(message.content, options) + messageOverheadTokens(options)
+    case 'Assistant':
+      return (
+        estimateContentTokens(assistantContent(message), options) +
+        estimateTextTokens(assistantReasoningText(message), options) +
+        assistantHostToolCalls(message).reduce(
+          (total, call) =>
+            total +
+            estimateTextTokens(call.id, options) +
+            estimateTextTokens(call.name, options) +
+            messageOverheadTokens(options),
+          0
+        ) +
+        messageOverheadTokens(options)
+      )
+  }
+}
+
+export const estimateAgentMessagesTokens = (
+  messages: ReadonlyArray<AgentMessage>,
+  options: TokenEstimateOptions = {}
+) => messages.reduce((total, message) => total + estimateAgentMessageTokens(message, options), 0)

package/src/compaction/index.ts

@@ -0,0 +1,49 @@
+export {
+  contextBudgetStatus,
+  contextBudgetUsageRatio,
+  makeContextBudget
+} from './budget.ts'
+export type { ContextBudget, ContextBudgetInput, ContextBudgetStatus } from './budget.ts'
+export {
+  defaultCharactersPerToken,
+  defaultMediaPartTokens,
+  defaultMessageOverheadTokens,
+  estimateAgentMessageTokens,
+  estimateAgentMessagesTokens,
+  estimateContentTokens,
+  estimateTextTokens
+} from './estimator.ts'
+export type {
+  MessageTokenEstimator,
+  TokenEstimateOptions,
+  TranscriptTokenEstimator
+} from './estimator.ts'
+export {
+  defaultPreviewSummaryHeader,
+  defaultSummaryPreviewMaxCharacters,
+  makePreviewSummaryContent,
+  makePreviewSummaryMessage,
+  previewAgentMessage,
+  truncateSummaryPreview
+} from './summary.ts'
+export type { PreviewSummaryMessageOptions } from './summary.ts'
+export {
+  applyCompactionPlan,
+  defaultCompactionTailMessageCount,
+  defaultMinimumCompactionMessages,
+  planWindowCompaction,
+  windowTailStartIndex
+} from './window.ts'
+export type {
+  ApplyCompactionPlanOptions,
+  CompactCompactionPlan,
+  CompactionResult,
+  CompactionSkipReason,
+  CompletedCompactionResult,
+  SkippedCompactionPlan,
+  SkippedCompactionResult,
+  WindowCompactionPlan,
+  WindowCompactionPlanOptions
+} from './window.ts'
+export { compactWindowMessages, makeWindowCompactionTransformer } from './transformer.ts'
+export type { SummaryMessageFactory, WindowCompactionOptions } from './transformer.ts'

package/src/compaction/summary.ts

@@ -0,0 +1,70 @@
+import {
+  UserMessage,
+  assistantContent,
+  contentPreview,
+  contentText,
+  type AgentMessage
+} from '@yolk-sdk/agent/protocol'
+
+export type PreviewSummaryMessageOptions = {
+  readonly header?: string
+  readonly maxCharacters?: number
+}
+
+export const defaultPreviewSummaryHeader =
+  'Earlier conversation compacted. Preserve these facts and continue from the recent messages.'
+
+export const defaultSummaryPreviewMaxCharacters = 180
+
+export const truncateSummaryPreview = (value: string, maxCharacters: number) => {
+  const normalized = value.replaceAll(/\s+/g, ' ').trim()
+
+  if (maxCharacters <= 0) {
+    return ''
+  }
+
+  if (normalized.length <= maxCharacters) {
+    return normalized
+  }
+
+  return `${normalized.slice(0, Math.max(0, maxCharacters - 1))}…`
+}
+
+export const previewAgentMessage = (
+  message: AgentMessage,
+  options: PreviewSummaryMessageOptions = {}
+) => {
+  const maxCharacters = options.maxCharacters ?? defaultSummaryPreviewMaxCharacters
+
+  switch (message._tag) {
+    case 'User':
+      return `User: ${truncateSummaryPreview(
+        contentText(message.content) || contentPreview(message.content),
+        maxCharacters
+      )}`
+    case 'Assistant':
+      return `Assistant: ${truncateSummaryPreview(
+        contentText(assistantContent(message)) || contentPreview(assistantContent(message)),
+        maxCharacters
+      )}`
+    case 'ToolResult':
+      return `Tool ${message.toolCallId}: ${truncateSummaryPreview(
+        contentText(message.content) || contentPreview(message.content),
+        maxCharacters
+      )}`
+  }
+}
+
+export const makePreviewSummaryContent = (
+  messages: ReadonlyArray<AgentMessage>,
+  options: PreviewSummaryMessageOptions = {}
+) =>
+  [
+    options.header ?? defaultPreviewSummaryHeader,
+    ...messages.map(message => previewAgentMessage(message, options))
+  ].join('\n')
+
+export const makePreviewSummaryMessage = (
+  messages: ReadonlyArray<AgentMessage>,
+  options: PreviewSummaryMessageOptions = {}
+) => UserMessage.make({ content: makePreviewSummaryContent(messages, options) })

package/src/compaction/transformer.ts

@@ -0,0 +1,57 @@
+import { Effect, Layer } from 'effect'
+import type { AgentMessage } from '@yolk-sdk/agent/protocol'
+import { ContextTransformer } from '@yolk-sdk/agent/loop'
+import {
+  applyCompactionPlan,
+  planWindowCompaction,
+  type CompactionResult,
+  type SkippedCompactionPlan,
+  type SkippedCompactionResult
+} from './window.ts'
+import type { TranscriptTokenEstimator } from './estimator.ts'
+
+export type SummaryMessageFactory = (
+  messages: ReadonlyArray<AgentMessage>
+) => AgentMessage
+
+export type WindowCompactionOptions = {
+  readonly strategy: string
+  readonly thresholdTokens: number
+  readonly tailMessageCount?: number
+  readonly minMessages?: number
+  readonly estimateTokens?: TranscriptTokenEstimator
+  readonly makeSummaryMessage: SummaryMessageFactory
+}
+
+const skippedCompactionResult = (plan: SkippedCompactionPlan): SkippedCompactionResult => ({
+  _tag: 'Skipped',
+  reason: plan.reason,
+  messages: plan.messages,
+  events: [],
+  beforeTokens: plan.beforeTokens
+})
+
+export const compactWindowMessages = (
+  messages: ReadonlyArray<AgentMessage>,
+  options: WindowCompactionOptions
+): CompactionResult => {
+  const plan = planWindowCompaction(messages, options)
+
+  if (plan._tag === 'Skip') {
+    return skippedCompactionResult(plan)
+  }
+
+  return applyCompactionPlan(plan, {
+    strategy: options.strategy,
+    summaryMessage: options.makeSummaryMessage(plan.compactedMessages),
+    estimateTokens: options.estimateTokens
+  })
+}
+
+export const makeWindowCompactionTransformer = (options: WindowCompactionOptions) =>
+  Layer.succeed(
+    ContextTransformer,
+    ContextTransformer.of({
+      transform: messages => Effect.succeed(compactWindowMessages(messages, options))
+    })
+  )

package/src/compaction/window.ts

@@ -0,0 +1,172 @@
+import {
+  CompactionEnd,
+  CompactionStart,
+  type AgentEvent,
+  type AgentMessage
+} from '@yolk-sdk/agent/protocol'
+import { estimateAgentMessagesTokens, type TranscriptTokenEstimator } from './estimator.ts'
+
+export const defaultCompactionTailMessageCount = 16
+export const defaultMinimumCompactionMessages = 2
+
+export type CompactionSkipReason =
+  | 'too_few_messages'
+  | 'below_threshold'
+  | 'empty_window'
+  | 'not_smaller'
+
+export type WindowCompactionPlanOptions = {
+  readonly thresholdTokens: number
+  readonly tailMessageCount?: number
+  readonly minMessages?: number
+  readonly estimateTokens?: TranscriptTokenEstimator
+}
+
+export type SkippedCompactionPlan = {
+  readonly _tag: 'Skip'
+  readonly reason: CompactionSkipReason
+  readonly messages: ReadonlyArray<AgentMessage>
+  readonly beforeTokens: number
+}
+
+export type CompactCompactionPlan = {
+  readonly _tag: 'Compact'
+  readonly messages: ReadonlyArray<AgentMessage>
+  readonly compactedMessages: ReadonlyArray<AgentMessage>
+  readonly recentMessages: ReadonlyArray<AgentMessage>
+  readonly tailStartIndex: number
+  readonly beforeTokens: number
+}
+
+export type WindowCompactionPlan = SkippedCompactionPlan | CompactCompactionPlan
+
+export type SkippedCompactionResult = {
+  readonly _tag: 'Skipped'
+  readonly reason: CompactionSkipReason
+  readonly messages: ReadonlyArray<AgentMessage>
+  readonly events: ReadonlyArray<AgentEvent>
+  readonly beforeTokens: number
+}
+
+export type CompletedCompactionResult = {
+  readonly _tag: 'Compacted'
+  readonly strategy: string
+  readonly messages: ReadonlyArray<AgentMessage>
+  readonly events: ReadonlyArray<AgentEvent>
+  readonly beforeTokens: number
+  readonly afterTokens: number
+  readonly compactedMessages: ReadonlyArray<AgentMessage>
+  readonly recentMessages: ReadonlyArray<AgentMessage>
+  readonly summaryMessage: AgentMessage
+}
+
+export type CompactionResult = SkippedCompactionResult | CompletedCompactionResult
+
+export type ApplyCompactionPlanOptions = {
+  readonly strategy: string
+  readonly summaryMessage: AgentMessage
+  readonly estimateTokens?: TranscriptTokenEstimator
+}
+
+const estimator = (estimateTokens?: TranscriptTokenEstimator) =>
+  estimateTokens ?? estimateAgentMessagesTokens
+
+const skippedCompactionResult = (
+  reason: CompactionSkipReason,
+  messages: ReadonlyArray<AgentMessage>,
+  beforeTokens: number
+): SkippedCompactionResult => ({
+  _tag: 'Skipped',
+  reason,
+  messages,
+  events: [],
+  beforeTokens
+})
+
+export const windowTailStartIndex = (
+  messages: ReadonlyArray<AgentMessage>,
+  tailMessageCount: number
+) => {
+  const tailCount = Math.min(Math.max(0, tailMessageCount), Math.max(0, messages.length - 1))
+  const initialIndex = Math.max(1, messages.length - tailCount)
+  let index = initialIndex
+
+  while (index > 1 && messages[index]?._tag === 'ToolResult') {
+    index -= 1
+  }
+
+  return index
+}
+
+export const planWindowCompaction = (
+  messages: ReadonlyArray<AgentMessage>,
+  options: WindowCompactionPlanOptions
+): WindowCompactionPlan => {
+  const estimateTokens = estimator(options.estimateTokens)
+  const beforeTokens = estimateTokens(messages)
+  const minMessages = options.minMessages ?? defaultMinimumCompactionMessages
+
+  if (messages.length <= minMessages) {
+    return { _tag: 'Skip', reason: 'too_few_messages', messages, beforeTokens }
+  }
+
+  if (beforeTokens < options.thresholdTokens) {
+    return { _tag: 'Skip', reason: 'below_threshold', messages, beforeTokens }
+  }
+
+  const tailStart = windowTailStartIndex(
+    messages,
+    options.tailMessageCount ?? defaultCompactionTailMessageCount
+  )
+  const compactedMessages = messages.slice(0, tailStart)
+  const recentMessages = messages.slice(tailStart)
+
+  if (compactedMessages.length === 0 || recentMessages.length === 0) {
+    return { _tag: 'Skip', reason: 'empty_window', messages, beforeTokens }
+  }
+
+  return {
+    _tag: 'Compact',
+    messages,
+    compactedMessages,
+    recentMessages,
+    tailStartIndex: tailStart,
+    beforeTokens
+  }
+}
+
+export const applyCompactionPlan = (
+  plan: WindowCompactionPlan,
+  options: ApplyCompactionPlanOptions
+): CompactionResult => {
+  if (plan._tag === 'Skip') {
+    return skippedCompactionResult(plan.reason, plan.messages, plan.beforeTokens)
+  }
+
+  const estimateTokens = estimator(options.estimateTokens)
+  const messages = [options.summaryMessage, ...plan.recentMessages]
+  const afterTokens = estimateTokens(messages)
+
+  if (afterTokens >= plan.beforeTokens) {
+    return skippedCompactionResult('not_smaller', plan.messages, plan.beforeTokens)
+  }
+
+  return {
+    _tag: 'Compacted',
+    strategy: options.strategy,
+    messages,
+    events: [
+      CompactionStart.make({ strategy: options.strategy }),
+      CompactionEnd.make({
+        strategy: options.strategy,
+        beforeTokens: plan.beforeTokens,
+        afterTokens
+      })
+    ],
+    beforeTokens: plan.beforeTokens,
+    afterTokens,
+    compactedMessages: plan.compactedMessages,
+    recentMessages: plan.recentMessages,
+    summaryMessage: options.summaryMessage
+  }
+}