Session Pool

How AgentDesk manages Claude Code SDK sessions across agents.

The session pool is a process-level singleton that manages Claude Code SDK sessions for all agents. It handles session creation, resumption, concurrency, and event streaming.

Architecture

The session pool does not keep long-lived subprocesses between turns. Instead, it uses the Claude Code SDK’s resume feature:

First turn — the SDK spawns a new session and emits a system/init event with a session ID
Session ID saved — the ID is stored in agents.cc_session_id in the database
Subsequent turns — each query() call passes resume: sessionId, loading the conversation history from disk

Session state lives as .jsonl files in ~/.claude/projects/. This means sessions survive process restarts — the agent picks up where it left off.

Concurrency Model

Turns to the same agent are serialized — one at a time
Turns to different agents run in parallel
The dispatcher’s running Set coordinates this

Event Types

Each turn emits a stream of typed events:

Event	Description
`init`	Session initialized, contains session ID
`assistant-text`	Token-by-token text from the agent
`tool-use`	Agent invoked a tool (file read, shell, etc.)
`tool-progress`	Progress update for a running tool
`tool-result`	Tool execution completed
`result-success`	Turn completed successfully
`result-error`	Turn failed with an error
`status`	Agent status change
`command-output`	Shell command output

Events are streamed to the WebSocket hub for real-time display in the chat UI.

Effort Levels

The SDK supports effort levels that control response depth:

Level	Usage
`low`	Quick answers, simple lookups
`medium`	Moderate analysis
`high`	Default for interactive chat
`max`	Most thorough analysis

Interactive chat defaults to high. Dispatcher and scheduler turns use the SDK’s default effort level to avoid silent cost overruns.

Isolated Turns

The dispatcher uses sendIsolatedTurnAndCollect for heartbeat and cron turns. These create temporary sessions that don’t pollute the agent’s main chat history — the main session remains clean for human interaction.