@superbased/observer 1.7.23 → 1.7.25

package/README.md

@@ -55,6 +55,12 @@ A note for shared / CI machines where `npm install -g` may need
 `sudo`: see [Troubleshooting → EACCES](#npm-install--g-fails-with-eacces-permission-denied)
 for user-writable-prefix and version-manager fixes.
 
+> **Python users:** `pip install superbased-observer` ships the
+> same binary; version numbers are kept in lock-step. See
+> [the PyPI page](https://pypi.org/project/superbased-observer/).
+> Don't install both globally — whichever directory comes first on
+> `$PATH` wins, which gets confusing if their versions drift.
+
 Pre-built binaries ship for:
 
 | Platform              | Architecture |
@@ -551,7 +557,7 @@ a content-aware compressor. Six compressors:
 | Mechanism | What it does | When it fires |
 |-----------|--------------|---------------|
 | **json**  | Replaces every scalar value with a type sentinel (`"<string>"`, `"<number>"`, …) preserving structure (keys, arrays, nesting). Arrays of length > 1 collapse to one element with `_len: N`. | API responses, structured logs, telemetry exports. JSON tool_results are usually the biggest savings target. |
-| **code**  | Heuristic skeleton: keeps top-of-file imports + signature lines (function / method / class / struct / interface / type), drops bodies. | Source code files. **Opt-in only** (excluded from default `compress_types`) because the model often needs to read full code. |
+| **code**  | Heuristic skeleton: keeps top-of-file imports + signature lines (function / method / class / struct / interface / type), drops bodies. | Source code files. **On by default** as of v1.7.23 for the `claude-code` recipe (V7-24 empirical winner). |
 | **logs**  | Two-pass: collapses adjacent identical lines to `<line> [×N]`, then head+tail-truncates to 200 lines if still long. | Log-shaped output — `go test ./...`, `npm run build`, polling/retry loops. Lossless on distinct lines; only the truncate pass is lossy. |
 | **text**  | Catch-all for content not classified as code/json/logs/diff/html. Head+tail truncation: keeps 40 + 40 lines on inputs over 80 lines. | Markdown bodies, README excerpts, narrative descriptions. |
 | **diff**  | Strips unified-diff context beyond ±1 line of each change. Keeps every header, every `+`/`-` line, drops the rest with elision markers. | `git diff`, patch tool outputs. Lossless on changes; lossy only on the cheap-to-rebuild context. |
@@ -640,6 +646,53 @@ summary model: `summary_model` for Anthropic, `openai_summary_model` for
 OpenAI/Codex), and `[compression.conversation.compaction]`. The full knob
 reference lives in `docs/compression-modes.md`.
 
+### Measured savings (v1.7.23)
+
+We A/B every shipped recipe against an OFF baseline on a real refactor
+workload (`lumen` TypeScript codebase, 408-line Zustand store →
+4 domain sub-stores) on the v1.7.22 binary tip. The numbers below are
+the **most recent statistically-meaningful measurements**.
+
+**Pick a recipe based on which model you're running:**
+
+| Recipe | Use when your model is… | Workload | n | Δ vs OFF (mean cost) | What's compressed |
+|---|---|---|---|---|---|
+| **`claude-code`** *(default)* | Any Anthropic Claude model — `claude-sonnet-4-6`, `claude-opus-4-7`, `claude-haiku-4-5`, … | Refactor, Claude Sonnet 4.6 via Claude Code 2.1.158 | n=8 B vs n=4 OFF | **−6.9%** (CV 7.6%; tighter than OFF's 7.5%) | json + logs + code bodies; cache-aware; stash disabled |
+| **`codex-variant`** | OpenAI's `-codex` reasoning fork — `gpt-5.3-codex`, `gpt-5.4-codex`, `gpt-5-codex-agent`, anything matching `*-codex*` | Refactor, gpt-5.3-codex | n=10 B vs n=10 OFF | **−10%** ($0.270 vs $0.300) | Tools-defs trim; cache-aware; no per-type compression |
+| **`codex-safe`** | Plain OpenAI GPT under the codex CLI — `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.5`, `gpt-4o`, any non-`-codex` | Refactor, gpt-5.4 + `apply_patch` | n=3 B vs n=4 OFF | not statistically distinguishable on this workload | logs only; cache-aware |
+
+The word **"variant"** in `codex-variant` refers to the *model variant* (the `-codex` reasoning fork of GPT), NOT a variant of the codex CLI. Both codex recipes are for the codex CLI; they differ only in which model family they assume. `codex-safe` is so named because plain GPT models tolerate logs trimming safely — it's not "safer than codex-variant."
+
+**Honest caveats:**
+
+- **Workload-dependent.** The `codex-safe` row on gpt-5.4 was
+  inconclusive because the test workload used `apply_patch` (classified
+  as `code`, not `logs`) so `compress_types=["logs"]` never fired —
+  the proxy was a functional no-op and the cost variance was session
+  noise. A Bash-heavy workload would tell a different story.
+- **`claude-code` requires `ENABLE_TOOL_SEARCH=true`** in your shell.
+  Without it, Claude Code's SDK disables ToolSearch under
+  `ANTHROPIC_BASE_URL` and eager-inlines all MCP schemas (~+21K
+  tokens per turn). The proxy then becomes a net loss instead of
+  the −6.9% above. Setup steps cover this; verify with
+  `printenv ENABLE_TOOL_SEARCH`.
+- **`stash` stays disabled by default for Anthropic** (V7-25 finding:
+  +25% cost on n=1 due to prefix-cache miss; stash markers break
+  Anthropic's content-hash cache). Operators can opt in for a measured
+  workload but should A/B their own.
+- **Historic claims of higher savings are retracted.** The v1.4.38
+  release notes cited −14.8%; the project itself walked that back
+  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
+```
+
 
 ## Cost and token math
 
@@ -981,25 +1034,33 @@ port = 8082                                  # in config.toml
 
 ## Security and privacy
 
-- **No telemetry**. The observer never makes outbound network calls
-  except: (a) the proxy forwarding to the upstream API on your
-  behalf, (b) optional codegraph-MCP integration if you've configured
-  it. Both are explicit.
-- **Local-only HTTP**. The proxy and dashboard bind to
-  `127.0.0.1` by default. Don't bind to `0.0.0.0` unless you've
-  thought about it — there's no auth.
-- **Secrets scrubbing**. Tool inputs and outputs are passed through
-  a configurable scrubber (`internal/scrub`) that redacts API keys,
-  bearer tokens, and other obvious secrets before persistence. Not a
-  guarantee — review the rules in `~/.observer/config.toml` for your
-  own secret formats.
-- **Database**. `~/.observer/observer.db` is a SQLite file. Owns
-  the same security as your `~/.claude/` and `~/.codex/` session
-  logs (which already contain the same content). Encrypt the disk
-  if your threat model needs that.
-- **Logs**. `~/.observer/logs/` carries operational logs (start /
-  stop, errors, retention). Not request bodies — those are in the
-  DB only.
+**Local-only. No telemetry. No remote anything.** The watcher, hook
+handler, dashboard, MCP server, and CLI never make an outbound network
+call on observer's behalf. The only code paths that touch the network
+are the optional API proxy (which forwards **your** requests unchanged
+to the AI provider you already use) and a handful of explicit opt-in
+features (message-summary LLM, codegraph MCP, Teams org-server).
+
+The full privacy statement — what observer stores, what it reads,
+what it never stores, the explicit list of outbound-network call sites
+gated behind config, and how to verify "no telemetry" yourself with
+`grep`, `strings`, and a network-namespaced shell — lives in
+[`PRIVACY.md`](https://github.com/marmutapp/superbased-observer/blob/main/PRIVACY.md).
+
+Operational shorthand:
+
+- **Local-only HTTP.** The proxy and dashboard bind to `127.0.0.1`
+  by default. Don't bind to `0.0.0.0` unless you've thought about
+  it — there's no auth.
+- **Secrets scrubbing.** Tool inputs and outputs pass through
+  `internal/scrub/` before persistence; review the regex set if your
+  secrets follow non-default formats.
+- **Database.** `~/.observer/observer.db` is a SQLite file with the
+  same security posture as your `~/.claude/` and `~/.codex/` session
+  logs (which already hold the same content). Encrypt the disk if
+  your threat model needs that.
+- **Full delete.** `rm -rf ~/.observer/` removes everything observer
+  ever stored — no traces elsewhere on your system.
 
 
 ## Source, contributing, license

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superbased/observer",
-  "version": "1.7.23",
+  "version": "1.7.25",
   "description": "SuperBased Observer — capture, normalize, compress, and analyze AI coding tool activity across Claude Code, Codex, Cursor, Cline/Roo, and Copilot.",
   "keywords": [
     "ai",
@@ -36,11 +36,11 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@superbased/observer-linux-x64": "1.7.23",
-    "@superbased/observer-linux-arm64": "1.7.23",
-    "@superbased/observer-darwin-x64": "1.7.23",
-    "@superbased/observer-darwin-arm64": "1.7.23",
-    "@superbased/observer-win32-x64": "1.7.23"
+    "@superbased/observer-linux-x64": "1.7.25",
+    "@superbased/observer-linux-arm64": "1.7.25",
+    "@superbased/observer-darwin-x64": "1.7.25",
+    "@superbased/observer-darwin-arm64": "1.7.25",
+    "@superbased/observer-win32-x64": "1.7.25"
   },
   "scripts": {
     "test": "node bin/observer.js --version"