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,23 @@ 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, for example .when({ utilization: "80%" }); ' +
+          'a target other than "*" can call .when({}) 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/methods/__tests__/summarize.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest'
-import { flattenMessagesToContent, summarizeContent } from '../summarize.js'
+import { flattenMessagesToContent, formatSummarized, summarizeContent } from '../summarize.js'
 import { MockMessageModel } from '../../../__fixtures__/mock-message-model.js'
 import { AudioBlock, ImageBlock, VideoBlock } from '../../../types/media.js'
 import { CitationsBlock } from '../../../types/citations.js'
@@ -136,6 +136,12 @@ describe('flattenMessagesToContent', () => {
   })
 })
 
+describe('formatSummarized', () => {
+  it('leaves out a size the token count could not measure', () => {
+    expect(formatSummarized('media block', 0, 'a red square')).toBe('[Summarized: media block]\n\na red square')
+  })
+})
+
 describe('summarizeContent', () => {
   // guards against summarizer failures being hidden by a lossy retry (#5291)
   it('propagates a model error without retrying', async () => {

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

@@ -25,12 +25,14 @@ import { logger } from '../../logging/logger.js'
 export const SUMMARIZED_PREFIX = '[Summarized:'
 
 /**
- * Format a `[Summarized: ...]` marker with an optional summary body.
+ * Format a `[Summarized: ...]` marker with an optional summary body, leaving out a size the token count could not
+ * measure.
  *
  * @internal
  */
 export function formatSummarized(description: string, tokens: number, summary?: string): string {
-  const header = `${SUMMARIZED_PREFIX} ${description}, ~${tokens.toLocaleString('en-US')} tokens]`
+  const size = tokens ? `, ~${tokens.toLocaleString('en-US')} tokens` : ''
+  const header = `${SUMMARIZED_PREFIX} ${description}${size}]`
   return summary ? `${header}\n\n${summary}` : header
 }
 

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

@@ -18,32 +18,55 @@ const CHARS_PER_TOKEN = 4
  * @experimental
  */
 export interface TruncateConfig {
-  /** Number of tokens to keep as preview text. Defaults to 1,000. */
+  /**
+   * Number of tokens to keep as preview text. Defaults to 1,000. Content that already fits is left unchanged. For
+   * `Offload.truncate('*')` without a `threshold`, the budget of whole messages kept at the head and tail; the rest
+   * are replaced by one `[... N messages elided ...]` marker.
+   */
   previewTokens?: number
 
-  /** Which portion of the text to keep as preview. Defaults to 'headTail'. */
+  /**
+   * Which portion of the text to keep as preview. Defaults to 'headTail'. For `Offload.truncate('*')` without a
+   * `threshold`, `'head'` keeps only the oldest messages and `'tail'` only the newest.
+   */
   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

@@ -18,10 +18,10 @@ import { Offload } from './strategies/offload/index.js'
  * Preset names are the stable contract. The strategies they resolve to may change
  * between releases.
  *
- * - `'proactiveSummarization'` — batch summarize oldest messages at 70% utilization
+ * - `'proactiveSummarization'` — batch summarize the oldest 30% of 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
- * - `'staleToolCleanup'` — drop tool results older than 5 messages
+ * - `'overflowProtection'` — drop the oldest messages when the context window is full
+ * - `'staleToolCleanup'` — drop tool results outside the newest 5 tool-result messages
  */
 export const STRATEGY_PRESET_NAMES = [
   'proactiveSummarization',
@@ -48,7 +48,7 @@ export function resolvePreset(name: StrategyPresetName): ContextStrategy[] {
     case 'largeToolOffloading':
       return [Offload.truncate('toolResults', { previewTokens: 1000 }).when({ threshold: 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,11 @@ 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, for example .when({ utilization: "80%" }); ' +
+          'a target other than "*" can call .when({}) to run on every new message'
+      )
     } else {
       strategies.push(entry)
     }