readyagentsdev 0.8.2__py3-none-any.whl

readyagents/cli.py

@@ -0,0 +1,1050 @@
+"""Typer CLI for ReadyAgents Core."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any, NoReturn
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+from rich.panel import Panel
+from rich.table import Table
+
+from readyagents import __version__
+from readyagents.config import DEFAULT_MCP_TOKEN_ENV
+from readyagents.errors import ApprovalRequired, MCPError, ReadyAgentsError
+from readyagents.logging import configure_logging
+from readyagents.packs.loader import collect_pack_specs, discover_packs, load_local_packs
+from readyagents.scaffold import TEMPLATES, create_project
+from readyagents.testing.eval import load_eval_suite, run_eval
+from readyagents.workflow.runner import (
+    load_workflow,
+    replay_run,
+    resume_run,
+    run_workflow_file,
+)
+from readyagents.workflow.state import (
+    RunState,
+    build_decisions,
+    delete_run,
+    gc_runs,
+    list_runs,
+    load_decision_file,
+    load_run,
+    parse_input_pairs,
+)
+
+app = typer.Typer(
+    name="readyagents",
+    help="ReadyAgents Core — Agent Workflow engine + MCP Toolkit (BYOK).",
+    no_args_is_help=True,
+    add_completion=False,
+)
+mcp_app = typer.Typer(help="Run ReadyAgents as an MCP server.", no_args_is_help=True)
+runs_app = typer.Typer(help="Inspect persisted workflow runs.", no_args_is_help=True)
+app.add_typer(mcp_app, name="mcp")
+app.add_typer(runs_app, name="runs")
+
+console = Console()
+err_console = Console(stderr=True)
+
+_WORKFLOW_ARG = typer.Argument(
+    ...,
+    help="Workflow YAML or JSON file.",
+)
+_PACK_HELP = (
+    "Local pack .py to load (repeatable). Confined to the workspace. Env: READYAGENTS_PACK."
+)
+
+
+def _version_flag(value: bool) -> None:
+    if value:
+        console.print(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: bool | None = typer.Option(
+        None,
+        "--version",
+        callback=_version_flag,
+        is_eager=True,
+        help="Print version and exit.",
+    ),
+    log_level: str = typer.Option(
+        "INFO",
+        "--log-level",
+        help="DEBUG, INFO, WARNING, or ERROR.",
+        envvar="READYAGENTS_LOG_LEVEL",
+    ),
+    log_format: str = typer.Option(
+        "text",
+        "--log-format",
+        help="text or json (machine-parseable events with run/node).",
+        envvar="READYAGENTS_LOG_FORMAT",
+    ),
+) -> None:
+    configure_logging(log_level, fmt=log_format)
+
+
+@app.command()
+def version() -> None:
+    """Print the ReadyAgents version."""
+    console.print(__version__)
+
+
+@app.command("init")
+def init_cmd(
+    dest: Path = typer.Option(Path(".env"), "--dest", help="Path to write the env file."),
+) -> None:
+    """Create a local `.env` from `.env.example` if it does not exist."""
+    example = Path(".env.example")
+    if dest.exists():
+        console.print(f"[yellow]{dest} already exists[/yellow] — left unchanged.")
+        _print_next_steps()
+        return
+    if example.is_file():
+        dest.write_text(example.read_text(encoding="utf-8"), encoding="utf-8")
+    else:
+        dest.write_text(_ENV_TEMPLATE, encoding="utf-8")
+    console.print(f"[green]Wrote {dest}[/green] — then the keyless smoke:")
+    _print_next_steps()
+
+
+def _print_next_steps() -> None:
+    console.print(
+        Panel(
+            "[bold]Next steps[/bold]\n"
+            "1. Smoke test (no keys):  "
+            "[cyan]readyagents run examples/calc_pipeline.yaml[/cyan]\n"
+            "2. Scaffold:  [cyan]readyagents new my-flow[/cyan]\n"
+            "3. Edit `.env` and set OPENAI_API_KEY and/or ANTHROPIC_API_KEY\n"
+            "4. With keys:  [cyan]readyagents run examples/research_brief.yaml "
+            "--input topic=your-topic[/cyan]\n"
+            "See docs/getting-started.md",
+            title="ReadyAgents",
+        )
+    )
+
+
+@app.command("new")
+def new_cmd(
+    name: str = typer.Argument("starter", help="Project / workflow name."),
+    dest: Path | None = typer.Option(
+        None,
+        "--dest",
+        help="Directory to write (defaults to ./<name>).",
+    ),
+    template: str = typer.Option(
+        "pipeline",
+        "--template",
+        "-t",
+        help=f"Starter kind: {', '.join(TEMPLATES)}.",
+    ),
+) -> None:
+    """Write a starter workflow, README, and `.env.example`."""
+    target = dest if dest is not None else Path(name)
+    try:
+        written = create_project(target, name=name, template=template)
+    except ReadyAgentsError as exc:
+        _fail(exc)
+        return
+    console.print(f"[green]Created {target.resolve()}[/green]  template={template}")
+    for path in written:
+        console.print(f"  {path.name}")
+    wf = target / "workflow.yaml"
+    if template in {"basic", "pipeline", "foreach"}:
+        console.print(f"Run: [cyan]readyagents run {wf}[/cyan]")
+    elif template == "agent-tools":
+        console.print(f"Run: [cyan]readyagents run {wf} --dry-run[/cyan]")
+    elif template == "research":
+        console.print(f"Run: [cyan]readyagents run {wf} --approve publish[/cyan]")
+    else:
+        console.print(f"Run: [cyan]readyagents run {wf} --approve gate[/cyan]")
+
+
+@app.command()
+def validate(
+    path: Path = _WORKFLOW_ARG,
+    as_json: bool = typer.Option(
+        False,
+        "--json",
+        help="Print the workflow summary as JSON on stdout (no tables).",
+    ),
+) -> None:
+    """Schema-validate a workflow file without executing it."""
+    try:
+        workflow = load_workflow(path)
+    except ReadyAgentsError as exc:
+        if as_json:
+            _print_json(
+                _json_envelope(
+                    "validate",
+                    ok=False,
+                    error=type(exc).__name__,
+                    message=str(exc),
+                )
+            )
+            raise typer.Exit(code=1) from exc
+        _fail(exc)
+    nodes = [
+        {
+            "id": node.id,
+            "type": str(node.type),
+            "next": node.next,
+            "then": node.then,
+            "else": node.else_,
+        }
+        for node in workflow.nodes
+    ]
+    if as_json:
+        _print_json(
+            _json_envelope(
+                "validate",
+                ok=True,
+                name=workflow.name,
+                start=workflow.start,
+                node_count=len(workflow.nodes),
+                nodes=nodes,
+            )
+        )
+        return
+    table = Table(title=f"Valid: {workflow.name}")
+    table.add_column("Node")
+    table.add_column("Type")
+    table.add_column("Next")
+    for node in workflow.nodes:
+        table.add_row(node.id, str(node.type), _node_routing(node))
+    console.print(table)
+    console.print(f"[green]OK[/green] — {len(workflow.nodes)} node(s), start={workflow.start}")
+
+
+@app.command("eval")
+def eval_cmd(
+    path: Path = typer.Argument(
+        ...,
+        help="Eval suite YAML or JSON file.",
+    ),
+    as_json: bool = typer.Option(
+        False,
+        "--json",
+        help="Print the eval report as JSON on stdout (no tables).",
+    ),
+) -> None:
+    """Score fixture workflows from a suite file (no network, no API keys)."""
+    try:
+        cases = load_eval_suite(path)
+        report = run_eval(cases)
+    except ReadyAgentsError as extra:
+        if as_json:
+            _print_json(
+                _json_envelope(
+                    "eval",
+                    ok=False,
+                    error=type(extra).__name__,
+                    message=str(extra),
+                )
+            )
+            raise typer.Exit(code=1) from extra
+        _fail(extra)
+    if as_json:
+        _print_json(
+            _json_envelope(
+                "eval",
+                ok=report.ok,
+                passed=report.passed,
+                failed=report.failed,
+                results=[
+                    {"name": row.name, "passed": row.passed, "reason": row.reason}
+                    for row in report.results
+                ],
+            )
+        )
+    else:
+        for row in report.results:
+            if row.passed:
+                console.print(f"[green]PASS[/green] {escape(row.name)}")
+            else:
+                console.print(f"[red]FAIL[/red] {escape(row.name)}: {escape(row.reason)}")
+        console.print(f"passed={report.passed} failed={report.failed}")
+    if not report.ok:
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def run(
+    path: Path = _WORKFLOW_ARG,
+    inputs: list[str] = typer.Option(
+        [],
+        "--input",
+        "-i",
+        help="Input as KEY=VALUE (repeatable).",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Walk the graph without calling an LLM, http_get, or write_file.",
+    ),
+    no_persist: bool = typer.Option(False, "--no-persist", help="Do not write a run record."),
+    approve: list[str] = typer.Option(
+        [],
+        "--approve",
+        help="Approve an approval node by id (repeatable).",
+    ),
+    reject: list[str] = typer.Option(
+        [],
+        "--reject",
+        help="Reject an approval node by id (repeatable).",
+    ),
+    resume: str | None = typer.Option(
+        None,
+        "--resume",
+        help="Resume this run id instead of starting a new run.",
+    ),
+    as_json: bool = typer.Option(
+        False,
+        "--json",
+        help="Print the run record as JSON on stdout (no tables).",
+    ),
+    log_level: str | None = typer.Option(
+        None,
+        "--log-level",
+        help="DEBUG, INFO, WARNING, or ERROR (same as the root flag).",
+    ),
+    log_format: str | None = typer.Option(
+        None,
+        "--log-format",
+        help="text or json (same as the root flag).",
+    ),
+    decision_file: Path | None = typer.Option(
+        None,
+        "--decision-file",
+        help="JSON file injecting approval decisions (not only --approve flags).",
+    ),
+    actor: str | None = typer.Option(
+        None,
+        "--actor",
+        help="Actor id for RBAC hooks (env: READYAGENTS_ACTOR).",
+        envvar="READYAGENTS_ACTOR",
+    ),
+    no_cache: bool = typer.Option(
+        False,
+        "--no-cache",
+        help="Skip the local LLM response cache for this run.",
+    ),
+    pack: list[str] = typer.Option([], "--pack", help=_PACK_HELP),
+) -> None:
+    """Execute a workflow."""
+    if log_level or log_format:
+        configure_logging(log_level or "INFO", **({"fmt": log_format} if log_format else {}))
+    persist = not no_persist
+    try:
+        parsed = parse_input_pairs(inputs)
+        decisions = build_decisions(approve, reject)
+        extra_packs = _load_extra_packs(pack)
+        if resume:
+            state = resume_run(
+                resume,
+                path=path,
+                inputs=parsed or None,
+                dry_run=dry_run,
+                persist=persist,
+                extra_packs=extra_packs,
+                decisions=decisions,
+                decision_file=decision_file,
+                actor=actor,
+                no_cache=no_cache,
+            )
+        else:
+            state = run_workflow_file(
+                path,
+                inputs=parsed,
+                dry_run=dry_run,
+                persist=persist,
+                extra_packs=extra_packs,
+                decisions=decisions,
+                decision_file=decision_file,
+                actor=actor,
+                no_cache=no_cache,
+            )
+    except KeyboardInterrupt:
+        if as_json:
+            _print_json(_json_envelope("run", ok=False, error="cancelled", status="cancelled"))
+        else:
+            err_console.print("[yellow]cancelled[/yellow]")
+        raise typer.Exit(code=1) from None
+    except ReadyAgentsError as extra:
+        _emit_run_exception(extra, as_json=as_json, persist=persist, command="run")
+    _emit_run(state, as_json=as_json, command="run")
+
+
+@app.command("resume")
+def resume_cmd(
+    run_id: str = typer.Argument(..., help="Run id (or unique prefix)."),
+    workflow: Path | None = typer.Option(
+        None,
+        "--workflow",
+        help="Workflow file (defaults to the path stored on the run).",
+    ),
+    inputs: list[str] = typer.Option(
+        [],
+        "--input",
+        "-i",
+        help="Override stored inputs as KEY=VALUE (repeatable).",
+    ),
+    dry_run: bool = typer.Option(False, "--dry-run"),
+    no_persist: bool = typer.Option(False, "--no-persist"),
+    approve: list[str] = typer.Option([], "--approve"),
+    reject: list[str] = typer.Option([], "--reject"),
+    as_json: bool = typer.Option(
+        False,
+        "--json",
+        help="Print the run record as JSON on stdout (no tables).",
+    ),
+    decision_file: Path | None = typer.Option(
+        None,
+        "--decision-file",
+        help="JSON file injecting approval decisions.",
+    ),
+    actor: str | None = typer.Option(
+        None,
+        "--actor",
+        envvar="READYAGENTS_ACTOR",
+    ),
+    no_cache: bool = typer.Option(False, "--no-cache"),
+    pack: list[str] = typer.Option([], "--pack", help=_PACK_HELP),
+) -> None:
+    """Resume a paused or failed run from the last successful node."""
+    persist = not no_persist
+    try:
+        parsed = parse_input_pairs(inputs)
+        state = resume_run(
+            run_id,
+            path=workflow,
+            inputs=parsed or None,
+            dry_run=dry_run,
+            persist=persist,
+            extra_packs=_load_extra_packs(pack),
+            decisions=build_decisions(approve, reject),
+            decision_file=decision_file,
+            actor=actor,
+            no_cache=no_cache,
+        )
+    except KeyboardInterrupt:
+        if as_json:
+            _print_json(_json_envelope("resume", ok=False, error="cancelled", status="cancelled"))
+        else:
+            err_console.print("[yellow]cancelled[/yellow]")
+        raise typer.Exit(code=1) from None
+    except ReadyAgentsError as extra:
+        _emit_run_exception(extra, as_json=as_json, persist=persist, command="resume")
+    _emit_run(state, as_json=as_json, command="resume")
+
+
+@app.command("decide")
+def decide_cmd(
+    run_id: str = typer.Argument(..., help="Paused run id (or unique prefix)."),
+    decision_file: Path | None = typer.Option(
+        None,
+        "--file",
+        "--decision-file",
+        help='JSON payload: {"node": "approve"} or {"node_id", "decision"}.',
+    ),
+    node: str | None = typer.Option(None, "--node", help="Approval node id."),
+    decision: str | None = typer.Option(
+        None,
+        "--decision",
+        help="approve or reject (requires --node).",
+    ),
+    actor: str | None = typer.Option(None, "--actor", envvar="READYAGENTS_ACTOR"),
+    as_json: bool = typer.Option(False, "--json"),
+    no_persist: bool = typer.Option(False, "--no-persist"),
+    pack: list[str] = typer.Option([], "--pack", help=_PACK_HELP),
+) -> None:
+    """Inject an external approval decision into a paused run, then resume.
+
+    This is the core side of a webhook/pack: no always-on HTTP listener.
+    A pack can receive the webhook and call this (or write --file).
+    """
+    from readyagents.errors import ConfigError
+
+    persist = not no_persist
+    try:
+        decisions: dict[str, str] = {}
+        if decision_file is not None:
+            decisions.update(load_decision_file(decision_file))
+        if node:
+            if not decision:
+                raise ConfigError("--decision is required with --node")
+            decisions[node] = decision.strip().lower()
+        if not decisions:
+            raise ConfigError("Pass --file or --node plus --decision")
+        state = resume_run(
+            run_id,
+            persist=persist,
+            extra_packs=_load_extra_packs(pack),
+            decisions=decisions,
+            actor=actor,
+        )
+    except ReadyAgentsError as exc:
+        _emit_run_exception(exc, as_json=as_json, persist=persist, command="decide")
+    _emit_run(state, as_json=as_json, command="decide")
+
+
+@app.command("packs")
+def packs_cmd(
+    as_json: bool = typer.Option(False, "--json", help="Print JSON instead of a table."),
+    pack: list[str] = typer.Option([], "--pack", help=_PACK_HELP),
+) -> None:
+    """List installed ReadyAgents packs (entry point group readyagents.packs)."""
+    try:
+        found = list(discover_packs())
+        found.extend(_load_extra_packs(pack))
+    except ReadyAgentsError as exc:
+        if as_json:
+            _print_json(
+                _json_envelope(
+                    "packs",
+                    ok=False,
+                    error=type(exc).__name__,
+                    message=str(exc),
+                )
+            )
+            raise typer.Exit(code=1) from exc
+        _fail(exc)
+        return
+    if as_json:
+        _print_json(
+            _json_envelope(
+                "packs",
+                ok=True,
+                packs=[{"name": pack.name, "version": pack.version} for pack in found],
+            )
+        )
+        return
+    if not found:
+        console.print("No packs installed. Core runs without any packs.")
+        console.print("readyagents packs --pack examples/packs/connector_pack.py")
+        return
+    table = Table(title="Installed packs")
+    table.add_column("Name")
+    table.add_column("Version")
+    for pack in found:
+        table.add_row(pack.name, pack.version)
+    console.print(table)
+
+
+@runs_app.command("list")
+def runs_list(
+    as_json: bool = typer.Option(False, "--json", help="Print JSON instead of a table."),
+    status: str | None = typer.Option(
+        None, "--status", help="Filter: running, paused, failed, succeeded."
+    ),
+    workflow: str | None = typer.Option(None, "--workflow", help="Filter by workflow name."),
+    limit: int = typer.Option(0, "--limit", help="Max rows (0 = all)."),
+) -> None:
+    """List persisted runs (newest first)."""
+    from readyagents.config import get_settings
+
+    settings = get_settings()
+    found = list_runs(
+        settings.runs_dir(),
+        status=status,
+        workflow=workflow,
+        limit=limit,
+    )
+    if as_json:
+        payload = [
+            {
+                "run_id": s.run_id,
+                "workflow": s.workflow_name,
+                "status": s.status,
+                "started_at": s.started_at,
+                "pending_node": s.pending_node,
+                "nodes": [r.node_id for r in s.results],
+            }
+            for s in found
+        ]
+        _print_json(payload)
+        return
+    if not found:
+        console.print(f"No runs in {settings.runs_dir()}")
+        return
+    console.print(f"Runs in {settings.runs_dir()}")
+    for state in found:
+        nodes = ",".join(r.node_id for r in state.results) or "-"
+        console.print(
+            f"run_id: {state.run_id}  workflow: {state.workflow_name}  "
+            f"status: {state.status}  started: {state.started_at}  nodes: {nodes}"
+        )
+
+
+@runs_app.command("show")
+def runs_show(
+    run_id: str = typer.Argument(..., help="Run id (or unique prefix)."),
+    as_json: bool = typer.Option(False, "--json", help="Print the stored run record as JSON."),
+) -> None:
+    """Show a run record and its node timeline."""
+    _show_run(run_id, as_json=as_json)
+
+
+@runs_app.command("inspect")
+def runs_inspect(
+    run_id: str = typer.Argument(..., help="Run id (or unique prefix)."),
+    as_json: bool = typer.Option(False, "--json", help="Print the stored run record as JSON."),
+) -> None:
+    """Alias for `runs show` — inspect stored state and the node timeline."""
+    _show_run(run_id, as_json=as_json)
+
+
+@runs_app.command("report")
+def runs_report(
+    run_id: str = typer.Argument(..., help="Run id (or unique prefix)."),
+    dest: Path | None = typer.Option(
+        None,
+        "--out",
+        "-o",
+        help="HTML file to write (default: <run_id>.html in cwd).",
+    ),
+) -> None:
+    """Write a local HTML summary of a persisted run."""
+    from readyagents.config import get_settings
+    from readyagents.report import write_html_report
+
+    try:
+        state = load_run(get_settings().runs_dir(), run_id)
+        path = dest or Path(f"{state.run_id}.html")
+        written = write_html_report(state, path)
+    except ReadyAgentsError as exc:
+        _fail(exc)
+        return
+    console.print(f"[green]Wrote {written}[/green]  open it in a browser.")
+
+
+@runs_app.command("replay")
+def runs_replay(
+    run_id: str = typer.Argument(..., help="Run id (or unique prefix)."),
+    dry_run: bool = typer.Option(False, "--dry-run"),
+    no_persist: bool = typer.Option(False, "--no-persist"),
+    approve: list[str] = typer.Option([], "--approve"),
+    reject: list[str] = typer.Option([], "--reject"),
+    as_json: bool = typer.Option(
+        False,
+        "--json",
+        help="Print the run record as JSON on stdout (no tables).",
+    ),
+    decision_file: Path | None = typer.Option(None, "--decision-file"),
+    actor: str | None = typer.Option(None, "--actor", envvar="READYAGENTS_ACTOR"),
+    no_cache: bool = typer.Option(False, "--no-cache"),
+    pack: list[str] = typer.Option([], "--pack", help=_PACK_HELP),
+) -> None:
+    """Start a new run using the stored workflow path and inputs."""
+    persist = not no_persist
+    try:
+        state = replay_run(
+            run_id,
+            dry_run=dry_run,
+            persist=persist,
+            extra_packs=_load_extra_packs(pack),
+            decisions=build_decisions(approve, reject),
+            decision_file=decision_file,
+            actor=actor,
+            no_cache=no_cache,
+        )
+    except ReadyAgentsError as exc:
+        _emit_run_exception(exc, as_json=as_json, persist=persist, command="replay")
+    _emit_run(state, as_json=as_json, command="replay")
+
+
+@runs_app.command("delete")
+def runs_delete(
+    run_id: str = typer.Argument(..., help="Run id (or unique prefix)."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Do not prompt."),
+) -> None:
+    """Delete one persisted run JSON file."""
+    from readyagents.config import get_settings
+
+    settings = get_settings()
+    try:
+        state = load_run(settings.runs_dir(), run_id)
+        if not yes:
+            console.print(f"Delete run {state.run_id} ({state.status})? Pass --yes to confirm.")
+            raise typer.Exit(code=1)
+        path = delete_run(settings.runs_dir(), run_id)
+    except ReadyAgentsError as extra:
+        _fail(extra)
+        return
+    console.print(f"[green]Deleted[/green] {path}")
+
+
+@runs_app.command("gc")
+def runs_gc_cmd(
+    status: list[str] = typer.Option(
+        ["succeeded", "failed", "cancelled"],
+        "--status",
+        help="Statuses to delete (repeatable).",
+    ),
+    keep: int = typer.Option(0, "--keep", help="Keep this many newest matching runs."),
+    include_paused: bool = typer.Option(
+        False,
+        "--include-paused",
+        help="Also delete paused runs (off by default).",
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Do not prompt."),
+) -> None:
+    """Delete old succeeded/failed/cancelled runs. Paused runs are kept unless forced."""
+    from readyagents.config import get_settings
+
+    settings = get_settings()
+    if not yes:
+        console.print("Pass --yes to garbage-collect matching run files.")
+        raise typer.Exit(code=1)
+    try:
+        deleted = gc_runs(
+            settings.runs_dir(),
+            statuses=status,
+            include_paused=include_paused,
+            keep=keep,
+        )
+    except ReadyAgentsError as extra:
+        _fail(extra)
+        return
+    console.print(f"[green]Deleted {len(deleted)} run(s)[/green]")
+    for rid in deleted:
+        console.print(f"  {rid}")
+
+
+@mcp_app.command("serve")
+def mcp_serve(
+    ctx: typer.Context,
+    transport: str = typer.Option(
+        "stdio",
+        "--transport",
+        help="stdio (default) or streamable-http.",
+    ),
+    host: str = typer.Option(
+        "127.0.0.1",
+        "--host",
+        help="Bind host. HTTP only. v0.9 rejects non-loopback binds.",
+        envvar="READYAGENTS_MCP_HTTP_HOST",
+    ),
+    port: int = typer.Option(
+        8765,
+        "--port",
+        min=1,
+        max=65535,
+        help="Bind port. HTTP only.",
+        envvar="READYAGENTS_MCP_HTTP_PORT",
+    ),
+    auth: str = typer.Option(
+        "token",
+        "--auth",
+        help="token (default) or none. none is loopback-only and warns.",
+    ),
+    token_env: str = typer.Option(
+        DEFAULT_MCP_TOKEN_ENV,
+        "--token-env",
+        help="Env var holding the bearer token. HTTP only.",
+    ),
+    max_concurrent_runs: int = typer.Option(
+        4,
+        "--max-concurrent-runs",
+        help="In-process executor cap. HTTP only.",
+        envvar="READYAGENTS_MCP_MAX_CONCURRENT_RUNS",
+        min=1,
+    ),
+    max_pending_runs: int = typer.Option(
+        32,
+        "--max-pending-runs",
+        help="Pending-run queue cap. HTTP only.",
+        envvar="READYAGENTS_MCP_MAX_PENDING_RUNS",
+        min=1,
+    ),
+) -> None:
+    """Expose builtin tools (and run_workflow) over MCP stdio or Streamable HTTP."""
+    mode = (transport or "stdio").strip().lower()
+    http_flags = (
+        "--host",
+        "--port",
+        "--auth",
+        "--token-env",
+        "--max-concurrent-runs",
+        "--max-pending-runs",
+    )
+    http_params = (
+        "host",
+        "port",
+        "auth",
+        "token_env",
+        "max_concurrent_runs",
+        "max_pending_runs",
+    )
+    if mode == "stdio":
+        from_argv = any(
+            arg == flag or arg.startswith(f"{flag}=") for arg in sys.argv for flag in http_flags
+        )
+        from_cli = any(
+            getattr(ctx.get_parameter_source(name), "name", None) == "COMMANDLINE"
+            for name in http_params
+        )
+        passed = from_argv or from_cli
+        if passed:
+            _fail(
+                MCPError(
+                    "HTTP flags (--host, --port, --auth, --token-env, "
+                    "--max-concurrent-runs, --max-pending-runs) are only valid "
+                    "with --transport streamable-http"
+                )
+            )
+        try:
+            from readyagents.mcp.server import serve_stdio
+
+            serve_stdio()
+        except ReadyAgentsError as exc:
+            _fail(exc)
+        return
+    if mode != "streamable-http":
+        _fail(MCPError(f"Unknown --transport '{transport}'. Use stdio or streamable-http."))
+    try:
+        from readyagents.mcp.http import serve_streamable_http
+
+        serve_streamable_http(
+            host=host,
+            port=port,
+            auth_mode=auth,
+            token_env=token_env,
+            max_concurrent_runs=max_concurrent_runs,
+            max_pending_runs=max_pending_runs,
+        )
+    except ReadyAgentsError as exc:
+        _fail(exc)
+
+
+def _show_run(run_id: str, *, as_json: bool = False) -> None:
+    from readyagents.config import get_settings
+
+    try:
+        state = load_run(get_settings().runs_dir(), run_id)
+    except ReadyAgentsError as exc:
+        if as_json:
+            _print_json(
+                _json_envelope(
+                    "runs show",
+                    ok=False,
+                    error=type(exc).__name__,
+                    message=str(exc),
+                    run_id=run_id,
+                )
+            )
+            raise typer.Exit(code=1) from exc
+        _fail(exc)
+        return
+    if as_json:
+        _print_json(_json_envelope("runs show", ok=True, **state.to_record()))
+        return
+    console.print(f"run_id: {state.run_id}")
+    console.print(f"workflow: {state.workflow_name}")
+    console.print(f"status: {state.status}")
+    if state.pending_node:
+        console.print(f"pending_node: {state.pending_node}")
+    if state.pending:
+        prompt = state.pending.get("prompt")
+        if prompt:
+            console.print(Panel(escape(str(prompt)), title="Pending prompt"))
+        resume_hint = state.pending.get("resume")
+        if resume_hint:
+            console.print(f"Resume: [cyan]{escape(str(resume_hint))}[/cyan]")
+    _print_usage(state)
+    _print_run(state)
+    if state.output_keys:
+        console.print(Panel(escape(_preview(state.output_keys, limit=2000)), title="Outputs"))
+    if state.inputs:
+        console.print(Panel(escape(_preview(state.inputs, limit=2000)), title="Inputs"))
+
+
+def _load_extra_packs(pack_flags: list[str]) -> list[Any]:
+    """Load --pack / READYAGENTS_PACK modules confined to the workspace."""
+    from readyagents.config import get_settings
+
+    specs = collect_pack_specs(pack_flags)
+    if not specs:
+        return []
+    return load_local_packs(specs, root=get_settings().workspace_path())
+
+
+def _print_json(payload: object) -> None:
+    """Write JSON to stdout without Rich markup (values may contain `[...]`)."""
+    typer.echo(json.dumps(payload, indent=2, ensure_ascii=False))
+
+
+def _json_envelope(command: str, *, ok: bool, **fields: Any) -> dict[str, Any]:
+    """Additive JSON envelope: existing keys stay, ok/command always win."""
+    payload = dict(fields)
+    payload["ok"] = ok
+    payload["command"] = command
+    return payload
+
+
+def _node_routing(node: Any) -> str:
+    """Compact then/else/next for the validate table (else was previously dropped)."""
+    bits: list[str] = []
+    if node.then:
+        bits.append(f"then:{node.then}")
+    if node.else_:
+        bits.append(f"else:{node.else_}")
+    if node.next:
+        bits.append(node.next if not bits else f"next:{node.next}")
+    return " ".join(bits)
+
+
+def _state_from_exc(exc: BaseException) -> RunState | None:
+    state = getattr(exc, "state", None)
+    return state if isinstance(state, RunState) else None
+
+
+def _emit_run(state: RunState, *, as_json: bool, command: str = "run") -> None:
+    if as_json:
+        _print_json(
+            _json_envelope(
+                command,
+                ok=state.status == "succeeded",
+                **state.to_record(),
+            )
+        )
+    else:
+        _print_run(state)
+        if state.status == "succeeded":
+            console.print("[green]succeeded[/green]")
+            console.print(f"run_id: {state.run_id}")
+            _print_usage(state)
+            if state.output_keys:
+                console.print(
+                    Panel(escape(_preview(state.output_keys, limit=2000)), title="Outputs")
+                )
+        else:
+            console.print(f"[red]{state.status}[/red]")
+            console.print(f"run_id: {state.run_id}")
+    if state.status != "succeeded":
+        raise typer.Exit(code=1)
+
+
+def _emit_run_exception(
+    exc: ReadyAgentsError, *, as_json: bool, persist: bool, command: str = "run"
+) -> NoReturn:
+    """Print a paused or failed run (JSON or tables) and exit. Never returns."""
+    if isinstance(exc, ApprovalRequired):
+        state = _state_from_exc(exc)
+        if as_json:
+            payload: dict[str, Any] = {
+                "error": type(exc).__name__,
+                "message": str(exc),
+                "run_id": exc.run_id,
+                "node_id": exc.node_id,
+                "prompt": exc.prompt,
+                "status": "paused",
+            }
+            if state is not None:
+                payload["run"] = state.to_record()
+            _print_json(_json_envelope(command, ok=False, **payload))
+        else:
+            _print_paused(exc)
+        raise typer.Exit(code=2) from exc
+
+    state = _state_from_exc(exc)
+    run_id = getattr(exc, "run_id", None) or (state.run_id if state is not None else None)
+    if as_json:
+        payload = {
+            "error": type(exc).__name__,
+            "message": str(exc),
+            "run_id": run_id,
+            "status": state.status if state is not None else "failed",
+        }
+        if state is not None:
+            payload["run"] = state.to_record()
+        _print_json(_json_envelope(command, ok=False, **payload))
+        raise typer.Exit(code=1) from exc
+
+    if state is not None:
+        _print_run(state)
+        err_console.print(f"[red]{type(exc).__name__}:[/red] {exc}")
+        console.print(f"run_id: {state.run_id}  status: {state.status}")
+        if persist:
+            cmd = f"readyagents resume {state.run_id}"
+            pending = state.pending_node
+            if pending:
+                console.print(
+                    f"Resume: [cyan]{cmd}[/cyan]  (retry node [bold]{escape(pending)}[/bold])"
+                )
+            else:
+                console.print(f"Resume: [cyan]{cmd}[/cyan]")
+        raise typer.Exit(code=1) from exc
+
+    _fail(exc)
+
+
+def _print_usage(state: RunState) -> None:
+    if not state.usage:
+        return
+    parts = [f"{k}={v}" for k, v in state.usage.items()]
+    micros = state.usage.get("cost_micros")
+    if micros:
+        parts.append(f"cost_usd={micros / 1_000_000:.6f}")
+    console.print("usage: " + " ".join(parts))
+
+
+def _print_run(state: RunState) -> None:
+    table = Table(title=f"Run {state.run_id} — {state.status}")
+    table.add_column("Node")
+    table.add_column("Type")
+    table.add_column("Status")
+    table.add_column("Output", overflow="fold")
+    for result in state.results:
+        preview = result.error or _preview(result.output)
+        if result.tool_rounds:
+            names = ",".join(str(row.get("name") or "?") for row in result.tool_rounds)
+            preview = f"{preview}  [tools:{names}]"
+        table.add_row(result.node_id, result.type, result.status, escape(preview))
+    console.print(table)
+
+
+def _print_paused(exc: ApprovalRequired) -> None:
+    if exc.state is not None and isinstance(exc.state, RunState):
+        _print_run(exc.state)
+    err_console.print(f"[yellow]{type(exc).__name__}:[/yellow] {exc}")
+    if exc.prompt:
+        console.print(Panel(escape(exc.prompt), title=f"Approval: {exc.node_id}"))
+    console.print(f"Resume: [cyan]readyagents resume {exc.run_id} --approve {exc.node_id}[/cyan]")
+
+
+def _preview(value: object, limit: int = 160) -> str:
+    text = value if isinstance(value, str) else repr(value)
+    text = text.replace("\n", " ")
+    if len(text) > limit:
+        return text[: limit - 1] + "…"
+    return text
+
+
+def _fail(exc: BaseException) -> NoReturn:
+    err_console.print(f"[red]{type(exc).__name__}:[/red] {exc}")
+    raise typer.Exit(code=1) from exc
+
+
+_ENV_TEMPLATE = """# ReadyAgents BYOK — fill in your keys. Never commit real keys.
+
+READYAGENTS_DEFAULT_MODEL=openai:gpt-4o-mini
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+# READYAGENTS_ALLOW_HTTP=0
+"""
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()