feat(agent): wire robot CLI subcommand to expose Self-Documentation API Refs #1011

- Add Robot variant to Command enum with subcommands:
  capabilities, schemas, examples
- Add RobotFormat enum (json, table, minimal) for --format flag
- Add handle_robot_command() and format_robot_output() helpers
- Wire Robot command in main() before catch-all server/offline dispatch
- Add unreachable! arms in run_offline_command and run_server_command
  to satisfy exhaustive match (Robot is handled in main)
- Add 4 integration tests: capabilities JSON, schemas JSON,
  examples text, all formats honoured
- Fix pre-existing compilation errors in terraphim_orchestrator
  (config clone + concurrency_permit field)

Author: AlexMikhalev

crates/terraphim_agent/src/main.rs

@@ -545,6 +545,14 @@ pub enum OutputFormat {
     JsonCompact,
 }
 
+#[derive(clap::ValueEnum, Debug, Clone, Default)]
+enum RobotFormat {
+    #[default]
+    Json,
+    Table,
+    Minimal,
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 enum CommandOutputMode {
     Human,
@@ -889,6 +897,12 @@ enum Command {
         #[arg(long)]
         config: Option<String>,
     },
+
+    /// Robot mode self-documentation commands
+    Robot {
+        #[command(subcommand)]
+        sub: RobotSub,
+    },
 }
 
 #[derive(Subcommand, Debug)]
@@ -1214,6 +1228,32 @@ enum SessionsSub {
     Stats,
 }
 
+#[derive(Subcommand, Debug)]
+enum RobotSub {
+    /// Show robot capabilities
+    Capabilities {
+        /// Output format
+        #[arg(long, value_enum, default_value_t = RobotFormat::Json)]
+        format: RobotFormat,
+    },
+    /// Show command schemas
+    Schemas {
+        /// Command name to get schema for (all commands if omitted)
+        command: Option<String>,
+        /// Output format
+        #[arg(long, value_enum, default_value_t = RobotFormat::Json)]
+        format: RobotFormat,
+    },
+    /// Show command examples
+    Examples {
+        /// Command name to get examples for (all commands if omitted)
+        command: Option<String>,
+        /// Output format
+        #[arg(long, value_enum, default_value_t = RobotFormat::Table)]
+        format: RobotFormat,
+    },
+}
+
 fn emit_robot_error_and_exit(
     err: &anyhow::Error,
     code: robot::exit_codes::ExitCode,
@@ -1540,6 +1580,67 @@ fn apply_forgiving_parsing(args: &[String]) -> Vec<String> {
     }
 }
 
+/// Format a value using robot mode output formatting.
+fn format_robot_output<T: Serialize>(value: &T, format: RobotFormat) -> Result<String> {
+    let robot_format = match format {
+        RobotFormat::Json => robot::output::OutputFormat::Json,
+        RobotFormat::Table => robot::output::OutputFormat::Table,
+        RobotFormat::Minimal => robot::output::OutputFormat::Minimal,
+    };
+    let config = robot::output::RobotConfig::new().with_format(robot_format);
+    let formatter = robot::output::RobotFormatter::new(config);
+    formatter
+        .format(value)
+        .map_err(|e| anyhow::anyhow!("Failed to format output: {}", e))
+}
+
+/// Handle robot mode self-documentation commands.
+fn handle_robot_command(sub: RobotSub) -> Result<()> {
+    let docs = robot::SelfDocumentation::new();
+
+    match sub {
+        RobotSub::Capabilities { format } => {
+            let caps = docs.capabilities_data();
+            let output = format_robot_output(&caps, format)?;
+            println!("{}", output);
+        }
+        RobotSub::Schemas { command, format } => {
+            if let Some(cmd) = command {
+                if let Some(schema) = docs.schema(&cmd) {
+                    let output = format_robot_output(&schema, format)?;
+                    println!("{}", output);
+                } else {
+                    return Err(anyhow::anyhow!("Unknown command: {}", cmd));
+                }
+            } else {
+                let schemas = docs.all_schemas();
+                let output = format_robot_output(&schemas, format)?;
+                println!("{}", output);
+            }
+        }
+        RobotSub::Examples { command, format } => {
+            if let Some(cmd) = command {
+                if let Some(examples) = docs.examples(&cmd) {
+                    let output = format_robot_output(&examples, format)?;
+                    println!("{}", output);
+                } else {
+                    return Err(anyhow::anyhow!("Unknown command: {}", cmd));
+                }
+            } else {
+                let all_examples: Vec<_> = docs
+                    .all_schemas()
+                    .iter()
+                    .flat_map(|s| &s.examples)
+                    .collect();
+                let output = format_robot_output(&all_examples, format)?;
+                println!("{}", output);
+            }
+        }
+    }
+
+    Ok(())
+}
+
 fn main() -> Result<()> {
     let args: Vec<String> = std::env::args().collect();
     let corrected_args = apply_forgiving_parsing(&args);
@@ -1632,6 +1733,10 @@ fn main() -> Result<()> {
             }
             rt.block_on(listener::run_listener(listener_config))
         }
+        Some(Command::Robot { sub }) => {
+            handle_robot_command(sub)?;
+            Ok(())
+        }
         Some(command) => {
             let rt = Runtime::new()?;
             let robot_mode = cli.robot;
@@ -2870,6 +2975,9 @@ async fn run_offline_command(
         Command::Repl { .. } => {
             unreachable!("REPL mode should be handled above")
         }
+        Command::Robot { .. } => {
+            unreachable!("Robot commands are handled in main()")
+        }
     }
 }
 
@@ -4590,6 +4698,9 @@ async fn run_server_command(
             eprintln!("The listener runs in offline mode only.");
             std::process::exit(1);
         }
+        Command::Robot { .. } => {
+            unreachable!("Robot commands are handled in main()")
+        }
     }
 }
 

crates/terraphim_agent/tests/offline_mode_tests.rs

@@ -528,3 +528,90 @@ async fn test_forgiving_parser_case_insensitive() -> Result<()> {
 
     Ok(())
 }
+
+#[tokio::test]
+#[serial]
+async fn test_robot_capabilities_json() -> Result<()> {
+    let (stdout, stderr, code) =
+        run_offline_command(&["robot", "capabilities", "--format", "json"])?;
+
+    assert_eq!(
+        code, 0,
+        "robot capabilities should succeed, stderr: {}",
+        stderr
+    );
+
+    // Should output valid JSON
+    let json: serde_json::Value = serde_json::from_str(&stdout).expect("Should be valid JSON");
+    assert!(json.get("name").is_some(), "Should have name field");
+    assert!(json.get("version").is_some(), "Should have version field");
+    assert!(json.get("commands").is_some(), "Should have commands field");
+
+    Ok(())
+}
+
+#[tokio::test]
+#[serial]
+async fn test_robot_schemas_json() -> Result<()> {
+    let (stdout, stderr, code) =
+        run_offline_command(&["robot", "schemas", "search", "--format", "json"])?;
+
+    assert_eq!(
+        code, 0,
+        "robot schemas search should succeed, stderr: {}",
+        stderr
+    );
+
+    // Should output valid JSON schema
+    let json: serde_json::Value = serde_json::from_str(&stdout).expect("Should be valid JSON");
+    assert!(json.get("name").is_some(), "Should have name field");
+    assert!(
+        json.get("arguments").is_some(),
+        "Should have arguments field"
+    );
+
+    Ok(())
+}
+
+#[tokio::test]
+#[serial]
+async fn test_robot_examples_text() -> Result<()> {
+    let (stdout, stderr, code) = run_offline_command(&["robot", "examples", "search"])?;
+
+    assert_eq!(
+        code, 0,
+        "robot examples search should succeed, stderr: {}",
+        stderr
+    );
+
+    // Should output readable text (not error)
+    assert!(
+        !stdout.starts_with("error:") && !stdout.starts_with("Error:"),
+        "Should not show error: {}",
+        stdout
+    );
+    assert!(!stdout.is_empty(), "Should have output");
+
+    Ok(())
+}
+
+#[tokio::test]
+#[serial]
+async fn test_robot_capabilities_all_formats() -> Result<()> {
+    for format in ["json", "table", "minimal"] {
+        let (stdout, stderr, code) =
+            run_offline_command(&["robot", "capabilities", "--format", format])?;
+        assert_eq!(
+            code, 0,
+            "robot capabilities --format {} should succeed, stderr: {}",
+            format, stderr
+        );
+        assert!(
+            !stdout.is_empty(),
+            "Should have output for format {}",
+            format
+        );
+    }
+
+    Ok(())
+}

crates/terraphim_orchestrator/src/concurrency.rs

@@ -162,6 +162,40 @@ impl ConcurrencyController {
         self.acquire(AgentMode::MentionDriven, project).await
     }
 
+    /// Try to acquire a generic slot without mode-specific quota checks.
+    ///
+    /// Only enforces the global semaphore and per-project caps. Used when the
+    /// caller does not know the agent mode (e.g. `spawn_agent` is shared across
+    /// cron, mention, and issue-driven paths).
+    pub async fn acquire_any(&self, project: &str) -> Option<AgentPermit> {
+        if !self
+            .project_has_capacity(AgentMode::TimeDriven, project)
+            .await
+        {
+            return None;
+        }
+        let global_permit = match self.global.clone().try_acquire_owned() {
+            Ok(p) => p,
+            Err(_) => {
+                tracing::debug!("global concurrency limit reached");
+                return None;
+            }
+        };
+        {
+            let mut counts = self.running.lock().await;
+            counts.time_driven += 1;
+            let entry = counts.per_project.entry(project.to_string()).or_default();
+            entry.total += 1;
+        }
+        tracing::debug!(project, "acquired generic concurrency slot");
+        Some(AgentPermit {
+            _global: global_permit,
+            mode: AgentMode::TimeDriven,
+            project: project.to_string(),
+            running: self.running.clone(),
+        })
+    }
+
     /// Get current running counts (time_driven, issue_driven).
     pub async fn running_counts(&self) -> (usize, usize) {
         let counts = self.running.lock().await;