feat(orchestrator): per-handler JSON Schema validation; doctor validate-recipe checks handler args; add mcp.call schema

Author: jeremi

orchestrator/engine/handlers/agent.py

@@ -8,6 +8,13 @@
 class AgentWaitHandler(NodeHandler):
     name = "agent.wait"
 
+    def schema(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {"goal": {"type": "string"}},
+            "additionalProperties": False,
+        }
+
     def execute(self, *, args: Dict[str, Any], ctx: Dict[str, Any], **kw) -> ExecResult:
         logger = kw.get("logger")
         goal = str(args.get("goal", ""))

orchestrator/engine/handlers/git.py

@@ -8,6 +8,16 @@
 class GitHandler(NodeHandler):
     name = "git.apply"
 
+    def schema(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "branch": {"type": "string"},
+                "commit": {"type": "string"},
+            },
+            "additionalProperties": False,
+        }
+
     def execute(self, *, args: Dict[str, Any], ctx: Dict[str, Any], **kw) -> ExecResult:
         git = kw.get("git")
         assert git is not None, "Git adapter missing"

orchestrator/engine/handlers/github.py

@@ -8,6 +8,18 @@
 class OpenPRHandler(NodeHandler):
     name = "github.open_pr"
 
+    def schema(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "base": {"type": "string"},
+                "title": {"type": "string"},
+                "bodyFrom": {"type": "string"},
+            },
+            "required": ["base", "title"],
+            "additionalProperties": False,
+        }
+
     def execute(self, *, args: Dict[str, Any], ctx: Dict[str, Any], **kw) -> ExecResult:
         gh = kw.get("github")
         tm = kw.get("tm")

orchestrator/engine/handlers/mcp.py

@@ -8,6 +8,18 @@
 class MCPCallHandler(NodeHandler):
     name = "mcp.call"
 
+    def schema(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "server": {"type": "string"},
+                "tool": {"type": "string"},
+                "arguments": {"type": "object"},
+            },
+            "required": ["server", "tool"],
+            "additionalProperties": False,
+        }
+
     def execute(self, *, args: Dict[str, Any], ctx: Dict[str, Any], **kw) -> ExecResult:
         clients: Dict[str, Any] = kw.get("mcp_clients", {})
         server = str(args.get("server"))

orchestrator/engine/handlers/odoo.py

@@ -8,6 +8,17 @@
 class OdooToolHandler(NodeHandler):
     name = "odoo.call"
 
+    def schema(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "tool": {"type": "string"},
+                "args": {"type": "object"},
+            },
+            "required": ["tool"],
+            "additionalProperties": False,
+        }
+
     def execute(self, *, args: Dict[str, Any], ctx: Dict[str, Any], **kw) -> ExecResult:
         odoo = kw.get("odoo")
         assert odoo is not None, "Odoo adapter missing"

orchestrator/engine/handlers/tm.py

@@ -8,6 +8,14 @@
 class TMDecisionHandler(NodeHandler):
     name = "tm.log_decision"
 
+    def schema(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {"note": {"type": "string"}},
+            "required": ["note"],
+            "additionalProperties": False,
+        }
+
     def execute(self, *, args: Dict[str, Any], ctx: Dict[str, Any], **kw) -> ExecResult:
         tm = kw.get("tm")
         assert tm is not None, "TM adapter missing"
@@ -19,6 +27,14 @@ def execute(self, *, args: Dict[str, Any], ctx: Dict[str, Any], **kw) -> ExecRes
 class TMSetStatusHandler(NodeHandler):
     name = "tm.set_status"
 
+    def schema(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {"status": {"type": "string"}},
+            "required": ["status"],
+            "additionalProperties": False,
+        }
+
     def execute(self, *, args: Dict[str, Any], ctx: Dict[str, Any], **kw) -> ExecResult:
         tm = kw.get("tm")
         assert tm is not None, "TM adapter missing"

orchestrator/engine/registry.py

@@ -34,6 +34,14 @@ def register(self, handler: NodeHandler) -> None:
     def resolve(self, name: str) -> Optional[NodeHandler]:
         return self._by_name.get(name)
 
+    def validate_args(self, handler: NodeHandler, args: Dict[str, Any]) -> None:
+        try:
+            import jsonschema  # type: ignore
+        except Exception as e:  # pragma: no cover
+            raise RuntimeError("jsonschema is required for handler validation") from e
+        schema = handler.schema() or {"type": "object"}
+        jsonschema.validate(instance=args, schema=schema)
+
     def route_compat(self, step: Dict[str, Any]) -> Tuple[str, Dict[str, Any]]:
         """Map legacy 'uses' step to a handler name + args.
 

orchestrator/main.py

@@ -184,6 +184,10 @@ def validate_recipe(
             if not reg.resolve(h):
                 typer.secho(f"step {i}: handler {h} not found", fg=typer.colors.RED)
                 ok = False
+            else:
+                # Validate args against handler schema
+                _, args = reg.route_compat(step)
+                reg.validate_args(reg.resolve(h), args)  # type: ignore[arg-type]
         except Exception as e:
             typer.secho(f"step {i}: {e}", fg=typer.colors.RED)
             ok = False