bog-agents-cli 0.9.2__tar.gz → 0.9.4__tar.gz

{bog_agents_cli-0.9.2 → bog_agents_cli-0.9.4}/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.9.4](https://github.com/bogware/bog-agents/compare/bog-agents-cli==0.9.3...bog-agents-cli==0.9.4) (2026-06-08)
+
+
+### Features
+
+* **sdk,cli:** deepagents parity, headless driving, provider resilience ([#91](https://github.com/bogware/bog-agents/issues/91)) ([165c5cb](https://github.com/bogware/bog-agents/commit/165c5cbc17a28fac8e15026914dfd7b0da3b02f2))
+
+## [0.9.3](https://github.com/bogware/bog-agents/compare/bog-agents-cli==0.9.2...bog-agents-cli==0.9.3) (2026-05-23)
+
+
+* **bog-agents-cli:** Synchronize bog-agents-monorepo versions
+
 ## [0.9.2](https://github.com/bogware/bog-agents/compare/bog-agents-cli==0.9.1...bog-agents-cli==0.9.2) (2026-05-22)
 
 

{bog_agents_cli-0.9.2 → bog_agents_cli-0.9.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bog-agents-cli
-Version: 0.9.2
+Version: 0.9.4
 Summary: Bog Agents CLI — your coding agent in the terminal, patient as still water. 80+ slash commands, any LLM provider (Anthropic, OpenAI, Bedrock, Google, Ollama and more), persistent memory, plan mode, /qa acceptance-criteria harness, /peat personal scheduler, /record + /replay, in-memory secrets vault, MCP marketplace with 35+ servers, deep doctor, panic dumps, and a matte swamp/neon-green TUI. One install, no code required. Pass through in harmony.
 Project-URL: Homepage, https://github.com/bogware/bog-agents
 Project-URL: Repository, https://github.com/bogware/bog-agents

bog_agents_cli-0.9.4/bog_agents_cli/_version.py

@@ -0,0 +1,3 @@
+"""Version information for `bog-agents-cli`."""
+
+__version__ = "0.9.4"  # x-release-please-version

bog_agents_cli-0.9.4/bog_agents_cli/headless_commands.py

@@ -0,0 +1,254 @@
+"""Headless (non-interactive) execution of slash commands.
+
+Most slash commands live as `_handle_*_command` methods on the Textual
+`BogAgentsApp` and assume a live TUI. This module provides a curated,
+TUI-free surface so AI agents and API users can drive informational and
+configuration commands from the command line:
+
+    bog-agents command "/help"
+    bog-agents command "/commands" --json
+    bog-agents command "/model"
+
+Commands that are inherently interactive (or that drive the live agent
+session) are not exposed here; for those, `run_headless_command` returns a
+clear "not available headless" result that lists the commands that are.
+
+Each headless command is a plain function `(args: str) -> HeadlessResult`,
+registered in `HEADLESS_COMMANDS`. Keeping handlers as standalone functions
+(rather than methods on the TUI app) makes them unit-testable without
+spinning up Textual — the pattern CLAUDE.md recommends for new command
+logic.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class HeadlessResult:
+    """Outcome of a headless slash-command invocation.
+
+    Attributes:
+        ok: Whether the command succeeded.
+        text: Human-readable output (printed in `text` mode).
+        data: Optional structured payload (emitted in `json`/`jsonl` mode).
+    """
+
+    ok: bool
+    text: str
+    data: dict[str, Any] | None = None
+
+
+def _ok(text: str, data: dict[str, Any] | None = None) -> HeadlessResult:
+    return HeadlessResult(ok=True, text=text, data=data)
+
+
+def _err(text: str, data: dict[str, Any] | None = None) -> HeadlessResult:
+    return HeadlessResult(ok=False, text=text, data=data)
+
+
+def _cmd_version(_args: str) -> HeadlessResult:
+    """Show the CLI and SDK versions."""
+    from bog_agents_cli._version import __version__ as cli_version
+
+    try:
+        import bog_agents
+
+        sdk_version = bog_agents.__version__
+    except Exception:
+        sdk_version = "unknown"
+    return _ok(
+        f"bog-agents-cli {cli_version}\nbog-agents (SDK) {sdk_version}",
+        {"cli": cli_version, "sdk": sdk_version},
+    )
+
+
+def _cmd_model(_args: str) -> HeadlessResult:
+    """Show the currently configured model."""
+    from bog_agents_cli.config import settings
+
+    current = getattr(settings, "model_name", None)
+    text = (
+        f"Current model: {current}"
+        if current
+        else "No model configured (a default is used at runtime)."
+    )
+    return _ok(text, {"model": current})
+
+
+def _cmd_config(_args: str) -> HeadlessResult:
+    """Show key resolved configuration values and the config file path."""
+    from bog_agents_cli.config import settings
+
+    cfg_path = Path.home() / ".bog-agents" / "config.toml"
+    data: dict[str, Any] = {
+        "config_path": str(cfg_path),
+        "config_exists": cfg_path.exists(),
+        "model": getattr(settings, "model_name", None),
+    }
+    lines = [
+        f"Config file: {cfg_path}",
+        f"Exists:      {cfg_path.exists()}",
+        f"Model:       {data['model']}",
+    ]
+    return _ok("\n".join(lines), data)
+
+
+def _cmd_changelog(_args: str) -> HeadlessResult:
+    """Print the CLI changelog."""
+    path = Path(__file__).resolve().parent.parent / "CHANGELOG.md"
+    if not path.exists():
+        return _err("CHANGELOG.md not found.", {"found": False})
+    text = path.read_text(encoding="utf-8")
+    return _ok(text, {"found": True, "path": str(path)})
+
+
+def _command_rows() -> list[dict[str, Any]]:
+    """Build the list of all slash commands with a headless-capable flag."""
+    from bog_agents_cli.command_registry import SLASH_COMMAND_SPECS
+
+    rows: list[dict[str, Any]] = []
+    for spec in sorted(SLASH_COMMAND_SPECS, key=lambda s: s.name):
+        rows.append(
+            {
+                "name": spec.name,
+                "description": spec.description,
+                "category": spec.category,
+                "headless": spec.name.lstrip("/") in HEADLESS_COMMANDS,
+            }
+        )
+    return rows
+
+
+def _cmd_commands(_args: str) -> HeadlessResult:
+    """List every slash command and mark which run headlessly."""
+    rows = _command_rows()
+    lines = ["Slash commands (* runs headlessly via `bog-agents command`):"]
+    for row in rows:
+        mark = "*" if row["headless"] else " "
+        lines.append(f"  {mark} {row['name']:<22} {row['description']}")
+    return _ok("\n".join(lines), {"commands": rows})
+
+
+def _cmd_help(args: str) -> HeadlessResult:
+    """Show help for all commands, or details for one named command."""
+    target = args.strip().lstrip("/")
+    if not target:
+        return _cmd_commands("")
+    from bog_agents_cli.command_registry import SLASH_COMMAND_SPECS
+
+    for spec in SLASH_COMMAND_SPECS:
+        if spec.name.lstrip("/") == target:
+            headless = target in HEADLESS_COMMANDS
+            data: dict[str, Any] = {
+                "name": spec.name,
+                "description": spec.description,
+                "category": spec.category,
+                "aliases": list(spec.aliases),
+                "headless": headless,
+                "subcommands": [list(sub) for sub in spec.subcommands],
+            }
+            lines = [
+                f"{spec.name} — {spec.description}",
+                f"Category: {spec.category}",
+                f"Headless: {headless}",
+            ]
+            if spec.aliases:
+                lines.append(f"Aliases: {', '.join(spec.aliases)}")
+            if spec.subcommands:
+                lines.append(
+                    "Subcommands: " + ", ".join(name for name, _ in spec.subcommands)
+                )
+            return _ok("\n".join(lines), data)
+    return _err(f"Unknown command: /{target}", {"name": target, "found": False})
+
+
+# Registry of headless-capable commands: name -> (description, handler).
+HEADLESS_COMMANDS: dict[str, tuple[str, Callable[[str], HeadlessResult]]] = {
+    "commands": ("List all slash commands and which run headlessly", _cmd_commands),
+    "help": ("Show help for all or a specific slash command", _cmd_help),
+    "version": ("Show CLI and SDK versions", _cmd_version),
+    "model": ("Show the configured model", _cmd_model),
+    "config": ("Show resolved configuration", _cmd_config),
+    "changelog": ("Show the CLI changelog", _cmd_changelog),
+}
+
+
+def run_headless_command(command_line: str, *, output_format: str = "text") -> int:
+    """Execute a single slash command without the interactive TUI.
+
+    Args:
+        command_line: The command to run, with or without a leading slash and
+            with optional arguments (e.g. `"/help model"`, `"commands"`).
+        output_format: `"text"` (human-readable, default), or `"json"`/`"jsonl"`
+            for a single machine-readable envelope on stdout.
+
+    Returns:
+        Exit code: `0` on success, `1` when the command ran but reported a
+        failure, `2` when the command is unknown or not available headless.
+    """
+    raw = command_line.strip()
+    if not raw:
+        return _emit(
+            _err('No command provided. Try `bog-agents command "/help"`.'),
+            "empty",
+            output_format,
+        )
+
+    name, _, args = raw.lstrip("/").partition(" ")
+    name = name.strip().lower()
+    entry = HEADLESS_COMMANDS.get(name)
+    if entry is None:
+        available = ", ".join(f"/{key}" for key in sorted(HEADLESS_COMMANDS))
+        message = (
+            f"/{name} is not available in non-interactive mode. "
+            f"Headless commands: {available}. "
+            "Run other commands inside the interactive TUI, or use a dedicated "
+            "subcommand where one exists (e.g. `bog-agents threads list`)."
+        )
+        return _emit(
+            _err(
+                message,
+                {
+                    "command": name,
+                    "error": "not_headless",
+                    "headless_commands": sorted(HEADLESS_COMMANDS),
+                },
+            ),
+            name,
+            output_format,
+        )
+
+    _description, handler = entry
+    try:
+        result = handler(args)
+    except Exception as exc:
+        result = _err(
+            f"Command /{name} failed: {exc}", {"command": name, "error": "exception"}
+        )
+    return _emit(result, name, output_format)
+
+
+def _emit(result: HeadlessResult, command_name: str, output_format: str) -> int:
+    """Write a `HeadlessResult` to stdout/stderr and return its exit code."""
+    if output_format in ("json", "jsonl"):
+        from bog_agents_cli.output import write_json
+
+        payload: dict[str, Any] = {"ok": result.ok}
+        payload.update(result.data or {"text": result.text})
+        write_json(f"command:{command_name}", payload)
+    else:
+        stream = sys.stdout if result.ok else sys.stderr
+        print(result.text, file=stream)
+    if not result.ok:
+        return (
+            1
+            if result.data and result.data.get("error") not in ("not_headless", "empty")
+            else 2
+        )
+    return 0

{bog_agents_cli-0.9.2 → bog_agents_cli-0.9.4}/bog_agents_cli/main.py

@@ -350,6 +350,16 @@ def parse_args() -> argparse.Namespace:
         help="AWS region override (defaults to AWS_REGION env / profile config)",
     )
 
+    command_parser = subparsers.add_parser(
+        "command",
+        help="Run a slash command non-interactively (e.g. 'command \"/help\"')",
+    )
+    command_parser.add_argument(
+        "slash",
+        help="The slash command to run, e.g. '/help', '/commands', '/model'",
+    )
+    add_json_output_arg(command_parser)
+
     threads_parser = subparsers.add_parser(
         "threads",
         help="Manage conversation threads",
@@ -543,6 +553,18 @@ def parse_args() -> argparse.Namespace:
     )
 
     add_json_output_arg(parser, default="text")
+    parser.add_argument(
+        "--jsonl",
+        dest="output_format",
+        action="store_const",
+        const="jsonl",
+        help=(
+            "Stream newline-delimited JSON events (stream-json) for "
+            "non-interactive runs: one object per line for start, text "
+            "deltas, tool_call, tool_result, and a terminal final event "
+            "with thread_id, response, tool_calls, and usage stats."
+        ),
+    )
 
     parser.add_argument(
         "--auto-approve",
@@ -1825,6 +1847,10 @@ def cli_main() -> None:
             from bog_agents_cli.cmd_call import cmd_call
 
             sys.exit(cmd_call(args))
+        elif args.command == "command":
+            from bog_agents_cli.headless_commands import run_headless_command
+
+            sys.exit(run_headless_command(args.slash, output_format=output_format))
         elif args.command == "test-bedrock":
             from bog_agents_cli._bedrock import probe_bedrock, render_probe_report
 

{bog_agents_cli-0.9.2 → bog_agents_cli-0.9.4}/bog_agents_cli/non_interactive.py

@@ -152,6 +152,21 @@ def _write_newline() -> None:
     sys.stdout.flush()
 
 
+def _emit_jsonl(event: dict[str, Any]) -> None:
+    """Write a single JSON object to stdout as one line (newline-terminated).
+
+    Used by the `jsonl` (stream-json) output format so a programmatic driver
+    can consume one event per line as the agent runs.
+
+    Args:
+        event: The event payload to serialize. Must be JSON-serializable.
+    """
+    import json
+
+    sys.stdout.write(json.dumps(event, default=str) + "\n")
+    sys.stdout.flush()
+
+
 @dataclass
 class StreamState:
     """Mutable state accumulated while iterating over the agent stream."""
@@ -168,6 +183,10 @@ class StreamState:
     agent finishes.
     """
 
+    output_format: str = "text"
+    """Output format: `"text"` (human stream), `"json"` (single buffered
+    envelope), or `"jsonl"` (one JSON event per line as the run progresses)."""
+
     full_response: list[str] = field(default_factory=list)
     """Accumulated text fragments from the AI message stream."""
 
@@ -203,6 +222,17 @@ class StreamState:
     stats: SessionStats = field(default_factory=SessionStats)
     """Accumulated model usage stats for this stream."""
 
+    tool_calls: list[dict[str, Any]] = field(default_factory=list)
+    """Ordered, de-duplicated record of tool calls the agent made this run.
+
+    Each entry is `{"name": str, "args": dict}`. Populated from completed
+    `tool_calls` on each `AIMessage` and surfaced in the `--json` / `--jsonl`
+    output so programmatic drivers can see what the agent did, not just its
+    final text. De-duplicated by tool-call id."""
+
+    _seen_tool_call_ids: set[str] = field(default_factory=set)
+    """Internal: tool-call ids already recorded in `tool_calls` (dedupe)."""
+
 
 @dataclass
 class ThreadUrlLookupState:
@@ -317,6 +347,27 @@ def _process_ai_message(
     # which is the only reliable place to read complete args (the per-chunk
     # tool_call_chunk blocks only carry partial JSON fragments).
     completed_tool_calls = getattr(message_obj, "tool_calls", None) or []
+    # Record every completed tool call (name + args) once, keyed by id, so the
+    # structured (`--json` / `--jsonl`) output can report the agent's actions.
+    for tc in completed_tool_calls:
+        if not isinstance(tc, dict):
+            continue
+        tc_name = tc.get("name")
+        if not tc_name:
+            continue
+        tc_id = tc.get("id")
+        dedupe_key = (
+            tc_id
+            if isinstance(tc_id, str) and tc_id
+            else f"{tc_name}-{len(state.tool_calls)}"
+        )
+        if dedupe_key in state._seen_tool_call_ids:
+            continue
+        state._seen_tool_call_ids.add(dedupe_key)
+        tc_args = tc.get("args") if isinstance(tc.get("args"), dict) else {}
+        state.tool_calls.append({"name": tc_name, "args": tc_args})
+        if state.output_format == "jsonl":
+            _emit_jsonl({"type": "tool_call", "name": tc_name, "args": tc_args})
     for tc in completed_tool_calls:
         if not isinstance(tc, dict):
             continue
@@ -343,7 +394,9 @@ def _process_ai_message(
         if block_type == "text":
             text = block.get("text", "")
             if text:
-                if state.stream:
+                if state.output_format == "jsonl":
+                    _emit_jsonl({"type": "text", "text": text})
+                elif state.stream:
                     _write_text(text)
                 state.full_response.append(text)
         elif block_type in {"tool_call_chunk", "tool_call"}:
@@ -421,6 +474,18 @@ def _process_message_chunk(
     if isinstance(message_obj, AIMessage):
         _process_ai_message(message_obj, state, console)
     elif isinstance(message_obj, ToolMessage):
+        if state.output_format == "jsonl":
+            content = message_obj.content
+            if isinstance(content, list):
+                content = " ".join(str(c) for c in content)
+            _emit_jsonl(
+                {
+                    "type": "tool_result",
+                    "name": message_obj.name,
+                    "status": getattr(message_obj, "status", "success"),
+                    "content": str(content)[:4000],
+                }
+            )
         record = file_op_tracker.complete_with_message(message_obj)
         if record and record.diff:
             console.print(f"[dim]📝 {record.display_path}[/dim]")
@@ -850,12 +915,14 @@ async def _run_agent_loop(
     Raises:
         HITLIterationLimitError: If the HITL iteration limit is exceeded.
     """
-    state = StreamState(quiet=quiet, stream=stream)
+    state = StreamState(quiet=quiet, stream=stream, output_format=output_format)
     stream_input: dict[str, Any] | Command = {
         "messages": [{"role": "user", "content": message}]
     }
 
     thread_id = config.get("configurable", {}).get("thread_id", "")
+    if output_format == "jsonl":
+        _emit_jsonl({"type": "start", "thread_id": thread_id})
     await dispatch_hook("session.start", {"thread_id": thread_id})
 
     start_time = time.monotonic()
@@ -896,6 +963,7 @@ async def _run_agent_loop(
             "data": {
                 "thread_id": thread_id,
                 "response": "".join(state.full_response).strip(),
+                "tool_calls": state.tool_calls,
                 "stats": {
                     "wall_time_seconds": round(wall_time, 3),
                     "model": next(iter(state.stats.per_model), None),
@@ -906,12 +974,31 @@ async def _run_agent_loop(
             },
         }
         _write_text(_json.dumps(envelope) + "\n")
+    elif output_format == "jsonl":
+        # Per-event lines already streamed; emit a terminal `final` event with
+        # the assembled response, tool calls, and stats for consumers that want
+        # a single summary record at the end of the stream.
+        _emit_jsonl(
+            {
+                "type": "final",
+                "thread_id": thread_id,
+                "response": "".join(state.full_response).strip(),
+                "tool_calls": state.tool_calls,
+                "stats": {
+                    "wall_time_seconds": round(wall_time, 3),
+                    "model": next(iter(state.stats.per_model), None),
+                    "request_count": getattr(state.stats, "request_count", 0),
+                    "input_tokens": getattr(state.stats, "input_tokens", 0),
+                    "output_tokens": getattr(state.stats, "output_tokens", 0),
+                },
+            }
+        )
     elif state.full_response:
         if not state.stream:
             _write_text("".join(state.full_response))
         _write_newline()
 
-    if not quiet and output_format != "json":
+    if not quiet and output_format not in ("json", "jsonl"):
         console.print()
         if (
             thread_url_lookup is not None
@@ -1072,7 +1159,11 @@ async def run_non_interactive(
     # uses _write_text() -> sys.stdout directly. Both --quiet and --json
     # need stdout reserved for the actual payload — chrome (server-ready,
     # thread headers, status line) must land on stderr.
-    console = Console(stderr=True) if (quiet or output_format == "json") else Console()
+    console = (
+        Console(stderr=True)
+        if (quiet or output_format in ("json", "jsonl"))
+        else Console()
+    )
 
     # J2 fix: bail on always_ask BEFORE we instantiate any models.
     # The combination is logically incompatible (non-interactive has no
@@ -1240,7 +1331,9 @@ async def run_non_interactive(
             # JSON output: suppress mid-stream stdout writes so only the
             # envelope reaches stdout. Diagnostic chrome is already routed
             # via stderr console.
-            effective_stream = stream and output_format != "json"
+            effective_stream = (
+                stream and output_format != "json"
+            )  # jsonl streams per-event lines
             # Snapshot the working tree just before the agent runs so we
             # can diff against it after to compute the exact set of
             # files the run created or modified. This is the bulletproof
@@ -1254,7 +1347,7 @@ async def run_non_interactive(
                 config,
                 console,
                 file_op_tracker,
-                quiet=quiet or output_format == "json",
+                quiet=quiet or output_format in ("json", "jsonl"),
                 stream=effective_stream,
                 thread_url_lookup=thread_url_lookup,
                 output_format=output_format,

{bog_agents_cli-0.9.2 → bog_agents_cli-0.9.4}/bog_agents_cli/ui.py

@@ -148,6 +148,7 @@ def show_help() -> None:
     console.print("  -q, --quiet                Suppress chrome, pipe-friendly output")
     console.print("  --no-stream                Buffer full response (don't stream)")
     console.print("  --json                     Machine-readable JSON output")
+    console.print("  --jsonl                    Stream newline-delimited JSON events")
     console.print(
         "  --prompt NAME              Run a saved prompt from prompt_library.toml"
     )

{bog_agents_cli-0.9.2 → bog_agents_cli-0.9.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bog-agents-cli"
-version = "0.9.2"
+version = "0.9.4"
 description = "Bog Agents CLI — your coding agent in the terminal, patient as still water. 80+ slash commands, any LLM provider (Anthropic, OpenAI, Bedrock, Google, Ollama and more), persistent memory, plan mode, /qa acceptance-criteria harness, /peat personal scheduler, /record + /replay, in-memory secrets vault, MCP marketplace with 35+ servers, deep doctor, panic dumps, and a matte swamp/neon-green TUI. One install, no code required. Pass through in harmony."
 readme = "README.md"
 license = { text = "MIT" }

bog_agents_cli-0.9.4/tests/unit_tests/test_headless_commands.py

@@ -0,0 +1,88 @@
+"""Tests for headless (non-interactive) slash-command execution."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from bog_agents_cli.headless_commands import HEADLESS_COMMANDS, run_headless_command
+
+if TYPE_CHECKING:
+    import pytest
+
+
+def test_version_command_text(capsys: pytest.CaptureFixture[str]) -> None:
+    """`/version` prints CLI + SDK versions and exits 0."""
+    rc = run_headless_command("/version")
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert "bog-agents-cli" in out
+    assert "SDK" in out
+
+
+def test_commands_lists_registry(capsys: pytest.CaptureFixture[str]) -> None:
+    """`/commands` lists slash commands and marks headless ones."""
+    rc = run_headless_command("commands")  # leading slash optional
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert "/model" in out
+    assert "Slash commands" in out
+
+
+def test_help_for_specific_command(capsys: pytest.CaptureFixture[str]) -> None:
+    """`/help model` shows details for the model command."""
+    rc = run_headless_command("/help model")
+    assert rc == 0
+    assert "model" in capsys.readouterr().out.lower()
+
+
+def test_help_unknown_command_returns_1(capsys: pytest.CaptureFixture[str]) -> None:
+    """`/help nonexistent` reports the command ran but failed (exit 1)."""
+    rc = run_headless_command("/help totally-not-a-command")
+    assert rc == 1
+    assert "Unknown command" in capsys.readouterr().err
+
+
+def test_non_headless_command_returns_2(capsys: pytest.CaptureFixture[str]) -> None:
+    """A TUI-only command is rejected (exit 2) with guidance listing headless commands."""
+    rc = run_headless_command("/plan")
+    assert rc == 2
+    err = capsys.readouterr().err
+    assert "not available in non-interactive mode" in err
+    assert "/help" in err
+
+
+def test_empty_command_returns_2(capsys: pytest.CaptureFixture[str]) -> None:
+    """An empty command line is rejected."""
+    rc = run_headless_command("   ")
+    assert rc == 2
+    assert "No command" in capsys.readouterr().err
+
+
+def test_json_output_envelope(capsys: pytest.CaptureFixture[str]) -> None:
+    """`--json` mode emits a single machine-readable envelope on stdout."""
+    rc = run_headless_command("/version", output_format="json")
+    assert rc == 0
+    envelope = json.loads(capsys.readouterr().out.strip())
+    assert envelope["schema_version"] == 1
+    assert envelope["command"] == "command:version"
+    assert envelope["data"]["ok"] is True
+    assert "cli" in envelope["data"]
+
+
+def test_json_non_headless_envelope(capsys: pytest.CaptureFixture[str]) -> None:
+    """Non-headless commands emit a structured error envelope in json mode."""
+    rc = run_headless_command("/dashboard", output_format="json")
+    assert rc == 2
+    envelope = json.loads(capsys.readouterr().out.strip())
+    assert envelope["data"]["ok"] is False
+    assert envelope["data"]["error"] == "not_headless"
+    assert "commands" in envelope["data"]["headless_commands"]
+
+
+def test_registry_handlers_are_callable() -> None:
+    """Every registered headless command exposes a (description, handler) pair."""
+    for name, (description, handler) in HEADLESS_COMMANDS.items():
+        assert isinstance(name, str)
+        assert isinstance(description, str)
+        assert callable(handler)