feat: Wire output schema into CLI and runtime execution

Complete CLI to runtime integration for structured I/O:

CLI Layer:
- Parse --output-schema flag (pre-built names or inline JSON)
- Parse --output-schema-file flag (JSON schema from file)
- Pass parsed schema to run_agent() function

Runtime Integration:
- Import AgentContext for schema attachment
- Create context with schema using .with_output_schema()
- Execute using runtime.execute_with_context() when schema present
- Fallback to standard execute() when no schema

Supported Schema Names:
- container-list: Docker/K8s container listings
- resource-stats: CPU/memory statistics
- simple-list: Generic item lists
- key-value: Key-value data

Example Usage:
  aofctl run agent docker.yaml --output-schema container-list
  aofctl run agent k8s.yaml --output-schema-file custom.json
  aofctl run agent stats.yaml --output-schema resource-stats

The schema enhances the system prompt with JSON schema instructions,
ensuring the LLM produces consistently structured output.

Related: #74

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

Author: initcron

crates/aof-runtime/src/executor/agent_executor.rs

@@ -663,7 +663,7 @@ impl AgentExecutor {
         warn!("[BUILD_REQUEST] Converted {} messages", messages.len());
 
         // Get tool definitions if available
-        let tools: Vec<ModelToolDefinition> = if let Some(executor) = &self.tool_executor {
+        let mut tools: Vec<ModelToolDefinition> = if let Some(executor) = &self.tool_executor {
             warn!("[BUILD_REQUEST] Tool executor available, listing tools...");
             let tool_defs = executor.list_tools();
             warn!("[BUILD_REQUEST] Got {} tool definitions from executor", tool_defs.len());
@@ -683,15 +683,28 @@ impl AgentExecutor {
             Vec::new()
         };
 
-        warn!("[BUILD_REQUEST] Final: messages={}, tools={}, system_prompt={:?}",
+        // Enhance system prompt with output schema instructions if schema is present
+        let system_prompt = if let Some(schema) = &context.output_schema {
+            warn!("[BUILD_REQUEST] Output schema present, adding structured output instructions");
+
+            let base_prompt = self.config.system_prompt.as_deref().unwrap_or("");
+            let schema_instructions = schema.to_system_instructions();
+
+            Some(format!("{}\n\n{}", base_prompt, schema_instructions))
+        } else {
+            self.config.system_prompt.clone()
+        };
+
+        warn!("[BUILD_REQUEST] Final: messages={}, tools={}, system_prompt={:?}, has_schema={}",
             messages.len(),
             tools.len(),
-            self.config.system_prompt.as_ref().map(|s| s.len())
+            system_prompt.as_ref().map(|s| s.len()),
+            context.output_schema.is_some()
         );
 
         Ok(ModelRequest {
             messages,
-            system: self.config.system_prompt.clone(),
+            system: system_prompt,
             tools,
             temperature: Some(self.config.temperature),
             max_tokens: self.config.max_tokens,

crates/aofctl/src/cli.rs

@@ -43,6 +43,16 @@ pub enum Commands {
         /// Output format (json, yaml, text)
         #[arg(short, long, default_value = "text")]
         output: String,
+
+        /// Output schema for structured responses
+        /// Use pre-built schema names (container-list, resource-stats, simple-list, key-value)
+        /// or provide inline JSON schema
+        #[arg(long)]
+        output_schema: Option<String>,
+
+        /// Path to JSON schema file for output validation
+        #[arg(long, conflicts_with = "output_schema")]
+        output_schema_file: Option<String>,
     },
 
     /// Get resources (verb-first: get agents, get agent <name>)
@@ -219,12 +229,16 @@ impl Cli {
                 name_or_config,
                 input,
                 output,
+                output_schema,
+                output_schema_file,
             } => {
                 commands::run::execute(
                     &resource_type,
                     &name_or_config,
                     input.as_deref(),
                     &output,
+                    output_schema.as_deref(),
+                    output_schema_file.as_deref(),
                     context.as_ref(),
                 )
                 .await

crates/aofctl/src/commands/run.rs

@@ -1,5 +1,5 @@
 use anyhow::{Context as AnyhowContext, Result, anyhow};
-use aof_core::{AgentConfig, Context as AofContext};
+use aof_core::{AgentConfig, AgentContext, Context as AofContext, OutputSchema};
 use aof_runtime::Runtime;
 use std::fs;
 use std::io::{self, IsTerminal, Write};
@@ -155,12 +155,53 @@ impl Write for LogWriter {
     }
 }
 
+/// Parse output schema from CLI arguments
+fn parse_output_schema(
+    schema_name: Option<&str>,
+    schema_file: Option<&str>,
+) -> Result<Option<OutputSchema>> {
+    use aof_core::schema::schemas;
+
+    if let Some(file_path) = schema_file {
+        // Read schema from file
+        let content = fs::read_to_string(file_path)
+            .with_context(|| format!("Failed to read schema file: {}", file_path))?;
+        let schema_json: serde_json::Value = serde_json::from_str(&content)
+            .with_context(|| format!("Failed to parse schema file as JSON: {}", file_path))?;
+        return Ok(Some(OutputSchema::from_json_schema(schema_json)));
+    }
+
+    if let Some(name) = schema_name {
+        // Check if it's a pre-built schema name
+        let schema = match name {
+            "container-list" => schemas::container_list(),
+            "resource-stats" => schemas::resource_stats(),
+            "simple-list" => schemas::simple_list(),
+            "key-value" => schemas::key_value(),
+            _ => {
+                // Try to parse as inline JSON schema
+                let schema_json: serde_json::Value = serde_json::from_str(name)
+                    .with_context(|| format!(
+                        "Invalid schema name '{}'. Expected one of: container-list, resource-stats, simple-list, key-value, or inline JSON schema",
+                        name
+                    ))?;
+                OutputSchema::from_json_schema(schema_json)
+            }
+        };
+        return Ok(Some(schema));
+    }
+
+    Ok(None)
+}
+
 /// Execute a resource (agent, workflow, job) with configuration and input
 pub async fn execute(
     resource_type: &str,
     name_or_config: &str,
     input: Option<&str>,
     output: &str,
+    output_schema: Option<&str>,
+    output_schema_file: Option<&str>,
     context: Option<&AofContext>,
 ) -> Result<()> {
     // Log context if provided
@@ -178,8 +219,11 @@ pub async fn execute(
     let rt = ResourceType::from_str(resource_type)
         .ok_or_else(|| anyhow::anyhow!("Unknown resource type: {}", resource_type))?;
 
+    // Parse output schema if provided
+    let schema = parse_output_schema(output_schema, output_schema_file)?;
+
     match rt {
-        ResourceType::Agent => run_agent(name_or_config, input, output, context).await,
+        ResourceType::Agent => run_agent(name_or_config, input, output, schema, context).await,
         ResourceType::Workflow | ResourceType::Flow => run_workflow(name_or_config, input, output).await,
         ResourceType::Fleet => run_fleet(name_or_config, input, output).await,
         ResourceType::Job => run_job(name_or_config, input, output).await,
@@ -190,7 +234,13 @@ pub async fn execute(
 }
 
 /// Run an agent with configuration
-async fn run_agent(config: &str, input: Option<&str>, output: &str, context: Option<&AofContext>) -> Result<()> {
+async fn run_agent(
+    config: &str,
+    input: Option<&str>,
+    output: &str,
+    schema: Option<OutputSchema>,
+    context: Option<&AofContext>,
+) -> Result<()> {
     // Check if interactive mode should be enabled (when no input provided and stdin is a TTY)
     let interactive = input.is_none() && io::stdin().is_terminal();
 
@@ -251,10 +301,21 @@ async fn run_agent(config: &str, input: Option<&str>, output: &str, context: Opt
         }
     });
 
-    let result = runtime
-        .execute(&agent_name, input_str)
-        .await
-        .with_context(|| "Failed to execute agent")?;
+    // Execute with or without schema
+    let result = if let Some(output_schema) = schema {
+        // Create context with schema attached
+        let mut ctx = AgentContext::new(input_str).with_output_schema(output_schema);
+        runtime
+            .execute_with_context(&agent_name, &mut ctx)
+            .await
+            .with_context(|| "Failed to execute agent with schema")?
+    } else {
+        // Standard execution without schema
+        runtime
+            .execute(&agent_name, input_str)
+            .await
+            .with_context(|| "Failed to execute agent")?
+    };
 
     // Stop spinner
     spinner_handle.abort();