feat: add Agent Orchestrator for main-sub agent coordination

- Implement event-driven orchestrator based on a3s-event
- Add real-time monitoring of SubAgent lifecycle, state, and progress
- Add dynamic control: pause, resume, cancel, adjust params, inject prompts
- Add 11 event types for comprehensive monitoring
- Add Python SDK bindings (Orchestrator, SubAgentConfig, SubAgentHandle)
- Add 7 unit tests (1480 total tests passing)
- Add comprehensive documentation and examples
- Bump version to v1.0.4

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: hikejs

Cargo.lock

@@ -7,6 +7,30 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ---
 
+## [1.0.4] - 2026-03-05
+
+### New Features
+
+- **Agent Orchestrator** — Main-sub agent coordinator with real-time monitoring and dynamic control
+  - Event-driven architecture based on a3s-event
+  - Real-time monitoring of all SubAgent behaviors, planning, and execution
+  - Dynamic control: pause, resume, cancel, adjust parameters, inject prompts
+  - 11 event types: started, completed, state_changed, progress, tool_execution, control_signal, etc.
+  - Pluggable communication: default memory-based, supports custom NATS provider
+  - Concurrency management with configurable limits
+- **Python SDK Orchestrator bindings** — `Orchestrator`, `SubAgentConfig`, `SubAgentHandle` classes
+  - Full API support for spawning, monitoring, and controlling SubAgents
+  - Event subscription and filtering
+  - State management and result collection
+
+### Improvements
+
+- **Test coverage** — Added 7 orchestrator unit tests (1480 total tests passing)
+- **Documentation** — Added comprehensive orchestrator documentation in English and Chinese
+- **Examples** — Added Python examples for orchestrator usage and integration testing
+
+---
+
 ## [1.0.2] - 2026-03-04
 
 ### New Features

core/CHANGELOG.md

@@ -1,6 +1,6 @@
 [package]
 name = "a3s-code-core"
-version = "1.0.3"
+version = "1.0.4"
 edition = "2021"
 authors = ["A3S Lab Team"]
 license = "MIT"

core/Cargo.toml

@@ -0,0 +1,89 @@
+//! Orchestrator 使用示例
+
+use a3s_code_core::orchestrator::{AgentOrchestrator, SubAgentConfig};
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    println!("=== AgentOrchestrator 示例 ===\n");
+
+    // 1. 创建 orchestrator (默认使用内存事件通讯)
+    let orchestrator = AgentOrchestrator::new_memory();
+    println!("✓ Orchestrator 已创建（使用内存事件通讯）\n");
+
+    // 2. 订阅所有事件
+    let mut events = orchestrator.subscribe_all();
+    println!("✓ 已订阅所有事件\n");
+
+    // 3. 在后台监控事件
+    tokio::spawn(async move {
+        println!("--- 事件监控开始 ---");
+        while let Ok(event) = events.recv().await {
+            println!("[Event] {} - {:?}", event.event_name(), event.subagent_id());
+        }
+    });
+
+    // 4. 启动第一个 SubAgent
+    println!("启动 SubAgent 1...");
+    let handle1 = orchestrator
+        .spawn_subagent(
+            SubAgentConfig::new("general", "Analyze Python files")
+                .with_description("Count Python files")
+                .with_permissive(true)
+                .with_max_steps(5),
+        )
+        .await?;
+    println!("✓ SubAgent 1 已启动: {}\n", handle1.id);
+
+    // 5. 启动第二个 SubAgent
+    println!("启动 SubAgent 2...");
+    let handle2 = orchestrator
+        .spawn_subagent(
+            SubAgentConfig::new("explore", "Find Rust files")
+                .with_description("Count Rust files")
+                .with_permissive(true)
+                .with_max_steps(3),
+        )
+        .await?;
+    println!("✓ SubAgent 2 已启动: {}\n", handle2.id);
+
+    // 6. 查询状态
+    tokio::time::sleep(tokio::time::Duration::from_millis(200)).await;
+    println!("--- 当前状态 ---");
+    let states = orchestrator.get_all_states().await;
+    for (id, state) in &states {
+        println!("  {}: {}", id, state);
+    }
+    println!();
+
+    // 7. 控制 SubAgent
+    println!("暂停 SubAgent 1...");
+    orchestrator.pause_subagent(&handle1.id).await?;
+    println!("✓ SubAgent 1 已暂停\n");
+
+    tokio::time::sleep(tokio::time::Duration::from_millis(100)).await;
+
+    println!("恢复 SubAgent 1...");
+    orchestrator.resume_subagent(&handle1.id).await?;
+    println!("✓ SubAgent 1 已恢复\n");
+
+    // 8. 等待完成
+    println!("等待所有 SubAgent 完成...");
+    let result1 = handle1.wait().await?;
+    let result2 = handle2.wait().await?;
+
+    println!("\n--- 执行结果 ---");
+    println!("SubAgent 1: {}", result1);
+    println!("SubAgent 2: {}", result2);
+
+    // 9. 最终状态
+    println!("\n--- 最终状态 ---");
+    let final_states = orchestrator.get_all_states().await;
+    for (id, state) in &final_states {
+        println!("  {}: {}", id, state);
+    }
+
+    println!("\n✓ 所有 SubAgent 已完成");
+    println!("活跃数量: {}", orchestrator.active_count().await);
+
+    Ok(())
+}

core/examples/orchestrator_basic.rs

@@ -66,6 +66,7 @@ pub mod hooks;
 pub mod llm;
 pub mod mcp;
 pub mod memory;
+pub mod orchestrator;
 pub mod permissions;
 pub mod planning;
 pub(crate) mod prompts;

core/src/lib.rs

@@ -0,0 +1,113 @@
+//! Orchestrator configuration
+
+use serde::{Deserialize, Serialize};
+
+/// Orchestrator 配置
+#[derive(Debug, Clone)]
+pub struct OrchestratorConfig {
+    /// 事件通道缓冲区大小
+    pub event_buffer_size: usize,
+
+    /// 控制信号通道缓冲区大小
+    pub control_buffer_size: usize,
+
+    /// SubAgent 最大并发数
+    pub max_concurrent_subagents: usize,
+
+    /// 事件主题前缀
+    pub subject_prefix: String,
+}
+
+impl Default for OrchestratorConfig {
+    fn default() -> Self {
+        Self {
+            event_buffer_size: 1000,
+            control_buffer_size: 100,
+            max_concurrent_subagents: 50,
+            subject_prefix: "agent".to_string(),
+        }
+    }
+}
+
+/// SubAgent 配置
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SubAgentConfig {
+    /// Agent 类型 (general, explore, plan, etc.)
+    pub agent_type: String,
+
+    /// 任务描述
+    pub description: String,
+
+    /// 执行提示词
+    pub prompt: String,
+
+    /// 是否启用宽松模式（绕过 HITL）
+    #[serde(default)]
+    pub permissive: bool,
+
+    /// 最大执行步数
+    pub max_steps: Option<usize>,
+
+    /// 执行超时（毫秒）
+    pub timeout_ms: Option<u64>,
+
+    /// 父 SubAgent ID（用于嵌套）
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub parent_id: Option<String>,
+
+    /// 自定义元数据
+    #[serde(default)]
+    pub metadata: serde_json::Value,
+}
+
+impl SubAgentConfig {
+    /// 创建新的 SubAgent 配置
+    pub fn new(agent_type: impl Into<String>, prompt: impl Into<String>) -> Self {
+        Self {
+            agent_type: agent_type.into(),
+            description: String::new(),
+            prompt: prompt.into(),
+            permissive: false,
+            max_steps: None,
+            timeout_ms: None,
+            parent_id: None,
+            metadata: serde_json::Value::Null,
+        }
+    }
+
+    /// 设置描述
+    pub fn with_description(mut self, description: impl Into<String>) -> Self {
+        self.description = description.into();
+        self
+    }
+
+    /// 设置宽松模式
+    pub fn with_permissive(mut self, permissive: bool) -> Self {
+        self.permissive = permissive;
+        self
+    }
+
+    /// 设置最大步数
+    pub fn with_max_steps(mut self, max_steps: usize) -> Self {
+        self.max_steps = Some(max_steps);
+        self
+    }
+
+    /// 设置超时
+    pub fn with_timeout_ms(mut self, timeout_ms: u64) -> Self {
+        self.timeout_ms = Some(timeout_ms);
+        self
+    }
+
+    /// 设置父 ID
+    pub fn with_parent_id(mut self, parent_id: impl Into<String>) -> Self {
+        self.parent_id = Some(parent_id.into());
+        self
+    }
+
+    /// 设置元数据
+    pub fn with_metadata(mut self, metadata: serde_json::Value) -> Self {
+        self.metadata = metadata;
+        self
+    }
+}

core/src/orchestrator/config.rs

@@ -0,0 +1,42 @@
+//! 控制信号定义
+
+use serde::{Deserialize, Serialize};
+
+/// 控制信号 - 主智能体发送给子智能体的指令
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ControlSignal {
+    /// 暂停执行
+    Pause,
+
+    /// 恢复执行
+    Resume,
+
+    /// 取消执行
+    Cancel,
+
+    /// 调整参数
+    AdjustParams {
+        #[serde(skip_serializing_if = "Option::is_none")]
+        max_steps: Option<usize>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        timeout_ms: Option<u64>,
+    },
+
+    /// 注入新提示词
+    InjectPrompt {
+        prompt: String,
+    },
+}
+
+impl std::fmt::Display for ControlSignal {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            ControlSignal::Pause => write!(f, "pause"),
+            ControlSignal::Resume => write!(f, "resume"),
+            ControlSignal::Cancel => write!(f, "cancel"),
+            ControlSignal::AdjustParams { .. } => write!(f, "adjust_params"),
+            ControlSignal::InjectPrompt { .. } => write!(f, "inject_prompt"),
+        }
+    }
+}