Skip to main content

infinity_daemon/
rap_servers.rs

1//! Lazy, daemon-managed RAP tool servers.
2//!
3//! The daemon runs one agent system for its whole lifetime; sessions are just
4//! groups of threads sharing a working directory. What *does* start and stop
5//! with session activity are the session's RAP tool servers. This module
6//! makes that lifecycle lazy:
7//!
8//! - A session's toolset is resolved the first time one of its threads runs a
9//!   step (via [`SessionRapManager`]'s [`ThreadConfigSource`] impl): the
10//!   configured servers are booted, their manifests fetched, and one
11//!   [`ManagedRapTool`] built per remote tool definition.
12//! - When the session goes idle (no live thread drivers, no keep-alive
13//!   client), the daemon calls [`SessionRapManager::shutdown_session`], which
14//!   stops the server processes but keeps the cached tool definitions.
15//! - The next tool invocation boots the server back up transparently
16//!   ([`ManagedRapServer::invoke_endpoint`]), so shutting servers down is
17//!   always safe — there is no teardown/wakeup race to coordinate.
18//!
19//! Migration flows boot the same configured servers eagerly (outside any
20//! session) via [`boot_migration_servers`], pairing source and destination
21//! servers by config id and consulting each manifest's `needsMigration`
22//! flag.
23
24use infinity_agent_core::ThreadId;
25use std::collections::HashMap;
26use std::path::{Path, PathBuf};
27use std::rc::Rc;
28use std::sync::Arc;
29
30use async_trait::async_trait;
31use infinity_agent_core::system::local::ChannelSender;
32use infinity_agent_core::system::{ThreadConfig, ThreadConfigSource};
33use infinity_agent_core::tools::Tool;
34use infinity_agent_core::tools::config::ToolSetConfig;
35use infinity_agent_core::tools::rap_tool::{
36    RapInvocationParams, RapToolDescriptor, invoke_rap_tool,
37};
38use infinity_protocol::DaemonMessage;
39use rap_client::http::{HttpClient, SimpleHttpClient};
40use rap_client::notifier::RapNotifier;
41use rap_protocol::ToolsetManifest;
42
43use crate::memory_store::PersistentConversationStore;
44use crate::session::SessionStoreHandle;
45use crate::session::observer::SubscriberMap;
46use crate::{config, mcp_proxy, set_title_tool};
47
48type BoxError = Box<dyn std::error::Error + Send + Sync>;
49
50// ── ManagedRapServer ─────────────────────────────────────────────────────────
51
52/// How to bring a configured RAP server up.
53enum ServerSpec {
54    /// A command spawned as a child process (`RAP_EMBEDDED=1`).
55    Command { command: String, cwd: PathBuf },
56    /// A stdio MCP server proxied behind an in-process RAP server. The proxy
57    /// owns the child process; it is booted once and kept for the daemon's
58    /// lifetime.
59    Mcp {
60        name: String,
61        command: Vec<String>,
62        env: HashMap<String, String>,
63    },
64    /// A remote MCP server proxied behind an in-process RAP server.
65    HttpMcp {
66        name: String,
67        url: String,
68        headers: HashMap<String, String>,
69    },
70    /// A pre-existing external server URL; never started or stopped by us.
71    External { url: String },
72}
73
74#[expect(
75    clippy::large_enum_variant,
76    reason = "at most a handful of servers exist per session"
77)]
78enum ServerState {
79    Down,
80    Up {
81        base_url: String,
82        /// The server's manifest, fetched once per boot. (The invocation
83        /// endpoint changes across reboots since command servers get a
84        /// fresh port.)
85        manifest: ToolsetManifest,
86        /// The child process for command-based servers (killed on shutdown).
87        child: Option<tokio::process::Child>,
88        /// The accept-loop task of an in-process MCP proxy. Stored for
89        /// ownership: unlike command servers, MCP servers may hold state
90        /// that lives only as long as their process (RAP servers persist
91        /// state via the thread ID, but MCP has no such contract), so
92        /// [`shutdown`](ManagedRapServer::shutdown) leaves proxies running
93        /// rather than restarting them across session idles. The task is
94        /// only ever aborted to tear down a half-booted proxy (manifest
95        /// fetch failure) before it is stored here.
96        #[expect(dead_code, reason = "held for ownership; never polled")]
97        task: Option<tokio::task::JoinHandle<()>>,
98    },
99}
100
101/// A handle to one configured RAP server that the daemon can boot lazily and
102/// shut down at will. Tools hold an `Arc` to it and call
103/// [`invoke_endpoint`](Self::invoke_endpoint) per invocation, so a server
104/// stopped while its session idled reboots transparently on the next call.
105pub struct ManagedRapServer {
106    /// Config id (for migration bookkeeping), when present.
107    pub config_id: Option<String>,
108    session_id: ThreadId,
109    spec: ServerSpec,
110    state: tokio::sync::Mutex<ServerState>,
111}
112
113impl ManagedRapServer {
114    fn new(session_id: ThreadId, config_id: Option<String>, spec: ServerSpec) -> Self {
115        Self {
116            config_id,
117            session_id,
118            spec,
119            state: tokio::sync::Mutex::new(ServerState::Down),
120        }
121    }
122
123    /// The server's base URL if it is currently up.
124    pub async fn current_base_url(&self) -> Option<String> {
125        match &*self.state.lock().await {
126            ServerState::Up { base_url, .. } => Some(base_url.clone()),
127            ServerState::Down => None,
128        }
129    }
130
131    /// Boot the server if it is down and return its manifest (cached for the
132    /// lifetime of the boot). If the server boots but its manifest cannot be
133    /// fetched, the boot is torn down and the server stays down, so `Up`
134    /// always has a usable manifest.
135    pub async fn ensure_up(&self) -> Result<ToolsetManifest, BoxError> {
136        let mut state = self.state.lock().await;
137        if let ServerState::Up { manifest, .. } = &*state {
138            return Ok(manifest.clone());
139        }
140
141        let (base_url, mut child, task) = match &self.spec {
142            ServerSpec::Command { command, cwd } => {
143                tracing::info!(
144                    "Booting RAP server for session {}: {command}",
145                    self.session_id
146                );
147                let (child, port) = spawn_rap_server(command, cwd).await?;
148                (format!("http://127.0.0.1:{port}"), Some(child), None)
149            }
150            ServerSpec::Mcp { name, command, env } => {
151                let (port, task) =
152                    mcp_proxy::start_mcp_proxy(name.clone(), command.clone(), env.clone()).await?;
153                (format!("http://127.0.0.1:{port}"), None, Some(task))
154            }
155            ServerSpec::HttpMcp { name, url, headers } => {
156                let (port, task) =
157                    mcp_proxy::start_http_mcp_proxy(name.clone(), url.clone(), headers.clone())
158                        .await?;
159                (format!("http://127.0.0.1:{port}"), None, Some(task))
160            }
161            ServerSpec::External { url } => (url.clone(), None, None),
162        };
163
164        match fetch_manifest(&base_url).await {
165            Ok(manifest) => {
166                *state = ServerState::Up {
167                    base_url,
168                    manifest: manifest.clone(),
169                    child,
170                    task,
171                };
172                Ok(manifest)
173            }
174            Err(e) => {
175                // Tear the boot down; the next call retries from scratch.
176                if let Some(child) = &mut child {
177                    let _ = child.start_kill();
178                    let _ = child.wait().await;
179                }
180                if let Some(task) = task {
181                    task.abort();
182                }
183                Err(e)
184            }
185        }
186    }
187
188    /// The invocation endpoint, booting the server first if necessary.
189    pub async fn invoke_endpoint(&self) -> Result<String, BoxError> {
190        Ok(self.ensure_up().await?.endpoint)
191    }
192
193    /// Stop the server. Safe to call at any time: the next invocation (or
194    /// manifest fetch) boots it back up. Only command-based child processes
195    /// are stopped — RAP servers persist their state keyed by thread ID, so
196    /// a restart is transparent. MCP servers have no such contract (one may
197    /// hold state that lives only as long as its process), so MCP proxies
198    /// are left running; external servers are not ours to stop.
199    pub async fn shutdown(&self) {
200        let mut state = self.state.lock().await;
201        match &self.spec {
202            ServerSpec::Command { .. } => {
203                if let ServerState::Up { child, .. } = &mut *state
204                    && let Some(mut child) = child.take()
205                {
206                    #[cfg(unix)]
207                    {
208                        use nix::sys::signal::{self, Signal};
209                        use nix::unistd::Pid;
210                        if let Some(id) = child.id() {
211                            // Negative ID signals the entire process group.
212                            let _ = signal::kill(Pid::from_raw(-(id as i32)), Signal::SIGINT);
213                        }
214                    }
215                    #[cfg(not(unix))]
216                    {
217                        let _ = child.start_kill();
218                    }
219                    let _ = child.wait().await;
220                    tracing::info!("Stopped RAP server for session {}", self.session_id);
221                }
222                *state = ServerState::Down;
223            }
224            // In-process proxies and external servers are not ours to stop.
225            ServerSpec::Mcp { .. } | ServerSpec::HttpMcp { .. } | ServerSpec::External { .. } => {}
226        }
227    }
228}
229
230async fn fetch_manifest(base_url: &str) -> Result<ToolsetManifest, BoxError> {
231    let http = SimpleHttpClient::new();
232    let url = format!("{}/.well-known/rap-toolset", base_url.trim_end_matches('/'));
233    let (status, body) = http
234        .get(&url)
235        .await
236        .map_err(|e| format!("failed to fetch toolset manifest from {url}: {e}"))?;
237    if !(200..300).contains(&status) {
238        return Err(format!("toolset manifest fetch from {url} returned status {status}").into());
239    }
240    let manifest: ToolsetManifest = serde_json::from_slice(&body)
241        .map_err(|e| format!("invalid toolset manifest from {url}: {e}"))?;
242    Ok(manifest)
243}
244
245// ── Migration boots ──────────────────────────────────────────────────────────
246
247/// A RAP server booted eagerly for a migration flow. Migration servers are
248/// ordinary configured RAP servers — the same specs the session runtime
249/// boots lazily — brought up outside any session so the migration protocol
250/// can be spoken to the ones whose manifest declares `needsMigration`.
251///
252/// Owns the underlying server: dropping this kills a command server's child
253/// process (`kill_on_drop`), which bounds the servers' lifetime to the
254/// migration flow. MCP proxies detach and keep running, as everywhere else.
255pub struct MigrationServer {
256    /// The server's config id, when its config entry has one (migration
257    /// pairing between source and destination is keyed by these ids).
258    pub config_id: Option<String>,
259    /// The server's reachable base URL.
260    pub url: String,
261    /// The local port, for servers we booted ourselves (`None` for external
262    /// `toolset_server` URLs).
263    pub port: Option<u16>,
264    /// Whether the server's manifest declared `needsMigration: true`.
265    pub needs_migration: bool,
266    _server: ManagedRapServer,
267}
268
269/// Boot every server in `cwd`'s merged RAP config and fetch its manifest.
270/// Servers that fail to boot are skipped with a warning, matching the
271/// session runtime's tolerance for individual server failures.
272pub async fn boot_migration_servers(
273    cwd: &Path,
274    user_config_path: Option<&Path>,
275) -> Result<Vec<MigrationServer>, BoxError> {
276    let (_source_info, specs) =
277        collect_server_specs(&ThreadId::from("migration"), cwd, user_config_path)?;
278    let mut servers = Vec::new();
279    for server in specs {
280        let manifest = match server.ensure_up().await {
281            Ok(m) => m,
282            Err(e) => {
283                tracing::warn!("failed to boot RAP server for migration: {e}");
284                continue;
285            }
286        };
287        let url = server
288            .current_base_url()
289            .await
290            .expect("bug: server is up right after ensure_up");
291        // Only servers we booted ourselves have a meaningful local port
292        // (external toolset_server URLs are excluded from port maps, since
293        // migration tunnels forward local ports).
294        let port = if matches!(server.spec, ServerSpec::External { .. }) {
295            None
296        } else {
297            url.rsplit_once(':')
298                .and_then(|(_, p)| p.trim_end_matches('/').parse().ok())
299        };
300        servers.push(MigrationServer {
301            config_id: server.config_id.clone(),
302            url,
303            port,
304            needs_migration: manifest.needs_migration,
305            _server: server,
306        });
307    }
308    Ok(servers)
309}
310
311/// The `config_id → port` map for the servers that need migration — the
312/// payload of [`DaemonMessage::RapServersBooted`].
313pub fn migration_server_ports(servers: &[MigrationServer]) -> HashMap<String, u16> {
314    servers
315        .iter()
316        .filter(|s| s.needs_migration)
317        .filter_map(|s| Some((s.config_id.clone()?, s.port?)))
318        .collect()
319}
320
321/// Spawn a command-based RAP server (`RAP_EMBEDDED=1`) and wait for it to
322/// report its port on stdout. Used both by the lazy per-session server
323/// management and by the eager migration boots above.
324async fn spawn_rap_server(
325    command: &str,
326    cwd: &Path,
327) -> Result<(tokio::process::Child, u16), BoxError> {
328    use infinity_agent_core::tools::config::CommandServerReady;
329    use std::process::Stdio;
330    use tokio::io::AsyncBufReadExt;
331
332    let working_dir = cwd.join(".infinity");
333    std::fs::create_dir_all(&working_dir).ok();
334
335    let mut child = tokio::process::Command::new("sh")
336        .args(["-c", command])
337        .env("RAP_EMBEDDED", "1")
338        .current_dir(&working_dir)
339        // Ensure all children are in the the same process group. We will send SIGINT to the entire
340        // group during shutdown.
341        .process_group(0)
342        .stdout(Stdio::piped())
343        .stderr(Stdio::null())
344        .kill_on_drop(true)
345        .spawn()
346        .map_err(|e| format!("failed to spawn '{command}': {e}"))?;
347
348    let stdout = child.stdout.take().ok_or("no stdout")?;
349    let mut reader = tokio::io::BufReader::new(stdout);
350    let mut line = String::new();
351    reader
352        .read_line(&mut line)
353        .await
354        .map_err(|e| format!("failed to read startup line: {e}"))?;
355
356    if line.is_empty() {
357        let _ = child.kill().await;
358        return Err("server exited before emitting port".into());
359    }
360
361    let ready: CommandServerReady = serde_json::from_str(line.trim())
362        .map_err(|e| format!("invalid startup JSON: {e} (got: {line})"))?;
363    Ok((child, ready.port))
364}
365
366// ── ManagedRapTool ───────────────────────────────────────────────────────────
367
368/// A RAP tool bound to a [`ManagedRapServer`]: each invocation resolves the
369/// server's current endpoint, booting it first if it was shut down.
370pub struct ManagedRapTool {
371    pub descriptor: RapToolDescriptor,
372    pub server: Arc<ManagedRapServer>,
373    pub http_client: SimpleHttpClient,
374}
375
376#[async_trait]
377impl Tool<ChannelSender> for ManagedRapTool {
378    fn name(&self) -> &str {
379        &self.descriptor.name
380    }
381
382    fn description(&self) -> &str {
383        &self.descriptor.description
384    }
385
386    fn parameters(&self) -> serde_json::Value {
387        self.descriptor.parameters.clone()
388    }
389
390    fn display_script(&self) -> Option<&str> {
391        self.descriptor.display_script.as_deref()
392    }
393
394    async fn execute(
395        &self,
396        args: serde_json::Value,
397        id: rap_protocol::ToolCallId,
398        call_id: Option<rap_protocol::ProviderCallId>,
399        context: &infinity_agent_core::tools::ToolContext<ChannelSender>,
400    ) -> Result<(), BoxError> {
401        let endpoint = self.server.invoke_endpoint().await?;
402        invoke_rap_tool(
403            &self.http_client,
404            RapInvocationParams {
405                endpoint: &endpoint,
406                operation: &self.descriptor.name,
407                arguments: args,
408                id,
409                call_id,
410                callback_url: None,
411            },
412            context,
413        )
414        .await
415    }
416}
417
418// ── SessionRapManager ────────────────────────────────────────────────────────
419
420/// A session's resolved toolset: the tool instances shared by all of the
421/// session's threads plus the managed servers behind them.
422struct SessionToolset {
423    tools: Vec<Rc<dyn Tool<ChannelSender>>>,
424    servers: Vec<Arc<ManagedRapServer>>,
425    extra_system_prompt: String,
426}
427
428/// Daemon-wide manager of per-session toolsets and their RAP servers. Also
429/// the agent system's [`ThreadConfigSource`]: each thread resolves to its
430/// session's toolset.
431#[derive(Clone)]
432pub struct SessionRapManager {
433    toolsets: Rc<tokio::sync::Mutex<HashMap<ThreadId, Rc<SessionToolset>>>>,
434    conversation_store: PersistentConversationStore,
435    session_store: SessionStoreHandle,
436    user_rap_config: Option<PathBuf>,
437    /// Used to surface boot progress to the session's subscribers.
438    subscriber_map: SubscriberMap,
439    /// Sessions whose servers have been shut down at least once (observable
440    /// for tests and diagnostics).
441    shutdown_log: Rc<std::cell::RefCell<Vec<ThreadId>>>,
442}
443
444impl SessionRapManager {
445    pub fn new(
446        conversation_store: PersistentConversationStore,
447        session_store: SessionStoreHandle,
448        user_rap_config: Option<PathBuf>,
449        subscriber_map: SubscriberMap,
450    ) -> Self {
451        Self {
452            toolsets: Rc::new(tokio::sync::Mutex::new(HashMap::new())),
453            conversation_store,
454            session_store,
455            user_rap_config,
456            subscriber_map,
457            shutdown_log: Rc::new(std::cell::RefCell::new(Vec::new())),
458        }
459    }
460
461    /// Send an informational message to the session's subscribers.
462    fn info(&self, session_id: &ThreadId<str>, text: String) {
463        let msg = DaemonMessage::Info {
464            thread_id: Some(infinity_protocol::ThreadRef::local(session_id.to_owned())),
465            text,
466        };
467        crate::session::observer::broadcast_to_thread(&self.subscriber_map, session_id, &msg, None);
468    }
469
470    /// Get (or lazily build) the toolset for a session: read the RAP config
471    /// for the session's cwd, boot the servers, fetch their manifests, and
472    /// build the tool instances.
473    async fn get_or_init(
474        &self,
475        session_id: &ThreadId<str>,
476    ) -> Result<Rc<SessionToolset>, BoxError> {
477        let mut toolsets = self.toolsets.lock().await;
478        if let Some(ts) = toolsets.get(session_id) {
479            return Ok(ts.clone());
480        }
481
482        let cwd = {
483            let store = self.session_store.lock().await;
484            store.get_cwd(session_id).clone()
485        };
486
487        let mut servers: Vec<Arc<ManagedRapServer>> = Vec::new();
488        match collect_server_specs(session_id, &cwd, self.user_rap_config.as_deref()) {
489            Ok((source_info, specs)) => {
490                self.info(session_id, source_info);
491                for server in specs {
492                    servers.push(Arc::new(server));
493                }
494            }
495            Err(e) => {
496                self.info(
497                    session_id,
498                    format!("Warning: failed to read RAP config: {e}"),
499                );
500            }
501        }
502
503        // Boot each server once to discover its tools.
504        let http_client = SimpleHttpClient::new();
505        let mut tools: Vec<Rc<dyn Tool<ChannelSender>>> = Vec::new();
506        let mut tool_count = 0usize;
507        for server in &servers {
508            match server.ensure_up().await {
509                Ok(manifest) => {
510                    for def in manifest.tools {
511                        tool_count += 1;
512                        tools.push(Rc::new(ManagedRapTool {
513                            descriptor: def.into(),
514                            server: server.clone(),
515                            http_client: http_client.clone(),
516                        }));
517                    }
518                }
519                Err(e) => {
520                    self.info(
521                        session_id,
522                        format!("Warning: failed to start RAP server: {e}"),
523                    );
524                }
525            }
526        }
527        if tool_count > 0 {
528            self.info(session_id, format!("Loaded {tool_count} RAP tool(s)"));
529        }
530
531        tools.push(Rc::new(set_title_tool::SetTitleTool {
532            conversation_store: self.conversation_store.clone(),
533        }));
534
535        let extra_system_prompt = format!(
536            "The user's current working directory is: {cwd:?}\n\n\
537             Use the `set_title` tool to give the current thread a short, descriptive title. \
538             Set it once at the start when the user's intent becomes clear, and update it only \
539             when the overall scope of work changes significantly. Do not call it repeatedly \
540             for minor follow-ups within the same task."
541        );
542
543        let toolset = Rc::new(SessionToolset {
544            tools,
545            servers,
546            extra_system_prompt,
547        });
548        toolsets.insert(session_id.to_owned(), toolset.clone());
549        Ok(toolset)
550    }
551
552    /// Stop the session's RAP servers (keeping the cached toolset, so a later
553    /// tool invocation reboots them transparently). Safe to call at any time.
554    pub async fn shutdown_session(&self, session_id: &ThreadId<str>) {
555        let toolset = {
556            let toolsets = self.toolsets.lock().await;
557            toolsets.get(session_id).cloned()
558        };
559        if let Some(toolset) = toolset {
560            for server in &toolset.servers {
561                server.shutdown().await;
562            }
563        }
564        self.shutdown_log.borrow_mut().push(session_id.to_owned());
565    }
566
567    /// Stop the session's servers and drop its cached toolset entirely, so
568    /// the next use re-reads the RAP config and re-fetches manifests. Used
569    /// when a session is explicitly shut down.
570    pub async fn evict_session(&self, session_id: &ThreadId<str>) {
571        self.shutdown_session(session_id).await;
572        self.toolsets.lock().await.remove(session_id);
573    }
574
575    /// Stop every managed server (daemon exit).
576    pub async fn shutdown_all(&self) {
577        let session_ids: Vec<ThreadId> = self.toolsets.lock().await.keys().cloned().collect();
578        for session_id in session_ids {
579            self.shutdown_session(&session_id).await;
580        }
581    }
582
583    /// How many times [`shutdown_session`](Self::shutdown_session) has been
584    /// invoked for `session_id` (diagnostics / tests).
585    pub fn times_shut_down(&self, session_id: &ThreadId<str>) -> usize {
586        self.shutdown_log
587            .borrow()
588            .iter()
589            .filter(|s| *s == session_id)
590            .count()
591    }
592}
593
594#[async_trait(?Send)]
595impl ThreadConfigSource<ChannelSender, SimpleHttpClient> for SessionRapManager {
596    async fn resolve(
597        &self,
598        thread_id: &ThreadId<str>,
599    ) -> Result<ThreadConfig<ChannelSender, SimpleHttpClient>, BoxError> {
600        let session_id = self.conversation_store.get_root_thread_id(thread_id);
601        let toolset = self.get_or_init(&session_id).await?;
602
603        // Best-effort lifecycle notifications go to the servers that are
604        // currently up (a server that is down has nothing in flight).
605        let mut urls = Vec::new();
606        for server in &toolset.servers {
607            if let Some(url) = server.current_base_url().await {
608                urls.push(url);
609            }
610        }
611        Ok(ThreadConfig {
612            tools: toolset.tools.clone(),
613            extra_system_prompt: Some(toolset.extra_system_prompt.clone()),
614            rap_notifier: Some(RapNotifier::new(urls, SimpleHttpClient::new())),
615        })
616    }
617}
618
619/// Read the merged RAP config for `cwd` and build the (un-booted) server
620/// handles. Also returns a human-readable line describing which config
621/// source(s) were used, for display to the session's subscribers.
622fn collect_server_specs(
623    session_id: &ThreadId<str>,
624    cwd: &Path,
625    user_config_path: Option<&Path>,
626) -> Result<(String, Vec<ManagedRapServer>), BoxError> {
627    let (source_info, merged) = config::load_merged_rap_config(cwd, user_config_path)?;
628    let Some(merged) = merged else {
629        return Ok((source_info, Vec::new()));
630    };
631
632    let mut servers = Vec::new();
633    for entry in merged.tool_sets {
634        let (id, spec) = match entry {
635            ToolSetConfig::ToolsetServer { server_url, id } => {
636                (id, ServerSpec::External { url: server_url })
637            }
638            ToolSetConfig::ToolsetCommand { command, id, .. } => (
639                id,
640                ServerSpec::Command {
641                    command,
642                    cwd: cwd.to_path_buf(),
643                },
644            ),
645            ToolSetConfig::McpServer {
646                name,
647                command,
648                env,
649                id,
650            } => (id, ServerSpec::Mcp { name, command, env }),
651            ToolSetConfig::HttpMcpServer {
652                name,
653                url,
654                headers,
655                id,
656            } => (id, ServerSpec::HttpMcp { name, url, headers }),
657        };
658        servers.push(ManagedRapServer::new(session_id.to_owned(), id, spec));
659    }
660    Ok((source_info, servers))
661}