@compaction/cli 0.3.0 → 0.3.1

package/README.md

@@ -1,19 +1,53 @@
 # @compaction/cli
 
-**The free, local-first CLI for capturing and measuring AI agent traces.** It captures
-supported agent sessions on your own machine, shows input/output tokens and estimated spend
-with honest labels, and writes local reports and redacted share bundles. Everything runs
-locally and writes local files only — **no account, no telemetry, no upload by default.**
+**The free, local-first CLI for the Compaction Gateway — a local, OpenAI-compatible proxy that
+measures your AI traffic without changing it.** Point your OpenAI-compatible client's base URL at
+the local gateway (or launch your workflow through it) and it forwards traffic to your provider and
+records **content-free** token/cache receipts — counts and labels only, never prompt/response
+content. Your provider key stays on the client. The CLI also captures and measures agent traces
+locally. Everything runs on your machine — **no account, no telemetry, no upload to Compaction.**
+
+> The free CLI runs the **local Gateway** (byte-safe **record** mode + content-free receipts, plus
+> an **explicit, experimental deterministic apply/recovery**), captures and measures agent traces,
+> and performs deterministic local compaction with the basic policies (`compact`) — writing honest
+> before/after artifacts. The **learned context model (LCM), learned optimization engine, hosted /
+> team control plane, verified-savings logic, and advanced proprietary evals are NOT in the npm /
+> free CLI** — they are the **opt-in Compaction API**, which is **not a live hosted service yet**.
+
+## The Gateway (local, byte-safe)
+
+The Compaction **Gateway** is a **local, OpenAI-compatible reverse proxy for OpenAI-compatible
+clients**. Point your client's base URL at it, or launch your workflow through it, and it forwards
+traffic to your provider and records **content-free** token/cache receipts (counts / structure /
+labels only — never prompt/response content). Your provider key rides straight through to the
+provider and is **never read, stored, or logged**. Set it up from onboarding (`compaction` →
+**Gateway setup**), or directly:
 
-> **The free CLI captures, measures, inspects, reports, redacts — and performs deterministic
-> local compaction with the basic policies (`compact`), writing honest before/after artifacts.**
-> Advanced verification, recommendation and apply guidance, advanced policies, and team
-> reporting are **not** in the free CLI — they are the **opt-in Compaction API**, which is
-> **not a live hosted service yet**.
-
-## What the CLI does
+```bash
+compaction gateway start                  # start the local gateway (RECORD mode: byte-safe, no mutation)
+compaction gateway run -- npm run dev      # run a command through the gateway (no baseURL copy-paste)
+compaction gateway status                  # requests observed + a content-free receipts rollup
+compaction gateway activate                # print env exports:  eval "$(compaction gateway activate)"
+```
 
-Everything below runs on your machine and writes local files only:
+- **Record mode is byte-safe** — it forwards your request and the provider's response
+  **byte-for-byte** and never changes either. Receipts are content-free and local-only (gitignored).
+- **Explicit, experimental deterministic apply** (`--mode apply --policy deterministic-dedupe`) can
+  remove **exact-duplicate large blocks** from known-safe requests. It is **off by default**,
+  opt-in, and **retains the original locally** (`compaction gateway recover <id>`). Unknown/complex
+  shapes **fail closed** (forwarded unchanged); system/developer instructions and tool schemas are
+  never touched; the **response is never changed**.
+- **No hosted/managed proxy or model routing.** The local Gateway is an OpenAI-compatible reverse
+  proxy for compatible clients — it runs on your machine.
+- **Claim boundary.** The gateway reports **provider-reported** token/cache counts (or
+  `unavailable`) — it makes **no cost-savings, no output-token-savings, and no billing-confirmed
+  claim**. A model-visible **input** reduction is stated only when apply actually changed the
+  request (a **local-estimate** before/after; the original is retained) — never a cost or
+  output-token figure, and never a "no context lost" claim.
+
+## Trace / capture utilities (other local tools)
+
+Beyond the Gateway, the free CLI captures and measures agent traces locally — local files only:
 
 - **Capture supported agent sessions.** Claude Code is the primary supported workflow
   (`capture claude-code`); OpenAI Agents SDK (`capture openai-agents`) and Codex / local-file
@@ -34,55 +68,54 @@ Everything below runs on your machine and writes local files only:
 - **Build a local context store and retrieve from it.** `context add` accumulates source-pointed
   items from a captured/imported trace into a local, size-capped store; `context get`
   deterministically retrieves and assembles the active context for a query under a token budget,
-  printing it **with source pointers** plus local retrieval **diagnostics** (what was
-  considered / included / dropped, the recoverable fraction, latency). Local-only and
-  deterministic — **no model, no embeddings, no network**. It reports **diagnostics only** (no
-  quality or sufficiency verdict on your data) and makes **no savings claim** (see `spend` /
-  `summary` for cost).
-- **Write local reports.** `analyze` writes local JSON + Markdown reports under an
-  operator-chosen output directory. Local files only.
+  printing it **with source pointers** plus local retrieval **diagnostics**. Local-only and
+  deterministic — **no model, no embeddings, no network**. It reports **diagnostics only** and
+  makes **no savings claim**.
+- **Write local reports.** `analyze` writes local JSON + Markdown reports under an operator-chosen
+  output directory. Local files only.
 - **Create redacted, content-free share bundles.** `feedback --redact` writes a redacted,
   privacy-safe bundle as a **local file only — never uploaded**, and only with an explicit write
   gesture (`--yes`).
-- **No upload by default.** There is **no telemetry**. The **only** network call in the free CLI
-  is the explicitly operator-invoked, read-only `capture provider-usage` (credential supplied via
-  an environment variable only; aggregate usage/cost figures only, no prompt/completion content).
 
-The free CLI deliberately answers the first-value question — *"where is my context being wasted,
-and roughly what does it cost?"* — entirely locally, with honest labels.
+## Free (npm) vs. private (opt-in API)
 
-## What requires the Compaction API (opt-in — not in the free CLI)
+**In the free / local CLI (npm):**
 
-These are **not** part of the free local CLI:
+- the **local Gateway** — record mode, `status`, content-free receipts, `gateway run`,
+- **explicit deterministic apply / dry-run / recover** (experimental, opt-in),
+- **capture / import / analyze / spend / compact / context / feedback** (local trace utilities).
 
-- **Recommendation** — a recommended-policy verdict (`recommend`) for a captured trace.
-- **Advanced verification** — stronger checks on what a compacted context retains (incl. `compact --eval`).
-- **Apply guidance** — a readiness verdict and a review/approval path before any context is applied.
-- **Advanced policies & team reporting** — configurable behavior controls beyond the basic
-  deterministic policies, and cross-run / team reporting.
+**NOT in the npm / free CLI** (these are the opt-in Compaction API — **not a live hosted service
+yet**):
 
-> **The Compaction API is not broadly hosted yet.** There is **no live hosted service today**.
-> Until the API is available, these capabilities are **on the roadmap / opt-in**, not present in
-> the free CLI. The honesty rails carry over unchanged: cost stays an **estimate** unless
-> billing-confirmed (no figure carries that label today); verification is **deterministic
-> recoverability, NOT semantic/meaning preservation**; and there is **no auto-apply** — every
-> application is an explicit operator gesture.
+- the **LCM / learned context model**,
+- the **learned optimization engine**,
+- the **hosted / team control plane**,
+- **verified-savings** logic,
+- **advanced proprietary evals** (and recommendation / advanced verification / apply-guidance / advanced policies).
+
+> **The Compaction API is not broadly hosted yet.** There is **no live hosted service today**. The
+> honesty rails carry over unchanged: cost stays an **estimate** unless billing-confirmed (no figure
+> carries that label today); verification is **deterministic recoverability, NOT semantic/meaning
+> preservation**; and there is **no auto-apply** — every application is an explicit operator gesture.
 
 ## Install
 
-A local-first CLI. It makes no network calls by default; the only command that reaches the
-network is the explicitly operator-invoked `capture provider-usage`. There is no telemetry.
+A local-first CLI. **No telemetry and no upload to Compaction.** Network happens only when you
+explicitly call provider-usage (`capture provider-usage`) or route your own provider traffic through
+the local gateway (which forwards it to your provider). Nothing else reaches the network.
 
 ### npm / npx
 
 ```bash
-npm install -g @compaction/cli   # then: compaction init
+npm install -g @compaction/cli   # then: compaction
 npx @compaction/cli init         # no global install
 npx @compaction/cli --help       # no install at all
 ```
 
 The installed binary is `compaction`. After a global install, sanity-check with
-`compaction --version` (→ `0.3.0`) and `compaction --help`.
+`compaction --version` (→ `0.3.1`) and `compaction --help`. Run `compaction` (no args) to open
+onboarding, including **Gateway setup**.
 
 ### curl one-liner
 
@@ -102,42 +135,29 @@ curl -fsSL https://cli.compaction.dev/install | sh -s -- --dry-run
 
 ## Quick start
 
-Run on **your own** captured/imported workflow — not a demo. The recommended free local loop is
-**capture → analyze → (local report) → redact / share**:
+Two local loops, both on **your own** workflow — not a demo.
+
+**Route your traffic through the local Gateway** (byte-safe; content-free receipts):
 
 ```bash
-compaction init                  # one-time local scaffold (writes nothing until you capture)
-# 1. Capture a real workflow (Claude Code shown; --discover lists local sessions):
-compaction capture claude-code --discover
-compaction capture claude-code --session <session.jsonl> --out ./my-trace
-# 2. Measure tokens + estimated spend, and see where it came from:
-compaction analyze ./my-trace/captured-trace.json
-compaction spend ./my-trace/captured-trace.json
-# 3. Share a redacted, content-free bundle (local file only, never uploaded):
-compaction feedback --redact --yes
+compaction gateway start                  # start the local gateway (RECORD mode)
+compaction gateway run -- npm run dev      # or point your OpenAI client's baseURL at the listen address + /v1
+compaction gateway status                  # see requests observed + the content-free receipts rollup
 ```
 
-Deterministic basic compaction (`compaction compact <trace> --out <dir>`) also runs locally in
-the free CLI. Advanced verification, recommendation, and apply guidance are the opt-in
-Compaction API — not steps of the free local CLI.
-
-## Gateway (local, byte-safe)
-
-The Compaction **Gateway** is a local, OpenAI-compatible reverse proxy. Point your OpenAI client at it
-(or launch your workflow through it) and it forwards traffic to the provider and records **content-free**
-token/cache receipts — no prompt/response content, and your provider key stays on the client. Set it up
-from onboarding (`compaction` → **Gateway setup**), or directly:
+**Capture + measure an agent trace** (local files only):
 
 ```bash
-compaction gateway start                     # start the local gateway (RECORD mode; byte-safe, no mutation)
-compaction gateway run -- npm run dev         # run a command through the gateway (no baseURL copy-paste)
-compaction gateway status                     # requests observed + a content-free receipts rollup
+compaction init                           # one-time local scaffold (writes nothing until you capture)
+compaction capture claude-code --discover # list local Claude Code sessions
+compaction capture claude-code --session <session.jsonl> --out ./my-trace
+compaction analyze ./my-trace/captured-trace.json   # tokens + estimated spend, honestly labeled
+compaction feedback --redact --yes        # redacted, content-free bundle (local file only, never uploaded)
 ```
 
-Record mode never changes your request or response. An **experimental**, explicit-opt-in deterministic
-`apply` mode (`--mode apply --policy deterministic-dedupe`) can remove exact-duplicate large blocks from
-known-safe requests, retaining the original locally (`compaction gateway recover <id>`). Nothing is called
-a saving — the gateway reports provider-reported token/cache counts (or "unavailable"), never a cost figure.
+Deterministic basic compaction (`compaction compact <trace> --out <dir>`) also runs locally.
+Advanced verification, recommendation, and apply guidance are the opt-in Compaction API — not steps
+of the free local CLI.
 
 ## Supported local workflows
 
@@ -153,14 +173,29 @@ a saving — the gateway reports provider-reported token/cache counts (or "unava
   `codex exec --json` export) and normalizes it. **Level 1.** Codex token counts on this path are
   **locally estimated (chars/4)**, not provider-reported. `compaction import --list-sources` lists
   supported sources.
+- **OpenAI-compatible clients via the local Gateway** — any OpenAI-compatible client can route
+  through `compaction gateway` for content-free receipts (and, opt-in, explicit deterministic apply).
 
-There is **no** native/Level 3 SDK instrumentation, no production proxy, no model routing, and no
+There is **no** native/Level 3 SDK instrumentation, **no hosted/managed proxy or model routing**
+(the local Gateway is an OpenAI-compatible reverse proxy for compatible clients), and no
 consumer-app (ChatGPT/Claude desktop) support.
 
 ## Commands
 
 ```bash
+compaction                                       # onboarding (workflow chooser + Gateway setup)
 compaction init                                  # one-time local scaffold
+
+# Gateway (local, byte-safe):
+compaction gateway start                         # start the local gateway (RECORD mode)
+compaction gateway run -- <command>              # run a command through the gateway
+compaction gateway status                        # requests observed + content-free receipts rollup
+compaction gateway activate                      # print env exports (eval-able); prints only, no mutation
+compaction gateway configure                     # approval-gated: propose a project baseURL (diff, no write without --apply)
+compaction gateway recover <recovery_id>         # recover the original request retained by apply mode
+compaction gateway stop                          # stop a running local gateway
+
+# Trace / capture utilities:
 compaction capture claude-code --session <session.jsonl> [--include-subagents] --out <dir>
 compaction capture claude-code --discover [--projects-dir <path>]
 compaction capture openai-agents --out <dir> -- <command> [args...]
@@ -177,15 +212,20 @@ compaction aggregate                             # per-session / cross-session l
 compaction feedback --redact [--yes]             # redacted, local-only share bundle
 ```
 
-`compaction --help` lists the free local commands.
+`compaction --help` lists the free local commands; `compaction gateway --help` lists the gateway commands.
 
 ## Privacy and security
 
-- **No telemetry; no upload by default.** The free CLI is local-first and file-based.
-- **One network call only.** `capture provider-usage` is explicitly operator-invoked and read-only;
-  its credential comes from an **environment variable only** (never a flag value, never logged,
-  never written into artifacts), and it captures **aggregate** usage/cost figures only — no
-  prompt/completion content. Its absence is a clean refusal.
+- **No telemetry; no upload to Compaction.** The free CLI is local-first and file-based.
+- **Network only on explicit action.** Network happens only when you explicitly call
+  `capture provider-usage` (read-only; credential via an **environment variable only**, never a flag
+  value, never logged, never written into artifacts; **aggregate** usage/cost figures only — no
+  prompt/completion content) **or** route your own provider traffic through the local gateway (which
+  forwards it to your provider; your provider key stays on the client and is never read or stored).
+- **Content-free gateway receipts.** Gateway receipts record token/cache counts and labels only —
+  never prompt/response content; they are local-only (gitignored). Apply mode retains the original
+  request **locally** (restrictive permissions) so it is recoverable; that original is referenced
+  from receipts by id only.
 - **Captured traces can contain local content.** Capturing a session may include local file
   content — review a trace before sharing it.
 - **Redacted sharing.** `feedback --redact` produces a redacted, content-free bundle as a local
@@ -199,33 +239,42 @@ Every figure this tool produces carries one of these labels — and nothing stro
 | Label | Meaning |
 |---|---|
 | **local estimate** | chars/4 token heuristics and price-table cost approximations computed locally |
-| **provider-reported token delta** | token counts read from the provider's own API response/usage metadata (operator-entered or captured); input tokens are deterministic for a fixed context+prompt |
+| **provider-reported token delta** | token counts read from the provider's own API response/usage metadata (operator-entered, captured, or via the gateway); input tokens are deterministic for a fixed context+prompt |
 | **token-estimated cost** | a price-table estimate applied to provider-reported token counts (`price_table_estimate`) — an estimate, never a billed figure |
 | **operator-entered billing record** | billed costs the operator read from their own provider console; recorded, not provider-verified by this tool |
 | **billing-confirmed** | only with real provider billing/invoice evidence **AND** the accepted measurement criterion met on those billed runs (N ≥ 3 runs per arm AND the delta-of-means ±2·SE interval excludes zero) — the statistical criterion alone is a bar on operator-entered figures, not proof of billing, so it is never sufficient by itself — **no figure in this repository currently carries this label** |
 
-**What is NOT claimed:** no billing-confirmed savings claim; no invoice savings claim; no general savings claim (all results are workflow-scoped and caveated); no auto-apply (every application is an explicit operator gesture); no hosted service or control plane (the free CLI is local-first, file-based); no universal "no context is lost" claim; no semantic/meaning preservation claim (it stays `not_evaluated`); no native/production/Level 3 integration claim.
+**What is NOT claimed:** no billing-confirmed savings claim; no invoice savings claim; no
+output-token savings claim unless measured before/after **and** eval-confirmed; no general savings
+claim (all results are workflow-scoped and caveated); no auto-apply (every application is an explicit
+operator gesture); no hosted service or control plane, and **no hosted-live claim** (the free CLI +
+Gateway are local-first, file-based); no universal "no context is lost" claim; no semantic/meaning
+preservation claim (it stays `not_evaluated`); no native/production/Level 3 integration claim.
 
 ## Known limitations
 
-- **The free CLI captures, measures, and compacts deterministically; it does not perform
-  advanced verification.** Recommendation, advanced verification (incl. `compact --eval`), apply
-  guidance, advanced policies, and team reporting are the **opt-in Compaction API** — not the
-  free local CLI. The API is **not broadly hosted yet**.
+- **The free CLI runs the local Gateway, captures/measures traces, and compacts deterministically;
+  it does not perform advanced verification.** The LCM / learned optimization engine, hosted/team
+  control plane, verified savings, advanced proprietary evals, recommendation, advanced verification
+  (incl. `compact --eval`), apply guidance, and advanced policies are the **opt-in Compaction API** —
+  not the free local CLI. The API is **not broadly hosted yet**.
 - **Cost figures are estimates or operator-entered records, not billing-confirmed.** Locally
   computed cost figures are price-table estimates; provider-usage records carry operator-entered/
   captured console figures (not provider-verified by this tool). **No figure is billing-confirmed.**
 - **Token counts are local estimates unless provider-reported usage is captured.** The default is a
   chars/4 estimate, labeled as such. Unknown stays unknown — output tokens, provider, or cost the
   data does not carry are never inferred.
+- **Gateway apply is experimental, deterministic, and opt-in.** It removes only exact-duplicate large
+  blocks from known-safe request shapes, retains the original locally, and fails closed on anything
+  else; it makes no output-token or cost claim, and never claims meaning preservation or "no context
+  lost". Record mode is the byte-safe default.
 - **Integrations are Level 1/2, not native/production.** Claude Code and OpenAI Agents capture are
   Level 2 local command-wrappers; Codex/local-file import is Level 1. There is **no** native/Level 3
-  SDK instrumentation, no production proxy, no model routing, and no consumer-app support.
+  SDK instrumentation, **no hosted/managed proxy or model routing**, and no consumer-app support.
 - **Verification (opt-in API) is deterministic recoverability, not semantic preservation.** Where
   the opt-in API verifies a compacted context, it checks deterministic recoverability for a
   supported workflow; it does **not** evaluate meaning or task equivalence and does **not** re-run
-  your agent through a model. Semantic / meaning preservation remains **not evaluated**; true model
-  replay is future work.
+  your agent through a model. Semantic / meaning preservation remains **not evaluated**.
 - **No universal "no context is lost" guarantee.** Any apply-guidance verdict from the opt-in API
   is **fail-closed and scoped** to supported developer-agent workflows — never a universal
   guarantee, and never a semantic/meaning claim.

package/dist/cli/commands/upgrade-status.js

@@ -97,7 +97,7 @@ export async function runUpgrade(opts) {
  */
 export async function runStatus(opts = {}) {
     const env = opts.env ?? process.env;
-    const version = opts.version ?? "0.3.0";
+    const version = opts.version ?? "0.3.1";
     const target = resolveTarget({ env });
     const configured = target.apiKey !== undefined && !isLocalDefaultUrl(target.url);
     console.log(chalk.cyan("compaction status"));
@@ -146,7 +146,7 @@ export function registerStatusCommand(program) {
         .command("status")
         .description("Show local core status and whether a hosted endpoint is configured + reachable.")
         .action(async () => {
-        await runStatus({ version: program.version() ?? "0.3.0" });
+        await runStatus({ version: program.version() ?? "0.3.1" });
     });
 }
 //# sourceMappingURL=upgrade-status.js.map

package/dist/cli/index.js

@@ -39,7 +39,7 @@ const program = new Command();
 program
     .name("compaction")
     .description("CLI-first trace compaction tools for AI agent workflows.")
-    .version("0.3.0");
+    .version("0.3.1");
 // Brand mark above the TOP-LEVEL help only (compaction --help / bare `compaction`).
 // Derived rendering of apps/web/src/assets/compaction-mark.svg — see
 // docs/brand/terminal-logo.md. Colored only on a TTY with NO_COLOR unset; plain

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compaction/cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "publishConfig": {
     "access": "public"
   },