Sessions
Cross-client session metadata with CAS storage — AgentsKit keeps message authority.
Persistent cross-client sessions
AgentsKit remains the message authority. Put a ChatMemory on definition.chat.memory, then store only Chat application metadata through SessionStorage.
Split of ownership
| Concern | Owner | Store |
|---|---|---|
| Messages, tools, streams | AgentsKit | ChatMemory / provider |
| Routes, app state, confirmations, cursor | AgentsKit Chat | SessionStorage |
Resume on any shell
import { resumeChatSession } from '@agentskit/chat'
import { AgentChat } from '@agentskit/chat/react'
const session = await resumeChatSession(definition, {
sessionId: 'customer-42',
storage: applicationSessionStorage,
})
export const Support = () => (
<AgentChat definition={definition} session={session} />
)The same preparation works before mounting React Native or Ink: load the same sessionId, point ChatConfig.memory at the same conversation.
CAS contract (required)
SessionStorage.save(snapshot, expectedCursor) must be atomic:
expectedCursor | Behavior |
|---|---|
undefined | Create only |
| stored value | Update only if cursor matches |
| mismatch | Return false (conflict) |
A plain last-write-wins key/value write is unsafe — two resumed clients must not resolve the same pending action.
Snapshot shape
Protocol agentskit.chat.session v1 includes:
- definition identity + revision
- deterministic application state
- monotonic cursor
- pending or terminal confirmation bindings
Never messages. Increment definition.revision when a state-machine change invalidates old application metadata.
Hydration rules
| Load result | Behavior |
|---|---|
null / undefined | Start clean |
| Invalid JSON / unknown version | Reject before hydration |
| Session / definition / revision mismatch | Reject |
Version 0 is the only implicit migration currently supported.
Persist and confirmations
- Call
session.persist()at an explicit durability boundary. - Deterministic transitions also schedule saves.
- Confirmation changes await durable storage; failure rejects the operation.
- Resolution uses durable processing status before delegation; terminal status only after upstream success.