Re-implement conversation-manager as a hook provider

[zastrowm]

Re-implement conversation-manager as a hook provider

Overview

Refactor the conversation-manager from a concrete class hierarchy to a hook-based system. This decouples conversation management from the Agent implementation and makes it consistent with the extensibility patterns in the SDK.

Note: This differs from the Python implementation approach.

Original Requirements

• Update AfterModelCall to pass in an exception if there is an exception
• Expose a AfterModelCall.retryModelCall that can be set to True/False (only valid if there's an exception)
• Reimplement all conversation-managers to be hook providers. The NullProvider simply registers 0 hooks
• Remove all hard-coded calls to the conversation manager and remove the base interface for the conversation manager. The existing apply/reduceContext should be simply hook callback messages

Implementation Requirements

Technical Approach

This is a breaking change that removes the ConversationManager abstract base class and converts conversation management to use the hooks system.

Current Implementation Context

• ConversationManager: Abstract base class with applyManagement() and reduceContext() methods
• Implementations: NullConversationManager and SlidingWindowConversationManager
• Agent Integration: Direct method calls at:
  • Line 286: this.conversationManager.applyManagement(this) in finally block
  • Line 369: this.conversationManager.reduceContext(this, error) on ContextWindowOverflowError
• Public API: ConversationManager is exported and used in AgentConfig.conversationManager

Changes Required

1. Update AfterModelCallEvent (src/hooks/events.ts)

• Add retryModelCall?: boolean field to AfterModelCallEvent class
• This field is only valid when error field is present
• Hook callbacks can set this field to request a retry: event.retryModelCall = true
• Document that this enables hooks to trigger model call retry after reducing context

2. Convert NullConversationManager to HookProvider (src/conversation-manager/null-conversation-manager.ts)

• Change from extends ConversationManager to implements HookProvider
• Implement registerCallbacks(registry: HookRegistry): void method
• Register 0 hooks (empty implementation - no callbacks registered)
• Remove applyManagement() and reduceContext() methods
• Update TSDoc to reflect it's a no-op HookProvider

3. Convert SlidingWindowConversationManager to HookProvider (src/conversation-manager/sliding-window-conversation-manager.ts)

• Change from extends ConversationManager to implements HookProvider
• Implement registerCallbacks(registry: HookRegistry): void method that registers:
  • AfterInvocationEvent callback: Calls logic from current applyManagement() method
  • AfterModelCallEvent callback: When error is present, calls logic from current reduceContext() method and sets event.retryModelCall = true if successful
• Keep existing private helper methods (truncateToolResults, findLastMessageWithToolResults, etc.)
• Keep SlidingWindowConversationManagerConfig interface unchanged
• Maintain all existing behavior, just triggered via hooks instead of direct calls

4. Update Agent Class (src/agent/agent.ts)

• Remove conversationManager field
• Remove conversationManager from AgentConfig type
• Remove line 286: this.conversationManager.applyManagement(this) call (now handled by AfterInvocationEvent hook)
• Update lines 361-374 (error handling in invokeModel):

  // Current code:
  catch (error) {
    const modelError = normalizeError(error)
    await this.hooks.invokeCallbacks(new AfterModelCallEvent({ agent: this, error: modelError }))
    
    if (error instanceof ContextWindowOverflowError) {
      this.conversationManager.reduceContext(this, error)
      return yield* this.invokeModel(args)
    }
    throw error
  }
  
  // New code:
  catch (error) {
    const modelError = normalizeError(error)
    const event = await this.hooks.invokeCallbacks(
      new AfterModelCallEvent({ agent: this, error: modelError })
    )
    
    if (event.retryModelCall) {
      return yield* this.invokeModel(args)
    }
    throw error
  }

• Update constructor to remove default SlidingWindowConversationManager initialization
• Update TSDoc to reflect removal of conversationManager config

5. Remove ConversationManager Base Class

• Delete src/conversation-manager/conversation-manager.ts
• Update src/conversation-manager/index.ts:
  • Remove exports for ConversationManager and ConversationContext
  • Keep exports for NullConversationManager and SlidingWindowConversationManager
• Delete or minimize src/conversation-manager/__tests__/conversation-manager.test.ts

6. Update Public API Exports (src/index.ts)

• Remove line 122: export { ConversationManager }
• Keep export { NullConversationManager } (line 123)
• Keep export { SlidingWindowConversationManager, type SlidingWindowConversationManagerConfig } (lines 124-126)

7. Update Tests

• Update src/conversation-manager/__tests__/null-conversation-manager.test.ts:
  • Test HookProvider interface implementation
  • Test that registerCallbacks registers 0 hooks
• Update src/conversation-manager/__tests__/sliding-window-conversation-manager.test.ts:
  • Test HookProvider interface implementation
  • Test hook callbacks for AfterInvocationEvent and AfterModelCallEvent
  • Test that retryModelCall is set correctly
  • Test message trimming and truncation logic through hooks
• Update src/agent/__tests__/agent.test.ts:
  • Remove tests for conversationManager field
  • Add tests for retry behavior via retryModelCall flag
  • Test that hooks properly trigger context management
• Maintain 80%+ test coverage across all modified files

Migration Guide for Users

Before (Old Pattern):

const agent = new Agent({
  model,
  conversationManager: new SlidingWindowConversationManager({ windowSize: 20 })
})

After (New Pattern):

const agent = new Agent({
  model,
  hooks: [new SlidingWindowConversationManager({ windowSize: 20 })]
})

Files to Modify

Source Files (8-10 files):

• src/hooks/events.ts - Add retryModelCall field
• src/conversation-manager/null-conversation-manager.ts - Convert to HookProvider
• src/conversation-manager/sliding-window-conversation-manager.ts - Convert to HookProvider
• src/conversation-manager/conversation-manager.ts - DELETE
• src/conversation-manager/index.ts - Update exports
• src/agent/agent.ts - Remove direct calls, add retry logic
• src/index.ts - Update public exports

Test Files (~4 files):

• src/conversation-manager/__tests__/null-conversation-manager.test.ts
• src/conversation-manager/__tests__/sliding-window-conversation-manager.test.ts
• src/conversation-manager/__tests__/conversation-manager.test.ts - DELETE or minimize
• src/agent/__tests__/agent.test.ts

Acceptance Criteria

• AfterModelCallEvent has retryModelCall field
• NullConversationManager implements HookProvider with 0 hooks
• SlidingWindowConversationManager implements HookProvider with proper callbacks
• Agent class has no conversationManager field or direct calls
• Agent properly handles retryModelCall flag for context overflow retry
• ConversationManager base class is removed
• Public API exports updated (breaking change)
• All tests pass with 80%+ coverage
• TSDoc comments updated for all modified public APIs
• Existing conversation management behavior preserved (just triggered differently)

Estimated Scope

• Complexity: Medium-High (breaking change, core agent loop modification)
• Files Modified: ~10-12 files
• Breaking Changes: Yes - removal of ConversationManager base class and AgentConfig.conversationManager field
• Estimated Effort: 2-3 days for implementation and testing

Notes

• This is intentionally different from Python implementation
• Breaking change requires version bump and migration documentation
• All existing conversation management behavior is preserved, just triggered via hooks instead of direct method calls
• The retry mechanism via retryModelCall provides more flexibility for custom hook implementations

[zastrowm]

/strands implement

[github-actions]

Failed to create pull request, you can create it by clicking this link:

https://github.com/strands-agents/sdk-typescript/compare/main...agent-tasks/210?quick_pull=1&title=refactor!:%20Convert%20conversation%20managers%20to%20hook%20providers&body=Resolves:%20#210%0A%0A##%20Overview%0AThis%20PR%20refactors%20the%20conversation-manager%20from%20a%20concrete%20class%20hierarchy%20to%20a%20hook-based%20system.%20This%20decouples%20conversation%20management%20from%20the%20Agent%20implementation%20and%20makes%20it%20consistent%20with%20the%20extensibility%20patterns%20in%20the%20SDK.%0A%0A**BREAKING%20CHANGE**:%20This%20removes%20the%20`ConversationManager`%20base%20class%20and%20`Agent.conversationManager`%20field%20from%20the%20public%20API.%0A%0A##%20Changes%0A%0A###%20Core%20Refactoring%0A-%20Added%20`retryModelCall?:%20boolean`%20field%20to%20`AfterModelCallEvent`%20for%20retry%20control%0A-%20Converted%20`NullConversationManager`%20to%20`HookProvider`%20(registers%200%20hooks)%0A-%20Converted%20`SlidingWindowConversationManager`%20to%20`HookProvider`%20with:%0A%20%20-%20`AfterInvocationEvent`%20callback%20for%20sliding%20window%20management%0A%20%20-%20`AfterModelCallEvent`%20callback%20for%20context%20overflow%20handling%20and%20retry%0A-%20Updated%20`Agent`%20class:%0A%20%20-%20Removed%20`conversationManager`%20field%20and%20related%20config%0A%20%20-%20Updated%20retry%20logic%20to%20use%20`retryModelCall`%20flag%20instead%20of%20catching%20`ContextWindowOverflowError`%0A-%20Added%20`messages`%20field%20to%20`AgentData`%20interface%20for%20hook%20access%0A-%20Deleted%20`ConversationManager`%20base%20class%20and%20`ConversationContext`%20interface%0A-%20Updated%20public%20API%20exports%20to%20remove%20`ConversationManager`%0A%0A###%20Migration%20Guide%0A%0A**Before**:%0A```typescript%0Aconst%20agent%20=%20new%20Agent({%0A%20%20model,%0A%20%20conversationManager:%20new%20SlidingWindowConversationManager({%20windowSize:%2020%20})%0A})%0A```%0A%0A**After**:%0A```typescript%0Aconst%20agent%20=%20new%20Agent({%0A%20%20model,%0A%20%20hooks:%20[new%20SlidingWindowConversationManager({%20windowSize:%2020%20})]%0A})%0A```%0A%0A##%20Testing%0A-%20All%20578%20tests%20passing%0A-%2091.51%%20code%20coverage%0A-%20All%20pre-commit%20checks%20passed%20(tests,%20lint,%20format,%20type-check)%0A%0A##%20Implementation%20Notes%0A-%20All%20existing%20conversation%20management%20behavior%20is%20preserved%0A-%20The%20retry%20mechanism%20via%20`retryModelCall`%20provides%20more%20flexibility%20for%20custom%20hook%20implementations%0A-%20`NullConversationManager`%20now%20truly%20does%20nothing%20(registers%200%20hooks)%0A-%20This%20approach%20is%20intentionally%20different%20from%20the%20Python%20SDK%20implementation