AGENTS.md

1# proxy — the byte-safe standalone `caveman` proxy (commercial, binary-distributed)
2 
3A base-URL-swap reverse proxy: match → authenticate → inspect → byte-safe transform → upstream
4→ meter. Single-operator, BYOK, **zero cloud dependencies**. It shares its provider adapters with
5the managed gateway (the managed gateway imports them from here). `caveman start` launches the
6`caveman-proxy` binary.
7 
8## Layout
9- `providers/` — the shared, public byte-safe adapter set: `Adapter` interface + `Base` embed + `UsageScanner`/`ParseUsageBytes` (`adapter.go`), and `anthropic`/`openai`/`gemini`/`azureopenai`/`bedrock`/`vertex`/`openaicompat`. `ResolveUpstreamURL` takes `providers.RouteContext` (no control-plane coupling). Anthropic + OpenAI carry both prefixed and bare routes (`/v1/messages`, `/v1/chat/completions`). `vertex` is a bearer pass-through proxy for Gemini + Claude on Vertex AI (no signing, no custom usage parser).
10- `internal/gateway/` — the request lifecycle (`server.go` + `proxy.go`) behind three injected seams: `Authenticator`, `CredentialResolver`, `TelemetrySink`. Ports the managed loop with the fail-open fix.
11- `internal/config/` — `caveman.yaml` loader + BYOK env-key resolution; unknown mode fails closed to `record`.
12- `internal/store/` — `~/.caveman/caveman.db` SQLite spend store (`modernc.org/sqlite`, cgo-free); implements `TelemetrySink`.
13- `internal/standalone/` — wiring: static `Auth`, BYOK `Creds`, adapter set, and the always-on SSRF-guarded client.
14- `cmd/caveman-proxy/` — binary: `serve` (default), `stats`, and content-blind
15  `agent-evidence --session --build --plan`. Evidence query returns only exact
16  provider usage, request hashes, declared context/plan identity, ordered
17  provider-prefix component hashes, actual transform IDs/counts, and CCR handle;
18  basis is always `inferred`, verified dollars always zero.
19 
20## Conventions
21- Build/test: `make product-build PRODUCT=proxy` / `make product-test PRODUCT=proxy`.
22- Tests inject a plain `*http.Client` to reach loopback stubs; the binary uses the SSRF-guarded client.
23- New provider/optimizer work goes in `providers/` (shared) — change it once, both proxies get it.
24 
25## Gotchas (honesty invariants — correctness, not style)
26- **byte-safe**: `record` mode never transforms; on transform error the ORIGINAL bytes are forwarded (HTTP 200, fail-open) — never a 400.
27- **request-wide opt-out**: `x-cave-transforms: caveman.pass-through.v1` suppresses every request transform path — compress, pixel, and provider-native — not only compiled plan routes. Tests cover all three modes.
28- **no-fake-savings**: standalone records `Basis: "inferred"` on every row; it never writes `verified` and never re-projects to a monthly figure.
29- **practice join**: local learn sinks carry additive `practice_id`; one
30  fail-closed mapping table owns sink→practice and unknown sinks keep `""`.
31  The historical `subagent_overuse` sink is count-only and deliberately has no
32  practice id: spawn count cannot reactivate the retired
33  `context-exploration-offload` opportunity or prove any spawn unnecessary.
34- **local trial heuristics are not actuation evidence**: a model name never emits
35  the retired `model-right-sizing` id, and provider plus positive cost never
36  emits a cache move because neither proves stable-prefix eligibility. Legacy
37  rows for those identities are hidden at read time. Compression replay reports
38  one trial's local engine `estimated_engine_o200k` before/after shape with zero
39  dollars and low confidence; it is not provider-counted, a rate, an invoice,
40  causal/verified savings, or task-outcome evidence.
41- **Anthropic automatic caching is experimental observation only**:
42  `anthropic-automatic-prompt-cache` is a typed, default-off manual policy
43  experiment and may add only Anthropic's top-level 5-minute marker on direct
44  Messages API requests. Managed traffic additionally requires server-attested
45  official Anthropic origin; custom or provenance-unknown origins lose the flag
46  before the adapter. It is mutually
47  exclusive with the explicit `anthropic-cache-breakpoints` transform and any
48  caller `cache_control`; Bedrock and count-tokens requests stay byte-identical.
49  An applied marker records only its optimizer id plus actual provider usage and
50  cost. It has no practice, recipe, generic mode/candidate activation, ledger
51  tuple, inferred savings, or verified-savings path (cache-only and forged IDs
52  are excluded from the counted-baseline method too); evaluate it by manual
53  paired observation because shared provider cache state can contaminate an A/B.
54- **SSRF always on**: `standalone.StandaloneHTTPClient` guards every upstream dial (not gated on `CAVE_ENV`) using `ssrf.SelfHostedConfig` — NOT ManagedConfig, which ignores the allowlist and would make the escape hatch a silent no-op. `CAVE_SSRF_ALLOWLIST` opts loopback/private hosts back in (local model servers like Ollama; `localhost` as an entry covers 127.0.0.0/8 + ::1); metadata/link-local stay blocked in every mode.
55- **Auth scheme is preserved**: a key from an inbound `Authorization: Bearer` keeps `Scheme:"bearer"` on the `providers.Credential`; Anthropic and Gemini forward bearer credentials as bearer credentials (Claude/Gemini OAuth breaks if remapped to an API-key header). BYOK env keys and inbound `x-api-key` keep provider API-key mapping.
56- **fail-closed**: unknown route → 404; unknown mode → `record`.
57- **subscription AND oauth compression is NOT account-gated**: non-PAYG sessions from Claude Code, Codex ChatGPT, Gemini CLI, and other routed clients take live-zone compression with no Caveman account, entitlement, or seat. `CAVEMAN_WRAP_ENTITLED` and every `WrapEntitled` field are **deleted**, not merely ignored — do not reintroduce them. Exactly four conditions remain, all technical and all fail-closed (`liveZoneCompressionAllowed`): the operator `subscription_compress` switch (empty/`live_zone` allow, `off` and any unknown value close it), the adapter must implement schema-aware `PrefixStabilizer` zones, recovery must run through the agent's own MCP `caveman_retrieve`, and a durable prefix cache must be wired. The dedicated Codex `/chatgpt/responses` route uses the OpenAI Responses stabilizer while preserving OAuth and `ChatGPT-Account-ID` headers; transformed 4xx responses retry once with exact original bytes. Rows are **tokens-only** — `compression_tokens_before/after` + `estimated_engine_o200k`, never compression dollars. LOCAL wrap only; managed gateway non-PAYG behavior is unchanged.
58- **cache safety is byte-stable replacement**: a compressed live-zone turn becomes prefix on next request, so same logical message must re-serialize to deterministically identical bytes every time. Replacement is pure function of segment content (deterministic compressor + content-hash CCR marker), held in durable replacement cache and re-substituted below cache floor; new compression stays live-zone-only. Cache miss/write failure forwards original bytes. Cross-turn stability covers **anthropic, openai, azureopenai/openaicompat, and gemini** through `ExtractStabilizable`; `bedrock` and `vertex` expose no compressible blocks and stay pass-through. Anthropic uses declared `cache_control`; OpenAI/Gemini use latest-user/latest-tool zones against implicit provider caches. Replacement cache is SQLite spend store and must retain `journal_mode(WAL)` + `busy_timeout`.
59- **pixel mode**: S4 lossy text→PNG (`pxpipe` port). Default allowlist is `claude-fable-5,gpt-5.6` via `CAVE_PIXEL_MODELS`; original request is always in CCR before transformed bytes are sent; savings stay inferred-only; any error is byte-identical pass-through.
60- **boundary**: this is public code — it must never import the managed-cloud lane. `make check-boundaries` enforces it.
61 
62See ../../CLAUDE.md (root)
63