@context-chef/ai-sdk-middleware 1.0.4 → 1.0.5

package/README.md

@@ -98,6 +98,36 @@ const model = withContextChef(openai('gpt-4o'), {
 
 The middleware automatically extracts token usage from `generateText` and `streamText` responses and feeds it back to the compression engine. No manual `reportTokenUsage()` calls needed.
 
+### Compact (Mechanical Clearing)
+
+Zero-LLM-cost content clearing for thinking blocks and tool results:
+
+```typescript
+const model = withContextChef(openai('gpt-4o'), {
+  contextWindow: 128_000,
+  compact: {
+    clear: ['thinking', { target: 'tool-result', keepRecent: 5 }],
+  },
+});
+```
+
+> **Important: compact + compress interaction**
+>
+> When using `compact` together with `compress`, only clear `thinking` in compact:
+>
+> ```typescript
+> const model = withContextChef(openai('gpt-4o'), {
+>   contextWindow: 128_000,
+>   compact: { clear: ['thinking'] },                // thinking only
+>   compress: { model: openai('gpt-4o-mini') },
+> });
+> ```
+>
+> Clearing `tool-result` before compression causes the compression model to receive
+> empty placeholders instead of actual tool outputs, producing low-quality summaries.
+> Compression's turn-based splitting already manages history length — use `compact`
+> for `tool-result` clearing only when `compress` is **not** configured.
+
 ## API
 
 ### `withContextChef(model, options)`
@@ -123,6 +153,7 @@ const wrappedModel = withContextChef(model, options);
 | `truncate.headChars` | `number` | No | Characters to preserve from start (default: `0`) |
 | `truncate.tailChars` | `number` | No | Characters to preserve from end (default: `1000`) |
 | `truncate.storage` | `VFSStorageAdapter` | No | Storage adapter to persist original content before truncation |
+| `compact` | `CompactConfig` | No | Mechanical content clearing (thinking, tool-result). When combined with `compress`, use `clear: ['thinking']` only |
 | `tokenizer` | `(msgs) => number` | No | Custom tokenizer for precise counting |
 | `onCompress` | `(summary, count) => void` | No | Hook called after compression |
 

package/dist/index.d.cts

@@ -27,6 +27,12 @@ interface CompressOptions {
 /**
  * Mechanical compaction options — zero LLM cost.
  * Runs before LLM-based compression to reduce token usage at no cost.
+ *
+ * **Important:** When using together with `compress`, only clear `thinking`.
+ * Clearing `tool-result` before compression causes the compression model to
+ * receive empty placeholders instead of actual tool outputs, producing
+ * low-quality summaries. Leave tool-result management to compression's
+ * turn-based splitting.
  */
 interface CompactConfig {
   /** Which content types to clear from history. */
@@ -60,6 +66,9 @@ interface ContextChefOptions {
   /**
    * Mechanical compaction before LLM compression.
    * Clears specified content types (tool-result, thinking) at zero LLM cost.
+   *
+   * When combined with `compress`, use `clear: ['thinking']` only.
+   * See CompactConfig for details.
    */
   compact?: CompactConfig;
   /**

package/dist/index.d.mts

@@ -27,6 +27,12 @@ interface CompressOptions {
 /**
  * Mechanical compaction options — zero LLM cost.
  * Runs before LLM-based compression to reduce token usage at no cost.
+ *
+ * **Important:** When using together with `compress`, only clear `thinking`.
+ * Clearing `tool-result` before compression causes the compression model to
+ * receive empty placeholders instead of actual tool outputs, producing
+ * low-quality summaries. Leave tool-result management to compression's
+ * turn-based splitting.
  */
 interface CompactConfig {
   /** Which content types to clear from history. */
@@ -60,6 +66,9 @@ interface ContextChefOptions {
   /**
    * Mechanical compaction before LLM compression.
    * Clears specified content types (tool-result, thinking) at zero LLM cost.
+   *
+   * When combined with `compress`, use `clear: ['thinking']` only.
+   * See CompactConfig for details.
    */
   compact?: CompactConfig;
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@context-chef/ai-sdk-middleware",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -39,7 +39,7 @@
     "url": "https://github.com/MyPrototypeWhat/context-chef/issues"
   },
   "dependencies": {
-    "@context-chef/core": "3.0.1"
+    "@context-chef/core": "3.0.2"
   },
   "peerDependencies": {
     "@ai-sdk/provider": ">=3",