Skip to content

Conversation

@jariy17
Copy link
Contributor

@jariy17 jariy17 commented Jan 31, 2026

Summary

  • Replaces prefixed actorId approach (session_{session_id}, agent_{agent_id}) with event metadata for identifying session and agent state events
  • Adds automatic migration for backwards compatibility with existing sessions
  • Fixes pagination bug with metadata filters and handles eventual consistency

Fixes #220
Fixes #196

Changes

Event Metadata for State Identification

  • Added StateType enum (SESSION, AGENT) and metadata constants (STATE_TYPE_KEY, AGENT_ID_KEY)
  • Session and agent events now use metadata filters instead of prefixed actorIds
  • Cleaner separation of concerns - actorId represents the actual actor, not encoded state

Backwards Compatibility

  • Auto-migration: when legacy events are detected, they are migrated to the new format
  • Creates new event with metadata, deletes old event with prefixed actorId
  • Existing sessions continue to work without any code changes

Bug Fixes

  • Fixed pagination in list_events where API returns nextToken even with 0 results, causing metadata filter mismatch errors
  • Added _retry_with_backoff to handle eventual consistency when reading newly created agents
  • Track created agent IDs to handle updates during consistency window

Test plan

  • Unit tests pass (55 passing, 1 pre-existing failure unrelated to this PR)
  • End-to-end demo with real API completed successfully
  • Legacy migration tested with existing sessions

Future Work

The following improvements are planned for subsequent PRs:

Replace actorId prefix-based approach with event metadata for distinguishing
session and agent state events. Add auto-migration for legacy events.

Changes:
- Add StateType enum (SESSION, AGENT) and metadata keys
- Update create_session/create_agent to include stateType metadata
- Update read_session/read_agent to filter by metadata
- Add backwards-compatible auto-migration: legacy events are converted
  to new format on read (create new with metadata, delete old)
- Add tests for legacy migration behavior
… filters

- Fix pagination bug in list_events where API returns nextToken even with
  0 results, causing "metadata filter mismatch" error on subsequent page
- Add _retry_with_backoff method for handling eventual consistency when
  reading newly created agents via metadata filter
- Track created agent IDs to handle updates during consistency window
- Update test to account for retry behavior in legacy migration
@jariy17 jariy17 requested a review from a team January 31, 2026 18:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant