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