feat(context): add context manager by lizradway · Pull Request #2547 · strands-agents/harness-sdk

lizradway · 2026-06-01T19:44:45Z

Description

Implements the v1 contextManager facade as designed in strands-agents/docs#831.

Adds a contextManager parameter to AgentConfig that pre-composes the SDK's context management primitives into a single configuration surface. An internal ContextManager plugin composes sub-plugins (ContextCompression, ContextOffloader) that handle the actual behavior.

Architecture

ContextManager (internal plugin)
├── ContextCompression (sub-plugin)
│   ├── Proactive compression (BeforeModelCallEvent)
│   ├── Reactive overflow recovery (AfterModelCallEvent)
│   └── Sliding window enforcement (AfterInvocationEvent)
└── ContextOffloader (sub-plugin)
    ├── Tool result caching (AfterToolCallEvent)
    └── retrieve_offloaded_content tool

Sub-plugins work independently when used standalone. User-provided plugins with matching names take precedence over managed sub-plugins. When contextManager is set, ContextCompression takes priority — NullConversationManager is used (same pattern as other dedicated-param plugins like retryStrategy, sessionManager).

What ships

contextManager parameter on AgentConfig — accepts "auto" or a config object
ContextCompression plugin — proactive/reactive compression with own reduction logic (truncate or summarize)
ContextOffloader — stays in vended-plugins/context-offloader/, composed internally by ContextManager
Message pinning (context-manager/compression/protection.ts) — pinMessageTool for agent-controlled pinning at runtime. Internal utilities (pinMessage, unpinMessage, isPinned, isProtected) not exported; programmatic pinning API deferred.
protectFirst — number of messages at the start of the conversation to protect from eviction
estimateInputTokens() utility — shared token estimation in src/context-manager/token-estimation.ts
<summary> XML tags — summarized messages are wrapped in <summary> tags so the model can distinguish framework-injected summaries from user content
conversationManager marked as pending deprecation — still works, JSDoc-tagged

Public API Surface

New on AgentConfig:

contextManager?: ContextManagerParam

New exports:

pinMessageTool (agent-invokable tool)
ContextManagerParam (type)

All classes (ContextManager, ContextCompression, ContextOffloader) are internal. ContextOffloader remains accessible via the vended-plugins/context-offloader sub-path for backward compat.

Configuration model

Two semantics depending on whether strategy: 'auto' is present:

Override (strategy: 'auto') — starts with everything enabled, you override specific settings:

contextManager: "auto"                                              // everything with defaults
contextManager: { strategy: 'auto', compression: { windowSize: 60 } }  // auto, tweak compression
contextManager: { strategy: 'auto', offloader: { threshold: 5000 } }   // auto, tweak offloader

Additive (no strategy) — starts with nothing, you enable what you want:

contextManager: { compression: true }                               // only compression
contextManager: { compression: 'summarize' }                        // only summarize compression
contextManager: { offloader: true }                                 // only offloading
contextManager: { compression: true, offloader: true }              // both (same as "auto")
contextManager: {}                                                  // nothing enabled

Compression config (discriminated union on `method`)

compression: true                                       // defaults
compression: 'truncate'                                 // method shorthand
compression: 'summarize'                                // method shorthand
compression: { method: 'truncate', windowSize: 30 }     // full config
compression: { method: 'summarize', summaryRatio: 0.5 } // full config
compression: { protectFirst: 2 }                        // protect first 2 messages

Defaults (when enabled via "auto")

Parameter	Default
offloader threshold	2500 tokens
offloader previewTokens	1500 tokens
compression method	"truncate"
compression windowSize	40
compression proactive	true (threshold 0.7)
storage	InMemoryStorage

Plugin registration

contextManager must be passed via the dedicated parameter — same pattern as conversationManager, retryStrategy, and sessionManager. No guards for misuse in plugins[] (consistent with other special-cased plugins).

Deprecation Plan

The following are marked as pending deprecation in v1 and will be removed in v2:

AgentConfig.conversationManager → contextManager: { compression: ... }
Agent._estimateInputTokens() → shared estimateInputTokens() utility
BeforeModelCallEvent.projectedInputTokens → future contextManager budget API
ConversationManager, SlidingWindowConversationManager, SummarizingConversationManager, NullConversationManager → ContextCompression plugin
vended-plugins/context-offloader/ sub-path → import from @strands-agents/sdk directly

Breaking Changes

None. All changes are additive. Existing behavior is unchanged when contextManager is not set.

Related Issues

Documentation PR

strands-agents/docs#831

Type of Change

New feature

Testing

Type check passes
Lint passes
All 2915 tests pass (106 test files)
60 new unit tests covering: token estimation, compression plugin, truncate/summarize strategies, protection logic, context manager resolution

Checklist

I have read the CONTRIBUTING document
I have added any necessary tests that prove my fix is effective or my feature works
I have updated the documentation accordingly
I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
My changes generate no new warnings
Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

github-actions · 2026-06-02T16:46:18Z

+  // Tool-pair partner protection: if adjacent message is protected and they form a pair
+  const msg = messages[index]!
+  const hasToolResult = msg.content.some((b) => b.type === 'toolResultBlock')
+  if (hasToolResult && index > 0 && index - 1 < protectFirst) return true


Issue: This does not verify that messages[index - 1] actually contains a matching toolUseBlock. It only checks that the current message has a toolResult and the previous message is within protectFirst. If message at index - 1 happens to be a regular text message at the boundary of protectFirst, this incorrectly marks the current message as protected.

Suggestion: Add a check that validates the previous message contains a toolUseBlock with a matching toolUseId:

if (hasToolResult && index > 0 && index - 1 < protectFirst) { const prev = messages[index - 1]! const resultIds = new Set( msg.content.filter((b): b is ToolResultBlock => b.type === 'toolResultBlock').map((b) => b.toolUseId) ) if (prev.content.some((b) => b.type === 'toolUseBlock' && resultIds.has((b as ToolUseBlock).toolUseId))) { return true } }

In practice, the LLM API ordering (toolUse always precedes toolResult) may prevent this from manifesting as a user-visible bug, but the validation keeps the function correct regardless of message arrangement.

github-actions · 2026-06-02T16:46:20Z

+export type OffloaderConfig = {
+  /** Token threshold above which tool results are offloaded. Defaults to 2500. */
+  threshold?: number
+  /** Number of tokens to keep as an inline preview. Defaults to 500. */


Issue: previewTokens default is documented as 500 here (and repeated on line 46), but the actual fallback on line 159 is ?? 1500. The PR description's table also states 1500.

Suggestion: Update the TSDoc to say "Defaults to 1500" to match the implementation.

github-actions · 2026-06-02T16:46:22Z

+  if (hasToolResult && index > 0 && index - 1 < protectFirst) return true
+
+  const hasToolUse = msg.content.some((b) => b.type === 'toolUseBlock')
+  if (hasToolUse && index + 1 < messages.length && index + 1 < protectFirst) return true


Issue: This condition is unreachable. We only arrive here when index >= protectFirst (line 123 already returned true for index < protectFirst). For index + 1 < protectFirst to be true, we'd need index < protectFirst - 1, which contradicts index >= protectFirst.

Suggestion: Remove this dead branch or rewrite the tool-pair partner logic. If the intent is "protect a toolUse whose partner toolResult is in the protected range", note that toolResult always comes after toolUse in message ordering, so the toolUse is always at a lower index — meaning it would already be protected by line 123.

github-actions · 2026-06-02T16:46:24Z

+      continue
+    }
+
+    const hasToolUse = msg.content.some((b) => b.type === 'toolUseBlock')


Issue: The findValidTrimPoint function checks for toolUseBlock on user-role messages (lines 73-80), but toolUseBlocks only appear in assistant messages. Since line 63 already skips non-user messages, this branch is dead code.

The same pattern appears in adjustSplitForToolPairs in summarize.ts.

Suggestion: Remove the dead hasToolUse check or restructure the logic to correctly handle the trim boundary. The actual concern is: don't start the "kept" portion at a toolResult (user message) that is the result of a toolUse (assistant message) immediately before it — which is already handled by the toolResultBlock check on line 68.

github-actions · 2026-06-02T16:46:26Z

+ * ```typescript
+ * // Config shorthand (most users)
+ * const agent = new Agent({ contextManager: "auto" })
+ *


Issue: The TSDoc @example (lines 82-88) shows passing a ContextManager class instance to Agent({ contextManager: cm }), but ContextManagerParam is typed as ContextStrategyValue | ContextManagerConfig — it doesn't accept a ContextManager instance. This example would fail type-checking.

Suggestion: Either update ContextManagerParam to also accept ContextManager instances (if that's the intended "power user" path), or fix the example to show the config-object approach:

const agent = new Agent({ contextManager: { storage: new S3Storage("bucket") } })

github-actions · 2026-06-02T16:46:28Z

+      continue
+    }
+
+    const hasToolUse = msg.content.some((b) => b.type === 'toolUseBlock')


Issue: The adjustSplitForToolPairs function has the same dead code pattern as findValidTrimPoint in truncate.ts — checking for toolUseBlock on messages that have already passed the role !== 'user' skip (line 128-129 skips non-user messages, so the message at idx is always user-role, which never contains toolUseBlock).

Suggestion: Same as the comment on truncate.ts — consider removing the dead branch or documenting why it exists as defensive coding.

github-actions · 2026-06-02T16:46:30Z

        )
      }
      this._conversationManager = new NullConversationManager()
+    } else if (contextManagerPlugin) {


Issue: When a non-stateful model has both contextManager and conversationManager set, the conversationManager is silently ignored (line 365-366 takes priority). This could confuse users who set both accidentally.

Suggestion: Consider logging a warning when both are provided, e.g.:

} else if (contextManagerPlugin) { if (config?.conversationManager) { logger.warn('contextManager takes priority over conversationManager — conversationManager will be ignored') } this._conversationManager = new NullConversationManager() }

github-actions · 2026-06-02T16:46:31Z

Assessment: Comment

Well-architected feature with clear separation of concerns between the facade (ContextManager), sub-plugins (ContextCompression, ContextOffloader), and strategy functions. The additive vs override configuration semantics are well thought out.

Review Categories

Documentation/Implementation mismatch: The previewTokens default is documented as 500 but implemented as 1500. The TSDoc example shows a usage pattern that doesn't match the type system.
Dead/unreachable code: The isProtected function has an unreachable branch, and findValidTrimPoint/adjustSplitForToolPairs have dead code checking for toolUseBlocks on user-role messages.
Correctness: Tool-pair validation in isProtected doesn't verify the adjacent message actually contains a matching toolUseBlock — could incorrectly protect messages in edge cases.
API review: This introduces a new contextManager primitive on AgentConfig with a significant public surface. Per the API Bar Raising guidelines, this scope likely warrants a needs-api-review label and designated reviewer if not already done.

The overall design aligns well with SDK tenets — particularly composability and "provide both low-level and high-level APIs".

opieter-aws · 2026-06-02T19:50:50Z

   * Conversation manager for handling message history and context overflow.
   * Defaults to SlidingWindowConversationManager with windowSize of 40.
+   *
+   * @remarks Pending deprecation — use `contextManager` instead. The `contextManager` parameter


Are we actually planning to deprecate this? Do we need this warning if we're only deprecating in 2.0?

opieter-aws · 2026-06-02T19:57:13Z

+  /** Positive: protect first N messages. Negative: protect last N messages. */
+  protectFirst?: number


What if I want both first and last?

opieter-aws · 2026-06-02T20:00:38Z

+  /** Ratio of messages to summarize (0.1–0.8). Defaults to 0.3. */
+  summaryRatio?: number
+  /** Minimum recent messages to preserve during summarization. Defaults to 10. */
+  preserveRecentMessages?: number


protectLast would have more synergy with protectFirst. That said, I'd be in favor of exposing an object instead, but let's at least align the two for consistency.

opieter-aws · 2026-06-02T20:01:20Z

+
+export type SummarizeCompressionConfig = SharedCompressionOptions & {
+  method: 'summarize'
+  /** Ratio of messages to summarize (0.1–0.8). Defaults to 0.3. */


This is an unclear description to me. What does ratio of messages mean?

opieter-aws · 2026-06-02T20:03:46Z

+   * Compression configuration.
+   * - `true`: enable with defaults (truncate, proactive at 0.7).
+   * - `'truncate'` / `'summarize'`: enable specific strategy with defaults.
+   * - `CompressionStrategy.Truncate(...)` / `CompressionStrategy.Summarize(...)`: full config.


Do we actually expose these types?

opieter-aws · 2026-06-02T20:05:38Z

+  storage?: Storage
+  /**
+   * Context offloader configuration.
+   * - `true`: enable with defaults (threshold=2500, previewTokens=500).


previewTokens has a different default here than actual (1500)

Also, are we purposefully drifting from the existing offloader's default of 1000?

opieter-aws · 2026-06-02T20:12:06Z

+ * @param model - The model to use for token counting
+ * @returns Estimated token count, or undefined if estimation fails
+ */
+export async function estimateInputTokens(messages: Message[], model: Model): Promise<number | undefined> {


In the current implementation we add the option to estimate systemPrompt and toolSpecs. Can we support this here to avoid regression? Then we can also forward Agent._estimateInputTokens() to use this function and avoid maintaining 2 copies.

notowen333 · 2026-06-02T19:29:17Z

+   *
+   * When set, takes priority over `conversationManager` — `NullConversationManager` is used.
+   */
+  contextManager?: ContextManagerParam


Can we rename this to maybe ContextManagerInput or inline the union. Param jumped out as confusing to me

notowen333 · 2026-06-02T19:33:25Z

+ */
+export type CompressionConfig =
+  | true
+  | import('./compression/context-compression.js').CompressionMethod


why are we not just importing top level? What does this buy us?

notowen333 · 2026-06-02T19:33:56Z

+  /** Strategy name. Only "auto" is supported currently. */
+  strategy?: ContextStrategyValue
+  /** Storage backend for cached tool results. Defaults to InMemoryStorage. */
+  storage?: Storage


If it's just cached tool results should we narrow the parameter name?

Or if it is also other things... Storage alone is too concise

notowen333 · 2026-06-02T19:36:44Z

+    if (config.compression) {
+      const userProvided = userPlugins?.some((p) => p.name === 'strands:context-compression')
+      if (!userProvided) {
+        let compressionConfig: import('./compression/context-compression.js').CompressionOptions | undefined


notowen333 · 2026-06-02T19:37:59Z

+    const plugins: Plugin[] = []
+
+    if (config.compression) {
+      const userProvided = userPlugins?.some((p) => p.name === 'strands:context-compression')


Can we do instanceof instead of this name matching pattern?

notowen333 · 2026-06-02T19:43:53Z

+ * A message is protected if it is pinned, within the protectFirst range,
+ * or is a tool-pair partner of a protected message.
+ */
+export function isProtected(messages: Message[], index: number, protectFirst?: number): boolean {


Maybe a more descriptive function name

notowen333 · 2026-06-02T19:46:00Z

+const SUMMARIZATION_PROMPT = `You are a conversation summarizer. Provide a concise summary of the conversation history.
+
+Format Requirements:
+- You MUST create a structured and concise summary in bullet-point format.


confirming bullet-point format

notowen333 · 2026-06-02T19:47:07Z

+ * @param options - Summarization options
+ * @returns `true` if messages were summarized, `false` if not enough to summarize
+ */
+export async function summarize(messages: Message[], model: Model, options?: SummarizeOptions): Promise<boolean> {


could expose sys prompt for the summarization

notowen333 · 2026-06-02T20:55:28Z

+ * @param message - The message to check
+ * @returns `true` if the message has `metadata.custom.pinned === true`
+ */
+export function isPinned(message: Message): boolean


After offline discussion, it sounds like "pin" verbage is coming from tool result pairs. I.e. we don't say protect/ed directly because it can mean two messages.

I think this mismatch is confusing. I wouldn't mind just letting protected automatically include a pair.

github-actions Bot added the size/l label Jun 1, 2026

lizradway requested a deployment to manual-approval June 1, 2026 19:45 — with GitHub Actions Waiting

lizradway force-pushed the context-manager branch from 06171e3 to a1337f0 Compare June 1, 2026 19:55

github-actions Bot added size/l and removed size/l labels Jun 1, 2026

lizradway requested a deployment to manual-approval June 1, 2026 19:55 — with GitHub Actions Waiting

lizradway force-pushed the context-manager branch from a1337f0 to a97206c Compare June 1, 2026 19:57

github-actions Bot added size/l and removed size/l labels Jun 1, 2026

lizradway requested a deployment to manual-approval June 1, 2026 19:57 — with GitHub Actions Waiting

lizradway force-pushed the context-manager branch from a97206c to 8f0feca Compare June 1, 2026 20:32

github-actions Bot added size/l and removed size/l labels Jun 1, 2026

lizradway requested a deployment to manual-approval June 1, 2026 20:39 — with GitHub Actions Waiting

lizradway force-pushed the context-manager branch from 8f0feca to 3ef3431 Compare June 1, 2026 21:04

lizradway requested a deployment to manual-approval June 1, 2026 22:00 — with GitHub Actions Waiting

github-actions Bot added size/l and removed size/l labels Jun 1, 2026

lizradway requested a deployment to manual-approval June 1, 2026 22:00 — with GitHub Actions Waiting

lizradway changed the title ~~feat(context): add context manager class~~ feat(context): add context manager Jun 2, 2026

lizradway force-pushed the context-manager branch from 3ef3431 to a70ae1c Compare June 2, 2026 13:45

github-actions Bot added size/xl and removed size/l labels Jun 2, 2026

lizradway requested a deployment to manual-approval June 2, 2026 13:45 — with GitHub Actions Waiting

lizradway force-pushed the context-manager branch from a70ae1c to 50e7824 Compare June 2, 2026 13:47

github-actions Bot added the size/xl label Jun 2, 2026

lizradway requested a deployment to manual-approval June 2, 2026 16:04 — with GitHub Actions Waiting

lizradway temporarily deployed to manual-approval June 2, 2026 16:04 — with GitHub Actions Inactive

lizradway marked this pull request as ready for review June 2, 2026 16:38

lizradway requested a deployment to manual-approval June 2, 2026 16:39 — with GitHub Actions Waiting

github-actions Bot added the strands-running label Jun 2, 2026

github-actions Bot reviewed Jun 2, 2026

View reviewed changes

github-actions Bot removed the strands-running label Jun 2, 2026

lizradway mentioned this pull request Jun 2, 2026

[FEATURE] Context Manager #2562

Open

13 tasks

feat(context): add context manager class

686bdfb

lizradway force-pushed the context-manager branch from 29d1f4d to 686bdfb Compare June 2, 2026 17:55

lizradway requested a deployment to manual-approval June 2, 2026 17:55 — with GitHub Actions Waiting

github-actions Bot added size/xl and removed size/xl labels Jun 2, 2026

lizradway had a problem deploying to auto-approve June 2, 2026 17:55 — with GitHub Actions Failure

opieter-aws reviewed Jun 2, 2026

View reviewed changes

notowen333 reviewed Jun 2, 2026

View reviewed changes

		/** Positive: protect first N messages. Negative: protect last N messages. */
		protectFirst?: number

Conversation

lizradway commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Architecture

What ships

Public API Surface

Configuration model

Compression config (discriminated union on method)

Defaults (when enabled via "auto")

Plugin registration

Deprecation Plan

Breaking Changes

Related Issues

Documentation PR

Type of Change

Testing

Checklist

Uh oh!

github-actions Bot Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jun 2, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

lizradway commented Jun 1, 2026 •

edited

Loading

Compression config (discriminated union on `method`)