docs(handlers): add scaffold example and cross-links; feat(cli): --strict-validate flag for run_graph to validate handlers+args

Author: jeremi

orchestrator/docs/HANDLERS.md

@@ -128,3 +128,16 @@ This reuses the orchestrator’s persistent MCP clients for `odoo` and `tm`.
 - Discover additional handlers via entry points (packaged plugins) if needed.
 - Optional lockfile to pin handler name/version for reproducibility.
 - Full REST fallback for `github.open_pr` when `gh` is unavailable.
+
+## Scaffolding a custom handler
+
+See `orchestrator/docs/examples/handler_skeleton.py` for a minimal example. It shows:
+
+- Declaring a `name` (e.g., `my.example`)
+- Optional `schema()` to validate arguments
+- `execute()` reading args, writing a log, optionally raising a `NodeInterrupt`, and
+  returning an `ExecResult`.
+
+Today, legacy `uses:` steps are auto-mapped to built-ins. In a future iteration, the
+registry will support project-local plugins so you can drop a handler in your repo and
+reference it by `handler: my.example` in recipes.

orchestrator/docs/examples/handler_skeleton.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from orchestrator.engine.handlers.base import ExecResult, NodeHandler, NodeInterrupt
+
+
+class MyExampleHandler(NodeHandler):
+    """Skeleton for a custom handler.
+
+    Register this handler via a local registry (future), or temporarily call it via
+    `handler: my.example` once the registry supports project-local plugins.
+    """
+
+    name = "my.example"
+
+    def schema(self) -> Dict[str, Any]:
+        # Optional JSON Schema to validate step arguments
+        return {
+            "type": "object",
+            "properties": {
+                "message": {"type": "string"},
+                "interrupt": {"type": "boolean"},
+            },
+            "required": ["message"],
+            "additionalProperties": False,
+        }
+
+    def execute(self, *, args: Dict[str, Any], ctx: Dict[str, Any], **kw) -> ExecResult:
+        logger = kw.get("logger")
+        message = str(args.get("message"))
+        if logger is not None:
+            logger.write_log("custom/example.log", f"message: {message}\n")
+
+        # Example: raise an interrupt to yield control (optional)
+        if bool(args.get("interrupt")):
+            raise NodeInterrupt("await-human", {"note": "please continue"})
+
+        # Normal completion
+        return ExecResult(ok=True, output={"echo": message})

orchestrator/main.py

@@ -116,6 +116,11 @@ def run_graph(
     recipe: str = typer.Option(..., "--recipe", help="Recipe name"),
     config: Optional[Path] = typer.Option(None, "--config"),
     resume_run: Optional[str] = typer.Option(None, "--resume", help="Resume run_id"),
+    strict_validate: bool = typer.Option(
+        False,
+        "--strict-validate/--no-strict-validate",
+        help="Validate each step against resolved handler schema before execution",
+    ),
 ):
     cfg = load_config(config)
     root = repo_root()
@@ -135,6 +140,27 @@ def run_graph(
     cp = Checkpointer(
         root / "orchestrator" / ".orchestrator" / "checkpoints" / "cp.sqlite"
     )
+    # Optional strict validation using the handler registry
+    if strict_validate:
+        from .engine.registry import HandlerRegistry
+
+        reg = HandlerRegistry()
+        ok = True
+        for i, step in enumerate(recipe_data.get("steps", []), start=1):
+            try:
+                h, args = reg.route_compat(step)
+                handler = reg.resolve(h)
+                if not handler:
+                    typer.secho(f"step {i}: handler {h} not found", fg=typer.colors.RED)
+                    ok = False
+                    continue
+                reg.validate_args(handler, args)
+            except Exception as e:
+                typer.secho(f"step {i}: {e}", fg=typer.colors.RED)
+                ok = False
+        if not ok:
+            raise typer.Exit(1)
+
     g = compile_recipe_to_graph(recipe_data)
     with MCPRuntime(odoo_cmd=odoo_cmd, tm_cmd=tm_cmd, repo_root=root) as mcp:
         execg = GraphExecutor(cfg, logger, root, mcp, cp)