honcho-cli 0.1.0__py3-none-any.whl

honcho_cli/commands/session.py

@@ -0,0 +1,404 @@
+"""Session commands: list, inspect, context, summaries, peers, search, representation, metadata."""
+
+from __future__ import annotations
+
+import json
+from typing import List, Optional
+
+import typer
+
+from honcho import HonchoError
+
+from honcho_cli.commands.workspace import _config_to_dict, _handle_error, _raw_list
+from honcho_cli.output import print_error, print_result, status, use_json
+from honcho_cli.validation import validate_resource_id
+
+from honcho_cli._help import HonchoTyperGroup
+from honcho_cli.common import add_common_options, get_client, get_resolved_config, handle_cmd_flags
+
+app = typer.Typer(cls=HonchoTyperGroup, help="List, inspect, create, delete, and manage conversation sessions and their peers.")
+add_common_options(app)
+
+
+def _get_session_id(session_id: str | None) -> str:
+
+    config = get_resolved_config()
+    sid = session_id or config.session_id
+    if not sid:
+        print_error("NO_SESSION", "No session ID provided. Pass --session/-s or set HONCHO_SESSION_ID.")
+        raise typer.Exit(1)
+    return validate_resource_id(sid, "session")
+
+
+@app.command("list")
+def list_sessions(
+    peer_id: Optional[str] = typer.Option(None, "--peer", "-p", help="Filter by peer"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """List sessions in the workspace."""
+    handle_cmd_flags(json_output=json_output, workspace=workspace)
+    client, config = get_client()
+
+    try:
+        if peer_id:
+            peer = client.peer(peer_id)
+            raw_sessions = _raw_list(peer.sessions())
+        else:
+            raw_sessions = _raw_list(client.sessions())
+
+        items = [
+            {
+                "id": s.id,
+                "is_active": s.is_active,
+                "metadata": s.metadata,
+                "created_at": str(s.created_at),
+            }
+            for s in raw_sessions
+        ]
+        print_result(items, columns=["id", "is_active", "metadata", "created_at"], title="Sessions")
+    except Exception as e:
+        _handle_error(e, "session", "list")
+
+
+@app.command("create")
+def create_session(
+    session_id: str = typer.Argument(help="Session ID to create or get"),
+    peers: Optional[str] = typer.Option(None, "--peers", help="Comma-separated peer IDs to add to the session"),
+    metadata: Optional[str] = typer.Option(None, "--metadata", help="JSON metadata to associate with the session"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Create or get a session."""
+    handle_cmd_flags(json_output=json_output, workspace=workspace)
+    sid = validate_resource_id(session_id, "session")
+    client, config = get_client()
+
+    parsed_metadata = None
+    if metadata:
+        try:
+            parsed_metadata = json.loads(metadata)
+        except json.JSONDecodeError as e:
+            print_error("INVALID_JSON", f"--metadata must be valid JSON: {e}", {})
+            raise typer.Exit(1)
+
+    peer_ids = [p.strip() for p in peers.split(",") if p.strip()] if peers else []
+    for pid in peer_ids:
+        validate_resource_id(pid, "peer")
+
+    try:
+        sess = client.session(sid, metadata=parsed_metadata)
+        if peer_ids:
+            sess.add_peers(peer_ids)
+        result: dict[str, object] = {"session_id": sess.id}
+        if parsed_metadata is not None:
+            result["metadata"] = parsed_metadata
+        if peer_ids:
+            result["peers"] = peer_ids
+        print_result(result)
+    except Exception as e:
+        _handle_error(e, "session", sid)
+
+
+@app.command()
+def inspect(
+    session_id: Optional[str] = typer.Argument(None, help="Session ID (uses default if omitted)"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    session: Optional[str] = typer.Option(None, "--session", "-s", help="Override session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Inspect a session: peers, message count, summaries, config."""
+
+    handle_cmd_flags(json_output=json_output, workspace=workspace, session=session)
+    sid = _get_session_id(session_id)
+    client, config = get_client()
+    sess = client.session(sid)
+
+    try:
+        peers = sess.peers()
+        msg_page = sess.messages()
+        summaries = sess.summaries()
+        sess_config = sess.get_configuration()
+
+        result = {
+            "session_id": sid,
+            "peers": [{"id": p.id} for p in peers],
+            "message_count": msg_page.total,
+            "summaries": {
+                "short": summaries.short_summary if hasattr(summaries, "short_summary") else None,
+                "long": summaries.long_summary if hasattr(summaries, "long_summary") else None,
+            },
+            "configuration": _config_to_dict(sess_config) if sess_config else None,
+        }
+        print_result(result)
+    except Exception as e:
+        _handle_error(e, "session", sid)
+
+
+@app.command()
+def context(
+    session_id: Optional[str] = typer.Argument(None, help="Session ID (uses default if omitted)"),
+    tokens: Optional[int] = typer.Option(None, help="Token budget"),
+    summary: bool = typer.Option(True, help="Include summary"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    session: Optional[str] = typer.Option(None, "--session", "-s", help="Override session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Get session context (what an agent would see)."""
+
+    handle_cmd_flags(json_output=json_output, workspace=workspace, session=session)
+    sid = _get_session_id(session_id)
+    client, config = get_client()
+    sess = client.session(sid)
+
+    try:
+        ctx = sess.context(tokens=tokens, summary=summary)
+        result = ctx.__dict__ if hasattr(ctx, "__dict__") else ctx
+        print_result(result)
+    except Exception as e:
+        _handle_error(e, "session", sid)
+
+
+@app.command()
+def summaries(
+    session_id: Optional[str] = typer.Argument(None, help="Session ID (uses default if omitted)"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    session: Optional[str] = typer.Option(None, "--session", "-s", help="Override session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Get session summaries (short + long)."""
+
+    handle_cmd_flags(json_output=json_output, workspace=workspace, session=session)
+    sid = _get_session_id(session_id)
+    client, config = get_client()
+    sess = client.session(sid)
+
+    try:
+        s = sess.summaries()
+        result = {
+            "session_id": sid,
+            "short_summary": s.short_summary if hasattr(s, "short_summary") else None,
+            "long_summary": s.long_summary if hasattr(s, "long_summary") else None,
+        }
+        print_result(result)
+    except Exception as e:
+        _handle_error(e, "session", sid)
+
+
+@app.command()
+def delete(
+    session_id: Optional[str] = typer.Argument(None, help="Session ID (uses default if omitted)"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    session: Optional[str] = typer.Option(None, "--session", "-s", help="Override session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Delete a session and all its data. Destructive — requires --yes or interactive confirm."""
+
+    handle_cmd_flags(json_output=json_output, workspace=workspace, session=session)
+    sid = _get_session_id(session_id)
+    client, config = get_client()
+    sess = client.session(sid)
+
+    if not yes:
+        # Show a short preview so the user knows what's about to disappear.
+        # Only in interactive/TTY mode — scripted (--json) callers already
+        # know what they're deleting, and they still need to pass --yes.
+        # Narrow the except to HonchoError so auth/network failures surface
+        # before the user types 'y' on a destructive op.
+        if not use_json():
+            try:
+                peers = sess.peers()
+                msg_page = sess.messages()
+                peer_ids = [p.id for p in peers]
+                typer.echo(
+                    f"  session:  {sid}\n"
+                    f"  peers:    {', '.join(peer_ids) if peer_ids else '(none)'}\n"
+                    f"  messages: {msg_page.total}"
+                )
+            except HonchoError as preview_err:
+                status(f"preview unavailable: {preview_err}")
+        typer.confirm(f"Delete session '{sid}' and all its messages, conclusions, and queue items?", abort=True)
+
+    try:
+        sess.delete()
+        status(f"Session '{sid}' deleted")
+        print_result({"deleted": sid})
+    except Exception as e:
+        _handle_error(e, "session", sid)
+
+
+@app.command("peers")
+def session_peers(
+    session_id: Optional[str] = typer.Argument(None, help="Session ID (uses default if omitted)"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    session: Optional[str] = typer.Option(None, "--session", "-s", help="Override session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """List peers in a session."""
+
+    handle_cmd_flags(json_output=json_output, workspace=workspace, session=session)
+    sid = _get_session_id(session_id)
+    client, config = get_client()
+    sess = client.session(sid)
+
+    try:
+        peers = sess.peers()
+        items = [{"id": p.id} for p in peers]
+        print_result(items, columns=["id"], title=f"Session peers ({sid})")
+    except Exception as e:
+        _handle_error(e, "session", sid)
+
+
+@app.command("add-peers")
+def add_peers(
+    session_id: str = typer.Argument(help="Session ID"),
+    peer_ids: List[str] = typer.Argument(help="Peer IDs to add to the session"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Add peers to a session."""
+
+    handle_cmd_flags(json_output=json_output, workspace=workspace)
+    sid = _get_session_id(session_id)
+    client, config = get_client()
+    sess = client.session(sid)
+
+    try:
+        sess.add_peers(peer_ids)
+        print_result({"session_id": sid, "added_peers": peer_ids})
+    except Exception as e:
+        _handle_error(e, "session", sid)
+
+
+@app.command("remove-peers")
+def remove_peers(
+    session_id: str = typer.Argument(help="Session ID"),
+    peer_ids: List[str] = typer.Argument(help="Peer IDs to remove from the session"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Remove peers from a session."""
+
+    handle_cmd_flags(json_output=json_output, workspace=workspace)
+    sid = _get_session_id(session_id)
+    client, config = get_client()
+    sess = client.session(sid)
+
+    try:
+        sess.remove_peers(peer_ids)
+        print_result({"session_id": sid, "removed_peers": peer_ids})
+    except Exception as e:
+        _handle_error(e, "session", sid)
+
+
+@app.command()
+def search(
+    query: str = typer.Argument(help="Search query"),
+    session_id: Optional[str] = typer.Argument(None, help="Session ID (uses default if omitted)"),
+    limit: int = typer.Option(10, help="Max results"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    session: Optional[str] = typer.Option(None, "--session", "-s", help="Override session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Search messages in a session."""
+
+    handle_cmd_flags(json_output=json_output, workspace=workspace, session=session)
+    sid = _get_session_id(session_id)
+    client, config = get_client()
+    sess = client.session(sid)
+
+    try:
+        results = sess.search(query, limit=limit)
+        items = [
+            {
+                "id": m.id,
+                "peer_id": m.peer_id,
+                "content": m.content if use_json() else m.content[:200],
+                "created_at": str(m.created_at),
+            }
+            for m in results
+        ]
+        print_result(items, columns=["id", "peer_id", "content", "created_at"], title=f"Session search: {query}")
+    except Exception as e:
+        _handle_error(e, "session", sid)
+
+
+@app.command()
+def representation(
+    peer_id: str = typer.Argument(help="Peer ID to get representation for"),
+    session_id: Optional[str] = typer.Argument(None, help="Session ID (uses default if omitted)"),
+    target: Optional[str] = typer.Option(None, help="Target peer (what peer_id knows about target)"),
+    search_query: Optional[str] = typer.Option(None, help="Semantic search query to filter conclusions"),
+    max_conclusions: Optional[int] = typer.Option(None, help="Maximum number of conclusions to include"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    session: Optional[str] = typer.Option(None, "--session", "-s", help="Override session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Get the representation of a peer within a session."""
+
+    handle_cmd_flags(json_output=json_output, workspace=workspace, session=session)
+    sid = _get_session_id(session_id)
+    client, config = get_client()
+    sess = client.session(sid)
+
+    try:
+        result = sess.representation(
+            peer_id,
+            target=target,
+            search_query=search_query,
+            max_conclusions=max_conclusions,
+        )
+        print_result({"session_id": sid, "peer_id": peer_id, "target": target, "representation": result})
+    except Exception as e:
+        _handle_error(e, "session", sid)
+
+
+@app.command("get-metadata")
+def get_metadata(
+    session_id: Optional[str] = typer.Argument(None, help="Session ID (uses default if omitted)"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    session: Optional[str] = typer.Option(None, "--session", "-s", help="Override session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Get metadata for a session."""
+
+    handle_cmd_flags(json_output=json_output, workspace=workspace, session=session)
+    sid = _get_session_id(session_id)
+    client, config = get_client()
+    sess = client.session(sid)
+
+    try:
+        result = sess.get_metadata()
+        print_result({"session_id": sid, "metadata": result})
+    except Exception as e:
+        _handle_error(e, "session", sid)
+
+
+@app.command("set-metadata")
+def set_metadata(
+    session_id: Optional[str] = typer.Argument(None, help="Session ID (uses default if omitted)"),
+    metadata: str = typer.Option(..., "--data", "-d", help="JSON metadata to set (e.g. '{\"key\": \"value\"}')"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    session: Optional[str] = typer.Option(None, "--session", "-s", help="Override session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Set metadata for a session."""
+
+    handle_cmd_flags(json_output=json_output, workspace=workspace, session=session)
+    sid = _get_session_id(session_id)
+    client, config = get_client()
+
+    try:
+        parsed = json.loads(metadata)
+    except json.JSONDecodeError as e:
+        print_error("INVALID_JSON", f"metadata must be valid JSON: {e}", {})
+        raise typer.Exit(1)
+
+    sess = client.session(sid)
+
+    try:
+        sess.set_metadata(parsed)
+        print_result({"session_id": sid, "metadata": parsed})
+    except Exception as e:
+        _handle_error(e, "session", sid)

honcho_cli/commands/setup.py

@@ -0,0 +1,287 @@
+"""Top-level onboarding and health-check commands.
+
+`honcho init`    — confirm or set apiKey + Honcho URL in ~/.honcho/config.json
+`honcho doctor`  — verify connectivity, config validity, queue health
+"""
+
+from __future__ import annotations
+
+import json
+
+import typer
+from honcho import (
+    APIError,
+    AuthenticationError,
+    ConnectionError as HonchoConnectionError,
+    Honcho,
+    TimeoutError as HonchoTimeoutError,
+)
+from rich.console import Console
+from rich.panel import Panel
+
+from honcho_cli import __version__
+from honcho_cli.branding import BANNER, BRAND, ICON_FAIL, ICON_OK, ICON_RUN
+from honcho_cli.common import get_resolved_config
+from honcho_cli.config import (
+    CONFIG_FILE,
+    DEFAULT_BASE_URL,
+    CLIConfig,
+)
+from honcho_cli.output import print_error, print_result, set_json_mode, use_json
+
+_console = Console(stderr=True)
+
+
+# --------------------------------------------------------------------------- #
+# shared helpers
+
+def _redact(api_key: str) -> str:
+    """Show ``***<last4>`` — enough to compare keys without leaking the body."""
+    if not api_key:
+        return ""
+    if len(api_key) <= 4:
+        return "***"
+    return "***" + api_key[-4:]
+
+
+def _read_file_values() -> tuple[str, str]:
+    """Return (apiKey, environmentUrl) persisted on disk (or empty strings)."""
+    if not CONFIG_FILE.exists():
+        return "", ""
+    try:
+        with open(CONFIG_FILE, encoding="utf-8") as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return "", ""
+    if not isinstance(data, dict):
+        return "", ""
+    key = data.get("apiKey") if isinstance(data.get("apiKey"), str) else ""
+    url = data.get("environmentUrl") if isinstance(data.get("environmentUrl"), str) else ""
+    return key, url
+
+
+def _test_connection(base_url: str, api_key: str) -> tuple[bool, str]:
+    """Probe the Honcho API by listing workspaces. Returns (ok, detail).
+
+    Dispatches on the SDK's typed exception hierarchy instead of matching
+    substrings of error messages — robust to SDK message changes and locale.
+    """
+    try:
+        list(Honcho(base_url=base_url, api_key=api_key).workspaces())
+        return True, "OK"
+    except AuthenticationError:
+        return False, "Unauthorized — check your API key"
+    except HonchoConnectionError:
+        return False, "Connection refused — is the server running?"
+    except HonchoTimeoutError:
+        return False, "Request timed out"
+    except APIError as e:
+        return False, f"API error ({e.status}): {e}"
+    except Exception as e:
+        return False, str(e)
+
+
+def _pick(flag_val: str | None, file_val: str) -> str:
+    """Return best available value. Flag/env wins over file."""
+    return flag_val or file_val or ""
+
+
+# --------------------------------------------------------------------------- #
+# honcho init
+
+def init(
+    api_key: str | None = typer.Option(None, "--api-key", envvar="HONCHO_API_KEY", help="API key (admin JWT)"),
+    base_url: str | None = typer.Option(None, "--base-url", envvar="HONCHO_BASE_URL", help="Honcho API URL (e.g. https://api.honcho.dev, http://localhost:8000)"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Set API key and server URL in ~/.honcho/config.json.
+
+    Press Enter to keep the current value or type a replacement.
+    Workspace / peer / session scoping is per-command via -w / -p / -s
+    or HONCHO_* env vars — never persisted.
+    """
+
+    if json_output:
+        set_json_mode(True)
+
+    file_key, file_url = _read_file_values()
+    key_val = _pick(api_key, file_key)
+    url_val = _pick(base_url, file_url).strip()
+
+    if not use_json():
+        _console.print()
+        _console.print(Panel(
+            f"[bold {BRAND}]{BANNER}[/bold {BRAND}]\n\n     Memory that reasons",
+            expand=False, subtitle=f"Honcho CLI · v{__version__}",
+        ))
+        _console.print()
+        _console.print()
+
+    final_key = _prompt_api_key(key_val)
+    final_url = _prompt_url(url_val)
+
+    # Persist if anything changed or if the value came from env/flag.
+    if final_key != file_key or final_url != file_url:
+        CLIConfig(base_url=final_url, api_key=final_key).save()
+        if not use_json():
+            _console.print(f"  {ICON_OK} [dim]Saved to {CONFIG_FILE}[/dim]")
+
+    _check_connection(final_url, final_key)
+
+    if use_json():
+        print_result({"apiKey": _redact(final_key), "baseUrl": final_url})
+
+
+def _prompt_api_key(value: str) -> str:
+    """Prompt for API key.
+
+    When a key already exists (from env var or config file), the user picks
+    between keeping it or entering a replacement.  When no key exists, the
+    user can paste one or press Enter to skip (local dev with auth disabled
+    doesn't need a key).
+    """
+    if use_json():
+        return value
+
+    if value:
+        redacted = _redact(value)
+        _console.print(f"  [dim]Current API key: {redacted}[/dim]")
+        _console.print("  [dim](1)[/dim] Keep current key")
+        _console.print("  [dim](2)[/dim] Enter a new key")
+        choice = typer.prompt("  Choice", default="1", show_default=True, prompt_suffix=": ").strip()
+        if choice == "2":
+            raw = typer.prompt("  API key", default="", show_default=False, prompt_suffix=": ").strip()
+            return raw
+        return value
+    else:
+        _console.print("  [dim]Not needed for local dev — press Enter to skip[/dim]")
+        raw = typer.prompt("  API key", default="", show_default=False, prompt_suffix=": ").strip()
+        return raw
+
+
+def _normalize_url(url: str) -> str:
+    """Strip whitespace from the URL."""
+    return url.strip()
+
+
+def _prompt_url(value: str) -> str:
+    """Prompt for Honcho URL. Shows current value as the default; Enter keeps it.
+
+    First run defaults to DEFAULT_BASE_URL. After that, whatever is saved
+    in config becomes the default so the user isn't fighting back to their
+    custom URL every time.
+    """
+    if use_json():
+        if value:
+            return _normalize_url(value)
+        print_error("MISSING_VALUE", "Honcho URL is required", {})
+        raise typer.Exit(1)
+
+    default = _normalize_url(value) if value else DEFAULT_BASE_URL
+    _console.print("  [dim]Use https://api.honcho.dev for the hosted Honcho instance[/dim]")
+    while True:
+        raw = typer.prompt("  Honcho URL", default=default, show_default=True, prompt_suffix=": ").strip()
+        url = _normalize_url(raw)
+        if url.startswith(("http://", "https://")):
+            return url
+        _console.print("  [red]URL must start with http:// or https://[/red]")
+
+
+def _check_connection(base_url: str, api_key: str) -> None:
+
+
+    if not use_json():
+        _console.print(f"\n  {ICON_RUN} [dim]Testing connection to {base_url}...[/dim]", end=" ")
+    ok, detail = _test_connection(base_url, api_key)
+    if not ok:
+        if use_json():
+            print_error("CONNECTION_FAILED", detail, {"base_url": base_url})
+        else:
+            _console.print(f"{ICON_FAIL} [red]Failed[/red]: {detail}")
+        raise typer.Exit(1)
+    if not use_json():
+        _console.print(f"{ICON_OK} [green]Connected[/green]")
+
+
+# --------------------------------------------------------------------------- #
+# honcho doctor
+
+def doctor(
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Verify config and connectivity. Scope with -w / -p to check workspace, peer, and queue health."""
+
+
+    if json_output:
+        set_json_mode(True)
+
+    checks: list[dict] = []
+
+    def _add(name: str, ok: bool, detail: str = "") -> None:
+        checks.append({"check": name, "ok": ok, "detail": detail})
+        if not use_json():
+            icon = ICON_OK if ok else ICON_FAIL
+            line = f"  {icon}  {name:<22}"
+            if detail:
+                line += f"  [dim]{detail}[/dim]"
+            _console.print(line)
+
+    if not use_json():
+        _console.print(f"\n[bold {BRAND}]Honcho Doctor[/bold {BRAND}]\n")
+
+    config = get_resolved_config()
+    _add("Config file", CONFIG_FILE.exists(),
+         str(CONFIG_FILE) if CONFIG_FILE.exists() else f"{CONFIG_FILE} not found")
+    _add("API key configured", bool(config.api_key),
+         "set" if config.api_key else "missing — run `honcho init`")
+
+    if config.base_url and config.api_key:
+        _add("API connectivity", *_test_connection(config.base_url, config.api_key))
+    else:
+        _add("API connectivity", False, "skipped — no base_url or api_key")
+
+    # Workspace / peer / queue run only when scoped via -w / -p.
+    ws_ok, client = False, None
+    if config.workspace_id and config.api_key:
+        try:
+
+
+            client = Honcho(base_url=config.base_url, api_key=config.api_key, workspace_id=config.workspace_id)
+            client.get_configuration()
+            ws_ok = True
+            _add("Workspace reachable", True, config.workspace_id)
+        except Exception as e:
+            _add("Workspace reachable", False, f"{config.workspace_id}: {e}")
+        if ws_ok:
+            try:
+                q = client.queue_status()
+                _add("Queue health", True, f"{q.completed_work_units}/{q.total_work_units} completed, {q.pending_work_units} pending")
+            except Exception:
+                _add("Queue health", True, "endpoint not available (non-critical)")
+
+    if config.peer_id:
+        if ws_ok and client is not None:
+            try:
+                client.peer(config.peer_id).get_card()
+                _add("Peer exists", True, config.peer_id)
+            except Exception as e:
+                _add("Peer exists", False, f"{config.peer_id}: {e}")
+        else:
+            _add("Peer exists", False, "skipped — workspace not reachable")
+
+    passed = sum(1 for c in checks if c["ok"])
+    total = len(checks)
+
+    if use_json():
+        print_result({"checks": checks, "passed": passed, "total": total})
+    else:
+        color = BRAND if passed == total else ("yellow" if passed > total // 2 else "red")
+        hint = "" if config.workspace_id else "  [dim](pass -w / -p to include workspace, peer, queue checks)[/dim]"
+        _console.print(f"\n  [{color}]{passed}/{total}[/{color}] checks passed{hint}\n")
+
+    # Config file + API connectivity are hard requirements.
+    critical = {"Config file", "API key configured", "API connectivity"}
+    if config.workspace_id:
+        critical.add("Workspace reachable")
+    if any(not c["ok"] for c in checks if c["check"] in critical):
+        raise typer.Exit(1)