Session Management & Chat
Relevant source files
The following files were used as context for generating this wiki page:
Session Management & Chat handles the lifecycle, state, and user interface for interactions between users and AI agents. It coordinates multiple AI providers (harnesses), manages conversation history through transcripts, and provides a command interface for agents to interact with the application environment.
This system enables long-running tasks by supporting background execution, session delegation, and persistent storage of conversation blocks. It serves as the primary interface for both manual user interaction and automated agent orchestration.
Session Architecture and Data Model
The core of the system is the Session object, which represents an isolated instance of an agent interaction within a specific project directory. Each session tracks its AI harness, model settings, and a sequence of conversation blocks.
Core Session Structure
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the session. |
cwd | string | The project directory the session operates within. |
harness | HarnessId | The AI provider (e.g., codex, claude, cursor). |
model | string | The specific model ID used for the session. |
blocks | Block[] | An array of conversation entries (user, assistant, tool, etc.). |
busy | boolean | Indicates if a turn is currently in progress. |
runtimeMode | string | Permission level (e.g., supervised, full-access). |
Sources: src/features/sessions/model/session.ts:10-50, src/features/agent-app/model/agentApp.ts:50-60
Conversation Blocks
Transcripts consist of Block objects. A block represents a single turn or action within the chat.
Agent App Command Interface
The Agent App interface allows agents to call internal application functions via a CLI-like JSON interface. This enables agents to manage other sessions, read notes, and interact with the filesystem.
Command Execution Flow
When an agent or user issues a command (e.g., sessions.start), the handleAgentApp function validates inputs and dispatches the action to the appropriate handler.
Supported Session Actions
| Action | Parameters | Description |
|---|---|---|
sessions.list | project | Lists all sessions in a specific project. |
sessions.read | sessionId, before, limit | Returns a paginated view of a session's history. |
sessions.start | prompt, model, workspaceMode | Launches a new background or foreground session. |
sessions.send | sessionId, prompt | Sends a follow-up message to an existing session. |
sessions.stop | sessionId | Interrupts a running agent turn. |
Sources: src/features/agent-app/model/agentApp.ts:130-160, src/features/agent-app/model/agentApp.ts:580-650
Transcript Rendering and UI
The AgentTranscript component renders the conversation history. It handles complex states such as streaming text, tool execution progress, and multi-agent orchestration.
UI Features
- Streaming Support: Displays partial results as the AI generates text, keeping the interface responsive.
- Activity Folding: Collapses multiple tool calls (e.g., shell commands) into a "Show the work" summary to keep the transcript readable.
- Interjections: Renders system-level messages or advisor feedback between agent turns.
- Pilot Context: Credits turns to a specific "Pilot" identity regardless of the underlying model used.
Sources: src/features/sessions/ui/AgentTranscript.test.ts:100-250, src/features/sessions/ui/AgentTranscript.test.ts:500-600
Message Formatting Logic
transcripts omit internal reasoning or secret tool outputs when generating a user-facing view, focusing only on the final assistant response and the user's intent.
Persistence and State Management
Sessions are persisted to local storage to survive application restarts. The system uses a fingerprinting mechanism to detect changes and avoid redundant writes.
Sanitization Process
Before saving, sessions are sanitized to:
- Drop large binary payloads from generated images.
- Remove path-like session IDs that are specific to a single environment.
- Preserve metadata for "In-Between" (BTW) threads and linked GitHub work items.
- Retain the last 100 steps of long subagent runs to manage storage limits.
Sources: src/features/sessions/data/sessionStore.test.ts:350-450, src/features/sessions/data/sessionStore.test.ts:550-600
Session Delegation and Orchestration
Agents can start "sub-sessions" to delegate specific tasks. This is governed by orchestration metadata within plan blocks.
- Lead Sessions: Manage the high-level goal and delegate parts to worker sessions.
- Worker Sessions: Receive a specific scope (e.g., a file path) and report back to the lead.
- Completion Notifications: When a delegated session finishes, the lead session is notified and resumes to integrate the results.
Sources: src/features/sessions/ui/AgentTranscript.test.ts:150-180, src/features/agent-app/model/agentApp.ts:80-100
Session Management & Chat provides the infrastructure for robust AI-driven workflows by combining a flexible command interface with a sophisticated UI for monitoring complex agent behaviors. It ensures that conversation history is both readable for humans and actionable for machines.