spooling 0.2.9__tar.gz → 0.2.11__tar.gz

{spooling-0.2.9/spooling.egg-info → spooling-0.2.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spooling
-Version: 0.2.9
+Version: 0.2.11
 Summary: Local session tracker and semantic search for AI coding assistants
 Author: Parsed Analytics, Inc.
 License: MIT
@@ -155,6 +155,29 @@ spooling stats --week      # Weekly breakdown
 spooling stats --days 30   # Last 30 days
 ```
 
+### `spooling tools`, `spooling agents`, `spooling traces`
+
+See which tools and agents your sessions use. These read the spans stored by `spooling sync`, and use the same agent/tool names as the web app (an agent is its subagent type, falling back to its span name).
+
+```bash
+spooling tools                       # Top tools: uses, traces, errors, avg time
+spooling tools --agent explore       # Tools called by the "explore" agent
+spooling tools --days 7 --provider claude-code
+
+spooling agents                      # Agents: runs, traces, tokens, cost
+spooling agents --tool Bash          # Agents whose runs called Bash
+
+spooling traces                      # Latest traces, with the agents each ran
+spooling traces ses_10dd             # Search title, project, session id, trace id or agent name
+spooling traces --agent explore --tool Bash --days 30
+```
+
+Common options: `--days N`, `--project TEXT`, `--provider/-p NAME`, `--limit/-n N`, and `--json` for scripting. `--agent` and `--tool` can be repeated (matches any).
+
+`tools --agent` and `agents --tool` look inside an agent's own runs. `traces --agent/--tool` matches whole traces, like the Traces page.
+
+`spooling tools --cloud` and `spooling agents --cloud` show workspace-wide totals from Spooling Cloud. The cloud endpoints only support `--limit`, so combining `--cloud` with other filters is an error. Agent data is only recorded for providers that expose subagents (for example Claude Code's `Task` tool), so `spooling agents` can be empty for other providers.
+
 ### `spooling search <query>`
 
 Semantic search across all your session history using natural language. Each result shows the session title **and its session id**, so you can open it with `spooling session show`.

{spooling-0.2.9 → spooling-0.2.11}/README.md

@@ -119,6 +119,29 @@ spooling stats --week      # Weekly breakdown
 spooling stats --days 30   # Last 30 days
 ```
 
+### `spooling tools`, `spooling agents`, `spooling traces`
+
+See which tools and agents your sessions use. These read the spans stored by `spooling sync`, and use the same agent/tool names as the web app (an agent is its subagent type, falling back to its span name).
+
+```bash
+spooling tools                       # Top tools: uses, traces, errors, avg time
+spooling tools --agent explore       # Tools called by the "explore" agent
+spooling tools --days 7 --provider claude-code
+
+spooling agents                      # Agents: runs, traces, tokens, cost
+spooling agents --tool Bash          # Agents whose runs called Bash
+
+spooling traces                      # Latest traces, with the agents each ran
+spooling traces ses_10dd             # Search title, project, session id, trace id or agent name
+spooling traces --agent explore --tool Bash --days 30
+```
+
+Common options: `--days N`, `--project TEXT`, `--provider/-p NAME`, `--limit/-n N`, and `--json` for scripting. `--agent` and `--tool` can be repeated (matches any).
+
+`tools --agent` and `agents --tool` look inside an agent's own runs. `traces --agent/--tool` matches whole traces, like the Traces page.
+
+`spooling tools --cloud` and `spooling agents --cloud` show workspace-wide totals from Spooling Cloud. The cloud endpoints only support `--limit`, so combining `--cloud` with other filters is an error. Agent data is only recorded for providers that expose subagents (for example Claude Code's `Task` tool), so `spooling agents` can be empty for other providers.
+
 ### `spooling search <query>`
 
 Semantic search across all your session history using natural language. Each result shows the session title **and its session id**, so you can open it with `spooling session show`.

{spooling-0.2.9 → spooling-0.2.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spooling"
-version = "0.2.9"
+version = "0.2.11"
 description = "Local session tracker and semantic search for AI coding assistants"
 readme = "README.md"
 authors = [{ name = "Parsed Analytics, Inc." }]

{spooling-0.2.9 → spooling-0.2.11}/spooling/cli.py

@@ -1339,6 +1339,207 @@ def stats_providers():
     console.print(table)
 
 
+# ---------------------------------------------------------------------------
+# Tools / agents / traces insights
+# ---------------------------------------------------------------------------
+
+def _fmt_ms(ms) -> str:
+    if ms is None:
+        return "-"
+    if ms < 1000:
+        return f"{ms:.0f}ms"
+    if ms < 60_000:
+        return f"{ms / 1000:.1f}s"
+    return f"{ms / 60_000:.1f}m"
+
+
+def _fmt_num(n) -> str:
+    n = int(n or 0)
+    if n >= 1_000_000:
+        return f"{n / 1_000_000:.1f}M"
+    if n >= 10_000:
+        return f"{n / 1000:.1f}K"
+    return f"{n:,}"
+
+
+def _emit_json(data) -> None:
+    import json
+    click.echo(json.dumps(data, indent=2, default=str))
+
+
+def _reject_cloud_filters(**filters) -> None:
+    used = [f"--{k}" for k, v in filters.items() if v]
+    if used:
+        raise click.UsageError(
+            f"{', '.join(used)} can't be combined with --cloud "
+            "(the cloud endpoint only supports --limit). Drop --cloud to filter local data."
+        )
+
+
+_FILTER_OPTS = [
+    click.option("--days", type=int, default=None, help="Only the last N days"),
+    click.option("--project", default=None, help="Project name contains this text"),
+    click.option("--provider", "-p", default=None, help="Only this provider (claude-code, opencode, ...)"),
+    click.option("--limit", "-n", type=int, default=20, show_default=True, help="Max rows"),
+    click.option("--json", "as_json", is_flag=True, help="Print JSON instead of a table"),
+]
+
+
+def _filter_opts(fn):
+    for opt in reversed(_FILTER_OPTS):
+        fn = opt(fn)
+    return fn
+
+
+@cli.command("tools")
+@click.option("--agent", "agents", multiple=True, help="Only tools called by this agent (repeatable)")
+@click.option("--cloud", "cloud_mode", is_flag=True, help="Use the cloud workspace instead of local data")
+@_filter_opts
+def tools_cmd(agents, cloud_mode, days, project, provider, limit, as_json):
+    """Show which tools are used, how often, and how often they fail.
+
+    \b
+    spooling tools                      top tools across all traces
+    spooling tools --agent explore      tools called by the 'explore' agent
+    spooling tools --days 7 --json
+    spooling tools --cloud              workspace-wide, from Spooling Cloud
+    """
+    if cloud_mode:
+        _reject_cloud_filters(agent=agents, days=days, project=project, provider=provider)
+        from spooling.cloud import cloud_tools
+        rows = cloud_tools(limit)
+        if as_json:
+            return _emit_json(rows)
+        table = Table(title="Tools (cloud)", show_lines=False)
+        table.add_column("Tool", style="cyan")
+        table.add_column("Uses", justify="right")
+        table.add_column("Sessions", justify="right")
+        table.add_column("Errors", justify="right")
+        for r in rows:
+            table.add_row(r["tool_name"], _fmt_num(r["uses"]), _fmt_num(r["sessions"]),
+                          f"[red]{r['errors']}[/red]" if r["errors"] else "0")
+        console.print(table if rows else "[yellow]No tool data in the cloud workspace yet.[/yellow]")
+        return
+
+    from spooling.insights import tool_stats
+    rows = tool_stats(days=days, project=project, provider=provider, agents=list(agents) or None, limit=limit)
+    if as_json:
+        return _emit_json(rows)
+    if not rows:
+        console.print("[yellow]No tool data found. Run 'spooling sync' first"
+                      + (" (agent filters need traces that contain agent spans)." if agents else ".") + "[/yellow]")
+        return
+    table = Table(title="Tools" + (f" called by {', '.join(agents)}" if agents else ""), show_lines=False)
+    table.add_column("Tool", style="cyan")
+    table.add_column("Uses", justify="right")
+    table.add_column("Traces", justify="right")
+    table.add_column("Errors", justify="right")
+    table.add_column("Avg time", justify="right", style="dim")
+    for r in rows:
+        table.add_row(r["name"], _fmt_num(r["uses"]), _fmt_num(r["traces"]),
+                      f"[red]{r['errors']}[/red]" if r["errors"] else "0", _fmt_ms(r["avg_ms"]))
+    console.print(table)
+
+
+@cli.command("agents")
+@click.option("--tool", "tools", multiple=True, help="Only agents that called this tool (repeatable)")
+@click.option("--cloud", "cloud_mode", is_flag=True, help="Use the cloud workspace instead of local data")
+@_filter_opts
+def agents_cmd(tools, cloud_mode, days, project, provider, limit, as_json):
+    """Show which agents (subagent types) ran, how often, and what they cost.
+
+    \b
+    spooling agents                     agents across all traces
+    spooling agents --tool Bash         agents whose runs called Bash
+    spooling agents --days 30 --json
+    spooling agents --cloud             workspace-wide, from Spooling Cloud
+    """
+    if cloud_mode:
+        _reject_cloud_filters(tool=tools, days=days, project=project, provider=provider)
+        from spooling.cloud import cloud_agents
+        rows = cloud_agents()[:limit]
+        if as_json:
+            return _emit_json(rows)
+        table = Table(title="Agents (cloud)", show_lines=False)
+        table.add_column("Agent", style="cyan")
+        table.add_column("Runs", justify="right")
+        for r in rows:
+            table.add_row(r["agent_type"], _fmt_num(r["uses"]))
+        console.print(table if rows else "[yellow]No agent data in the cloud workspace yet.[/yellow]")
+        return
+
+    from spooling.insights import agent_stats
+    rows = agent_stats(days=days, project=project, provider=provider, tools=list(tools) or None, limit=limit)
+    if as_json:
+        return _emit_json(rows)
+    if not rows:
+        console.print(
+            "[yellow]No agent spans found locally.[/yellow]\n"
+            "[dim]Agent runs are recorded for providers that expose subagents (e.g. Claude Code's Task tool). "
+            "Run 'spooling sync' after using one, or try 'spooling agents --cloud'.[/dim]"
+        )
+        return
+    table = Table(title="Agents" + (f" that called {', '.join(tools)}" if tools else ""), show_lines=False)
+    table.add_column("Agent", style="cyan")
+    table.add_column("Runs", justify="right")
+    table.add_column("Traces", justify="right")
+    table.add_column("Tokens", justify="right")
+    table.add_column("Est. Cost", justify="right")
+    table.add_column("Avg time", justify="right", style="dim")
+    for r in rows:
+        table.add_row(r["name"], _fmt_num(r["runs"]), _fmt_num(r["traces"]), _fmt_num(r["tokens"]),
+                      f"${r['cost']:.2f}", _fmt_ms(r["avg_ms"]))
+    console.print(table)
+
+
+@cli.command("traces")
+@click.argument("query", required=False)
+@click.option("--agent", "agents", multiple=True, help="Only traces that ran this agent (repeatable)")
+@click.option("--tool", "tools", multiple=True, help="Only traces that used this tool (repeatable)")
+@click.option("--session", default=None, help="Session id (or unique prefix)")
+@_filter_opts
+def traces_cmd(query, agents, tools, session, days, project, provider, limit, as_json):
+    """List traces, optionally filtered by agent, tool, or free text.
+
+    QUERY matches title, project, session id, trace id or an agent name.
+
+    \b
+    spooling traces                           latest traces
+    spooling traces ses_10dd                  find by session id
+    spooling traces --agent explore           traces that ran the explore agent
+    spooling traces --tool Bash --days 7      traces that used Bash this week
+    """
+    from spooling.insights import list_traces
+    rows = list_traces(query=query, agents=list(agents) or None, tools=list(tools) or None,
+                       session=session, days=days, project=project, provider=provider, limit=limit)
+    if as_json:
+        return _emit_json(rows)
+    if not rows:
+        console.print("[yellow]No traces match. Traces are created by 'spooling sync'.[/yellow]")
+        return
+    table = Table(title=f"Traces ({len(rows)})", show_lines=False, pad_edge=False)
+    table.add_column("Date", style="dim", no_wrap=True)
+    table.add_column("Title", style="cyan", max_width=22, overflow="ellipsis", no_wrap=True)
+    table.add_column("Session", style="dim", no_wrap=True)
+    table.add_column("Agents", max_width=12, overflow="ellipsis", no_wrap=True)
+    table.add_column("Spans", justify="right", no_wrap=True)
+    table.add_column("Tools", justify="right", no_wrap=True)
+    table.add_column("Cost", justify="right", no_wrap=True)
+    for r in rows:
+        ag = r["agents"]
+        ag_txt = ", ".join(ag[:1]) + (f" +{len(ag) - 1}" if len(ag) > 1 else "") if ag else "-"
+        table.add_row(
+            str(r["started_at"] or "")[5:10],
+            r["title"] or "(untitled)",
+            (r["session_id"] or "")[:10],
+            ag_txt,
+            _fmt_num(r["span_count"]),
+            _fmt_num(r["tool_count"]),
+            f"${float(r['total_cost_usd'] or 0):.2f}",
+        )
+    console.print(table)
+
+
 # ---------------------------------------------------------------------------
 # Token management
 # ---------------------------------------------------------------------------

{spooling-0.2.9 → spooling-0.2.11}/spooling/cloud.py

@@ -4,13 +4,17 @@ import json
 import os
 import re
 import signal
+import socket
+import ssl
 import time
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
+from urllib.parse import urlparse
 
 import click
 import httpx
 from rich.console import Console
+from rich.markup import escape
 
 from spooling.db import get_connection
 from spooling.redact import redact_messages, redact_traces
@@ -70,6 +74,143 @@ def _api_base() -> str:
     return cfg.get("api_url") or os.environ.get("SPOOLING_CLOUD_URL") or DEFAULT_API
 
 
+# --- Friendly network errors -------------------------------------------------
+#
+# Raw exceptions like "[Errno 8] nodename nor servname provided, or not known"
+# tell a user nothing. Everything that talks to the cloud funnels its errors
+# through _explain_error / _explain_http so they get a plain-English cause and
+# the next step.
+
+_SELF_HOST_HINT = (
+    "Using a self-hosted or staging server? Point the CLI at it with\n"
+    "    spooling cloud login --key sk_... --api-url https://your-host\n"
+    "  or set SPOOLING_CLOUD_URL."
+)
+
+
+def _host_port(base: str) -> tuple[str, int]:
+    try:
+        u = urlparse(base)
+        host = u.hostname or base
+        port = u.port or (80 if u.scheme == "http" else 443)
+    except ValueError:  # e.g. port out of range in a hand-typed URL
+        return base, 443
+    return host, port
+
+
+def _exc_chain(e: BaseException):
+    seen = set()
+    while e is not None and id(e) not in seen:
+        seen.add(id(e))
+        yield e
+        e = e.__cause__ or e.__context__
+
+
+_DNS_MARKERS = (
+    "nodename nor servname",          # macOS
+    "name or service not known",      # Linux (glibc)
+    "temporary failure in name resolution",
+    "no address associated with hostname",
+    "getaddrinfo failed",             # Windows
+    "no such host",
+)
+
+
+def _is_dns_error(e: BaseException) -> bool:
+    for x in _exc_chain(e):
+        if isinstance(x, socket.gaierror):
+            return True
+        if any(m in str(x).lower() for m in _DNS_MARKERS):
+            return True
+    return False
+
+
+def _explain_error(e: BaseException, base: str) -> str:
+    """Return a plain-English explanation (rich markup) for a failed request.
+
+    Never raises: it runs inside error handlers, where a second exception would
+    hide the original problem.
+    """
+    try:
+        return _explain_error_impl(e, base)
+    except Exception:  # noqa: BLE001
+        return escape(str(e) or type(e).__name__)
+
+
+def _explain_error_impl(e: BaseException, base: str) -> str:
+    host, port = _host_port(base)
+    chain = list(_exc_chain(e))
+    if _is_dns_error(e):
+        return (
+            f"Can't reach Spooling Cloud at {escape(base)}\n"
+            f"  The hostname '{escape(host)}' doesn't resolve (DNS lookup failed).\n"
+            f"  Either you're offline, or that server doesn't exist (yet).\n"
+            f"  - Offline or on a VPN? Check your connection and try again.\n"
+            f"  - {_SELF_HOST_HINT}"
+        )
+    if any(isinstance(x, ConnectionRefusedError) for x in chain):
+        return (
+            f"Connection refused by {escape(host)}:{port}\n"
+            f"  The host is reachable but nothing is listening. Is the sync server running?\n"
+            f"  - {_SELF_HOST_HINT}"
+        )
+    if isinstance(e, httpx.TimeoutException) or any(isinstance(x, (TimeoutError, socket.timeout)) for x in chain):
+        return (
+            f"Timed out talking to {escape(base)}\n"
+            f"  The server may be starting up or overloaded. Try again in a moment."
+        )
+    if any(isinstance(x, ssl.SSLError) for x in chain):
+        return (
+            f"TLS/SSL error connecting to {escape(host)}\n"
+            f"  {escape(str(e))}\n"
+            f"  Check the server's certificate, and that the URL scheme (http/https) is right."
+        )
+    if isinstance(e, httpx.ConnectError):
+        return f"Can't connect to {escape(base)}: {escape(str(e) or type(e).__name__)}"
+    return escape(str(e) or type(e).__name__)
+
+
+def _explain_http(e: "httpx.HTTPStatusError") -> str:
+    code = e.response.status_code
+    body = escape(e.response.text[:200])
+    if code == 401:
+        return (
+            f"HTTP 401: the server rejected your API key.\n"
+            f"  Create a new key in the admin app (Settings > API keys), then run\n"
+            f"    spooling cloud login --key sk_...\n"
+            f"  {body}"
+        )
+    if code == 403:
+        return f"HTTP 403: this API key isn't allowed to do that (missing scope or no workspace).\n  {body}"
+    if code == 429:
+        retry = e.response.headers.get("retry-after")
+        return f"HTTP 429: rate limited{f', retry in {retry}s' if retry else ''}. Slow down or try again shortly."
+    if code >= 500:
+        return f"HTTP {code}: the server hit an error. This is not a problem with your data; try again shortly.\n  {body}"
+    return f"HTTP {code}: {body}"
+
+
+def _fail(message: str) -> "None":
+    """Print an error and exit non-zero so scripts and cron can detect it."""
+    console.print(f"[red]{message}[/red]")
+    raise click.exceptions.Exit(1)
+
+
+def _preflight(base: str) -> None:
+    """Fail fast, before any sync/redaction work, if the server can't be resolved.
+
+    Only checks DNS (no request is sent, so it works with any server version).
+    Connection-level problems are still reported by the request itself.
+    """
+    host, port = _host_port(base)
+    try:
+        socket.getaddrinfo(host, port, type=socket.SOCK_STREAM)
+    except OSError as e:
+        console.print(f"[red]{_explain_error(e, base)}[/red]")
+        console.print("[dim]Nothing was sent. Your local sessions are untouched.[/dim]")
+        raise click.exceptions.Exit(1)
+
+
 @click.group()
 def cloud():
     """Spooling Cloud: push local sessions to api.spooling.ai."""
@@ -93,8 +234,10 @@ def cloud_login(key: str, api_url: str | None):
         stats = r.json()
         console.print(f"[green]Logged in to {base}[/green]")
         console.print(f"  sessions in cloud: [bold]{stats.get('sessions', 0)}[/bold]")
+    except httpx.HTTPStatusError as e:
+        console.print(f"[red]Saved key, but the server rejected the check:\n  {_explain_http(e)}[/red]")
     except Exception as e:
-        console.print(f"[red]Saved key, but /v1/stats check failed: {e}[/red]")
+        console.print(f"[red]Saved key, but couldn't verify it.\n  {_explain_error(e, base)}[/red]")
 
 
 @cloud.command("status")
@@ -114,8 +257,10 @@ def cloud_status():
         console.print(f"  messages: [bold]{s.get('messages', 0)}[/bold]")
         console.print(f"  providers: [bold]{s.get('providers', 0)}[/bold]")
         console.print(f"  cost: [bold]${s.get('cost', 0):.2f}[/bold]")
+    except httpx.HTTPStatusError as e:
+        _fail(f"{_explain_http(e)}")
     except Exception as e:
-        console.print(f"[red]Error: {e}[/red]")
+        _fail(f"{_explain_error(e, base)}")
 
 
 @cloud.command("logout")
@@ -395,14 +540,9 @@ def _push_trace_batches(
                 else:
                     log(f"  pushed {acc} trace(s), {spans} span(s)")
             except httpx.HTTPStatusError as e:
-                return (
-                    accepted,
-                    rejected,
-                    spans_total,
-                    f"HTTP {e.response.status_code}: {e.response.text[:200]}",
-                )
+                return accepted, rejected, spans_total, _explain_http(e)
             except Exception as e:
-                return accepted, rejected, spans_total, str(e)
+                return accepted, rejected, spans_total, _explain_error(e, base)
     return accepted, rejected, spans_total, None
 
 
@@ -448,9 +588,9 @@ def _push_batches(
                 else:
                     log(f"  pushed {accepted} sessions")
             except httpx.HTTPStatusError as e:
-                return total, rejected, f"HTTP {e.response.status_code}: {e.response.text[:200]}"
+                return total, rejected, _explain_http(e)
             except Exception as e:
-                return total, rejected, str(e)
+                return total, rejected, _explain_error(e, base)
     return total, rejected, None
 
 
@@ -559,6 +699,8 @@ def push(limit: int, batch: int, project: str | None, cwd_substr: str | None, ti
         return
     headers = _auth_headers()
     base = _api_base()
+    if not dry_run:
+        _preflight(base)  # fail fast, before syncing and redacting, if the server can't be reached
     if do_sync:
         _sync_local()
     sessions = _collect_sessions(
@@ -607,8 +749,7 @@ def push(limit: int, batch: int, project: str | None, cwd_substr: str | None, ti
         return
     total, rejected, err = _push_batches(sessions, batch, base, headers, console.print, copy=copy)
     if err:
-        console.print(f"[red]{err}[/red]")
-        return
+        _fail(err)
     if rejected:
         console.print(
             f"[green]Done.[/green] {total} sessions synced to {base} "
@@ -649,8 +790,7 @@ def push(limit: int, batch: int, project: str | None, cwd_substr: str | None, ti
             traces, trace_batch_size, base, headers, console.print,
         )
         if t_err:
-            console.print(f"[yellow]Trace push failed: {t_err}[/yellow]")
-            return
+            _fail(f"Sessions were pushed, but the trace/span upload failed:\n  {t_err}")
         msg = f"[green]Done.[/green] {t_acc} trace(s) and {t_spans} span(s) synced"
         if t_rej:
             msg += f" ([yellow]{t_rej} trace(s) rejected[/yellow])"
@@ -715,7 +855,7 @@ def cloud_watch(interval: int, limit: int, batch: int, lookback: int, no_redact:
                     console.print(f"  [dim]Redacted {redaction_count} secret(s) before push[/dim]")
             total, rejected, err = _push_batches(sessions, batch, base, headers, console.print)
             if err:
-                console.print(f"[red]{err}[/red] (will retry next cycle)")
+                console.print(f"[red]{err.splitlines()[0]}[/red] (will retry next cycle)")
             else:
                 # Advance watermark to the cycle start; the lookback window catches
                 # sessions whose started_at slid backwards or whose messages were
@@ -790,6 +930,7 @@ def cloud_delete(project: str | None, cwd_substr: str | None, session_id: str |
 
     headers = _auth_headers()
     base = _api_base()
+    _preflight(base)
     params = {"dry_run": "true" if dry_run else "false"}
     if project:
         params["project"] = project
@@ -810,10 +951,10 @@ def cloud_delete(project: str | None, cwd_substr: str | None, session_id: str |
         r.raise_for_status()
         data = r.json()
     except httpx.HTTPStatusError as e:
-        console.print(f"[red]HTTP {e.response.status_code}: {e.response.text[:200]}[/red]")
+        console.print(f"[red]{_explain_http(e)}[/red]")
         return
     except Exception as e:
-        console.print(f"[red]{e}[/red]")
+        console.print(f"[red]{_explain_error(e, base)}[/red]")
         return
 
     matched = data.get("matched", 0)
@@ -928,9 +1069,9 @@ def _pull_sessions(
             r = client.get(f"{base}/v1/sessions", headers=headers, params=params)
             r.raise_for_status()
         except httpx.HTTPStatusError as e:
-            return 0, 0, f"HTTP {e.response.status_code}: {e.response.text[:200]}"
+            return 0, 0, _explain_http(e)
         except Exception as e:
-            return 0, 0, str(e)
+            return 0, 0, _explain_error(e, base)
 
         data = r.json()
         cloud_sessions = data.get("sessions", [])
@@ -979,6 +1120,7 @@ def pull(limit: int, batch: int, dry_run: bool):
     """
     headers = _auth_headers()
     base = _api_base()
+    _preflight(base)
 
     cfg = _load_config()
     last = cfg.get("last_pull_at")
@@ -996,10 +1138,10 @@ def pull(limit: int, batch: int, dry_run: bool):
         r = httpx.get(f"{base}/v1/sessions", headers=headers, params=params, timeout=30)
         r.raise_for_status()
     except httpx.HTTPStatusError as e:
-        console.print(f"[red]HTTP {e.response.status_code}: {e.response.text[:200]}[/red]")
+        console.print(f"[red]{_explain_http(e)}[/red]")
         return
     except Exception as e:
-        console.print(f"[red]{e}[/red]")
+        console.print(f"[red]{_explain_error(e, base)}[/red]")
         return
 
     data = r.json()
@@ -1070,6 +1212,7 @@ def sync(limit: int, batch: int, project: str | None, cwd_substr: str | None, ti
     """
     headers = _auth_headers()
     base = _api_base()
+    _preflight(base)
 
     # Phase 1: Push local → cloud
     console.print("[bold]Phase 1: Push local → cloud[/bold]")
@@ -1115,10 +1258,10 @@ def sync(limit: int, batch: int, project: str | None, cwd_substr: str | None, ti
         r = httpx.get(f"{base}/v1/sessions", headers=headers, params=params, timeout=30)
         r.raise_for_status()
     except httpx.HTTPStatusError as e:
-        console.print(f"  [red]HTTP {e.response.status_code}: {e.response.text[:200]}[/red]")
+        console.print(f"  [red]{_explain_http(e)}[/red]")
         return
     except Exception as e:
-        console.print(f"  [red]{e}[/red]")
+        console.print(f"  [red]{_explain_error(e, base)}[/red]")
         return
 
     data = r.json()
@@ -1189,3 +1332,25 @@ def cloud_stats() -> dict | None:
         return r.json()
     except Exception:
         return None
+
+
+def _cloud_get(path: str, params: dict | None = None):
+    """GET a Spooling Cloud endpoint; on any failure print a plain-English reason and exit 1."""
+    headers = _auth_headers()
+    base = _api_base()
+    try:
+        r = httpx.get(f"{base}{path}", headers=headers, params=params, timeout=15)
+        r.raise_for_status()
+        return r.json()
+    except Exception as e:  # noqa: BLE001
+        _fail(_explain_error(e, base))
+
+
+def cloud_tools(limit: int = 20) -> list[dict]:
+    """Per-tool usage across the cloud workspace (GET /v1/tools)."""
+    return _cloud_get("/v1/tools", {"limit": limit})
+
+
+def cloud_agents() -> list[dict]:
+    """Per-agent-type usage across the cloud workspace (GET /v1/stats/agent-subtypes)."""
+    return _cloud_get("/v1/stats/agent-subtypes").get("agent_subtypes", [])