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