Addresses review feedback on PR #194: prior code validated X-Headroom-Stack
slugs differently at each ingress — the Prometheus counter capped length but
the env-var path and beacon didn't. Under a misconfigured or malicious client
sending arbitrary X-Headroom-Stack values, requests_by_stack could grow
unbounded in memory, in the Prometheus scrape, and in the JSONB telemetry
payload.
- New normalize_stack(raw) in headroom/telemetry/context.py: strips, lowercases,
enforces ^[a-z][a-z0-9_]{0,63}$. Single chokepoint.
- detect_stack now routes HEADROOM_STACK and stats dominant-slug through it;
invalid env values fall through to the agent-type path or default "proxy".
- PrometheusMetrics.record_stack routes through normalize_stack and rejects
new slugs once the dict hits MAX_DISTINCT_STACKS (32); existing slugs still
increment so valid callers aren't starved.
- 10 new unit tests covering normalize_stack charset/length/empty cases, the
cardinality cap, and invalid-env fallback paths.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds two orthogonal identity fields to the anonymous telemetry beacon so we
can segment usage by integration surface and deployment shape:
- headroom_stack: how Headroom is invoked (proxy, wrap_claude, wrap_codex,
adapter_ts_openai, adapter_ts_anthropic, etc.). Resolved from HEADROOM_STACK
env, HEADROOM_AGENT_TYPE fallback, or aggregated request-header counts.
- install_mode: how the proxy is deployed (wrapped / persistent / on_demand).
Detected from HEADROOM_AGENT_TYPE plus DeploymentManifest lookup.
TS SDK adapters now tag every request with X-Headroom-Stack; a FastAPI
middleware buckets the counts and surfaces them via /stats so the beacon can
report requests_by_stack for mixed-integration sessions.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Do not strip the raw git-log record before splitting on the field
separator, because commits with empty bodies lose their delimiter and get
dropped entirely. Add a deterministic unit test for empty-body parsing.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Determine the release bump from all unreleased commits since the previous
release tag and apply the highest required semantic version increment.
This keeps feat commits at a minor bump unless a breaking change requires
major, even when later patch-level commits are present.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Three scenarios lock the issue-175 additive guarantee:
1. Legacy-only user (HEADROOM_SAVINGS_PATH set, canonical unset) still
gets the byte-for-byte legacy value.
2. Canonical-only user (HEADROOM_WORKSPACE_DIR set) sees every workspace
bucket resource relocate with the correct filenames.
3. Both set: legacy per-resource env var wins over canonical root env
for its own resource; other unreserved helpers still follow the new
canonical root (orthogonality).
Plus a regression guard asserting all three legacy vars (savings, toin,
subscription) simultaneously beat the canonical workspace override.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Every public helper in headroom/paths.py now has both a default-derived
test and a HEADROOM_WORKSPACE_DIR/CONFIG_DIR precedence test. Adds the
derived_workspace_helpers parametrized matrix plus explicit cases for
proxy_log_path, rtk_path, beacon_lock_path, plugin_*_dir, and both
ensure_* functions.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replace the inline release version math with a tested helper that normalizes legacy four-part tags and computes a single semantic version for packages and GitHub releases.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Tests expected the old behavior where _crush_number_array prepended a
summary string into the array. The fix in 14415db moved stats to the
strategy string instead, keeping arrays homogeneously numeric. Update
3 tests to check strategy string instead of array[0].
Edge proxies such as Cloudflare Workers inject accept-encoding values
(e.g. gzip, br, zstd) into every outbound request. When Headroom
forwarded these headers unchanged to OpenAI or Anthropic, the upstream
could respond with Brotli-encoded content. Because httpx does not
decompress brotli without the optional brotli package, the raw
compressed bytes reached the JSON parser, causing a UnicodeDecodeError
and a 502 response to the client.
Fix: pop accept-encoding before forwarding so httpx negotiates its own
encoding independently. Applied consistently across all four request
header construction sites:
- openai.py: chat completions handler
- openai.py: Responses API handler
- openai.py: generic passthrough handler
- anthropic.py: main messages handler (CCR continuation already had the strip)
Closes#135
- Number array compression no longer mixes types (string summary was
prepended to numeric array, violating schema-preserving guarantee).
Statistics now go in the strategy string instead.
- Replace instance-level _current_field_semantics with threading.local()
to prevent cross-thread contamination in concurrent crushes.
- Add lock to module-level _within_compressor lazy init (was unprotected).
- Add _MAX_PROCESS_DEPTH=50 guard to _process_value to prevent
RecursionError on deeply nested JSON.
- Remove dead expression (unused stats.max_val - stats.min_val).
- Fix all UP038 isinstance(x, (A, B)) -> isinstance(x, A | B) across file.
- Add 11 regression tests covering all fixes.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- test_memory_sync.py: remove unused imports (asyncio, MagicMock,
AgentMemory, AgentMemoryAdapter, SyncResult), fix import sorting
- test_ws_memory_relay.py: remove unused pytest import and unused
output_index variable, fix import sorting
- test_wrap_copilot.py: provide dummy API keys in test env — the
BYOK validation added in 7a7b8b6 requires ANTHROPIC_API_KEY or
OPENAI_API_KEY to be set
- test_package_init_lazy.py: stop hardcoding version string that
breaks on every bump; assert it's a non-empty string instead
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
_component_tokenizations only split on `-` and `.`, so directory names
like `my_project` could never be reconstructed from the dash-encoded
slug. Add `_` as a separator so the greedy decoder matches snake_case
directory names correctly.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
KompressConfig now accepts model_id, chunk_words, and score_threshold so
domain-specific models (e.g. kompress-finance with 50-word chunks) can be
used without forking the compressor. Model cache is keyed by model_id,
allowing multiple models to coexist. All defaults match prior behavior.
Also fix mypy errors in memory/sync.py from recent merge.
Memory saved in one agent (Codex, Claude Code, Aider) is now accessible
from any other agent through a shared headroom DB. Three integration layers:
MCP Server (headroom.memory.mcp_server):
- stdio MCP server that Codex/Claude discover natively via config.toml
- memory_search with supersession filtering (only active memories returned)
- memory_save accepts atomic facts array — each fact stored/indexed individually
- Auto-supersession: new facts that match existing ones (≥0.70 similarity)
retire the old entry via the supersedes/superseded_by lineage chain
- ONNX embedder pre-loaded at startup (no cold-start on first query)
- HuggingFace offline mode eliminates network latency on startup
Sync Engine (headroom.memory.sync):
- Bidirectional sync: DB ↔ agent-native memory files
- Pluggable adapters: ClaudeCodeAdapter (frontmatter .md files + MEMORY.md index),
CodexAdapter (AGENTS.md sections)
- Fast no-op: fingerprint comparison skips sync when nothing changed (<5ms)
- Content-hash dedup prevents duplicate memories across agents
- Lineage metadata: source_agent, source_file, content_hash, synced_at
- Anti-echo: memories imported from an agent are not re-exported to that agent
- CLI entry point: python -m headroom.memory.sync --agent claude|codex
Wrap CLI integration:
- `wrap codex --memory`: registers MCP server + AGENTS.md guidance + syncs
Claude memories into DB for MCP search
- `wrap claude --memory`: bidirectional sync at startup (DB ↔ Claude files)
- MCP config re-injected after provider config to survive file rewrite
- Cross-platform: Windows path handling in TOML configs and path sanitization
Proxy improvements:
- Responses API: tool format conversion (Chat Completions → Responses API)
- Responses API: memory tool calls handled with proper continuation
- WebSocket: buffer-then-decide relay suppresses memory tool events from
Codex, executes them transparently, relays only the final answer
- memory_handler: supports Responses API function_call format (call_id,
top-level arguments, output[] extraction)
- HNSW vector index now persists to disk via auto_save + save_path
Tests: 37 new tests covering WS relay event suppression, sync import/export,
bidirectional sync, idempotency, fast no-op, lineage, cross-agent interop
_ensure_proxy() now queries the running proxy's /health config to
detect feature mismatches. When --memory, --learn, or --code-graph
is requested but not enabled on the running proxy, it merges flags
and restarts the proxy with the upgraded configuration.
- Expose memory, learn, code_graph, pid in /health config response
- Add _query_proxy_config() and _kill_proxy_by_pid() helpers
- Refactor _detect_running_proxy_backend() to use _query_proxy_config()
Implements compress_batch() for issue #151. Compresses N texts with
batched forward passes on GPU and falls back to sequential compress()
on CPU where batching doesn't help.
Measured performance (RTX 3080 Ti, 1000-word / ~6K-char inputs):
GPU (PyTorch + CUDA):
N=1: 2.68x speedup (multi-chunk text batches within single call)
N=5: 2.75x speedup
N=12: 2.49x speedup
CPU (ONNX): fallback to sequential — parity with compress() in loop
ONNX Runtime's CPU execution provider does not parallelize across the
batch dimension for this model architecture; verified across default,
physical-cores-only, and single-thread configurations. The fallback
keeps the API useful while that limitation exists.
Features:
- Per-item target_ratio: scalar applies to all, list allows per-text
- Input order preserved in output
- Passthrough parity with compress() on short texts / errors
- Configurable batch_size (default 32)
Tests: 8 new (TestKompressCompressorBatch), 21 total pass.
Closes#151
Passively capture x-codex-* response headers from proxied Codex API
calls and surface them in /stats and the dashboard.
Unlike Anthropic subscription window tracking (which polls a dedicated
OAuth endpoint), Codex embeds rate-limit data directly in every API
response header — no polling, no new credentials needed.
Changes:
- headroom/subscription/codex_rate_limits.py: new module with
CodexRateLimitWindow, CodexCreditsSnapshot, CodexRateLimitSnapshot
data models and a thread-safe CodexRateLimitState singleton;
parse_codex_rate_limits() parses x-codex-primary/secondary-used-percent,
window-minutes, reset-at, credits, limit-name, and promo-message headers
- headroom/subscription/__init__.py: re-export new public symbols
- headroom/proxy/handlers/openai.py: call
get_codex_rate_limit_state().update_from_headers() after each
proxied /v1/chat/completions and /v1/responses response
- headroom/proxy/server.py: add codex_rate_limits key to /stats
via _get_codex_rate_limit_stats() helper
- headroom/dashboard/templates/dashboard.html: new OpenAI Codex
Rate-Limit Window panel (primary + secondary progress bars, credits
balance, limit name, reset countdown); hidden when no data
- tests/test_codex_rate_limits.py: 25 unit tests covering parsing,
window labels, reset time, credits, state updates
- docs/screenshots/subscription_window_active.png: updated screenshot
showing both Anthropic and Codex panels in the real dashboard
Header schema (from codex-rs/codex-api/src/rate_limits.rs):
x-codex-primary-used-percent / x-codex-primary-window-minutes /
x-codex-primary-reset-at (and secondary- variants)
x-codex-credits-has-credits / -unlimited / -balance
x-codex-limit-name / x-codex-promo-message
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Make Unix-only file locking imports type-safe on Windows, tighten beacon lock cleanup, and fix the remaining exposed typing issues so the repository's mypy check passes cleanly on Windows again.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add focused regression coverage for install, runtime, provider, state, health, supervisor, and persistent wrap flows so the new persistent deployment surfaces are exercised more thoroughly in CI.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Align Docker-native wrapper help and runtime behavior with the Python install contract, including persistent deployment metadata, baked install-image defaults, and explicit unsupported wrap targets.
Harden the Python persistent-install path with profile validation, safer provider-scope handling, Windows environment restoration, runtime parity improvements, and rollback-safe apply/update behavior.
Update README, Docker install docs, CI, and focused regressions to cover the Windows BOM failure, wrapper parity, compose coverage, and Docker-native wrap behavior.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Tighten Docker-native bash and PowerShell wrapper validation for wrap and proxy flows, pin the bash wrapper to the install-time interpreter, clean up failed persistent container starts, and extend docs, CI, e2e, and native installer coverage for persistent Docker installs.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add headroom wrap copilot with backend-aware provider routing, health metadata for running proxy detection, focused Copilot tests, and docs updates across the main integration surfaces.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add host-managed OpenClaw wrap and unwrap flows to the Docker-native wrappers so the installed headroom script can configure the OpenClaw plugin on the host while keeping Headroom itself in Docker. Reuse hidden prepare-only hooks for OpenClaw config payloads, preserve existing plugin metadata on unwrap, and update the Docker-native and integration docs to reflect the supported flow.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add system-native install scripts and host wrappers for running Headroom from Docker while keeping wrapped tools on the host. Document the Docker-native path, add a complete CLI reference with help output and parity details, and add support for root help/version aliases and proxy env-based binding behavior.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Keep the default Headroom proxy startup path lightweight so OpenClaw can launch it reliably on Windows. This defers heavyweight provider, cache, transform, pricing, and detector imports until they are actually needed, adds a lightweight version module, and keeps the OpenClaw launcher on the configured Python path.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add a default devcontainer and a compose-backed memory-stack profile, validate them in CI, and document the contributor workflow.
Also lock the memory-stack dependencies, pin related container tooling, and sync the latest healthcheck shutdown fix for stubbed memory handlers.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add /livez and /readyz, keep /health backward-compatible, and wire readiness into Docker artifacts and docs.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
When --model codex-cli is used but codex is not in PATH,
subprocess.run raises FileNotFoundError. Catch it and raise
a clear RuntimeError with guidance.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
