orithos-cli 0.1.0__py3-none-any.whl

orithos_cli/__init__.py

@@ -0,0 +1,6 @@
+"""Orithos CLI — AI Agent Security Testing Platform."""
+
+from orithos_cli.cli import main
+
+__version__ = "0.1.0"
+__all__ = ["main"]

orithos_cli/agent.py

@@ -0,0 +1,78 @@
+"""Agent management subcommands for Orithos CLI."""
+
+from __future__ import annotations
+
+import httpx
+import click
+
+from orithos_cli.config import get_config
+
+
+@click.group(name="agent")
+def agent_group() -> None:
+    """Manage Orithos agents."""
+    pass
+
+
+@agent_group.command("new")
+@click.option("--name", default="", help="Agent name (omit for interactive wizard)")
+def new_agent(name: str) -> None:
+    """Interactive agent setup — configure identity, prompt, tools, memory, guardrails."""
+    from orithos_cli.agent_wizard import interactive_agent_wizard
+
+    interactive_agent_wizard()
+
+
+@agent_group.command("create")
+@click.option("--name", default="", help="Agent name (omit for interactive wizard)")
+def create_agent(name: str) -> None:
+    """Create a new agent — interactive wizard by default."""
+    from orithos_cli.agent_wizard import interactive_agent_wizard
+
+    interactive_agent_wizard()
+
+
+@agent_group.command("list")
+def list_agents() -> None:
+    """List all registered agents."""
+    cfg = get_config()
+
+    try:
+        response = httpx.get(
+            f"{cfg.api_url}/v1/agents",
+            headers=cfg.auth_headers(),
+            timeout=cfg.timeout,
+        )
+        response.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        click.echo(f"Error: {exc.response.status_code} — {exc.response.text}", err=True)
+        raise SystemExit(1)
+    except httpx.RequestError as exc:
+        click.echo(f"Connection error: {exc}", err=True)
+        raise SystemExit(1)
+
+    agents = response.json()
+    if not agents:
+        click.echo("No agents found.")
+        return
+
+    for agent in agents:
+        click.echo(f"[{agent['id']}] {agent['name']} — {agent['endpoint_url']}")
+
+
+@agent_group.command("delete")
+@click.argument("agent-id")
+def delete_agent(agent_id: str) -> None:
+    """Delete an agent by ID."""
+    cfg = get_config()
+    try:
+        response = httpx.delete(
+            f"{cfg.api_url}/v1/agents/{agent_id}",
+            headers=cfg.auth_headers(),
+            timeout=cfg.timeout,
+        )
+        response.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        click.echo(f"Error: {exc.response.status_code} — {exc.response.text}", err=True)
+        raise SystemExit(1)
+    click.echo(f"Agent {agent_id[:8]} deleted.")

orithos_cli/agent_wizard.py

@@ -0,0 +1,255 @@
+"""Interactive agent wizard for Orithos CLI — 5 steps matching dashboard."""
+
+from __future__ import annotations
+
+import json
+import httpx
+import click
+
+from orithos_cli.config import get_config, fmt_http_error
+
+
+def _s(text: str = "", fg: str | None = None, dim: bool = False, bold: bool = False) -> str:
+    return click.style(text, fg=fg, dim=dim, bold=bold)
+
+
+PROVIDER_OPTIONS = [
+    ("Pinecone", "Pinecone", "Vector database"),
+    ("Weaviate", "Weaviate", "Vector database"),
+    ("Chroma", "Chroma", "Vector database"),
+    ("Milvus", "Milvus", "Vector database"),
+    ("Qdrant", "Qdrant", "Vector database"),
+    ("Pgvector", "Pgvector", "PostgreSQL vector extension"),
+]
+
+RAG_TYPE_OPTIONS = [
+    ("Vector Database", "Vector Database", "Embedding-based retrieval"),
+    ("Document Store", "Document Store", "Raw document storage"),
+    ("Knowledge Graph", "Knowledge Graph", "Graph-based retrieval"),
+]
+
+GUARDRAIL_PROVIDERS = [
+    ("NVIDIA NeMo Guardrails", "NeMo Guardrails", "NeMo"),
+    ("Llama Guard", "Llama Guard", "Meta safety model"),
+    ("Custom Classifier", "Custom Classifier", "Custom classifier endpoint"),
+    ("OpenAI Moderation", "OpenAI Moderation", "OpenAI moderation API"),
+]
+
+STAGE_OPTIONS = [
+    ("pre", "Pre", "Before agent inference"),
+    ("post", "Post", "After agent response"),
+    ("both", "Both", "Pre and post"),
+]
+
+TOOL_PARAM_TYPES = ["string", "number", "integer", "boolean", "object", "array"]
+
+
+def _pick(options: list[tuple[str, str, str]], prompt: str, default: int = 1) -> str:
+    for i, (_, label, desc) in enumerate(options, 1):
+        click.echo(f"  [{i}] {_s(label, bold=True)} \u2014 {_s(desc, dim=True)}")
+    choice = click.prompt(prompt, type=int, default=default)
+    if choice < 1 or choice > len(options):
+        choice = default
+    return options[choice - 1][0]
+
+
+def _confirm(prompt: str, default: bool = True) -> bool:
+    return click.confirm(_s(prompt, dim=True), default=default)
+
+
+def _risk_class(name: str, desc: str) -> str:
+    low = (name + " " + desc).lower()
+    critical_kw = ["refund", "payment", "transfer", "charge", "delete", "remove", "purge",
+                   "destroy", "create_user", "add_user", "grant", "elevate", "permission"]
+    write_kw = critical_kw + ["send", "message", "email", "notify", "write", "create",
+                               "update", "post", "admin", "access", "install", "deploy"]
+    if any(w in low for w in critical_kw):
+        return "write"
+    if any(w in low for w in write_kw):
+        return "write"
+    return "read"
+
+
+def interactive_agent_wizard() -> None:
+    cfg = get_config()
+
+    click.echo()
+    click.echo(_s("\u2726 Orithos Agent Wizard", fg="green", bold=True))
+    click.echo(_s("  Configure your agent step by step.", dim=True))
+    click.echo()
+
+    # === Step 1: Identity ===
+    click.echo(_s("Step 1/5: Identity", fg="green"))
+    name = click.prompt("  Agent name", default="")
+    if not name:
+        click.echo(_s("  Agent name is required.", fg="red"))
+        raise SystemExit(1)
+    version = click.prompt("  Version", default="1.0")
+    description = click.prompt("  Description", default="")
+    click.echo()
+
+    # === Step 2: System Prompt ===
+    click.echo(_s("Step 2/5: System Prompt", fg="green"))
+    click.echo(_s("  Paste the system prompt. Enter '.' on a blank line to finish.", dim=True))
+    lines: list[str] = []
+    while True:
+        line = input()
+        if line == ".":
+            break
+        lines.append(line)
+    system_prompt = "\n".join(lines).strip()
+
+    if system_prompt:
+        click.echo(_s("  Analysing prompt...", dim=True), nl=False)
+        try:
+            ar = httpx.post(
+                f"{cfg.api_url}/v1/agents/analyze-prompt",
+                json={"text": system_prompt},
+                headers=cfg.auth_headers(),
+                timeout=30,
+            )
+            if ar.status_code == 200:
+                analysis = ar.json()
+                constraints = analysis.get("constraints_count", 0)
+                identifiers = analysis.get("identifiers_count", 0)
+                probes = analysis.get("summary", {}).get("estimated_total_probes", 0)
+                leakage = analysis.get("leakage_risk", "low")
+                click.echo(_s(f" \u2713", fg="green"))
+                click.echo(_s(f"  \u21b3 {constraints} constraints \u00b7 {identifiers} identifiers \u00b7 ~{probes} probes \u00b7 leakage: {leakage}", dim=True))
+            else:
+                click.echo(_s(" \u2716 (analysis unavailable)", fg="yellow"))
+        except httpx.RequestError:
+            click.echo(_s(" \u2716 (analysis unavailable)", fg="yellow"))
+    click.echo()
+
+    # === Step 3: Tools ===
+    click.echo(_s("Step 3/5: Tools (optional)", fg="green"))
+    tools: list[dict] = []
+    if _confirm("  Add tools?"):
+        while True:
+            t_name = click.prompt("    Tool name", default="")
+            if not t_name:
+                break
+            t_desc = click.prompt("    Description", default="")
+            params: list[dict] = []
+            click.echo(_s("    Parameters (enter blank name to stop):", dim=True))
+            pi = 1
+            while True:
+                p_name = click.prompt(f"      param {pi} name", default="")
+                if not p_name:
+                    break
+                p_type = click.prompt(f"      param {pi} type", type=click.Choice(TOOL_PARAM_TYPES), default="string", show_choices=False)
+                params.append({"name": p_name, "type": p_type})
+                pi += 1
+
+            access = _risk_class(t_name, t_desc)
+            tools.append({
+                "name": t_name,
+                "description": t_desc,
+                "parameters": params,
+                "access_level": access,
+            })
+            click.echo(f"    Risk: {_s(access, dim=True)}")
+            if not _confirm("    Add another tool?", default=False):
+                break
+    click.echo()
+
+    # === Step 4: Memory & Guardrails ===
+    click.echo(_s("Step 4/5: Memory & Guardrails (optional)", fg="green"))
+    memory_sources: list[dict] = []
+    guardrails: list[dict] = []
+
+    if _confirm("  Add RAG source?"):
+        while True:
+            rag_name = click.prompt("    Source name", default="knowledge-base")
+            rag_provider = _pick(PROVIDER_OPTIONS, "    Provider")
+            rag_type = _pick(RAG_TYPE_OPTIONS, "    Type", default=1)
+            rag_docs = click.prompt("    Document count", type=int, default=0)
+            memory_sources.append({
+                "name": rag_name,
+                "type": rag_type,
+                "provider": rag_provider,
+                "doc_count": rag_docs,
+                "risk": "supply_chain",
+            })
+            if not _confirm("    Add another RAG source?", default=False):
+                break
+
+    if _confirm("  Add guardrail?"):
+        while True:
+            g_name = click.prompt("    Guardrail name", default="")
+            g_provider = _pick(GUARDRAIL_PROVIDERS, "    Provider")
+            g_stage = _pick(STAGE_OPTIONS, "    Stage")
+            guardrails.append({
+                "name": g_name,
+                "type": g_provider,
+                "stage": g_stage,
+                "enabled": True,
+            })
+            if not _confirm("    Add another guardrail?", default=False):
+                break
+    click.echo()
+
+    # === Step 5: Confirm & Save ===
+    click.echo(_s("Step 5/5: Confirm & Save", fg="green"))
+    tool_count = len(tools)
+    tool_names = ", ".join(t.get("name", "?") for t in tools[:3])
+    if tool_count > 3:
+        tool_names += f" +{tool_count - 3} more"
+    prompt_preview = system_prompt[:60].replace("\n", "\\n") + ("..." if len(system_prompt) > 60 else "")
+    prompt_tokens = max(1, len(system_prompt) // 4)
+
+    click.echo(_s("\u250c" + "\u2500" * 47 + "\u2510", dim=True))
+    for line in [
+        f" Name:        {name}",
+        f" Version:     {version}",
+        f" Description: {description[:40] or '(none)'}",
+        f" Prompt:      {prompt_tokens} tokens",
+        f" Tools:       {tool_names or 'none'}",
+        f" RAG sources: {len(memory_sources)}",
+        f" Guardrails:  {len(guardrails)}",
+    ]:
+        click.echo(_s(f"\u2502 {line:<45}\u2502", dim=True))
+    click.echo(_s("\u2514" + "\u2500" * 47 + "\u2518", dim=True))
+    click.echo()
+
+    if not _confirm("  Save agent?", default=True):
+        click.echo(_s("  Cancelled.", fg="yellow"))
+        return
+
+    payload: dict = {
+        "name": name,
+        "version": version,
+        "endpoint_url": "",
+    }
+    if description:
+        payload["description"] = description
+    if system_prompt:
+        payload["system_prompt"] = system_prompt
+    if tools:
+        payload["tools_config"] = tools
+    if memory_sources:
+        payload["memory_sources"] = memory_sources
+    if guardrails:
+        payload["guardrails"] = guardrails
+
+    try:
+        r = httpx.post(
+            f"{cfg.api_url}/v1/agents",
+            json=payload,
+            headers=cfg.auth_headers(),
+            timeout=cfg.timeout,
+        )
+        r.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        click.echo(_s(f"Error creating agent: {fmt_http_error(exc)}", fg="red"), err=True)
+        raise SystemExit(1)
+    except httpx.RequestError as exc:
+        click.echo(_s(f"Connection error: {exc}", fg="red"), err=True)
+        raise SystemExit(1)
+
+    data = r.json()
+    aid = data.get("id", "?")[:8]
+    click.echo(_s(f"\u2726 Agent created: {aid}", fg="green", bold=True))
+    click.echo(_s(f"  Name: {data.get('name', '?')}", dim=True))
+    click.echo(_s(f"  Tools: {len(tools)}  RAG: {len(memory_sources)}  Guardrails: {len(guardrails)}", dim=True))

orithos_cli/auth.py

@@ -0,0 +1,21 @@
+"""Authentication and request signing utilities for Orithos CLI."""
+
+import os
+import hmac
+import hashlib
+import time
+
+
+def sign_request(method: str, path: str, body: bytes = b"") -> dict:
+    """Add HMAC-SHA256 signature headers to a request."""
+    key = os.environ.get("TRACESHIELD_REQUEST_SIGNING_KEY", "")
+    if not key:
+        return {}  # No signing in dev mode
+
+    timestamp = int(time.time())
+    payload = f"{timestamp}.{method}.{path}.{hashlib.sha256(body).hexdigest()}".encode()
+    signature = hmac.new(key.encode(), payload, hashlib.sha256).hexdigest()
+    return {
+        "X-Orithos-Timestamp": str(timestamp),
+        "X-Orithos-Signature": f"t={timestamp},v1={signature}",
+    }

orithos_cli/cli.py

@@ -0,0 +1,82 @@
+"""Orithos CLI — main entry point."""
+
+import click
+
+from orithos_cli.configure import configure
+from orithos_cli.agent import agent_group
+from orithos_cli.compliance import compliance_group
+from orithos_cli.connection import connection_group
+from orithos_cli.discovery import discovery_group
+from orithos_cli.graph import graph_group
+from orithos_cli.guardrail import guardrail_group
+from orithos_cli.mcp import mcp_group
+from orithos_cli.probes import probes_group
+from orithos_cli.remediation import remediation_group
+from orithos_cli.runtime import alerting_group, runtime_group
+from orithos_cli.scan import scan_group
+from orithos_cli.skill import skill_group
+from orithos_cli.template import template_group
+from orithos_cli.verify import verify_package_file
+
+
+@click.group()
+@click.version_option(version="0.1.0", prog_name="orithos")
+def main() -> None:
+    """Orithos CLI — AI Agent Security Testing Platform.
+
+    Quick start: orithos configure
+
+    Environment variables (override config file):
+    ORITHOS_API_KEY     API key (tsk_...)
+    ORITHOS_API_URL     API base URL (overrides default https://api.orithos.com)
+    ORITHOS_ORG_ID      Organisation ID (optional override)
+    ORITHOS_TIMEOUT     Request timeout in seconds (default: 30)
+    """
+    pass
+
+
+@main.command("verify")
+@click.argument("package_file", type=click.Path(exists=True, dir_okay=False))
+def verify_cmd(package_file: str) -> None:
+    """Verify an evidence package offline (hashes + Merkle root).
+
+    Recomputes every artifact hash and the Merkle root from the package
+    content and compares against the declared manifest. No network access,
+    no Orithos contact — independent verifiability for auditors.
+    """
+    from pathlib import Path
+
+    result = verify_package_file(Path(package_file))
+    if result["ok"]:
+        click.echo("OK — package integrity verified")
+    else:
+        click.echo("FAIL — package integrity check failed")
+        for err in result["errors"]:
+            click.echo(f"  - {err}")
+    for art in result.get("artifacts", []):
+        click.echo(f"  {art['name']}: {art['sha256'][:16]}…")
+    if result.get("merkle_root"):
+        click.echo(f"  merkle root: {result['merkle_root'][:16]}…")
+    if not result["ok"]:
+        raise SystemExit(1)
+
+
+main.add_command(configure)
+main.add_command(agent_group)
+main.add_command(scan_group)
+main.add_command(remediation_group)
+main.add_command(guardrail_group)
+main.add_command(graph_group)
+main.add_command(runtime_group)
+main.add_command(alerting_group)
+main.add_command(discovery_group)
+main.add_command(connection_group)
+main.add_command(template_group)
+main.add_command(probes_group)
+main.add_command(compliance_group)
+main.add_command(mcp_group)
+main.add_command(skill_group)
+
+
+if __name__ == "__main__":
+    main()

orithos_cli/compliance.py

@@ -0,0 +1,133 @@
+"""Compliance mapping and reporting commands."""
+
+from __future__ import annotations
+
+import json
+
+import click
+import httpx
+
+from orithos_cli.config import get_config
+
+
+@click.group(name="compliance")
+def compliance_group() -> None:
+    """View compliance mappings and generate compliance reports."""
+    pass
+
+
+@compliance_group.command("mappings")
+@click.option(
+    "--framework", help="Filter by framework (OWASP_LLM, NIST_AI_RMF, MITRE_ATLAS, CWE)"
+)
+@click.option(
+    "--format", "output_format", type=click.Choice(["table", "json"]), default="table"
+)
+def list_mappings(framework: str | None, output_format: str) -> None:
+    """List all compliance mappings for the organisation."""
+    cfg = get_config()
+
+    try:
+        response = httpx.get(
+            f"{cfg.api_url}/v1/compliance/mappings",
+            headers=cfg.auth_headers(),
+            timeout=cfg.timeout,
+        )
+        response.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        click.echo(f"Error: {exc.response.status_code} — {exc.response.text}", err=True)
+        raise SystemExit(1)
+    except httpx.RequestError as exc:
+        click.echo(f"Connection error: {exc}", err=True)
+        raise SystemExit(1)
+
+    data = response.json()
+    # GET /v1/compliance/mappings returns {"mappings": [...], "total": N}.
+    mappings = (data.get("mappings") or []) if isinstance(data, dict) else data
+
+    if framework:
+        mappings = [m for m in mappings if m.get("framework") == framework]
+
+    if output_format == "json":
+        click.echo(json.dumps(mappings, indent=2))
+        return
+
+    frameworks = sorted(set(m["framework"] for m in mappings))
+    click.echo(
+        f"Compliance Mappings ({len(mappings)} total across {len(frameworks)} frameworks)"
+    )
+    click.echo(f"{'=' * 70}")
+
+    for fw in frameworks:
+        fw_mappings = [m for m in mappings if m["framework"] == fw]
+        click.echo(f"\n{fw} ({len(fw_mappings)} controls)")
+        click.echo("-" * 50)
+        for m in fw_mappings:
+            click.echo(f"  [{m['control_id']}] {m['control_name']}")
+            click.echo(f"    Severity mapping: {m['severity_mapping']}")
+            click.echo(f"    {m['description'][:80]}...")
+
+
+@compliance_group.command("report")
+@click.argument("scan_id")
+@click.option(
+    "--framework", help="Filter by framework (OWASP_LLM, NIST_AI_RMF, MITRE_ATLAS, CWE)"
+)
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["summary", "json"]),
+    default="summary",
+)
+def compliance_report(scan_id: str, framework: str | None, output_format: str) -> None:
+    """Generate a compliance report for a completed scan."""
+    cfg = get_config()
+
+    try:
+        response = httpx.get(
+            f"{cfg.api_url}/v1/compliance/report/{scan_id}",
+            headers=cfg.auth_headers(),
+            timeout=cfg.timeout,
+        )
+        response.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        click.echo(f"Error: {exc.response.status_code} — {exc.response.text}", err=True)
+        raise SystemExit(1)
+    except httpx.RequestError as exc:
+        click.echo(f"Connection error: {exc}", err=True)
+        raise SystemExit(1)
+
+    report = response.json()
+
+    if output_format == "json":
+        click.echo(json.dumps(report, indent=2))
+        return
+
+    summary = report.get("summary", {})
+    click.echo(f"Orithos Compliance Report — Scan {scan_id}")
+    click.echo(f"{'=' * 60}")
+    click.echo(f"Total findings: {summary.get('total_findings', 0)}")
+    click.echo(f"High-risk findings: {summary.get('high_risk_findings', 0)}")
+    click.echo(
+        f"Frameworks with findings: {', '.join(summary.get('frameworks_with_findings', [])) or 'None'}"
+    )
+    click.echo("")
+
+    by_framework = report.get("by_framework", {})
+    if framework:
+        frameworks_to_show = [framework] if framework in by_framework else []
+    else:
+        frameworks_to_show = sorted(by_framework.keys())
+
+    for fw in frameworks_to_show:
+        controls = by_framework.get(fw, [])
+        if not controls:
+            continue
+        click.echo(f"\n{fw} ({len(controls)} findings)")
+        click.echo("-" * 50)
+        for c in controls:
+            # get_compliance_report returns control_id/control_name/our_severity
+            # (no remediation_guidance — removed with the regex-mapping rewrite).
+            click.echo(
+                f"  [{c['control_id']}] {c['control_name']} — severity: {c.get('our_severity', 'N/A')}"
+            )

orithos_cli/config.py

@@ -0,0 +1,114 @@
+"""Configuration management for Orithos CLI.
+
+Read order: CLI flag > env var > config file > default.
+Config file: ~/.orithos/config.json
+"""
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+
+
+CONFIG_DIR = Path.home() / ".orithos"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+DEFAULT_API_URL = "https://api.orithos.com"
+
+
+@dataclass
+class CLIConfig:
+    api_url: str
+    org_id: str
+    timeout: float
+    api_key: str
+
+    @classmethod
+    def from_env(cls) -> "CLIConfig":
+        file_cfg = _read_config_file()
+        return cls(
+            api_url=(
+                os.environ.get("ORITHOS_API_URL")
+                or os.environ.get("TRACESHIELD_API_URL")
+                or file_cfg.get("api_url", "")
+                or DEFAULT_API_URL
+            ),
+            org_id=(
+                os.environ.get("ORITHOS_ORG_ID")
+                or os.environ.get("TRACESHIELD_ORG_ID")
+                or file_cfg.get("org_id", "org_demo")
+            ),
+            timeout=float(
+                os.environ.get("ORITHOS_TIMEOUT")
+                or os.environ.get("TRACESHIELD_TIMEOUT")
+                or file_cfg.get("timeout", "30")
+            ),
+            api_key=(
+                os.environ.get("ORITHOS_API_KEY")
+                or os.environ.get("TRACESHIELD_INTERNAL_API_KEY")
+                or file_cfg.get("api_key", "")
+            ),
+        )
+
+    def auth_headers(self) -> dict[str, str]:
+        headers = {"x-org-id": self.org_id}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "api_url": self.api_url,
+            "org_id": self.org_id,
+            "timeout": str(self.timeout),
+            "api_key": self.api_key,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, str]) -> "CLIConfig":
+        return cls(
+            api_url=d.get("api_url", DEFAULT_API_URL),
+            org_id=d.get("org_id", "org_demo"),
+            timeout=float(d.get("timeout", "30")),
+            api_key=d.get("api_key", ""),
+        )
+
+
+CONFIG: CLIConfig | None = None
+
+
+def get_config() -> CLIConfig:
+    global CONFIG
+    if CONFIG is None:
+        CONFIG = CLIConfig.from_env()
+    return CONFIG
+
+
+def _read_config_file() -> dict[str, str]:
+    try:
+        if CONFIG_FILE.exists():
+            with open(CONFIG_FILE) as f:
+                return json.load(f)
+    except (json.JSONDecodeError, OSError):
+        pass
+    return {}
+
+
+def write_config(cfg: CLIConfig) -> Path:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    with open(CONFIG_FILE, "w") as f:
+        json.dump(cfg.to_dict(), f, indent=2)
+    return CONFIG_FILE
+
+
+def fmt_http_error(exc: httpx.HTTPStatusError) -> str:
+    """Extract a clean detail message from an HTTP error response."""
+    try:
+        body = exc.response.json()
+        msg = body.get("detail") or body.get("message") or body.get("error") or ""
+        if msg:
+            return f"{exc.response.status_code} — {msg}"
+    except (json.JSONDecodeError, AttributeError):
+        pass
+    return f"{exc.response.status_code} — {exc.response.text[:200]}"