@tanstack/ai-compaction 0.0.0 → 0.1.1

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/index.ts"],"sourcesContent":["/**\n * `@tanstack/ai-compaction` — context-window compaction as a `chat()`\n * middleware. `withCompaction({ maxTokens, strategy })` runs before each model\n * call: when the working message set grows past `maxTokens`, the chosen\n * `CompactionStrategy` rewrites the messages. Because it runs every call,\n * compaction is incremental and rolling.\n *\n * Strategies are pluggable, mirroring `AgentLoopStrategy`. Three are built in:\n * {@link evictOldest}, {@link summarizeOldest}, and {@link clearToolResults}.\n * Write your own by passing any {@link CompactionStrategy}.\n *\n * The system prompt is never touched — `chat()` keeps it separate from\n * `messages`.\n */\nimport { MetadataCapability, getMetadata } from '@tanstack/ai'\nimport type {\n  ChatMiddleware,\n  ChatMiddlewareContext,\n  ModelMessage,\n} from '@tanstack/ai'\n\n/** CUSTOM stream event: compaction is about to run. */\nexport const COMPACTION_STARTED_EVENT = 'compaction:started'\n/** CUSTOM stream event: compaction result (counts and previews). */\nexport const COMPACTION_STATE_EVENT = 'compaction:state'\n/** CUSTOM stream event: compaction finished. */\nexport const COMPACTION_ENDED_EVENT = 'compaction:ended'\n\nexport type CompactionStreamEventName =\n  | typeof COMPACTION_STARTED_EVENT\n  | typeof COMPACTION_STATE_EVENT\n  | typeof COMPACTION_ENDED_EVENT\n\nconst PREVIEW_CHARS = 4000\nconst MAX_PREVIEWS = 24\n\n/** One message in a `compaction:state` preview list. */\nexport interface CompactionMessagePreview {\n  role: string\n  tokens: number\n  text: string\n}\n\n/** Payload of {@link COMPACTION_STARTED_EVENT}. */\nexport interface CompactionStartedEventValue {\n  before: number\n  messagesBefore: number\n  reusedCheckpoint: boolean\n  maxTokens: number\n  strategyKey?: string\n}\n\n/** Payload of {@link COMPACTION_STATE_EVENT}. */\nexport interface CompactionStateEventValue {\n  before: number\n  after: number\n  messagesBefore: number\n  messagesAfter: number\n  reusedCheckpoint: boolean\n  maxTokens: number\n  strategyKey?: string\n  /** Messages removed or rewritten. */\n  dropped?: Array<CompactionMessagePreview>\n  /** Messages the model will see after compaction. */\n  result?: Array<CompactionMessagePreview>\n}\n\n/** Payload of {@link COMPACTION_ENDED_EVENT}. */\nexport interface CompactionEndedEventValue {\n  after: number\n  messagesAfter: number\n  reusedCheckpoint: boolean\n  maxTokens: number\n  durationMs: number\n  strategyKey?: string\n}\n\nfunction emitCompactionStarted(\n  ctx: ChatMiddlewareContext,\n  value: CompactionStartedEventValue,\n) {\n  ctx.emitCustomEvent(COMPACTION_STARTED_EVENT, value)\n}\n\nfunction emitCompactionState(\n  ctx: ChatMiddlewareContext,\n  value: CompactionStateEventValue,\n) {\n  ctx.emitCustomEvent(COMPACTION_STATE_EVENT, value)\n}\n\nfunction emitCompactionEnded(\n  ctx: ChatMiddlewareContext,\n  value: CompactionEndedEventValue,\n) {\n  ctx.emitCustomEvent(COMPACTION_ENDED_EVENT, value)\n}\n\nconst strategyKeys = new WeakMap<CompactionStrategy, string>()\nconst CHECKPOINT_NAMESPACE = '@tanstack/ai-compaction'\n\ninterface CompactionCheckpoint {\n  schemaVersion: 1\n  sourceMessageCount: number\n  sourceHash: string\n  strategyKey: string\n  compactedMessages: Array<ModelMessage>\n}\n\nfunction identifyStrategy(\n  strategy: CompactionStrategy,\n  key: string | undefined,\n): CompactionStrategy {\n  if (key) strategyKeys.set(strategy, key)\n  return strategy\n}\n\nasync function hashMessages(\n  messages: ReadonlyArray<ModelMessage>,\n): Promise<string> {\n  const bytes = new TextEncoder().encode(JSON.stringify(messages))\n  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes)\n  return Array.from(new Uint8Array(digest), (byte) =>\n    byte.toString(16).padStart(2, '0'),\n  ).join('')\n}\n\nfunction isModelMessage(value: unknown): value is ModelMessage {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    'role' in value &&\n    (value.role === 'user' ||\n      value.role === 'assistant' ||\n      value.role === 'tool') &&\n    'content' in value\n  )\n}\n\nfunction isCompactionCheckpoint(value: unknown): value is CompactionCheckpoint {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    'schemaVersion' in value &&\n    value.schemaVersion === 1 &&\n    'sourceMessageCount' in value &&\n    typeof value.sourceMessageCount === 'number' &&\n    Number.isInteger(value.sourceMessageCount) &&\n    value.sourceMessageCount >= 0 &&\n    'sourceHash' in value &&\n    typeof value.sourceHash === 'string' &&\n    'strategyKey' in value &&\n    typeof value.strategyKey === 'string' &&\n    'compactedMessages' in value &&\n    Array.isArray(value.compactedMessages) &&\n    value.compactedMessages.every(isModelMessage)\n  )\n}\n\nfunction messagePreviewText(message: ModelMessage): string {\n  if (typeof message.content === 'string') return message.content\n  return JSON.stringify(message.content ?? '')\n}\n\nfunction toMessagePreview(\n  message: ModelMessage,\n  estimate: (message: ModelMessage) => number,\n): CompactionMessagePreview {\n  const text = messagePreviewText(message)\n  return {\n    role: message.role,\n    tokens: estimate(message),\n    text:\n      text.length > PREVIEW_CHARS ? `${text.slice(0, PREVIEW_CHARS)}…` : text,\n  }\n}\n\nfunction previewList(\n  messages: ReadonlyArray<ModelMessage>,\n  estimate: (message: ModelMessage) => number,\n): Array<CompactionMessagePreview> {\n  const mapped = messages.map((message) => toMessagePreview(message, estimate))\n  if (mapped.length <= MAX_PREVIEWS) return mapped\n  return mapped.slice(0, MAX_PREVIEWS)\n}\n\nfunction droppedMessages(\n  before: ReadonlyArray<ModelMessage>,\n  after: ReadonlyArray<ModelMessage>,\n): Array<ModelMessage> {\n  const afterKeys = new Set(after.map((message) => JSON.stringify(message)))\n  return before.filter((message) => !afterKeys.has(JSON.stringify(message)))\n}\n\nfunction compactionStateValue(args: {\n  before: number\n  after: number\n  messagesBefore: number\n  messagesAfter: number\n  reusedCheckpoint: boolean\n  maxTokens: number\n  strategyKey?: string\n  beforeMessages?: ReadonlyArray<ModelMessage>\n  afterMessages?: ReadonlyArray<ModelMessage>\n  estimate: (message: ModelMessage) => number\n}): CompactionStateEventValue {\n  const value: CompactionStateEventValue = {\n    before: args.before,\n    after: args.after,\n    messagesBefore: args.messagesBefore,\n    messagesAfter: args.messagesAfter,\n    reusedCheckpoint: args.reusedCheckpoint,\n    maxTokens: args.maxTokens,\n    ...(args.strategyKey ? { strategyKey: args.strategyKey } : {}),\n  }\n  if (args.afterMessages) {\n    value.result = previewList(args.afterMessages, args.estimate)\n  }\n  if (args.beforeMessages && args.afterMessages) {\n    value.dropped = previewList(\n      droppedMessages(args.beforeMessages, args.afterMessages),\n      args.estimate,\n    )\n  }\n  return value\n}\n\n/** Rough token estimate for one message. Default: characters / 4. */\nexport function estimateMessageTokens(message: ModelMessage): number {\n  let text = messagePreviewText(message)\n  if (message.toolCalls?.length) text += JSON.stringify(message.toolCalls)\n  return Math.ceil(text.length / 4)\n}\n\n/** What a {@link CompactionStrategy} receives alongside the messages. */\nexport interface CompactionContext {\n  /** The `maxTokens` budget from `withCompaction`. */\n  maxTokens: number\n  /** The shared token estimator (default {@link estimateMessageTokens}). */\n  estimate: (message: ModelMessage) => number\n}\n\n/**\n * Shrinks a message list. Called only when the estimate is over budget.\n * Return the rewritten messages, or `null` to leave them unchanged.\n */\nexport type CompactionStrategy = (\n  messages: ReadonlyArray<ModelMessage>,\n  ctx: CompactionContext,\n) => Array<ModelMessage> | null | Promise<Array<ModelMessage> | null>\n\n/** Reported to `onCompact` after each compaction event. */\nexport interface CompactionInfo {\n  /** Estimated tokens before compaction. */\n  before: number\n  /** Estimated tokens after compaction. */\n  after: number\n  /** Message count before compaction. */\n  messagesBefore: number\n  /** Message count after compaction (unchanged for {@link clearToolResults}). */\n  messagesAfter: number\n}\n\nexport interface CompactionOptions {\n  /** Compact when estimated tokens across `messages` exceed this. */\n  maxTokens: number\n  /** How to shrink the messages. Default: {@link evictOldest}. */\n  strategy?: CompactionStrategy\n  /** Per-message token estimator. Default: {@link estimateMessageTokens}. */\n  estimateTokens?: (message: ModelMessage) => number\n  /**\n   * Stable identity for persisted checkpoints. Set this for custom strategies\n   * or estimators, and change it when their output can change.\n   */\n  strategyKey?: string\n  /** Observe each compaction (logging, metrics). */\n  onCompact?: (info: CompactionInfo) => void\n}\n\nconst sum = (\n  messages: ReadonlyArray<ModelMessage>,\n  estimate: (m: ModelMessage) => number,\n) => messages.reduce((total, m) => total + estimate(m), 0)\n\n/**\n * Find the split point that keeps the most recent messages up to\n * `keepRecentTokens`, then moves the cut forward past any leading tool result\n * so the kept tail never starts with an orphan (its tool call would be dropped).\n * Returns the index where the tail begins (head is `messages[0..cut)`).\n */\nfunction splitAtRecent(\n  messages: ReadonlyArray<ModelMessage>,\n  estimate: (m: ModelMessage) => number,\n  keepRecentTokens: number,\n): number {\n  let kept = 0\n  let cut = messages.length\n  while (cut > 0) {\n    const prev = messages[cut - 1]\n    if (!prev) break\n    const size = estimate(prev)\n    if (kept + size > keepRecentTokens) break\n    kept += size\n    cut--\n  }\n  // Always keep at least the last message.\n  if (cut >= messages.length) cut = messages.length - 1\n  while (cut < messages.length && messages[cut]?.role === 'tool') cut++\n  // Trailing tool results: skipping orphans would drop the whole tail (the\n  // normal agent-loop state). Keep those results and the message that owns them.\n  if (cut >= messages.length) {\n    cut = messages.length\n    while (cut > 0 && messages[cut - 1]?.role === 'tool') cut--\n    if (cut > 0) cut--\n  }\n  return cut\n}\n\n/**\n * Drop the oldest messages and replace them with a short marker. Cheapest\n * strategy — no extra model call. This is the default.\n */\nexport function evictOldest(\n  options: {\n    /** Tokens of recent messages to keep verbatim. Default `floor(maxTokens/2)`. */\n    keepRecentTokens?: number\n    /** Build the marker that replaces the dropped head. */\n    marker?: (droppedCount: number) => string\n  } = {},\n): CompactionStrategy {\n  const strategy: CompactionStrategy = (messages, ctx) => {\n    const keep = options.keepRecentTokens ?? Math.floor(ctx.maxTokens / 2)\n    const cut = splitAtRecent(messages, ctx.estimate, keep)\n    // Can't shrink past the recent window; raise keepRecentTokens or lower\n    // maxTokens if compaction never fires.\n    if (cut <= 0) return null\n    const marker =\n      options.marker?.(cut) ??\n      `[${cut} earlier message(s) omitted to save context.]`\n    return [{ role: 'user', content: marker }, ...messages.slice(cut)]\n  }\n  return identifyStrategy(\n    strategy,\n    options.marker\n      ? undefined\n      : `evict-oldest:${options.keepRecentTokens ?? 'half'}`,\n  )\n}\n\n/**\n * Drop the oldest messages and replace them with an LLM summary. Keeps the gist\n * of old turns at the cost of one summarization call. Wire `summarize` to\n * `summarize()` or any model call.\n */\nexport function summarizeOldest(options: {\n  summarize: (messages: Array<ModelMessage>) => Promise<string>\n  /** Tokens of recent messages to keep verbatim. Default `floor(maxTokens/2)`. */\n  keepRecentTokens?: number\n  /** Role of the injected summary message. Default `'assistant'`. */\n  summaryRole?: 'user' | 'assistant'\n}): CompactionStrategy {\n  const strategy: CompactionStrategy = async (messages, ctx) => {\n    const keep = options.keepRecentTokens ?? Math.floor(ctx.maxTokens / 2)\n    const cut = splitAtRecent(messages, ctx.estimate, keep)\n    if (cut <= 0) return null\n    const summary = await options.summarize(messages.slice(0, cut))\n    return [\n      {\n        role: options.summaryRole ?? 'assistant',\n        content: `<untrusted-conversation-summary>\\n${summary}\\n</untrusted-conversation-summary>`,\n      },\n      ...messages.slice(cut),\n    ]\n  }\n  return identifyStrategy(\n    strategy,\n    `summarize-oldest:${options.keepRecentTokens ?? 'half'}:${options.summaryRole ?? 'assistant'}`,\n  )\n}\n\n/**\n * Replace the content of old tool-result messages with a stub, keeping every\n * message and its tool-call pairing in place. Best for agent loops where tool\n * output (file reads, command output) dominates the token count — it clears the\n * bulk without disturbing the conversation shape. No extra model call.\n */\nexport function clearToolResults(\n  options: {\n    /** Number of most-recent tool results to keep verbatim. Default `3`. */\n    keepRecentToolResults?: number\n    /** Text that replaces a cleared tool result. */\n    stub?: string\n  } = {},\n): CompactionStrategy {\n  const keepN = options.keepRecentToolResults ?? 3\n  const stub = options.stub ?? '[tool output cleared to save context]'\n  const strategy: CompactionStrategy = (messages) => {\n    const toolIndexes: Array<number> = []\n    messages.forEach((m, i) => {\n      if (m.role === 'tool') toolIndexes.push(i)\n    })\n    if (toolIndexes.length <= keepN) return null\n    const clearBefore = toolIndexes[toolIndexes.length - keepN] ?? 0\n    let changed = false\n    const next = messages.map((m, i) => {\n      if (m.role === 'tool' && i < clearBefore && m.content !== stub) {\n        changed = true\n        return { ...m, content: stub }\n      }\n      return m\n    })\n    return changed ? next : null\n  }\n  return identifyStrategy(strategy, `clear-tool-results:${keepN}:${stub}`)\n}\n\n/**\n * Run several strategies in order, escalating: stop as soon as the running\n * estimate is back under `maxTokens`. Put the cheap, targeted strategy first\n * (for example {@link clearToolResults}) and a broad fallback last (for example\n * {@link evictOldest}) — the fallback only runs when clearing was not enough.\n * A strategy that returns `null` (no change) is skipped and the next one runs.\n *\n * @example\n * ```ts\n * withCompaction({\n *   maxTokens: 100_000,\n *   strategy: composeStrategies(clearToolResults(), evictOldest()),\n * })\n * ```\n */\nexport function composeStrategies(\n  ...strategies: Array<CompactionStrategy>\n): CompactionStrategy {\n  const strategy: CompactionStrategy = async (messages, ctx) => {\n    let current: ReadonlyArray<ModelMessage> = messages\n    let result: Array<ModelMessage> | null = null\n    for (const itemStrategy of strategies) {\n      if (sum(current, ctx.estimate) <= ctx.maxTokens) break\n      const out = await itemStrategy(current, ctx)\n      if (out) {\n        current = out\n        result = out\n      }\n    }\n    return result\n  }\n  const keys = strategies.map((item) => strategyKeys.get(item))\n  return identifyStrategy(\n    strategy,\n    keys.every((key) => key !== undefined) ? keys.join('|') : undefined,\n  )\n}\n\n/**\n * Context-compaction middleware. Add to `chat({ middleware: [...] })`.\n *\n * @example\n * ```ts\n * chat({\n *   adapter,\n *   messages,\n *   middleware: [withCompaction({ maxTokens: 100_000 })], // evictOldest by default\n * })\n * ```\n */\nexport function withCompaction(options: CompactionOptions): ChatMiddleware {\n  const estimate = options.estimateTokens ?? estimateMessageTokens\n  const strategy = options.strategy ?? evictOldest()\n  const strategyKey =\n    options.strategyKey ??\n    (options.estimateTokens ? undefined : strategyKeys.get(strategy))\n  const checkpointStrategyKey = strategyKey\n    ? `${strategyKey}:maxTokens=${options.maxTokens}`\n    : undefined\n\n  return {\n    name: 'compaction',\n    optionalRequires: [MetadataCapability],\n    async onConfig(ctx, config) {\n      // init is discarded by the engine rebuild and can run before persistence\n      // hydrates the thread. Compact only on model-bound phases.\n      if (ctx.phase === 'init') return\n\n      const startedAt = Date.now()\n      const { messages } = config\n      const inputMessages = config.providerMessages ?? messages\n      const metadata = getMetadata(ctx, { optional: true })\n      let workingMessages = inputMessages\n      let reusedCheckpoint = false\n\n      if (metadata && checkpointStrategyKey && inputMessages === messages) {\n        const stored = await metadata.get(CHECKPOINT_NAMESPACE, ctx.threadId)\n        if (\n          isCompactionCheckpoint(stored) &&\n          stored.strategyKey === checkpointStrategyKey &&\n          stored.sourceMessageCount <= messages.length &&\n          stored.sourceHash ===\n            (await hashMessages(messages.slice(0, stored.sourceMessageCount)))\n        ) {\n          workingMessages = [\n            ...stored.compactedMessages,\n            ...messages.slice(stored.sourceMessageCount),\n          ]\n          reusedCheckpoint = true\n        }\n      }\n\n      const before = sum(workingMessages, estimate)\n      const startedValue: CompactionStartedEventValue = {\n        before,\n        messagesBefore: workingMessages.length,\n        reusedCheckpoint,\n        maxTokens: options.maxTokens,\n        ...(checkpointStrategyKey\n          ? { strategyKey: checkpointStrategyKey }\n          : {}),\n      }\n\n      if (before <= options.maxTokens) {\n        if (reusedCheckpoint) {\n          emitCompactionStarted(ctx, startedValue)\n          const stateValue = compactionStateValue({\n            before,\n            after: before,\n            messagesBefore: workingMessages.length,\n            messagesAfter: workingMessages.length,\n            reusedCheckpoint: true,\n            maxTokens: options.maxTokens,\n            strategyKey: checkpointStrategyKey,\n            afterMessages: workingMessages,\n            estimate,\n          })\n          emitCompactionState(ctx, stateValue)\n          emitCompactionEnded(ctx, {\n            after: before,\n            messagesAfter: workingMessages.length,\n            reusedCheckpoint: true,\n            maxTokens: options.maxTokens,\n            durationMs: Date.now() - startedAt,\n            ...(checkpointStrategyKey\n              ? { strategyKey: checkpointStrategyKey }\n              : {}),\n          })\n          return { providerMessages: workingMessages }\n        }\n        return\n      }\n\n      emitCompactionStarted(ctx, startedValue)\n      const next = await strategy(workingMessages, {\n        maxTokens: options.maxTokens,\n        estimate,\n      })\n      if (!next || next === workingMessages) {\n        emitCompactionEnded(ctx, {\n          after: before,\n          messagesAfter: workingMessages.length,\n          reusedCheckpoint,\n          maxTokens: options.maxTokens,\n          durationMs: Date.now() - startedAt,\n          ...(checkpointStrategyKey\n            ? { strategyKey: checkpointStrategyKey }\n            : {}),\n        })\n        if (reusedCheckpoint) {\n          return { providerMessages: workingMessages }\n        }\n        return\n      }\n\n      const info = {\n        before,\n        after: sum(next, estimate),\n        messagesBefore: workingMessages.length,\n        messagesAfter: next.length,\n      }\n      options.onCompact?.(info)\n      emitCompactionState(\n        ctx,\n        compactionStateValue({\n          ...info,\n          reusedCheckpoint,\n          maxTokens: options.maxTokens,\n          strategyKey: checkpointStrategyKey,\n          beforeMessages: workingMessages,\n          afterMessages: next,\n          estimate,\n        }),\n      )\n      emitCompactionEnded(ctx, {\n        after: info.after,\n        messagesAfter: info.messagesAfter,\n        reusedCheckpoint,\n        maxTokens: options.maxTokens,\n        durationMs: Date.now() - startedAt,\n        ...(checkpointStrategyKey\n          ? { strategyKey: checkpointStrategyKey }\n          : {}),\n      })\n\n      if (metadata && checkpointStrategyKey && inputMessages === messages) {\n        const checkpoint: CompactionCheckpoint = {\n          schemaVersion: 1,\n          sourceMessageCount: messages.length,\n          sourceHash: await hashMessages(messages),\n          strategyKey: checkpointStrategyKey,\n          compactedMessages: next,\n        }\n        if (!ctx.signal?.aborted) {\n          await metadata.set(CHECKPOINT_NAMESPACE, ctx.threadId, checkpoint)\n        }\n      }\n\n      return { providerMessages: next }\n    },\n  }\n}\n"],"mappings":"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"}

package/dist/esm/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,10 +1,50 @@
-{
-    "description":  "OIDC trusted publishing setup package for @tanstack/ai-compaction",
-    "name":  "@tanstack/ai-compaction",
-    "version":  "0.0.0",
-    "keywords":  [
-                     "oidc",
-                     "trusted-publishing",
-                     "setup"
-                 ]
-}
+{
+  "name": "@tanstack/ai-compaction",
+  "version": "0.1.1",
+  "description": "Context-window compaction middleware for TanStack AI chat()",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-compaction"
+  },
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "ai",
+    "tanstack",
+    "compaction",
+    "context",
+    "middleware"
+  ],
+  "peerDependencies": {
+    "@tanstack/ai": "^0.53.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "4.1.10",
+    "@tanstack/ai": "0.53.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "oxlint src --type-aware --fix",
+    "test:build": "publint --strict",
+    "test:oxlint": "oxlint src --type-aware",
+    "test:lib": "vitest --passWithNoTests",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,543 @@
+import { describe, expect, it, vi } from 'vitest'
+import type {
+  ChatMiddlewareConfig,
+  ChatMiddlewareContext,
+  MetadataStore,
+  ModelMessage,
+  ToolCall,
+} from '@tanstack/ai'
+import { provideMetadata } from '@tanstack/ai'
+import {
+  COMPACTION_ENDED_EVENT,
+  COMPACTION_STARTED_EVENT,
+  COMPACTION_STATE_EVENT,
+  clearToolResults,
+  composeStrategies,
+  estimateMessageTokens,
+  evictOldest,
+  summarizeOldest,
+  withCompaction,
+} from './index'
+
+interface RecordedCustom {
+  name: string
+  value: Record<string, unknown>
+}
+
+function recordingContext(
+  phase: ChatMiddlewareContext['phase'] = 'beforeModel',
+  extras: Partial<ChatMiddlewareContext> = {},
+): { ctx: ChatMiddlewareContext; events: Array<RecordedCustom> } {
+  const events: Array<RecordedCustom> = []
+  // oxlint-disable-next-line eslint-js/no-restricted-syntax -- focused hook stub
+  const ctx = {
+    phase,
+    emitCustomEvent: (name: string, value: Record<string, unknown>) => {
+      events.push({ name, value })
+    },
+    ...extras,
+  } as unknown as ChatMiddlewareContext
+  return { ctx, events }
+}
+
+function runOnConfig(
+  mw: ReturnType<typeof withCompaction>,
+  messages: Array<ModelMessage>,
+  ctx: ChatMiddlewareContext = recordingContext().ctx,
+) {
+  const config: ChatMiddlewareConfig = {
+    messages,
+    systemPrompts: [],
+    tools: [],
+  }
+  return mw.onConfig?.(ctx, config)
+}
+
+function checkpointContext(
+  store: MetadataStore,
+  options: { aborted?: boolean; phase?: ChatMiddlewareContext['phase'] } = {},
+): ChatMiddlewareContext {
+  const recorded = recordingContext(options.phase)
+  // oxlint-disable-next-line eslint-js/no-restricted-syntax -- focused hook stub
+  const ctx = {
+    ...recorded.ctx,
+    threadId: 'thread-1',
+    signal: options.aborted ? AbortSignal.abort() : undefined,
+    capabilities: { markProvided: () => undefined },
+  } as unknown as ChatMiddlewareContext
+  provideMetadata(ctx, store)
+  return ctx
+}
+
+function memoryStore(): MetadataStore {
+  const values = new Map<string, unknown>()
+  return {
+    get: async (namespace, key) => values.get(`${namespace}:${key}`) ?? null,
+    set: async (namespace, key, value) => {
+      values.set(`${namespace}:${key}`, value)
+    },
+    delete: async (namespace, key) => {
+      values.delete(`${namespace}:${key}`)
+    },
+  }
+}
+
+function phaseContext(
+  phase: ChatMiddlewareContext['phase'],
+): ChatMiddlewareContext {
+  return recordingContext(phase).ctx
+}
+
+const text = (role: ModelMessage['role'], content: string): ModelMessage => ({
+  role,
+  content,
+})
+// ~40 tokens each at chars/4.
+const big = (role: ModelMessage['role']) => text(role, 'x'.repeat(160))
+
+const call: ToolCall = {
+  id: 't1',
+  type: 'function',
+  function: { name: 'f', arguments: '{}' },
+}
+
+describe('withCompaction', () => {
+  it('passes through when under the token budget', async () => {
+    const mw = withCompaction({ maxTokens: 1000 })
+    const result = await runOnConfig(mw, [
+      text('user', 'hi'),
+      text('assistant', 'hello'),
+    ])
+    expect(result).toBeUndefined()
+  })
+
+  it('defaults to evictOldest', async () => {
+    const mw = withCompaction({ maxTokens: 100 })
+    const msgs = [big('user'), big('assistant'), big('user'), big('assistant')]
+    const result = await runOnConfig(mw, msgs)
+    const out = result?.providerMessages ?? []
+    expect(out[0]?.content).toContain('omitted')
+    expect(out[out.length - 1]).toBe(msgs[msgs.length - 1])
+  })
+
+  it('reports before/after token and message counts via onCompact', async () => {
+    const onCompact = vi.fn()
+    const mw = withCompaction({ maxTokens: 100, onCompact })
+    await runOnConfig(mw, [
+      big('user'),
+      big('assistant'),
+      big('user'),
+      big('assistant'),
+    ])
+    expect(onCompact).toHaveBeenCalledOnce()
+    const info = onCompact.mock.calls[0]?.[0]
+    expect(info.after).toBeLessThan(info.before)
+    expect(info.messagesAfter).toBeLessThan(info.messagesBefore)
+  })
+
+  it('emits started, state, and ended custom events when compacting', async () => {
+    const mw = withCompaction({ maxTokens: 100 })
+    const { ctx, events } = recordingContext('beforeModel')
+    const msgs = [big('user'), big('assistant'), big('user'), big('assistant')]
+    await runOnConfig(mw, msgs, ctx)
+    expect(events.map((event) => event.name)).toEqual([
+      COMPACTION_STARTED_EVENT,
+      COMPACTION_STATE_EVENT,
+      COMPACTION_ENDED_EVENT,
+    ])
+    const stateValue = events[1]?.value
+    expect(stateValue).toMatchObject({
+      reusedCheckpoint: false,
+      maxTokens: 100,
+    })
+    expect(Array.isArray(stateValue?.dropped)).toBe(true)
+    expect(Array.isArray(stateValue?.result)).toBe(true)
+    expect(
+      Array.isArray(stateValue?.dropped) ? stateValue.dropped.length : 0,
+    ).toBeGreaterThan(0)
+    expect(typeof events[2]?.value.durationMs).toBe('number')
+  })
+
+  it('emits started before summarizeOldest finishes', async () => {
+    let release!: (summary: string) => void
+    const gate = new Promise<string>((resolve) => {
+      release = resolve
+    })
+    const mw = withCompaction({
+      maxTokens: 100,
+      strategy: summarizeOldest({ summarize: () => gate }),
+    })
+    const { ctx, events } = recordingContext('beforeModel')
+    const pending = runOnConfig(
+      mw,
+      [big('user'), big('assistant'), big('user'), big('assistant')],
+      ctx,
+    )
+    await vi.waitFor(() => {
+      expect(events.map((event) => event.name)).toEqual([
+        COMPACTION_STARTED_EVENT,
+      ])
+    })
+    release('the gist')
+    await pending
+    expect(events.map((event) => event.name)).toEqual([
+      COMPACTION_STARTED_EVENT,
+      COMPACTION_STATE_EVENT,
+      COMPACTION_ENDED_EVENT,
+    ])
+  })
+
+  it('does not emit custom events when under the token budget', async () => {
+    const mw = withCompaction({ maxTokens: 1000 })
+    const { ctx, events } = recordingContext('beforeModel')
+    await runOnConfig(mw, [text('user', 'hi')], ctx)
+    expect(events).toEqual([])
+  })
+
+  it('does not compact during init', async () => {
+    const onCompact = vi.fn()
+    const mw = withCompaction({ maxTokens: 100, onCompact })
+    const result = await runOnConfig(
+      mw,
+      [big('user'), big('assistant'), big('user'), big('assistant')],
+      phaseContext('init'),
+    )
+    expect(result).toBeUndefined()
+    expect(onCompact).not.toHaveBeenCalled()
+  })
+
+  it('runs summarize once per beforeModel call with no metadata store', async () => {
+    const summarize = vi.fn(async () => 'the gist')
+    const onCompact = vi.fn()
+    const mw = withCompaction({
+      maxTokens: 100,
+      strategy: summarizeOldest({ summarize, keepRecentTokens: 50 }),
+      onCompact,
+    })
+    const msgs = [big('user'), big('assistant'), big('user'), big('assistant')]
+
+    await runOnConfig(mw, msgs, phaseContext('init'))
+    await runOnConfig(mw, msgs, phaseContext('beforeModel'))
+
+    expect(summarize).toHaveBeenCalledOnce()
+    expect(onCompact).toHaveBeenCalledOnce()
+  })
+
+  it('reuses a persisted checkpoint for an unchanged canonical prefix', async () => {
+    const store = memoryStore()
+    const summarize = vi.fn(async () => 'the gist')
+    const messages = [
+      big('user'),
+      big('assistant'),
+      big('user'),
+      big('assistant'),
+    ]
+    const options = {
+      maxTokens: 100,
+      strategy: summarizeOldest({ summarize, keepRecentTokens: 50 }),
+      strategyKey: 'summary-v1',
+    }
+
+    const first = await runOnConfig(
+      withCompaction(options),
+      messages,
+      checkpointContext(store),
+    )
+    const appended = [...messages, text('user', 'new')]
+    const second = await runOnConfig(
+      withCompaction(options),
+      appended,
+      checkpointContext(store),
+    )
+
+    expect(summarize).toHaveBeenCalledOnce()
+    expect(first?.providerMessages?.[0]?.content).toContain('the gist')
+    expect(second?.providerMessages?.[0]?.content).toContain('the gist')
+    expect(second?.providerMessages?.at(-1)?.content).toBe('new')
+    expect(appended).toHaveLength(5)
+  })
+
+  it('rejects a checkpoint when the canonical prefix changes', async () => {
+    const store = memoryStore()
+    const summarize = vi.fn(async () => 'the gist')
+    const options = {
+      maxTokens: 100,
+      strategy: summarizeOldest({ summarize, keepRecentTokens: 50 }),
+      strategyKey: 'summary-v1',
+    }
+    const messages = [
+      big('user'),
+      big('assistant'),
+      big('user'),
+      big('assistant'),
+    ]
+
+    await runOnConfig(
+      withCompaction(options),
+      messages,
+      checkpointContext(store),
+    )
+    await runOnConfig(
+      withCompaction(options),
+      [text('user', 'changed'.repeat(30)), ...messages.slice(1)],
+      checkpointContext(store),
+    )
+
+    expect(summarize).toHaveBeenCalledTimes(2)
+  })
+
+  it('does not write a checkpoint after cancellation', async () => {
+    const set = vi.fn<MetadataStore['set']>()
+    const store: MetadataStore = {
+      get: async () => null,
+      set,
+      delete: async () => undefined,
+    }
+
+    await runOnConfig(
+      withCompaction({ maxTokens: 100 }),
+      [big('user'), big('assistant'), big('user'), big('assistant')],
+      checkpointContext(store, { aborted: true }),
+    )
+
+    expect(set).not.toHaveBeenCalled()
+  })
+})
+
+describe('evictOldest', () => {
+  it('keeps the recent tail and drops the head', async () => {
+    const mw = withCompaction({
+      maxTokens: 100,
+      strategy: evictOldest({ keepRecentTokens: 50 }),
+    })
+    const msgs = [big('user'), big('assistant'), big('user'), big('assistant')]
+    const out = (await runOnConfig(mw, msgs))?.providerMessages ?? []
+    expect(out[0]?.content).toContain('omitted')
+    expect(out[out.length - 1]).toBe(msgs[msgs.length - 1])
+  })
+
+  it('never lets the tail start with an orphaned tool result', async () => {
+    const assistantCall: ModelMessage = {
+      role: 'assistant',
+      content: 'x'.repeat(160),
+      toolCalls: [call],
+    }
+    const toolResult: ModelMessage = {
+      role: 'tool',
+      content: 'x'.repeat(160),
+      toolCallId: 't1',
+    }
+    const msgs = [big('user'), assistantCall, toolResult, big('user')]
+    const mw = withCompaction({
+      maxTokens: 100,
+      strategy: evictOldest({ keepRecentTokens: 45 }),
+    })
+    const out = (await runOnConfig(mw, msgs))?.providerMessages ?? []
+    expect(out.slice(1).some((m) => m.role === 'tool')).toBe(false)
+  })
+
+  it('keeps the trailing assistant plus tool result when the transcript ends in a tool', async () => {
+    const assistantCall: ModelMessage = {
+      role: 'assistant',
+      content: 'x'.repeat(160),
+      toolCalls: [call],
+    }
+    const toolResult: ModelMessage = {
+      role: 'tool',
+      content: 'x'.repeat(160),
+      toolCallId: 't1',
+    }
+    const msgs = [big('user'), assistantCall, toolResult]
+    const mw = withCompaction({
+      maxTokens: 100,
+      strategy: evictOldest({ keepRecentTokens: 45 }),
+    })
+    const out = (await runOnConfig(mw, msgs))?.providerMessages ?? []
+    expect(out.at(-2)).toBe(assistantCall)
+    expect(out.at(-1)).toBe(toolResult)
+    expect(out.some((m) => m.role === 'tool')).toBe(true)
+  })
+
+  it('keeps a trailing parallel tool-result group with its assistant', async () => {
+    const assistantCall: ModelMessage = {
+      role: 'assistant',
+      content: 'x'.repeat(160),
+      toolCalls: [
+        call,
+        {
+          id: 't2',
+          type: 'function',
+          function: { name: 'g', arguments: '{}' },
+        },
+      ],
+    }
+    const toolA: ModelMessage = {
+      role: 'tool',
+      content: 'x'.repeat(160),
+      toolCallId: 't1',
+    }
+    const toolB: ModelMessage = {
+      role: 'tool',
+      content: 'x'.repeat(160),
+      toolCallId: 't2',
+    }
+    const msgs = [big('user'), assistantCall, toolA, toolB]
+    const mw = withCompaction({
+      maxTokens: 100,
+      strategy: evictOldest({ keepRecentTokens: 45 }),
+    })
+    const out = (await runOnConfig(mw, msgs))?.providerMessages ?? []
+    expect(out.slice(-3)).toEqual([assistantCall, toolA, toolB])
+  })
+})
+
+describe('summarizeOldest', () => {
+  it('replaces the head with a summary', async () => {
+    const summarize = vi.fn(async () => 'the gist')
+    const mw = withCompaction({
+      maxTokens: 100,
+      strategy: summarizeOldest({ summarize, keepRecentTokens: 50 }),
+    })
+    const result = await runOnConfig(mw, [
+      big('user'),
+      big('assistant'),
+      big('user'),
+      big('assistant'),
+    ])
+    expect(summarize).toHaveBeenCalledOnce()
+    expect(result?.providerMessages?.[0]?.role).toBe('assistant')
+    expect(result?.providerMessages?.[0]?.content).toBe(
+      '<untrusted-conversation-summary>\nthe gist\n</untrusted-conversation-summary>',
+    )
+  })
+
+  it('reuses a checkpoint without an explicit strategyKey', async () => {
+    const store = memoryStore()
+    const summarize = vi.fn(async () => 'the gist')
+    const messages = [
+      big('user'),
+      big('assistant'),
+      big('user'),
+      big('assistant'),
+    ]
+    const options = {
+      maxTokens: 100,
+      strategy: summarizeOldest({ summarize, keepRecentTokens: 50 }),
+    }
+
+    await runOnConfig(
+      withCompaction(options),
+      messages,
+      checkpointContext(store),
+    )
+    const second = await runOnConfig(
+      withCompaction(options),
+      [...messages, text('user', 'new')],
+      checkpointContext(store),
+    )
+
+    expect(summarize).toHaveBeenCalledOnce()
+    expect(second?.providerMessages?.at(-1)?.content).toBe('new')
+  })
+})
+
+describe('clearToolResults', () => {
+  const toolMsg = (id: string): ModelMessage => ({
+    role: 'tool',
+    content: 'x'.repeat(400),
+    toolCallId: id,
+  })
+
+  it('stubs old tool results but keeps recent ones and message count', async () => {
+    const msgs: Array<ModelMessage> = [
+      text('user', 'go'),
+      toolMsg('a'),
+      toolMsg('b'),
+      toolMsg('c'),
+      toolMsg('d'),
+    ]
+    const mw = withCompaction({
+      maxTokens: 100,
+      strategy: clearToolResults({ keepRecentToolResults: 2 }),
+    })
+    const out = (await runOnConfig(mw, msgs))?.providerMessages ?? []
+    // Same number of messages — structure is untouched.
+    expect(out.length).toBe(msgs.length)
+    // Oldest two tool results are stubbed.
+    expect(out[1]?.content).toBe('[tool output cleared to save context]')
+    expect(out[2]?.content).toBe('[tool output cleared to save context]')
+    // Two most recent tool results are untouched.
+    expect(out[3]?.content).toBe('x'.repeat(400))
+    expect(out[4]?.content).toBe('x'.repeat(400))
+  })
+
+  it('no-ops when there are not enough tool results to clear', async () => {
+    const msgs: Array<ModelMessage> = [big('user'), toolMsg('a'), big('user')]
+    const mw = withCompaction({
+      maxTokens: 50,
+      strategy: clearToolResults({ keepRecentToolResults: 3 }),
+    })
+    expect(await runOnConfig(mw, msgs)).toBeUndefined()
+  })
+})
+
+describe('composeStrategies', () => {
+  const assistantCall = (id: string): ModelMessage => ({
+    role: 'assistant',
+    content: '',
+    toolCalls: [
+      { id, type: 'function', function: { name: 'f', arguments: '{}' } },
+    ],
+  })
+  const toolMsg = (id: string): ModelMessage => ({
+    role: 'tool',
+    content: 'x'.repeat(800), // ~200 tokens
+    toolCallId: id,
+  })
+  const history = (): Array<ModelMessage> => [
+    text('user', 'HEAD_MARKER'),
+    assistantCall('a'),
+    toolMsg('a'),
+    assistantCall('b'),
+    toolMsg('b'),
+    text('user', 'last'),
+  ]
+
+  it('stops after the first strategy once back under budget', async () => {
+    const mw = withCompaction({
+      maxTokens: 260,
+      strategy: composeStrategies(
+        clearToolResults({ keepRecentToolResults: 1 }),
+        evictOldest({ keepRecentTokens: 50 }),
+      ),
+    })
+    const msgs = history()
+    const out = (await runOnConfig(mw, msgs))?.providerMessages ?? []
+    // Clearing one tool result was enough, so evict never ran:
+    // the head message and full message count survive.
+    expect(out.length).toBe(msgs.length)
+    expect(out.some((m) => m.content === 'HEAD_MARKER')).toBe(true)
+    expect(out[2]?.content).toBe('[tool output cleared to save context]')
+  })
+
+  it('escalates to the next strategy when the first is not enough', async () => {
+    const mw = withCompaction({
+      maxTokens: 60,
+      strategy: composeStrategies(
+        clearToolResults({ keepRecentToolResults: 1 }),
+        evictOldest({ keepRecentTokens: 30 }),
+      ),
+    })
+    const msgs = history()
+    const out = (await runOnConfig(mw, msgs))?.providerMessages ?? []
+    // Clearing was not enough, so evict ran too: the head is dropped.
+    expect(out.some((m) => m.content === 'HEAD_MARKER')).toBe(false)
+    expect(out[0]?.content).toContain('omitted')
+  })
+})
+
+describe('estimateMessageTokens', () => {
+  it('counts content and tool calls', () => {
+    expect(estimateMessageTokens(text('user', 'x'.repeat(40)))).toBe(10)
+  })
+})