spooling 0.2.6__tar.gz → 0.2.8__tar.gz

{spooling-0.2.6/spooling.egg-info → spooling-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spooling
-Version: 0.2.6
+Version: 0.2.8
 Summary: Local session tracker and semantic search for AI coding assistants
 Author: Parsed Analytics, Inc.
 License: MIT
@@ -56,7 +56,7 @@ No Docker, no PostgreSQL, no Node.js required.
 
 ## How it works
 
-**Four commands. Zero cloud.**
+**Three steps. Local by default.**
 
 ### 01   Install
 
@@ -82,6 +82,8 @@ spooling sync      # embed every session for semantic search
 
 ```bash
 spooling search "that redis race condition"
+spooling session list                      # find a session and its id
+spooling session show ses_e6310bd1 -m      # read that session's full text
 spooling stats
 spooling mcp       # MCP server at http://127.0.0.1:3004/mcp
 ```
@@ -90,7 +92,7 @@ spooling mcp       # MCP server at http://127.0.0.1:3004/mcp
 
 ## Connect Spooling to your AI coding agent
 
-`spooling mcp` exposes an MCP server at `http://127.0.0.1:3004/mcp` (HTTP streamable transport). Any MCP-speaking agent can connect to it and pull context from your local KB mid-conversation. The agent gets tools like `spooling_search`, `spooling_recent_sessions`, `spooling_get_session`, `spooling_workspace_stats`, and `spooling_top_projects`.
+`spooling mcp` exposes an MCP server at `http://127.0.0.1:3004/mcp` (HTTP streamable transport). Any MCP-speaking agent can connect to it and pull context from your local KB mid-conversation. The agent gets tools like `search_sessions` (find a session), `get_session` (read its full conversation by id), `get_stats`, and `list_traces`. See [Tools exposed](#tools-exposed) for the full list.
 
 ### Cursor / Windsurf / Codex / Antigravity
 
@@ -117,7 +119,7 @@ curl -s http://127.0.0.1:3004/mcp \
   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq
 ```
 
-Should return the five `spool_*` tools. If you get "connection refused", `spooling ui` is not running (or its ports got squatted, run `lsof -ti :3004 | xargs kill -9` and retry).
+Should return the tools listed under [Tools exposed](#tools-exposed). If you get "connection refused", `spooling mcp` (or `spooling ui`) is not running, or something else is using port 3004. Find it with `lsof -i :3004`.
 
 ---
 
@@ -125,7 +127,7 @@ Should return the five `spool_*` tools. If you get "connection refused", `spooli
 
 ### `spooling init`
 
-Check database connection and show which AI coding tool providers are detected on your system. This scans default paths for Codex CLI, GitHub Copilot, Cursor, and Windsurf session data.
+Check that the local database opens and show which AI coding tool providers are detected on your system. This scans the default paths for every supported provider (see [Supported Providers](#supported-providers)).
 
 ```bash
 spooling init
@@ -154,17 +156,48 @@ spooling stats --days 30   # Last 30 days
 
 ### `spooling search <query>`
 
-Semantic search across all your session history using natural language.
+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`.
 
 ```bash
 spooling search "snowflake connector"
 spooling search "authentication bug" -n 5
-spooling search "database migration" -p ~/myproject
+spooling search "database migration" -p myproject
+spooling search ses_e6310bd1                # a session id (or prefix) matches that session first
+spooling search "login issue" --cloud       # search your cloud workspace instead
 ```
 
+Session ids work in the query: a full id, a prefix such as `ses_e6310bd1`, or a UUID/hex prefix of 8+ characters. The matching session is ranked first and labelled `(id match)`. `--cloud` search is matched by the server, so ids are shown but not ranked first.
+
 Options:
 - `-n, --limit` - Number of results (default: 10)
-- `-p, --project` - Filter by project name
+- `-p, --project` - Filter by exact project name (see `spooling session list`)
+- `--cloud` - Search the cloud workspace instead of the local database
+
+### `spooling session`
+
+List sessions and read one back by id.
+
+```bash
+spooling session list                         # newest first, with full session ids
+spooling session list --title login -n 10     # filter by title substring
+spooling session list --id e6310bd1           # filter by id substring
+spooling session list --project myproject --cwd ~/code
+
+spooling session show ses_e6310bd1            # summary: model, tokens, cost, tools used
+spooling session show ses_e6310bd1 -m         # plus the full conversation text
+spooling session show ses_e6310bd1 -m --max-chars 300   # truncate each message
+```
+
+`spooling session <id> -m` is shorthand for `spooling session show <id> -m`. `session show` accepts a full session id or any unique prefix. If a prefix matches several sessions, it lists them and exits so you can pick one.
+
+### `spooling optimize`
+
+Compact the local database. Removes duplicated tool-call rows left by older versions (before 0.2.6), truncates oversized previews, embeds any messages missing from search, and runs `VACUUM`. A backup is written next to the database first, and it is safe to re-run. `spooling sync` prints a hint when it finds duplicates.
+
+```bash
+spooling optimize
+spooling optimize --no-backup --no-vacuum --no-embed   # skip individual steps
+```
 
 ### `spooling watch`
 
@@ -336,11 +369,15 @@ the CLI ships with a `spooling cloud` subcommand.
 Send the most recent local sessions up to the cloud:
 
 ```bash
-spooling push                 # 100 sessions, batches of 20
+spooling push                 # syncs local sessions first, then pushes 100 in batches of 20
 spooling push --limit 500     # bigger backfill
+spooling push --no-sync       # push only what is already in the local database
+spooling push --dry-run       # show what would be pushed
 ```
 
-The server upserts by session id, so re-running is safe.
+`push` ingests new provider sessions into the local database before uploading, so you don't need to run `spooling sync` first. The server upserts by session id, so re-running is safe.
+
+To bring sessions from the cloud back down, use `spooling cloud pull`, or `spooling cloud sync` for both directions.
 
 ### Watch (continuous push)
 
@@ -374,8 +411,8 @@ The cloud API at `api.spooling.ai` uses `/v1/` endpoints. Requests require a Bea
 curl -s "https://api.spooling.ai/v1/stats" \
   -H "Authorization: Bearer $SPOOLING_KEY"
 
-# Search (when deployed — falls back to local search on self-hosted)
-curl -s "https://api.spooling.ai/api/search?q=migration&limit=10" \
+# Search (matches session titles and ids)
+curl -s "https://api.spooling.ai/v1/search?q=migration&limit=10" \
   -H "Authorization: Bearer $SPOOLING_KEY"
 ```
 
@@ -450,7 +487,8 @@ the full config snippet so you don't have to remember it.
 |------|---------|
 | `list_traces` | Recent Spooling traces, filterable by provider/project |
 | `get_trace` | Full detail for one trace: header, spans, eval scores |
-| `search_sessions` | Semantic search over embedded session chunks |
+| `search_sessions` | Semantic search over embedded session chunks. Results include `session_id`; a session id in the query matches that session first |
+| `get_session` | Full detail for one session by id or unique prefix, including the conversation text (`include_messages`, `max_messages`, `max_chars`) |
 | `get_stats` | Top-line stats: traces, tokens, cost, errors |
 | `get_top_vendors` | Most-used external vendors by tool-call count |
 | `list_evals` | Recent eval runs, optionally filtered by rubric |
@@ -462,8 +500,15 @@ the full config snippet so you don't have to remember it.
 For MCP clients that only speak stdio, run `spooling mcp --stdio` and register
 it with the command-based form:
 
-```bash
-# MCP config for stdio transport
+```json
+{
+  "mcpServers": {
+    "spooling": {
+      "command": "spooling",
+      "args": ["mcp", "--stdio"]
+    }
+  }
+}
 ```
 
 ---
@@ -539,7 +584,9 @@ spooling/
 │   ├── parser.py            # Session JSONL parser
 │   ├── embeddings.py        # sentence-transformers (all-MiniLM-L6-v2)
 │   ├── ingest.py            # Sync pipeline
-│   ├── search.py            # Numpy cosine similarity search
+│   ├── search.py            # Numpy cosine similarity search (+ session-id matching)
+│   ├── sessions.py          # Session id lookup helpers
+│   ├── optimize.py          # Database dedupe / compaction
 │   ├── stats.py             # Usage statistics
 │   ├── watcher.py           # File watcher (watchdog)
 │   ├── agent.py             # Chat agent (Ollama + Anthropic)
@@ -583,7 +630,6 @@ All optional — defaults work out of the box.
 | `SPOOLING_DB` | `~/.local/share/spooling/spooling.db` | Path to the SQLite database file (`%APPDATA%\spooling\spooling.db` on Windows) |
 | `SPOOLING_EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Sentence transformer model |
 | `SPOOLING_UI_HOST` | `127.0.0.1` | API server host |
-| `SPOOLING_UI_PORT` | `3001` | API server port (used by `spooling serve`) |
 | `SPOOLING_UI_DIR` | *(auto-detected)* | Path to the Next.js `ui/` directory (required for `spooling ui`) |
 | `ANTHROPIC_API_KEY` | - | Anthropic API key (alternative to setting in the GUI) |
 
@@ -604,5 +650,5 @@ All optional — defaults work out of the box.
 
 Run `spooling init` to see which providers are detected on your system.
 
-No data is sent to external servers. Everything runs locally.
+Nothing leaves your machine unless you opt in: Spooling Cloud (`spooling push`), a tunnel (`spooling tunnel`), or the Anthropic chat provider. `spooling pricing refresh` downloads public model prices but sends none of your data.
 

{spooling-0.2.6 → spooling-0.2.8}/README.md

@@ -20,7 +20,7 @@ No Docker, no PostgreSQL, no Node.js required.
 
 ## How it works
 
-**Four commands. Zero cloud.**
+**Three steps. Local by default.**
 
 ### 01   Install
 
@@ -46,6 +46,8 @@ spooling sync      # embed every session for semantic search
 
 ```bash
 spooling search "that redis race condition"
+spooling session list                      # find a session and its id
+spooling session show ses_e6310bd1 -m      # read that session's full text
 spooling stats
 spooling mcp       # MCP server at http://127.0.0.1:3004/mcp
 ```
@@ -54,7 +56,7 @@ spooling mcp       # MCP server at http://127.0.0.1:3004/mcp
 
 ## Connect Spooling to your AI coding agent
 
-`spooling mcp` exposes an MCP server at `http://127.0.0.1:3004/mcp` (HTTP streamable transport). Any MCP-speaking agent can connect to it and pull context from your local KB mid-conversation. The agent gets tools like `spooling_search`, `spooling_recent_sessions`, `spooling_get_session`, `spooling_workspace_stats`, and `spooling_top_projects`.
+`spooling mcp` exposes an MCP server at `http://127.0.0.1:3004/mcp` (HTTP streamable transport). Any MCP-speaking agent can connect to it and pull context from your local KB mid-conversation. The agent gets tools like `search_sessions` (find a session), `get_session` (read its full conversation by id), `get_stats`, and `list_traces`. See [Tools exposed](#tools-exposed) for the full list.
 
 ### Cursor / Windsurf / Codex / Antigravity
 
@@ -81,7 +83,7 @@ curl -s http://127.0.0.1:3004/mcp \
   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq
 ```
 
-Should return the five `spool_*` tools. If you get "connection refused", `spooling ui` is not running (or its ports got squatted, run `lsof -ti :3004 | xargs kill -9` and retry).
+Should return the tools listed under [Tools exposed](#tools-exposed). If you get "connection refused", `spooling mcp` (or `spooling ui`) is not running, or something else is using port 3004. Find it with `lsof -i :3004`.
 
 ---
 
@@ -89,7 +91,7 @@ Should return the five `spool_*` tools. If you get "connection refused", `spooli
 
 ### `spooling init`
 
-Check database connection and show which AI coding tool providers are detected on your system. This scans default paths for Codex CLI, GitHub Copilot, Cursor, and Windsurf session data.
+Check that the local database opens and show which AI coding tool providers are detected on your system. This scans the default paths for every supported provider (see [Supported Providers](#supported-providers)).
 
 ```bash
 spooling init
@@ -118,17 +120,48 @@ spooling stats --days 30   # Last 30 days
 
 ### `spooling search <query>`
 
-Semantic search across all your session history using natural language.
+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`.
 
 ```bash
 spooling search "snowflake connector"
 spooling search "authentication bug" -n 5
-spooling search "database migration" -p ~/myproject
+spooling search "database migration" -p myproject
+spooling search ses_e6310bd1                # a session id (or prefix) matches that session first
+spooling search "login issue" --cloud       # search your cloud workspace instead
 ```
 
+Session ids work in the query: a full id, a prefix such as `ses_e6310bd1`, or a UUID/hex prefix of 8+ characters. The matching session is ranked first and labelled `(id match)`. `--cloud` search is matched by the server, so ids are shown but not ranked first.
+
 Options:
 - `-n, --limit` - Number of results (default: 10)
-- `-p, --project` - Filter by project name
+- `-p, --project` - Filter by exact project name (see `spooling session list`)
+- `--cloud` - Search the cloud workspace instead of the local database
+
+### `spooling session`
+
+List sessions and read one back by id.
+
+```bash
+spooling session list                         # newest first, with full session ids
+spooling session list --title login -n 10     # filter by title substring
+spooling session list --id e6310bd1           # filter by id substring
+spooling session list --project myproject --cwd ~/code
+
+spooling session show ses_e6310bd1            # summary: model, tokens, cost, tools used
+spooling session show ses_e6310bd1 -m         # plus the full conversation text
+spooling session show ses_e6310bd1 -m --max-chars 300   # truncate each message
+```
+
+`spooling session <id> -m` is shorthand for `spooling session show <id> -m`. `session show` accepts a full session id or any unique prefix. If a prefix matches several sessions, it lists them and exits so you can pick one.
+
+### `spooling optimize`
+
+Compact the local database. Removes duplicated tool-call rows left by older versions (before 0.2.6), truncates oversized previews, embeds any messages missing from search, and runs `VACUUM`. A backup is written next to the database first, and it is safe to re-run. `spooling sync` prints a hint when it finds duplicates.
+
+```bash
+spooling optimize
+spooling optimize --no-backup --no-vacuum --no-embed   # skip individual steps
+```
 
 ### `spooling watch`
 
@@ -300,11 +333,15 @@ the CLI ships with a `spooling cloud` subcommand.
 Send the most recent local sessions up to the cloud:
 
 ```bash
-spooling push                 # 100 sessions, batches of 20
+spooling push                 # syncs local sessions first, then pushes 100 in batches of 20
 spooling push --limit 500     # bigger backfill
+spooling push --no-sync       # push only what is already in the local database
+spooling push --dry-run       # show what would be pushed
 ```
 
-The server upserts by session id, so re-running is safe.
+`push` ingests new provider sessions into the local database before uploading, so you don't need to run `spooling sync` first. The server upserts by session id, so re-running is safe.
+
+To bring sessions from the cloud back down, use `spooling cloud pull`, or `spooling cloud sync` for both directions.
 
 ### Watch (continuous push)
 
@@ -338,8 +375,8 @@ The cloud API at `api.spooling.ai` uses `/v1/` endpoints. Requests require a Bea
 curl -s "https://api.spooling.ai/v1/stats" \
   -H "Authorization: Bearer $SPOOLING_KEY"
 
-# Search (when deployed — falls back to local search on self-hosted)
-curl -s "https://api.spooling.ai/api/search?q=migration&limit=10" \
+# Search (matches session titles and ids)
+curl -s "https://api.spooling.ai/v1/search?q=migration&limit=10" \
   -H "Authorization: Bearer $SPOOLING_KEY"
 ```
 
@@ -414,7 +451,8 @@ the full config snippet so you don't have to remember it.
 |------|---------|
 | `list_traces` | Recent Spooling traces, filterable by provider/project |
 | `get_trace` | Full detail for one trace: header, spans, eval scores |
-| `search_sessions` | Semantic search over embedded session chunks |
+| `search_sessions` | Semantic search over embedded session chunks. Results include `session_id`; a session id in the query matches that session first |
+| `get_session` | Full detail for one session by id or unique prefix, including the conversation text (`include_messages`, `max_messages`, `max_chars`) |
 | `get_stats` | Top-line stats: traces, tokens, cost, errors |
 | `get_top_vendors` | Most-used external vendors by tool-call count |
 | `list_evals` | Recent eval runs, optionally filtered by rubric |
@@ -426,8 +464,15 @@ the full config snippet so you don't have to remember it.
 For MCP clients that only speak stdio, run `spooling mcp --stdio` and register
 it with the command-based form:
 
-```bash
-# MCP config for stdio transport
+```json
+{
+  "mcpServers": {
+    "spooling": {
+      "command": "spooling",
+      "args": ["mcp", "--stdio"]
+    }
+  }
+}
 ```
 
 ---
@@ -503,7 +548,9 @@ spooling/
 │   ├── parser.py            # Session JSONL parser
 │   ├── embeddings.py        # sentence-transformers (all-MiniLM-L6-v2)
 │   ├── ingest.py            # Sync pipeline
-│   ├── search.py            # Numpy cosine similarity search
+│   ├── search.py            # Numpy cosine similarity search (+ session-id matching)
+│   ├── sessions.py          # Session id lookup helpers
+│   ├── optimize.py          # Database dedupe / compaction
 │   ├── stats.py             # Usage statistics
 │   ├── watcher.py           # File watcher (watchdog)
 │   ├── agent.py             # Chat agent (Ollama + Anthropic)
@@ -547,7 +594,6 @@ All optional — defaults work out of the box.
 | `SPOOLING_DB` | `~/.local/share/spooling/spooling.db` | Path to the SQLite database file (`%APPDATA%\spooling\spooling.db` on Windows) |
 | `SPOOLING_EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Sentence transformer model |
 | `SPOOLING_UI_HOST` | `127.0.0.1` | API server host |
-| `SPOOLING_UI_PORT` | `3001` | API server port (used by `spooling serve`) |
 | `SPOOLING_UI_DIR` | *(auto-detected)* | Path to the Next.js `ui/` directory (required for `spooling ui`) |
 | `ANTHROPIC_API_KEY` | - | Anthropic API key (alternative to setting in the GUI) |
 
@@ -568,5 +614,5 @@ All optional — defaults work out of the box.
 
 Run `spooling init` to see which providers are detected on your system.
 
-No data is sent to external servers. Everything runs locally.
+Nothing leaves your machine unless you opt in: Spooling Cloud (`spooling push`), a tunnel (`spooling tunnel`), or the Anthropic chat provider. `spooling pricing refresh` downloads public model prices but sends none of your data.
 

{spooling-0.2.6 → spooling-0.2.8}/pyproject.toml

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

{spooling-0.2.6 → spooling-0.2.8}/spooling/cli.py

@@ -138,9 +138,13 @@ def search(query, limit, project, cloud_mode):
             f"[dim]{ts[:19]}[/dim]"
             + (f" [cyan](cloud)[/cyan]" if source == "cloud" else "")
         )
-        if r["title"]:
-            console.print(f"   [dim]Session:[/dim] {r['title']}")
-        console.print(f"   {r['content']}")
+        console.print(
+            f"   [dim]Session:[/dim] {r['title'] or '(untitled)'} "
+            f"[cyan]{r['session_id']}[/cyan]"
+            + (" [yellow](id match)[/yellow]" if r.get("match") == "session_id" else "")
+        )
+        if r.get("match") != "session_id":
+            console.print(f"   {r['content']}")
 
 
 @cli.command()
@@ -1131,9 +1135,27 @@ def redact(path, session_id, show):
 # Sessions
 # ---------------------------------------------------------------------------
 
-@cli.group()
+class _SessionGroup(click.Group):
+    """`spooling session <id>` is shorthand for `spooling session show <id>`."""
+
+    def resolve_command(self, ctx, args):
+        try:
+            return super().resolve_command(ctx, args)
+        except click.UsageError:
+            if args and not args[0].startswith("-") and "show" in self.commands:
+                return "show", self.commands["show"], args
+            raise
+
+
+@cli.group(cls=_SessionGroup)
 def session():
-    """Inspect and list local sessions."""
+    """Inspect and list local sessions.
+
+    \b
+    spooling session list                  list sessions with ids
+    spooling session show ID -m            read a session's full text
+    spooling session ID -m                 same as 'show ID'
+    """
     pass
 
 
@@ -1141,8 +1163,9 @@ def session():
 @click.option("--project", "-p", default=None, help="Filter by exact project name")
 @click.option("--cwd", default=None, help="Filter by cwd substring")
 @click.option("--title", default=None, help="Filter by title substring")
+@click.option("--id", "id_part", default=None, help="Filter by session id substring")
 @click.option("--limit", "-n", default=20, help="Max sessions to return (default: 20)")
-def session_list(project, cwd, title, limit):
+def session_list(project, cwd, title, id_part, limit):
     """List local sessions with optional filters."""
     from spooling.db import get_connection
     from datetime import datetime as _dt
@@ -1159,6 +1182,9 @@ def session_list(project, cwd, title, limit):
     if title:
         wheres.append("title LIKE ?")
         params.append(f"%{title}%")
+    if id_part:
+        wheres.append("id LIKE ?")
+        params.append(f"%{id_part}%")
     where_clause = ("WHERE " + " AND ".join(wheres)) if wheres else ""
     params.append(limit)
 
@@ -1176,8 +1202,8 @@ def session_list(project, cwd, title, limit):
         return
 
     table = Table(title=f"Sessions ({len(rows)})", show_lines=False)
-    table.add_column("ID", style="dim")
-    table.add_column("Provider", style="cyan")
+    table.add_column("Session ID", style="cyan", no_wrap=True)
+    table.add_column("Provider")
     table.add_column("Project")
     table.add_column("Title")
     table.add_column("Started", style="dim")
@@ -1194,7 +1220,7 @@ def session_list(project, cwd, title, limit):
                 raw_ts = None
         ts = raw_ts.strftime("%m/%d %H:%M") if raw_ts else ""
         table.add_row(
-            (r["id"] or "")[:12],
+            r["id"] or "",
             r["provider_id"] or "",
             _clean_project(r["project"] or ""),
             (r["title"] or "")[:45],
@@ -1208,15 +1234,30 @@ def session_list(project, cwd, title, limit):
 
 @session.command("show")
 @click.argument("session_id")
-@click.option("--messages", "-m", is_flag=True, help="Show full message content")
-def session_show(session_id, messages):
-    """Show full detail for a session including messages and tool calls."""
+@click.option("--messages", "-m", is_flag=True, help="Print the full session text (all messages)")
+@click.option("--max-chars", default=0, type=int, help="Truncate each message to N chars (0 = no limit)")
+def session_show(session_id, messages, max_chars):
+    """Show a session by id (full id or unique prefix), optionally with its full text."""
     from spooling.stats import get_session_detail
+    from spooling.sessions import resolve_session_ids
+
+    matches = resolve_session_ids(session_id)
+    if len(matches) > 1:
+        console.print(f"[yellow]'{session_id}' is ambiguous; matches:[/yellow]")
+        for m in matches:
+            console.print(f"  {m}")
+        raise SystemExit(1)
+    if matches:
+        session_id = matches[0]
 
     detail = get_session_detail(session_id)
     if not detail:
-        console.print(f"[yellow]Session not found: {session_id}[/yellow]")
-        return
+        console.print(
+            f"[yellow]Session not found: {session_id}[/yellow]\n"
+            "[dim]Find ids with 'spooling session list --id PART' or 'spooling search QUERY'. "
+            "If the session is recent, run 'spooling sync' first.[/dim]"
+        )
+        raise SystemExit(1)
 
     s = detail["session"]
     console.print(Panel(
@@ -1244,23 +1285,19 @@ def session_show(session_id, messages):
         console.print(table)
 
     if messages and detail["messages"]:
-        table = Table(title="Messages", show_lines=True)
-        table.add_column("Role", style="cyan", width=10)
-        table.add_column("Timestamp", style="dim", width=18)
-        table.add_column("Content")
         for m in detail["messages"]:
-            content = (m.get("content") or "")[:300]
+            role = m.get("role") or ""
+            color = "green" if role == "user" else "blue"
+            console.print(f"\n[{color}]{role}[/{color}] [dim]{str(m.get('timestamp') or '')[:19]}[/dim]")
+            content = m.get("content") or ""
+            if max_chars and len(content) > max_chars:
+                content = content[:max_chars] + "..."
+            console.print(content, markup=False, highlight=False)
             if m.get("tool_calls"):
                 tools = ", ".join(tc["name"] for tc in m["tool_calls"])
-                content += f"\n[dim]Tools: {tools}[/dim]"
-            table.add_row(
-                m.get("role", ""),
-                str(m.get("timestamp") or "")[:18],
-                content,
-            )
-        console.print(table)
+                console.print(f"Tools: {tools}", style="dim", markup=False)
     elif not messages and detail["messages"]:
-        console.print(f"[dim]{len(detail['messages'])} messages — pass --messages to show content[/dim]")
+        console.print(f"[dim]{len(detail['messages'])} messages — pass --messages to print the session text[/dim]")
 
 
 # ---------------------------------------------------------------------------

{spooling-0.2.6 → spooling-0.2.8}/spooling/mcp_server.py

@@ -10,6 +10,7 @@ Tools exposed:
   - list_traces(limit, provider, project)
   - get_trace(trace_id)
   - search_sessions(query, limit, project)
+  - get_session(session_id, include_messages)
   - get_stats()
   - get_top_vendors()
   - list_evals(rubric_id, limit)
@@ -306,6 +307,10 @@ def search_sessions(
 ) -> list[dict]:
     """Semantic search over Spooling's embedded session chunks. Returns ranked matches.
 
+    Each result includes ``session_id`` and ``title``. A session id (or prefix,
+    e.g. ``ses_e6310bd1``) in the query matches that session directly and ranks
+    first. Use ``get_session`` to read a result's full conversation.
+
     Falls back to Spooling Cloud ILIKE search when the local DB has no
     embedded results and a cloud API key is configured. Cloud results
     include a ``_source: "cloud"`` field.
@@ -374,6 +379,53 @@ def search_sessions(
     ]
 
 
+@mcp.tool()
+def get_session(
+    session_id: str,
+    include_messages: bool = True,
+    max_messages: int = 200,
+    max_chars: int = 4000,
+) -> dict:
+    """Fetch one session by id, including its conversation text.
+
+    Use after ``search_sessions`` (or ``list_traces``) to read what was said.
+    Accepts a full session id or a unique prefix (e.g. ``ses_e6310bd1``).
+
+    Args:
+        session_id: Full session id or unique prefix.
+        include_messages: Include the message text (default True).
+        max_messages: Max messages to return, oldest first (default 200).
+        max_chars: Truncate each message to this many characters (0 = no limit).
+    """
+    from spooling.sessions import resolve_session_ids
+    from spooling.stats import get_session_detail
+
+    matches = resolve_session_ids(session_id)
+    if not matches:
+        return {"error": f"session not found: {session_id}"}
+    if len(matches) > 1:
+        return {"error": f"ambiguous session id: {session_id}", "matches": matches}
+
+    detail = get_session_detail(matches[0])
+    if not detail:
+        return {"error": f"session not found: {session_id}"}
+
+    out: dict = {
+        "session": detail["session"],
+        "tool_summary": detail["tool_summary"],
+        "message_count": len(detail["messages"]),
+    }
+    if include_messages:
+        msgs = detail["messages"][: max(0, max_messages)]
+        for m in msgs:
+            content = m.get("content") or ""
+            if max_chars and len(content) > max_chars:
+                m["content"] = content[:max_chars] + "..."
+        out["messages"] = msgs
+        out["truncated"] = len(detail["messages"]) > len(msgs)
+    return out
+
+
 @mcp.tool()
 def get_stats() -> dict:
     """Top-line Spooling stats: total traces, spans, tools, llm calls, cost, errors.

{spooling-0.2.6 → spooling-0.2.8}/spooling/search.py

@@ -73,7 +73,40 @@ def _load_index(conn, dim: int) -> _Index:
 
 
 def search(query: str, limit: int = 10, project: str | None = None) -> list[dict]:
-    """Search session chunks by semantic similarity."""
+    """Search session chunks by semantic similarity.
+
+    Session ids (full or partial) found in the query are matched directly and
+    ranked first, so ids are searchable alongside titles and content.
+    """
+    id_hits = _id_matches(query, project)
+    results = _semantic_search(query, limit, project)
+    seen = {r["session_id"] for r in id_hits}
+    merged = id_hits + [r for r in results if r["session_id"] not in seen]
+    return merged[:limit]
+
+
+def _id_matches(query: str, project: str | None) -> list[dict]:
+    from spooling.sessions import find_sessions_by_id_in_query
+
+    out = []
+    for s in find_sessions_by_id_in_query(query):
+        if project and s["project"] != project:
+            continue
+        out.append({
+            "content": s["title"] or "(untitled)",
+            "role": "session",
+            "project": s["project"],
+            "timestamp": s["started_at"],
+            "session_id": s["id"],
+            "similarity": 1.0,
+            "title": s["title"],
+            "cwd": s["cwd"],
+            "match": "session_id",
+        })
+    return out
+
+
+def _semantic_search(query: str, limit: int = 10, project: str | None = None) -> list[dict]:
     query_arr = np.array(embed_text(query), dtype=np.float32)
 
     conn = get_connection()