spooling 0.2.10__tar.gz → 0.2.12__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spooling
-Version: 0.2.10
+Version: 0.2.12
 Summary: Local session tracker and semantic search for AI coding assistants
 Author: Parsed Analytics, Inc.
 License: MIT
@@ -155,6 +155,33 @@ 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 (currently Claude Code, via its `Agent` tool, previously called `Task`), so `spooling agents` is empty for other providers.
+
+After upgrading, `spooling sync` re-reads your Claude Code sessions once to pick up agents. To force a re-read of any provider's files at any time, run `spooling sync --reparse` (optionally with `-p claude-code`).
+
+Agent runs show duration and the prompt that started them. Their own tokens, cost and tool calls are not attributed yet, because Claude Code writes subagent activity to separate transcript files that Spooling does not read yet.
+
 ### `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.12}/README.md

@@ -119,6 +119,33 @@ 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 (currently Claude Code, via its `Agent` tool, previously called `Task`), so `spooling agents` is empty for other providers.
+
+After upgrading, `spooling sync` re-reads your Claude Code sessions once to pick up agents. To force a re-read of any provider's files at any time, run `spooling sync --reparse` (optionally with `-p claude-code`).
+
+Agent runs show duration and the prompt that started them. Their own tokens, cost and tool calls are not attributed yet, because Claude Code writes subagent activity to separate transcript files that Spooling does not read yet.
+
 ### `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.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spooling"
-version = "0.2.10"
+version = "0.2.12"
 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.12}/spooling/cli.py

@@ -65,10 +65,11 @@ def init():
 @cli.command()
 @click.option("--no-embed", is_flag=True, help="Skip embedding (faster sync)")
 @click.option("--provider", "-p", default=None, help="Only sync a specific provider (claude-code, jsonl-session, codex, cursor, copilot, windsurf)")
-def sync(no_embed, provider):
+@click.option("--reparse", is_flag=True, help="Re-read session files even if they look unchanged (rebuilds traces/spans)")
+def sync(no_embed, provider, reparse):
     """Sync AI coding sessions to the database."""
     from spooling.ingest import sync as do_sync
-    do_sync(embed=not no_embed, provider_filter=provider)
+    do_sync(embed=not no_embed, provider_filter=provider, reparse=reparse)
 
 
 @cli.command()
@@ -1339,6 +1340,208 @@ 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 (currently Claude Code, via its "
+            "Agent/Task tool). Run 'spooling sync' after using one, or try 'spooling agents --cloud'.\n"
+            "If you use Claude Code and still see this, run 'spooling sync --reparse -p claude-code'.[/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.12}/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.10 → spooling-0.2.12}/spooling/ingest.py

@@ -458,8 +458,42 @@ def _sync_remote_provider(conn, provider, prov_info: dict, embed: bool) -> tuple
     return total_sessions, total_messages, total_chunks
 
 
-def sync(embed: bool = True, provider_filter: str | None = None):
-    """Sync sessions from all connected providers to the database."""
+_REVISION_PREFIX = "__parser_revision__:"
+
+
+def _needs_reread(conn, synced: dict, provider_type: str, revision: int, reparse: bool) -> bool:
+    """True if this provider's already-synced files must be re-read this run.
+
+    Either the user asked (``--reparse``), or a parser fix shipped
+    (``provider.parser_revision`` is newer than the one recorded at last sync)
+    and there are previously synced files that were parsed the old way.
+    """
+    if reparse:
+        return True
+    if not revision:
+        return False
+    stored = synced.get(_REVISION_PREFIX + provider_type)
+    if stored is not None and stored >= revision:
+        return False
+    row = conn.execute(
+        "SELECT COUNT(*) AS n FROM sync_state WHERE provider_id = %s AND file_path NOT LIKE %s",
+        (provider_type, _REVISION_PREFIX + "%"),
+    ).fetchone()
+    return bool(row["n"])
+
+
+def _record_revision(conn, synced: dict, provider_type: str, revision: int) -> None:
+    if revision and synced.get(_REVISION_PREFIX + provider_type) != revision:
+        _mark_synced(conn, _REVISION_PREFIX + provider_type, revision, provider_type)
+        synced[_REVISION_PREFIX + provider_type] = revision
+
+
+def sync(embed: bool = True, provider_filter: str | None = None, reparse: bool = False):
+    """Sync sessions from all connected providers to the database.
+
+    ``reparse`` re-reads files even if they look unchanged (also done
+    automatically, once, when a provider's parser improves).
+    """
     conn = get_connection()
     connected = _get_connected_providers(conn)
 
@@ -533,20 +567,31 @@ def sync(embed: bool = True, provider_filter: str | None = None):
         if not files:
             continue
 
+        revision = getattr(provider, "parser_revision", 0)
+        reread = _needs_reread(conn, synced, prov_info["type"], revision, reparse)
+        # When re-reading, pretend nothing was synced so every file is parsed again.
+        prov_synced = {} if reread else synced
+
         # Filter to new or changed files. Incremental providers (many sessions
         # per file) are always scanned; they skip unchanged sessions themselves.
         to_process = []
         for f in files:
             size = f.stat().st_size
-            if provider.incremental or str(f) not in synced or synced[str(f)] != size:
+            if provider.incremental or str(f) not in prov_synced or prov_synced[str(f)] != size:
                 to_process.append(f)
 
         if not to_process:
+            _record_revision(conn, synced, prov_info["type"], revision)
+            conn.commit()
             continue
 
         console.print(
             f"[bold]{provider.name}:[/bold] Found {len(to_process)} new/updated session files."
         )
+        if reread and not reparse:
+            console.print(
+                f"  [dim]Re-reading {provider.name} sessions once to pick up improved parsing.[/dim]"
+            )
 
         total_messages = 0
         total_chunks = 0
@@ -570,7 +615,7 @@ def sync(embed: bool = True, provider_filter: str | None = None):
                 batch_sessions: list[tuple] = []  # (file, [sessions])
 
                 for f in batch_files:
-                    sessions = parse_file(provider, f, synced)
+                    sessions = parse_file(provider, f, prov_synced)
                     for session in sessions:
                         _store_session(conn, session)
                         if session.trace is not None:
@@ -601,6 +646,8 @@ def sync(embed: bool = True, provider_filter: str | None = None):
                     _mark_synced(conn, str(f), f.stat().st_size, prov_info["type"])
                 conn.commit()
 
+        _record_revision(conn, synced, prov_info["type"], revision)
+
         # Update provider stats
         conn.execute(
             """UPDATE providers SET