co-mono/packages/coding-agent/docs/session-tree-plan.md

Session Tree Implementation Plan

Reference: session-tree.md

Phase 1: SessionManager Core ✅

• Update entry types with id, parentId fields (using SessionEntryBase)
• Add version field to SessionHeader
• Change CompactionEntry.firstKeptEntryIndex → firstKeptEntryId
• Add BranchSummaryEntry type
• Add CustomEntry type for hooks
• Add byId: Map<string, SessionEntry> index
• Add leafId: string tracking
• Implement getPath(fromId?) tree traversal
• Implement getTree() returning SessionTreeNode[]
• Implement getEntry(id) lookup
• Implement getLeafUuid() and getLeafEntry() helpers
• Update _buildIndex() to populate byId map
• Rename saveXXX() to appendXXX() (returns id, advances leaf)
• Add appendCustomEntry(customType, data) for hooks
• Update buildSessionContext() to use getPath() traversal

Phase 2: Migration ✅

• Add CURRENT_SESSION_VERSION = 2 constant
• Implement migrateV1ToV2() with extensible migration chain
• Update setSessionFile() to detect version and migrate
• Implement _rewriteFile() for post-migration persistence
• Handle firstKeptEntryIndex → firstKeptEntryId conversion in migration

Phase 3: Branching ✅

• Implement branch(id) - switch leaf pointer
• Implement branchWithSummary(id, summary) - create summary entry
• Implement createBranchedSession(leafId) - extract path to new file
• Update AgentSession.branch() to use new API

Phase 4: Compaction Integration ✅

• Update compaction.ts to work with IDs
• Update prepareCompaction() to return firstKeptEntryId
• Update compact() to return CompactionResult with firstKeptEntryId
• Update AgentSession compaction methods
• Add firstKeptEntryId to before_compact hook event

Phase 5: Testing ✅

• migration.test.ts - v1 to v2 migration, idempotency
• build-context.test.ts - context building with tree structure, compaction, branches
• tree-traversal.test.ts - append operations, getPath, getTree, branching
• file-operations.test.ts - loadEntriesFromFile, findMostRecentSession
• save-entry.test.ts - custom entry integration
• Update existing compaction tests for new types

---

Remaining Work

Compaction Refactor

• Use CompactionResult type for hook return value
• Make CompactionEntry<T> generic with optional details?: T field for hook-specific data
• Make CompactionResult<T> generic to match
• Update SessionEventBase to pass sessionManager and modelRegistry instead of derived fields
• Update before_compact event:
  • Pass preparation: CompactionPreparation instead of individual fields
  • Pass previousCompactions: CompactionEntry[] (newest first) instead of previousSummary?: string
  • Keep: customInstructions, model, signal
  • Drop: resolveApiKey (use modelRegistry.getApiKey()), cutPoint, entries
• Update hook example custom-compaction.ts to use new API
• Update getSessionFile() to return string | undefined for in-memory sessions
• Update before_switch to have targetSessionFile, switch to have previousSessionFile

Reference: #314 - Structured compaction with anchored iterative summarization needs details field to store ArtifactIndex and version markers.

Branch Summary Design

Current type:

export interface BranchSummaryEntry extends SessionEntryBase {
  type: "branch_summary";
  summary: string;
}

Questions to resolve:

• Add abandonedLeafId field to reference what was abandoned?
• Store metadata about why the branch happened?
• Who generates the summary - user, LLM, or both options?
• Design and implement branch summarizer
• Add tests for branchWithSummary() flow

Entry Labels ✅

• Add LabelEntry type with targetId and label fields
• Add labelsById: Map<string, string> private field
• Build labels map in _buildIndex() via linear scan
• Add getLabel(id) method
• Add appendLabelChange(targetId, label) method (undefined clears)
• Update createBranchedSession() to filter out LabelEntry and recreate from resolved map
• buildSessionContext() already ignores LabelEntry (only handles message types)
• Add label?: string to SessionTreeNode, populated by getTree()
• Display labels in UI (tree view, path view) - deferred to UI phase
• /label command - deferred to UI phase

CustomMessageEntry

Hook-injected messages that participate in LLM context. Unlike CustomEntry<T> (for hook state only), these are sent to the model.

export interface CustomMessageEntry<T = unknown> extends SessionEntryBase {
  type: "custom_message";
  customType: string;                         // Hook identifier
  content: string | (TextContent | ImageContent)[];  // Message content (same as UserMessage)
  details?: T;                                // Hook-specific data for state reconstruction on reload
  display: boolean;                           // Whether to display in TUI
}

Behavior:

• Type definition matching plan
• appendCustomMessageEntry(customType, content, display, details?) in SessionManager
• buildSessionContext() includes custom_message entries as user messages
• Exported from main index
• TUI rendering:
  • display: false - hidden entirely
  • display: true - rendered with purple styling (customMessageBg, customMessageText, customMessageLabel theme colors)
  • registerCustomMessageRenderer(customType, renderer) in HookAPI for custom renderers
  • Renderer returns inner Component, TUI wraps in styled Box

Hook API Changes

Renamed:

• renderCustomMessage() → registerCustomMessageRenderer()

New: sendMessage() ✅

Replaces send(). Always creates CustomMessageEntry, never user messages.

type HookMessage<T = unknown> = Pick<CustomMessageEntry<T>, 'customType' | 'content' | 'display' | 'details'>;

sendMessage(message: HookMessage, triggerTurn?: boolean): void;

Implementation:

• Uses agent's queue mechanism with _hookData marker on AppMessage
• message_end handler routes based on marker presence
• AgentSession.sendHookMessage() handles three cases:
  • Streaming: queues via agent.queueMessage(), loop processes and emits message_end
  • Not streaming + triggerTurn: direct append + agent.continue()
  • Not streaming + no trigger: direct append only
• TUI updates via event (streaming) or explicit rebuild (non-streaming)

New: appendEntry() ✅

For hook state persistence (NOT in LLM context):

appendEntry(customType: string, data?: unknown): void;

Calls sessionManager.appendCustomEntry() directly.

New: registerCommand() (types ✅, wiring TODO)

interface CommandContext {
  args: string;                    // Everything after /commandname
  ui: HookUIContext;
  hasUI: boolean;
  cwd: string;
  sessionManager: SessionManager;
  modelRegistry: ModelRegistry;
  sendMessage: HookAPI['sendMessage'];
  exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
}

registerCommand(name: string, options: {
  description?: string;
  handler: (ctx: CommandContext) => Promise<string | undefined>;
}): void;

Handler return:

• void - command completed (use sendMessage() with triggerTurn: true to prompt LLM)

Wiring (all in AgentSession.prompt()):

• Add hook commands to autocomplete in interactive-mode
• _tryExecuteHookCommand() in AgentSession handles command execution
• Build CommandContext with ui (from hookRunner), exec, sessionManager, etc.
• If handler returns string, use as prompt text
• If handler returns undefined, return early (no LLM call)
• Works for all modes (interactive, RPC, print) via shared AgentSession

New: ui.custom()

For arbitrary hook UI with keyboard focus:

interface HookUIContext {
  // ... existing: select, confirm, input, notify
  
  /** Show custom component with keyboard focus. Call done() when finished. */
  custom(component: Component, done: () => void): void;
}

See also: CustomEntry<T> for storing hook state that does NOT participate in context.

HTML Export

• Add collapsible sidebar showing full tree structure
• Allow selecting any node in tree to view that path
• Add "reset to session leaf" button
• Render full path (no compaction resolution needed)
• Responsive: collapse sidebar on mobile

UI Commands

Design new commands based on refactored SessionManager:

/branch - Current behavior (creates new session file from path)

• Review if this is still the right UX with tree structure
• Consider: should this use createBranchedSession() or branch()?

/branch-here - In-place branching (new)

• Use branch(id) to move leaf pointer without creating new file
• Subsequent messages become new branch in same file
• Design: how to select branch point? (similar to current /branch UI?)

/branches - List/navigate branches (new)

• Show tree structure or list of branch points
• Allow switching between branches (move leaf pointer)
• Show current position in tree

Documentation

Review and update all docs:

• docs/hooks.md - Major update for hook API:
  • pi.send() → pi.sendMessage() with new signature
  • New pi.appendEntry() for state persistence
  • New pi.registerCommand() for custom slash commands
  • New pi.registerCustomMessageRenderer() for custom TUI rendering
  • CommandContext interface and handler patterns
  • HookMessage<T> type
  • Updated event signatures (SessionEventBase, before_compact, etc.)
• docs/hooks-v2.md - Review/merge or remove if obsolete
• docs/sdk.md - Update for:
  • HookAppMessage and isHookAppMessage()
  • Agent.prompt(AppMessage) overload
  • Session v2 tree structure
  • SessionManager API changes
• docs/session.md - Update for v2 tree structure, new entry types
• docs/custom-tools.md - Check if hook changes affect custom tools
• docs/rpc.md - Check if hook commands work in RPC mode
• docs/skills.md - Review for any hook-related updates
• docs/extension-loading.md - Review
• docs/theme.md - Add customMessageBg/Text/Label color tokens
• README.md - Update hook examples if any

Examples

Review and update examples:

• examples/hooks/ - Update existing, add new examples:
  • Review custom-compaction.ts for new API
  • Add registerCommand() example
  • Add sendMessage() example
  • Add registerCustomMessageRenderer() example
• examples/sdk/ - Update for new session/hook APIs
• examples/custom-tools/ - Review for compatibility

---

Notes

• All append methods return the new entry's ID
• Migration rewrites file on first load if version < CURRENT_VERSION
• Existing sessions become linear chains after migration (parentId = previous entry)
• Tree features available immediately after migration
• SessionHeader does NOT have id/parentId (it's metadata, not part of tree)
• Session is append-only: entries cannot be modified or deleted, only branching changes the leaf pointer