Session Management

{"type":"session","version":3,"id":"abc123","timestamp":"2024-01-01T00:00:00.000Z","cwd":"/home/user/project"}
{"type":"message","id":"def456","parentId":null,"timestamp":"2024-01-01T00:00:00.000Z","message":{"role":"user","content":[{"type":"text","text":"Hello"}],"timestamp":1704067200000}}
{"type":"message","id":"ghi789","parentId":"def456","timestamp":"2024-01-01T00:00:05.000Z","message":{"role":"assistant","content":[{"type":"text","text":"Hi!"}],"timestamp":1704067205000}}

type SessionEntry =
  | SessionMessageEntry      // User, assistant, or toolResult messages
  | ThinkingLevelChangeEntry // Thinking level changes
  | ModelChangeEntry         // Model changes
  | CompactionEntry          // Context compaction summaries
  | BranchSummaryEntry       // Branch summaries
  | CustomEntry              // Extension state (not sent to LLM)
  | CustomMessageEntry       // Extension messages (sent to LLM)
  | LabelEntry               // User-defined bookmarks
  | SessionInfoEntry;        // Session metadata (display name)

Session Header
  ├─ Entry A (parentId: null)
  │   ├─ Entry B (parentId: A)
  │   │   └─ Entry C (parentId: B)  ← leaf
  │   └─ Entry D (parentId: A)       ← branch point
  │       └─ Entry E (parentId: D)  ← alternate branch
  └─ Entry F (parentId: null)       ← separate root

import { SessionManager } from "@mariozechner/pi-coding-agent";

const session = SessionManager.create(process.cwd());

// Append some messages
session.appendMessage(userMessage1);   // Entry A
session.appendMessage(assistantMsg1);  // Entry B (child of A)
session.appendMessage(userMessage2);   // Entry C (child of B)

// Branch from Entry A
session.branch("entry-a-id");

// Next append creates a child of A (not C)
session.appendMessage(userMessage3);   // Entry D (child of A)

A
├─ B
│  └─ C
└─ D  ← new leaf

import { SessionManager } from "@mariozechner/pi-coding-agent";

// Create new session (auto-generates file path)
const session = SessionManager.create(process.cwd());

// Open existing session
const session = SessionManager.open("/path/to/session.jsonl");

// Continue most recent session
const session = SessionManager.continueRecent(process.cwd());

// Fork from another project
const session = SessionManager.forkFrom(
  "/other/project/session.jsonl",
  process.cwd()
);

~/.pi/agent/sessions/
├── --home-user-project1--/
│   ├── 2024-01-01T12-00-00-000Z_abc123.jsonl
│   └── 2024-01-02T09-30-00-000Z_def456.jsonl
└── --home-user-project2--/
    └── 2024-01-03T14-15-00-000Z_ghi789.jsonl

// Append messages
session.appendMessage({
  role: "user",
  content: [{ type: "text", text: "Hello" }],
  timestamp: Date.now(),
});

// Append model changes
session.appendModelChange("anthropic", "claude-sonnet-4-20250514");

// Append thinking level changes
session.appendThinkingLevelChange("high");

// Append custom entries (extension state)
session.appendCustomEntry("my-extension", { state: "data" });

// Append custom messages (sent to LLM)
session.appendCustomMessageEntry(
  "context",
  "Additional context",
  true,  // display in UI
  { source: "external" }
);

const { messages, thinkingLevel, model } = session.buildSessionContext();

// Or build from a specific entry
const context = session.buildSessionContext(entryId);

// Example path with compaction:
[
  Entry A (user),
  Entry B (assistant),
  Entry C (user),
  Entry D (compaction, firstKeptEntryId: C),  ← summary point
  Entry E (user),
  Entry F (assistant)
]

// Resulting messages:
[
  { role: "compactionSummary", summary: "..." },  // From Entry D
  { role: "user", ... },                          // Entry C
  { role: "user", ... },                          // Entry E
  { role: "assistant", ... }                      // Entry F
]

contextTokens > contextWindow - reserveTokens

## Goal
[What is the user trying to accomplish?]

## Constraints & Preferences
- [User requirements]

## Progress
### Done
- [x] Completed tasks

### In Progress
- [ ] Current work

## Key Decisions
- **Decision**: Rationale

## Next Steps
1. What should happen next

## Critical Context
- Important data/examples

## Files
- Read: file1.ts, file2.ts
- Modified: file3.ts

import { AgentSession } from "@mariozechner/pi-coding-agent";

const session = new AgentSession({ /* ... */ });

// Compact with optional custom instructions
const result = await session.compact(
  "Focus on architectural decisions"
);

console.log("Compacted from", result.tokensBefore, "tokens");
console.log("Summary:", result.summary);

pi.on("session_before_compact", async (event, ctx) => {
  const { preparation, signal } = event;
  
  // Generate custom summary
  const summary = await generateStructuredSummary(
    preparation.messagesToSummarize,
    signal
  );
  
  return {
    compaction: {
      summary,
      firstKeptEntryId: preparation.firstKeptEntryId,
      tokensBefore: preparation.tokensBefore,
      details: { customData: "..." },
    },
  };
});

// Get the full tree structure
const tree = session.getTree();

// Walk from specific entry to root
const path = session.getBranch(entryId);

// Get all entries (flat list)
const entries = session.getEntries();

// Get specific entry
const entry = session.getEntry(entryId);

// Get direct children
const children = session.getChildren(entryId);

// Set label
session.appendLabelChange(entryId, "Before refactor");

// Get label
const label = session.getLabel(entryId);

// Clear label
session.appendLabelChange(entryId, undefined);

interface SessionTreeNode {
  entry: SessionEntry;
  children: SessionTreeNode[];
  label?: string;  // Resolved from latest LabelEntry
}

import { AgentSession } from "@mariozechner/pi-coding-agent";

const session = new AgentSession({ /* ... */ });

// Navigate to different branch with summary
await session.navigateTree(entryId, {
  summarize: true,
  customInstructions: "Focus on why we're changing direction",
  label: "Tried async approach",
});

session.appendSessionInfo("Refactor authentication");

const name = session.getSessionName();
// "Refactor authentication"

const sessions = await SessionManager.list(process.cwd());

for (const info of sessions) {
  console.log(info.name);              // Display name
  console.log(info.path);              // File path
  console.log(info.cwd);               // Working directory
  console.log(info.created);           // Creation date
  console.log(info.modified);          // Last activity
  console.log(info.messageCount);      // Total messages
  console.log(info.firstMessage);      // First user message
  console.log(info.parentSessionPath); // Parent (if forked)
}

// Fork session from another project into current project
const session = SessionManager.forkFrom(
  "/other/project/sessions/session.jsonl",
  process.cwd(),
  "/path/to/target/sessions"  // optional
);