feat: add Orchestrator bindings to Node.js SDK

- Add Orchestrator, SubAgentConfig, SubAgentHandle classes
- Add TypeScript definitions with JSDoc examples
- Add orchestrator.mjs example
- Update version to 1.0.4

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

Author: hikejs

sdk/node/Cargo.toml

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

sdk/node/examples/orchestrator.mjs

@@ -0,0 +1,101 @@
+/**
+ * Agent Orchestrator Example for Node.js
+ *
+ * Demonstrates main-sub agent coordination with real-time monitoring
+ * and dynamic control.
+ */
+
+const { Orchestrator } = require('@a3s-lab/code');
+
+async function main() {
+  console.log('=== Agent Orchestrator Node.js Example ===\n');
+
+  // Create orchestrator
+  console.log('1. Creating orchestrator...');
+  const orch = Orchestrator.create();
+  console.log(`   Active SubAgents: ${orch.activeCount()}\n`);
+
+  // Spawn SubAgent 1
+  console.log('2. Spawning SubAgent 1...');
+  const config1 = {
+    agentType: 'general',
+    description: 'Code analysis task',
+    prompt: 'Use glob to find all JavaScript files',
+    permissive: true,
+    maxSteps: 10
+  };
+  const handle1 = orch.spawnSubagent(config1);
+  console.log(`   SubAgent 1 ID: ${handle1.id}\n`);
+
+  // Spawn SubAgent 2
+  console.log('3. Spawning SubAgent 2...');
+  const config2 = {
+    agentType: 'explore',
+    description: 'Documentation check',
+    prompt: 'Check if README.md exists',
+    permissive: true,
+    maxSteps: 5
+  };
+  const handle2 = orch.spawnSubagent(config2);
+  console.log(`   SubAgent 2 ID: ${handle2.id}\n`);
+
+  // Monitor execution
+  console.log('4. Monitoring execution...');
+  for (let i = 0; i < 15; i++) {
+    await sleep(200);
+    const active = orch.activeCount();
+    const state1 = handle1.state();
+    const state2 = handle2.state();
+
+    console.log(`   [${(i * 0.2).toFixed(1)}s] Active: ${active}, State1: ${state1.substring(0, 20)}, State2: ${state2.substring(0, 20)}`);
+
+    // Test control operations
+    if (i === 3) {
+      console.log('\n   -> Pausing SubAgent 1...');
+      handle1.pause();
+    }
+
+    if (i === 6) {
+      console.log('   -> Resuming SubAgent 1...\n');
+      handle1.resume();
+    }
+
+    // Check if all done
+    if (active === 0) {
+      console.log(`\n   All SubAgents completed at ${(i * 0.2).toFixed(1)}s`);
+      break;
+    }
+  }
+
+  // Collect results
+  console.log('\n5. Collecting results...');
+  try {
+    const result1 = handle1.wait();
+    console.log(`   SubAgent 1: ${result1.substring(0, 80)}...`);
+  } catch (e) {
+    console.log(`   SubAgent 1 error: ${e.message}`);
+  }
+
+  try {
+    const result2 = handle2.wait();
+    console.log(`   SubAgent 2: ${result2.substring(0, 80)}...`);
+  } catch (e) {
+    console.log(`   SubAgent 2 error: ${e.message}`);
+  }
+
+  // Final status
+  console.log('\n6. Final status:');
+  console.log(`   Active SubAgents: ${orch.activeCount()}`);
+  console.log(`   SubAgent 1 state: ${handle1.state()}`);
+  console.log(`   SubAgent 2 state: ${handle2.state()}`);
+
+  console.log('\n=== Example completed ===');
+  console.log('\nNote: This example uses placeholder execution.');
+  console.log('For real LLM execution, integrate AgentLoop in SubAgentWrapper.');
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+main().catch(console.error);

sdk/node/index.d.ts

@@ -569,6 +569,87 @@ export declare class TeamRunner {
   runUntilDone(goal: string): Promise<TeamRunResult>;
 }
 
+// ============================================================================
+// Agent Orchestrator - Main-Sub Agent Coordination
+// ============================================================================
+
+/**
+ * SubAgent configuration for orchestrator.
+ */
+export interface SubAgentConfig {
+  /** Agent type (general, explore, plan, etc.) */
+  agentType: string;
+  /** Task description */
+  description: string;
+  /** Execution prompt */
+  prompt: string;
+  /** Enable permissive mode (bypass HITL) */
+  permissive: boolean;
+  /** Maximum execution steps */
+  maxSteps?: number;
+  /** Execution timeout (milliseconds) */
+  timeoutMs?: number;
+  /** Parent SubAgent ID (for nesting) */
+  parentId?: string;
+}
+
+/**
+ * SubAgent handle for control and monitoring.
+ */
+export declare class SubAgentHandle {
+  /** Get SubAgent ID */
+  readonly id: string;
+  /** Get current state (non-blocking) */
+  state(): string;
+  /** Pause execution */
+  pause(): void;
+  /** Resume execution */
+  resume(): void;
+  /** Cancel execution */
+  cancel(): void;
+  /** Wait for completion and get result */
+  wait(): string;
+}
+
+/**
+ * Agent Orchestrator for main-sub agent coordination.
+ *
+ * Provides real-time monitoring and dynamic control of multiple SubAgents
+ * through an event-driven architecture.
+ *
+ * @example
+ * ```typescript
+ * const orch = Orchestrator.create();
+ *
+ * const config: SubAgentConfig = {
+ *   agentType: 'general',
+ *   description: 'Find Python files',
+ *   prompt: 'Use glob to find Python files',
+ *   permissive: true,
+ *   maxSteps: 10
+ * };
+ *
+ * const handle = orch.spawnSubagent(config);
+ * console.log('SubAgent ID:', handle.id);
+ *
+ * // Control operations
+ * handle.pause();
+ * handle.resume();
+ *
+ * // Wait for result
+ * const result = handle.wait();
+ * console.log('Result:', result);
+ * ```
+ */
+export declare class Orchestrator {
+  /** Create a new orchestrator with memory-based event communication */
+  static create(): Orchestrator;
+  /** Spawn a new SubAgent */
+  spawnSubagent(config: SubAgentConfig): SubAgentHandle;
+  /** Get active SubAgent count */
+  activeCount(): number;
+}
+
 // ============================================================================
 // Standalone functions
 // ============================================================================

sdk/node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a3s-lab/code",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "A3S Code - Native AI coding agent library for Node.js",
   "main": "index.js",
   "types": "index.d.ts",

sdk/node/src/lib.rs

@@ -23,6 +23,11 @@ use a3s_code_core::agent_teams::{
     TeamRole as RustTeamRole, TeamRunner as RustTeamRunner, TeamTask as RustTeamTask,
     TeamTaskBoard as RustTeamTaskBoard,
 };
+use a3s_code_core::orchestrator::{
+    AgentOrchestrator as RustOrchestrator, ControlSignal as RustControlSignal,
+    OrchestratorEvent as RustOrchestratorEvent, SubAgentConfig as RustSubAgentConfig,
+    SubAgentHandle as RustSubAgentHandle, SubAgentState as RustSubAgentState,
+};
 use a3s_code_core::config::{
     SearchConfig as RustSearchConfig, SearchEngineConfig as RustSearchEngineConfig,
     SearchHealthConfig as RustSearchHealthConfig,
@@ -2245,3 +2250,150 @@ impl From<SearchConfig> for RustSearchConfig {
         }
     }
 }
+
+// ============================================================================
+// Agent Orchestrator - Main-Sub Agent Coordination
+// ============================================================================
+
+/// SubAgent configuration for orchestrator.
+#[napi(object)]
+#[derive(Clone)]
+pub struct SubAgentConfig {
+    /// Agent type (general, explore, plan, etc.)
+    pub agent_type: String,
+    /// Task description
+    pub description: String,
+    /// Execution prompt
+    pub prompt: String,
+    /// Enable permissive mode (bypass HITL)
+    pub permissive: bool,
+    /// Maximum execution steps
+    pub max_steps: Option<u32>,
+    /// Execution timeout (milliseconds)
+    pub timeout_ms: Option<u32>,
+    /// Parent SubAgent ID (for nesting)
+    pub parent_id: Option<String>,
+}
+
+impl From<SubAgentConfig> for RustSubAgentConfig {
+    fn from(c: SubAgentConfig) -> Self {
+        let mut config = RustSubAgentConfig::new(c.agent_type, c.prompt);
+        if !c.description.is_empty() {
+            config = config.with_description(c.description);
+        }
+        config = config.with_permissive(c.permissive);
+        if let Some(steps) = c.max_steps {
+            config = config.with_max_steps(steps as usize);
+        }
+        if let Some(timeout) = c.timeout_ms {
+            config = config.with_timeout_ms(timeout as u64);
+        }
+        if let Some(parent) = c.parent_id {
+            config = config.with_parent_id(parent);
+        }
+        config
+    }
+}
+
+/// SubAgent handle for control and monitoring.
+#[napi]
+pub struct SubAgentHandle {
+    inner: Arc<tokio::sync::Mutex<RustSubAgentHandle>>,
+}
+
+#[napi]
+impl SubAgentHandle {
+    /// Get SubAgent ID
+    #[napi(getter)]
+    pub fn id(&self) -> napi::Result<String> {
+        let handle = self.inner.clone();
+        Ok(get_runtime().block_on(async move {
+            let h = handle.lock().await;
+            h.id.clone()
+        }))
+    }
+
+    /// Get current state (non-blocking)
+    #[napi]
+    pub fn state(&self) -> napi::Result<String> {
+        let handle = self.inner.clone();
+        Ok(get_runtime().block_on(async move {
+            let h = handle.lock().await;
+            let state = h.state_async().await;
+            format!("{:?}", state)
+        }))
+    }
+
+    /// Pause execution
+    #[napi]
+    pub fn pause(&self) -> napi::Result<()> {
+        let handle = self.inner.clone();
+        get_runtime()
+            .block_on(async move { handle.lock().await.pause().await })
+            .map_err(|e| napi::Error::from_reason(format!("Pause failed: {}", e)))
+    }
+
+    /// Resume execution
+    #[napi]
+    pub fn resume(&self) -> napi::Result<()> {
+        let handle = self.inner.clone();
+        get_runtime()
+            .block_on(async move { handle.lock().await.resume().await })
+            .map_err(|e| napi::Error::from_reason(format!("Resume failed: {}", e)))
+    }
+
+    /// Cancel execution
+    #[napi]
+    pub fn cancel(&self) -> napi::Result<()> {
+        let handle = self.inner.clone();
+        get_runtime()
+            .block_on(async move { handle.lock().await.cancel().await })
+            .map_err(|e| napi::Error::from_reason(format!("Cancel failed: {}", e)))
+    }
+
+    /// Wait for completion and get result
+    #[napi]
+    pub fn wait(&self) -> napi::Result<String> {
+        let handle = self.inner.clone();
+        get_runtime()
+            .block_on(async move { handle.lock().await.wait().await })
+            .map_err(|e| napi::Error::from_reason(format!("Wait failed: {}", e)))
+    }
+}
+
+/// Agent Orchestrator for main-sub agent coordination.
+#[napi]
+pub struct Orchestrator {
+    inner: Arc<tokio::sync::Mutex<RustOrchestrator>>,
+}
+
+#[napi]
+impl Orchestrator {
+    /// Create a new orchestrator with memory-based event communication
+    #[napi(factory)]
+    pub fn create() -> Self {
+        Self {
+            inner: Arc::new(tokio::sync::Mutex::new(RustOrchestrator::new_memory())),
+        }
+    }
+
+    /// Spawn a new SubAgent
+    #[napi]
+    pub fn spawn_subagent(&self, config: SubAgentConfig) -> napi::Result<SubAgentHandle> {
+        let orch = self.inner.clone();
+        let cfg: RustSubAgentConfig = config.into();
+        let handle = get_runtime()
+            .block_on(async move { orch.lock().await.spawn_subagent(cfg).await })
+            .map_err(|e| napi::Error::from_reason(format!("Spawn failed: {}", e)))?;
+        Ok(SubAgentHandle {
+            inner: Arc::new(tokio::sync::Mutex::new(handle)),
+        })
+    }
+
+    /// Get active SubAgent count
+    #[napi]
+    pub fn active_count(&self) -> napi::Result<u32> {
+        let orch = self.inner.clone();
+        Ok(get_runtime().block_on(async move { orch.lock().await.active_count().await }) as u32)
+    }
+}