feat(session): add dirty flag to skip unnecessary agent state persistence

[Unshure]

Motivation

Session managers currently call update_agent() on every sync, even when the agent's state hasn't changed. This results in unnecessary I/O operations (file writes, S3 puts, etc.) that impact performance, especially in high-throughput scenarios where agents process messages without modifying their state.

This change reduces the number of update_agent() calls by tracking state changes via version IDs and skipping persistence when nothing has changed.

Resolves #1798

Public API Changes

JSONSerializableDict now includes a private method for version tracking:

# Internal method for consumers to track changes
state._get_version()  # Returns incrementing version number

The version increments each time set() or delete() is called:

state = JSONSerializableDict()
state._get_version()  # 0

state.set("key", "value")
state._get_version()  # 1

state.set("key2", "value2")
state._get_version()  # 2

_InterruptState similarly uses _get_version() that increments on activate(), deactivate(), or resume().

RepositorySessionManager.sync_agent() now conditionally persists by comparing versions:

• User-managed state version (agent.state._get_version())
• Internal state version (agent._interrupt_state._get_version())
• Conversation manager state (direct comparison)

# Before: always persists
session_manager.sync_agent(agent)  # Always calls update_agent()

# After: skips if no changes
agent.state.set("key", "value")
session_manager.sync_agent(agent)  # Persists (version changed)
session_manager.sync_agent(agent)  # Skips (version unchanged since last sync)

Use Cases

• High-throughput agents: Agents that process many messages without modifying state will see reduced I/O overhead
• Retry scenarios: If persistence fails, the tracked version isn't updated, so the next sync will retry
• Multi-sync handlers: The MessageAddedEvent and AfterInvocationEvent hooks both trigger syncs; subsequent syncs will be skipped if nothing changed
• Multiple consumers: Version-based tracking allows multiple consumers to independently track changes without explicit dirty flag clearing

[github-actions]

Assessment: Comment

Good implementation that addresses the performance optimization goal. The dirty flag pattern is well-executed with proper retry semantics (flag preserved on failure).

Review Details

• Testing: One condition in the sync optimization logic lacks test coverage (conversation_manager_state_changed). See inline comment for suggested test case.
• Design: The implementation correctly tracks three independent state sources and only persists when necessary.

Minor suggestion for future consideration: The _last_synced_internal_state dictionary could accumulate entries for agents that are no longer in use. Consider cleanup in a future follow-up if long-running sessions with many transient agents become a use case.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Unshure]

/strands Address the review comment

[github-actions]

Assessment: Approve

The previous review feedback has been addressed - the test for conversation_manager_state_changed has been added.

Test Coverage Summary

All three sync conditions are now tested:

• ✅ state_dirty - test_sync_agent_calls_update_when_state_is_dirty
• ✅ internal_state_changed - test_sync_agent_calls_update_when_internal_state_changed
• ✅ conversation_manager_state_changed - test_sync_agent_calls_update_when_conversation_manager_state_changed

Plus edge cases: skip behavior, flag clearing, failure handling, first sync.

Clean implementation that follows repository patterns and properly optimizes I/O operations.

[Unshure]

/strands

[github-actions]

Assessment: Approve

Good update adding dirty tracking to _InterruptState for consistency.

Changes Reviewed

_InterruptState dirty flag (src/strands/interrupt.py):

• ✅ _dirty field with compare=False, repr=False (excludes from dataclass equality)
• ✅ activate(), deactivate(), resume() all set _dirty = True
• ✅ to_dict() explicitly excludes _dirty from serialization
• ✅ _is_dirty() and _clear_dirty() methods follow same pattern as JSONSerializableDict

sync_agent() update (src/strands/session/repository_session_manager.py):

• ✅ Uses agent._interrupt_state._is_dirty() instead of dictionary comparison
• ✅ Clears both agent.state._clear_dirty() and agent._interrupt_state._clear_dirty() after successful sync
• ✅ Simplifies _last_synced_internal_state (only stores conversation_manager_state now)

Tests (tests/strands/test_interrupt.py):

• ✅ 6 new tests for _InterruptState dirty flag behavior
• ✅ Test verifies _dirty not in to_dict() output

Clean improvement that makes dirty tracking consistent across both state types.

[zastrowm]

Would it be better to have an id that is incremented that the session manager checks/stores? That way it doesn't have to explicitly clear it?

This seems to be tying dirtiness only to the session-manager which is fine, but slightly leaky

[zastrowm]

Same for the other classes.

(we could do this later)

[github-actions]

Good suggestion! A version ID approach would decouple change tracking from specific consumers. The current dirty flag is simpler for the single-consumer case, but we can refactor to version IDs in a follow-up if multiple consumers need independent tracking.

[Unshure]

/strands apply the proposed fix for the dirty flag