@superbased/observer 1.18.0 → 1.20.0

package/README.md

@@ -7,12 +7,27 @@
 
 **Homepage:** [https://superbased.app/](https://superbased.app/)
 
-**Capture, normalize, compress, and analyze every AI coding tool call you
-run** — across Claude Code, Codex, Cursor, Cline / Roo Code + Cline CLI,
-GitHub Copilot (VS Code), GitHub Copilot CLI, OpenCode, OpenClaw, Pi,
-Google Antigravity, Gemini CLI, Cowork, Nous Research's Hermes Agent, and
-Kilo Code (legacy IDE extension + CLI) — in one local single-binary tool.
-No telemetry, no cloud, no data leaves your machine.
+**Claude Code cost tracking. Cursor token usage. Codex spend.
+AI coding agent observability — one local tool, proxy-accurate.**
+SuperBased Observer captures, normalizes, and analyzes every AI
+coding tool call across **26 adapters** — Claude Code, Codex, Cursor,
+Cline + Cline CLI, GitHub Copilot (VS Code) + Copilot CLI, Gemini CLI,
+OpenCode, Google Antigravity, Cowork, Nous Research's Hermes Agent,
+Kilo Code (legacy IDE extension + CLI), Aider, Goose, Devin, OpenClaw,
+Pi, and more — in one local single-binary tool. An optional API proxy
+reconciles the *exact* tokens your provider billed (net input, cache
+5m/1h splits, reasoning tokens, long-context surcharges) instead of a
+JSONL-derived estimate. No telemetry, no cloud, no data leaves your
+machine.
+
+**Two planes, one binary.** Plane B is coding-agent observability —
+desktop-first: this package, capturing your own AI coding tools, with
+an optional team rollup server. Plane A is general LLM-app
+observability — admin-server-first: OTLP trace/span capture, evals,
+and an LLM-as-judge input-admission guardrail for an application you
+host. Most installs only ever use Plane B; see the [main
+repo](https://github.com/marmutapp/superbased-observer#readme) for
+the full two-plane explainer.
 
 <p align="center">
   <img src="https://github.com/marmutapp/superbased-observer/raw/main/docs/assets/infographics/one-local-path.png" alt="One local path for AI coding activity" width="780">
@@ -22,6 +37,7 @@ No telemetry, no cloud, no data leaves your machine.
 
 - [Install](#install)
 - [Five-minute quickstart](#five-minute-quickstart)
+- [Two planes, one binary](#two-planes-one-binary)
 - [Per-AI-client setup](#per-ai-client-setup)
 - [Architecture in detail](#architecture-in-detail)
 - [Dashboard tour](#dashboard-tour)
@@ -125,6 +141,21 @@ MCP and codex routing are explicit-only because both write per-client
 config files. Hooks self-heal on every `start`.
 
 
+## Two planes, one binary
+
+Everything below this line — proxy routing, per-client capture,
+compression, cache, MCP tools — is **Plane B: coding-agent
+observability**, desktop-first. It's what this package is for: a
+local node that watches your own AI coding tools and gives you
+proxy-accurate cost and cache numbers, with an optional team rollup
+server for org-wide spend visibility. The same binary also ships
+**Plane A: general LLM-app observability**, admin-server-first — OTLP
+trace/span capture, evals, and an LLM-as-judge input-admission
+guardrail for an application *you* host, whose end users route
+through Observer. Most installs only ever touch Plane B; Plane A is
+opt-in and unrelated to your own coding-agent traffic. Full explainer:
+[superbased.app/docs/getting-started/two-planes](https://superbased.app/docs/getting-started/two-planes).
+
 ## Per-AI-client setup
 
 ### Routing through the proxy — the canonical section
@@ -277,10 +308,12 @@ requests.
 
 ### 5. MCP server (stdio) — opt-in via `observer init`
 
-19 read-only tools the AI client itself can call mid-conversation —
-`check_file_freshness`, `get_last_test_result`, `search_past_outputs`,
-`search_symbols`, etc. (plus `retrieve_stashed` when the proxy stash
-is configured).
+21 read-only tools are always registered — `check_file_freshness`,
+`get_last_test_result`, `search_past_outputs`, `search_symbols`,
+etc. — plus 4 more (`get_file`, `get_symbols`, `get_relations`,
+`retrieve_stashed`) that register conditionally, only when the
+capability they depend on (the proxy stash, or the codeintel index)
+is actually configured.
 Powers cross-client tool sharing: if Claude Code ran `go test`,
 Cursor's MCP query for the latest test result will return Claude
 Code's run. The code-aware tools (`get_symbols`, `get_relations`,
@@ -535,7 +568,7 @@ migrations 036 + 037 — never pushed to a Teams org server, pinned by
   (`[cachetrack].retention_days = 90`); the maintenance tick prunes
   stale `cache_*` rows alongside the existing retention pass.
 
-Operator reference: [`docs/cache-tracking.md`](https://github.com/marmutapp/superbased-observer/blob/main/docs/cache-tracking.md).
+Operator reference: [superbased.app/docs/guides/cache-tracking](https://superbased.app/docs/guides/cache-tracking).
 
 ### Suggestions tab
 
@@ -690,11 +723,12 @@ explaining the actual algorithm.
 
 Once you've run `observer init` (it's opt-in — `observer start`
 alone does NOT register the MCP server), every connected AI client
-gets these 19 tools registered as an MCP server — plus
-`retrieve_stashed` when the proxy stash is configured. They're
-**read-only** queries against the unified database, so any agent
-can read any other agent's recorded work — true cross-platform
-tool-call sharing.
+gets 21 tools registered as an MCP server always, plus 4 more
+(`get_file`, `get_symbols`, `get_relations`, `retrieve_stashed`) that
+register conditionally, only when the capability they depend on is
+actually configured. They're **read-only** queries against the
+unified database, so any agent can read any other agent's recorded
+work — true cross-platform tool-call sharing.
 
 | Tool                              | Purpose |
 |-----------------------------------|---------|
@@ -711,12 +745,17 @@ tool-call sharing.
 | `get_cost_summary`                | Daily / per-model / per-session cost rollups |
 | `get_redundancy_report`           | Stale rereads, repeated commands, cross-tool overlap for the project |
 | `list_actions_around`             | ±N actions adjacent to a pivot `action_id` — browse a session's local timeline cheaply |
-| `get_file`                        | The file's current bytes (or at a given commit), with a path-safety gate + audit |
-| `get_symbols`                     | Resolve a symbol name + range to its file path + body (codeintel-backed) |
-| `get_relations`                   | Codeintel BFS — who calls / is called by this symbol |
 | `search_symbols`                  | Fuzzy symbol search across the project's codeintel index (Tier-C) |
+| `get_output_composition`          | Code vs. explanation split of a session's output, by bytes, with the code:explanation ratio and languages used |
+| `get_suggestions`                 | Top dollar/time-quantified cost & quality suggestions from the local advisor |
 | `cache_status`                    | Live prompt-cache health: which caches are warm, expiring, or cold, with value-at-risk |
 | `get_model_recommendation`        | Evidence-backed model suggestion per turn-kind, from the local Model Value Report |
+| `get_routing_status`              | Model-routing layer state: phase, available policy templates, tier-table size, decision-log counters |
+| `continue_session`                | A distilled, scrubbed handover of a session from another AI tool, so you can continue its work here |
+| `get_session_message`             | One full, un-excerpted message from a session's transcript — pulls the complete body a handover excerpt truncated |
+| `get_file` _(conditional)_        | The file's current bytes (or at a given commit), with a path-safety gate + audit |
+| `get_symbols` _(conditional)_     | Resolve a symbol name + range to its file path + body (codeintel-backed) |
+| `get_relations` _(conditional)_   | Codeintel BFS — who calls / is called by this symbol |
 | `retrieve_stashed` _(conditional)_| Pulls original bytes of a tool_result the proxy compressed away. Only registered when `[compression.conversation].stash` is configured. |
 
 **Cost trade-off**: with the MCP registered, the AI client sends the
@@ -899,13 +938,9 @@ The word **"variant"** in `codex-variant` refers to the *model variant* (the `-c
   after a deeper repro showed it was within noise. The numbers above
   are the post-retraction floor.
 
-**Reproduce it yourself:**
-
-```bash
-# Full methodology, raw arm data, per-arm cost rows, and a reproducer
-# script live in this repo:
-docs/v1.7.23-compression-savings-empirical-2026-06-01.md
-```
+**Reproduce it yourself:** the numbers above are workload-specific, not a
+guarantee — A/B your own traffic with `observer profile show <name>` and
+an OFF-baseline comparison before relying on any of them in production.
 
 
 ## Cost and token math
@@ -1001,6 +1036,18 @@ What makes it different from standalone command-guards:
   guardrails suggested from your own observed spend (p95 + headroom)
   with a daily burn-down meter, MCP pin approvals, and one-click
   compliance evidence downloads.
+- **Alerting, not just logging.** Guard verdicts and budget/obs-alert
+  crossings can push out through desktop toast notifications
+  (`[guard.alerts] desktop = true`) and outbound webhooks — generic,
+  Slack, Discord, or PagerDuty (`[[guard.cloud.webhooks]]` for guard
+  events; the org server's per-budget and per-obs-alert-rule webhook
+  columns for spend/eval alerts) — each behind its own opt-in, routed
+  through one egress worker with an endpoint allowlist and a payload
+  cap. Nothing fires until you configure it.
+- **Optional process observability.** `[observer.process]` (opt-in,
+  off by default) attaches the OS-level process tree — Linux eBPF or
+  Windows ETW — beneath each captured session, for runtime side
+  effects hooks alone can't see.
 
 Honest scope: hooks see declared commands, not side effects (use OS
 sandboxes for containment — the guard detects and recommends them);
@@ -1020,17 +1067,13 @@ observer guard simulate --since 168h  # what would last week have flagged?
 observer guard enable --enforce       # flip to enforce when ready
 ```
 
-Full references:
-[guard.md](https://github.com/marmutapp/superbased-observer/blob/main/docs/guard.md)
-(operator guide + getting started),
-[guard-rules.md](https://github.com/marmutapp/superbased-observer/blob/main/docs/guard-rules.md)
-(rule catalog),
-[guard-policy-authoring.md](https://github.com/marmutapp/superbased-observer/blob/main/docs/guard-policy-authoring.md)
-(writing rules + cookbook),
-[guard-enforce-runbook.md](https://github.com/marmutapp/superbased-observer/blob/main/docs/guard-enforce-runbook.md)
-(the observe→enforce migration),
-[guard-compliance.md](https://github.com/marmutapp/superbased-observer/blob/main/docs/guard-compliance.md)
-(SOC 2 / NIST mapping).
+Full reference: [superbased.app/docs/guides/security-guard](https://superbased.app/docs/guides/security-guard)
+(concepts, modes, the observe→enforce path, Teams policy merge, the honest
+"what guard does NOT do" list). The rule catalog, policy-authoring cookbook,
+enforce runbook, and SOC 2 / NIST compliance mapping ship as
+`docs/guard-rules.md`, `docs/guard-policy-authoring.md`,
+`docs/guard-enforce-runbook.md`, and `docs/guard-compliance.md` in the
+source repository.
 
 ## Terminology and glossary
 
@@ -1060,7 +1103,8 @@ dashboard) has the full versions with cross-links.
   bodies. Pass 1 = per-content-type compression, Pass 2 = drop with
   marker. See [Compression mechanisms](#compression-mechanisms).
 - **Cross-platform tool calling** — every AI client connected via
-  `observer init` can call the 19 MCP tools against the unified
+  `observer init` can call the 25 MCP tools (21 always-on + 4
+  conditional) against the unified
   database. So Cursor's `get_last_test_result` can return a `go test`
   Claude Code ran an hour earlier.
 - **Cross-thread reread** — the parent thread re-reads a file the
@@ -1121,11 +1165,11 @@ Every command supports `--help` for the full surface.
 |------------------------------------|---------|
 | `observer init`                    | Register hooks + MCP server + durable proxy routes with installed AI clients (each side defaults on; opt out with `--skip-hooks` / `--skip-mcp` / `--skip-proxy-route`). With **zero flags on a terminal** it runs an interactive checklist instead: detects your tools, previews each pending config write, and asks consent one write at a time (MCP never pre-selected). Any flag or redirected stdio keeps the batch behaviour. |
 | `observer uninstall`               | Reverse `observer init` |
-| `observer start`                   | Run watcher + dashboard + proxy in one process (recommended). Auto-opens the dashboard on interactive launches. Flags: `--dashboard-addr ADDR` (default `127.0.0.1:8081`), `--no-dashboard` to skip the HTTP UI, `--no-open` to skip the browser. |
+| `observer start`                   | Run watcher + dashboard + proxy in one process (recommended). Auto-opens the dashboard on interactive launches. Flags: `--dashboard-addr ADDR` (default `127.0.0.1:8081`; for a durable setting use `[dashboard].addr` in config or the `OBSERVER_DASHBOARD_ADDR` env var — precedence flag > env > config > default), `--no-dashboard` to skip the HTTP UI, `--no-open` to skip the browser. |
 | `observer claude [-- args…]`       | Launch Claude Code routed through the proxy for that session only (no config writes; fresh Pro/Max OAuth token re-exported so the SDK can't bypass). `--verify` runs pre-flight checks without launching. |
 | `observer codex [-- args…]`        | Launch Codex routed through the proxy for that session only (injects `openai_base_url` via argv; no config writes). |
 | `observer watch`                   | Long-running JSONL watcher only |
-| `observer dashboard --addr ADDR`   | HTTP dashboard only |
+| `observer dashboard --addr ADDR`   | HTTP dashboard only. `--addr`/`--port` still win when passed; otherwise falls back to `OBSERVER_DASHBOARD_ADDR` > `[dashboard].addr` config > default. |
 | `observer proxy start`             | Reverse proxy only |
 | `observer scan`                    | One-shot ingest of existing JSONL files (catch-up after install) |
 | `observer status`                  | DB stats + recent activity |
@@ -1171,8 +1215,12 @@ anthropic_upstream = "https://api.anthropic.com"
 openai_upstream = "https://api.openai.com"
 
 [dashboard]
-listen_addr = "127.0.0.1"
-port = 8081
+# Durable dashboard listen address as host:port. Empty/omitted = the built-in
+# 127.0.0.1:8081 default. Precedence: `observer start --dashboard-addr` flag >
+# OBSERVER_DASHBOARD_ADDR env var > this value > default. Binds at daemon start
+# (restart to apply). A non-loopback host still fails closed unless [remote] is
+# armed.
+addr = "127.0.0.1:8081"
 
 [compression.conversation]
 enabled = false            # opt-in; default off

package/README.template.md

@@ -7,12 +7,27 @@
 
 **Homepage:** [https://superbased.app/](https://superbased.app/)
 
-**Capture, normalize, compress, and analyze every AI coding tool call you
-run** — across Claude Code, Codex, Cursor, Cline / Roo Code + Cline CLI,
-GitHub Copilot (VS Code), GitHub Copilot CLI, OpenCode, OpenClaw, Pi,
-Google Antigravity, Gemini CLI, Cowork, Nous Research's Hermes Agent, and
-Kilo Code (legacy IDE extension + CLI) — in one local single-binary tool.
-No telemetry, no cloud, no data leaves your machine.
+**Claude Code cost tracking. Cursor token usage. Codex spend.
+AI coding agent observability — one local tool, proxy-accurate.**
+SuperBased Observer captures, normalizes, and analyzes every AI
+coding tool call across **26 adapters** — Claude Code, Codex, Cursor,
+Cline + Cline CLI, GitHub Copilot (VS Code) + Copilot CLI, Gemini CLI,
+OpenCode, Google Antigravity, Cowork, Nous Research's Hermes Agent,
+Kilo Code (legacy IDE extension + CLI), Aider, Goose, Devin, OpenClaw,
+Pi, and more — in one local single-binary tool. An optional API proxy
+reconciles the *exact* tokens your provider billed (net input, cache
+5m/1h splits, reasoning tokens, long-context surcharges) instead of a
+JSONL-derived estimate. No telemetry, no cloud, no data leaves your
+machine.
+
+**Two planes, one binary.** Plane B is coding-agent observability —
+desktop-first: this package, capturing your own AI coding tools, with
+an optional team rollup server. Plane A is general LLM-app
+observability — admin-server-first: OTLP trace/span capture, evals,
+and an LLM-as-judge input-admission guardrail for an application you
+host. Most installs only ever use Plane B; see the [main
+repo](https://github.com/marmutapp/superbased-observer#readme) for
+the full two-plane explainer.
 
 <p align="center">
   <img src="https://github.com/marmutapp/superbased-observer/raw/main/docs/assets/infographics/one-local-path.png" alt="One local path for AI coding activity" width="780">
@@ -22,6 +37,7 @@ No telemetry, no cloud, no data leaves your machine.
 
 - [Install](#install)
 - [Five-minute quickstart](#five-minute-quickstart)
+- [Two planes, one binary](#two-planes-one-binary)
 - [Per-AI-client setup](#per-ai-client-setup)
 - [Architecture in detail](#architecture-in-detail)
 - [Dashboard tour](#dashboard-tour)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@superbased/observer",
-  "version": "1.18.0",
-  "description": "SuperBased Observer — capture, normalize, compress, and analyze AI coding tool activity across Claude Code, Codex, Cursor, Cline/Roo, and Copilot.",
+  "version": "1.20.0",
+  "description": "Claude Code cost tracking, Cursor token usage, Codex spend — AI coding agent observability across 26 adapters, proxy-accurate token counts and cost.",
   "keywords": [
     "ai",
     "observability",
@@ -12,7 +12,12 @@
     "cursor",
     "mcp",
     "tokens",
-    "cost"
+    "cost",
+    "cost-tracking",
+    "token-usage",
+    "ai-coding-agent",
+    "llm-observability",
+    "spend"
   ],
   "homepage": "https://superbased.app/",
   "repository": {
@@ -36,11 +41,11 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@superbased/observer-linux-x64": "1.18.0",
-    "@superbased/observer-linux-arm64": "1.18.0",
-    "@superbased/observer-darwin-x64": "1.18.0",
-    "@superbased/observer-darwin-arm64": "1.18.0",
-    "@superbased/observer-win32-x64": "1.18.0"
+    "@superbased/observer-linux-x64": "1.20.0",
+    "@superbased/observer-linux-arm64": "1.20.0",
+    "@superbased/observer-darwin-x64": "1.20.0",
+    "@superbased/observer-darwin-arm64": "1.20.0",
+    "@superbased/observer-win32-x64": "1.20.0"
   },
   "scripts": {
     "test": "node bin/observer.js --version"