Session

Session

Edge adaptation of the upstream event-sourced session log.

Upstream reference: Session

What Upstream Provides

The Session is an append-only log of typed events — the single source of truth for all agent interaction history. LLM message history is derived from this log, never stored separately. Key concepts:

• SessionEventMap — merge-extensible event vocabulary: turn/step boundaries, user/assistant messages, tool calls/results, request headers, goal changes, and more.
• Surface events — three event types (user/message, assistant/message, tool/result) carry surfaceOp metadata declaring how they enter the derived message history (append or replace range).
• deriveMessages() — cached projection from event log to model-visible Message[]. Rebuilt on surface rewrites; messages are frozen.
• Persistence contract — events must be losslessly JSON-serializable, contiguous in seq, and complete (including raw chunks). Backends encode at will; load must return identical events.
• Cordis API (ctx.sessions) — create, fork, flush, dispose lifecycle. Events broadcast via session/event.

What Edge Changed

Direct Reuse SessionStore plugin

SessionStore is installed as-is. The event log, append validation, surface management, message derivation, fork logic, and flush contract are entirely upstream code.

Replacement Persistence backend

Upstream persists sessions as JSONL files on the local filesystem. Edge replaces this with DurableObjectSessionPersistence backed by DO SQL tables. See the Session Persistence page for details.

Transport Bridge Event delivery

Upstream clients observe events in-process via ctx.on('session/event'). Edge captures events through this same cordis hook and delivers them to the browser as session/event WebSocket frames via publishSessionEvent().

What Edge Did NOT Change

• Event types, their schemas, and the SessionEventMap vocabulary
• Surface event semantics and message derivation logic
• Session fork boundaries and seed handling
• Append validation (JSON serializability, contiguous seq, surface constraints)
• Flush/checkpoint contract

Performance Characteristics

Event append

session.append() is synchronous — it validates, pushes to the in-memory log, and broadcasts to cordis listeners. The persistence write happens asynchronously on flush(). This matches upstream's contract: append is fast; durability is a separate checkpoint.

Message derivation

deriveMessages() rebuilds the message array from the surface projection. The result is cached and only invalidated on surface rewrites (compaction). For most events (chunks, tool calls), the cache is untouched. Cost: O(surface events) on first call or after rewrite; O(1) on subsequent reads.

Event broadcast fan-out

Each appended event synchronously notifies all session/event listeners: SessionProjectionRegistry.drive(), the onChanged projection buffer, GoalRoundDriver, and Edge's own publishSessionEvent delivery chain. All listeners are synchronous and constant-time per event.

Architecture Summary

Component	Category	Edge Code
SessionStore	Reuse	One ctx.plugin() call
Persistence backend	Replace	DurableObjectSessionPersistence
Event delivery	Bridge	publishSessionEvent → WebSocket

Key observation: The Session is the foundational data structure of the entire system — every (goal, title, projection, compaction) builds on top of its event log. Edge treats it as a black box: install the plugin, replace the storage backend, bridge the event delivery. Zero changes to the event model itself.