Agent-mode API: the machine-facing interface for LLM consumers

agent_api.rs — complete agent-facing API:
- AST-as-JSON bridge: parse_to_json(), json_to_program(), validate_json_ast()
  Agents can produce AST directly as JSON, skip text parsing entirely
- Structured errors: AgentError with error code, Kategoria level, context,
  and Remediation suggestions with confidence scores and AstPatch fixes
- TypeError→AgentError conversion for all 14 error kinds with tailored
  remediations (e.g., LinearUsedTwice → "remove second use" or "clone")
- Valid moves API: variables in scope, callable functions, spawnable agents,
  linear obligations, budget remaining, protocol state
- Grammar summary card: 10 top-level forms, 14 statements, 12 expressions,
  10 types, 54 keywords, 14 operators, 10 cost entries, 11 Harvard rules
- Full validation pipeline: parse→typecheck→summarize in single JSON call

CLI commands: agent-parse, agent-validate, agent-moves, agent-card, agent-from-json

Design rationale: the text syntax is the human interface. The AST-JSON +
structured errors + valid-next-moves API is the agent interface. 007 needs
both. This implements the second.

169 tests (160 + 9 new). Zero clippy warnings.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

crates/oo7-cli/src/main.rs

@@ -23,6 +23,11 @@ fn main() {
         Some("typecheck") => cmd_typecheck(&args),
         Some("eval") => cmd_eval(&args),
         Some("demo") => run_demo(),
+        Some("agent-parse") => cmd_agent_parse(&args),
+        Some("agent-validate") => cmd_agent_validate(&args),
+        Some("agent-moves") => cmd_agent_moves(&args),
+        Some("agent-card") => cmd_agent_card(),
+        Some("agent-from-json") => cmd_agent_from_json(),
         Some("--help") | Some("-h") | None => print_usage(),
         Some(cmd) => {
             eprintln!("Unknown command: {}", cmd);
@@ -36,12 +41,20 @@ fn print_usage() {
     println!("007 Agent Meta-Language — Reference Evaluator");
     println!();
     println!("Usage:");
-    println!("  oo7 parse <file.007>      Parse a .007 file and print AST as JSON");
-    println!("  oo7 check <file.007>      Validate syntax (no output on success)");
-    println!("  oo7 typecheck <file.007>  Type-check a .007 file (L1-3, L7)");
-    println!("  oo7 eval <file.007>       Parse and evaluate (parse-only for now)");
-    println!("  oo7 demo                  Run built-in demo producing decision traces");
-    println!("  oo7 --help                Show this help message");
+    println!("  oo7 parse <file.007>              Parse a .007 file and print AST as JSON");
+    println!("  oo7 check <file.007>              Validate syntax (no output on success)");
+    println!("  oo7 typecheck <file.007>          Type-check a .007 file (L1-3, L7)");
+    println!("  oo7 eval <file.007>               Parse and evaluate (parse-only for now)");
+    println!("  oo7 demo                          Run built-in demo producing decision traces");
+    println!();
+    println!("Agent-Mode API (machine-facing, JSON output):");
+    println!("  oo7 agent-parse <file.007>        Parse and return JSON AST");
+    println!("  oo7 agent-validate <file.007>     Full pipeline: parse + typecheck, return AgentResult");
+    println!("  oo7 agent-moves <file.007> <name> Valid moves for agent <name> as JSON");
+    println!("  oo7 agent-card                    Print grammar reference card as JSON");
+    println!("  oo7 agent-from-json               Read JSON AST from stdin, validate, return AgentResult");
+    println!();
+    println!("  oo7 --help                        Show this help message");
     println!();
     println!("The telescope is on. We're looking.");
 }
@@ -187,6 +200,115 @@ fn cmd_eval(args: &[String]) {
     }
 }
 
+// ============================================================
+// Agent-Mode CLI Commands
+// ============================================================
+
+/// `oo7 agent-parse <file.007>` — parse and return JSON AST.
+///
+/// Equivalent to `oo7 parse` but uses the agent_api bridge for
+/// consistency with the agent-mode interface.
+fn cmd_agent_parse(args: &[String]) {
+    let source = read_source_file(args);
+
+    match oo7_core::agent_api::parse_to_json(&source) {
+        Ok(json) => println!("{}", json),
+        Err(e) => {
+            let err_json = serde_json::to_string_pretty(&e).unwrap_or_else(|_| e.message.clone());
+            eprintln!("{}", err_json);
+            std::process::exit(1);
+        }
+    }
+}
+
+/// `oo7 agent-validate <file.007>` — full pipeline, return AgentResult as JSON.
+///
+/// Runs parse -> typecheck -> declaration summary -> valid moves.
+/// Always outputs JSON, even on error.
+fn cmd_agent_validate(args: &[String]) {
+    let source = read_source_file(args);
+    let result = oo7_core::agent_api::validate_source(&source);
+    let json = serde_json::to_string_pretty(&result).expect("AgentResult serialization failed");
+    println!("{}", json);
+
+    if !result.success {
+        std::process::exit(1);
+    }
+}
+
+/// `oo7 agent-moves <file.007> <agent-name>` — valid moves for an agent.
+///
+/// Parses and type-checks the file, then returns the ValidMoves for
+/// the named agent as JSON.
+fn cmd_agent_moves(args: &[String]) {
+    let source = read_source_file(args);
+    let agent_name = match args.get(3) {
+        Some(name) => name,
+        None => {
+            eprintln!("Error: missing agent name argument.");
+            eprintln!("Usage: oo7 agent-moves <file.007> <agent-name>");
+            std::process::exit(1);
+        }
+    };
+
+    let program = match parser::parse_program(&source) {
+        Ok(p) => p,
+        Err(e) => {
+            let err = oo7_core::agent_api::AgentResult::error(vec![
+                oo7_core::AgentError {
+                    code: "PARSE_ERROR".to_string(),
+                    level: 0,
+                    message: e.to_string(),
+                    location: None,
+                    context: serde_json::Value::Null,
+                    remediations: vec![],
+                },
+            ]);
+            let json = serde_json::to_string_pretty(&err).unwrap();
+            eprintln!("{}", json);
+            std::process::exit(1);
+        }
+    };
+
+    let moves = oo7_core::agent_api::valid_moves(&program, agent_name);
+    let json = serde_json::to_string_pretty(&moves).expect("ValidMoves serialization failed");
+    println!("{}", json);
+}
+
+/// `oo7 agent-card` — print grammar reference card as JSON.
+fn cmd_agent_card() {
+    println!("{}", oo7_core::agent_api::grammar_card());
+}
+
+/// `oo7 agent-from-json` — read JSON AST from stdin, validate, return AgentResult.
+///
+/// Reads the entire stdin as a JSON AST, deserializes to Program,
+/// type-checks, and returns the AgentResult.
+fn cmd_agent_from_json() {
+    let mut input = String::new();
+    if let Err(e) = std::io::Read::read_to_string(&mut std::io::stdin(), &mut input) {
+        let result = oo7_core::agent_api::AgentResult::error(vec![oo7_core::AgentError {
+            code: "IO_ERROR".to_string(),
+            level: 0,
+            message: format!("Failed to read stdin: {}", e),
+            location: None,
+            context: serde_json::Value::Null,
+            remediations: vec![],
+        }]);
+        let json = serde_json::to_string_pretty(&result).unwrap();
+        println!("{}", json);
+        std::process::exit(1);
+    }
+
+    let result = oo7_core::agent_api::validate_json_ast(&input);
+    let json = serde_json::to_string_pretty(&result).expect("AgentResult serialization failed");
+    println!("{}", json);
+
+    if !result.success {
+        std::process::exit(1);
+    }
+}
+
 /// Run a built-in demo that exercises the branch/given/traced system
 /// and produces decision trace output.
 fn run_demo() {