levain-cli 0.1.18__tar.gz → 0.1.20__tar.gz

{levain_cli-0.1.18 → levain_cli-0.1.20}/.gitignore

@@ -69,6 +69,7 @@ skills-lock.json
 .claude/skills/*
 !.claude/skills/check-pr/
 !.claude/skills/weekly-update/
+!.claude/skills/cost-review/
 
 # Knead orchestrator state
 .knead/

{levain_cli-0.1.18 → levain_cli-0.1.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: levain-cli
-Version: 0.1.18
+Version: 0.1.20
 Summary: Levain recipe toolchain: PlusCal validator, TLC model checking, and GraphState codegen for agent recipes
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -17,21 +17,31 @@ Description-Content-Type: text/markdown
 # levain-cli
 
 The open toolchain for authoring [Levain](https://levainlabs.com) agent
-recipes: a validator, model checker, and code generator for the PlusCal
-recipe format that Levain agents are defined in.
+recipes: a validator, model checker, and code generator for the recipe
+formats that Levain agents are defined in.
 
-A recipe package is a `graph.tla` PlusCal spec (the agent's node graph
-and state) plus a Python package with one function per node. This tool
-checks both halves and keeps them coherent:
+A recipe package is one of two kinds, set by `kind` under `[tool.levain]`
+in its `pyproject.toml`:
 
-- **validate** — parse the spec, enforce the recipe grammar profile,
+- **graph** (the default): a `graph.tla` PlusCal spec (the agent's node
+  graph and state) plus a Python package with one function per node.
+- **harness**: one engine session (Claude Code or Hermes) declared in
+  `[tool.levain.harness]`: engine, model, effort, system prompt, tools,
+  MCP servers and state fields. No graph and no Python.
+
+This tool checks both and keeps a graph's two halves coherent:
+
+- **validate** — parse a spec, enforce the recipe grammar profile,
   check graph topology, translate PlusCal to TLA+, and model-check the
   result with TLC (deadlock and termination).
-- **validate-package** — all of the above, plus Python source
-  cross-checks (every `@node` function exists and is importable) and
-  `pyproject.toml` checks.
+- **validate-package** — validate a package of either kind. For a
+  graph: all of the above, plus Python source cross-checks (every
+  `@node` function exists and is importable) and `pyproject.toml`
+  checks. For a harness: the `[tool.levain.harness]` keys and values,
+  the prompt file, the state fields and the MCP server names.
 - **generate-state** — regenerate `_state.py`, the typed `GraphState`
-  TypedDict node functions program against.
+  TypedDict a graph's node functions program against. A harness has
+  no state module.
 
 ## Install
 
@@ -58,9 +68,13 @@ The import package is `levain_recipe` — use it to lint recipes from
 your own CI or scripts:
 
 ```python
-from levain_recipe.validate import validate_fast
+from levain_recipe.validate import validate_fast, validate_recipe
 ```
 
+`validate_recipe(dir)` reads the package's kind and returns a
+`ValidatedSpec` for a graph or a `HarnessSpec` for a harness, or a list
+of errors.
+
 Validation errors are prescriptive (`[stage] line N: message`, with
 TLC counterexample traces) — they are the recipe format's primary
 teaching interface, for humans and agents alike.

{levain_cli-0.1.18 → levain_cli-0.1.20}/README.md

@@ -1,21 +1,31 @@
 # levain-cli
 
 The open toolchain for authoring [Levain](https://levainlabs.com) agent
-recipes: a validator, model checker, and code generator for the PlusCal
-recipe format that Levain agents are defined in.
+recipes: a validator, model checker, and code generator for the recipe
+formats that Levain agents are defined in.
 
-A recipe package is a `graph.tla` PlusCal spec (the agent's node graph
-and state) plus a Python package with one function per node. This tool
-checks both halves and keeps them coherent:
+A recipe package is one of two kinds, set by `kind` under `[tool.levain]`
+in its `pyproject.toml`:
 
-- **validate** — parse the spec, enforce the recipe grammar profile,
+- **graph** (the default): a `graph.tla` PlusCal spec (the agent's node
+  graph and state) plus a Python package with one function per node.
+- **harness**: one engine session (Claude Code or Hermes) declared in
+  `[tool.levain.harness]`: engine, model, effort, system prompt, tools,
+  MCP servers and state fields. No graph and no Python.
+
+This tool checks both and keeps a graph's two halves coherent:
+
+- **validate** — parse a spec, enforce the recipe grammar profile,
   check graph topology, translate PlusCal to TLA+, and model-check the
   result with TLC (deadlock and termination).
-- **validate-package** — all of the above, plus Python source
-  cross-checks (every `@node` function exists and is importable) and
-  `pyproject.toml` checks.
+- **validate-package** — validate a package of either kind. For a
+  graph: all of the above, plus Python source cross-checks (every
+  `@node` function exists and is importable) and `pyproject.toml`
+  checks. For a harness: the `[tool.levain.harness]` keys and values,
+  the prompt file, the state fields and the MCP server names.
 - **generate-state** — regenerate `_state.py`, the typed `GraphState`
-  TypedDict node functions program against.
+  TypedDict a graph's node functions program against. A harness has
+  no state module.
 
 ## Install
 
@@ -42,9 +52,13 @@ The import package is `levain_recipe` — use it to lint recipes from
 your own CI or scripts:
 
 ```python
-from levain_recipe.validate import validate_fast
+from levain_recipe.validate import validate_fast, validate_recipe
 ```
 
+`validate_recipe(dir)` reads the package's kind and returns a
+`ValidatedSpec` for a graph or a `HarnessSpec` for a harness, or a list
+of errors.
+
 Validation errors are prescriptive (`[stage] line N: message`, with
 TLC counterexample traces) — they are the recipe format's primary
 teaching interface, for humans and agents alike.

{levain_cli-0.1.18 → levain_cli-0.1.20}/levain_recipe/__init__.py

@@ -17,4 +17,4 @@ avoid them.
 # or annotation vocabulary changes, independently of tool
 # releases.  The API's toolchain handshake compares this against
 # the server's copy.
-LANGUAGE_VERSION = "1.0"
+LANGUAGE_VERSION = "1.1"

{levain_cli-0.1.18 → levain_cli-0.1.20}/levain_recipe/_format.py

@@ -8,7 +8,7 @@ language-version bump.
 
 from __future__ import annotations
 
-from .models import ValidatedSpec, ValidationError
+from .models import HarnessSpec, RecipeSpec, ValidationError
 
 
 def format_error(err: ValidationError) -> str:
@@ -31,8 +31,16 @@ def format_errors(errors: list[ValidationError]) -> str:
     return f"{header}\n{body}\n\nFix these errors and regenerate the spec."
 
 
-def format_success(spec: ValidatedSpec) -> str:
+def format_success(spec: RecipeSpec) -> str:
     """Format the success summary."""
+    if isinstance(spec, HarnessSpec):
+        fields = ", ".join(v.name for v in spec.variables)
+        return (
+            f"VALIDATION PASSED\n\n"
+            f"Kind: harness\n"
+            f"Engine: {spec.engine} ({spec.model})\n"
+            f"State: {fields}"
+        )
     nodes = ", ".join(n.label for n in spec.nodes)
     transitions = sum(len(r.routes) for r in spec.routing)
     invariants = ", ".join(spec.invariants) if spec.invariants else "(none)"

{levain_cli-0.1.18 → levain_cli-0.1.20}/levain_recipe/cli.py

@@ -23,7 +23,8 @@ from . import LANGUAGE_VERSION
 from ._format import format_errors, format_success
 from ._java import ensure_jar
 from .codegen import generate_state_module, state_module_signature
-from .validate import validate, validate_fast, validate_package
+from .models import ValidatedSpec
+from .validate import validate, validate_fast, validate_recipe
 
 app = typer.Typer(
     name="levain",
@@ -111,7 +112,7 @@ def validate_package_cmd(
         typer.Argument(help="Path to recipe package directory"),
     ],
 ) -> None:
-    """Validate a full recipe package (graph.tla + Python source)."""
+    """Validate a recipe package (a graph with its Python source, or a harness)."""
     if not recipe_dir.is_dir():
         print(
             f"Error: not a directory: {recipe_dir}",
@@ -120,7 +121,7 @@ def validate_package_cmd(
         raise typer.Exit(2)
 
     _prepare_tlc()
-    result = validate_package(str(recipe_dir))
+    result = validate_recipe(str(recipe_dir))
     if isinstance(result, list):
         print(format_errors(result))
         raise typer.Exit(1)
@@ -130,27 +131,33 @@ def validate_package_cmd(
     # matches. The comparison is structural (field names, types,
     # reducers) so formatter rewraps and doc metadata don't trip
     # it. Read-only on purpose — ``generate-state`` writes.
-    state_path = recipe_dir / "src" / result.module_name / "_state.py"
-    if state_path.parent.is_dir():
-        expected = state_module_signature(generate_state_module(result))
-        current = (
-            state_module_signature(state_path.read_text(encoding="utf-8"))
-            if state_path.is_file()
-            else None
-        )
-        if current != expected:
-            what = "missing" if current is None else "stale"
-            print(
-                f"Error: {state_path.relative_to(recipe_dir)} is {what} — "
-                f"run `levain generate-state {recipe_dir}` and commit "
-                f"the result.",
-                file=sys.stderr,
-            )
-            raise typer.Exit(1)
+    if isinstance(result, ValidatedSpec):
+        _check_state_module(recipe_dir, result)
 
     print(format_success(result))
 
 
+def _check_state_module(recipe_dir: Path, result: ValidatedSpec) -> None:
+    state_path = recipe_dir / "src" / result.module_name / "_state.py"
+    if not state_path.parent.is_dir():
+        return
+    expected = state_module_signature(generate_state_module(result))
+    current = (
+        state_module_signature(state_path.read_text(encoding="utf-8"))
+        if state_path.is_file()
+        else None
+    )
+    if current != expected:
+        what = "missing" if current is None else "stale"
+        print(
+            f"Error: {state_path.relative_to(recipe_dir)} is {what} — "
+            f"run `levain generate-state {recipe_dir}` and commit "
+            f"the result.",
+            file=sys.stderr,
+        )
+        raise typer.Exit(1)
+
+
 @app.command("generate-state")
 def generate_state_cmd(
     recipe_dir: Annotated[
@@ -171,10 +178,16 @@ def generate_state_cmd(
         raise typer.Exit(2)
 
     _prepare_tlc()
-    result = validate_package(str(recipe_dir))
+    result = validate_recipe(str(recipe_dir))
     if isinstance(result, list):
         print(format_errors(result))
         raise typer.Exit(1)
+    if not isinstance(result, ValidatedSpec):
+        print(
+            "Error: a harness recipe has no Python state module.",
+            file=sys.stderr,
+        )
+        raise typer.Exit(2)
 
     src_dir = recipe_dir / "src" / result.module_name
     if not src_dir.is_dir():

levain_cli-0.1.20/levain_recipe/harness.py

@@ -0,0 +1,346 @@
+"""Harness recipe packages: one engine session, declared in ``pyproject.toml``.
+
+A harness recipe has no ``graph.tla`` and no node functions.  Its
+``pyproject.toml`` carries::
+
+    [tool.levain]
+    kind = "harness"
+
+    [tool.levain.harness]
+    engine = "claude_code"            # or "hermes"
+    model = "claude-sonnet-4-6"
+    effort = "high"                   # optional
+    prompt = "prompts/system.md"      # optional system-prompt append
+    tools = ["Read", "Edit", "Bash"]  # optional permission allowlist
+    mcp_servers = ["levain-wiki"]     # optional, platform or attached names
+    permission_mode = "bypassPermissions"
+
+    [tool.levain.harness.state]
+    task = { type = "string", description = "What to work on" }
+    summary = "string"                # shorthand: type only
+
+Validation errors are prescriptive in the same ``[stage] message``
+shape as the PlusCal pipeline, so the build agent and the CLI treat
+both kinds alike.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from typing import Any
+
+from .integrations_check import check_mcp_names
+from .models import (
+    DEFAULT_PERMISSION_MODE,
+    DEFAULT_RECIPE_KIND,
+    EFFORT_LEVELS,
+    HARNESS_ENGINES,
+    MESSAGES_FIELD,
+    PERMISSION_MODES,
+    RECIPE_KINDS,
+    SPEC_TYPES,
+    HarnessSpec,
+    NodeAnnotation,
+    StateField,
+    ValidationError,
+)
+from .reducers import REDUCERS
+
+_STAGE = "harness"
+_KEYS = (
+    "engine",
+    "model",
+    "effort",
+    "prompt",
+    "tools",
+    "mcp_servers",
+    "permission_mode",
+    "state",
+)
+_FIELD_KEYS = ("type", "default", "description", "reducer")
+_DEFAULTS: dict[str, Any] = {
+    "bool": False,
+    "string": "",
+    "int": 0,
+    "list": [],
+}
+
+
+def _err(message: str) -> ValidationError:
+    return ValidationError(stage=_STAGE, message=message)
+
+
+def read_pyproject(recipe_dir: str) -> dict[str, Any] | list[ValidationError]:
+    path = os.path.join(recipe_dir, "pyproject.toml")
+    if not os.path.isfile(path):
+        return [
+            ValidationError(
+                stage="source",
+                message="pyproject.toml not found in recipe directory.",
+            )
+        ]
+    try:
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except tomllib.TOMLDecodeError as exc:
+        return [
+            ValidationError(
+                stage="source",
+                message=f"pyproject.toml is not valid TOML: {exc}",
+            )
+        ]
+
+
+def _levain_table(data: dict[str, Any]) -> dict[str, Any]:
+    tool = data.get("tool")
+    levain = tool.get("levain") if isinstance(tool, dict) else None
+    return levain if isinstance(levain, dict) else {}
+
+
+def recipe_kind(recipe_dir: str) -> str | list[ValidationError]:
+    """The package's declared kind; ``graph`` when nothing says otherwise.
+
+    A missing ``pyproject.toml`` reads as ``graph`` so the PlusCal
+    pipeline reports it with its own, more specific error.
+    """
+    data = read_pyproject(recipe_dir)
+    if isinstance(data, list):
+        return DEFAULT_RECIPE_KIND
+    kind = _levain_table(data).get("kind", DEFAULT_RECIPE_KIND)
+    if kind not in RECIPE_KINDS:
+        return [
+            _err(
+                f"[tool.levain] kind = {kind!r} is not a recipe kind."
+                f" Known: {', '.join(RECIPE_KINDS)}."
+            )
+        ]
+    return str(kind)
+
+
+def load_harness_spec(
+    recipe_dir: str,
+    *,
+    attached_mcp_names: list[str] | None = None,
+) -> HarnessSpec | list[ValidationError]:
+    """Read and validate ``[tool.levain.harness]``.
+
+    ``attached_mcp_names`` has the same contract as the PlusCal
+    pipeline's MCP-name check (see ``integrations_check``).
+    """
+    data = read_pyproject(recipe_dir)
+    if isinstance(data, list):
+        return data
+    table = _levain_table(data).get("harness")
+    if not isinstance(table, dict):
+        return [
+            _err(
+                "[tool.levain.harness] table is missing. A harness recipe"
+                " declares at least `engine` and `model` there."
+            )
+        ]
+
+    errors: list[ValidationError] = []
+    for key in table:
+        if key not in _KEYS:
+            errors.append(
+                _err(
+                    f"[tool.levain.harness] has no key {key!r}."
+                    f" Legal keys: {', '.join(_KEYS)}."
+                )
+            )
+
+    engine = table.get("engine")
+    if engine not in HARNESS_ENGINES:
+        errors.append(
+            _err(
+                f"engine = {engine!r} is not an engine."
+                f" Known: {', '.join(HARNESS_ENGINES)}."
+            )
+        )
+
+    model = table.get("model")
+    if not isinstance(model, str) or not model.strip():
+        errors.append(_err("model must be a non-empty string."))
+
+    effort = table.get("effort")
+    if effort is not None and effort not in EFFORT_LEVELS:
+        errors.append(
+            _err(
+                f"effort = {effort!r} is not an effort level."
+                f" Known: {', '.join(EFFORT_LEVELS)}."
+            )
+        )
+
+    prompt = table.get("prompt")
+    if prompt is not None:
+        if not isinstance(prompt, str) or not prompt.strip():
+            errors.append(
+                _err("prompt must be a path relative to the package.")
+            )
+        elif os.path.isabs(prompt) or ".." in prompt.split(os.sep):
+            errors.append(
+                _err(f"prompt = {prompt!r} must stay inside the package.")
+            )
+        elif not os.path.isfile(os.path.join(recipe_dir, prompt)):
+            errors.append(_err(f"prompt file {prompt!r} not found."))
+
+    tools = table.get("tools")
+    if tools is not None and not _is_str_list(tools):
+        errors.append(_err("tools must be a list of tool names."))
+
+    mcp_servers = table.get("mcp_servers", [])
+    if not _is_str_list(mcp_servers):
+        errors.append(_err("mcp_servers must be a list of server names."))
+        mcp_servers = []
+
+    permission_mode = table.get("permission_mode", DEFAULT_PERMISSION_MODE)
+    if permission_mode not in PERMISSION_MODES:
+        errors.append(
+            _err(
+                f"permission_mode = {permission_mode!r} is not a mode."
+                f" Known: {', '.join(PERMISSION_MODES)}."
+            )
+        )
+
+    variables, field_errors = _state_fields(table.get("state", {}))
+    errors.extend(field_errors)
+
+    errors.extend(
+        check_mcp_names(
+            [
+                NodeAnnotation(
+                    label="Session",
+                    function=str(engine),
+                    args={"mcp_servers": list(mcp_servers)},
+                )
+            ],
+            attached_mcp_names=attached_mcp_names,
+        )
+    )
+    if errors:
+        return errors
+    return HarnessSpec(
+        engine=str(engine),
+        model=str(model).strip(),
+        variables=variables,
+        effort=effort,
+        prompt=prompt,
+        tools=list(tools) if tools is not None else None,
+        mcp_servers=list(mcp_servers),
+        permission_mode=str(permission_mode),
+    )
+
+
+def _is_str_list(value: Any) -> bool:
+    return isinstance(value, list) and all(
+        isinstance(v, str) and v.strip() for v in value
+    )
+
+
+def _state_fields(
+    raw: Any,
+) -> tuple[list[StateField], list[ValidationError]]:
+    fields = [
+        StateField(
+            name=MESSAGES_FIELD,
+            type="list",
+            default=[],
+            reducer="add_messages",
+            description="The conversation.",
+        )
+    ]
+    if not isinstance(raw, dict):
+        return fields, [_err("[tool.levain.harness.state] must be a table.")]
+    errors: list[ValidationError] = []
+    for name, entry in raw.items():
+        spec = {"type": entry} if isinstance(entry, str) else entry
+        where = f"state.{name}"
+        if name == MESSAGES_FIELD:
+            errors.append(
+                _err(
+                    f"{where}: `{MESSAGES_FIELD}` is implicit; do not declare it."
+                )
+            )
+            continue
+        if name.startswith("_"):
+            errors.append(
+                _err(
+                    f"{where}: names prefixed with '_' are reserved"
+                    " for platform metadata."
+                )
+            )
+            continue
+        if not isinstance(spec, dict):
+            errors.append(
+                _err(
+                    f"{where}: declare a field as a type name or a table"
+                    f" with keys {', '.join(_FIELD_KEYS)}."
+                )
+            )
+            continue
+        unknown = [k for k in spec if k not in _FIELD_KEYS]
+        if unknown:
+            errors.append(
+                _err(
+                    f"{where}: unknown key(s) {', '.join(unknown)}."
+                    f" Legal: {', '.join(_FIELD_KEYS)}."
+                )
+            )
+            continue
+        vtype = spec.get("type")
+        if vtype not in SPEC_TYPES:
+            errors.append(
+                _err(
+                    f"{where}: type = {vtype!r} is not a state type."
+                    f" Known: {', '.join(SPEC_TYPES)}."
+                )
+            )
+            continue
+        reducer = spec.get("reducer")
+        if reducer is not None and reducer not in REDUCERS:
+            errors.append(
+                _err(
+                    f"{where}: unknown reducer {reducer!r}."
+                    f" Known: {', '.join(sorted(REDUCERS))}."
+                )
+            )
+            continue
+        if vtype == "list" and reducer is None:
+            errors.append(
+                _err(
+                    f"{where}: a list field must declare a reducer"
+                    " (the default last-write-wins drops accumulated items)."
+                )
+            )
+            continue
+        if vtype != "list" and reducer is not None:
+            errors.append(
+                _err(f"{where}: reducer is only valid on list fields.")
+            )
+            continue
+        default = spec.get("default", _DEFAULTS[vtype])
+        if not _default_fits(default, vtype):
+            errors.append(
+                _err(f"{where}: default {default!r} is not a {vtype}.")
+            )
+            continue
+        description = spec.get("description")
+        fields.append(
+            StateField(
+                name=str(name),
+                type=str(vtype),
+                default=default,
+                reducer=reducer,
+                description=(
+                    str(description) if isinstance(description, str) else None
+                ),
+            )
+        )
+    return fields, errors
+
+
+def _default_fits(value: Any, vtype: str) -> bool:
+    if vtype == "int":
+        return isinstance(value, int) and not isinstance(value, bool)
+    return isinstance(value, SPEC_TYPES[vtype])

{levain_cli-0.1.18 → levain_cli-0.1.20}/levain_recipe/mcp.py

@@ -15,7 +15,9 @@ from fastmcp import FastMCP
 from ._format import format_errors, format_success
 from ._java import ensure_jar
 from .codegen import generate_state_module
-from .validate import validate, validate_fast, validate_package
+from .models import ValidatedSpec
+from .validate import validate, validate_fast
+from .validate import validate_recipe as validate_recipe_dir
 
 server = FastMCP("levain-recipe")
 
@@ -48,7 +50,7 @@ def validate_recipe(path: str) -> str:
 
 @server.tool()
 def validate_recipe_package(recipe_dir: str) -> str:
-    """Validate a full recipe package (graph.tla + Python source)."""
+    """Validate a recipe package (a graph with its Python source, or a harness)."""
     if not Path(recipe_dir).is_dir():
         return f"Error: not a directory: {recipe_dir}"
 
@@ -57,7 +59,7 @@ def validate_recipe_package(recipe_dir: str) -> str:
         ensure_jar()
     else:
         note = _NO_JAVA_NOTE
-    result = validate_package(recipe_dir)
+    result = validate_recipe_dir(recipe_dir)
     if isinstance(result, list):
         return note + format_errors(result)
     return note + format_success(result)
@@ -72,9 +74,11 @@ def generate_state(recipe_dir: str) -> str:
 
     if shutil.which("java"):
         ensure_jar()
-    result = validate_package(recipe_dir)
+    result = validate_recipe_dir(recipe_dir)
     if isinstance(result, list):
         return format_errors(result)
+    if not isinstance(result, ValidatedSpec):
+        return "Error: a harness recipe has no Python state module."
 
     src_dir = root / "src" / result.module_name
     if not src_dir.is_dir():

{levain_cli-0.1.18 → levain_cli-0.1.20}/levain_recipe/models.py

@@ -5,6 +5,7 @@ and sandbox modules.  Other modules should import from here
 rather than defining their own copies.
 """
 
+import dataclasses
 from dataclasses import dataclass, field
 from typing import Any
 
@@ -144,3 +145,74 @@ class ValidationError:
     message: str
     line: int | None = None
     counterexample: list[dict[str, Any]] | None = None
+
+
+# Recipe kinds.  A ``graph`` package is a PlusCal spec plus node
+# functions; a ``harness`` package is one engine session with no
+# graph.  Read from ``[tool.levain] kind`` in ``pyproject.toml``.
+RECIPE_KINDS = ("graph", "harness")
+DEFAULT_RECIPE_KIND = "graph"
+
+HARNESS_ENGINES = ("claude_code", "hermes")
+EFFORT_LEVELS = ("low", "medium", "high", "xhigh", "max")
+PERMISSION_MODES = ("default", "acceptEdits", "plan", "bypassPermissions")
+DEFAULT_PERMISSION_MODE = "bypassPermissions"
+
+# The conversation field every harness recipe carries; declared
+# implicitly so the platform's message projection, A2A output and
+# post-run hooks see the same shape as a graph recipe's state.
+MESSAGES_FIELD = "messages"
+
+
+@dataclass(frozen=True)
+class HarnessSpec:
+    """A validated harness recipe: one engine session per platform session.
+
+    ``variables`` holds the declared state fields plus the implicit
+    ``messages`` field.  ``prompt`` is a path relative to the package
+    root; ``tools`` is the engine's permission allowlist (``None``
+    keeps the engine's default toolset).
+    """
+
+    engine: str
+    model: str
+    variables: list[StateField]
+    effort: str | None = None
+    prompt: str | None = None
+    tools: list[str] | None = None
+    mcp_servers: list[str] = field(default_factory=list)
+    permission_mode: str = DEFAULT_PERMISSION_MODE
+
+
+RecipeSpec = ValidatedSpec | HarnessSpec
+
+
+def recipe_kind_of(spec: RecipeSpec) -> str:
+    return "harness" if isinstance(spec, HarnessSpec) else "graph"
+
+
+def graph_payload(spec: ValidatedSpec) -> dict[str, Any]:
+    """The spec in its runtime shape: what the sandbox graph engine builds.
+
+    Plain JSON (the turn params carry it), so the sandbox needs none of
+    this package to run a graph; the spec's source and invariants stay
+    behind, they are the validator's.
+    """
+    return {
+        "variables": [dataclasses.asdict(v) for v in spec.variables],
+        "nodes": [dataclasses.asdict(n) for n in spec.nodes],
+        "routing": [dataclasses.asdict(t) for t in spec.routing],
+        "constants": dict(spec.constants),
+    }
+
+
+def mcp_server_names(spec: RecipeSpec) -> set[str]:
+    """Every MCP server name the recipe declares, whichever its kind."""
+    if isinstance(spec, HarnessSpec):
+        return set(spec.mcp_servers)
+    names: set[str] = set()
+    for node in spec.nodes:
+        servers = node.args.get("mcp_servers")
+        if isinstance(servers, list):
+            names.update(s for s in servers if isinstance(s, str))
+    return names

{levain_cli-0.1.18 → levain_cli-0.1.20}/levain_recipe/user_input.py

@@ -25,7 +25,12 @@ from __future__ import annotations
 from collections.abc import Callable
 from typing import Any, Literal, NotRequired, TypedDict
 
-from .models import INTERRUPT_BUILTIN, StateField, ValidatedSpec
+from .models import (
+    INTERRUPT_BUILTIN,
+    HarnessSpec,
+    RecipeSpec,
+    StateField,
+)
 from .reducers import REDUCERS
 
 # Each kind names a JSON-shape the API knows how to validate and
@@ -75,8 +80,12 @@ class UserInputSchema(TypedDict):
     interrupting: bool
 
 
-def user_input_schema(spec: ValidatedSpec) -> UserInputSchema:
-    """Project a ``ValidatedSpec`` to its user-input schema."""
+def user_input_schema(spec: RecipeSpec) -> UserInputSchema:
+    """Project a recipe spec to its user-input schema.
+
+    A harness recipe is a conversation: every turn ends waiting for
+    the next message, so it is always ``interrupting``.
+    """
     fields: dict[str, FieldSchema] = {}
     for var in spec.variables:
         if var.name.startswith("_"):
@@ -85,7 +94,7 @@ def user_input_schema(spec: ValidatedSpec) -> UserInputSchema:
         if descr is None:
             continue
         fields[var.name] = descr
-    interrupting = any(
+    interrupting = isinstance(spec, HarnessSpec) or any(
         node.function == INTERRUPT_BUILTIN for node in spec.nodes
     )
     return {"fields": fields, "interrupting": interrupting}

{levain_cli-0.1.18 → levain_cli-0.1.20}/levain_recipe/validate.py

@@ -14,6 +14,7 @@ from typing import cast
 
 from ._java import resolve_jar
 from .graph import check_graph
+from .harness import load_harness_spec, recipe_kind
 from .integrations_check import check_mcp_names
 from .models import (
     CALL_AGENT_BUILTIN,
@@ -21,6 +22,7 @@ from .models import (
     INTERRUPTIBLE_CLASSES,
     INTERRUPTIBLE_KEY,
     NodeAnnotation,
+    RecipeSpec,
     RoutingTable,
     StateField,
     ValidatedSpec,
@@ -383,6 +385,27 @@ def validate_package(
     return result
 
 
+def validate_recipe(
+    recipe_dir: str,
+    *,
+    attached_mcp_names: list[str] | None = None,
+) -> RecipeSpec | list[ValidationError]:
+    """Validate a recipe package of either kind.
+
+    The one entry point callers should use: it reads the package's
+    ``[tool.levain] kind`` and runs the PlusCal pipeline for a graph
+    or the harness loader for a harness recipe.
+    """
+    kind = recipe_kind(recipe_dir)
+    if isinstance(kind, list):
+        return kind
+    if kind == "harness":
+        return load_harness_spec(
+            recipe_dir, attached_mcp_names=attached_mcp_names
+        )
+    return validate_package(recipe_dir, attached_mcp_names=attached_mcp_names)
+
+
 def _require_tlc() -> bool:
     """Whether deployed services must run full TLC validation.
 

{levain_cli-0.1.18 → levain_cli-0.1.20}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "levain-cli"
-version = "0.1.18"
+version = "0.1.20"
 description = "Levain recipe toolchain: PlusCal validator, TLC model checking, and GraphState codegen for agent recipes"
 readme = "README.md"
 license = "Apache-2.0"