feature(session): session surface

packages/session/README.md

@@ -1,6 +1,6 @@
 # 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.
+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. A **surface** layer (a linked list of message-producing events) is maintained on top of the raw log for efficient derivation and compaction.
 
 ## Service: `SessionStore` (ctx key: `sessions`)
 
@@ -24,16 +24,17 @@ Creates and holds event-sourced `Session` instances. Persistence is intentionall
 
 Plain class (not a Cordis Service). Create via `ctx.sessions.create()`.
 
-- `session.append(type, data): SessionEvent` — synchronous, never blocks on I/O. **Throws** if `data` is not losslessly JSON-serializable (BigInt, function, symbol, undefined, non-finite number, circular ref, or an exotic object like Map/Set/Date) — the event log is the durable source of truth, so this invariant is enforced at the source (exported as `isJsonValue` for backends to reuse on their replay/fork entry points).
-- `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.append(type, data, opts?): SessionEvent` — synchronous, never blocks on I/O. **Throws** if `data` is not losslessly JSON-serializable (BigInt, function, symbol, undefined, non-finite number, circular ref, or an exotic object like Map/Set/Date) — the event log is the durable source of truth, so this invariant is enforced at the source (exported as `isJsonValue` for backends to reuse on their replay/fork entry points). An optional third parameter `opts: SurfaceAppendOpts` carries surface metadata: `surfaceOp` controls how the event enters the surface linked list, and `sourceEventSeqs` records provenance (the seq numbers of events this one derives from).
+- `session.deriveMessages(): Message[]` — derive the LLM message history. If any event in the log carries `surfaceOp`, derivation walks the surface linked list (skipping non-surface events). Otherwise, falls back to a linear scan of the raw log (legacy sessions without surface markers).
+- `session.surface: SurfaceManager` — the derived surface, lazily rebuilt from `surfaceOp` markers in the log. Processes only new events (delta) on each access — the log is append-only, so prior events never change.
 - `session.events`, `session.seq`, `session.id`
 - `session.header: SessionHeader` — immutable creation metadata (`version`, `id`, `createdAt`, optional `cwd`/`parentSession`). Kept out of the event log (a storage concern, not replayable state); a minimal v1 header is synthesized for bare `Session` construction.
 
-### Metadata types (`types.ts`)
+### Surface types
 
-- `SessionHeader` — immutable, written once: `{ version, id, createdAt, cwd?, parentSession? }`.
-- `SessionSummary` — mutable, updateable without touching the log: `{ updatedAt, title?, firstPrompt? }`.
-- `SessionMeta = SessionHeader & SessionSummary` — owned here (beside `SessionId`) because `Session.header` is typed by it; persistence backends re-export these rather than own them (which would force a package cycle).
+- `SurfaceOp` — how a surface node entered the linked list: `'append'` (normal tail append) or `{ op: 'replace', start, end }` (replace nodes from `start` through `end` inclusive — both must be valid surface node seqs; `start === end` replaces a single node). Used by compaction to shadow old nodes without deleting them.
+- `SurfaceAppendOpts` — `{ surfaceOp?: SurfaceOp; sourceEventSeqs?: number[] }`, the optional third parameter to `session.append()`.
+- `SurfaceNode` — `{ seq: number; prev: number | null; next: number | null }`, one node in the surface linked list.
 
 ### Session event vocabulary (`types.ts`)
 
@@ -43,11 +44,23 @@ Merge-extensible via `SessionEventMap` — a compaction plugin adds `compaction/
 
 Also defines `TurnTriggerMap` and `TurnEndReasonMap` (merge-extensible sum types for typed turn boundaries — `kind`-tagged instead of strings).
 
+Every `SessionEvent` carries two optional top-level fields (structural metadata):
+
+- `sourceEventSeqs?: number[]` — seq numbers of provenance sources (e.g., the `assistant/chunk` seqs behind an `assistant/message`, or the shadowed nodes behind a compaction marker).
+- `surfaceOp?: SurfaceOp` — how this event entered the surface. Absent for non-surface events (boundaries, chunks, usage, errors).
+
+### Metadata types (`types.ts`)
+
+- `SessionHeader` — immutable, written once: `{ version, id, createdAt, cwd?, parentSession? }`.
+- `SessionSummary` — mutable, updateable without touching the log: `{ updatedAt, title?, firstPrompt? }`.
+- `SessionMeta = SessionHeader & SessionSummary` — owned here (beside `SessionId`) because `Session.header` is typed by it; persistence backends re-export these rather than own them (which would force a package cycle).
+
 ### Extension points
 
 - Persistence plugins: subscribe to `session/event` (write-behind) and drain on `session/flush` (awaited) and fiber dispose. A durable backend reads the log and reloads it into a live session; the metadata seam (`SessionHeader`/`SessionSummary`/`SessionMeta`, `session.header`) is what such a backend stores beside the log.
-- Replay/fork: `ctx.sessions.create(id, { seed })` seeds a new session with an existing event log.
+- Replay/fork: `ctx.sessions.create(id, { seed })` seeds a new session with an existing event log. The surface rebuilds deterministically from `surfaceOp` markers in the seeded events.
+- Compaction: a future plugin appends a new event with `surfaceOp: { op: 'replace', start, end }` to shadow old surface nodes.
 
 ### What is NOT here (TODO)
 
-- **Session branching/tree** (pi-style entry tree) — defered unless needed beyond seed-based forking.
+- **Session branching/tree** (pi-style entry tree) — deferred unless needed beyond seed-based forking.

packages/session/src/index.ts

@@ -10,12 +10,14 @@ import { Context, Service } from 'cordis'
 import { isAbsolute } from 'node:path'
 import type { ContentBlock, Message, MessageSource } from '@deepseek-ai/dsh-llm'
 import { SessionId } from './types.ts'
-import type { CreateSessionOptions, SessionEvent, SessionEventMap, SessionEventType, SessionHeader } from './types.ts'
+import type { CreateSessionOptions, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SurfaceAppendOpts } from './types.ts'
 import { isJsonValue } from './json.ts'
+import { SurfaceManager } from './surface.ts'
 
 export * from './types.ts'
 export { isJsonValue } from './json.ts'
 export { interruptedTurnClosers } from './repair.ts'
+export type { SurfaceNode } from './surface.ts'
 
 declare module 'cordis' {
   interface Context {
@@ -65,6 +67,21 @@ export class Session {
   /** Set by the store so appends are observable; undefined when detached. */
   onAppend: ((event: SessionEvent) => void) | undefined
 
+  /**
+   * Derived surface — a cached linked list of message-producing events.
+   * Lazily rebuilt from `surfaceOp` markers in the log; processes only new
+   * events (delta) on each access — the log is append-only, so prior events
+   * never change.
+   * `append`. Undefined until first accessed (including after fork/seed).
+   */
+  private _surface: SurfaceManager | undefined
+
+  /** The surface linked list over this session's event log. */
+  get surface(): SurfaceManager {
+    if (!this._surface) this._surface = new SurfaceManager(this.log)
+    return this._surface
+  }
+
   /**
    * Immutable creation metadata (format version, cwd, lineage). Supplied by
    * the store via `ctx.sessions.create()`. When a `Session` is constructed
@@ -117,6 +134,11 @@ export class Session {
    * `onAppend`. The hot path never blocks on I/O — persistence plugins buffer
    * asynchronously.
    *
+   * @param type - The event type (key of {@link SessionEventMap}).
+   * @param data - The event payload; must be JSON-serializable.
+   * @param opts - Optional surface metadata: `surfaceOp` controls how the
+   *   event enters the surface linked list; `sourceEventSeqs` records
+   *   provenance (the seq numbers of events this one derives from).
    * @throws if `data` is not losslessly JSON-serializable (BigInt, function,
    *   symbol, undefined, non-finite number, circular ref, or an exotic object
    *   like Map/Set/Date). The event log is the durable source of truth, so this
@@ -125,7 +147,7 @@ export class Session {
    *   throw surfaces at the buggy caller's append site, not asynchronously in a
    *   backend flush.
    */
-  append<T extends SessionEventType>(type: T, data: SessionEventMap[T]): SessionEvent<T> {
+  append<T extends SessionEventType>(type: T, data: SessionEventMap[T], opts?: SurfaceAppendOpts): SessionEvent<T> {
     if (!isJsonValue(data)) {
       throw new Error(`session event "${type}" carries non-JSON-serializable data`)
     }
@@ -138,14 +160,29 @@ export class Session {
     // validated. structuredClone is safe because serializability was just
     // checked. The returned event carries the SAME snapshot, so a caller reading
     // back `event.data` sees the logged value, not its own mutable input.
-    const event = { type, seq: this.log.length, time: Date.now(), data: structuredClone(data) } as SessionEvent<T>
+    //
+    // Surface metadata is snapshot separately: sourceEventSeqs (number[] —
+    // primitives, so array spread is a complete copy) and surfaceOp (a string
+    // primitive, or cloned if it's a replace object).
+    const event = {
+      type,
+      seq: this.log.length,
+      time: Date.now(),
+      data: structuredClone(data),
+      ...opts?.sourceEventSeqs !== undefined ? { sourceEventSeqs: [...opts.sourceEventSeqs] } : {},
+      ...opts?.surfaceOp !== undefined ? {
+        surfaceOp: typeof opts.surfaceOp === 'string' ? opts.surfaceOp : structuredClone(opts.surfaceOp),
+      } : {},
+    } as SessionEvent<T>
     this.log.push(event)
     this.onAppend?.(event)
     return event
   }
 
   /**
-   * Derive the LLM message history from the event log.
+   * Derive the LLM message history from the session surface (when surface
+   * markers exist) or from a linear scan of the raw event log (legacy sessions
+   * without surface markers).
    *
    * - `user/message` → user message
    * - `assistant/message` → assistant message (chunks are skipped — they are
@@ -163,43 +200,62 @@ export class Session {
    * negligible next to a model call.
    */
   deriveMessages(): Message[] {
+    if (this.surface.hasSurface) {
+      const messages: Message[] = []
+      for (const node of this.surface.nodes) {
+        // Surface nodes are built from this.log — node.seq is always a valid
+        // index by construction. The non-null assertion expresses that invariant.
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        const msg = this._deriveOneMessage(this.log[node.seq]!)
+        if (msg) messages.push(msg)
+      }
+      return messages
+    }
+    // Legacy path: linear scan for sessions without surface markers.
     const messages: Message[] = []
     for (const event of this.log) {
-      // Intentionally non-exhaustive: only message-producing events derive
-      // history; turn/step boundaries, chunks, usage, and errors are
-      // trace/replay data.
-      // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
-      switch (event.type) {
-        case 'user/message': {
-          messages.push({ role: 'user', content: structuredClone(event.data.content) })
-          break
-        }
-        case 'assistant/message': {
-          messages.push({ role: 'assistant', content: structuredClone(event.data.content) })
-          break
-        }
-        case 'tool/result': {
-          const { callId, content, isError } = event.data
-          messages.push({
-            role: 'user',
-            content: [{ type: 'tool-result', toolCallId: callId, content: structuredClone(content), isError }],
-          })
-          break
-        }
-        case 'context/message': {
-          const { content, source } = event.data
-          messages.push({ role: 'user', content: renderTagged('context', structuredClone(content), source) })
-          break
-        }
-        case 'steering/message': {
-          const { content, source } = event.data
-          messages.push({ role: 'user', content: renderTagged('steering', structuredClone(content), source) })
-          break
-        }
-      }
+      const msg = this._deriveOneMessage(event)
+      if (msg) messages.push(msg)
     }
     return messages
   }
+
+  /**
+   * Derive a single LLM message from one event, or null if the event type
+   * does not produce a message. Extracted so both the surface path and the
+   * legacy linear-scan path share the same derivation rules.
+   */
+  private _deriveOneMessage(event: SessionEvent): Message | null {
+    // Intentionally non-exhaustive: only message-producing events derive
+    // history; turn/step boundaries, chunks, usage, and errors are
+    // trace/replay data.
+
+    switch (event.type) {
+      case 'user/message': {
+        return { role: 'user', content: structuredClone(event.data.content) }
+      }
+      case 'assistant/message': {
+        return { role: 'assistant', content: structuredClone(event.data.content) }
+      }
+      case 'tool/result': {
+        const { callId, content, isError } = event.data
+        return {
+          role: 'user',
+          content: [{ type: 'tool-result', toolCallId: callId, content: structuredClone(content), isError }],
+        }
+      }
+      case 'context/message': {
+        const { content, source } = event.data
+        return { role: 'user', content: renderTagged('context', structuredClone(content), source) }
+      }
+      case 'steering/message': {
+        const { content, source } = event.data
+        return { role: 'user', content: renderTagged('steering', structuredClone(content), source) }
+      }
+      default:
+        return null
+    }
+  }
 }
 
 /**

packages/session/src/repair.ts

@@ -61,7 +61,12 @@ export function interruptedTurnClosers(events: readonly SessionEvent[]): Session
   // call is "pending" until its matching tool/result arrives. Reset at every
   // turn boundary so a committed earlier turn (already balanced) never leaks a
   // phantom pending call into the interrupted-turn repair.
-  const pendingCalls = new Map<CallId, { step: number }>()
+  // Track pending tool calls with their callSeq (the seq of the `tool/call`
+  // event, captured for surface sourceEventSeqs provenance on the synthetic
+  // result). CallSeq is set from `tool/call` events; the assistant/message
+  // block scan may register a call first (it appears earlier in the log), and
+  // the later `tool/call` event fills in the seq.
+  const pendingCalls = new Map<CallId, { step: number; callSeq?: number }>()
   for (const event of events) {
     switch (event.type) {
       case 'turn/start':
@@ -87,6 +92,18 @@ export function interruptedTurnClosers(events: readonly SessionEvent[]): Session
           if (block.type === 'tool-call') pendingCalls.set(block.id, { step: event.data.step })
         }
         break
+      case 'tool/call':
+        // Capture the tool/call event seq for surface provenance on the
+        // synthesized tool/result. The entry may already exist (registered by
+        // the assistant/message above) or may be new (if the assistant/message
+        // came from a prior step that was already closed).
+        {
+          const entry = pendingCalls.get(event.data.callId)
+          if (entry) {
+            entry.callSeq = event.seq
+          }
+        }
+        break
       case 'tool/result':
         pendingCalls.delete(event.data.callId)
         break
@@ -112,7 +129,7 @@ export function interruptedTurnClosers(events: readonly SessionEvent[]): Session
   // crash, so deriveMessages() yields a valid provider transcript on resume (a
   // dangling assistant tool-call is rejected by every provider). Insertion
   // order follows the Map (insertion = log order of the assistant messages).
-  for (const [callId, { step }] of pendingCalls) {
+  for (const [callId, { step, callSeq }] of pendingCalls) {
     closers.push({
       type: 'tool/result',
       seq: seq++,
@@ -125,6 +142,8 @@ export function interruptedTurnClosers(events: readonly SessionEvent[]): Session
         isError: true,
         error: { name: 'InterruptedError', code: 'interrupted' },
       },
+      surfaceOp: 'append',
+      ...callSeq !== undefined ? { sourceEventSeqs: [callSeq] } : {},
     })
   }
 

packages/session/src/surface.ts

@@ -0,0 +1,129 @@
+/**
+ * Surface layer on top of the session event log: a derived, cached linked list
+ * of events that produce LLM messages. Rebuilt deterministically from
+ * `surfaceOp` markers in the log — the log is the source of truth; the surface
+ * is a view.
+ *
+ * @module @deepseek-ai/dsh-session/surface
+ */
+
+import type { SessionEvent, SurfaceOp } from './types.ts'
+
+/** One node in the surface linked list. */
+export interface SurfaceNode {
+  /** The event seq of this surface node. */
+  seq: number
+  /** The previous surface node's seq, or null if this is the head. */
+  prev: number | null
+  /** The next surface node's seq, or null if this is the tail. */
+  next: number | null
+}
+
+/**
+ * Maintains a cached linked list of surface nodes, rebuilt lazily from
+ * `surfaceOp` markers in the event log. Because the log is append-only, it
+ * processes only the delta since the last rebuild — new events are folded
+ * into the existing surface in O(new events) rather than rescanning the
+ * whole log.
+ */
+export class SurfaceManager {
+  /** Surface nodes in linked-list order (head to tail). Empty until first access. */
+  private _nodes: SurfaceNode[] = []
+  /** Map from event seq → node for O(1) lookup during replacements. */
+  private _nodeBySeq = new Map<number, SurfaceNode>()
+  /** The last processed seq. -1 forces a full rebuild on first access. */
+  private _lastProcessedSeq = -1
+
+  constructor(private log: readonly SessionEvent[]) {}
+
+  /**
+   * Reset to unprocessed state. Call after the log has been replaced
+   * wholesale (e.g. after Session seed). Not needed for normal appends —
+   * those are picked up incrementally.
+   */
+  invalidate(): void {
+    this._lastProcessedSeq = -1
+    this._nodes = []
+    this._nodeBySeq.clear()
+  }
+
+  /** The surface nodes in linked-list order (head to tail). */
+  get nodes(): readonly SurfaceNode[] {
+    if (this._lastProcessedSeq < this.log.length - 1) this._processDelta()
+    return this._nodes
+  }
+
+  /** Whether any event in the log carries `surfaceOp` markers. */
+  get hasSurface(): boolean {
+    if (this._nodes.length > 0) return true
+    // Never processed anything — scan the whole log.
+    if (this._lastProcessedSeq === -1) return this.log.some(e => e.surfaceOp !== undefined)
+    // Processed up to _lastProcessedSeq without finding surface nodes; check
+    // only new events.
+    for (let i = this._lastProcessedSeq + 1; i < this.log.length; i++) {
+      if (this.log[i]?.surfaceOp !== undefined) return true
+    }
+    return false
+  }
+
+  /**
+   * Process events from `_lastProcessedSeq + 1` through the end of the log,
+   * folding new surface markers into the existing linked list.
+   */
+  private _processDelta(): void {
+    for (let i = this._lastProcessedSeq + 1; i < this.log.length; i++) {
+      const event = this.log[i]
+      if (event === undefined || event.surfaceOp === undefined) continue
+
+      if (event.surfaceOp === 'append') {
+        const tail = this._nodes.length > 0 ? this._nodes[this._nodes.length - 1] : undefined
+        const node: SurfaceNode = { seq: event.seq, prev: tail?.seq ?? null, next: null }
+        if (tail) tail.next = event.seq
+        this._nodes.push(node)
+        this._nodeBySeq.set(event.seq, node)
+      } else {
+        this._replace(this._nodes, this._nodeBySeq, event.seq, event.surfaceOp)
+      }
+    }
+    this._lastProcessedSeq = this.log.length - 1
+  }
+
+  /** Apply a replace operation to the in-progress surface. */
+  private _replace(
+    nodes: SurfaceNode[],
+    nodeBySeq: Map<number, SurfaceNode>,
+    newSeq: number,
+    op: Extract<SurfaceOp, { op: 'replace' }>,
+  ): void {
+    const startIdx = nodes.findIndex(n => n.seq === op.start)
+    if (startIdx === -1) {
+      throw new Error(`surface replace: start seq ${op.start} not found in surface`)
+    }
+    const endIdx = nodes.findIndex(n => n.seq === op.end)
+    if (endIdx === -1) {
+      throw new Error(`surface replace: end seq ${op.end} not found in surface`)
+    }
+    if (startIdx > endIdx) {
+      throw new Error(`surface replace: start seq ${op.start} (index ${startIdx}) is after end seq ${op.end} (index ${endIdx})`)
+    }
+
+    // Remove shadowed nodes from `[startIdx, endIdx]` inclusive.
+    const count = endIdx - startIdx + 1
+    const removed = nodes.splice(startIdx, count)
+    for (const r of removed) nodeBySeq.delete(r.seq)
+
+    // Insert the new node where the removed range was.
+    const prevNode = startIdx > 0 ? nodes[startIdx - 1] : undefined
+    const nextNode = startIdx < nodes.length ? nodes[startIdx] : undefined
+
+    const newNode: SurfaceNode = {
+      seq: newSeq,
+      prev: prevNode?.seq ?? null,
+      next: nextNode?.seq ?? null,
+    }
+    if (prevNode) prevNode.next = newSeq
+    if (nextNode) nextNode.prev = newSeq
+    nodes.splice(startIdx, 0, newNode)
+    nodeBySeq.set(newSeq, newNode)
+  }
+}

packages/session/src/types.ts

@@ -160,6 +160,34 @@ export interface SessionEventMap {
 
 export type SessionEventType = keyof SessionEventMap
 
+/**
+ * How a session event entered the surface linked list. Absent for non-surface
+ * events (boundaries, chunks, usage, errors).
+ *
+ * - `'append'`: added to the tail — normal path for user/assistant/tool/context
+ *   messages.
+ * - `{ op: 'replace', start, end }`: replaces surface nodes from `start`
+ *   (inclusive) through `end` (inclusive) with this node. Both must exist as
+ *   surface nodes in the current surface. `start === end` replaces a single
+ *   node. The node's {@link SessionEvent.sourceEventSeqs} must include every
+ *   shadowed surface node. Used by compaction and possible other manipulations.
+ */
+export type SurfaceOp =
+  | 'append'
+  | { op: 'replace'; start: number; end: number }
+
+/**
+ * Optional surface metadata passed to {@link Session.append}.
+ * `surfaceOp` controls how the event enters the surface linked list;
+ * `sourceEventSeqs` records the seq numbers of events that are provenance
+ * sources of this one (e.g. the `assistant/chunk` seqs behind an
+ * `assistant/message`, or the shadowed nodes behind a compaction replacement).
+ */
+export interface SurfaceAppendOpts {
+  surfaceOp?: SurfaceOp
+  sourceEventSeqs?: number[]
+}
+
 /**
  * One immutable entry in the session log.
  *
@@ -174,5 +202,13 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
     /** Unix epoch milliseconds. */
     time: number
     data: SessionEventMap[K]
+    /**
+     * Seq numbers of events that are provenance sources of this event
+     * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
+     * or the surface nodes shadowed by a compaction marker).
+     */
+    sourceEventSeqs?: number[]
+    /** How this event entered the surface; absent for non-surface events. */
+    surfaceOp?: SurfaceOp
   }
 }[T]

packages/session/tests/repair.spec.ts

@@ -122,4 +122,36 @@ describe('interruptedTurnClosers', () => {
     const result = closers[0]!
     expect(result.type === 'tool/result' && result.data.callId).toBe('call-b')
   })
+
+  it('synthesized tool/result carries surfaceOp and sourceEventSeqs when tool/call was logged', () => {
+    const events: SessionEvent[] = [
+      userTurnStart(1, 0),
+      { type: 'step/start', seq: 1, time: 1, data: { turn: 1, step: 1 } },
+      { type: 'assistant/message', seq: 2, time: 2, data: { turn: 1, step: 1, content: [
+        { type: 'tool-call', id: CallId('call-1'), name: 'bash', arguments: '{}' },
+      ] } },
+      { type: 'tool/call', seq: 3, time: 3, data: { turn: 1, step: 1, callId: CallId('call-1'), name: 'bash', arguments: '{}' } },
+    ]
+    const closers = interruptedTurnClosers(events)
+    expect(closers.map(e => e.type)).toEqual(['tool/result', 'step/end', 'turn/end'])
+    const result = closers[0]!
+    expect(result.surfaceOp).toBe('append')
+    expect(result.sourceEventSeqs).toEqual([3])
+  })
+
+  it('handles tool/call without a matching assistant/message entry gracefully', () => {
+    // A tool/call event exists in the log but no assistant/message registered
+    // the callId in pendingCalls (e.g., a plugin appended it directly, or the
+    // assistant/message from a prior step didn't have this call). The repair
+    // should still close the turn — it just won't synthesize a result for this
+    // call (there's nothing to answer).
+    const events: SessionEvent[] = [
+      userTurnStart(1, 0),
+      { type: 'step/start', seq: 1, time: 1, data: { turn: 1, step: 1 } },
+      { type: 'tool/call', seq: 2, time: 2, data: { turn: 1, step: 1, callId: CallId('orphan'), name: 'bash', arguments: '{}' } },
+    ]
+    const closers = interruptedTurnClosers(events)
+    // No pending calls → no synthetic tool/result, just step/end + turn/end.
+    expect(closers.map(e => e.type)).toEqual(['step/end', 'turn/end'])
+  })
 })

packages/session/tests/surface.spec.ts

@@ -0,0 +1,324 @@
+import { describe, expect, it } from 'vitest'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import { CallId } from '@deepseek-ai/dsh-llm'
+
+/** Build a minimal session with turn boundaries and a single user message. */
+function surfaceSession(): Session {
+  const s = new Session(SessionId('ss'))
+  s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+  s.append('user/message', { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+  s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'hi' }] }, { surfaceOp: 'append' })
+  s.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+  return s
+}
+
+describe('SurfaceManager', () => {
+  it('rebuilds a linked list from surfaceOp: append markers', () => {
+    const s = surfaceSession()
+    const nodes = s.surface.nodes
+    // Only the user/message and assistant/message carry surfaceOp: 'append'.
+    // The turn boundaries do not have surface markers.
+    expect(nodes.length).toBe(2)
+    expect(nodes[0]!.seq).toBe(1) // user/message (turn/start is seq 0)
+    expect(nodes[0]!.prev).toBeNull()
+    expect(nodes[0]!.next).toBe(2) // assistant/message (seq 2)
+    expect(nodes[1]!.seq).toBe(2)
+    expect(nodes[1]!.prev).toBe(1)
+    expect(nodes[1]!.next).toBeNull()
+  })
+
+  it('hasSurface returns false when no events have surfaceOp', () => {
+    const s = new Session(SessionId('nosurface'))
+    s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    s.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } })
+    s.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    expect(s.surface.hasSurface).toBe(false)
+  })
+
+  it('hasSurface returns true when any event has surfaceOp', () => {
+    const s = surfaceSession()
+    expect(s.surface.hasSurface).toBe(true)
+  })
+
+  it('hasSurface detects surface markers that arrive after initial processing', () => {
+    // Start with no surface markers. Access nodes first to set _lastProcessedSeq
+    // (via delta processing), keeping _nodes empty. Then append a mix of non-surface
+    // and surface events, and verify hasSurface detects via the delta-only check.
+    const s = new Session(SessionId('late'))
+    s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    s.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } })
+    // Access nodes to trigger processing: sets _lastProcessedSeq = 1, _nodes = [].
+    expect(s.surface.nodes.length).toBe(0)
+    // Append non-surface events first (exercises the loop-continue branch), then
+    // a surface event (exercises the return-true branch).
+    s.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    s.append('turn/start', { turn: 2, trigger: { kind: 'continuation' } })
+    s.append('assistant/message', { turn: 2, step: 1, content: [] }, { surfaceOp: 'append' })
+    // hasSurface checks only new seqs [2, 3, 4]; skips 2 and 3 (non-surface),
+    // finds surfaceOp on seq 4 and returns true.
+    expect(s.surface.hasSurface).toBe(true)
+  })
+
+  it('invalidate resets to full rebuild', () => {
+    const s = surfaceSession()
+    expect(s.surface.nodes.length).toBe(2)
+    // After invalidate, the surface should rebuild from scratch on next access.
+    ;(s.surface).invalidate()
+    expect(s.surface.nodes.length).toBe(2) // same result, but rebuilt
+  })
+
+  it('empty surface yields empty nodes', () => {
+    const s = new Session(SessionId('empty'))
+    // Only turn boundaries, no surface nodes.
+    s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    s.append('step/start', { turn: 1, step: 1 })
+    s.append('step/end', { turn: 1, step: 1 })
+    s.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    expect(s.surface.nodes.length).toBe(0)
+    expect(s.surface.hasSurface).toBe(false)
+    // deriveMessages returns empty array
+    expect(s.deriveMessages()).toEqual([])
+  })
+
+  it('picks up new events incrementally (delta processing)', () => {
+    const s = surfaceSession()
+    expect(s.surface.nodes.length).toBe(2)
+    // Append another surface node
+    s.append('tool/result', { turn: 1, step: 1, callId: CallId('c1'), content: [{ type: 'text', text: 'ok' }], isError: false }, { surfaceOp: 'append' })
+    expect(s.surface.nodes.length).toBe(3)
+    expect(s.surface.nodes[2]!.seq).toBe(4) // seq 4: after turn/end at seq 3
+    expect(s.surface.nodes[2]!.prev).toBe(2)
+    expect(s.surface.nodes[1]!.next).toBe(4)
+  })
+
+  it('replays identically from a seeded log with surface markers', () => {
+    const original = surfaceSession()
+    original.append('tool/result', { turn: 1, step: 1, callId: CallId('c1'), content: [{ type: 'text', text: 'ok' }], isError: false }, { surfaceOp: 'append' })
+    const replayed = new Session(SessionId('replay'), [...original.events])
+    // Surface rebuilds from the seeded log's markers.
+    expect(replayed.surface.nodes.map(n => n.seq)).toEqual([1, 2, 4])
+    expect(replayed.deriveMessages()).toEqual(original.deriveMessages())
+  })
+
+  it('rebuild with replace operation splices out shadowed nodes', () => {
+    const s = surfaceSession()
+    // seq: 0=turn/start, 1=user, 2=assistant, 3=turn/end
+    // Surface nodes: seq 1 (user), seq 2 (assistant).
+    // Replace both with a compaction marker. Both 1 and 2 are valid surface seqs.
+    s.append('assistant/message',
+      { turn: 2, step: 1, content: [{ type: 'text', text: 'summary' }] },
+      { surfaceOp: { op: 'replace', start: 1, end: 2 }, sourceEventSeqs: [1, 2] },
+    )
+    // Now the surface should have just the compaction node.
+    expect(s.surface.nodes.length).toBe(1)
+    expect(s.surface.nodes[0]!.seq).toBe(4) // seq of the compaction marker
+    expect(s.surface.nodes[0]!.prev).toBeNull()
+    expect(s.surface.nodes[0]!.next).toBeNull()
+  })
+
+  it('replace with both ends at real nodes splices only the range', () => {
+    const s = new Session(SessionId('range'))
+    s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 0
+    s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 1
+    s.append('user/message', { content: [{ type: 'text', text: 'c' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 2
+    // Replace seq 0 through 1 inclusive: shadow a and b, keep c.
+    s.append('assistant/message',
+      { turn: 1, step: 1, content: [{ type: 'text', text: 'summary' }] },
+      { surfaceOp: { op: 'replace', start: 0, end: 1 }, sourceEventSeqs: [0, 1] },
+    ) // seq 3
+    expect(s.surface.nodes.map(n => n.seq)).toEqual([3, 2])
+    // Links: 3 ↔ 2
+    expect(s.surface.nodes[0]!.prev).toBeNull()
+    expect(s.surface.nodes[0]!.next).toBe(2)
+    expect(s.surface.nodes[1]!.prev).toBe(3)
+    expect(s.surface.nodes[1]!.next).toBeNull()
+  })
+
+  it('single-node replacement (start === end)', () => {
+    const s = new Session(SessionId('single'))
+    s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 0
+    s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 1
+    // Replace only seq 1 (single node).
+    s.append('assistant/message',
+      { turn: 1, step: 1, content: [{ type: 'text', text: 'x' }] },
+      { surfaceOp: { op: 'replace', start: 1, end: 1 }, sourceEventSeqs: [1] },
+    ) // seq 2
+    expect(s.surface.nodes.map(n => n.seq)).toEqual([0, 2])
+    expect(s.surface.nodes[0]!.next).toBe(2)
+    expect(s.surface.nodes[1]!.prev).toBe(0)
+  })
+
+  it('throws when replace start is not found', () => {
+    const s = new Session(SessionId('bad-start'))
+    s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 0
+    s.append('assistant/message',
+      { turn: 1, step: 1, content: [{ type: 'text', text: 'y' }] },
+      { surfaceOp: { op: 'replace', start: 5, end: 0 }, sourceEventSeqs: [5, 0] },
+    )
+    expect(() => s.surface.nodes).toThrow(/surface replace: start seq 5 not found/)
+  })
+
+  it('throws when replace end is not found', () => {
+    const s = new Session(SessionId('bad-end'))
+    s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 0
+    s.append('assistant/message',
+      { turn: 1, step: 1, content: [{ type: 'text', text: 'y' }] },
+      { surfaceOp: { op: 'replace', start: 0, end: 99 }, sourceEventSeqs: [0] },
+    )
+    expect(() => s.surface.nodes).toThrow(/surface replace: end seq 99 not found/)
+  })
+
+  it('throws when start is after end', () => {
+    const s = new Session(SessionId('reversed'))
+    s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 0
+    s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 1
+    // start=1, end=0 would be reversed order.
+    s.append('assistant/message',
+      { turn: 1, step: 1, content: [{ type: 'text', text: 'y' }] },
+      { surfaceOp: { op: 'replace', start: 1, end: 0 }, sourceEventSeqs: [1, 0] },
+    )
+    expect(() => s.surface.nodes).toThrow(/start seq 1.*after end seq 0/)
+  })
+
+  it('sourceEventSeqs is snapshot so caller mutation does not affect logged event', () => {
+    const s = new Session(SessionId('immutable'))
+    const sources = [10, 20]
+    s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'h' }] }, { surfaceOp: 'append', sourceEventSeqs: sources })
+    // Mutate caller's array after append.
+    sources.push(30)
+    sources[0] = 99
+    const logged = s.events[0]!
+    expect(logged.sourceEventSeqs).toEqual([10, 20])
+  })
+
+  it('replace starting at non-head position links to previous node correctly', () => {
+    const s = new Session(SessionId('mid-replace'))
+    s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 0
+    s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 1
+    s.append('user/message', { content: [{ type: 'text', text: 'c' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 2
+    // Replace the middle node (seq 1) only, keeping seq 0 and seq 2.
+    s.append('assistant/message',
+      { turn: 1, step: 1, content: [{ type: 'text', text: 'x' }] },
+      { surfaceOp: { op: 'replace', start: 1, end: 1 }, sourceEventSeqs: [1] },
+    ) // seq 3
+    expect(s.surface.nodes.map(n => n.seq)).toEqual([0, 3, 2])
+    // Links: 0 → 3 → 2
+    expect(s.surface.nodes[0]!.prev).toBeNull()
+    expect(s.surface.nodes[0]!.next).toBe(3)
+    expect(s.surface.nodes[1]!.prev).toBe(0)
+    expect(s.surface.nodes[1]!.next).toBe(2)
+    expect(s.surface.nodes[2]!.prev).toBe(3)
+    expect(s.surface.nodes[2]!.next).toBeNull()
+  })
+
+  it('surfaceOp replace object is snapshot so caller mutation is isolated', () => {
+    const s = new Session(SessionId('immutable-op'))
+    s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    const op = { op: 'replace' as const, start: 0, end: 0 }
+    s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 's' }] }, { surfaceOp: op, sourceEventSeqs: [0] })
+    // Mutate caller's object after append.
+    op.start = 99
+    const logged = s.events[1]!
+    expect(logged.surfaceOp).toEqual({ op: 'replace', start: 0, end: 0 })
+  })
+})
+
+describe('deriveMessages with surface', () => {
+  it('uses the surface path when surface markers are present', () => {
+    const s = surfaceSession()
+    const messages = s.deriveMessages()
+    expect(messages).toHaveLength(2)
+    expect(messages[0]!.role).toBe('user')
+    expect(messages[0]!.content[0]).toMatchObject({ type: 'text', text: 'hello' })
+    expect(messages[1]!.role).toBe('assistant')
+    expect(messages[1]!.content[0]).toMatchObject({ type: 'text', text: 'hi' })
+  })
+
+  it('falls back to linear scan when no surface markers exist', () => {
+    const s = new Session(SessionId('legacy'))
+    s.append('user/message', { content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } })
+    s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'a' }] })
+    const messages = s.deriveMessages()
+    expect(messages).toHaveLength(2)
+    expect(messages[0]!.role).toBe('user')
+    expect(messages[1]!.role).toBe('assistant')
+  })
+
+  it('surface path skips non-surface events (chunks, boundaries)', () => {
+    const s = new Session(SessionId('filter'))
+    s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    s.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'h' } })
+    s.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 1, text: 'i' } })
+    s.append('user/message', { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'hi' }] }, { surfaceOp: 'append' })
+    s.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    // Chunks and boundaries are NOT in the surface, so only 2 messages.
+    expect(s.deriveMessages()).toHaveLength(2)
+  })
+
+  it('deriveMessages via surface respects replace (shadowed nodes are excluded)', () => {
+    const s = new Session(SessionId('compacted'))
+    s.append('user/message', { content: [{ type: 'text', text: 'original' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'compacted' }] }, { surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] })
+    // Only the compaction node is visible.
+    const messages = s.deriveMessages()
+    expect(messages).toHaveLength(1)
+    expect(messages[0]!.content[0]).toMatchObject({ type: 'text', text: 'compacted' })
+  })
+
+  it('context/message and steering/message appear on surface', () => {
+    const s = new Session(SessionId('ctx'))
+    s.append('context/message', { content: [{ type: 'text', text: 'file changed' }], source: { kind: 'plugin', plugin: 'watcher' } }, { surfaceOp: 'append' })
+    s.append('steering/message', { turn: 1, content: [{ type: 'text', text: 'focus' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    const messages = s.deriveMessages()
+    expect(messages).toHaveLength(2)
+    expect(messages[0]!.content[0]).toMatchObject({ type: 'text', text: '<context source="plugin">' })
+    expect(messages[1]!.content[0]).toMatchObject({ type: 'text', text: '<steering source="user">' })
+  })
+})
+
+describe('Session.append surface opts', () => {
+  it('records sourceEventSeqs and surfaceOp on the event', () => {
+    const s = new Session(SessionId('opts'))
+    const event = s.append('assistant/message',
+      { turn: 1, step: 1, content: [{ type: 'text', text: 'h' }] },
+      { surfaceOp: 'append', sourceEventSeqs: [3, 5, 7] },
+    )
+    expect(event.sourceEventSeqs).toEqual([3, 5, 7])
+    expect(event.surfaceOp).toBe('append')
+    // The logged event matches the returned event.
+    expect(s.events[0]!.sourceEventSeqs).toEqual([3, 5, 7])
+    expect(s.events[0]!.surfaceOp).toBe('append')
+  })
+
+  it('deriveMessages skips surface nodes whose event type is not message-producing', () => {
+    // A surface node with a type not handled by _deriveOneMessage (e.g., 'usage'
+    // placed on surface) should be skipped — the null-check in the surface
+    // derivation path is exercised.
+    const seed: SessionEvent[] = [
+      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+      { type: 'step/start', seq: 1, time: 2, data: { turn: 1, step: 1 } },
+      { type: 'usage', seq: 2, time: 3, data: { turn: 1, step: 1, usage: { inputTokens: 0, outputTokens: 0 } }, surfaceOp: 'append' as const },
+      { type: 'step/end', seq: 3, time: 4, data: { turn: 1, step: 1 } },
+      { type: 'turn/end', seq: 4, time: 5, data: { turn: 1, reason: { kind: 'completed' } } },
+    ]
+    const s = new Session(SessionId('nomessage'), seed)
+    // The usage event is on the surface but _deriveOneMessage returns null for it.
+    expect(s.deriveMessages()).toHaveLength(0)
+  })
+
+  it('append without surface opts produces an event without surface fields', () => {
+    const s = new Session(SessionId('noopts'))
+    s.append('user/message', { content: [{ type: 'text', text: 'x' }], source: { kind: 'user' } })
+    expect(s.events[0]!.sourceEventSeqs).toBeUndefined()
+    expect(s.events[0]!.surfaceOp).toBeUndefined()
+  })
+
+  it('surfaceOp primitives are not cloned (they are immutable)', () => {
+    const s = new Session(SessionId('prim'))
+    const event = s.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: 'append' })
+    // The string 'append' is a primitive — identity-preserving is fine.
+    expect(event.surfaceOp).toBe('append')
+  })
+})