Chat session observation API for extension-owned evaluation and tooling

Start by reviewing vscode.proposed.chatSessionsProvider.d.ts and vscode.proposed.chatParticipantPrivate.d.ts to understand the existing provider and observer surfaces. Compare those APIs with the proposed session enumeration, history, and lifecycle requirements. Done would require an agreed public read-only API design covering those gaps.

Extensions currently have no supported way to inspect chat sessions other than the active one. The only workable path today is to read private storage directly, usually workspaceStorage/{hash}/chatSessions/*.jsonl plus state.vscdb.

That private storage format is already breaking extensions in production. A proposed API for read-only chat session observation would give extension authors a supported path for session-level tooling without depending on VS Code internals.

Use cases

1. Agent evaluation: read a completed session to identify friction patterns and improve guidance for future sessions
2. Supervisory dashboards: show active sessions across workspaces with rate limit risk, session size, and agent status
3. Cross-session search: answer questions like "which session discussed the pool config issue last week?"
4. Session lifecycle automation: trigger evaluation when a session ends, or archive stale sessions

Proposed API surface

namespace vscode.chat {
  // Enumerate sessions (all workspaces in window)
  export function getSessions(filter?: ChatSessionFilter): Thenable<ChatSessionInfo[]>;
  
  // Read structured history (no JSONL parsing needed)
  export function getSessionHistory(sessionId: string): Thenable<ChatSessionHistory>;
  
  // Lifecycle events
  export const onDidCreateSession: Event<ChatSessionInfo>;
  export const onDidChangeSession: Event<ChatSessionChangeEvent>;
  export const onDidEndSession: Event<ChatSessionInfo>;
}

interface ChatSessionInfo {
  sessionId: string;
  title: string;
  agentMode?: string;
  model?: string;
  createdAt: number;
  lastModifiedAt: number;
  sizeBytes: number;
  isArchived: boolean;
  workspaceUri?: Uri;
}

interface ChatSessionHistory {
  turns: (ChatRequestTurn | ChatResponseTurn)[];
}

interface ChatSessionChangeEvent {
  sessionId: string;
  kind: 'newTurn' | 'archived' | 'titleChanged' | 'ended';
}

Current workarounds and why they are fragile

The private storage format is not a stable extension API. Related reports already show the failure modes:

• #291374: extensions parsing workspaceStorage/{hash}/chatSessions/*.jsonl crash on format changes
• #308381: JSONL parsing of ChatSessionItemCollection closed as not planned
• #295334: 10.45 MB session JSONL overflow and renderer crash during a 20-turn agent session
• #314556: base64 image payloads inline in chatSessions/*.jsonl cause unbounded file growth

Current workarounds in the wild include:

• Direct JSONL file parsing, with an undocumented format that changes between versions
• Custom zero-dependency SQLite readers for state.vscdb
• File watchers on chatSessions/ directories, with polling and no lifecycle semantics
• Process enumeration plus presence beacons for active session detection

Relationship to existing proposed APIs

This seems to sit between two existing surfaces.

1. vscode.proposed.chatSessionsProvider.d.ts is the provider/write side. It lets an extension register a custom session backend. The extension owns and renders the sessions it provides. It does not provide a way to query history for sessions owned by Copilot or VS Code itself.

   The observer API proposed here would be the read-side complement: providers register what they own, observers query what exists.

2. vscode.proposed.chatParticipantPrivate.d.ts has a small private observer surface today:

   • chat.onDidDisposeChatSession: Event<string>: weak analogue of onDidEndSession, but it only returns a session ID
   • window.activeChatPanelSessionResource: Uri | undefined: focused session only, no enumeration
   • window.onDidChangeActiveChatPanelSessionResource: Event<Uri | undefined>: focus change only, not a general session change event

These cover part of the need, but the main gaps remain:

• enumerate all sessions
• read structured history by session ID
• observe create/change/end lifecycle events from third-party extensions

Related issue

#316946: Copilot Mobile Companion identifies the same API gap from a different use case. It notes that "no public Chat API exposes Copilot Chat history or accepts injected prompts into existing sessions."

This proposal is focused only on the read/observation side: session enumeration, structured history access, and lifecycle events.