All your machines, one app. For you and your AI agents: agent sessions, desktops, files, logs and GitHub across your Macs, Linux and Windows machines, with an MCP server.
//! Handing a session's work to another agent (Claude Code to Codex, say):
//! Muxin's agent on the machine writes a note in its folder from the
//! conversation so far and where the git work stands (agent/src/handoff.rs),
//! then the new agent starts there, asked to read it first, and the old one
//! ends. A box keeps its container and checkout and changes agents.
//!
//! The work can move to another machine too (agent/src/carry.rs): its commits
//! that aren't on origin, uncommitted changes and new files are packed, copied
//! across through Muxin, and put in a workspace there (a worktree of a
//! checkout of the repository, else a clone) that starts where the work did.
//! The folder it left stays as it was.
use std::sync::Arc;
use std::sync::atomic::AtomicBool;
use serde::Serialize;
use serde_json::{Value, json};
use super::{AgentKind, Control, SessionInfo, StartSession, agent, default_title};
use crate::fleet::Engine;
use crate::fleet::boxes::BoxInfo;
/// Where the note goes, in the session's folder (kept out of git).
pub const NOTE: &str = ".muxin/handoff.md";
/// A handoff, done.
#[derive(Debug, Clone, Serialize)]
pub struct HandedOff {
/// The new agent's session.
pub session: SessionInfo,
/// The note, on the machine.
pub note: String,
/// What the note was made from: "transcript" (the old agent's own),
/// "terminal" (what its terminal showed) or "none" (only the git state).
pub source: String,
/// The old session, when it was kept running.
#[serde(skip_serializing_if = "Option::is_none")]
pub kept: Option<String>,
/// The box, when it was a box's agent.
#[serde(skip_serializing_if = "Option::is_none")]
pub box_id: Option<String>,
/// The workspace the work moved to, on another machine.
#[serde(skip_serializing_if = "Option::is_none")]
pub workspace: Option<String>,
/// What didn't go quite as planned in a move (changes that didn't apply cleanly, ...).
#[serde(skip_serializing_if = "Vec::is_empty")]
pub warnings: Vec<String>,
}
/// What the new agent is asked first.
pub fn prompt(from: &str) -> String {
format!("You're taking over this work from {from}. First read {NOTE}: Muxin wrote it from {from}'s conversation, with where the code stands. Then carry on with what's left.")
}
impl Engine {
/// Hands session `id`'s work (or box `id`'s) to agent `to`: writes the
/// note, starts `to` in the same folder asked to read it, and ends the old
/// session unless `keep`. A box's agent changes in the box. With
/// `machine` (another one), the work moves there first.
pub async fn handoff_session(self: &Arc<Self>, id: &str, to: &str, keep: bool, machine: Option<&str>) -> Result<HandedOff, String> {
let kind = super::agent(to).filter(|k| !k.command.is_empty()).ok_or_else(|| {
let ids: Vec<&str> = super::AGENTS.iter().filter(|a| !a.command.is_empty()).map(|a| a.id).collect();
format!("Hand off to which agent? Use one of: {}.", ids.join(", "))
})?;
if self.demo_world().is_some() {
return self.demo_handoff(id, kind, keep, machine).await;
}
let snap = self.current();
let s = snap.sessions.iter().find(|s| s.id == id).cloned();
let here = self.find_box(id).map(|b| b.machine_id).ok().or_else(|| s.as_ref().map(|s| s.machine_id.clone()));
let target = match machine.map(str::trim).filter(|m| !m.is_empty()) {
Some(m) => Some(snap.machines.iter().find(|x| x.id == m || x.name.eq_ignore_ascii_case(m)).map(|x| x.id.clone()).ok_or_else(|| format!("No machine called {m}."))?),
None => None,
}
.filter(|t| Some(t) != here.as_ref());
let in_box = self.find_box(id).is_ok() || s.as_ref().is_some_and(|s| s.box_id.is_some());
if target.is_some() && in_box {
return Err("A box stays on its machine: hand it to another agent there, or start a new box on the other machine.".into());
}
if let Ok(b) = self.find_box(id) {
return self.box_handoff(&b, kind.id).await;
}
let s = s.ok_or_else(|| format!("No session called {id}."))?;
if let Some(b) = s.box_id.as_deref() {
if b != s.name {
return Err(format!("{} is a shell in box {b}: hand off the box's agent instead.", s.title));
}
let b = self.find_box(b)?;
return self.box_handoff(&b, kind.id).await;
}
let from = super::agent(&s.agent).filter(|k| !k.command.is_empty()).ok_or_else(|| format!("{} is a shell: only an agent's work can be handed off.", s.title))?;
if !s.persistent {
return Err(format!("{} runs only in the Muxin window, so its conversation can't be read from here.", s.title));
}
if let Some(t) = target {
return self.move_session(&s, from, kind, &t, keep).await;
}
// The note, from the transcript (or the terminal, for agents whose transcript Muxin can't read).
let (spec, probe) = self.machine(&s.machine_id).ok_or_else(|| format!("No machine called {}.", s.machine_id))?;
agent::ensure(&spec, probe.as_ref()).await?;
let terminal = self.control_session(&s.id, Control::Read { lines: 400 }).await.unwrap_or_default();
let note = agent::ctl(
&spec,
&json!({
"op": "handoff",
"agent": from.id,
"cwd": s.cwd,
"since": s.created_at.map(|t| t.timestamp()).unwrap_or(0),
"from": from.name,
"to": kind.name,
"base": s.git.as_ref().and_then(|g| g.base.clone()),
"terminal": terminal,
}),
)
.await?;
// The new agent first, so a failure leaves the old one as it was.
let title = if s.title == default_title(from, &s.cwd) { default_title(kind, &s.cwd) } else { s.title.clone() };
let started = self
.start_session(StartSession {
machine_id: s.machine_id.clone(),
agent: kind.id.into(),
cwd: s.cwd.clone(),
title: Some(title.clone()),
prompt: Some(prompt(from.name)),
cols: 120,
rows: 40,
..Default::default()
})
.await
.map_err(|e| format!("The note is in {}, but {e}", s.cwd.trim_end_matches('/').to_string() + "/" + NOTE))?;
let mut session = started;
if !keep {
self.control_session(&s.id, Control::Stop).await?;
// It took a "… 2" title while the old one was still there.
if session.title != title
&& let Ok(renamed) = self.rename_session(&session.id, &title).await
{
session = renamed;
}
}
Ok(HandedOff { session, note: note_path(¬e), source: source(¬e), kept: keep.then(|| s.id.clone()), box_id: None, workspace: None, warnings: Vec::new() })
}
/// The demo's handoff: the new agent's session starts (in a workspace on
/// the other machine for a move) and the old one ends, with no note to write.
async fn demo_handoff(self: &Arc<Self>, id: &str, kind: &'static AgentKind, keep: bool, machine: Option<&str>) -> Result<HandedOff, String> {
let snap = self.current();
let s = snap.sessions.iter().find(|s| s.id == id).cloned().ok_or_else(|| format!("No session called {id}."))?;
if s.box_id.is_some() {
return Err("The demo's boxes are only for show.".into());
}
let from = super::agent(&s.agent).filter(|k| !k.command.is_empty()).ok_or_else(|| format!("{} is a shell: only an agent's work can be handed off.", s.title))?;
let target = match machine.map(str::trim).filter(|m| !m.is_empty()) {
Some(m) => snap.machines.iter().find(|x| x.id == m || x.name.eq_ignore_ascii_case(m)).map(|x| x.id.clone()).ok_or_else(|| format!("No machine called {m}."))?,
None => s.machine_id.clone(),
};
let moved = target != s.machine_id;
let workspace = moved.then(|| format!("ws-{}", super::super::workspaces::random_id(6)));
let cwd = match &workspace {
Some(ws) => format!("~/muxen/workspaces/{ws}"),
None => s.cwd.clone(),
};
let title = if s.title == default_title(from, &s.cwd) { default_title(kind, &s.cwd) } else { s.title.clone() };
let session = self.start_session(StartSession { machine_id: target, agent: kind.id.into(), cwd: cwd.clone(), title: Some(title), ..Default::default() }).await?;
if !keep {
self.control_session(&s.id, Control::Stop).await?;
}
Ok(HandedOff { session, note: format!("{cwd}/{NOTE}"), source: "transcript".into(), kept: keep.then(|| s.id.clone()), box_id: None, workspace, warnings: Vec::new() })
}
/// Moves session `s`'s work to machine `target` and hands it to `kind`
/// there, as an operation (its steps show in Activity).
async fn move_session(self: &Arc<Self>, s: &SessionInfo, from: &'static AgentKind, kind: &'static AgentKind, target: &str, keep: bool) -> Result<HandedOff, String> {
let m = self.current().machines.iter().find(|m| m.id == target).cloned().ok_or_else(|| format!("No machine called {target}."))?;
if m.platform.starts_with("windows") {
return Err(format!("Work can't move to a Windows machine ({}) yet.", m.name));
}
if m.is_down() {
return Err(format!("{} isn't reachable right now.", m.name));
}
// The agent's CLI there (looked up first when Muxin hasn't yet), before anything's copied.
if self.sessions_of(&m.id).is_none_or(|f| f.agents_checked_at.is_none()) {
let _ = self.refresh_tools(&m.id).await;
}
if self.sessions_of(&m.id).and_then(|f| f.agents_checked_at.map(|_| f.agents)).is_some_and(|a| !a.iter().any(|x| x == kind.id)) {
return Err(format!("{} isn't installed on {} (or isn't on its PATH there).", kind.name, m.name));
}
let (src, src_probe) = self.machine(&s.machine_id).ok_or_else(|| format!("No machine called {}.", s.machine_id))?;
let (dst, dst_probe) = self.machine(&m.id).ok_or_else(|| format!("No machine called {}.", m.id))?;
let op = self.begin_op("handoff", format!("Move {} from {} to {} ({})", s.title, src.name, dst.name, kind.name), Some(dst.id.clone()), None);
let pack_id = format!("mv-{}", super::super::workspaces::random_id(8));
let mut made: Option<String> = None;
let result = async {
agent::ensure(&src, src_probe.as_ref()).await?;
agent::ensure(&dst, dst_probe.as_ref()).await?;
self.op_log(op, format!("▸ Writing the note from {}'s conversation", from.name));
let terminal = self.control_session(&s.id, Control::Read { lines: 400 }).await.unwrap_or_default();
let note = agent::ctl(
&src,
&json!({
"op": "handoff",
"agent": from.id,
"cwd": s.cwd,
"since": s.created_at.map(|t| t.timestamp()).unwrap_or(0),
"from": from.name,
"to": kind.name,
"machine": src.name,
"base": s.git.as_ref().and_then(|g| g.base.clone()),
"terminal": terminal,
"write": false,
}),
)
.await?;
self.op_log(op, format!("▸ Packing the work in {}", s.cwd));
let pack = agent::ctl(&src, &json!({ "op": "carry_pack", "pack_id": pack_id, "cwd": s.cwd })).await?;
let (unpushed, uncommitted) = (pack["unpushed"].as_u64().unwrap_or(0), pack["uncommitted"].as_u64().unwrap_or(0));
self.op_log(
op,
format!(
"✓ {} not on origin, {} uncommitted ({})",
plural(unpushed, "commit"),
plural(uncommitted, "file"),
crate::util::bytes(pack["bytes"].as_u64().unwrap_or(0))
),
);
let origin = pack["origin"].as_str().map(String::from);
let base = pack["base"].as_str().map(String::from);
let gh_host = super::super::workspaces::github_web_host(&self.settings().github.api_url);
let github = s.git.as_ref().and_then(|g| g.repo.clone()).or_else(|| origin.as_deref().and_then(|o| crate::fleet::boxes::github_name(o, &gh_host)));
let branch = branch_there(pack["branch"].as_str(), s.git.as_ref().and_then(|g| g.base.as_deref()), origin.is_some(), &s.name);
// A worktree of a checkout of the repository there (looked at now: one may
// have been cloned since), else a clone, else a new repository.
let _ = self.refresh_checkouts(&dst.id).await;
// The user's own checkouts, not folders Muxin made (workspaces, boxes).
let made_by_muxin = |p: &str| p.contains("/muxen/workspaces/") || p.contains("/muxen/boxes/");
let checkout = github
.as_ref()
.and_then(|g| self.checkouts_of(&dst.id).into_iter().find(|c| !made_by_muxin(&c.path) && c.repo.as_deref().is_some_and(|r| r.eq_ignore_ascii_case(g))));
let mut req = super::super::workspaces::CreateWorkspace {
machine: Some(dst.id.clone()),
name: Some(s.title.clone()),
owner: Some("handoff".into()),
..Default::default()
};
match (&checkout, &origin) {
(Some(c), _) => {
self.op_log(op, format!("▸ Making a worktree of {} on {}, on {branch}", c.path, dst.name));
req.worktree_of = Some(c.path.clone());
req.git_ref = base.clone();
req.branch = Some(branch.clone());
}
(None, Some(o)) => {
let repo = github.clone().unwrap_or_else(|| o.clone());
self.op_log(op, format!("▸ Cloning {repo} on {}, on {branch}", dst.name));
req.repo = Some(repo);
req.git_ref = base.clone();
req.branch = Some(branch.clone());
}
(None, None) => self.op_log(op, format!("▸ Making a new repository for it on {}", dst.name)),
}
let ws = self.create_workspace(req).await?;
made = Some(ws.id.clone());
self.op_log(op, format!("▸ Copying the work to {}", dst.name));
let cancel = AtomicBool::new(false);
self.run_copy(op, &src, "~/.muxen/carry", std::slice::from_ref(&pack_id), &dst, "~/.muxen/carry", &cancel, false).await?;
let _ = agent::ctl(&src, &json!({ "op": "carry_drop", "pack_id": pack_id })).await;
let unpacked = agent::ctl(
&dst,
&json!({ "op": "carry_unpack", "pack_id": pack_id, "dir": ws.path, "branch": branch, "base": base, "note": note["text"] }),
)
.await?;
let warnings: Vec<String> = unpacked["warnings"].as_array().into_iter().flatten().filter_map(|w| w.as_str().map(String::from)).collect();
for w in &warnings {
self.op_log(op, format!("! {w}"));
}
self.op_log(op, format!("✓ The work is in {} on {}", ws.path, unpacked["branch"].as_str().unwrap_or(&branch)));
let sub = pack["sub"].as_str().unwrap_or("").trim_matches('/');
let cwd = if sub.is_empty() { ws.path.clone() } else { format!("{}/{sub}", ws.path.trim_end_matches('/')) };
let title = if s.title == default_title(from, &s.cwd) { default_title(kind, &s.cwd) } else { s.title.clone() };
self.op_log(op, format!("▸ Starting {} on {}", kind.name, dst.name));
let session = self
.start_session(StartSession {
machine_id: dst.id.clone(),
agent: kind.id.into(),
cwd,
title: Some(title),
prompt: Some(prompt(&format!("{} on {}", from.name, src.name))),
cols: 120,
rows: 40,
..Default::default()
})
.await?;
if !keep {
self.control_session(&s.id, Control::Stop).await?;
}
self.op_log(op, format!("✓ {} took over on {}", kind.name, dst.name));
Ok(HandedOff {
session,
note: format!("{}/{NOTE}", ws.path.trim_end_matches('/')),
source: source(¬e),
kept: keep.then(|| s.id.clone()),
box_id: None,
workspace: Some(ws.id),
warnings,
})
}
.await;
if let Err(e) = &result {
self.op_log(op, format!("error: {e}"));
// Nothing half-made stays: the packs, and the workspace there.
let _ = agent::ctl(&src, &json!({ "op": "carry_drop", "pack_id": pack_id })).await;
let _ = agent::ctl(&dst, &json!({ "op": "carry_drop", "pack_id": pack_id })).await;
if let Some(ws) = made {
let _ = self.destroy_workspace(&ws, false).await;
}
}
self.op_finish(op, result.as_ref().map(|_| ()).map_err(Clone::clone));
result
}
/// A box changes agents: the note in its checkout, its agent's session
/// ends, and the new agent starts in the box on it.
async fn box_handoff(self: &Arc<Self>, b: &BoxInfo, to: &str) -> Result<HandedOff, String> {
if !crate::fleet::boxes::BOX_AGENTS.contains(&to) {
return Err(format!("A box can't run {to}."));
}
let from = super::agent(&b.agent).map(|k| k.name).unwrap_or(&b.agent);
let to_name = super::agent(to).map(|k| k.name).unwrap_or(to);
let (spec, probe) = self.machine(&b.machine_id).ok_or_else(|| format!("{} isn't in Muxin anymore.", b.machine_id))?;
agent::ensure(&spec, probe.as_ref()).await?;
let terminal = match &b.session_id {
Some(sid) => self.control_session(sid, Control::Read { lines: 400 }).await.unwrap_or_default(),
None => String::new(),
};
// The box's home: next to its checkout (its agents' transcripts that aren't the machine's).
let home = std::path::Path::new(&b.path).parent().map(|p| p.join("home").to_string_lossy().to_string());
let note = agent::ctl(
&spec,
&json!({
"op": "handoff",
"agent": b.agent,
"cwd": b.path,
"since": b.created_at.map(|t| t.timestamp()).unwrap_or(0),
"homes": home.into_iter().collect::<Vec<_>>(),
"from": from,
"to": to_name,
"base": b.git.as_ref().and_then(|g| g.base.clone()),
"terminal": terminal,
}),
)
.await?;
let (start, typed) = crate::fleet::boxes::launcher(to).ok_or_else(|| format!("A box can't run {to}."))?;
agent::ctl(&spec, &json!({ "op": "box_switch", "box_id": b.id, "agent": to, "start": start, "type_prompt": typed })).await?;
agent::ctl(&spec, &json!({ "op": "box_resume", "box_id": b.id, "prompt": prompt(from) })).await?;
let found = self.refresh_sessions(&spec.id).await?;
let session = found.sessions.into_iter().find(|s| s.name == b.id).ok_or_else(|| format!("{to_name} didn't start in {}.", b.id))?;
Ok(HandedOff { session, note: note_path(¬e), source: source(¬e), kept: None, box_id: Some(b.id.clone()), workspace: None, warnings: Vec::new() })
}
}
/// The branch the work goes on in the other machine's checkout: its own, but
/// not the default branch of a clone ("main" is there already, as origin has
/// it), so one named for the session then.
fn branch_there(branch: Option<&str>, base: Option<&str>, has_origin: bool, session: &str) -> String {
let default = base.and_then(|b| b.split_once('/')).map(|(_, b)| b);
match branch.filter(|b| !b.is_empty()) {
Some(b) if has_origin && (Some(b) == default || (default.is_none() && matches!(b, "main" | "master"))) => format!("muxin/{session}"),
Some(b) => b.to_string(),
None if has_origin => format!("muxin/{session}"),
None => "main".into(),
}
}
fn plural(n: u64, what: &str) -> String {
if n == 1 { format!("1 {what}") } else { format!("{n} {what}s") }
}
fn note_path(reply: &Value) -> String {
reply["path"].as_str().unwrap_or(NOTE).to_string()
}
fn source(reply: &Value) -> String {
reply["source"].as_str().unwrap_or("none").to_string()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn the_work_keeps_its_branch_but_not_the_default_one() {
assert_eq!(branch_there(Some("fix-login"), Some("origin/main"), true, "claude-3f9a"), "fix-login");
assert_eq!(branch_there(Some("main"), Some("origin/main"), true, "claude-3f9a"), "muxin/claude-3f9a");
assert_eq!(branch_there(Some("master"), None, true, "codex-1"), "muxin/codex-1");
assert_eq!(branch_there(None, Some("origin/main"), true, "codex-1"), "muxin/codex-1");
// Without a remote there's no default branch to clash with.
assert_eq!(branch_there(Some("main"), None, false, "codex-1"), "main");
assert_eq!(branch_there(None, None, false, "codex-1"), "main");
}
}