feat(context)!: offload conditions decide granularity, and placeholders are typed (typescript)

strands-ts/src/context-manager/__tests__/presets.test.ts

@@ -1,6 +1,8 @@
 import { describe, it, expect } from 'vitest'
 import { resolvePreset, resolveStrategies, STRATEGY_PRESET_NAMES } from '../presets.js'
 import { ContextManager } from '../context-manager.js'
+import { Offload } from '../strategies/offload/index.js'
+import type { ContextStrategy } from '../types.js'
 
 describe('presets', () => {
   describe('resolvePreset', () => {
@@ -25,10 +27,10 @@ describe('presets', () => {
       expect(strategies[0]!.name).toBe('offload:truncate')
     })
 
-    it('overflowProtection resolves to a truncate strategy', () => {
+    it('overflowProtection resolves to a drop strategy', () => {
       const strategies = resolvePreset('overflowProtection')
       expect(strategies).toHaveLength(1)
-      expect(strategies[0]!.name).toBe('offload:truncate')
+      expect(strategies[0]!.name).toBe('offload:drop')
     })
 
     it('staleToolCleanup resolves to a drop strategy', () => {
@@ -57,7 +59,7 @@ describe('presets', () => {
       expect(result).toHaveLength(3)
       expect(result[0]!.name).toBe('offload:truncate')
       expect(result[1]!.name).toBe('custom')
-      expect(result[2]!.name).toBe('offload:truncate')
+      expect(result[2]!.name).toBe('offload:drop')
     })
 
     it('preserves order of preset expansion', () => {
@@ -72,6 +74,22 @@ describe('presets', () => {
         'Unknown strategy preset: "proactiveSummarisation"'
       )
     })
+
+    it.each([
+      ['drop', Offload.drop('toolResults')],
+      ['truncate', Offload.truncate('toolResults')],
+      ['summarize', Offload.summarize('*')],
+    ])('rejects an Offload.%s() builder without .when()', (_method, builder) => {
+      expect(() => resolveStrategies([builder as unknown as ContextStrategy])).toThrow(
+        'Offload strategies need .when() before use; call .when() with no conditions to run on every new message'
+      )
+    })
+
+    it('accepts an Offload builder once .when() is called', () => {
+      const result = resolveStrategies([Offload.drop('toolResults').when({})])
+      expect(result).toHaveLength(1)
+      expect(result[0]!.name).toBe('offload:drop')
+    })
   })
 
   describe('ContextManager.from', () => {

strands-ts/src/context-manager/__tests__/stash-integration.test.ts

@@ -113,7 +113,7 @@ describe('Offload strategies with stash', () => {
       const largeText = 'important data '.repeat(1000)
       const messages = [makeToolResultMessage(largeText)]
       await stashAll(stash, messages)
-      const strategy = Offload.truncate('toolResults')
+      const strategy = Offload.truncate('toolResults').when({})
       const context = makeContext(messages, stash)
 
       const acted = await strategy.apply(context)
@@ -133,7 +133,7 @@ describe('Offload strategies with stash', () => {
       const largeText = 'x'.repeat(20000)
       const messages = [makeToolResultMessage(largeText)]
       await stashAll(stash, messages)
-      const strategy = Offload.truncate('toolResults')
+      const strategy = Offload.truncate('toolResults').when({})
       const context = makeContext(messages, stash)
 
       await strategy.apply(context)
@@ -146,7 +146,7 @@ describe('Offload strategies with stash', () => {
     it('does not stash when no stash is configured', async () => {
       const largeText = 'x'.repeat(20000)
       const messages = [makeToolResultMessage(largeText)]
-      const strategy = Offload.truncate('toolResults')
+      const strategy = Offload.truncate('toolResults').when({})
       const context = makeContext(messages)
 
       await strategy.apply(context)
@@ -163,7 +163,7 @@ describe('Offload strategies with stash', () => {
       const largeText = 'critical information '.repeat(500)
       const messages = [makeToolResultMessage(largeText)]
       await stashAll(stash, messages)
-      const strategy = Offload.drop('toolResults')
+      const strategy = Offload.drop('toolResults').when({})
       const context = makeContext(messages, stash)
 
       const acted = await strategy.apply(context)
@@ -182,7 +182,7 @@ describe('Offload strategies with stash', () => {
       const largeText = 'x'.repeat(20000)
       const messages = [makeToolResultMessage(largeText)]
       await stashAll(stash, messages)
-      const strategy = Offload.drop('toolResults')
+      const strategy = Offload.drop('toolResults').when({})
       const context = makeContext(messages, stash)
 
       await strategy.apply(context)
@@ -210,7 +210,7 @@ describe('Offload strategies with stash', () => {
         }),
       ]
       await stashAll(stash, messages)
-      const strategy = Offload.drop('toolResults')
+      const strategy = Offload.drop('toolResults').when({})
       const context = makeContext(messages, stash)
 
       const acted = await strategy.apply(context)
@@ -245,7 +245,7 @@ describe('Offload strategies with stash', () => {
         }),
       ]
       await stashAll(stash, messages)
-      const strategy = Offload.drop('toolResults')
+      const strategy = Offload.drop('toolResults').when({})
       const context = makeContext(messages, stash)
 
       await strategy.apply(context)
@@ -371,7 +371,7 @@ describe('Offload strategies with stash', () => {
           ],
         }),
       ]
-      const strategy = Offload.truncate('toolResults')
+      const strategy = Offload.truncate('toolResults').when({})
       const context = makeContext(messages, stash)
 
       const acted = await strategy.apply(context)
@@ -401,7 +401,7 @@ describe('Offload strategies with stash', () => {
           ],
         }),
       ]
-      const strategy = Offload.truncate('toolResults')
+      const strategy = Offload.truncate('toolResults').when({})
       const context = makeContext(messages)
 
       const acted = await strategy.apply(context)

strands-ts/src/context-manager/context-manager.ts

@@ -73,7 +73,7 @@ export class ContextManager implements Plugin {
       ? resolveStrategies(config.strategies)
       : [
           Offload.truncate('toolResults', { previewTokens: TRUNCATE_PREVIEW_TOKENS }).when({
-            threshold: AUTO_TRUNCATE_THRESHOLD,
+            blockThreshold: AUTO_TRUNCATE_THRESHOLD,
           }),
           Offload.summarize('*').when({ utilization: AUTO_SUMMARIZE_UTILIZATION, preserveRecent: 4 }),
         ]
@@ -100,7 +100,7 @@ export class ContextManager implements Plugin {
       return new ContextManager({
         strategies: [
           Offload.truncate('toolResults', { previewTokens: TRUNCATE_PREVIEW_TOKENS }).when({
-            threshold: AGENTIC_TRUNCATE_THRESHOLD,
+            blockThreshold: AGENTIC_TRUNCATE_THRESHOLD,
           }),
           Offload.summarize('*').when({ utilization: 1, preserveRecent: 4 }),
         ],

strands-ts/src/context-manager/methods/truncate.ts

@@ -25,25 +25,41 @@ export interface TruncateConfig {
   preview?: 'head' | 'tail' | 'headTail'
 }
 
+/**
+ * Share of the preview budget kept from the head; the rest is kept from the tail.
+ *
+ * @internal
+ */
+export const PREVIEW_HEAD_SHARE = { head: 1, tail: 0, headTail: 0.6 } as const
+
+/**
+ * Resolves the preview token budget, defaulting to 1,000.
+ *
+ * @param config - Truncate configuration
+ * @returns The preview token budget
+ * @internal
+ */
+export function resolvePreviewTokens(config?: TruncateConfig): number {
+  return typeof config?.previewTokens === 'number' && Number.isFinite(config.previewTokens)
+    ? Math.max(0, config.previewTokens)
+    : DEFAULT_PREVIEW_TOKENS
+}
+
 /**
  * Builds a preview of the given text (head, tail, or head-tail depending on config).
  *
  * @returns The preview string with truncation metadata header, or the original text if already within budget.
  */
 export function buildPreview(fullText: string, blockCount: number, config?: TruncateConfig): string {
-  const previewTokens =
-    typeof config?.previewTokens === 'number' && Number.isFinite(config.previewTokens)
-      ? Math.max(0, config.previewTokens)
-      : DEFAULT_PREVIEW_TOKENS
-  const previewChars = previewTokens * CHARS_PER_TOKEN
+  const previewChars = resolvePreviewTokens(config) * CHARS_PER_TOKEN
   const previewMode = config?.preview ?? 'headTail'
   const totalChars = fullText.length
 
   if (totalChars <= previewChars) {
     return fullText
   }
 
-  const headShare = { head: 1, tail: 0, headTail: 0.6 }[previewMode]
+  const headShare = PREVIEW_HEAD_SHARE[previewMode]
   const headChars = Math.floor(previewChars * headShare)
   const tailChars = previewChars - headChars
   const head = fullText.slice(0, headChars)

strands-ts/src/context-manager/presets.ts

@@ -20,7 +20,7 @@ import { Offload } from './strategies/offload/index.js'
  *
  * - `'proactiveSummarization'` — batch summarize oldest messages at 70% utilization
  * - `'largeToolOffloading'` — truncate tool results over 2500 tokens to a 1000-token preview
- * - `'overflowProtection'` — truncate oldest messages when the context window is full
+ * - `'overflowProtection'` — drop the oldest messages when the context window is full
  * - `'staleToolCleanup'` — drop tool results older than 5 messages
  */
 export const STRATEGY_PRESET_NAMES = [
@@ -46,9 +46,9 @@ export function resolvePreset(name: StrategyPresetName): ContextStrategy[] {
     case 'proactiveSummarization':
       return [Offload.summarize('*').when({ utilization: 0.7, preserveRecent: 0.7 })]
     case 'largeToolOffloading':
-      return [Offload.truncate('toolResults', { previewTokens: 1000 }).when({ threshold: 2500 })]
+      return [Offload.truncate('toolResults', { previewTokens: 1000 }).when({ blockThreshold: 2500 })]
     case 'overflowProtection':
-      return [Offload.truncate('*').when({ utilization: 1.0, preserveRecent: 4 })]
+      return [Offload.drop('*').when({ utilization: 1.0, preserveRecent: 4 })]
     case 'staleToolCleanup':
       return [Offload.drop('toolResults').when({ preserveRecent: 5 })]
   }
@@ -59,6 +59,7 @@ export function resolvePreset(name: StrategyPresetName): ContextStrategy[] {
  *
  * @param entries - Array of raw strategies and/or preset name strings
  * @returns Flattened array of concrete strategies
+ * @throws Error when an entry is an unknown preset name or an `Offload` builder without `.when()`
  * @internal
  */
 export function resolveStrategies(entries: (ContextStrategy | StrategyPresetName)[]): ContextStrategy[] {
@@ -69,6 +70,10 @@ export function resolveStrategies(entries: (ContextStrategy | StrategyPresetName
         throw new Error(`Unknown strategy preset: "${entry}". Valid presets: ${STRATEGY_PRESET_NAMES.join(', ')}`)
       }
       strategies.push(...resolvePreset(entry as StrategyPresetName))
+    } else if (typeof entry.apply !== 'function') {
+      throw new Error(
+        'Offload strategies need .when() before use; call .when() with no conditions to run on every new message'
+      )
     } else {
       strategies.push(entry)
     }