deepseek-harness/packages/session

dsh-session

Event-sourced session log and in-memory store. A Session is the append-only source of truth for an agent's whole interaction history — the LLM message history is derived from it.

Service: SessionStore (ctx key: sessions)

Creates and holds event-sourced Session instances. Persistence is intentionally not implemented here — plugins subscribe to session/event and flush on session/flush.

Public API

• ctx.sessions.create(id?: string, seed?: SessionEvent[]): Session Create a session. seed replays/forks an existing event log. Disposed with the calling fiber.
• ctx.sessions.get(id: string): Session | undefined
• ctx.sessions.list(): Session[]

Events

Event	Mode	Purpose
session/created	emit	A session was created
session/event	emit	An event was appended (sync, fire-and-forget)
session/flush	parallel	Awaited durability checkpoint (persistence plugins drain buffers here)

Class: Session

Plain class (not a Cordis Service). Create via ctx.sessions.create().

• session.append(type, data): SessionEvent — synchronous, never blocks on I/O.
• session.deriveMessages(): Message[] — derive the LLM message history from the event log. Raw assistant/chunk events are skipped; context/message and steering/message render as tagged synthetic user messages.
• session.events, session.seq, session.id

Session event vocabulary (types.ts)

The append-only log: turn/start, turn/end, step/start, step/end, user/message, assistant/message, assistant/chunk, tool/call, tool/result, steering/message, context/message, usage, error.

Merge-extensible via SessionEventMap — a compaction plugin adds compaction/marker, etc.

Also defines TurnTriggerMap and TurnEndReasonMap (merge-extensible sum types for typed turn boundaries — kind-tagged instead of strings).

Extension points

• Persistence plugins: subscribe to session/event (write-behind) and drain on session/flush (awaited) and fiber dispose. See examples/echo-agent/src/session-jsonl.ts for the pattern.
• Replay/fork: ctx.sessions.create(id, seed) seeds a new session with an existing event log.

What is NOT here (TODO)

• Real persistence backends (JSONL per session dir, sqlite) — future phase.
• Session event vocabulary review — TODO(review) once the loop and a persistence plugin coexist.
• Session branching/tree (pi-style entry tree) — defered unless needed beyond seed-based forking.