feat: add /topology command with Canvas-based agent graph overlay (#37)

* feat: add /topology command with graphical Canvas-based agent overlay

Surface agent parent/child relationships in TUI via a top-right overlay
that renders a node-link graph using ratatui Canvas. Active agents show
animated spinner dots; finished agents are removed from the graph.

- Extend SubAgentSpawned event with parent + model fields (serde-compat)
- Track topology in SessionState (AgentViewState.parent/children)
- BFS tree layout positions nodes by level with adaptive overlay sizing
- /topology slash command toggles overlay on/off

* fix: rustfmt formatting + keep all files within 200-line limit

* fix: use EXE_SUFFIX for Windows binary path in e2e bootstrap test

Author: yishuiliunian

crates/loopal-agent-hub/src/agent_io.rs

@@ -71,9 +71,10 @@ pub async fn agent_io_loop(
                     spawn_wait_agent(hub.clone(), conn.clone(), id, params, agent_name.clone());
                 } else if method.starts_with("hub/") {
                     info!(agent = %agent_name, %method, "hub request received");
-                    match dispatch_hub_request(&hub, &method, params, agent_name.clone()).await
-                    {
-                        Ok(result) => { let _ = conn.respond(id, result).await; }
+                    match dispatch_hub_request(&hub, &method, params, agent_name.clone()).await {
+                        Ok(result) => {
+                            let _ = conn.respond(id, result).await;
+                        }
                         Err(e) => {
                             warn!(agent = %agent_name, %method, error = %e, "hub request failed");
                             let _ = conn
@@ -102,7 +103,11 @@ pub async fn agent_io_loop(
         }
     }
     // Prefer AttemptCompletion output over accumulated stream text
-    completion_output.or(if last_stream.is_empty() { None } else { Some(last_stream) })
+    completion_output.or(if last_stream.is_empty() {
+        None
+    } else {
+        Some(last_stream)
+    })
 }
 
 /// Spawn hub/wait_agent in a background task so it doesn't block the IO loop.
@@ -115,11 +120,16 @@ fn spawn_wait_agent(
 ) {
     tokio::spawn(async move {
         match crate::dispatch::dispatch_hub_request(
-            &hub, WAIT_AGENT_METHOD, params, agent_name.clone(),
+            &hub,
+            WAIT_AGENT_METHOD,
+            params,
+            agent_name.clone(),
         )
         .await
         {
-            Ok(result) => { let _ = conn.respond(request_id, result).await; }
+            Ok(result) => {
+                let _ = conn.respond(request_id, result).await;
+            }
             Err(e) => {
                 warn!(agent = %agent_name, "background wait_agent failed: {e}");
                 let _ = conn

crates/loopal-agent-hub/src/connection_ops.rs

@@ -66,10 +66,7 @@ impl AgentHub {
     }
 
     /// Create a completion watcher for a named agent.
-    pub fn watch_completion(
-        &mut self,
-        name: &str,
-    ) -> tokio::sync::watch::Receiver<Option<String>> {
+    pub fn watch_completion(&mut self, name: &str) -> tokio::sync::watch::Receiver<Option<String>> {
         let (tx, rx) = tokio::sync::watch::channel(None);
         self.completions.insert(name.to_string(), tx);
         rx
@@ -80,9 +77,12 @@ impl AgentHub {
         self.agents
             .get(parent)
             .map(|a| {
-                a.info.children.iter()
+                a.info
+                    .children
+                    .iter()
                     .filter(|c| {
-                        self.agents.get(c.as_str())
+                        self.agents
+                            .get(c.as_str())
                             .is_some_and(|a| a.info.lifecycle == AgentLifecycle::Running)
                     })
                     .cloned()
@@ -99,9 +99,9 @@ impl AgentHub {
                 let conn = conn.clone();
                 let n = name.clone();
                 tokio::spawn(async move {
-                    let _ = conn.send_notification(
-                        methods::AGENT_INTERRUPT.name, serde_json::json!({}),
-                    ).await;
+                    let _ = conn
+                        .send_notification(methods::AGENT_INTERRUPT.name, serde_json::json!({}))
+                        .await;
                     tracing::info!(agent = %n, "sent interrupt to orphan");
                 });
             }

crates/loopal-agent-hub/src/dispatch/dispatch_handlers.rs

@@ -80,7 +80,10 @@ pub async fn handle_spawn_agent(
     params: Value,
     from_agent: &str,
 ) -> Result<Value, String> {
-    let name = params["name"].as_str().ok_or("missing 'name' field")?.to_string();
+    let name = params["name"]
+        .as_str()
+        .ok_or("missing 'name' field")?
+        .to_string();
     let cwd = params["cwd"].as_str().unwrap_or(".").to_string();
     let model = params["model"].as_str().map(String::from);
     let prompt = params["prompt"].as_str().map(String::from);
@@ -90,9 +93,8 @@ pub async fn handle_spawn_agent(
     let hub_clone = hub.clone();
     let name_clone = name.clone();
     let handle = tokio::spawn(async move {
-        crate::spawn_manager::spawn_and_register(
-            hub_clone, name_clone, cwd, model, prompt, parent,
-        ).await
+        crate::spawn_manager::spawn_and_register(hub_clone, name_clone, cwd, model, prompt, parent)
+            .await
     });
 
     let agent_id = handle

crates/loopal-agent-hub/src/dispatch/topology_handlers.rs

@@ -7,10 +7,7 @@ use tokio::sync::Mutex;
 
 use crate::hub::AgentHub;
 
-pub async fn handle_agent_info(
-    hub: &Arc<Mutex<AgentHub>>,
-    params: Value,
-) -> Result<Value, String> {
+pub async fn handle_agent_info(hub: &Arc<Mutex<AgentHub>>, params: Value) -> Result<Value, String> {
     let name = params["name"].as_str().ok_or("missing 'name'")?;
     let h = hub.lock().await;
 

crates/loopal-agent-hub/src/dispatch/wait_handler.rs

@@ -10,11 +10,11 @@ use tracing::info;
 use crate::hub::AgentHub;
 
 /// Wait for an agent to finish. Timeout: 10 minutes.
-pub async fn handle_wait_agent(
-    hub: &Arc<Mutex<AgentHub>>,
-    params: Value,
-) -> Result<Value, String> {
-    let name = params["name"].as_str().ok_or("missing 'name' field")?.to_string();
+pub async fn handle_wait_agent(hub: &Arc<Mutex<AgentHub>>, params: Value) -> Result<Value, String> {
+    let name = params["name"]
+        .as_str()
+        .ok_or("missing 'name' field")?
+        .to_string();
     info!(agent = %name, "handle_wait_agent start");
 
     let mut rx = {

crates/loopal-agent-hub/src/hub.rs

@@ -65,11 +65,7 @@ impl AgentHub {
 
     /// Register a connected agent.
     /// `parent` is the spawning agent's name (None for root/TUI).
-    pub fn register_connection(
-        &mut self,
-        name: &str,
-        conn: Arc<Connection>,
-    ) -> Result<(), String> {
+    pub fn register_connection(&mut self, name: &str, conn: Arc<Connection>) -> Result<(), String> {
         self.register_connection_with_parent(name, conn, None, None)
     }
 
@@ -104,8 +100,7 @@ impl AgentHub {
     /// remove cached output and pending watchers.
     pub fn unregister_connection(&mut self, name: &str) {
         // Extract parent name before mutating
-        let parent_name = self.agents.get(name)
-            .and_then(|a| a.info.parent.clone());
+        let parent_name = self.agents.get(name).and_then(|a| a.info.parent.clone());
         if let Some(ref p) = parent_name {
             if let Some(parent) = self.agents.get_mut(p.as_str()) {
                 parent.info.children.retain(|c| c != name);
@@ -127,18 +122,14 @@ impl AgentHub {
 
     /// Get a named agent's IPC Connection (if connected).
     pub fn get_agent_connection(&self, name: &str) -> Option<Arc<Connection>> {
-        self.agents
-            .get(name)
-            .and_then(|a| a.state.connection())
+        self.agents.get(name).and_then(|a| a.state.connection())
     }
 
     /// Collect all connected agents with their Connections.
     pub fn all_agent_connections(&self) -> Vec<(String, Arc<Connection>)> {
         self.agents
             .iter()
-            .filter_map(|(name, agent)| {
-                agent.state.connection().map(|c| (name.clone(), c))
-            })
+            .filter_map(|(name, agent)| agent.state.connection().map(|c| (name.clone(), c)))
             .collect()
     }
 
@@ -166,15 +157,19 @@ impl AgentHub {
 
     /// Build serializable topology snapshot.
     pub fn topology_snapshot(&self) -> serde_json::Value {
-        let agents: Vec<serde_json::Value> = self.agents.iter()
+        let agents: Vec<serde_json::Value> = self
+            .agents
+            .iter()
             .filter(|(n, _)| !n.starts_with('_')) // skip internal (_tui)
-            .map(|(name, a)| serde_json::json!({
-                "name": name,
-                "parent": a.info.parent,
-                "children": a.info.children,
-                "lifecycle": format!("{:?}", a.info.lifecycle),
-                "model": a.info.model,
-            }))
+            .map(|(name, a)| {
+                serde_json::json!({
+                    "name": name,
+                    "parent": a.info.parent,
+                    "children": a.info.children,
+                    "lifecycle": format!("{:?}", a.info.lifecycle),
+                    "model": a.info.model,
+                })
+            })
             .collect();
         serde_json::json!({ "agents": agents })
     }

crates/loopal-agent-hub/src/hub_server.rs

@@ -65,7 +65,9 @@ pub async fn accept_loop(listener: TcpListener, hub: Arc<Mutex<AgentHub>>, token
                     let (tx, owned_rx) = tokio::sync::mpsc::channel(256);
                     tokio::spawn(async move {
                         while let Some(msg) = rx.recv().await {
-                            if tx.send(msg).await.is_err() { break; }
+                            if tx.send(msg).await.is_err() {
+                                break;
+                            }
                         }
                     });
                     crate::agent_io::start_agent_io(hub, &name, conn, owned_rx, false);
@@ -102,9 +104,7 @@ async fn wait_for_register(
                     .as_str()
                     .ok_or_else(|| anyhow::anyhow!("hub/register: missing 'name'"))?
                     .to_string();
-                let _ = conn
-                    .respond(id, serde_json::json!({"ok": true}))
-                    .await;
+                let _ = conn.respond(id, serde_json::json!({"ok": true})).await;
                 return Ok(name);
             }
             let _ = conn

crates/loopal-agent-hub/src/routing.rs

@@ -14,8 +14,8 @@ pub async fn route_to_agent(
     envelope: &Envelope,
     observation_tx: &mpsc::Sender<AgentEvent>,
 ) -> Result<(), String> {
-    let params = serde_json::to_value(envelope)
-        .map_err(|e| format!("failed to serialize envelope: {e}"))?;
+    let params =
+        serde_json::to_value(envelope).map_err(|e| format!("failed to serialize envelope: {e}"))?;
 
     conn.send_request(methods::AGENT_MESSAGE.name, params)
         .await

crates/loopal-agent-hub/src/spawn_manager.rs

@@ -33,19 +33,33 @@ pub async fn spawn_and_register(
         return Err(format!("agent initialize failed: {e}"));
     }
     info!(agent = %name, "spawn: starting agent");
-    if let Err(e) = client.start_agent(
-        std::path::Path::new(&cwd), model.as_deref(), Some("act"),
-        prompt.as_deref(), None, false, None,
-    ).await {
+    if let Err(e) = client
+        .start_agent(
+            std::path::Path::new(&cwd),
+            model.as_deref(),
+            Some("act"),
+            prompt.as_deref(),
+            None,
+            false,
+            None,
+        )
+        .await
+    {
         warn!(agent = %name, error = %e, "spawn: start failed, killing orphan");
         let _ = agent_proc.shutdown().await;
         return Err(format!("agent/start failed: {e}"));
     }
 
     let (conn, incoming_rx) = client.into_parts();
     let agent_id = register_agent_connection(
-        hub, &name, conn, incoming_rx, parent.as_deref(), model.as_deref(),
-    ).await;
+        hub,
+        &name,
+        conn,
+        incoming_rx,
+        parent.as_deref(),
+        model.as_deref(),
+    )
+    .await;
 
     // Supervised process cleanup: when agent exits, task completes.
     // AgentProcess::drop will kill the child (kill_on_drop) if not exited.
@@ -77,9 +91,7 @@ pub async fn register_agent_connection(
                 warn!(agent = %name, parent = %p, "parent not found, registering as orphan");
             }
         }
-        if let Err(e) = h.register_connection_with_parent(
-            name, conn.clone(), parent, model,
-        ) {
+        if let Err(e) = h.register_connection_with_parent(name, conn.clone(), parent, model) {
             warn!(agent = %name, error = %e, "registration failed");
             return agent_id;
         }
@@ -94,6 +106,8 @@ pub async fn register_agent_connection(
         let event = AgentEvent::root(AgentEventPayload::SubAgentSpawned {
             name: name.to_string(),
             agent_id: agent_id.clone(),
+            parent: parent.map(String::from),
+            model: model.map(String::from),
         });
         if h.event_sender().try_send(event).is_err() {
             tracing::debug!(agent = %name, "SubAgentSpawned event dropped");

crates/loopal-agent-hub/tests/suite.rs

@@ -1,27 +1,27 @@
 // Single test binary — includes all test modules
-#[path = "suite/event_router_test.rs"]
-mod event_router_test;
+#[path = "suite/advanced_scenarios_test.rs"]
+mod advanced_scenarios_test;
+#[path = "suite/collaboration_test.rs"]
+mod collaboration_test;
+#[path = "suite/completion_output_test.rs"]
+mod completion_output_test;
 #[path = "suite/dispatch_test.rs"]
 mod dispatch_test;
-#[path = "suite/relay_test.rs"]
-mod relay_test;
+#[path = "suite/e2e_bootstrap_test.rs"]
+mod e2e_bootstrap_test;
+#[path = "suite/event_router_test.rs"]
+mod event_router_test;
 #[path = "suite/hub_integration_test.rs"]
 mod hub_integration_test;
 #[path = "suite/hub_lifecycle_test.rs"]
 mod hub_lifecycle_test;
-#[path = "suite/spawn_lifecycle_test.rs"]
-mod spawn_lifecycle_test;
-#[path = "suite/e2e_bootstrap_test.rs"]
-mod e2e_bootstrap_test;
 #[path = "suite/multi_agent_test.rs"]
 mod multi_agent_test;
-#[path = "suite/advanced_scenarios_test.rs"]
-mod advanced_scenarios_test;
-#[path = "suite/wait_nonblocking_test.rs"]
-mod wait_nonblocking_test;
-#[path = "suite/completion_output_test.rs"]
-mod completion_output_test;
 #[path = "suite/race_condition_test.rs"]
 mod race_condition_test;
-#[path = "suite/collaboration_test.rs"]
-mod collaboration_test;
+#[path = "suite/relay_test.rs"]
+mod relay_test;
+#[path = "suite/spawn_lifecycle_test.rs"]
+mod spawn_lifecycle_test;
+#[path = "suite/wait_nonblocking_test.rs"]
+mod wait_nonblocking_test;