Migrating to v0.8

Copy Markdown View Source

This guide summarizes the breaking changes between v0.7 and v0.8 and the required updates for custom persistence integrations.

Breaking Changes

  • Removed modules: DurableStore port, NoopStore adapter, SessionStoreBridge adapter, and SQLiteSessionStore.
  • SessionStore new callbacks: append_events/2 and flush/2 are now required by the port.
  • Event pipeline rename: EventEmitter was renamed to EventBuilder.
  • Query/Maintenance refs: EctoQueryAPI and EctoMaintenance are now module-backed refs ({Module, Repo}), not dedicated GenServers.
  • Optional deps: Ecto and ExAws are now optional dependencies; adapters are conditionally compiled.

Required Updates for Custom Session Stores

1. Implement append_events/2

EventPipeline.process_batch/3 persists batches via append_events/2. If your store does not support true batch writes, call your single-event append in a loop, but keep ordering and idempotency guarantees.

2. Implement flush/2

SessionManager calls flush/2 at run finalization to persist the final session/run state (and any buffered events) atomically. If your backend supports transactions, wrap the full write in one. At minimum, ensure all three components are persisted and failures are surfaced as {:error, %Error{}}.

Expected payload shape:

%{
  session: %Session{},
  run: %Run{},
  events: [%Event{}],
  provider_metadata: %{}
}

3. Verify sequencing and idempotency

append_event_with_sequence/2 and get_latest_sequence/2 remain required. If you changed sequencing in v0.7, re-run the contract tests in test/agent_session_manager/ports/session_store_contract_test.exs.

Ecto Users

  • Apply the consolidated migration (Migration) that includes provider fields, soft delete, and artifact metadata tables.
  • Replace GenServer usage with module-backed refs:
query = {EctoQueryAPI, MyApp.Repo}
maint = {EctoMaintenance, MyApp.Repo}

Optional Dependencies

If you use Ecto-backed stores or S3 artifacts, ensure the corresponding deps are present in your mix.exs. Without them, those adapters compile to stubs that return a structured missing-dependency error.