Skip to content

Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.

feat(host): free idle bots' agents and sessions

leepokaif5d63508d8ff
diff --git a/docs/architecture/conversation-runtime.md b/docs/architecture/conversation-runtime.md
index 3f4b7869..833411d9 100644
--- a/docs/architecture/conversation-runtime.md
+++ b/docs/architecture/conversation-runtime.md
@@ -1,6 +1,7 @@
# Conversation runtime
- **Chat ≠ session**: a bot is one endless transcript (SQLite `entries`, ordered by `seq`); the ACP session underneath is resumed with `session/load` or replaced by *New session*.
+- **Agent processes**: a bot's agent starts on its first message and keeps its sessions loaded between messages. A session unused for 30 minutes is closed (agents with `session/close`), and once all of them are idle the agent stops with its process group; the next message starts it again and loads the session (`agent/bot/lifecycle.rs`). Nothing is released mid-turn or while a queue, approval or request waits. Agents that can't load sessions stay, and so do agents with something running in a process group of their own, like a dev server from Claude Code's shell tool (stopping the agent would orphan it). Windows agents are never stopped for idleness: without process groups a dev server can't be told from an MCP server, and stopping ends the whole tree.
- **Group chats and threads** are host features every client drives through the same methods (`send` with `threadId`, `thread`, `createBot {kind: group}`); clients never route, parse mentions or count replies themselves. A group is a roster row whose members answer in their own sessions (Grok Bot's room turns); a thread on a bot's message is a forked session: [docs/features/groups-and-threads.md](../features/groups-and-threads.md).
- Bot collaboration: built-in `team` MCP (`chat/team.rs`) lists visible bots and asks one for a reply or sends it an independent message through its actor queue. Asks are separate turns, cycle-checked and cancellable; native subagents stay with the harness. See [docs/features/bot-collaboration.md](../features/bot-collaboration.md).
- **Context & memory**: frozen instruction snapshot per session + compaction epoch (Claude gets it as a system prompt), profile edits as update blocks, per-bot Engram SQLite memory with a keeper agent, busy-time messages folded into one turn, interrupted turns resumed: [docs/features/context-and-memory.md](../features/context-and-memory.md).
diff --git a/host/src/agent/acp.rs b/host/src/agent/acp.rs
index c5701e8d..7d095ab6 100644
--- a/host/src/agent/acp.rs
+++ b/host/src/agent/acp.rs
@@ -112,6 +112,8 @@ pub struct Acp {
next_id: AtomicI64,
pending: Pending,
child: tokio::sync::Mutex<Child>,
+ /// The process (and, on Unix, process group) leader.
+ pid: Option<u32>,
}
impl Acp {
@@ -196,15 +198,21 @@ impl Acp {
});
}
+ let pid = child.id();
let acp = Arc::new(Self {
stdin: tokio::sync::Mutex::new(stdin),
next_id: AtomicI64::new(1),
pending,
child: tokio::sync::Mutex::new(child),
+ pid,
});
Ok((acp, rx))
}
+ pub fn pid(&self) -> Option<u32> {
+ self.pid
+ }
+
async fn write(&self, msg: Value) -> Result<()> {
let mut line = serde_json::to_vec(&msg)?;
line.push(b'\n');
diff --git a/host/src/agent/bot/lifecycle.rs b/host/src/agent/bot/lifecycle.rs
new file mode 100644
index 00000000..bf4bfd6a
--- /dev/null
+++ b/host/src/agent/bot/lifecycle.rs
@@ -0,0 +1,210 @@
+//! Idle agents give their resources back. A session unused for [`IDLE`] is closed; once every
+//! session is idle, the agent stops with its process group. The next message starts the agent
+//! again and loads the session, so the conversation carries on. Agents that can't load a
+//! session keep everything: stopping them would lose the conversation.
+
+use super::Actor;
+use serde_json::json;
+use std::collections::HashMap;
+use std::time::{Duration, Instant};
+
+/// Coming back costs a relaunch plus `session/load` (seconds), so ordinary pauses in a chat
+/// stay warm.
+const IDLE: Duration = Duration::from_secs(30 * 60);
+/// How often an idle bot looks for something to give back.
+const CHECK_EVERY: Duration = Duration::from_secs(60);
+
+#[derive(Debug, PartialEq)]
+enum Release {
+ Nothing,
+ /// These sessions; the agent keeps running the rest.
+ Sessions(Vec<String>),
+ /// The agent process, with everything in its process group.
+ Agent,
+}
+
+/// `used`: each live session's last use. Only an agent that can close sessions releases them one
+/// by one; any agent that can load them is stopped once all are idle.
+fn plan(used: &HashMap<String, Instant>, started: Instant, can_close: bool, now: Instant) -> Release {
+ let mut idle: Vec<String> =
+ used.iter().filter(|(_, at)| now.duration_since(**at) >= IDLE).map(|(sid, _)| sid.clone()).collect();
+ if idle.len() == used.len() && now.duration_since(started) >= IDLE {
+ Release::Agent
+ } else if can_close && !idle.is_empty() {
+ idle.sort();
+ Release::Sessions(idle)
+ } else {
+ Release::Nothing
+ }
+}
+
+impl Actor {
+ /// Runs on the actor's tick: at most every [`CHECK_EVERY`], and only while the bot has nothing
+ /// running, queued or waiting on the user.
+ pub(super) async fn release_idle(&mut self) {
+ if self.idle_checked.elapsed() < CHECK_EVERY || !self.at_rest() {
+ return;
+ }
+ self.idle_checked = Instant::now();
+ let Some(conn) = &self.conn else { return };
+ if !conn.sessions.load {
+ return;
+ }
+ let release = plan(&conn.loaded, conn.started, conn.sessions.close, Instant::now());
+ let leader = conn.acp.pid();
+ if release == Release::Nothing || background_work(leader).await {
+ return;
+ }
+ match release {
+ Release::Agent => {
+ tracing::info!(bot = %self.cfg.id, "stopping an idle agent");
+ if let Some(conn) = self.conn.take() {
+ conn.acp.kill().await;
+ }
+ }
+ Release::Sessions(sessions) => {
+ for sid in sessions {
+ self.close_session(&sid).await;
+ }
+ }
+ Release::Nothing => {}
+ }
+ }
+
+ fn at_rest(&self) -> bool {
+ self.turn.is_none()
+ && self.queue.is_empty()
+ && self.perms.is_empty()
+ && self.active_request.is_none()
+ && self.active_group.is_none()
+ && self.active_routine.is_none()
+ && self.routine_completion.is_none()
+ && self.cancel_deadline.is_none()
+ }
+
+ async fn close_session(&mut self, sid: &str) {
+ let closed = self.session_request("session/close", json!({ "sessionId": sid })).await;
+ let Some(conn) = self.conn.as_mut() else { return };
+ match closed {
+ Ok(_) => {
+ tracing::info!(bot = %self.cfg.id, session = sid, "closed an idle session");
+ conn.loaded.remove(sid);
+ conn.fast_options.remove(sid);
+ }
+ Err(error) => {
+ tracing::warn!(bot = %self.cfg.id, session = sid, error = format!("{error:#}"), "couldn't close an idle session");
+ // Try again after another idle period rather than every check.
+ conn.loaded.insert(sid.to_owned(), Instant::now());
+ }
+ }
+ }
+}
+
+/// Whether something the agent started runs in a process group of its own, like a dev server
+/// from its shell tool. Stopping the agent would orphan it and lose track of it, so the agent
+/// stays. MCP servers share the agent's group and don't count. Unsure counts as busy.
+// ponytail: a dev server keeps its agent (and memory) indefinitely; add a cap if that matters.
+#[cfg(unix)]
+async fn background_work(leader: Option<u32>) -> bool {
+ let Some(leader) = leader else { return true };
+ let listed = tokio::process::Command::new("ps").args(["-A", "-o", "pid=,ppid=,pgid="]).output().await;
+ let Ok(listed) = listed.inspect_err(|e| tracing::warn!(error = format!("{e:#}"), "couldn't list processes")) else {
+ return true;
+ };
+ if !listed.status.success() {
+ return true;
+ }
+ let processes: Vec<(u32, u32, u32)> = String::from_utf8_lossy(&listed.stdout)
+ .lines()
+ .filter_map(|line| {
+ let mut fields = line.split_whitespace().map(str::parse);
+ Some((fields.next()?.ok()?, fields.next()?.ok()?, fields.next()?.ok()?))
+ })
+ .collect();
+ detached_descendant(&processes, leader)
+}
+
+/// Windows has no process groups to tell a dev server from an MCP server, and stopping the agent
+/// ends its whole process tree there, so its agents are never released.
+#[cfg(windows)]
+#[allow(clippy::unused_async)] // the Unix check's signature
+async fn background_work(_leader: Option<u32>) -> bool {
+ true
+}
+
+/// `processes`: (pid, parent pid, process group) rows. The agent's group is its leader's pid.
+#[cfg(any(unix, test))]
+fn detached_descendant(processes: &[(u32, u32, u32)], leader: u32) -> bool {
+ let mut children: HashMap<u32, Vec<(u32, u32)>> = HashMap::new();
+ for &(pid, parent, group) in processes {
+ children.entry(parent).or_default().push((pid, group));
+ }
+ let mut stack = vec![leader];
+ while let Some(parent) = stack.pop() {
+ for &(pid, group) in children.get(&parent).into_iter().flatten() {
+ if group != leader {
+ return true;
+ }
+ stack.push(pid);
+ }
+ }
+ false
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn idle_sessions_close_one_by_one_and_an_idle_agent_stops() {
+ let started = Instant::now();
+ let now = started + IDLE * 4;
+ let (stale, fresh) = (started + IDLE * 2, now);
+ let used =
+ |rows: &[(&str, Instant)]| rows.iter().map(|(s, at)| ((*s).to_owned(), *at)).collect::<HashMap<_, _>>();
+ assert_eq!(
+ plan(&used(&[("main", fresh), ("t1", stale)]), started, true, now),
+ Release::Sessions(vec!["t1".into()])
+ );
+ assert_eq!(plan(&used(&[("main", fresh), ("t1", stale)]), started, false, now), Release::Nothing);
+ assert_eq!(plan(&used(&[("main", stale), ("t1", stale)]), started, false, now), Release::Agent);
+ assert_eq!(plan(&used(&[]), started, true, now), Release::Agent);
+ // A just-started agent isn't stopped before it had a chance to be used.
+ assert_eq!(plan(&used(&[]), now, true, now), Release::Nothing);
+ assert_eq!(plan(&used(&[("main", fresh)]), started, true, now), Release::Nothing);
+ }
+
+ #[test]
+ fn only_work_in_another_process_group_holds_the_agent() {
+ // 10 agent (group 10) -> 11 claude -> 12 MCP server, all in group 10.
+ let agent = [(10, 1, 10), (11, 10, 10), (12, 11, 10), (40, 1, 40)];
+ assert!(!detached_descendant(&agent, 10));
+ // claude's shell tool runs `npm run dev` in group 20.
+ let mut busy = agent.to_vec();
+ busy.extend([(20, 11, 20), (21, 20, 20)]);
+ assert!(detached_descendant(&busy, 10));
+ // Someone else's process in another group isn't the agent's.
+ assert!(!detached_descendant(&[(10, 1, 10), (30, 1, 30), (31, 30, 31)], 10));
+ }
+
+ #[cfg(unix)]
+ #[tokio::test]
+ async fn a_process_started_in_its_own_group_is_background_work() {
+ use std::process::Stdio;
+ let spawn = |script: &str| {
+ let mut command = tokio::process::Command::new("perl");
+ command.args(["-e", script]).stdin(Stdio::null()).kill_on_drop(true).process_group(0);
+ command.spawn().expect("perl runs")
+ };
+ let plain = spawn("my $pid = fork; if (!$pid) { sleep 30; exit } sleep 30");
+ let detached = spawn("my $pid = fork; if (!$pid) { setpgrp; sleep 30; exit } sleep 30");
+ tokio::time::sleep(Duration::from_millis(300)).await;
+ assert!(!background_work(plain.id()).await);
+ assert!(background_work(detached.id()).await);
+ for child in [plain, detached] {
+ if let Some(pid) = child.id() {
+ let _ = std::process::Command::new("/bin/kill").args(["-KILL", "--", &format!("-{pid}")]).status();
+ }
+ }
+ }
+}
diff --git a/host/src/agent/bot/mod.rs b/host/src/agent/bot/mod.rs
index ce615850..c153f430 100644
--- a/host/src/agent/bot/mod.rs
+++ b/host/src/agent/bot/mod.rs
@@ -17,6 +17,7 @@
mod fast_mode;
mod files;
+mod lifecycle;
mod queue;
mod session;
mod turn;
@@ -34,7 +35,7 @@ use crate::store::{BotConfig, Entry, EntryKind, Lane, now_ms};
use anyhow::{Result, anyhow};
use serde::Serialize;
use serde_json::{Value, json};
-use std::collections::{HashMap, HashSet, VecDeque};
+use std::collections::{HashMap, VecDeque};
use std::sync::Arc;
use std::time::{Duration, Instant};
use tokio::sync::mpsc;
@@ -154,6 +155,7 @@ pub fn spawn(hub: Arc<Hub>, cfg: BotConfig) -> BotHandle {
exit_tail: None,
tools_changed: false,
fast_support,
+ idle_checked: Instant::now(),
};
let task = tokio::spawn(actor.run(rx, interrupted));
BotHandle { tx, task }
@@ -171,6 +173,8 @@ struct SessionCaps {
load: bool,
/// `session/fork`: a thread starts as a copy of the main session.
fork: bool,
+ /// `session/close`: an idle session can be released while the agent keeps running.
+ close: bool,
}
pub(crate) struct Conn {
@@ -179,8 +183,9 @@ pub(crate) struct Conn {
sessions: SessionCaps,
/// Claude's adapter: takes `_meta.systemPrompt` and `_meta.claudeCode.options`.
pub(crate) claude: bool,
- /// Sessions already created or loaded in this process.
- loaded: HashSet<String>,
+ /// Sessions already created or loaded in this process, and when each was last used.
+ loaded: HashMap<String, Instant>,
+ started: Instant,
/// Each live session's Fast mode option, as the agent last listed it.
fast_options: HashMap<String, Value>,
}
@@ -252,6 +257,8 @@ struct Actor {
tools_changed: bool,
/// What the agent says about Fast mode; clients see it in the bot's runtime.
fast_support: FastModeSupport,
+ /// When idle sessions and agents were last looked for.
+ idle_checked: Instant,
}
struct RoutineCompletion {
@@ -316,6 +323,7 @@ impl Actor {
self.cancel_deadline = None;
if let Some(c) = self.conn.take() { c.acp.kill().await; }
}
+ self.release_idle().await;
},
}
}
diff --git a/host/src/agent/bot/session.rs b/host/src/agent/bot/session.rs
index d310c8bb..d59e0780 100644
--- a/host/src/agent/bot/session.rs
+++ b/host/src/agent/bot/session.rs
@@ -6,8 +6,8 @@ use crate::chat::context;
use crate::store::{BotConfig, Entry, EntryKind, Lane, lane_key};
use anyhow::{Result, anyhow, bail};
use serde_json::{Value, json};
-use std::collections::{HashMap, HashSet};
-use std::time::Duration;
+use std::collections::HashMap;
+use std::time::{Duration, Instant};
impl Actor {
/// Which session a lane's turns use: a thread of the bot's own chat has its own
@@ -196,7 +196,7 @@ impl Actor {
&& let Some(sid) = res["sessionId"].as_str().map(str::to_owned)
&& let Some(conn) = self.conn.as_mut()
{
- conn.loaded.insert(sid.clone());
+ conn.loaded.insert(sid.clone(), Instant::now());
self.set_session(slot, Some(&sid));
self.note_options(&sid, &res, false);
forked = true;
@@ -219,7 +219,7 @@ impl Actor {
if let Some(sid) = current {
let prompt_current =
snapshot.as_ref().is_none_or(|s| self.applied_system.get(&sid).is_some_and(|t| *t == s.system));
- if conn.loaded.contains(&sid) && prompt_current {
+ if conn.loaded.contains_key(&sid) && prompt_current {
self.turn_session = Some(sid);
return Ok(());
}
@@ -253,7 +253,7 @@ impl Actor {
} else {
res
};
- conn.loaded.insert(sid.clone());
+ conn.loaded.insert(sid.clone(), Instant::now());
self.note_options(&sid, &res, false);
if let Some(s) = snapshot {
// Its system prompt now names the bot as rendered.
@@ -281,7 +281,7 @@ impl Actor {
let res = self.session_request("session/new", params).await?;
let Some(conn) = self.conn.as_mut() else { bail!("agent not running") };
let sid = res["sessionId"].as_str().ok_or_else(|| anyhow!("agent returned no sessionId"))?.to_owned();
- conn.loaded.insert(sid.clone());
+ conn.loaded.insert(sid.clone(), Instant::now());
let options = select_model(&conn.acp, &res, &sid, &self.cfg).await?;
self.note_options(&sid, &options, false);
self.set_session(slot, Some(&sid));
@@ -431,9 +431,18 @@ pub(crate) async fn start_agent(command: &str, cwd: &str, env: &[(String, String
let sessions = SessionCaps {
load: init["agentCapabilities"]["loadSession"].as_bool().unwrap_or(false),
fork: init["agentCapabilities"]["sessionCapabilities"]["fork"].is_object(),
+ close: init["agentCapabilities"]["sessionCapabilities"]["close"].is_object(),
};
let claude = init["agentCapabilities"]["_meta"]["claudeCode"].is_object();
- Ok(Conn { acp, rx, sessions, claude, loaded: HashSet::new(), fast_options: HashMap::new() })
+ Ok(Conn {
+ acp,
+ rx,
+ sessions,
+ claude,
+ loaded: HashMap::new(),
+ started: Instant::now(),
+ fast_options: HashMap::new(),
+ })
}
#[cfg(test)]
diff --git a/host/src/agent/bot/turn.rs b/host/src/agent/bot/turn.rs
index e143d5e9..bc59dd72 100644
--- a/host/src/agent/bot/turn.rs
+++ b/host/src/agent/bot/turn.rs
@@ -10,7 +10,7 @@ use crate::remote::push::{self, AlertKind};
use crate::store::{EntryKind, Lane, now_ms};
use anyhow::{Context, Result, anyhow};
use serde_json::json;
-use std::time::Duration;
+use std::time::{Duration, Instant};
use tokio::sync::mpsc;
impl Actor {
@@ -183,6 +183,11 @@ impl Actor {
if self.turn.is_none() {
return;
}
+ if let (Some(conn), Some(sid)) = (self.conn.as_mut(), &self.turn_session)
+ && let Some(used) = conn.loaded.get_mut(sid)
+ {
+ *used = Instant::now();
+ }
self.files.cancel();
self.flush(true);
self.seg = Seg::None;