feat: align Orchestrator monitoring APIs to Python and Node.js SDKs

Python SDK:
- Add PySubAgentInfo class with metadata and current_activity
- Add PySubAgentActivity class (idle, calling_tool, requesting_llm, waiting_for_control)
- Add orchestrator.list_subagents() - get all SubAgent info
- Add orchestrator.get_subagent_info(id) - get specific SubAgent details
- Add orchestrator.get_active_activities() - get all active activities
- Add orchestrator.get_all_states() - get all SubAgent states
- Add orchestrator.pause_subagent(id) / resume_subagent(id) / cancel_subagent(id)
- Add orchestrator.wait_all() - wait for all SubAgents to complete

Node.js SDK:
- Add SubAgentInfo interface with metadata and currentActivity
- Add SubAgentActivity interface (activityType, data)
- Add SubAgentActivityEntry and SubAgentStateEntry for tuple returns
- Add orchestrator.listSubagents() - get all SubAgent info
- Add orchestrator.getSubagentInfo(id) - get specific SubAgent details
- Add orchestrator.getActiveActivities() - get all active activities
- Add orchestrator.getAllStates() - get all SubAgent states
- Add orchestrator.pauseSubagent(id) / resumeSubagent(id) / cancelSubagent(id)
- Add orchestrator.waitAll() - wait for all SubAgents to complete
- Update TypeScript definitions with complete API documentation and examples

All Rust core APIs now fully aligned across Python and Node.js SDKs.

Author: hikejs

sdk/node/index.d.ts

@@ -593,6 +593,54 @@ export interface SubAgentConfig {
   parentId?: string;
 }
 
+/**
+ * SubAgent activity type.
+ */
+export interface SubAgentActivity {
+  /** Activity type: idle, calling_tool, requesting_llm, waiting_for_control */
+  activityType: string;
+  /** Activity data (JSON string) */
+  data?: string;
+}
+
+/**
+ * SubAgent information with metadata and current activity.
+ */
+export interface SubAgentInfo {
+  /** SubAgent ID */
+  id: string;
+  /** Agent type */
+  agentType: string;
+  /** Task description */
+  description: string;
+  /** Current state */
+  state: string;
+  /** Parent SubAgent ID */
+  parentId?: string;
+  /** Creation timestamp (milliseconds) */
+  createdAt: number;
+  /** Last update timestamp (milliseconds) */
+  updatedAt: number;
+  /** Current activity */
+  currentActivity?: SubAgentActivity;
+}
+
+/**
+ * SubAgent activity entry (id + activity).
+ */
+export interface SubAgentActivityEntry {
+  id: string;
+  activity: SubAgentActivity;
+}
+
+/**
+ * SubAgent state entry (id + state).
+ */
+export interface SubAgentStateEntry {
+  id: string;
+  state: string;
+}
+
 /**
  * SubAgent handle for control and monitoring.
  */
@@ -632,13 +680,21 @@ export declare class SubAgentHandle {
  * const handle = orch.spawnSubagent(config);
  * console.log('SubAgent ID:', handle.id);
  *
+ * // Real-time monitoring
+ * const subagents = orch.listSubagents();
+ * for (const info of subagents) {
+ *   console.log(`${info.id}: ${info.state}`);
+ *   if (info.currentActivity) {
+ *     console.log(`  Activity: ${info.currentActivity.activityType}`);
+ *   }
+ * }
+ *
  * // Control operations
- * handle.pause();
- * handle.resume();
+ * orch.pauseSubagent(handle.id);
+ * orch.resumeSubagent(handle.id);
  *
- * // Wait for result
- * const result = handle.wait();
- * console.log('Result:', result);
+ * // Wait for all to complete
+ * orch.waitAll();
  * ```
  */
 export declare class Orchestrator {
@@ -648,6 +704,22 @@ export declare class Orchestrator {
   spawnSubagent(config: SubAgentConfig): SubAgentHandle;
   /** Get active SubAgent count */
   activeCount(): number;
+  /** Get all SubAgent information list */
+  listSubagents(): SubAgentInfo[];
+  /** Get specific SubAgent information */
+  getSubagentInfo(id: string): SubAgentInfo | null;
+  /** Get all active SubAgent activities */
+  getActiveActivities(): SubAgentActivityEntry[];
+  /** Get all SubAgent states */
+  getAllStates(): SubAgentStateEntry[];
+  /** Pause a SubAgent */
+  pauseSubagent(id: string): void;
+  /** Resume a SubAgent */
+  resumeSubagent(id: string): void;
+  /** Cancel a SubAgent */
+  cancelSubagent(id: string): void;
+  /** Wait for all SubAgents to complete */
+  waitAll(): void;
 }
 
 // ============================================================================

sdk/node/src/lib.rs

@@ -25,8 +25,9 @@ use a3s_code_core::agent_teams::{
 };
 use a3s_code_core::orchestrator::{
     AgentOrchestrator as RustOrchestrator, ControlSignal as RustControlSignal,
-    OrchestratorEvent as RustOrchestratorEvent, SubAgentConfig as RustSubAgentConfig,
-    SubAgentHandle as RustSubAgentHandle, SubAgentState as RustSubAgentState,
+    OrchestratorEvent as RustOrchestratorEvent, SubAgentActivity as RustSubAgentActivity,
+    SubAgentConfig as RustSubAgentConfig, SubAgentHandle as RustSubAgentHandle,
+    SubAgentInfo as RustSubAgentInfo, SubAgentState as RustSubAgentState,
 };
 use a3s_code_core::config::{
     SearchConfig as RustSearchConfig, SearchEngineConfig as RustSearchEngineConfig,
@@ -2361,6 +2362,96 @@ impl SubAgentHandle {
     }
 }
 
+/// SubAgent activity type
+#[napi(object)]
+pub struct SubAgentActivity {
+    /// Activity type: idle, calling_tool, requesting_llm, waiting_for_control
+    pub activity_type: String,
+    /// Activity data (JSON string)
+    pub data: Option<String>,
+}
+
+impl From<RustSubAgentActivity> for SubAgentActivity {
+    fn from(activity: RustSubAgentActivity) -> Self {
+        match activity {
+            RustSubAgentActivity::Idle => Self {
+                activity_type: "idle".to_string(),
+                data: None,
+            },
+            RustSubAgentActivity::CallingTool { tool_name, args } => Self {
+                activity_type: "calling_tool".to_string(),
+                data: Some(
+                    serde_json::json!({
+                        "tool_name": tool_name,
+                        "args": args
+                    })
+                    .to_string(),
+                ),
+            },
+            RustSubAgentActivity::RequestingLlm { message_count } => Self {
+                activity_type: "requesting_llm".to_string(),
+                data: Some(
+                    serde_json::json!({
+                        "message_count": message_count
+                    })
+                    .to_string(),
+                ),
+            },
+            RustSubAgentActivity::WaitingForControl { reason } => Self {
+                activity_type: "waiting_for_control".to_string(),
+                data: Some(
+                    serde_json::json!({
+                        "reason": reason
+                    })
+                    .to_string(),
+                ),
+            },
+        }
+    }
+}
+
+/// SubAgent information with metadata and current activity
+#[napi(object)]
+pub struct SubAgentInfo {
+    pub id: String,
+    pub agent_type: String,
+    pub description: String,
+    pub state: String,
+    pub parent_id: Option<String>,
+    pub created_at: i64,
+    pub updated_at: i64,
+    pub current_activity: Option<SubAgentActivity>,
+}
+
+impl From<RustSubAgentInfo> for SubAgentInfo {
+    fn from(info: RustSubAgentInfo) -> Self {
+        Self {
+            id: info.id,
+            agent_type: info.agent_type,
+            description: info.description,
+            state: info.state,
+            parent_id: info.parent_id,
+            created_at: info.created_at as i64,
+            updated_at: info.updated_at as i64,
+            current_activity: info.current_activity.map(|a| a.into()),
+        }
+    }
+}
+
+/// SubAgent activity entry (id + activity)
+#[napi(object)]
+pub struct SubAgentActivityEntry {
+    pub id: String,
+    pub activity: SubAgentActivity,
+}
+
+/// SubAgent state entry (id + state)
+#[napi(object)]
+pub struct SubAgentStateEntry {
+    pub id: String,
+    pub state: String,
+}
+
 /// Agent Orchestrator for main-sub agent coordination.
 #[napi]
 pub struct Orchestrator {
@@ -2396,4 +2487,87 @@ impl Orchestrator {
         let orch = self.inner.clone();
         Ok(get_runtime().block_on(async move { orch.lock().await.active_count().await }) as u32)
     }
+
+    /// Get all SubAgent information list
+    #[napi]
+    pub fn list_subagents(&self) -> napi::Result<Vec<SubAgentInfo>> {
+        let orch = self.inner.clone();
+        let infos = get_runtime().block_on(async move { orch.lock().await.list_subagents().await });
+        Ok(infos.into_iter().map(|i| i.into()).collect())
+    }
+
+    /// Get specific SubAgent information
+    #[napi]
+    pub fn get_subagent_info(&self, id: String) -> napi::Result<Option<SubAgentInfo>> {
+        let orch = self.inner.clone();
+        let info =
+            get_runtime().block_on(async move { orch.lock().await.get_subagent_info(&id).await });
+        Ok(info.map(|i| i.into()))
+    }
+
+    /// Get all active SubAgent activities
+    #[napi]
+    pub fn get_active_activities(&self) -> napi::Result<Vec<SubAgentActivityEntry>> {
+        let orch = self.inner.clone();
+        let activities =
+            get_runtime().block_on(async move { orch.lock().await.get_active_activities().await });
+        Ok(activities
+            .into_iter()
+            .map(|(id, activity)| SubAgentActivityEntry {
+                id,
+                activity: activity.into(),
+            })
+            .collect())
+    }
+
+    /// Get all SubAgent states
+    #[napi]
+    pub fn get_all_states(&self) -> napi::Result<Vec<SubAgentStateEntry>> {
+        let orch = self.inner.clone();
+        let states =
+            get_runtime().block_on(async move { orch.lock().await.get_all_states().await });
+        Ok(states
+            .into_iter()
+            .map(|(id, state)| SubAgentStateEntry {
+                id,
+                state: format!("{:?}", state),
+            })
+            .collect())
+    }
+
+    /// Pause a SubAgent
+    #[napi]
+    pub fn pause_subagent(&self, id: String) -> napi::Result<()> {
+        let orch = self.inner.clone();
+        get_runtime()
+            .block_on(async move { orch.lock().await.pause_subagent(&id).await })
+            .map_err(|e| napi::Error::from_reason(format!("Pause failed: {}", e)))
+    }
+
+    /// Resume a SubAgent
+    #[napi]
+    pub fn resume_subagent(&self, id: String) -> napi::Result<()> {
+        let orch = self.inner.clone();
+        get_runtime()
+            .block_on(async move { orch.lock().await.resume_subagent(&id).await })
+            .map_err(|e| napi::Error::from_reason(format!("Resume failed: {}", e)))
+    }
+
+    /// Cancel a SubAgent
+    #[napi]
+    pub fn cancel_subagent(&self, id: String) -> napi::Result<()> {
+        let orch = self.inner.clone();
+        get_runtime()
+            .block_on(async move { orch.lock().await.cancel_subagent(&id).await })
+            .map_err(|e| napi::Error::from_reason(format!("Cancel failed: {}", e)))
+    }
+
+    /// Wait for all SubAgents to complete
+    #[napi]
+    pub fn wait_all(&self) -> napi::Result<()> {
+        let orch = self.inner.clone();
+        get_runtime()
+            .block_on(async move { orch.lock().await.wait_all().await })
+            .map_err(|e| napi::Error::from_reason(format!("Wait failed: {}", e)))
+    }
 }