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