ADR-0011: Application session metadata over AgentsKit ChatMemory

Status: Accepted

Date: 2026-07-11

Context

Cross-client resume needs deterministic application state, protocol cursor, and confirmation bindings in addition to the canonical message history. AgentsKit already owns message persistence through ChatMemory; duplicating messages in an application envelope would create conflicting authorities.

Decision

AgentsKit Chat defines a runtime-validated agentskit.chat.session v1 envelope containing only application metadata: session and definition identity, definition revision, monotonic cursor, deterministic route decisions, and confirmation bindings. Messages remain exclusively in the ChatMemory configured on ChatDefinition.chat.

SessionStorage is a host port with load, compare-and-set save(snapshot, expectedCursor), and optional delete. A save returns false on conflict; last-write-wins storage is not conformant. resumeChatSession accepts missing state as a new session, explicitly migrates the supported v0 envelope, and rejects corrupt, unsupported, foreign-session, or incompatible-definition state before constructing a session. Renderers verify the prepared session identity and revision; they continue to use their official AgentsKit binding.

Pending, processing, and terminal confirmation records are persisted. A pending record remains bound to its original session and canonical tool-call id. Resolution first claims approving, rejecting, or expiring through CAS; only the winner delegates to the upstream controller and then advances to the matching terminal status through a second CAS. A crash leaves an accurate processing record for host reconciliation rather than falsely claiming completion or permitting replay.

Alternatives considered

1. Store messages inside the session envelope — rejected because ChatMemory already owns them.
2. Bundle localStorage, filesystem, and database adapters — rejected because upstream Core and Memory already provide message adapters and hosts have different metadata stores.
3. Silently accept any snapshot version or definition — rejected because partial hydration can corrupt state or weaken confirmation binding.

Consequences

• Cross-client hosts share two coordinated concerns: upstream ChatMemory for messages and SessionStorage for application metadata.
• Definition revisions make compatibility explicit.
• The v0-to-v1 migration is narrow and tested; future incompatible formats require a new migration and ADR.
• Storage failures reject explicit persistence calls but never introduce a second chat lifecycle.

Upstream adoption

Inspected AgentsKit Core memory types, serialization, controller hydration and confirmation execution, plus Memory filesystem, SQLite, Redis, and Turso adapters. Reused ChatMemory, canonical messages/tool calls, and controller approve/deny. Added only application metadata and host storage composition. No upstream source or behavior is copied and no upstream gap exists.