mirror of
https://github.com/getcompanion-ai/co-mono.git
synced 2026-04-15 17:00:59 +00:00
Add session tree format design doc
This commit is contained in:
Mario Zechner
parent
6d97d212d5
commit
351faef604
1 changed files with 379 additions and 0 deletions
379
packages/coding-agent/docs/session-tree.md
Normal file
379
packages/coding-agent/docs/session-tree.md
Normal file
|
|
@ -0,0 +1,379 @@
|
|||
# Session Tree Format
|
||||
|
||||
Analysis of switching from linear JSONL to tree-based session storage.
|
||||
|
||||
## Current Format (Linear)
|
||||
|
||||
```jsonl
|
||||
{"type":"session","id":"...","timestamp":"...","cwd":"..."}
|
||||
{"type":"message","timestamp":"...","message":{"role":"user",...}}
|
||||
{"type":"message","timestamp":"...","message":{"role":"assistant",...}}
|
||||
{"type":"compaction","timestamp":"...","summary":"...","firstKeptEntryIndex":2,"tokensBefore":50000}
|
||||
{"type":"message","timestamp":"...","message":{"role":"user",...}}
|
||||
```
|
||||
|
||||
Context is built by scanning linearly, applying compaction ranges.
|
||||
|
||||
## Proposed Format (Tree)
|
||||
|
||||
Each entry has a `parent` field pointing to its parent entry's index (-1 for root):
|
||||
|
||||
```jsonl
|
||||
{"type":"session","id":"...","parent":-1} // 0: root
|
||||
{"type":"message","parent":0,"message":{"role":"user",...}} // 1
|
||||
{"type":"message","parent":1,"message":{"role":"assistant",...}} // 2
|
||||
{"type":"message","parent":2,"message":{"role":"user",...}} // 3
|
||||
{"type":"message","parent":3,"message":{"role":"assistant",...}} // 4
|
||||
{"type":"head","parent":4,"name":"main"} // 5: current head
|
||||
```
|
||||
|
||||
The **last entry** is always the current leaf. Context = walk from leaf to root.
|
||||
|
||||
### Branching
|
||||
|
||||
Branch from entry 2 (after first assistant response):
|
||||
|
||||
```jsonl
|
||||
... entries 0-5 unchanged ...
|
||||
{"type":"message","parent":2,"message":{"role":"user",...}} // 6: new branch
|
||||
{"type":"message","parent":6,"message":{"role":"assistant",...}} // 7
|
||||
{"type":"head","parent":7,"name":"main"} // 8: new head
|
||||
```
|
||||
|
||||
Now entry 8 is the leaf. Walking 8→7→6→2→1→0 gives the branched context.
|
||||
|
||||
The old path (entries 3-5) remains in the file but is not in the current context.
|
||||
|
||||
### Visual
|
||||
|
||||
```
|
||||
[0:session]
|
||||
│
|
||||
[1:user "hello"]
|
||||
│
|
||||
[2:assistant "hi"]
|
||||
│
|
||||
┌────┴────┐
|
||||
│ │
|
||||
[3:user A] [6:user B] ← branch point at 2
|
||||
│ │
|
||||
[4:asst A] [7:asst B]
|
||||
│ │
|
||||
(old) [8:head] ← current leaf
|
||||
```
|
||||
|
||||
## Context Building
|
||||
|
||||
```typescript
|
||||
function buildContext(entries: SessionEntry[]): AppMessage[] {
|
||||
// Find current head (last entry, or last head entry)
|
||||
let current = entries.length - 1;
|
||||
|
||||
// Walk to root, collecting messages
|
||||
const path: SessionEntry[] = [];
|
||||
while (current >= 0) {
|
||||
const entry = entries[current];
|
||||
path.unshift(entry);
|
||||
current = entry.parent;
|
||||
}
|
||||
|
||||
// Extract messages, apply compaction summaries
|
||||
return pathToMessages(path);
|
||||
}
|
||||
```
|
||||
|
||||
Complexity: O(depth) instead of O(n) for linear scan.
|
||||
|
||||
## Consequences for Stacking
|
||||
|
||||
### Current Approach (hooks-v2.md)
|
||||
|
||||
Stacking uses `stack_pop` entries with complex range overlap rules:
|
||||
|
||||
```typescript
|
||||
interface StackPopEntry {
|
||||
type: "stack_pop";
|
||||
backToIndex: number;
|
||||
summary: string;
|
||||
prePopSummary?: string;
|
||||
}
|
||||
```
|
||||
|
||||
Context building requires tracking ranges, IDs, "later wins" logic.
|
||||
|
||||
### Tree Approach
|
||||
|
||||
Stacking becomes trivial branching:
|
||||
|
||||
```jsonl
|
||||
... conversation entries 0-10 ...
|
||||
{"type":"stack_summary","parent":3,"summary":"Work done in entries 4-10"} // 11
|
||||
{"type":"head","parent":11} // 12
|
||||
```
|
||||
|
||||
To "pop" to entry 3:
|
||||
1. Generate summary of entries 4-10
|
||||
2. Append summary entry with `parent:3`
|
||||
3. Append new head
|
||||
|
||||
Context walk: 12→11→3→2→1→0. Entries 4-10 are not traversed.
|
||||
|
||||
**No range tracking. No overlap rules. No "later wins" logic.**
|
||||
|
||||
### Multiple Pops
|
||||
|
||||
```
|
||||
[0]─[1]─[2]─[3]─[4]─[5]─[6]─[7]─[8]
|
||||
│
|
||||
└─[9:summary of 4-8]─[10]─[11]─[12]
|
||||
│
|
||||
└─[13:summary of 10-12]─[14:head]
|
||||
```
|
||||
|
||||
Each pop just creates a new branch. Context: 14→13→9→3→2→1→0.
|
||||
|
||||
## Consequences for Compaction
|
||||
|
||||
### Current Approach
|
||||
|
||||
Compaction stores `firstKeptEntryIndex` and requires careful handling when stacking crosses compaction boundaries.
|
||||
|
||||
### Tree Approach
|
||||
|
||||
Compaction creates a summary node:
|
||||
|
||||
```jsonl
|
||||
{"type":"compaction","parent":0,"summary":"...","summarizedPath":[1,2,3,4,5]} // 6
|
||||
{"type":"message","parent":6,"message":{"role":"user",...}} // 7
|
||||
```
|
||||
|
||||
The compaction node's `parent:0` means it attaches to root. Walking from 7: 7→6→0.
|
||||
|
||||
Entries 1-5 are still in the file (for export, debugging) but not in context.
|
||||
|
||||
### Compaction + Stacking
|
||||
|
||||
No special handling needed. They're both just branches:
|
||||
|
||||
```
|
||||
[0]─[1]─[2]─[3]─[4]─[5]
|
||||
│
|
||||
└─[6:compaction summary]─[7]─[8]─[9]─[10]
|
||||
│
|
||||
└─[11:stack summary]─[12:head]
|
||||
```
|
||||
|
||||
Context: 12→11→7→6→0. Clean.
|
||||
|
||||
## Consequences for API
|
||||
|
||||
### SessionManager Changes
|
||||
|
||||
```typescript
|
||||
interface SessionEntry {
|
||||
type: string;
|
||||
parent: number; // NEW: -1 for root, otherwise index of parent
|
||||
timestamp?: string;
|
||||
// ... type-specific fields
|
||||
}
|
||||
|
||||
class SessionManager {
|
||||
// NEW: Get current head index
|
||||
getCurrentHead(): number;
|
||||
|
||||
// NEW: Walk from entry to root
|
||||
getPath(fromIndex?: number): SessionEntry[];
|
||||
|
||||
// CHANGED: Uses tree walk instead of linear scan
|
||||
buildSessionContext(): SessionContext;
|
||||
|
||||
// NEW: Create branch point, returns new head index
|
||||
branch(parentIndex: number): number;
|
||||
|
||||
// NEW: Create branch with summary of abandoned subtree
|
||||
branchWithSummary(parentIndex: number, summary: string): number;
|
||||
|
||||
// CHANGED: Simpler, just creates summary node
|
||||
saveCompaction(entry: CompactionEntry): void;
|
||||
|
||||
// UNCHANGED
|
||||
saveMessage(message: AppMessage): void;
|
||||
saveEntry(entry: SessionEntry): void;
|
||||
}
|
||||
```
|
||||
|
||||
### AgentSession Changes
|
||||
|
||||
```typescript
|
||||
class AgentSession {
|
||||
// CHANGED: Uses tree-based branching
|
||||
async branch(entryIndex: number): Promise<BranchResult>;
|
||||
|
||||
// NEW: Branch in current session (no new file)
|
||||
async branchInPlace(entryIndex: number, options?: {
|
||||
summarize?: boolean; // Generate summary of abandoned subtree
|
||||
}): Promise<void>;
|
||||
|
||||
// NEW: Get tree structure for visualization
|
||||
getSessionTree(): SessionTree;
|
||||
|
||||
// CHANGED: Simpler implementation
|
||||
async compact(): Promise<CompactionResult>;
|
||||
}
|
||||
|
||||
interface BranchResult {
|
||||
selectedText: string;
|
||||
cancelled: boolean;
|
||||
newSessionFile?: string; // If branching to new file
|
||||
inPlace: boolean; // If branched in current file
|
||||
}
|
||||
```
|
||||
|
||||
### Hook API Changes
|
||||
|
||||
```typescript
|
||||
interface HookEventContext {
|
||||
// NEW: Tree-aware entry access
|
||||
entries: readonly SessionEntry[];
|
||||
currentPath: readonly SessionEntry[]; // Entries from root to current head
|
||||
|
||||
// NEW: Branch without creating new file
|
||||
branchInPlace(parentIndex: number, summary?: string): Promise<void>;
|
||||
|
||||
// Existing
|
||||
saveEntry(entry: SessionEntry): Promise<void>;
|
||||
rebuildContext(): Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
## New Features Enabled
|
||||
|
||||
### 1. In-Place Branching
|
||||
|
||||
Currently, `/branch` always creates a new session file. With tree format:
|
||||
|
||||
```
|
||||
/branch → Create new session file (current behavior)
|
||||
/branch-here → Branch in current file, optionally with summary
|
||||
```
|
||||
|
||||
Use case: Quick "let me try something else" without file proliferation.
|
||||
|
||||
### 2. Branch History Navigation
|
||||
|
||||
```
|
||||
/branches → List all branches in current session
|
||||
/switch 3 → Switch to branch starting at entry 3
|
||||
```
|
||||
|
||||
The session file contains full history. UI can visualize the tree.
|
||||
|
||||
### 3. Simpler Stacking
|
||||
|
||||
No hooks needed for basic stacking:
|
||||
|
||||
```
|
||||
/pop → Branch to previous user message with auto-summary
|
||||
/pop 5 → Branch to entry 5 with auto-summary
|
||||
```
|
||||
|
||||
Core functionality, not hook-dependent.
|
||||
|
||||
### 4. Subtree Export
|
||||
|
||||
```
|
||||
/export-branch 3 → Export just the subtree from entry 3
|
||||
```
|
||||
|
||||
Useful for sharing specific conversation paths.
|
||||
|
||||
### 5. Merge/Cherry-pick (Future)
|
||||
|
||||
With tree structure, could support:
|
||||
|
||||
```
|
||||
/cherry-pick 7 → Copy entry 7's message to current branch
|
||||
/merge 3 → Merge branch at entry 3 into current
|
||||
```
|
||||
|
||||
## Migration
|
||||
|
||||
### File Format
|
||||
|
||||
Add `parent` field to all entries. Existing sessions get `parent: previousIndex`:
|
||||
|
||||
```typescript
|
||||
function migrateSession(content: string): string {
|
||||
const lines = content.trim().split('\n');
|
||||
return lines.map((line, i) => {
|
||||
const entry = JSON.parse(line);
|
||||
entry.parent = i === 0 ? -1 : i - 1; // Linear chain
|
||||
return JSON.stringify(entry);
|
||||
}).join('\n');
|
||||
}
|
||||
```
|
||||
|
||||
Migrated sessions work exactly as before (linear path).
|
||||
|
||||
### API Compatibility
|
||||
|
||||
- `buildSessionContext()` returns same structure
|
||||
- `branch()` still works, just more options
|
||||
- Existing hooks continue to work
|
||||
|
||||
## Complexity Analysis
|
||||
|
||||
| Operation | Linear | Tree |
|
||||
|-----------|--------|------|
|
||||
| Append message | O(1) | O(1) |
|
||||
| Build context | O(n) | O(depth) |
|
||||
| Branch | O(n) copy | O(1) append |
|
||||
| Find entry | O(n) | O(n) |
|
||||
| Compaction | O(n) | O(depth) |
|
||||
|
||||
Tree is better or equal for all operations except "find arbitrary entry" (same).
|
||||
|
||||
## File Size
|
||||
|
||||
Tree format adds ~15 bytes per entry (`"parent":123,`). For 1000-entry session: ~15KB overhead. Negligible.
|
||||
|
||||
Abandoned branches remain in file but don't affect context building performance.
|
||||
|
||||
## Example: Full Session with Branching
|
||||
|
||||
```jsonl
|
||||
{"type":"session","id":"abc","parent":-1,"cwd":"/project"}
|
||||
{"type":"message","parent":0,"message":{"role":"user","content":"Build a CLI"}}
|
||||
{"type":"message","parent":1,"message":{"role":"assistant","content":"I'll create..."}}
|
||||
{"type":"message","parent":2,"message":{"role":"user","content":"Add --verbose flag"}}
|
||||
{"type":"message","parent":3,"message":{"role":"assistant","content":"Here's the flag..."}}
|
||||
{"type":"message","parent":4,"message":{"role":"user","content":"Actually use Python"}}
|
||||
{"type":"message","parent":5,"message":{"role":"assistant","content":"Converting to Python..."}}
|
||||
{"type":"branch_summary","parent":2,"summary":"Attempted Node.js CLI with --verbose flag"}
|
||||
{"type":"message","parent":7,"message":{"role":"user","content":"Use Rust instead"}}
|
||||
{"type":"message","parent":8,"message":{"role":"assistant","content":"Creating Rust CLI..."}}
|
||||
{"type":"head","parent":9}
|
||||
```
|
||||
|
||||
Context path: 10→9→8→7→2→1→0
|
||||
|
||||
Result:
|
||||
1. User: "Build a CLI"
|
||||
2. Assistant: "I'll create..."
|
||||
3. Summary: "Attempted Node.js CLI with --verbose flag"
|
||||
4. User: "Use Rust instead"
|
||||
5. Assistant: "Creating Rust CLI..."
|
||||
|
||||
Entries 3-6 (the Node.js path) are preserved but not in context.
|
||||
|
||||
## Recommendation
|
||||
|
||||
The tree format:
|
||||
- Simplifies stacking (no range overlap logic)
|
||||
- Simplifies compaction (no boundary crossing)
|
||||
- Enables in-place branching
|
||||
- Enables branch visualization/navigation
|
||||
- Maintains backward compatibility
|
||||
- Has negligible overhead
|
||||
|
||||
**Recommend implementing for v2 of hooks/session system.**
|
||||
Loading…
Add table
Add a link
Reference in a new issue