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.
Rust acpagent-client-protocolai-agentsai-assistantclaudeclaude-codecodexcoding-agentscursorgeminigemini-cligrok-bot-alternativeiosiphonelinuxmacosmcpopen-sourcerustself-hosted
//! The bot's side of its fallback chain (`agent::fallback`). Each turn starts on the first agent, in order, that
//! isn't resting; when the agent fails for a reason that moves on, the same turn starts again on the next one, told
//! what the agents before it did. Each agent keeps its own session (`park`), so going back resumes it, with a
//! catch-up of what was said meanwhile.
mod park;
pub(super) use park::resume_step;
use super::{Actor, Done, NoticeStyle};
use crate::LockExt;
use crate::agent::fallback::{self, Reason, carry, rest};
use crate::store::{BotConfig, Entry, EntryKind, Lane, now_ms};
use serde_json::{Value, json};
use tokio::sync::mpsc;
/// Longest handoff a chat line carries for the apps to unfold.
const LINE_CARRIED: usize = 8_000;
/// Chat messages read for a recap or a catch-up.
const READ: i64 = 120;
/// Tool calls a takeover lists, the latest ones.
const TOOLS_LISTED: usize = 40;
/// What a turn needs to start again on the next agent.
#[derive(Clone)]
struct Attempt {
lane: Lane,
entries: Vec<String>,
text: String,
}
/// The running turn's place in the chain.
#[derive(Default)]
pub(super) struct Relay {
/// The turn, to start again elsewhere; `None` for a hidden turn (a compaction, a resume).
attempt: Option<Attempt>,
/// Agents (their `rest::account`) this turn already failed on.
tried: Vec<String>,
/// Agents (their `rest::account`) that lack their step's model: skipped until the bot's settings change.
no_model: Vec<String>,
/// Agents this turn left signed out, in order, whose sign-in cards are in the chat. When no agent can answer, the
/// first one's card holds the turn's messages.
signed_out: Vec<String>,
/// The next `start_turn` is this turn again, on the next agent.
retrying: bool,
/// The agents that failed this turn, in order: why, and what each had done.
failed: Vec<carry::Failed>,
/// Why the agent just left stopped and when it comes back, for the chat line.
stopped: Option<(Reason, Option<i64>)>,
/// Every agent of the chain failed this turn: its failure notice says how each one is.
exhausted: bool,
/// The main session moved off this agent (and its session): its next turn there starts with a recap or a
/// catch-up. Kept until the main session comes up on an agent.
recap: Option<(String, Option<String>)>,
/// This attempt's move in the chat, which shows what the agent was told once its session is up.
line: Option<String>,
/// What this attempt's agent hears first after the user's handoff (`carry_in`); this turn's only.
pub(super) carried: Option<String>,
}
/// The bot as it runs on `current`'s agent with `base`'s settings, also when that agent is no longer in its chain.
pub(super) fn running(base: &BotConfig, current: &BotConfig) -> BotConfig {
match fallback::step_of(base, ¤t.backend) {
Some(step) => fallback::effective(base, step),
None => BotConfig {
backend: current.backend.clone(),
command: current.command.clone(),
model: current.model.clone(),
model_options: current.model_options.clone(),
..base.clone()
},
}
}
impl Actor {
/// The step of the agent the bot is on (its own: 0).
fn step(&self) -> Option<usize> {
fallback::step_of(&self.base, &self.cfg.backend)
}
/// The first step, in order, whose agent this turn hasn't failed on and that isn't resting. A signed-out agent
/// rests too: the sign-in state an app last checked can be stale.
fn next_step(&self, now: i64) -> Option<usize> {
(0..fallback::steps(&self.base)).find(|&s| {
let account = fallback::account(&self.base, s);
!self.relay.tried.contains(&account)
&& !self.relay.no_model.contains(&account)
&& rest::get(&self.hub.store, &account, now).is_none()
})
}
/// `start_turn`, once the turn has its lane and number: picks the agent. Not for hidden turns.
pub(super) async fn relay_turn(&mut self, lane: &Lane, entries: &[String], text: &str) {
if !std::mem::take(&mut self.relay.retrying) {
self.relay.tried.clear();
self.relay.failed.clear();
self.relay.signed_out.clear();
self.relay.stopped = None;
}
self.relay.exhausted = false;
self.relay.line = None;
self.relay.carried = None;
self.relay.attempt = Some(Attempt { lane: lane.clone(), entries: entries.to_vec(), text: text.to_owned() });
let now = now_ms();
let target = self.next_step(now).unwrap_or(0);
self.left_signed_out_before(target, now);
let from = self.cfg.clone();
if fallback::account(&self.base, target) != rest::account(&from) {
self.switch_to(target).await;
self.relay.line = self.tell_switch(&from, target);
}
}
/// A message that joined the running turn (`steer`) goes with it to the next agent.
pub(super) fn relay_joined(&mut self, entry_id: &str, text: &str) {
if let Some(attempt) = &mut self.relay.attempt {
attempt.entries.push(entry_id.to_owned());
attempt.text = format!("{}\n\n{text}", attempt.text);
}
}
/// A turn (or its retry) starting on step `target`: the agents before it that rest because a bot found them
/// signed out ask to be signed in here too.
fn left_signed_out_before(&mut self, target: usize, now: i64) {
let signed_out = |s: &usize| {
rest::get(&self.hub.store, &fallback::account(&self.base, *s), now)
.is_some_and(|r| r.reason == Reason::SignedOut)
};
let skipped: Vec<String> =
(0..target).filter(signed_out).map(|s| fallback::backend(&self.base, s).to_owned()).collect();
for agent in skipped {
self.left_signed_out(&agent);
}
}
/// `start_turn`, once the session is up (a new one, or the agent's own resumed): sets what the agent should hear
/// first, and puts it on the chat line of the move. The main session gets a recap of the chat in a new session or
/// a catch-up in its own; a retried turn gets what the agents before did. Not for hidden turns.
pub(super) fn carry_in(&mut self) {
let mut carried = Vec::new();
if self.slot().is_none()
&& let Some((agent, session)) = self.relay.recap.take()
&& let Some(text) = self.recap(&agent, session.as_deref())
{
carried.push(text);
}
carried.extend(carry::takeover(&self.relay.failed));
let text = (!carried.is_empty()).then(|| carried.join("\n\n"));
if let Some(text) = &text
&& let Some(id) = self.relay.line.take()
&& let Some(mut line) = self.hub.store.entry(&id)
{
line.data["agentSwitch"]["carried"] = crate::agent::acp::truncate(text, LINE_CARRIED).into();
self.hub.set_entry(&id, &line.data);
}
self.relay.carried = text;
}
/// The chat line for a move from the agent `from` ran on to step `target`'s (`carry_in` adds what the new agent
/// was told).
fn tell_switch(&self, from: &BotConfig, target: usize) -> Option<String> {
let to = self.cfg.backend.clone();
let from_account = rest::account(from);
let from = from.backend.as_str();
// Toward the bot's own agent, or away from one it no longer uses.
let back = fallback::step_of(&self.base, from).is_none_or(|s| target < s);
let (reason, until) = self
.relay
.stopped
.or_else(|| rest::get(&self.hub.store, &from_account, now_ms()).map(|r| (r.reason, Some(r.until))))
.unzip();
let until = until.flatten();
let text = if back {
format!("Back on {}.", fallback::name(&to))
} else {
let why = reason.map_or("can't answer right now", Reason::phrase);
let when = until
.filter(|_| reason == Some(Reason::UsageLimit))
.map(|t| format!(" (resets {})", carry::in_words(t - now_ms())))
.unwrap_or_default();
format!("{} {why}{when}. {} carried on.", fallback::name(from), fallback::name(&to))
};
let data = json!({
"text": text,
"style": "info",
"agentSwitch": {
"from": from, "to": to, "back": back, "reason": reason, "resetsAt": until, "carried": null,
},
});
self.line(data)
}
/// A notice with its own fields in the running turn's lane (or the bot's own chat between turns).
fn line(&self, data: Value) -> Option<String> {
let entry = if let Some(turn) = self.turn {
self.add(EntryKind::Notice, turn, data)
} else {
let main = Lane::main(&self.base.id);
self.hub.add_entry(&main, EntryKind::Notice, self.hub.store.max_turn(&self.base.id), &data)
};
entry.map(|e| e.id)
}
/// What the agent the main session just moved to should hear first: a catch-up when it resumed its own
/// session, a recap of the conversation when it started a new one. Only the user's messages and the bot's
/// replies count, never from before the user last started a new session.
fn recap(&self, from: &str, from_session: Option<&str>) -> Option<String> {
let bot = &self.base.id;
let main = Lane::main(bot);
let fresh: i64 = self.hub.store.kv_get(&park::fresh_key(bot)).and_then(|v| v.parse().ok()).unwrap_or(0);
let current = self.relay.attempt.as_ref().map(|a| a.entries.as_slice()).unwrap_or_default();
let messages = |after: i64| -> Option<Vec<Entry>> {
let mut entries = self.hub.store.messages_after(&main, after.max(fresh), READ).ok()?;
entries.retain(|e| !current.contains(&e.id));
Some(entries)
};
if !self.session_fresh {
let left = self.hub.store.kv_get(&park::left_key(bot, &self.cfg.backend)).and_then(|v| v.parse().ok());
return carry::catch_up(&carry::said(&messages(left.unwrap_or(i64::MAX))?));
}
let entries = messages(0)?;
let said = carry::said(&entries);
if said.is_empty() {
return None;
}
// The open plan, if it's as recent as the messages repeated.
let oldest = entries.first().map_or(0, |e| e.seq);
let summary = from_session.and_then(|s| self.hub.store.kv_get(&crate::chat::handoff::summary_key(bot, s)));
let plan = self
.hub
.store
.last_of_kind(&main, EntryKind::Plan, oldest.max(fresh))
.map(|e| crate::chat::handoff::plan_text(&e.data));
let bookmark = entries.last().map(|e| e.id.as_str());
Some(carry::recap(&fallback::name(from), summary.as_deref(), &said, plan.as_deref(), bookmark))
}
/// What the failing attempt did: its tool calls, the messages it sent, its last words.
fn so_far(&self) -> Option<String> {
let mut tools: Vec<_> = self.tools.values().filter_map(|id| self.hub.store.entry(id)).collect();
tools.sort_by_key(|e| e.seq);
let skip = tools.len().saturating_sub(TOOLS_LISTED);
let tools: Vec<(String, String)> = tools[skip..]
.iter()
.map(|e| {
let title = e.data["title"].as_str().unwrap_or("A tool call").to_owned();
(title, e.data["status"].as_str().unwrap_or("pending").to_owned())
})
.collect();
let narration = self.last_text.as_ref().and_then(|id| self.hub.store.entry(id));
carry::so_far(&tools, &self.sent, narration.as_ref().and_then(|e| e.data["text"].as_str()))
}
/// The turn failed with `error`: when it may move on and another agent can take it, starts it again there.
/// Whether the turn is handled (running again, or its failure reported).
pub(super) async fn fall_back(&mut self, error: &anyhow::Error, done_tx: &mpsc::UnboundedSender<Done>) -> bool {
if self.stop_requested || self.routine_timed_out || self.compacting.is_some() || self.turn.is_none() {
return false;
}
let (Some(mut reason), Some(attempt)) = (fallback::reason::of(error), self.relay.attempt.clone()) else {
return false;
};
let mut start_error: Option<anyhow::Error> = None;
loop {
let now = now_ms();
let (agent, account) = (self.cfg.backend.clone(), rest::account(&self.cfg));
if reason == Reason::SignedOut {
crate::agent::backends::set_signed_in(&agent, Some(false));
}
let resets = rest::reset_time(&self.hub.usage.locked(), &agent, now);
let rest = rest::record(&self.hub.store, &account, reason, now, resets);
if rest.is_some() {
fallback::tell_bots(&self.hub, &account);
}
if reason == Reason::ModelMissing {
self.relay.no_model.push(account.clone());
}
self.relay.tried.push(account);
let failed = start_error.as_ref().unwrap_or(error);
if self.next_step(now).is_none() {
self.relay.exhausted = true;
// No agent answers the turn's messages: they go out again once the first one left signed out is
// signed in (the last agent's own card holds them only when there is none, `held_for_sign_in`).
if let Some(first) = self.relay.signed_out.first().filter(|_| !self.turn_entries.is_empty()) {
self.sign_in_card(first, &self.turn_entries);
}
return match start_error {
Some(e) => {
self.start_failed(&e);
true
}
None => false,
};
}
if reason == Reason::SignedOut {
self.left_signed_out(&agent);
}
self.report_turn(false, Some(failed), "error");
crate::analytics::agent_fell_back(&self.hub, &agent, reason);
let done = self.so_far();
self.relay.failed.push(carry::Failed { agent: fallback::name(&agent), reason, done });
self.relay.stopped = Some((reason, rest.map(|r| r.until)));
self.close_attempt(true);
self.relay.retrying = true;
match self.start_turn(attempt.lane.clone(), &attempt.entries, &attempt.text, false, done_tx).await {
Ok(()) => return true,
Err(e) => {
let Some(r) = fallback::reason::of(&e) else {
self.start_failed(&e);
return true;
};
reason = r;
start_error = Some(e);
}
}
}
}
/// The turn moves past agent `agent`, signed out: its sign-in card goes in the chat, holding no message (the next
/// agent answers them, unless none can: `fall_back`). Signing in there brings the bot back (`fallback::signed_in`).
/// Once per turn.
fn left_signed_out(&mut self, agent: &str) {
if crate::agent::backends::harness(agent).is_some() && !self.relay.signed_out.iter().any(|a| a == agent) {
self.relay.signed_out.push(agent.to_owned());
self.sign_in_card(agent, &[]);
}
}
/// The messages the sign-in card of the agent this turn ended on holds: none when the card of an agent the turn
/// left signed out holds them already (`fall_back` ran out of agents), so they go out again once.
pub(super) fn held_for_sign_in(&self) -> &[String] {
if self.relay.exhausted && !self.relay.signed_out.is_empty() { &[] } else { &self.turn_entries }
}
/// A hidden turn (a compaction, a resume) stays on its agent and isn't started again elsewhere.
pub(super) fn hidden_turn(&mut self) {
self.relay.attempt = None;
self.relay.retrying = false;
self.relay.exhausted = false;
self.relay.carried = None;
}
/// The failure notice: with a failure that moves on, a bot without fallbacks offers to add one, and a bot whose
/// agents all failed this turn (`fall_back` ran out of them) says how each one is. It carries the turn's stop
/// `reason` (see `stop_notice`).
pub(super) fn failure_notice(&self, error: &anyhow::Error, text: &str, reason: &str) {
let mut data = json!({"text": text, "style": NoticeStyle::Error, "stopReason": reason});
match fallback::reason::of(error) {
Some(Reason::UsageLimit | Reason::OutOfCredits | Reason::RateLimited | Reason::Overloaded)
if self.base.fallbacks.is_empty() =>
{
data["addFallback"] = true.into();
}
Some(_) if self.relay.exhausted && !self.base.fallbacks.is_empty() => {
data["text"] = format!("{text}\n\n{}", self.chain_note()).into();
}
_ => {}
}
self.line(data);
}
/// How each agent of the chain is: "No agent in this bot's list could answer: Claude Code reached its usage
/// limit (resets in 2 h); Codex is rate limited (back in 4 min)."
fn chain_note(&self) -> String {
let now = now_ms();
let parts: Vec<String> = (0..fallback::steps(&self.base))
.map(|s| {
let agent = fallback::backend(&self.base, s);
match rest::get(&self.hub.store, &fallback::account(&self.base, s), now) {
Some(r) => {
let when = if r.reason == Reason::UsageLimit { "resets" } else { "back" };
let wait = carry::in_words(r.until - now);
format!("{} {} ({when} {wait})", fallback::name(agent), r.reason.phrase())
}
None => format!("{} couldn't answer", fallback::name(agent)),
}
})
.collect();
format!("No agent in this bot's list could answer: {}.", parts.join("; "))
}
/// A turn that couldn't start: on the next agent if one can take it, otherwise the failure as usual.
pub(super) async fn start_error(&mut self, error: anyhow::Error, done_tx: &mpsc::UnboundedSender<Done>) {
if !self.fall_back(&error, done_tx).await {
self.start_failed(&error);
}
}
/// The agent answered a turn: whatever rest it had is over.
pub(super) fn agent_answered(&mut self) {
fallback::end_rest(&self.hub, &rest::account(&self.cfg));
}
/// `switchBack`: the bot's own agent again, now when idle, or for its next turn.
pub(super) async fn switch_back(&mut self) {
let own = fallback::account(&self.base, 0);
fallback::end_rest(&self.hub, &own);
if self.turn.is_none() && rest::account(&self.cfg) != own {
let from = self.cfg.clone();
self.idle_relay();
self.switch_to(0).await;
self.tell_switch(&from, 0);
}
}
/// After a settings change: forgets parked sessions of agents whose step changed or left the chain, and moves an
/// idle bot off an agent it no longer uses.
pub(super) async fn settle_chain(&mut self, old: &BotConfig) {
self.forget_changed(old);
// A model the agent lacked may be one the bot no longer asks for.
self.relay.no_model.clear();
if self.step().is_none() && self.turn.is_none() {
let from = self.cfg.clone();
self.idle_relay();
let target = self.next_step(now_ms()).unwrap_or(0);
self.switch_to(target).await;
self.tell_switch(&from, target);
} else {
self.mark_step();
}
}
/// Between turns: the last turn's place in the chain is over, not the recap the main session still owes.
fn idle_relay(&mut self) {
self.relay = Relay { recap: self.relay.recap.take(), ..Relay::default() };
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_bot_keeps_running_an_agent_that_left_its_chain_until_it_moves_off() {
let mut base: BotConfig =
serde_json::from_value(json!({"id": "b", "name": "B", "backend": "claude", "model": "opus"})).expect("bot");
let mut on_codex = base.clone();
on_codex.backend = "codex".into();
on_codex.model = Some("gpt-5.5".into());
base.description = "new instructions".into();
let cfg = running(&base, &on_codex);
assert_eq!((cfg.backend.as_str(), cfg.model.as_deref()), ("codex", Some("gpt-5.5")));
assert_eq!(cfg.description, "new instructions");
assert_eq!(running(&base, &base).backend, "claude");
}
}