feat(context-ts): add context strategy presets + rewire defaults to use class

[lizradway]

Summary

Adds strategy presets to ContextManager and rewires the 'auto' and 'agentic' modes to use ContextManager internally instead of SummarizingConversationManager. This makes ContextManager the single owner of context reduction — overflow recovery, proactive compression, and emergency truncation all flow through the strategy pipeline.

What changed

• Strategy presets: named building blocks ('proactiveSummarization', 'largeToolOffloading', 'overflowProtection', 'staleToolCleanup') that resolve to concrete Offload.* strategies. Usable in the strategies array alongside raw strategies.
• ContextManager.from() factory: resolves ContextManagerStrategy values ('auto' | 'agentic' | ContextManagerConfig | false) into internal ContextManager instances. Validates unknown preset strings.
• Agent config simplified: contextManager on AgentConfig accepts a preset string or config object. The agent constructs and registers the manager — no need to instantiate ContextManager directly.
• ContextManager class removed from barrel: it's an internal implementation detail. Only the config types and Offload builder are public.
• _removalRatio removed: preserveRecent is now the sole control for message-level removal. Decimal (0 < n < 1) = ratio, integer (>= 1) = absolute count.
• Overflow recovery: strategies bypass utilization gates when running in response to ContextWindowOverflowError (the estimate undercounts without system prompt/tool specs). Emergency truncate also honors the overflow flag but clears it once strategies bring utilization below 1.0.
• Pinned message support: BaseOffloadStrategy now filters out pinned messages (and tool-pair partners) in both message-level and per-block paths. Emergency truncate ignores pins as a last resort.

API changes

New exports (all @experimental):

// Config types
export type { ContextManagerStrategy }    // 'auto' | 'agentic' | ContextManagerConfig | false
export type { ContextManagerConfig }       // { strategies?, stash? }
export type { ContextStrategy, ContextState, StashConfig }
export type { StrategyPresetName }         // 'proactiveSummarization' | 'largeToolOffloading' | ...

// Builder
export { Offload }                         // Offload.drop() / .truncate() / .summarize() + .when()
export type { OffloadTarget, OffloadConditions, OffloadStrategyBuilder }
export type { TruncateConfig, SummarizeConfig }

Changed:

• AgentConfig.contextManager: ContextManagerStrategy (was not previously typed for presets)

Removed from barrel:

• ContextManager class (internal — use preset strings or ContextManagerConfig instead)

Usage

// Preset (recommended)
const agent = new Agent({ contextManager: 'auto' })
const agent = new Agent({ contextManager: 'agentic' })

// Custom config with strategy presets
const agent = new Agent({
  contextManager: {
    strategies: ['largeToolOffloading', 'proactiveSummarization'],
  }
})

// Custom config with raw strategies
const agent = new Agent({
  contextManager: {
    strategies: [
      Offload.truncate('toolResults', { previewTokens: 500 }).when({ threshold: 2000 }),
      Offload.summarize('*').when({ utilization: 0.8, preserveRecent: 0.7 }),
    ],
    stash: { storage: myStorage },
  }
})

// Disable
const agent = new Agent({ contextManager: false })

Related Issues

#4053

Type of Change

New feature

Testing

• 205 unit tests passing across context-manager module
• Tests cover: preset resolution, ContextManager.from() validation, overflow bypass, emergency truncate, pinned message protection, strategy pipeline ordering
• Verified overflow recovery end-to-end: strategies fire and retry is set when provider throws ContextWindowOverflowError

[lizradway]

@strandly-the-agent pls review

[github-actions]

Review Summary

Assessment: Request Changes

Solid, well-scoped refactor that consolidates context management behind ContextManager + strategy presets. The core direction is good, but there are a couple of blocking items and a few design questions to resolve before merge.

Review Categories

• CI gates (blocking): format:check fails — Prettier reports style issues in context-manager.ts and offload/base.ts (ternary wrapping + a stray blank line). Run npm run format. Tests (73) and type-check pass locally.
• API bar-raising (blocking): A significant public surface is newly exported from index.ts, but there's no api/needs-review label and the PR description is the untouched template. Add the label and the required use cases / examples / signatures.
• Breaking API contract: contextManager no longer accepts a ContextManager instance (now ContextManagerConfig), even though ContextManager is publicly exported — and from() silently degrades an instance to the default pipeline for JS callers. Confirm this is intentional and document the migration.
• Behavioral change: base _removalRatio 0.3 → 1.0 changes default message-level removal from 30% to 100%; not called out or directly tested.
• Cleanup / tests: isContextManagerPreset is dead code; the preset "integration" tests only assert toBeDefined(); constructor default pipeline diverges from the 'auto' preset.

Nice consolidation overall — collapsing the SummarizingConversationManager + ContextOffloader wiring into a single ContextManager path meaningfully simplifies the agent construction logic.

[strandly-the-agent]

Changes requested — the presets are a good shape; the collateral changes to the reduction path are what need work.

Three blockers, all on documented entry points (evidence for each in the inline comments):

• 🔴 _removalRatio 0.3 → 1.0 makes every message-level strategy remove 100% of eligible messages in one pass — for all existing Offload.* users, not just the new presets.
• 🔴 proactiveSummarization has no preserveRecent, so at 70% utilization it summarizes the pending user turn away before the model sees it.
• 🔴 Presets now run on NullConversationManager, and the overflow retry re-gates on estimated utilization — a real ContextWindowOverflowError can end with no reduction and no retry (measured: 'auto'/'agentic' → no retry; old SummarizingConversationManager → retry).

Plus 3 🟡 inline (pins evicted under 'agentic', unvalidated preset strings, two storage tests that assert the same thing) and two design questions I'd want answered before merge: the silently-dropped conversationManager, and root barrel vs ./experimental for the new exports. The api/needs-review label + PR description the bot already asked for still apply — the export-surface decision needs an API reviewer, not a solo approve.

Not re-raised: the instance-form narrowing (fixed in d573ca9), dead isContextManagerPreset, {} vs 'auto' divergence, presets.test.ts toBeDefined(), prettier — the bot review covers those.

Details — evidence ledger, questions, reading order, appendix

Verified

• ✅ Reviewed d573ca940bc334b53dc0da226104d5ab7cfe4408 (delta from 90e412e7 is the 3-line instanceof ContextManager passthrough) against merge-base 545d9ed0.
• ✅ eslint (changed files) exit 0 · ✅ tsc --noEmit (src) exit 0 on both heads · 🔴 prettier --check exit 1 on 4 changed files (context-manager.ts, offload/base.ts, offload-strategy.test.ts, agent.context-manager.test.ts) · ✅ vitest run --project unit-node 32 files / 759 tests passed on 90e412e7.
• ✅ Probes (scratch vitest files, deleted): real ContextWindowOverflowError at the AfterModelCallEvent hook → from('agentic')/from('auto') retry=undefined, 40 messages untouched; SummarizingConversationManager(0.3) retry=true, 29 left. proactiveSummarization on 10 messages at util 0.7 → [m0, "[Summarized: 9 messages…]"], the question inside the summary. truncate('*').when({utilization:0.5}) on 8 messages → 1 left (pre-PR: 2 removed); 'auto' summarize on 40 → 5 left. Pinned message at index 3 gone after 'agentic' summarize. from('manual') → default pipeline, no throw; strategies: ['typo'] → TypeError: resolvePreset(...) is not iterable. Forcing _removalRatio back to 0.3 leaves the whole suite green. contextManager: 'auto' + agent storage does write through (context/<session>/scopes/agent/<id>/…) — only the test got weaker.
• Passes: triage, context-build, correctness, test-quality, docs-accuracy, API bar-raiser, adversarial. The API and adversarial passes timed out on the deep tier and were re-run on the standard tier, so the API read is somewhat shallower than usual. Raw pass outputs and logs are uploaded as artifacts.

Questions

Blocking

• Is the _removalRatio 1.0 flip meant for all existing strategies, or was it scoped to the new presets? strands-py/.../offload/base.py:269 keeps 0.3, design 0015:1125 still documents 0.3, and 0011:102 says defaults shouldn't be set on intuition alone. If deliberate, would it be cleaner as its own PR with the benchmark — or as a ratio knob on OffloadConditions so overflowProtection can ask for a full sweep while everything else stays incremental?
• { contextManager: 'auto', conversationManager: new SlidingWindowConversationManager({ windowSize: 20 }) } now silently discards the window (agent.ts:342; no logger.warn). Pre-PR honoured it and the site docs still promise it. Warn, or throw like the stateful-model guard at agent.ts:540-544 (Python throws at agent.py:660)?
• src/experimental/index.ts:12-18 already exports ten of these thirteen symbols via @strands-agents/sdk/experimental (#4231); index.ts:279-291 now duplicates them in the root barrel under a code comment TypeDoc can't see. Un-exporting later is itself a break — is root export a deliberate promotion? If not, would moving the block to src/experimental/index.ts be simpler? Either way ContextManagerStrategy, Offload, OffloadStrategyBuilder, StrategyPresetName lack @experimental tags and ContextManagerPreset is referenced by an exported type but not exported.

Non-blocking

• staleToolCleanup sets neither threshold nor utilization, so it drops older tool results on every model call even at 2% utilization; its preserveRecent: 5 counts tool-result-bearing messages, not "turns" as presets.ts:24 says. Intended?
• preserveRecent: 0.99 ≈ keep everything, preserveRecent: 1 = keep one message, 1.5 silently floors to 1; Python types it int. Would a separate preserveRecentRatio field avoid the discontinuity?
• The four STRATEGY_PRESET_NAMES have no Python counterpart and appear in no design doc — is serialized (JSON/YAML) config the reason they're strings rather than exported builders? That'd be worth stating in the PR body; it's the argument for the string layer.

Reading order

1. strands-ts/src/agent/agent.ts:326-345 — resolveConversationManager: every non-undefined/non-false value now yields NullConversationManager. The pivot of the PR.
2. strands-ts/src/context-manager/context-manager.ts:83-115 — ContextManager.from(), where 'auto'/'agentic' become strategy pipelines; compare with what agent.ts deleted.
3. strands-ts/src/context-manager/presets.ts — the named presets (the PR's stated purpose); short and self-contained.
4. strands-ts/src/context-manager/strategies/offload/base.ts:159-168, 295-322 — widest blast radius: preserveRecent as a ratio and the _removalRatio default; these affect every pre-existing strategy.
5. src/index.ts:279-291, types.ts, types/agent.ts — surface changes. Tests last: agent.context-manager.test.ts shows which behaviours were dropped.

Appendix — non-blocking (9)

• Stale site docs (not in this diff, but now false for TS): site/.../context-management.mdx:42-47 (auto = SummarizingConversationManager 0.3/0.85 + ContextOffloader; tool named retrieve_offloaded_content, actual stash tool is retrieve_context), :53-54 (co-provided manager "replaces" the auto one; offloader dedupe), :138 (agentic composition), :148 (durable-storage advice → now agent storage or contextManager: { stash: { storage } }); storage.mdx:58-61,247 (offloader/ prefix → context/<session>/scopes/agent/<id>); context-management.ts:21-27 example is now a no-op. Prose is shared py/ts and Python is unchanged, so it needs a <Tabs> split rather than a rewrite.
• preserveRecent isn't a hard floor when a tool pair straddles the boundary (collectRemovableWithPair pulls the partner out of the preserved window) — pre-existing, but now reachable on every fire because the whole eligible set is selected.
• Test gaps beyond the inline one: nothing asserts ContextManager.from() expansions (1500/8000, previewTokens 750, preserveRecent: 4); nothing pins message-level removal count (the truncate marker assertion at offload-strategy.test.ts:597-602 was loosened rather than pinned); ratio preserveRecent isn't covered through Offload.*.when(); the deleted param+plugins duplicate-registration test has no replacement now that the instance form is back.
• Agent.contextManager (agent.ts:432) is public while LocalAgent.contextManager (types/agent.ts:313) is @internal — pick one; with instances back, agent.contextManager!.stash is a plausible user route.
• ContextManager.from() is public but is Agent-construction plumbing returning ContextManager | undefined; consider @internal.
• strategies/offload/index.ts:41 @example says "over 2500 tokens" beside .when({ threshold: 1500 }) — pre-existing text, newly published.
• context-manager.ts:50 "On context overflow, runs the strategy pipeline" omits the BeforeModelCallEvent proactive path, which is the primary one for 'auto'.
• presets.ts:44 comment restates the module doc; presets.ts:5-6 has a blank line mid-paragraph that breaks TSDoc rendering.
• Prettier: 4 files, npm run format fixes it (also flagged by the bot).

[lizradway]

@strandly-the-agent pls review

[github-actions]

Follow-up review — commit d778af406 (round-2 feedback)

Assessment: Request changes (2 blocking items below; the rest of round 2 looks good)

Ran the gates on this head: context suites 135 tests pass, no type errors — but Prettier fails.

🔴 Blocking

1. Prettier failure — CI will fail. src/context-manager/__tests__/context-manager.test.ts:186 is 123 chars (the new BeforeModelCallEvent({ ... }) one-liner) and exceeds the 120 print width. Prettier wants it wrapped:

   const event = new BeforeModelCallEvent({
     agent,
     model: agent.model,
     invocationState: {},
     projectedInputTokens: 100,
   })

   Please run prettier --write before pushing.

2. The improved two-pass pinned test (fix models - anthropic #8) still doesn't guard the fix. I verified by reverting the repairAlternation change — the test still passes, because the fixture never actually merges the pinned message. Details + a verified drop-in fixture are in the reply on @strandly-the-agent's thread.

✅ Verified good (round 2)

• fix ci: update sphinx requirement from <6.0.0,>=5.0.0 to >=5.0.0,<9.0.0 #1 — the eager MessageAddedEvent hook is now isPinned-guarded, so a pinned oversized block is no longer truncated at add-time. Closes @opieter-aws's base.ts:333 thread.
• fix ci: update sphinx-rtd-theme requirement from <2.0.0,>=1.0.0 to >=1.0.0,<4.0.0 #3 — removing the overflow-clear is the right call: overflow is the authoritative signal and countTokens undercounts, so letting the estimate cancel the emergency-truncate backstop was the bug @opieter-aws flagged. The test was correctly retitled to the non-overflow case. (Note the intended tradeoff: emergency truncate now always fires on a genuine overflow, dropping the oldest ~20% even if earlier strategies already freed space — reasonable for a forward-progress guarantee, just worth confirming that's the desired behavior.)
• fix ci: update pre-commit requirement from <4.2.0,>=3.2.0 to >=3.2.0,<4.3.0 #4 / ci: update mypy requirement from <1.0.0,>=0.981 to >=0.981,<2.0.0 #2 / ci: update sphinx-autodoc-typehints requirement from <2.0.0,>=1.12.0 to >=1.12.0,<4.0.0 #5 — warn-on-both-managers, {@link ContextManagerConfig}, and the turns→messages doc fix all look correct. (Minor: @opieter-aws suggested warnOnce for ci: update pre-commit requirement from <4.2.0,>=3.2.0 to >=3.2.0,<4.3.0 #4; logger.warn here runs once per agent construction rather than per-request, so it's not spammy — fine either way.)

Still open (design/process)

• 🔴 _removalRatio 0.3 → 1.0 rationale/scope not captured in the PR description (Python still ships 0.3).
• 🔴 proactiveSummarization has no preserveRecent.
• 📋 API bar-raising: api/needs-review label + PR description (use cases / examples / signatures); experimental-vs-root-barrel export decision needs an API reviewer.

[github-actions]

Follow-up review — commit b05df8e4d

Assessment: Comment (one blocker cleared; one blocker + design items remain)

Re-ran gates on this head: Prettier clean across the context-manager tree + agent.ts, 135 tests pass, no type errors.

• ✅ Blocking ci: update sphinx requirement from <6.0.0,>=5.0.0 to >=5.0.0,<9.0.0 #1 (Prettier) resolved. The BeforeModelCallEvent construction is wrapped exactly as suggested — CI formatting check will pass now.
• ⚠️ Blocking ci: update mypy requirement from <1.0.0,>=0.981 to >=0.981,<2.0.0 #2 still open. offload-strategy.test.ts wasn't touched by this commit, so the two-pass pinned test remains the tautology from d778af406 — it passes even with the repairAlternation pin-propagation reverted, because the fixture never actually merges the pinned message. The verified drop-in fixture is in my reply on @strandly-the-agent's thread; swapping it in makes the test guard the fix.

Still open (design/process)

• 🔴 _removalRatio 0.3 → 1.0 rationale/scope not captured in the PR description (Python still ships 0.3).
• 🔴 proactiveSummarization has no preserveRecent.
• 📋 API bar-raising: api/needs-review label + PR description (use cases / examples / signatures); experimental-vs-root-barrel export decision needs an API reviewer.

Thanks for the quick formatting turnaround.

[lizradway]

@strandly-the-agent pls review

[strandly-the-agent]

Follow-up on b05df8e — two 🟡s, both fallout from the round-2 changes. Removing the overflow clear (per opieter-aws's thread) fixes the re-gating problem but swings the other way: the emergency truncate now fires on every overflow pass even after summarize has already resolved it, eating two of the four preserved turns (and ignoring pins). And the pinned-merge test still doesn't reach the merge — it passes with the fix reverted. Both have one-line fixes inline. Gates green.

Status:

• ✅ Eager MessageAddedEvent hook now skips pinned messages; logger.warn on co-provided conversationManager; {@link ContextManagerConfig}; staleToolCleanup doc wording.
• 🟡 context-manager.ts:208-215 — emergency truncate runs unconditionally under overflow even when earlier strategies acted. Verified with the 'auto' pipeline: [u0+Summarized+u8, a9, u10, a11] after summarize → [u0+Summarized+u8+u10, a11] after emergency.
• 🟡 offload-strategy.test.ts:678 — with both q10 and a11 appended the fixture is back to even length, so pinned-a3 sits between two user messages and never merges; drop a11 and the test fails without the fix (verified both ways).
• ⏳ Still open: storage-tests thread (agent.storage.test.ts:15), api/needs-review (bot's index.ts thread).

Details

• ✅ Reviewed b05df8e4d987bb25745c5421cb4b32b711540f9f (delta from 82402b3: 6 files, +23/−8). Self-run follow-up; each change verified, the overflow change probed with a working summarizer mock.
• ✅ tsc 0 · eslint 0 · prettier 0 (agent.ts + context-manager/) · vitest context-manager + agent cm/storage suites 9 files / 142 passed.
• ✅ Probe: new ContextManager() (= 'auto'), 12 messages, overflow: true, estimate 0.5 (and 1.2→0.5), summarizer returns SUMMARY. Result [u0+[Summarized: 7]+u8+u10, a11] — versus proactive at 0.9 [u0+[Summarized: 7]+u8, a9, u10, a11]; the difference is the emergency bite (drops a9, merges u10 into the head). With the inline patch: identical to proactive; a noop user strategy still lets emergency fire (a1, u2 dropped); existing context-manager.test.ts 16/16 green.
• ✅ Pin test: on this head the survives repairAlternation merge test passes with the repairAlternation metadata line removed. With a11 deleted from the fixture it fails without the fix (expected undefined to be true) and passes with it.

[github-actions]

Follow-up — no new commit since b05df8e4d

Reconciling with @strandly-the-agent's follow-up review — we've converged on the same two blockers, so here's the consolidated remaining list. Both have verified one-line fixes on the inline threads.

🔴 Blocking (2)

1. context-manager.ts:208 — emergency truncate fires on every overflow pass. I originally raised this as an "intended tradeoff, please confirm"; @strandly-the-agent's 'auto' probe shows it's actually a regression — emergency eats 2 of the 4 preserveRecent turns and ignores pins on every overflow, defeating the pinned-message guarantee this PR adds. Re-gate emergency once a prior strategy has acted (fix on the thread).
2. offload-strategy.test.ts:678 — pinned-merge test is a tautology. Passes with the repairAlternation pin-propagation reverted; the fixture never reaches the merge. Dropping a11 restores odd length so pinned-a3 merges with a7 — then the test fails without the fix (both verified). Comment also needs the a1→a7 correction.

Still open (design / process)

• 🔴 _removalRatio 0.3 → 1.0 rationale/scope not in the PR description (Python still ships 0.3).
• 🔴 proactiveSummarization has no preserveRecent.
• 📋 API bar-raising: api/needs-review label + PR description (use cases / examples / signatures); experimental-vs-root-barrel export decision needs an API reviewer.

Gates are green on this head; both blockers are small, well-scoped fixes.

[lizradway]

@strandly-the-agent pls review

[strandly-the-agent]

Follow-up on ab518bc — both fixes verified; nothing new from me.

• ✅ Emergency truncate re-gates once a prior strategy acted: 'auto' on overflow now yields exactly the proactive result ([u0+Summarized+u8, a9, u10, a11]); with a no-op user strategy the emergency still fires.
• ✅ The pinned-merge test now discriminates: with the repairAlternation metadata line reverted it fails (expected undefined to be true).
• ✅ tsc / eslint / prettier clean; context-manager + agent suites 9 files / 142 tests.

Only two things left on the board, neither a code defect: the storage-tests coverage nit (agent.storage.test.ts:15 thread — a two-line storage.list('context/') assertion, non-blocking), and the api/needs-review label for the root-barrel exports, which is the one reason I'm not stamping an approval solo — happy for an API reviewer to take it from here.