feat(session): add TodoItem + todo/write event vocabulary

Add the TodoItem type and a todo/write SessionEventMap variant carrying the
whole todo list as a snapshot (last-write-wins on replay). It is NOT a
SurfaceEventType: it produces no LLM message and never reaches
deriveMessages(), so it carries no surfaceOp and stays off the surface — it is
durable, replayable UI state that rides the existing session/event emit.

Tests cover the snapshot-clone-on-append contract, last-write-wins, the
not-on-surface guarantee, and a seeded replay round-trip. Docs: session.md
gains the TodoItem type-equiv block + the event member; core.md's variant count
goes to twelve; the type-equiv manifest gains TodoItem.

packages/core/session/src/types.ts

@@ -149,6 +149,24 @@ export interface TurnEndReasonMap {
 
 export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap]
 
+/**
+ * One entry in an agent's todo list — the unit of the `todo_write` tool's
+ * whole-list state (the `todo/write` {@link SessionEventMap} event).
+ *
+ * Deliberately minimal: a human-readable `content` line and a three-state
+ * `status`. No id, priority, or `activeForm` — the list is replaced wholesale
+ * on every write (last-write-wins), so entries need no stable identity, and the
+ * status triple is exactly the ACP `PlanEntryStatus` (so the ACP bridge maps a
+ * todo list to a `plan` update 1:1, synthesizing the priority ACP additionally
+ * requires).
+ */
+export interface TodoItem {
+  /** What this task is — a short imperative line shown in the UI. */
+  content: string
+  /** Lifecycle state. `in_progress` marks the single task being worked now. */
+  status: 'pending' | 'in_progress' | 'completed'
+}
+
 /**
  * The session event vocabulary — the append-only source of truth for an
  * agent's whole interaction history. The LLM message history is *derived*
@@ -194,6 +212,23 @@ export interface SessionEventMap {
   'tool/result': { turn: number; step: number; callId: CallId; content: ContentBlock[]; isError: boolean; error?: { name: string; code: string } }
   /** Steering content injected between steps of a running turn. */
   'steering/message': { turn: number; content: ContentBlock[]; source: MessageSource }
+  /**
+   * The agent's whole todo list, replaced wholesale on each write
+   * (last-write-wins on replay — the current list is the last `todo/write`).
+   * Written by the `todo_write` tool via
+   * `agent.session.append('todo/write', { todos })`.
+   *
+   * NOT a {@link SurfaceEventType}: it produces no LLM message and never reaches
+   * `deriveMessages()` — it is durable, replayable UI state. The full snapshot
+   * travels each time, so a resume re-derives the current list from the last
+   * event with no fold. UIs render off `session/event`: the stdio UI prints the
+   * list; the ACP bridge maps it to a `plan` sessionUpdate. This is a
+   * `SessionEventMap` member (it rides the existing `session/event` emit), not a
+   * first-class `interface Events` notification, so the cordis catalog gains no
+   * row for it.
+   * @mode emit
+   */
+  'todo/write': { todos: TodoItem[] }
 }
 
 export type SessionEventType = keyof SessionEventMap

packages/core/session/tests/session.spec.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SESSION_FORMAT_VERSION, Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
-import type { SessionEventType } from '@deepseek-ai/dsh-session'
+import type { SessionEventType, TodoItem } from '@deepseek-ai/dsh-session'
 
 describe('Session', () => {
   it('derives message history from the event log', () => {
@@ -365,3 +365,63 @@ describe('SessionStore', () => {
     expect(events).toHaveLength(1)
   })
 })
+
+describe('todo/write event', () => {
+  it('appends the whole-list snapshot and isolates the log from later mutation', () => {
+    const session = new Session(SessionId('t1'))
+    const todos: TodoItem[] = [
+      { content: 'plan the work', status: 'in_progress' },
+      { content: 'write the code', status: 'pending' },
+    ]
+    session.append('todo/write', { todos })
+
+    const event = session.events.findLast(e => e.type === 'todo/write')!
+    expect(event.type).toBe('todo/write')
+    expect(event.data.todos).toEqual(todos)
+
+    // The append snapshots its input: mutating the caller's array afterward must
+    // not change what the log holds (the durable-source-of-truth contract).
+    todos.push({ content: 'sneak in', status: 'pending' })
+    todos[0]!.status = 'completed'
+    expect(event.data.todos).toEqual([
+      { content: 'plan the work', status: 'in_progress' },
+      { content: 'write the code', status: 'pending' },
+    ])
+  })
+
+  it('is last-write-wins: the current list is the most recent todo/write', () => {
+    const session = new Session(SessionId('t2'))
+    session.append('todo/write', { todos: [{ content: 'first', status: 'pending' }] })
+    session.append('todo/write', { todos: [
+      { content: 'first', status: 'completed' },
+      { content: 'second', status: 'in_progress' },
+    ] })
+
+    const current = session.events.findLast(e => e.type === 'todo/write')!.data.todos
+    expect(current).toEqual([
+      { content: 'first', status: 'completed' },
+      { content: 'second', status: 'in_progress' },
+    ])
+  })
+
+  it('is NOT a surface event: it produces no derived message and joins no surface node', () => {
+    const session = new Session(SessionId('t3'))
+    session.append('user/message', { content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    const before = session.deriveMessages().length
+    session.append('todo/write', { todos: [{ content: 'a task', status: 'pending' }] })
+    // The todo event must not add a message to the derived history…
+    expect(session.deriveMessages()).toHaveLength(before)
+    // …and must not appear on the surface linked list.
+    expect(session.surface.nodes.some(node => node.seq === session.seq - 1)).toBe(false)
+  })
+
+  it('round-trips through a seeded replay identically (durable, no surfaceOp needed)', () => {
+    const original = new Session(SessionId('t4'))
+    original.append('todo/write', { todos: [{ content: 'only', status: 'completed' }] })
+    // Seeding a non-surface event with no surfaceOp must not throw.
+    const replayed = new Session(SessionId('t4-replay'), [...original.events])
+    expect(replayed.events.findLast(e => e.type === 'todo/write')!.data.todos)
+      .toEqual([{ content: 'only', status: 'completed' }])
+    expect(replayed.seq).toBe(original.seq)
+  })
+})