spooling 0.2.10__tar.gz → 0.2.11__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spooling
-Version: 0.2.10
+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.10 → 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.10 → spooling-0.2.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spooling"
-version = "0.2.10"
+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.10 → 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.10 → spooling-0.2.11}/spooling/cloud.py

@@ -1332,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", [])

spooling-0.2.11/spooling/insights.py

@@ -0,0 +1,253 @@
+"""Agent / tool / trace insights over the local span data.
+
+These power ``spooling tools``, ``spooling agents`` and ``spooling traces``.
+
+Naming matches the Spooling web app so numbers line up between the two:
+
+* an agent is its ``agent_type`` (the subagent type) when set, else the span name
+* a tool is its ``tool_name`` when set, else the span name
+
+Filter semantics:
+
+* ``tools --agent A``   tools called *by* agent A (inside its subtree)
+* ``agents --tool T``   agents whose runs called tool T (inside their subtree)
+* ``traces``            trace-level, like the Traces page: a trace matches an
+                        agent / tool filter if it contains any such span
+"""
+
+from __future__ import annotations
+
+from spooling.db import get_connection
+from spooling.stats import _days_ago
+
+AGENT_LABEL = "COALESCE(NULLIF({a}.agent_type, ''), {a}.name)"
+TOOL_LABEL = "COALESCE(NULLIF({a}.tool_name, ''), {a}.name)"
+
+
+def _agent(alias: str = "sp") -> str:
+    return AGENT_LABEL.format(a=alias)
+
+
+def _tool(alias: str = "sp") -> str:
+    return TOOL_LABEL.format(a=alias)
+
+
+def _marks(n: int) -> str:
+    return ",".join("?" * n)
+
+
+def _trace_filters(
+    *,
+    days: int | None,
+    project: str | None,
+    provider: str | None,
+    alias: str = "t",
+) -> tuple[list[str], list]:
+    """WHERE fragments restricting the ``traces`` table (alias ``t``)."""
+    where: list[str] = []
+    params: list = []
+    if days:
+        where.append(f"{alias}.started_at >= ?")
+        params.append(_days_ago(days))
+    if project:
+        where.append(f"{alias}.project LIKE ?")
+        params.append(f"%{project}%")
+    if provider:
+        where.append(f"{alias}.provider_id = ?")
+        params.append(provider)
+    return where, params
+
+
+# ---------------------------------------------------------------------------
+# tools
+# ---------------------------------------------------------------------------
+
+def tool_stats(
+    *,
+    days: int | None = None,
+    project: str | None = None,
+    provider: str | None = None,
+    agents: list[str] | None = None,
+    limit: int = 20,
+) -> list[dict]:
+    """Per-tool usage: calls, traces it appeared in, errors, average duration."""
+    where, params = _trace_filters(days=days, project=project, provider=provider)
+    where.insert(0, "sp.kind = 'tool'")
+
+    cte = ""
+    if agents:
+        # restrict to tool spans that live under one of the named agents
+        cte = f"""WITH RECURSIVE sub(id) AS (
+                    SELECT sp.id FROM spans sp WHERE sp.kind = 'agent' AND {_agent()} IN ({_marks(len(agents))})
+                    UNION
+                    SELECT c.id FROM spans c JOIN sub ON c.parent_id = sub.id
+                  )"""
+        where.append("sp.id IN (SELECT id FROM sub)")
+        params = list(agents) + params
+
+    sql = f"""{cte}
+        SELECT {_tool()} AS name,
+               COUNT(*) AS uses,
+               COUNT(DISTINCT sp.trace_id) AS traces,
+               COALESCE(SUM(sp.tool_is_error), 0) AS errors,
+               AVG(NULLIF(sp.duration_ms, 0)) AS avg_ms
+        FROM spans sp
+        JOIN traces t ON t.id = sp.trace_id
+        WHERE {' AND '.join(where)}
+        GROUP BY 1
+        ORDER BY uses DESC, name ASC
+        LIMIT ?"""
+    conn = get_connection()
+    try:
+        rows = conn.execute(sql, params + [limit]).fetchall()
+    finally:
+        conn.close()
+    return [
+        {
+            "name": r["name"],
+            "uses": int(r["uses"]),
+            "traces": int(r["traces"]),
+            "errors": int(r["errors"] or 0),
+            "avg_ms": float(r["avg_ms"]) if r["avg_ms"] is not None else None,
+        }
+        for r in rows
+    ]
+
+
+# ---------------------------------------------------------------------------
+# agents
+# ---------------------------------------------------------------------------
+
+def agent_stats(
+    *,
+    days: int | None = None,
+    project: str | None = None,
+    provider: str | None = None,
+    tools: list[str] | None = None,
+    limit: int = 20,
+) -> list[dict]:
+    """Per-agent usage: runs, traces it appeared in, tokens, cost."""
+    where, params = _trace_filters(days=days, project=project, provider=provider)
+    where.insert(0, "sp.kind = 'agent'")
+
+    cte = ""
+    if tools:
+        # restrict to agent spans that have one of the named tools somewhere beneath them
+        cte = f"""WITH RECURSIVE up(id) AS (
+                    SELECT sp.parent_id FROM spans sp
+                      WHERE sp.kind = 'tool' AND {_tool()} IN ({_marks(len(tools))}) AND sp.parent_id IS NOT NULL
+                    UNION
+                    SELECT p.parent_id FROM spans p JOIN up ON p.id = up.id WHERE p.parent_id IS NOT NULL
+                  )"""
+        where.append("sp.id IN (SELECT id FROM up)")
+        params = list(tools) + params
+
+    sql = f"""{cte}
+        SELECT {_agent()} AS name,
+               COUNT(*) AS runs,
+               COUNT(DISTINCT sp.trace_id) AS traces,
+               COALESCE(SUM(sp.input_tokens), 0) + COALESCE(SUM(sp.output_tokens), 0) AS tokens,
+               COALESCE(SUM(sp.cost_usd), 0) AS cost,
+               AVG(NULLIF(sp.duration_ms, 0)) AS avg_ms
+        FROM spans sp
+        JOIN traces t ON t.id = sp.trace_id
+        WHERE {' AND '.join(where)}
+        GROUP BY 1
+        ORDER BY runs DESC, name ASC
+        LIMIT ?"""
+    conn = get_connection()
+    try:
+        rows = conn.execute(sql, params + [limit]).fetchall()
+    finally:
+        conn.close()
+    return [
+        {
+            "name": r["name"],
+            "runs": int(r["runs"]),
+            "traces": int(r["traces"]),
+            "tokens": int(r["tokens"] or 0),
+            "cost": float(r["cost"] or 0),
+            "avg_ms": float(r["avg_ms"]) if r["avg_ms"] is not None else None,
+        }
+        for r in rows
+    ]
+
+
+# ---------------------------------------------------------------------------
+# traces
+# ---------------------------------------------------------------------------
+
+def list_traces(
+    *,
+    query: str | None = None,
+    agents: list[str] | None = None,
+    tools: list[str] | None = None,
+    session: str | None = None,
+    days: int | None = None,
+    project: str | None = None,
+    provider: str | None = None,
+    limit: int = 20,
+) -> list[dict]:
+    """Traces, newest first, each with its distinct agents.
+
+    ``query`` matches title, project, session id, trace id or an agent name
+    (the same fields the Traces page searches).
+    """
+    where, params = _trace_filters(days=days, project=project, provider=provider)
+
+    if session:
+        where.append("t.session_id LIKE ?")
+        params.append(f"{session}%")
+    if query and query.strip():
+        like = f"%{query.strip()}%"
+        where.append(
+            f"""(COALESCE(t.title, s.title) LIKE ? OR COALESCE(t.project, s.project) LIKE ?
+                 OR t.session_id LIKE ? OR t.id LIKE ?
+                 OR EXISTS (SELECT 1 FROM spans sp WHERE sp.trace_id = t.id AND sp.kind = 'agent'
+                            AND {_agent()} LIKE ?))"""
+        )
+        params.extend([like] * 5)
+    if agents:
+        where.append(
+            f"""EXISTS (SELECT 1 FROM spans sp WHERE sp.trace_id = t.id AND sp.kind = 'agent'
+                        AND {_agent()} IN ({_marks(len(agents))}))"""
+        )
+        params.extend(agents)
+    if tools:
+        where.append(
+            f"""EXISTS (SELECT 1 FROM spans sp WHERE sp.trace_id = t.id AND sp.kind = 'tool'
+                        AND {_tool()} IN ({_marks(len(tools))}))"""
+        )
+        params.extend(tools)
+
+    sql = f"""
+        SELECT t.id, t.session_id, t.provider_id,
+               COALESCE(t.project, s.project) AS project,
+               COALESCE(t.title, s.title) AS title,
+               t.started_at, t.duration_ms, t.span_count, t.agent_count, t.tool_count,
+               t.error_count, t.total_input_tokens, t.total_output_tokens,
+               t.total_cost_usd, t.model
+        FROM traces t
+        LEFT JOIN sessions s ON s.id = t.session_id
+        {('WHERE ' + ' AND '.join(where)) if where else ''}
+        ORDER BY t.started_at DESC
+        LIMIT ?"""
+    conn = get_connection()
+    try:
+        rows = [dict(r) for r in conn.execute(sql, params + [limit]).fetchall()]
+        if rows:
+            ids = [r["id"] for r in rows]
+            by_trace: dict[str, list[str]] = {i: [] for i in ids}
+            for a in conn.execute(
+                f"""SELECT DISTINCT sp.trace_id AS trace_id, {_agent()} AS name
+                    FROM spans sp
+                    WHERE sp.kind = 'agent' AND sp.trace_id IN ({_marks(len(ids))})
+                    ORDER BY name""",
+                ids,
+            ).fetchall():
+                by_trace[a["trace_id"]].append(a["name"])
+            for r in rows:
+                r["agents"] = by_trace[r["id"]]
+    finally:
+        conn.close()
+    return rows

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spooling
-Version: 0.2.10
+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.10 → spooling-0.2.11}/spooling.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ spooling/embeddings.py
 spooling/evals.py
 spooling/experiments.py
 spooling/ingest.py
+spooling/insights.py
 spooling/mcp_server.py
 spooling/optimize.py
 spooling/parser.py
@@ -65,6 +66,7 @@ spooling/providers/session_file.py
 spooling/providers/windsurf.py
 tests/test_claude_code_provider.py
 tests/test_cloud_errors.py
+tests/test_insights.py
 tests/test_mcp_auth_middleware.py
 tests/test_session_ids.py
 tests/test_storage_optimizations.py

spooling-0.2.11/tests/test_insights.py

@@ -0,0 +1,218 @@
+"""Tests for `spooling tools`, `spooling agents` and `spooling traces`
+(spooling.insights + the CLI commands)."""
+
+import json
+from datetime import datetime, timedelta, timezone
+
+import pytest
+from click.testing import CliRunner
+
+from spooling import db as db_mod
+from spooling import insights
+from spooling.cli import cli
+
+NOW = datetime.now(timezone.utc)
+
+
+@pytest.fixture
+def conn(tmp_path, monkeypatch):
+    monkeypatch.setattr(db_mod, "DB_PATH", tmp_path / "spooling.db")
+    c = db_mod.get_connection()
+    yield c
+    c.close()
+
+
+def add_trace(conn, tid, sid, *, title, days_ago=0, project="proj", provider="claude-code"):
+    started = (NOW - timedelta(days=days_ago)).isoformat()
+    conn.execute(
+        "INSERT INTO sessions (id, provider_id, project, title, started_at) VALUES (?,?,?,?,?)",
+        (sid, provider, project, title, started),
+    )
+    conn.execute(
+        "INSERT INTO traces (id, session_id, provider_id, project, title, started_at) VALUES (?,?,?,?,?,?)",
+        (tid, sid, provider, project, title, started),
+    )
+
+
+def add_span(conn, sid, tid, kind, *, parent=None, name=None, tool=None, agent=None,
+             err=0, ms=100, tokens=0, cost=0.0):
+    conn.execute(
+        """INSERT INTO spans (id, trace_id, parent_id, kind, name, tool_name, agent_type,
+                              tool_is_error, duration_ms, input_tokens, output_tokens, cost_usd)
+           VALUES (?,?,?,?,?,?,?,?,?,?,0,?)""",
+        (sid, tid, parent, kind, name or tool or agent or kind, tool, agent, err, ms, tokens, cost),
+    )
+
+
+@pytest.fixture
+def seeded(conn):
+    # trace A: root -> explore agent (Read x2, Grep) ; root -> Bash (top level, one error)
+    add_trace(conn, "tA", "ses_aaaa1111", title="Fix login bug", days_ago=1)
+    add_span(conn, "A-root", "tA", "session")
+    add_span(conn, "A-ex", "tA", "agent", parent="A-root", name="agent:explore", agent="explore", tokens=100, cost=0.5)
+    add_span(conn, "A-r1", "tA", "tool", parent="A-ex", tool="Read", ms=100)
+    add_span(conn, "A-r2", "tA", "tool", parent="A-ex", tool="Read", ms=300)
+    add_span(conn, "A-g1", "tA", "tool", parent="A-ex", tool="Grep")
+    add_span(conn, "A-b1", "tA", "tool", parent="A-root", tool="Bash", err=1)
+    # trace B (older): root -> build agent -> Bash ; agent has no agent_type, falls back to name
+    add_trace(conn, "tB", "ses_bbbb2222", title="Refactor billing", days_ago=40, project="other", provider="opencode")
+    add_span(conn, "B-root", "tB", "session")
+    add_span(conn, "B-bd", "tB", "agent", parent="B-root", name="build", agent=None, tokens=50, cost=0.25)
+    add_span(conn, "B-b1", "tB", "tool", parent="B-bd", tool="Bash")
+    # trace C: no agents at all
+    add_trace(conn, "tC", "ses_cccc3333", title="Quick question", days_ago=2)
+    add_span(conn, "C-root", "tC", "session")
+    add_span(conn, "C-r1", "tC", "tool", parent="C-root", tool="Read")
+    conn.commit()
+
+
+def by_name(rows):
+    return {r["name"]: r for r in rows}
+
+
+class TestToolStats:
+    def test_counts_errors_and_traces(self, seeded):
+        t = by_name(insights.tool_stats())
+        assert t["Read"]["uses"] == 3 and t["Read"]["traces"] == 2
+        assert t["Bash"]["uses"] == 2 and t["Bash"]["errors"] == 1
+        assert t["Read"]["avg_ms"] == pytest.approx(166.67, abs=0.1)
+
+    def test_sorted_by_uses_and_limited(self, seeded):
+        rows = insights.tool_stats(limit=1)
+        assert [r["name"] for r in rows] == ["Read"]
+
+    def test_agent_filter_is_subtree_only(self, seeded):
+        t = by_name(insights.tool_stats(agents=["explore"]))
+        assert set(t) == {"Read", "Grep"}          # top-level Bash and trace C's Read excluded
+        assert t["Read"]["uses"] == 2
+
+    def test_agent_filter_falls_back_to_span_name(self, seeded):
+        assert set(by_name(insights.tool_stats(agents=["build"]))) == {"Bash"}
+
+    def test_days_project_provider_filters(self, seeded):
+        assert by_name(insights.tool_stats(days=7))["Bash"]["uses"] == 1      # trace B is 40 days old
+        other = by_name(insights.tool_stats(project="other"))
+        assert set(other) == {"Bash"} and other["Bash"]["uses"] == 1
+        assert by_name(insights.tool_stats(provider="opencode"))["Bash"]["uses"] == 1
+
+
+class TestAgentStats:
+    def test_runs_tokens_cost(self, seeded):
+        a = by_name(insights.agent_stats())
+        assert set(a) == {"explore", "build"}
+        assert a["explore"]["runs"] == 1 and a["explore"]["tokens"] == 100
+        assert a["explore"]["cost"] == pytest.approx(0.5)
+
+    def test_tool_filter_is_subtree_only(self, seeded):
+        assert set(by_name(insights.agent_stats(tools=["Grep"]))) == {"explore"}
+        assert set(by_name(insights.agent_stats(tools=["Bash"]))) == {"build"}  # explore's Bash is not under it
+
+    def test_days_filter(self, seeded):
+        assert set(by_name(insights.agent_stats(days=7))) == {"explore"}
+
+    def test_none_when_no_agents(self, conn):
+        add_trace(conn, "t1", "s1", title="x")
+        add_span(conn, "r", "t1", "session")
+        conn.commit()
+        assert insights.agent_stats() == []
+
+
+class TestListTraces:
+    def test_newest_first_with_agents(self, seeded):
+        rows = insights.list_traces()
+        assert [r["id"] for r in rows] == ["tA", "tC", "tB"]
+        assert by_name([{"name": r["id"], **r} for r in rows])["tA"]["agents"] == ["explore"]
+        assert rows[1]["agents"] == []
+
+    def test_session_id_search_full_prefix_and_substring(self, seeded):
+        assert [r["id"] for r in insights.list_traces(query="ses_bbbb2222")] == ["tB"]
+        assert [r["id"] for r in insights.list_traces(query="bbbb")] == ["tB"]
+        assert [r["id"] for r in insights.list_traces(session="ses_aaaa")] == ["tA"]
+
+    def test_query_matches_title_and_agent_name(self, seeded):
+        assert [r["id"] for r in insights.list_traces(query="billing")] == ["tB"]
+        assert [r["id"] for r in insights.list_traces(query="explore")] == ["tA"]
+
+    def test_agent_and_tool_filters_are_trace_level(self, seeded):
+        assert [r["id"] for r in insights.list_traces(agents=["build"])] == ["tB"]
+        assert [r["id"] for r in insights.list_traces(agents=["build", "explore"])] == ["tA", "tB"]
+        assert [r["id"] for r in insights.list_traces(tools=["Grep"])] == ["tA"]
+        assert [r["id"] for r in insights.list_traces(agents=["explore"], tools=["Bash"])] == ["tA"]
+        assert insights.list_traces(agents=["explore"], tools=["Nope"]) == []
+
+    def test_other_filters_and_limit(self, seeded):
+        assert [r["id"] for r in insights.list_traces(provider="opencode")] == ["tB"]
+        assert [r["id"] for r in insights.list_traces(days=7)] == ["tA", "tC"]
+        assert len(insights.list_traces(limit=1)) == 1
+
+
+class TestCli:
+    def run(self, *args):
+        return CliRunner().invoke(cli, list(args))
+
+    def test_tools_table_and_json(self, seeded):
+        r = self.run("tools")
+        assert r.exit_code == 0 and "Read" in r.output and "Bash" in r.output
+        data = json.loads(self.run("tools", "--agent", "explore", "--json").output)
+        assert {d["name"] for d in data} == {"Read", "Grep"}
+
+    def test_agents_table_and_json(self, seeded):
+        assert "explore" in self.run("agents").output
+        data = json.loads(self.run("agents", "--tool", "Grep", "--json").output)
+        assert [d["name"] for d in data] == ["explore"]
+
+    def test_agents_empty_explains_why(self, conn):
+        r = self.run("agents")
+        assert r.exit_code == 0 and "No agent spans" in r.output
+
+    def test_traces_filters(self, seeded):
+        data = json.loads(self.run("traces", "--agent", "build", "--json").output)
+        assert [d["id"] for d in data] == ["tB"]
+        data = json.loads(self.run("traces", "ses_cccc", "--json").output)
+        assert [d["id"] for d in data] == ["tC"]
+        data = json.loads(self.run("traces", "--tool", "Grep", "--days", "7", "--json").output)
+        assert [d["id"] for d in data] == ["tA"]
+
+    def test_cloud_rejects_local_only_filters(self, seeded):
+        r = self.run("tools", "--cloud", "--days", "7")
+        assert r.exit_code == 2 and "can't be combined with --cloud" in r.output
+        r = self.run("agents", "--cloud", "--tool", "Bash")
+        assert r.exit_code == 2
+
+    def test_cloud_mode_renders_server_data(self, seeded, monkeypatch):
+        from spooling import cloud
+        monkeypatch.setattr(cloud, "cloud_tools", lambda limit=20: [
+            {"tool_name": "Bash", "uses": 12, "sessions": 3, "errors": 1}])
+        monkeypatch.setattr(cloud, "cloud_agents", lambda: [{"agent_type": "explore", "uses": 7}])
+        assert "Bash" in self.run("tools", "--cloud").output
+        assert json.loads(self.run("agents", "--cloud", "--json").output) == [{"agent_type": "explore", "uses": 7}]
+
+
+class TestCloudErrors:
+    def run(self, *args):
+        return CliRunner().invoke(cli, list(args))
+
+    def test_unreachable_server_exits_nonzero_with_reason(self, conn, monkeypatch):
+        import httpx
+        from spooling import cloud
+        monkeypatch.setattr(cloud, "_auth_headers", lambda: {"Authorization": "Bearer sk_x"})
+
+        def boom(*a, **k):
+            raise httpx.ConnectError("connection refused")
+        monkeypatch.setattr(cloud.httpx, "get", boom)
+        for cmd in (["tools", "--cloud"], ["agents", "--cloud"]):
+            r = self.run(*cmd)
+            assert r.exit_code == 1
+            assert "log in" not in r.output.lower()   # a network error must not read as "log in"
+
+    def test_rejected_key_explained(self, conn, monkeypatch):
+        import httpx
+        from spooling import cloud
+        monkeypatch.setattr(cloud, "_auth_headers", lambda: {"Authorization": "Bearer sk_x"})
+        req = httpx.Request("GET", "https://api.example/v1/tools")
+
+        def reject(*a, **k):
+            return httpx.Response(401, text="bad key", request=req)
+        monkeypatch.setattr(cloud.httpx, "get", reject)
+        r = self.run("tools", "--cloud")
+        assert r.exit_code == 1 and "401" in r.output