devrel-origin 0.2.14__py3-none-any.whl

devrel_origin/cli/auth.py

@@ -0,0 +1,227 @@
+"""`devrel auth` - configure or rotate the LLM API key for this project.
+
+Writes the chosen key to `.devrel/.env` (chmod 600) so subsequent CLI
+commands pick it up via the auto-loader in `_common._load_project_env`.
+Validates the key with a tiny ping call by default; pass `--no-validate`
+to skip when offline or working with credit-metered keys.
+
+Provider resolution:
+- `--provider anthropic` or `--provider openrouter` is explicit
+- Without `--provider`, prompts in interactive mode; defaults to anthropic
+  in non-interactive mode (preserves prior CLI default)
+
+Key handling:
+- `--key VALUE` accepts the key on the command line (history risk; OK for CI)
+- Without `--key`, prompts with hidden input
+- `--rotate` lets the user replace an existing key for the same provider;
+  without it, an existing key for the chosen provider blocks (use --rotate
+  to overwrite or pick a different provider)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import stat
+from pathlib import Path
+
+import typer
+from dotenv import dotenv_values, set_key
+from rich.console import Console
+
+from devrel_origin.cli._common import find_paths_or_exit
+from devrel_origin.core.llm import LLMClient
+from devrel_origin.project.paths import ProjectPaths
+
+console = Console()
+
+PROVIDER_ANTHROPIC = "anthropic"
+PROVIDER_OPENROUTER = "openrouter"
+PROVIDERS = (PROVIDER_ANTHROPIC, PROVIDER_OPENROUTER)
+KEY_VAR = {
+    PROVIDER_ANTHROPIC: "ANTHROPIC_API_KEY",
+    PROVIDER_OPENROUTER: "OPENROUTER_API_KEY",
+}
+SIGNUP_URL = {
+    PROVIDER_ANTHROPIC: "https://console.anthropic.com/settings/keys",
+    PROVIDER_OPENROUTER: "https://openrouter.ai/keys",
+}
+
+
+def _ensure_env_file(env_file: Path) -> None:
+    """Touch .devrel/.env if it doesn't exist and lock it to 0600."""
+    env_file.parent.mkdir(parents=True, exist_ok=True)
+    if not env_file.is_file():
+        env_file.touch()
+    # chmod 600 unconditionally so the file is locked down even if it
+    # pre-existed at a looser permission. POSIX-only; no-op on Windows
+    # but the perm bits are advisory there anyway.
+    try:
+        env_file.chmod(stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:
+        pass
+
+
+def _existing_key(env_file: Path, var: str) -> str:
+    if not env_file.is_file():
+        return ""
+    return (dotenv_values(env_file).get(var) or "").strip()
+
+
+async def _validate(provider: str, key: str) -> tuple[bool, str]:
+    """One-token ping. Returns (ok, error_message)."""
+    try:
+        if provider == PROVIDER_ANTHROPIC:
+            client = LLMClient(provider=PROVIDER_ANTHROPIC, api_key=key)
+        else:
+            client = LLMClient(provider=PROVIDER_OPENROUTER, openrouter_api_key=key)
+        try:
+            await client.generate(
+                system_prompt="Reply with the single word: ok",
+                user_prompt="ping",
+                max_tokens=5,
+                temperature=0.0,
+            )
+        finally:
+            await client.aclose()
+        return True, ""
+    except Exception as exc:  # noqa: BLE001 - surface any auth error to the user
+        return False, str(exc)
+
+
+def _resolve_provider(
+    arg: str | None,
+    *,
+    non_interactive: bool,
+) -> str:
+    if arg:
+        if arg not in PROVIDERS:
+            console.print(
+                f"[red]Unknown provider '{arg}'. Choose one of: {', '.join(PROVIDERS)}.[/red]"
+            )
+            raise typer.Exit(code=1)
+        return arg
+    if non_interactive:
+        return PROVIDER_ANTHROPIC
+    console.print("Pick an LLM provider:")
+    console.print("  [bold]1[/bold]) anthropic   (https://console.anthropic.com/settings/keys)")
+    console.print(
+        "  [bold]2[/bold]) openrouter  (https://openrouter.ai/keys, free credits available)"
+    )
+    choice = typer.prompt("Provider [1/2]", default="1").strip()
+    return PROVIDER_OPENROUTER if choice in ("2", "openrouter", "or") else PROVIDER_ANTHROPIC
+
+
+def _resolve_key(
+    provider: str,
+    *,
+    arg: str | None,
+    non_interactive: bool,
+    rotating: bool,
+    existing: str,
+) -> str:
+    if arg:
+        return arg.strip()
+    if non_interactive:
+        console.print(
+            f"[red]--key is required in --non-interactive mode. "
+            f"Pass --key <value> or set {KEY_VAR[provider]}.[/red]"
+        )
+        raise typer.Exit(code=1)
+    if existing and not rotating:
+        console.print(
+            f"[yellow]A {KEY_VAR[provider]} is already set in .devrel/.env. "
+            f"Pass --rotate to replace it, or pick a different provider.[/yellow]"
+        )
+        raise typer.Exit(code=1)
+    label = "Paste new" if existing else "Paste"
+    return typer.prompt(
+        f"{label} {KEY_VAR[provider]} (input hidden)",
+        hide_input=True,
+    ).strip()
+
+
+def auth_command(
+    provider: str = typer.Option(
+        "",
+        "--provider",
+        help="LLM provider: anthropic or openrouter. Prompts if omitted.",
+    ),
+    key: str = typer.Option(
+        "",
+        "--key",
+        help="API key (skip the prompt; not recommended interactively).",
+    ),
+    rotate: bool = typer.Option(
+        False, "--rotate", help="Replace an existing key for the same provider."
+    ),
+    no_validate: bool = typer.Option(
+        False, "--no-validate", help="Skip the ping call that verifies the key."
+    ),
+    non_interactive: bool = typer.Option(
+        False,
+        "--non-interactive",
+        help="Fail instead of prompting when --provider or --key is missing.",
+    ),
+) -> None:
+    """Configure (or rotate) the LLM API key for this project."""
+    paths: ProjectPaths = find_paths_or_exit(console)
+    chosen = _resolve_provider(provider or None, non_interactive=non_interactive)
+    var = KEY_VAR[chosen]
+    existing = _existing_key(paths.env_file, var)
+    new_key = _resolve_key(
+        chosen,
+        arg=key or None,
+        non_interactive=non_interactive,
+        rotating=rotate,
+        existing=existing,
+    )
+    if not new_key:
+        console.print("[red]Empty key; nothing to do.[/red]")
+        raise typer.Exit(code=1)
+
+    if not no_validate:
+        console.print(f"Validating {var} against {chosen}...")
+        ok, err = asyncio.run(_validate(chosen, new_key))
+        if not ok:
+            console.print(f"[red]Validation failed:[/red] {err}")
+            console.print(
+                "[dim]Pass --no-validate to write the key anyway "
+                "(useful for offline or rate-limited setups).[/dim]"
+            )
+            raise typer.Exit(code=1)
+        console.print("[green]✓[/green] key validated")
+
+    _ensure_env_file(paths.env_file)
+    set_key(str(paths.env_file), var, new_key, quote_mode="never")
+    # Re-apply 0600 in case set_key recreated the file with default perms.
+    try:
+        paths.env_file.chmod(stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:
+        pass
+
+    masked = new_key[:4] + "..." + new_key[-4:] if len(new_key) > 8 else "***"
+    rel = paths.env_file
+    try:
+        rel = paths.env_file.relative_to(paths.root)
+    except ValueError:
+        pass
+    verb = "rotated" if existing else "saved"
+    console.print(f"[green]✓[/green] {verb} {var}={masked} to {rel} (mode 0600)")
+    console.print()
+    console.print("Next steps:")
+    console.print(
+        "  1. [cyan]devrel doctor[/cyan]                    confirm everything is wired up"
+    )
+    console.print(
+        '  2. [cyan]devrel content draft "..."[/cyan]      ship your first grounded draft'
+    )
+    if chosen == PROVIDER_ANTHROPIC:
+        console.print(
+            "[dim]Tip: switch providers with `devrel auth --provider openrouter` "
+            "(free credits at https://openrouter.ai/).[/dim]"
+        )
+
+    # Make the key visible in the current process env too, in case the user
+    # immediately runs another devrel verb in the same shell pipeline.
+    os.environ[var] = new_key

devrel_origin/cli/config.py

@@ -0,0 +1,108 @@
+"""`devrel config {get, set}` — read/write .devrel/config.toml values.
+
+Dotted keys (e.g. `budget.monthly_usd`) navigate nested tables. `set`
+performs naive type coercion: int / float / "true"|"false" / fallback to
+string. The TOML file is round-tripped via tomllib (read) + tomli_w
+(write); comments are not preserved (acceptable for a setter).
+"""
+
+from __future__ import annotations
+
+import json
+import tomllib
+from pathlib import Path
+from typing import Any
+
+import tomli_w
+import typer
+from rich.console import Console
+
+from devrel_origin.cli._common import find_paths_or_exit
+
+console = Console()
+
+config_app = typer.Typer(
+    name="config",
+    help="Read and write .devrel/config.toml values by dotted key.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _coerce(value: str) -> Any:
+    """Coerce a string from the CLI into int / float / bool / str."""
+    s = value.strip()
+    if s.lower() == "true":
+        return True
+    if s.lower() == "false":
+        return False
+    # int (no leading sign issues, no underscore, no decimal point)
+    try:
+        if s and (s[0] in "+-" or s[0].isdigit()):
+            if "." not in s and "e" not in s.lower():
+                return int(s)
+            return float(s)
+    except ValueError:
+        pass
+    return s
+
+
+def _get_nested(d: dict, key: str) -> Any:
+    cur: Any = d
+    for part in key.split("."):
+        if not isinstance(cur, dict) or part not in cur:
+            raise KeyError(key)
+        cur = cur[part]
+    return cur
+
+
+def _set_nested(d: dict, key: str, value: Any) -> None:
+    parts = key.split(".")
+    cur = d
+    for part in parts[:-1]:
+        if part not in cur or not isinstance(cur[part], dict):
+            cur[part] = {}
+        cur = cur[part]
+    cur[parts[-1]] = value
+
+
+def _load(path: Path) -> dict:
+    with path.open("rb") as f:
+        return tomllib.load(f)
+
+
+def _dump(path: Path, data: dict) -> None:
+    with path.open("wb") as f:
+        tomli_w.dump(data, f)
+
+
+@config_app.command("get")
+def get_value(
+    key: str = typer.Argument(..., help="Dotted key (e.g. 'project.name', 'budget.monthly_usd')."),
+) -> None:
+    """Read a config value."""
+    paths = find_paths_or_exit(console)
+    data = _load(paths.config_file)
+    try:
+        val = _get_nested(data, key)
+    except KeyError:
+        console.print(f"[red]Key not found: {key}[/red]")
+        raise typer.Exit(code=1) from None
+    if isinstance(val, (dict, list)):
+        typer.echo(json.dumps(val, indent=2))
+    else:
+        typer.echo(str(val))
+
+
+@config_app.command("set")
+def set_value(
+    key: str = typer.Argument(..., help="Dotted key to set."),
+    value: str = typer.Argument(..., help="Value (int/float/true/false/string auto-detected)."),
+) -> None:
+    """Write a config value (round-trips via tomli_w; comments not preserved)."""
+    paths = find_paths_or_exit(console)
+    data = _load(paths.config_file)
+    coerced = _coerce(value)
+    _set_nested(data, key, coerced)
+    _dump(paths.config_file, data)
+    console.print(f"[green]✓[/green] {key} = {coerced!r}  ({type(coerced).__name__})")

devrel_origin/cli/content.py

@@ -0,0 +1,259 @@
+"""`devrel content draft|audit` — primary entry points to the editorial pipeline."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import re
+from contextlib import suppress
+from datetime import datetime, timezone
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from devrel_origin.cli._common import _build_llm_client as _build_project_llm_client
+from devrel_origin.core.kai import Kai
+from devrel_origin.core.llm import LLMClient
+from devrel_origin.project.paths import ProjectNotFoundError, ProjectPaths, find_devrel_root
+from devrel_origin.quality.editorial import AbortLoud, run_pipeline
+from devrel_origin.quality.slop import find_slop, parse_blocklist
+from devrel_origin.tools.api_client import PostHogClient
+from devrel_origin.tools.search_tools import SearchTools
+
+console = Console()
+
+content_app = typer.Typer(
+    name="content",
+    help="Generate and audit content through the editorial quality pipeline.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _build_llm_client(paths: ProjectPaths) -> LLMClient:
+    return _build_project_llm_client(paths, console)
+
+
+def _build_kai(paths: ProjectPaths, llm_client: LLMClient) -> Kai:
+    """Wire Kai with the same KB + optional search-tools the weekly cycle uses,
+    so `devrel content draft` produces grounded, code-validated output instead
+    of an editorial-pipeline pass over a generic LLM draft."""
+    posthog = PostHogClient(
+        api_key=os.environ.get("POSTHOG_API_KEY", ""),
+        project_id=os.environ.get("POSTHOG_PROJECT_ID", ""),
+    )
+    search_tools: SearchTools | None = None
+    if (
+        os.environ.get("FIRECRAWL_API_KEY", "").strip()
+        or os.environ.get("BRAVE_API_KEY", "").strip()
+    ):
+        search_tools = SearchTools(
+            firecrawl_api_key=os.environ.get("FIRECRAWL_API_KEY", ""),
+            brave_api_key=os.environ.get("BRAVE_API_KEY", ""),
+        )
+    return Kai(
+        api_client=posthog,
+        knowledge_base_path=paths.kb_dir,
+        llm_client=llm_client,
+        search_tools=search_tools,
+    )
+
+
+def _slug(text: str) -> str:
+    s = re.sub(r"[^a-zA-Z0-9]+", "-", text.lower()).strip("-")
+    return s[:48] or "draft"
+
+
+def _write_outputs(paths: ProjectPaths, slug: str, body: str, trace: dict) -> tuple[Path, Path]:
+    paths.deliverables_dir.mkdir(parents=True, exist_ok=True)
+    ts = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+    body_path = paths.deliverables_dir / f"{ts}-{slug}.md"
+    trace_path = paths.deliverables_dir / f"{ts}-{slug}-trace.json"
+    body_path.write_text(body)
+    trace_path.write_text(json.dumps(trace, indent=2))
+    return body_path, trace_path
+
+
+@content_app.command("draft")
+def draft_command(
+    prompt: str = typer.Argument(..., help="Topic or instruction for the new content."),
+    content_type: str = typer.Option(
+        "tutorial",
+        "--type",
+        help="Content type for targeting (tutorial, blog_post, landing_page, cold_email, battle_card).",
+    ),
+    timeout_seconds: float = typer.Option(
+        600.0,
+        "--timeout",
+        min=0.1,
+        help="Maximum seconds to wait for Kai before exiting with a clear timeout.",
+    ),
+    editorial_mode: str = typer.Option(
+        "fast",
+        "--editorial-mode",
+        help="Generation path: fast for a bounded first draft, full for the full editorial pipeline.",
+    ),
+) -> None:
+    """Generate new content through Kai: KB-grounded prompt + grounding/code validation."""
+    editorial_mode = editorial_mode.strip().lower()
+    if editorial_mode == "full":
+        editorial_mode = "pipeline"
+    if editorial_mode not in {"fast", "pipeline"}:
+        console.print("[red]--editorial-mode must be 'fast' or 'full'.[/red]")
+        raise typer.Exit(code=1)
+
+    try:
+        root = find_devrel_root()
+    except ProjectNotFoundError as e:
+        console.print(f"[red]{e}[/red]")
+        raise typer.Exit(code=1) from None
+    paths = ProjectPaths.from_root(root)
+    client = _build_llm_client(paths)
+    kai = _build_kai(paths, client)
+
+    async def _do() -> None:
+        console.print(
+            f"[cyan]Generating with Kai[/cyan] "
+            f"({content_type}, {editorial_mode}, timeout {timeout_seconds:g}s)..."
+        )
+
+        async def _heartbeat() -> None:
+            elapsed = 0
+            while True:
+                await asyncio.sleep(30)
+                elapsed += 30
+                console.print(f"[dim]Still generating... {elapsed}s elapsed[/dim]")
+
+        heartbeat = asyncio.create_task(_heartbeat())
+        try:
+            result = await asyncio.wait_for(
+                kai.execute(
+                    task=prompt,
+                    content_type=content_type,
+                    editorial_mode=editorial_mode,
+                ),
+                timeout=timeout_seconds,
+            )
+        except TimeoutError:
+            console.print(
+                f"[red]Kai timed out after {timeout_seconds:g}s.[/red] "
+                "Try a narrower prompt, add more focused KB evidence, or increase --timeout."
+            )
+            raise typer.Exit(code=1) from None
+        finally:
+            heartbeat.cancel()
+            with suppress(asyncio.CancelledError):
+                await heartbeat
+
+        status = result.get("status")
+        body = result.get("content") or ""
+        if status != "generated" or not body:
+            console.print(f"[red]Kai did not produce content (status={status}).[/red]")
+            for gap in result.get("evidence_gaps", []):
+                console.print(f"  - {gap}")
+            if result.get("error"):
+                console.print(f"  error: {result['error']}")
+            raise typer.Exit(code=1)
+
+        trace = {
+            "agent": "kai",
+            "task": result.get("task"),
+            "content_type": content_type,
+            "editorial_mode": result.get("editorial_mode", editorial_mode),
+            "grounding_sources": result.get("grounding_sources", []),
+            "pain_points_addressed": result.get("pain_points_addressed", []),
+            "real_issues_referenced": result.get("real_issues_referenced", []),
+            "revision": result.get("revision", {}),
+            "code_validation": result.get("code_validation", {}),
+            "grounding_validation": result.get("grounding_validation", {}),
+            "status": status,
+        }
+        body_path, trace_path = _write_outputs(paths, _slug(prompt), body, trace)
+        console.print(f"[green]✓[/green] Wrote {body_path.name} ({len(body)} chars)")
+        console.print(f"[green]✓[/green] Wrote {trace_path.name}")
+
+        sources = result.get("grounding_sources") or []
+        if sources:
+            console.print(f"[green]✓[/green] Grounded in {len(sources)} KB doc(s)")
+        else:
+            console.print(
+                "[yellow]⚠[/yellow] No KB sources matched the prompt; "
+                "output may be ungrounded. Run `devrel kb add` to populate the KB."
+            )
+
+        cv = result.get("code_validation") or {}
+        if cv and not cv.get("all_passed", True):
+            console.print(
+                f"[yellow]⚠[/yellow] Code validation: "
+                f"{cv.get('failed', 0)}/{cv.get('validated', 0)} blocks failed syntax checks"
+            )
+
+    asyncio.run(_do())
+
+
+@content_app.command("slop")
+def slop_command(
+    file: Path = typer.Argument(..., exists=True, readable=True, help="File to lint for slop."),
+) -> None:
+    """Run the deterministic regex slop blocklist against a file. Exits
+    nonzero if any blocklisted phrase is hit. No LLM calls."""
+    try:
+        root = find_devrel_root()
+    except ProjectNotFoundError as e:
+        console.print(f"[red]{e}[/red]")
+        raise typer.Exit(code=1) from None
+    paths = ProjectPaths.from_root(root)
+    if not paths.slop_file.is_file():
+        console.print(f"[red]No slop blocklist at {paths.slop_file}[/red]")
+        raise typer.Exit(code=1)
+    blocklist = parse_blocklist(paths.slop_file.read_text())
+    text = file.read_text()
+    hits = find_slop(text, blocklist)
+    if not hits:
+        console.print(
+            f"[green]✓[/green] {file.name}: no slop hits ({len(blocklist)} phrases checked)"
+        )
+        return
+    console.print(f"[red]✗[/red] {file.name}: {len(hits)} slop hit(s)")
+    for h in hits[:50]:
+        console.print(f"  [yellow]{h.phrase!r}[/yellow] at offset {h.start}")
+    raise typer.Exit(code=1)
+
+
+@content_app.command("audit")
+def audit_command(
+    file: Path = typer.Argument(..., exists=True, readable=True, help="Existing draft to audit."),
+    content_type: str = typer.Option("tutorial", "--type"),
+) -> None:
+    """Run the editorial pipeline against an existing draft file."""
+    try:
+        root = find_devrel_root()
+    except ProjectNotFoundError as e:
+        console.print(f"[red]{e}[/red]")
+        raise typer.Exit(code=1) from None
+    paths = ProjectPaths.from_root(root)
+    client = _build_llm_client(paths)
+
+    async def _do() -> None:
+        body = file.read_text()
+        try:
+            result = await run_pipeline(
+                initial_draft=body,
+                content_type=content_type,
+                project_paths=paths,
+                llm_client=client,
+            )
+        except AbortLoud as e:
+            console.print(f"[red]Pipeline aborted: {e}[/red]")
+            raise typer.Exit(code=1) from None
+        body_path, trace_path = _write_outputs(
+            paths, _slug(file.stem), result.final_text, result.revision_trace
+        )
+        console.print(f"[green]✓[/green] Wrote {body_path.name}")
+        console.print(f"[green]✓[/green] Wrote {trace_path.name}")
+        if result.flagged:
+            console.print("[yellow]⚠[/yellow] Flagged.")
+
+    asyncio.run(_do())

devrel_origin/cli/cost.py

@@ -0,0 +1,108 @@
+"""`devrel cost` — read the costs ledger from .devrel/state.db.
+
+Reads the SQLite `costs` table populated by the LLM cost sink (Phase 4
+Task 1). Reports total spend in USD, plus a per-agent breakdown. No
+ANTHROPIC_API_KEY required — this only reads local state.
+"""
+
+from __future__ import annotations
+
+import json
+
+import typer
+from rich.console import Console
+
+from devrel_origin.cli._common import find_paths_or_exit
+from devrel_origin.project.state import open_db
+
+console = Console()
+
+
+def cost_command(
+    month: str = typer.Option(
+        "",
+        "--month",
+        help="Filter to a YYYY-MM slice (e.g., '2026-04').",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+) -> None:
+    """Show recorded LLM cost totals from the project state DB."""
+    paths = find_paths_or_exit(console)
+    if not paths.state_db.is_file():
+        console.print("[yellow]No state.db yet. Run an agent first.[/yellow]")
+        if json_output:
+            typer.echo(
+                json.dumps(
+                    {
+                        "total_usd": 0.0,
+                        "by_agent": {},
+                        "calls": 0,
+                        "month_filter": month or None,
+                    }
+                )
+            )
+        return
+
+    # Build a parameterised WHERE clause. The `where` literal is one of two
+    # fixed strings we control — user input flows only through `params`,
+    # so SQL injection is impossible.
+    where = ""
+    params: tuple = ()
+    if month:
+        where = "WHERE recorded_at LIKE ?"
+        params = (f"{month}%",)
+
+    with open_db(paths.state_db) as conn:
+        total_row = conn.execute(
+            f"SELECT COALESCE(SUM(cost_usd), 0.0) AS total, COUNT(*) AS calls FROM costs {where}",
+            params,
+        ).fetchone()
+        total_usd = float(total_row["total"]) if total_row else 0.0
+        calls = int(total_row["calls"]) if total_row else 0
+
+        by_agent_rows = conn.execute(
+            f"SELECT agent, "
+            f"COALESCE(SUM(cost_usd), 0.0) AS usd, "
+            f"COALESCE(SUM(input_tokens), 0) AS in_tok, "
+            f"COALESCE(SUM(output_tokens), 0) AS out_tok, "
+            f"COUNT(*) AS calls "
+            f"FROM costs {where} GROUP BY agent ORDER BY usd DESC",
+            params,
+        ).fetchall()
+
+    by_agent = {
+        r["agent"]: {
+            "usd": float(r["usd"]),
+            "input_tokens": int(r["in_tok"]),
+            "output_tokens": int(r["out_tok"]),
+            "calls": int(r["calls"]),
+        }
+        for r in by_agent_rows
+    }
+
+    if json_output:
+        typer.echo(
+            json.dumps(
+                {
+                    "total_usd": total_usd,
+                    "calls": calls,
+                    "by_agent": by_agent,
+                    "month_filter": month or None,
+                },
+                indent=2,
+            )
+        )
+        return
+
+    suffix = f" for {month}" if month else ""
+    console.print(f"[bold]Total{suffix}:[/bold] ${total_usd:.4f}  [dim]({calls} call(s))[/dim]")
+    if not by_agent:
+        console.print("[dim]No cost rows yet.[/dim]")
+        return
+    console.print("\n[bold]By agent:[/bold]")
+    for agent, row in by_agent.items():
+        console.print(
+            f"  {agent:>10s}  ${row['usd']:.4f}  "
+            f"[dim]in={row['input_tokens']} out={row['output_tokens']} "
+            f"calls={row['calls']}[/dim]"
+        )