fix proactive sub agent spawning

OnTheThirdDay · OnTheThirdDay · commit 3e7712bf740c · 2026-03-22T19:17:05.000+11:00
diff --git a/crates/example-eventage-claw/src/agent.rs b/crates/example-eventage-claw/src/agent.rs
@@ -11,13 +11,15 @@ use crate::hooks::{HumanApprovalHook, SecurityGateHook};
 use crate::prompt::build_system_prompt;
 use crate::streaming::StreamingOpenAiProvider;
 use crate::tools::{
-    AddTaskTool, BrowserTool, CancelTaskTool, CompleteTaskTool, DockerRunCommandTool, EditFileTool,
-    GlobTool, GrepTool, GroupRegistry, ListGroupsTool, ListSessionTasksTool, ListTasksTool, LsTool,
-    MessageGroupTool, PauseTaskTool, ReadFileTool, RegisterGroupTool, ScheduleState,
-    ScheduleTaskTool, TaskState, UpdateTaskTool, WebFetchTool, WebSearchTool, WriteFileTool,
-    load_tasks, new_group_registry, new_task_state,
+    AddTaskTool, AgentSpawner, BrowserTool, CancelTaskTool, CompleteTaskTool,
+    DockerRunCommandTool, EditFileTool, GlobTool, GrepTool, GroupRegistry, ListGroupsTool,
+    ListSessionTasksTool, ListTasksTool, LsTool, MessageGroupTool, PauseTaskTool, ReadFileTool,
+    RegisterGroupTool, ScheduleState, ScheduleTaskTool, SpawnGroupTool, TaskState, UpdateTaskTool,
+    WebFetchTool, WebSearchTool, WriteFileTool, load_tasks, new_group_registry, new_task_state,
+};
+use crate::workers::{
+    ChannelOutputWorker, DelegationReplyWorker, GroupBuses, RelayWorker, SchedulerWorker,
 };
-use crate::workers::{ChannelOutputWorker, DelegationReplyWorker, RelayWorker, SchedulerWorker};
 use eventage::{
     agent::{ContextAssembler, DefaultContextAssembler},
     llm::OpenAiProvider,
@@ -26,7 +28,7 @@ use eventage::{
 };
 use std::collections::HashMap;
 use std::sync::{atomic::AtomicBool, Arc};
-use tokio::sync::Mutex;
+use tokio::sync::{Mutex, RwLock};
 use tracing::info;
 use uuid::Uuid;
 
@@ -186,10 +188,13 @@ impl ClawAgentBuilder {
             .map(|g| g.name.clone())
             .collect();
 
-        // Build per-group buses first so we can pass them to workers
-        let mut group_buses: HashMap<String, EventBus> = HashMap::new();
+        // Shared live map: group name → per-group EventBus.
+        // Arc<RwLock<…>> so dynamically spawned groups are immediately routable.
+        let group_buses: GroupBuses = Arc::new(RwLock::new(HashMap::new()));
         for g in &config.groups {
-            group_buses.insert(g.name.clone(), EventBus::new());
+            group_buses
+                .blocking_write()
+                .insert(g.name.clone(), EventBus::new());
         }
 
         // Build shared workers
@@ -203,12 +208,24 @@ impl ClawAgentBuilder {
                 group_buses: group_buses.clone(),
             });
 
+        // Spawner used by SpawnGroupTool — holds everything needed to build a
+        // new GroupAgent at runtime and insert it into the live routing table.
+        let spawner: Arc<dyn AgentSpawner> = Arc::new(ClawGroupSpawner {
+            config: Arc::new(config.clone()),
+            shared_bus: shared_bus.clone(),
+            group_buses: group_buses.clone(),
+            group_registry: group_registry.clone(),
+            schedule_state: schedule_state.clone(),
+            session_id_prefix: self.session_id_prefix.clone(),
+            tui_mode: self.tui_mode,
+        });
+
         // Build each group agent
         let mut groups: HashMap<String, GroupAgent> = HashMap::new();
         let active_group_name = config.groups.first().map(|g| g.name.clone()).unwrap_or_default();
 
         for group_config in &config.groups {
-            let group_bus = group_buses[&group_config.name].clone();
+            let group_bus = group_buses.blocking_read()[&group_config.name].clone();
             let session_id = format!("{}-{}", self.session_id_prefix, group_config.name);
             let task_state = new_task_state();
 
@@ -223,6 +240,7 @@ impl ClawAgentBuilder {
                 self.tui_mode,
                 session_id,
                 task_state,
+                spawner.clone(),
             );
 
             groups.insert(group_config.name.clone(), group_agent);
@@ -239,6 +257,103 @@ impl ClawAgentBuilder {
     }
 }
 
+// ── ClawGroupSpawner ──────────────────────────────────────────────────────────
+
+/// Implements [`AgentSpawner`] for the claw runtime.
+///
+/// Held by `SpawnGroupTool` (main group only). On `spawn()`, it builds a full
+/// `GroupAgent`, inserts the new bus into the shared routing table, and starts
+/// the agent task — all without restarting the process.
+struct ClawGroupSpawner {
+    config: Arc<ClawConfig>,
+    shared_bus: EventBus,
+    group_buses: GroupBuses,
+    group_registry: GroupRegistry,
+    schedule_state: ScheduleState,
+    session_id_prefix: String,
+    tui_mode: bool,
+}
+
+#[async_trait::async_trait]
+impl AgentSpawner for ClawGroupSpawner {
+    async fn spawn(&self, name: &str, system_prompt: Option<&str>) -> Result<(), String> {
+        // Reject duplicates.
+        if self.group_buses.read().await.contains_key(name) {
+            return Err(format!("group '{name}' already exists"));
+        }
+
+        let group_bus = EventBus::new();
+        let session_id = format!("{}-{}", self.session_id_prefix, name);
+        let task_state = new_task_state();
+
+        let group_config = GroupConfig {
+            name: name.to_string(),
+            is_main: false,
+            system_prompt_suffix: system_prompt.map(|s| s.to_string()),
+            human_approval_tools: vec![],
+            require_approve_all: false,
+            work_dir: None,
+            allowed_senders: vec![],
+        };
+
+        // Snapshot current group names for the new agent's MessageGroupTool hint.
+        let known_groups: Vec<String> = self.group_registry.lock().await.clone();
+
+        // No recursive spawning from spawned sub-agents — pass a no-op spawner.
+        let no_spawn: Arc<dyn AgentSpawner> = Arc::new(NoopSpawner);
+
+        let group_agent = build_group_agent(
+            &group_config,
+            &self.config,
+            group_bus.clone(),
+            self.shared_bus.clone(),
+            self.schedule_state.clone(),
+            self.group_registry.clone(),
+            &known_groups,
+            self.tui_mode,
+            session_id,
+            task_state,
+            no_spawn,
+        );
+
+        // Register in routing table before spawning so RelayWorker can route
+        // the very first message the main agent sends after spawn returns.
+        self.group_buses.write().await.insert(name.to_string(), group_bus);
+        self.group_registry.lock().await.push(name.to_string());
+
+        let group_name = name.to_string();
+        let agent = group_agent.agent;
+        let ws = group_agent.worker_set;
+        let bus = group_agent.bus;
+
+        tokio::spawn(async move {
+            let worker_bus = bus.clone();
+            let worker_name = group_name.clone();
+            tokio::spawn(async move {
+                if let Err(e) = ws.run_on(worker_bus).await {
+                    tracing::warn!(group = %worker_name, "spawned group worker error: {e}");
+                }
+            });
+            if let Err(e) = agent.run().await {
+                tracing::warn!(group = %group_name, "spawned group agent exited: {e}");
+            }
+        });
+
+        info!(group = %name, "ClawGroupSpawner: sub-agent spawned");
+        Ok(())
+    }
+}
+
+/// Placeholder spawner for sub-agents that should not spawn further agents.
+struct NoopSpawner;
+
+#[async_trait::async_trait]
+impl AgentSpawner for NoopSpawner {
+    async fn spawn(&self, name: &str, _system_prompt: Option<&str>) -> Result<(), String> {
+        Err(format!("sub-agent cannot spawn further agents (requested: '{name}')"))
+    }
+}
+
 // ── build_group_agent ─────────────────────────────────────────────────────────
 
 #[allow(clippy::too_many_arguments)]
@@ -253,6 +368,7 @@ fn build_group_agent(
     tui_mode: bool,
     session_id: String,
     task_state: TaskState,
+    spawner: Arc<dyn AgentSpawner>,
 ) -> GroupAgent {
     let work_dir = config.group_work_dir(&group_config.name);
     let _ = std::fs::create_dir_all(&work_dir);
@@ -398,7 +514,8 @@ fn build_group_agent(
             })
             .tool(ListGroupsTool {
                 registry: group_registry.clone(),
-            });
+            })
+            .tool(SpawnGroupTool { spawner });
     }
 
     // ── Hook ──────────────────────────────────────────────────────────────────
diff --git a/crates/example-eventage-claw/src/kinds.rs b/crates/example-eventage-claw/src/kinds.rs
@@ -25,6 +25,11 @@ pub const CLAW_SCHEDULE_UPDATE: &str = "claw.schedule.update";
 /// `RelayWorker` subscribes and routes the message to the target group's bus.
 pub const CLAW_GROUP_MESSAGE: &str = "claw.group.message";
 
+/// Published by `DelegationReplyWorker` when a sub-agent completes a relay request.
+/// `MessageGroupTool` (await_reply=true) waits for this on the shared bus.
+/// Kept separate from `CLAW_GROUP_MESSAGE` so `RelayWorker` never re-routes replies.
+pub const CLAW_GROUP_REPLY: &str = "claw.group.reply";
+
 /// Published by the TUI when the user switches the active group.
 pub const CLAW_GROUP_SWITCH: &str = "claw.group.switch";
 
diff --git a/crates/example-eventage-claw/src/tools/group.rs b/crates/example-eventage-claw/src/tools/group.rs
@@ -8,6 +8,15 @@ use tokio::sync::Mutex;
 
 use crate::kinds::CLAW_GROUP_REGISTER;
 
+// ── AgentSpawner trait ────────────────────────────────────────────────────────
+
+/// Abstracts over the runtime agent-spawning logic so `SpawnGroupTool` does
+/// not need to import from `agent.rs` (which would create a circular dep).
+#[async_trait]
+pub trait AgentSpawner: Send + Sync {
+    async fn spawn(&self, name: &str, system_prompt: Option<&str>) -> Result<(), String>;
+}
+
 /// Shared runtime group registry (name → bool for "active").
 pub type GroupRegistry = Arc<Mutex<Vec<String>>>;
 
@@ -105,3 +114,58 @@ impl Tool for ListGroupsTool {
         }))
     }
 }
+
+// ── SpawnGroupTool ────────────────────────────────────────────────────────────
+
+/// Dynamically spawns a new sub-agent group at runtime.
+///
+/// The new agent gets its own isolated EventBus, the full tool set, and begins
+/// listening immediately — no restart required.  `message_group` can reach it
+/// the moment this tool returns.  Only the main group has this tool.
+pub struct SpawnGroupTool {
+    pub spawner: Arc<dyn AgentSpawner>,
+}
+
+#[async_trait]
+impl Tool for SpawnGroupTool {
+    fn definition(&self) -> ToolDefinition {
+        ToolDefinition::function(
+            "spawn_group",
+            "Spawn a new sub-agent group at runtime with an isolated context and event bus. \
+             The agent starts immediately and can be reached via message_group. \
+             Only usable by the main group.",
+            json!({
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "description": "Unique group name for the new agent (e.g. 'researcher', 'coder')."
+                    },
+                    "system_prompt": {
+                        "type": "string",
+                        "description": "System prompt that defines this agent's persona and task focus."
+                    }
+                },
+                "required": ["name", "system_prompt"]
+            }),
+        )
+    }
+
+    async fn execute(&self, args: Value) -> Result<Value, AgentError> {
+        let name = args["name"]
+            .as_str()
+            .ok_or_else(|| AgentError::Tool("missing 'name'".into()))?;
+        let prompt = args["system_prompt"].as_str();
+
+        self.spawner
+            .spawn(name, prompt)
+            .await
+            .map_err(AgentError::Tool)?;
+
+        Ok(json!({
+            "spawned": true,
+            "name": name,
+            "message": format!("Agent '{name}' is running. Use message_group to communicate with it."),
+        }))
+    }
+}
diff --git a/crates/example-eventage-claw/src/tools/mod.rs b/crates/example-eventage-claw/src/tools/mod.rs
@@ -13,7 +13,10 @@ pub mod web;
 pub use browser::BrowserTool;
 pub use docker::DockerRunCommandTool;
 pub use fs::{EditFileTool, GlobTool, GrepTool, LsTool, ReadFileTool, WriteFileTool};
-pub use group::{new_group_registry, GroupRegistry, ListGroupsTool, RegisterGroupTool};
+pub use group::{
+    new_group_registry, AgentSpawner, GroupRegistry, ListGroupsTool, RegisterGroupTool,
+    SpawnGroupTool,
+};
 pub use relay::MessageGroupTool;
 pub use schedule::{
     load_tasks, CancelTaskTool, ListTasksTool, PauseTaskTool, ScheduleState, ScheduleTaskTool,
diff --git a/crates/example-eventage-claw/src/tools/relay.rs b/crates/example-eventage-claw/src/tools/relay.rs
@@ -1,17 +1,18 @@
 //! Inter-group IPC tool — the key EventBus-as-IPC demonstration.
 //!
 //! `MessageGroupTool` lets an agent send a message to another named group.
-//! It publishes a `CLAW_GROUP_MESSAGE` event on the shared bus; the
-//! `RelayWorker` subscribes and routes it to the target group's per-group bus
-//! as a `user.message` event.
+//! It publishes a `CLAW_GROUP_MESSAGE` event on the shared bus; `RelayWorker`
+//! routes it to the target group's per-group bus as an `agent.message` event.
+//! When `await_reply=true`, the tool waits on the shared bus for a matching
+//! `CLAW_GROUP_REPLY` published by the target group's `DelegationReplyWorker`.
 
 use async_trait::async_trait;
 use eventage::{AgentError, Event, EventBus, Tool, ToolDefinition};
 use serde_json::{json, Value};
 use std::time::Duration;
 use uuid::Uuid;
 
-use crate::kinds::CLAW_GROUP_MESSAGE;
+use crate::kinds::{CLAW_GROUP_MESSAGE, CLAW_GROUP_REPLY};
 
 pub struct MessageGroupTool {
     /// Shared bus — events published here are visible to all workers.
@@ -90,7 +91,7 @@ impl Tool for MessageGroupTool {
 
             let result = tokio::time::timeout(Duration::from_secs(30), async move {
                 bus.wait_for(|e: &Event| {
-                    e.kind == CLAW_GROUP_MESSAGE
+                    e.kind == CLAW_GROUP_REPLY
                         && e.payload["source_group"].as_str() == Some(&target_owned)
                         && e.payload["in_reply_to"].as_str() == Some(&msg_id_clone)
                 })
diff --git a/crates/example-eventage-claw/src/workers.rs b/crates/example-eventage-claw/src/workers.rs
