Skip to main content

claude_code_agent/
pool.rs

1//! Session pool — pre-warmed persistent processes with idle reuse.
2//!
3//!   - at most `max_sessions` sessions are checked out at once (semaphore)
4//!   - every session uses `PoolConfig::options` (hooks, MCP servers, model, …)
5//!   - `acquire_with(Checkout { model, effort, permission_mode })` hands out
6//!     a session with its own model, effort or permission mode; `None`
7//!     keeps the pool's value
8//!   - a returned session is reset before it is handed out again: `/clear`
9//!     empties the conversation, and model, effort and permission mode are
10//!     set for the next checkout, so a task may change them for itself
11//!     (`set_model`, `set_effort`, `set_permission_mode`) without affecting
12//!     the next one. A permission mode left `None` is the one the session
13//!     started in (the settings' `permissions.defaultMode`, else `default`)
14//!   - dead sessions are dropped and replaced by a fresh spawn
15//!   - a checkout asking for `bypassPermissions` gets a session started in
16//!     it: the CLI switches to that mode only when it started in it
17//!   - a session is not reused when its turn is still running, when the CLI
18//!     cannot `/clear` it (`SessionOptions::disable_slash_commands`), or
19//!     when `max_sessions` sessions are idle already; it ends once its last
20//!     handle is dropped (until then it runs outside the `max_sessions`
21//!     count)
22use std::sync::atomic::{AtomicU64, Ordering};
23use std::sync::{Arc, Mutex, MutexGuard, PoisonError};
24
25use tokio::sync::Semaphore;
26use tokio_stream::StreamExt;
27
28use crate::agent::{Agent, AgentEvent};
29use crate::protocol::{Effort, Initialize, PermissionMode};
30use crate::session::{Result, Session, SessionError, SessionOptions};
31
32/// Configuration of a `SessionPool`.
33#[derive(Debug, Clone)]
34pub struct PoolConfig {
35    /// Most sessions checked out at once. Default 4.
36    pub max_sessions: usize,
37    /// Options every pooled session is spawned with (`cwd`, hooks, …).
38    /// `record` names a pattern: session N records to `<stem>.N.<ext>`
39    /// (`hi.jsonl` → `hi.1.jsonl`, `hi.2.jsonl`, …), one file each.
40    pub options: SessionOptions,
41}
42
43impl Default for PoolConfig {
44    fn default() -> Self {
45        Self { max_sessions: 4, options: SessionOptions::default() }
46    }
47}
48
49/// Settings for one checkout. `None` keeps the value from
50/// `PoolConfig::options`.
51#[derive(Debug, Clone, Default, PartialEq)]
52pub struct Checkout {
53    /// Model (`Session::set_model`).
54    pub model: Option<String>,
55    /// Effort level (`Session::set_effort`).
56    pub effort: Option<Effort>,
57    /// Permission mode (`Session::set_permission_mode`).
58    pub permission_mode: Option<PermissionMode>,
59}
60
61impl Checkout {
62    /// The pool's options with this checkout's settings applied.
63    fn options(&self, base: &SessionOptions) -> SessionOptions {
64        SessionOptions {
65            model: self.model.clone().or_else(|| base.model.clone()),
66            effort: self.effort.or(base.effort),
67            permission_mode: self.permission_mode.or(base.permission_mode),
68            ..base.clone()
69        }
70    }
71}
72
73struct Idle {
74    session: Session,
75    /// Holds a previous task's conversation; needs `/clear` before reuse.
76    used: bool,
77}
78
79struct PoolInner {
80    idle: Mutex<Vec<Idle>>,
81    semaphore: Arc<Semaphore>,
82    config: PoolConfig,
83    /// Sessions spawned so far; numbers their recording files.
84    spawned: AtomicU64,
85}
86
87/// A pool of pre-warmed Claude sessions. Cheap to clone.
88#[derive(Clone)]
89pub struct SessionPool(Arc<PoolInner>);
90
91impl SessionPool {
92    /// An empty pool; sessions spawn on `warm` or `acquire`.
93    #[must_use]
94    pub fn new(config: PoolConfig) -> Self {
95        let max = config.max_sessions;
96        SessionPool(Arc::new(PoolInner {
97            idle: Mutex::new(Vec::with_capacity(max)),
98            semaphore: Arc::new(Semaphore::new(max)),
99            config,
100            spawned: AtomicU64::new(0),
101        }))
102    }
103
104    /// Spawn up to `n` idle sessions in parallel, within `max_sessions`
105    /// idle plus checked-out sessions. Returns how many were added.
106    pub async fn warm(&self, n: usize) -> usize {
107        let room = self.0.semaphore.available_permits().saturating_sub(self.idle().len());
108        let count = n.min(room);
109        // Held while spawning, so a concurrent acquire() cannot spawn past the limit.
110        let Ok(permits) = u32::try_from(count) else { return 0 };
111        let Ok(_permits) = Arc::clone(&self.0.semaphore).try_acquire_many_owned(permits) else {
112            return 0;
113        };
114        let tasks: Vec<_> = (0..count)
115            .map(|_| {
116                let opts = self.spawn_options(self.0.config.options.clone());
117                tokio::spawn(async move { Session::spawn(opts, Initialize::default()).await })
118            })
119            .collect();
120        let mut warmed = 0;
121        for t in tasks {
122            match t.await {
123                Ok(Ok(session)) => {
124                    self.idle().push(Idle { session, used: false });
125                    warmed += 1;
126                }
127                Ok(Err(e)) => tracing::warn!(error = %e, "pool warm-up spawn failed"),
128                Err(e) => tracing::warn!(error = %e, "pool warm-up task failed"),
129            }
130        }
131        warmed
132    }
133
134    /// Check out a session with an empty conversation and the pool's
135    /// settings; waits while `max_sessions` are checked out.
136    pub async fn acquire(&self) -> Result<PooledSession> {
137        self.acquire_with(Checkout::default()).await
138    }
139
140    /// Check out a session with an empty conversation and `checkout`'s
141    /// model, effort and permission mode; waits while `max_sessions` are
142    /// checked out.
143    pub async fn acquire_with(&self, checkout: Checkout) -> Result<PooledSession> {
144        let permit = Arc::clone(&self.0.semaphore)
145            .acquire_owned()
146            .await
147            .map_err(|_| SessionError::Closed)?;
148        let options = checkout.options(&self.0.config.options);
149
150        loop {
151            let next = {
152                let mut idle = self.idle();
153                idle.iter().rposition(|i| can_take(&i.session, &options)).map(|i| idle.remove(i))
154            };
155            let Some(Idle { session, used }) = next else { break };
156            if !session.is_alive() {
157                continue;
158            }
159            // An unused session already runs the pool's settings.
160            let prepared = match (used, checkout == Checkout::default()) {
161                (false, true) => Ok(()),
162                (false, false) => apply(&session, &options).await,
163                (true, _) => reset(&session, &options).await,
164            };
165            if let Err(e) = prepared {
166                tracing::warn!(error = %e, "pooled session reset failed; replacing it");
167                session.close().await;
168                continue;
169            }
170            return Ok(PooledSession { session, pool: self.clone(), _permit: permit });
171        }
172
173        let session = Session::spawn(self.spawn_options(options), Initialize::default()).await?;
174        Ok(PooledSession { session, pool: self.clone(), _permit: permit })
175    }
176
177    /// `options` for the next spawned session: its own recording file.
178    fn spawn_options(&self, mut options: SessionOptions) -> SessionOptions {
179        let n = self.0.spawned.fetch_add(1, Ordering::Relaxed) + 1;
180        options.record = options.record.map(|path| numbered(&path, n));
181        options
182    }
183
184    fn idle(&self) -> MutexGuard<'_, Vec<Idle>> {
185        self.0.idle.lock().unwrap_or_else(PoisonError::into_inner)
186    }
187}
188
189/// A reset makes no API call; anything slower means a stuck CLI.
190const RESET_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);
191
192/// Reset a used session for the next task: `/clear` the conversation (runs
193/// locally in the CLI, no API call, new session id), then set the next
194/// checkout's model, effort and permission mode.
195async fn reset(session: &Session, options: &SessionOptions) -> std::result::Result<(), String> {
196    let run = async {
197        let mut stream = Agent::new(session.clone()).prompt("/clear").await.map_err(|e| e.to_string())?;
198        loop {
199            match stream.next().await {
200                Some(AgentEvent::Done(_)) => break,
201                Some(AgentEvent::Error(e)) => return Err(e.to_string()),
202                Some(_) => {}
203                None => return Err("stream ended without a result".to_string()),
204            }
205        }
206        apply(session, options).await
207    };
208    tokio::time::timeout(RESET_TIMEOUT, run).await.unwrap_or_else(|_| Err("reset timed out".into()))
209}
210
211/// Set model, effort and permission mode from `options` on a live session.
212async fn apply(session: &Session, options: &SessionOptions) -> std::result::Result<(), String> {
213    session.set_model(options.model.as_deref()).await.map_err(|e| e.to_string())?;
214    session.set_effort(options.effort).await.map_err(|e| e.to_string())?;
215    let mode = options.permission_mode.or_else(|| session.launch_permission_mode()).unwrap_or(PermissionMode::Default);
216    session.set_permission_mode(mode).await.map_err(|e| e.to_string())
217}
218
219/// Whether `session` can switch to `options`' permission mode: the CLI
220/// refuses `bypassPermissions` unless the session started in it.
221fn can_take(session: &Session, options: &SessionOptions) -> bool {
222    options.permission_mode != Some(PermissionMode::BypassPermissions)
223        || session.launch_permission_mode() == Some(PermissionMode::BypassPermissions)
224}
225
226/// A session borrowed from the pool. Returns to the pool on Drop. Keep
227/// clones of `session` (e.g. inside an `Agent`) no longer than the
228/// `PooledSession`: after Drop another task may get the same session.
229pub struct PooledSession {
230    /// The borrowed session.
231    pub session: Session,
232    pool: SessionPool,
233    _permit: tokio::sync::OwnedSemaphorePermit,
234}
235
236impl std::ops::Deref for PooledSession {
237    type Target = Session;
238    fn deref(&self) -> &Self::Target {
239        &self.session
240    }
241}
242
243impl Drop for PooledSession {
244    fn drop(&mut self) {
245        // Synchronous: safe to drop outside a Tokio runtime.
246        let reusable = self.session.is_alive() && !self.session.is_busy() && self.session.offers_command("clear");
247        let mut idle = self.pool.idle();
248        if reusable && idle.len() < self.pool.0.config.max_sessions {
249            idle.push(Idle { session: self.session.clone(), used: true });
250        }
251        // Permit dropped here → semaphore released.
252    }
253}
254
255/// `path` with `n` before its extension: `hi.jsonl` → `hi.3.jsonl`.
256fn numbered(path: &std::path::Path, n: u64) -> std::path::PathBuf {
257    let stem = path.file_stem().unwrap_or_default().to_string_lossy();
258    let name = match path.extension() {
259        Some(ext) => format!("{stem}.{n}.{}", ext.to_string_lossy()),
260        None => format!("{stem}.{n}"),
261    };
262    path.with_file_name(name)
263}