feat(cli): sandcastle run --local (in-process, no server) + onboarding engine pick (#242)

gizmax · Tomas Pflanzer · web-flow · commit 3e537e2b56f6 · 2026-06-02T00:03:22.000+02:00
Two first-run UX fixes.

1. `sandcastle run --local &lt;workflow&gt;` executes a workflow in-process via the engine
   executor, with no running server. Before this, `sandcastle run` was an HTTP client
   pointed at localhost:8080, so a fresh `pip install sandcastle-ai` could not run
   anything until `sandcastle serve` was started - the very first command failed with
   a connection error. --local resolves a .yaml path or a built-in template name,
   builds the plan, best-effort creates a local DB run row (so steps/audit persist and
   the run shows in the dashboard, silently skipped when no DB), and runs the engine
   with admin_trusted=True so code/transform steps work. The connection-error message
   now also suggests --local.

2. Onboarding: add a fifth featured template, Provider Consensus
   (provider-consensus-decision-engine), as an "Engine" pick that showcases the
   provider-neutral thesis (ask three providers, act on their agreement).

Adds test_cli_local_run.py (code-only workflow runs with no server/keys, unknown name
exits cleanly, a built-in name resolves). Existing CLI tests and the 794 dashboard
tests stay green.

Co-authored-by: Tomas Pflanzer &lt;tom@wiseguys.co&gt;
diff --git a/dashboard/src/components/onboarding/StepChooseTemplate.tsx b/dashboard/src/components/onboarding/StepChooseTemplate.tsx
@@ -6,6 +6,7 @@ import {
   FileText,
   Search,
   Database,
+  Network,
   Loader2,
 } from "lucide-react";
 import { api } from "@/api/client";
@@ -64,6 +65,14 @@ const FEATURED_TEMPLATES: FeaturedTemplate[] = [
     icon: Database,
     color: "text-[#A78BFA] bg-[#A78BFA]/10",
   },
+  {
+    name: "provider-consensus-decision-engine",
+    displayName: "Provider Consensus",
+    description: "Ask three AI providers the same question and act on their agreement. Provider-neutral by design: swap or lose a provider and the decision holds.",
+    category: "Engine",
+    icon: Network,
+    color: "text-[#2DD4BF] bg-[#2DD4BF]/10",
+  },
 ];
 
 interface ApiTemplate {
diff --git a/src/sandcastle/__main__.py b/src/sandcastle/__main__.py
@@ -225,7 +225,8 @@ def _format_cli_error(exc: Exception) -> str:
     if "ConnectError" in exc_type or "ConnectionError" in exc_type:
         return (
             f"Connection failed: {exc}\n"
-            "  Is the Sandcastle server running? Start it with: sandcastle serve"
+            "  Is the Sandcastle server running? Start it with: sandcastle serve\n"
+            "  Or run without a server: sandcastle run --local <workflow.yaml>"
         )
     if "ConnectTimeout" in exc_type or "TimeoutException" in exc_type:
         return f"Connection timed out: {exc}\n  Check that the server URL is correct."
@@ -916,6 +917,130 @@ def _cmd_serve(args: argparse.Namespace) -> None:
     )
 
 
+def _run_local(workflow: str, input_data: dict[str, Any], max_cost: float | None) -> None:
+    """Execute a workflow in-process, without a running server.
+
+    Resolves *workflow* as a path to a .yaml file or as a built-in template name,
+    builds the plan, and runs it through the engine executor directly. The local
+    caller is trusted, so code/transform steps are allowed. Run-step persistence is
+    best-effort and silently skipped when no database is configured.
+    """
+    import asyncio
+    import tempfile
+    from pathlib import Path
+
+    from sandcastle.engine.dag import build_plan, parse_yaml_string
+    from sandcastle.engine.executor import execute_workflow
+    from sandcastle.engine.storage import LocalStorage
+
+    wf_path = Path(workflow)
+    try:
+        if wf_path.suffix in (".yaml", ".yml") and wf_path.exists():
+            content = wf_path.read_text()
+        else:
+            from sandcastle.templates import get_template
+
+            content, _ = get_template(workflow)
+        wf = parse_yaml_string(content)
+        plan = build_plan(wf)
+    except FileNotFoundError:
+        print(
+            f"Error: workflow '{workflow}' not found as a file or a built-in template.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    except Exception as exc:
+        print(_format_cli_error(exc), file=sys.stderr)
+        sys.exit(1)
+
+    storage = LocalStorage(tempfile.mkdtemp(prefix="sandcastle-local-"))
+    print(_color(f"Running '{wf.name}' locally (in-process, no server)...", _C.CYAN))
+
+    async def _local_async() -> Any:
+        import uuid
+
+        run_id = str(uuid.uuid4())
+        persisted = False
+        # Best-effort: set up the local DB and a parent run row so step/audit
+        # persistence works and the run shows up in the dashboard. When no DB is
+        # available this is silently skipped and the run still executes.
+        try:
+            from sandcastle.models.db import Run, RunStatus, async_session, init_db
+
+            await init_db()
+            async with async_session() as session:
+                session.add(
+                    Run(
+                        id=uuid.UUID(run_id),
+                        workflow_name=wf.name,
+                        status=RunStatus.RUNNING,
+                        input_data=input_data,
+                        max_cost_usd=max_cost,
+                    )
+                )
+                await session.commit()
+            persisted = True
+        except Exception:
+            persisted = False
+
+        wf_result = await execute_workflow(
+            workflow=wf,
+            plan=plan,
+            input_data=input_data,
+            run_id=run_id if persisted else None,
+            storage=storage,
+            max_cost_usd=max_cost,
+            admin_trusted=True,
+        )
+
+        if persisted:
+            try:
+                from sandcastle.models.db import Run, RunStatus, async_session
+
+                status_map = {
+                    "completed": RunStatus.COMPLETED,
+                    "failed": RunStatus.FAILED,
+                    "error": RunStatus.FAILED,
+                    "partial": RunStatus.PARTIAL,
+                    "cancelled": RunStatus.CANCELLED,
+                    "budget_exceeded": RunStatus.BUDGET_EXCEEDED,
+                }
+                async with async_session() as session:
+                    db_run = await session.get(Run, uuid.UUID(run_id))
+                    if db_run is not None:
+                        db_run.status = status_map.get(
+                            str(_attr(wf_result, "status", "")), RunStatus.COMPLETED
+                        )
+                        db_run.total_cost_usd = _attr(wf_result, "total_cost_usd", 0.0)
+                        db_run.output_data = _attr(wf_result, "outputs", {})
+                        db_run.error = _attr(wf_result, "error", None)
+                        await session.commit()
+            except Exception:
+                pass
+        return wf_result
+
+    try:
+        result = asyncio.run(_local_async())
+    except Exception as exc:
+        print(_format_cli_error(exc), file=sys.stderr)
+        sys.exit(1)
+
+    status = _attr(result, "status", "unknown")
+    run_id = _attr(result, "run_id", "")
+    cost = _attr(result, "total_cost_usd", 0.0)
+    error = _attr(result, "error", None)
+    outputs = _attr(result, "outputs", {}) or {}
+
+    print(f"{_status_color(str(status))}  run {run_id}  cost ${float(cost or 0.0):.4f}")
+    if error:
+        print(_color(f"Error: {error}", _C.RED), file=sys.stderr)
+    if outputs:
+        print(_color("Outputs:", _C.BOLD))
+        print(json.dumps(outputs, indent=2, default=str))
+    if str(status) in ("failed", "error", "budget_exceeded"):
+        sys.exit(2)
+
+
 def _cmd_run(args: argparse.Namespace) -> None:
     """Run a workflow via the SDK client."""
     from pathlib import Path
@@ -931,6 +1056,15 @@ def _cmd_run(args: argparse.Namespace) -> None:
         print("Error: workflow name cannot be empty.", file=sys.stderr)
         sys.exit(1)
 
+    # Local in-process execution path - no running server required.
+    if getattr(args, "local", False):
+        input_data: dict[str, Any] = {}
+        if args.input_file:
+            input_data = _load_input_file(args.input_file)
+        input_data.update(_parse_input_pairs(args.input))
+        _run_local(workflow_name, input_data, args.max_cost)
+        return
+
     client = _get_client(args)
 
     # Build input data
@@ -4373,6 +4507,11 @@ def _build_parser() -> argparse.ArgumentParser:
     p_run.add_argument(
         "--max-cost", type=float, default=None, metavar="USD", help="Maximum cost limit in USD"
     )
+    p_run.add_argument(
+        "--local",
+        action="store_true",
+        help="Run the workflow in-process without a server (no `sandcastle serve` needed)",
+    )
     _add_connection_args(p_run)
 
     # --- status ---
diff --git a/tests/test_cli_local_run.py b/tests/test_cli_local_run.py
@@ -0,0 +1,59 @@
+"""Tests for `sandcastle run --local` - in-process execution without a server.
+
+The local path fixes the first-run experience: a fresh `pip install` could not run
+anything because `sandcastle run` is an HTTP client that needs `sandcastle serve`
+first. `--local` parses the workflow and drives the engine executor directly.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from sandcastle.__main__ import _run_local
+
+CODE_ONLY_WORKFLOW = """name: cli-local-test
+description: A code-only workflow that runs with no server and no API keys.
+default_model: sonnet
+input_schema:
+  required: []
+  properties:
+    who: { type: string, default: "world" }
+steps:
+  - id: greet
+    type: code
+    code_config:
+      code: |
+        result = {"msg": "hi " + str(_input.get("who", "world")), "n": 6 * 7}
+"""
+
+
+def test_run_local_executes_code_only_workflow(tmp_path, capsys):
+    """A code-only workflow runs in-process and prints its output - no server, no keys."""
+    wf = tmp_path / "wf.yaml"
+    wf.write_text(CODE_ONLY_WORKFLOW)
+    _run_local(str(wf), {"who": "tester"}, None)
+    out = capsys.readouterr().out
+    assert "completed" in out
+    assert "hi tester" in out
+    assert "42" in out  # 6 * 7, proving the code step actually executed
+
+
+def test_run_local_unknown_workflow_exits_cleanly(capsys):
+    """An unknown name (not a file, not a built-in template) exits 1 with a clear error."""
+    with pytest.raises(SystemExit) as exc_info:
+        _run_local("/nonexistent/path/nope.yaml", {}, None)
+    assert exc_info.value.code == 1
+    assert "not found" in capsys.readouterr().err
+
+
+def test_run_local_resolves_builtin_template_name(tmp_path, capsys):
+    """A bare built-in template name resolves (does not error as 'not found'). It may
+    fail later for lack of provider keys, but resolution + planning must succeed."""
+    # 'summarize' is a built-in template; with no key it will fail at the LLM step,
+    # which exits 2 (run failed) - never the 'not found' path (exit 1).
+    try:
+        _run_local("summarize", {"text": "hello"}, None)
+    except SystemExit as exc:
+        assert exc.code in (0, 2), f"unexpected exit code {exc.code}"
+    combined = capsys.readouterr()
+    assert "not found" not in (combined.out + combined.err)
