Commit Graph
15 Commits
Author SHA1 Message Date
JD DavisandCopilot 177fab3782 docs: add guidance for scripted PR/issue comment posting (#4760)
## Description

Documents safe patterns for agent/script-authored PR and issue comments,
so replies like `System.Collections.Hashtable` (seen on #4726) don't
ship unnoticed. Adds a "Posting PR/issue comments from scripts or
agents" section to `CONTRIBUTING.md` with shell-agnostic rules:
file-based bodies and a read-back requirement.

Refs #4757. Only the documentation checkbox of the issue is covered
here, so this does not close it; the issue's decision record is below.

## Type of Change

- [x] Documentation update

## Changes Made

- `CONTRIBUTING.md`: new shell-neutral section: single-string file-based
bodies, no collections in `-f`/`-F`, read-back verification,
delete-and-repost for bad comments.

**Decision on the optional follow-ups (acceptance criterion 2):**
deferred. A governance-workflow regex check and a `gh-reply` helper
script would add new CI/script surface to maintain for a one-off failure
mode. The documented read-back step is the main guardrail. Happy to
follow up if maintainers want either.

## Testing

- [ ] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
Docs-only change; no code touched. Reviewed the rendered Markdown diff.
```

## Real Behavior Proof

- Environment: any OS/shell with `gh`
- Steps: reviewed `git diff origin/main -- CONTRIBUTING.md`; confirmed
the section renders before "Development setup" and contains no
shell-specific syntax.
- Not tested: not executed against a live PR (docs only).

## Runtime Rollout Safety

- Rollout-managed feature(s): N/A (docs only)
- Minimum rollout channel: N/A
- Stable/default behavior changed: No
- Kill switch / disable path: N/A
- Unsafe override required: No
- Qualification impact: None
- Rollback path: revert the commit

## Review Readiness

- [x] I have performed a self-review
- [ ] This PR is ready for human review

## Checklist

- [x] I have made corresponding changes to the documentation
- [x] I did **not** edit `CHANGELOG.md`

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-16 19:43:55 -06:00
Mansurshakh JaparovandJerrettDavis cde584d7fe fix(langchain): check optional integration availability (#4042)
## Description

Closes #4039.

The optional integration uses the existing LANGCHAIN_AVAILABLE guard;
installed LangChain binding precedence remains intact. Current head:
`ac9e49af43501d2b3bbb6d0a21cb07fe94030bc9`, normally updated onto main
`f1bc`.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [x] Documentation update

## Changes Made

- Install langchain-core in the existing CI lint job, with the
optional-extra version range, so the normal mypy invocation covers the
integration. Remove the pytest-launched mypy subprocess.
- Keep our nested unwrap-precedence regression (sync and async) and two
real loopback HTTP cases: bind_tools and nested caller-overrides. Remove
the vendor tool-response/usage-parsing matrix, as requested by the
maintainer.
- Replace the private LiteLLM cache invalidator with the public
register_model API; preserve the independent cost_per_token billing
oracle and fixture/catalog restoration.
- Correct the compatibility doc numbering and document the normal typing
path in CONTRIBUTING.
- Preserve the published startup SDK/provider module and parent-package
restoration fixes.

## Testing

- [ ] Unit tests pass (pytest) — no whole-project suite pass claimed.
- [ ] Linting passes (ruff check .) — changed-file Ruff passed; no new
whole-repository Ruff claim.
- [x] Type checking passes (mypy headroom)
- [x] Manual testing performed

### Test Output

Current published head, Python 3.13.14, installed langchain-core 1.6.10,
langchain-openai 1.7.1, LiteLLM 1.105.0 and a fresh native build:

`python -m pytest tests/test_integrations/langchain/test_binding_http.py
tests/test_integrations/langchain/test_langchain_1x_compat.py
tests/test_startup_log_noise.py tests/test_xai_cache_economics.py -q`

```text
28 passed, 1 skipped in 14.73s
```

The skip is optional trafilatura unavailable. A SQLite ResourceWarning
was emitted at interpreter teardown; it is not suppressed or claimed
fixed.

Normal mypy command in an isolated lint environment with mypy 1.20.2 and
installed langchain-core: success, no issues in 569 source files. This
local lint environment uses Python 3.14; the runtime consumer suite uses
Python 3.13.14. Existing untyped-body/unused-ignore notes remain.

Ordinary push gates: Rust workspace tests, fresh native extension build,
181 critical Python tests, and commitlint passed. Two prior normal
publication attempts failed seven native parity cases; neither was
bypassed or repinned. Publication passed with a separate clean Cargo
target. This establishes the successful isolated build, not a proven
root cause for the earlier build discrepancy.

## Real Behavior Proof

- Environment: installed SDKs, actual localhost HTTP server, no
provider-network or billing requests.
- Exact command / steps: an independent runtime driver invoked
HeadroomChatModel with bind_tools and nested RunnableBinding objects
against the real local ChatOpenAI transport; the retained HTTP
regressions exercised both cases again on the published head.
- Observed result: two actual requests; bind_tools sent lookup; nested
caller temperature 0.3 won, and inner top_p 0.8 survived. The sync/async
unwrap regression retains the real RunnableBinding precedence check. The
pricing oracle and startup teardown regressions passed.
- Not tested: live provider invoices, paid requests, remote production
deployment, or current-head hosted CI completion. Historical CI/approval
is not attributed to this new head.

## Runtime Rollout Safety

- Rollout-managed feature(s): none; optional integration guard and test
isolation.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: no binding precedence, runtime
defaults, authentication or serialization changes; CI lint now
explicitly installs the existing optional typing dependency.
- Kill switch / disable path: existing optional extra remains optional;
no new runtime switch.
- Unsafe override required: no.
- Qualification impact: optional-extra typing and real binding consumers
are exercised; normal local native/critical gates passed.
- Rollback path: revert the bounded guard/CI/test edits; no
persistent-state migration.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have made corresponding changes to the documentation
- [x] I did not edit CHANGELOG.md — release-please owns it

## Additional Notes

AI-assisted without subagents. No force push, skipped hook, new approval
or merge. The reduced HTTP scope follows the maintainer's explicit
request:
https://github.com/headroomlabs-ai/headroom/pull/4042#issuecomment-6157529674
.


### Maintainer current-main requalification

Exact head `ff329f3e487940f85d56ba0b35bd9994afadb506`, upstream main
`c01cf07d943d816cfd9d97e6838ed4e38f1ff9a4`.

Requalified against upstream main
c01cf07d94. The only merge conflict
combined main's Python 3.11 minimum with the contributor's
optional-integration typing guidance; both retained. No contributor
availability/binding policy rewritten. Current author/chopratejas/Devin
discussion reviewed, including the intentional removal of vendor-owned
response-parsing coverage. Nested binding precedence, real loopback HTTP
controls, public LiteLLM register_model isolation, independent billing
oracle and parent-module restoration remain covered.

Fresh focused tests: 29 passed with installed langchain-core 1.4.2 and
langchain-openai 1.2.2. Full mypy against the Linux CI target checked
580 source files: PR reports 22 errors; an actual detached current-main
run with the same environment reports those same 22 plus a
RunnableBinding truthy-function error that this PR removes. The 22
shared errors are in unrelated unchanged prefix-tracker, optional
memory/MCP and CrewAI modules; they are not contributor blockers and
this is not a clean full-mypy claim. Five changed Python files pass Ruff
lint/format and main-relative whitespace checks. Current-main DLL
supports local startup, without a branch-specific native-build or live
model-provider claim. No new source blocker; approval awaits exact-head
hosted qualification. Nothing merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-06 09:24:06 -06:00
Mansurshakh JaparovandJerrettDavis 50bf775e8c fix(proxy): bypass compression for large admitted histories (#4142)
## Description

Closes #4139.

A history that is too large to compress should still reach the provider.
This keeps the 100 MiB hard admission limit and bypasses request-side
transforms above 16 MiB decoded size. The hard limit still applies
before forwarding.

Current head: `62ffe3defef1684f70d96f1640818d99445a43bb`, merging
current main `a2d4fe72` into `1902d8ef`. The
42-test/native/manual/pre-push results below qualify `1902d8ef`, not
this new merge. New-head shard 4 has a cached-prefix fixture failure
under investigation; coverage uploads are still incomplete.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [x] Performance improvement
- [x] Documentation update

## Changes Made

- Keep the startup override and both wire/decompressed hard bounds.
Large admitted histories skip normalization, image processing, memory
injection, tokenization and compression on Messages, Chat/Responses,
Gemini and Bedrock HTTP routes.
- Keep provider routing and backend translation, including Copilot Chat,
Codex `store:false` and Vertex route-forced streaming. Native forwarding
retains decoded bytes unless the provider's wire contract requires a
rewrite; translation retains the full message text.
- Report actual provider usage, with zero compression savings or
attempted tokens for the bypass. Keep `/v1/compress` and WebSocket
contracts unchanged.
- Add real-provider coverage for large Gemini JSON/SSE requests with
query-key auth, and OpenAI JSON/SSE through the installed LiteLLM
adapter. No admission-policy or CI changes in this follow-up.

## Testing

- [x] Unit tests pass (focused suite and normal critical pre-push suite)
- [x] Linting passes (normal hooks)
- [x] New tests added for admission, recovery and passthrough accounting
- [x] Manual testing performed against the real native build

### Test Output

```sh
python -m pytest -q tests/test_proxy_compression_admission.py tests/test_proxy/test_gemini_plugin_routed_streaming.py --cov=headroom --cov-branch
# 42 passed, 41 warnings
```

Normal pre-push `make ci-precheck` passed: 1668 Rust tests (3 ignored),
181 Python tests, lint/type checks and commitlint. No hook bypass. The
initial deep-module coverage command hit a Pydantic import-isolation
error; using the repo's `--cov=headroom` convention passed both complete
modules without disabling plugins or tests.

The earlier `96c5fe7e` qualification covered the other native protocols,
configured/per-request backends, hard-ceiling recovery and complete
local shards 2/3. Those runs are historical, not a new whole-suite
claim. New-head hosted success is not claimed.

## Real Behavior Proof

- Environment: Linux x86_64, Python 3.13.14, freshly built real
`headroom._core`, public Headroom ASGI routes, a real localhost HTTP
provider and installed LiteLLM. Synthetic credentials, offline mode and
`DO_NOT_TRACK=1`; no live provider calls.
- Exact command / steps: Start
`create_app(ProxyConfig(backend="litellm-openai", ...))` with all
upstream URLs set to the localhost peer and
`litellm.api_base=peer+"/v1"`. Leave the production 16 MiB soft/100 MiB
hard limits unchanged. POST `"history " * (16777216 // 8 + 1024) + "LAST
TURN"` as a user message to Chat Completions, then as a Gemini content
part to generateContent/streamGenerateContent, with streaming off/on.
The peer rejects a changed history, requires Gemini query-key auth and
one `alt=sse`, and returns protocol-valid JSON/SSE with 101 input/1
output tokens. The maintained four small-ceiling cases are in
`tests/test_proxy_compression_admission.py` and run with the command
above.
- Observed result: All four >16 MiB requests returned 200 with the full
history intact. JSON/SSE and Gemini auth survived; streamGenerateContent
forced SSE even with incoming `alt=json`. Each request recorded exactly
101 provider input/1 output tokens, zero compression attempts/savings
and no failures; `/livez` stayed 200. Earlier recorded qualification
also covered all five native HTTP protocols, real translating backends
and 413 recovery.
- Not tested: Live cloud accounts, the reporter's deployed 4 GB VPS,
screenshot/image quality or a zero-JSON-parse path. One envelope/model
JSON parse remains; no proxy-only RSS guarantee is claimed.

## Runtime Rollout Safety

- Rollout-managed feature(s): None; this is the admission/compatibility
fix.
- Minimum rollout channel: Stable/default.
- Stable/default behavior changed: Keep the 100 MiB hard ceiling; bypass
request-side transforms above 16 MiB decoded size on the named HTTP
routes.
- Kill switch / disable path: Set
`HEADROOM_REQUEST_BODY_MAX_BYTES=16777216` (or lower) and restart,
accepting local 413s instead of the large-body path.
- Unsafe override required: No.
- Qualification impact: Local native protocols, backend translation,
hard bounds and recovery exercised; live-provider/VPS qualification
remains external.
- Rollback path: Revert the admission revision and restart; no storage
migration.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] I have made corresponding changes to the documentation
- [x] I did not edit `CHANGELOG.md`

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-04 22:37:21 -06:00
Tejas ChopraandClaude Fable 5.1 3c6f82b060 deps: require Python 3.11; clear Dependabot alerts in the 3.10 lock fork (#4517)
## Description

Vanta/Dependabot report 64 open alerts on this repo. 59 of them are
pillow, filelock and virtualenv versions that exist only in the Python
3.10 split of `uv.lock`: the patched releases (pillow 13, filelock 4.2)
require Python 3.11, so Dependabot could not open a fix PR. Python 3.10
reached end of life in October 2026 and CI already tests only 3.11, 3.12
and 3.14.

The second commit also fixes the two `security.yml` jobs that fail on
`main` today: pip-audit (litellm CVE-2026-114612) and the e2e npm audit
(three undici advisories published after #4453 for the copy bundled
inside npm).

## Type of Change

- [x] Breaking change: `pip install headroom-ai` now refuses Python 3.10
- [x] Bug fix: security patches

## Changes Made

- `requires-python = ">=3.11"`; drop the 3.10 classifier and the `tomli`
backport dependency
- pillow override and filelock floor lose their `python_version` markers
- mypy `python_version = "3.11"`; the three `tomli` import fallbacks in
`headroom/` become plain `import tomllib`
- ruff `target-version` stays `py310` with a note: moving it raises 213
pyupgrade findings (UP017/UP036/UP041/UP042), a separate mechanical PR
- `uv.lock` re-resolved: pillow 13.0.0, filelock 4.2.4, virtualenv
21.14.13 (single entry each, the 3.10 fork is gone)
- gitpython 3.1.62 → 3.2.1, strands-agents 1.24.0 → 1.62.0, litellm
1.101.0 → 1.101.3
- `e2e/wrap/tools/npm-audit-exceptions.json`: three further undici 6.x
advisories added at the existing exact path and version, expiry
unchanged (2026-11-15)
- README, CONTRIBUTING and the Dockerfile comment updated

Clears 61 of the 64 Dependabot alerts. The remaining 3 (undici,
ip-address) live inside the bundled dependencies of the `npm` package in
`e2e/wrap/tools/package-lock.json`; npm 12.2.1 is the newest release and
still ships them, so there is no bump available yet.

## Dependencies & supply chain

**gitpython 3.1.62 → 3.2.1.** Already a dependency; bumped for a
security patch (CVE-2026-114145). Maintained by the gitpython-developers
org (Sebastian Thiel), monthly-ish releases, long advisory history with
prompt fixes. Install surface unchanged: pure-Python wheel
(`py3-none-any`), one runtime dependency (`gitdb`), no native code, no
install-time or runtime network of its own.

**strands-agents 1.24.0 → 1.62.0.** Already a dependency behind the
`[strands]` extra; bumped for a security patch (CVE-2026-115419, fixed
in 1.43.0; the lock takes the current release). Maintained by AWS
(strands-agents org, `opensource@amazon.com`), weekly releases. Install
surface: pure-Python wheel, no native code. Declared dependencies grow
by two, `httpx` and `pyyaml`, both already in the lock for other
packages, so no new transitive packages are introduced. Runtime network
is unchanged: it calls the model provider the user configures, as
before.

**litellm 1.101.0 → 1.101.3.** Already a core dependency; patch bump for
CVE-2026-114612, the smallest fix that keeps the `filelock>=4.2.1` floor
resolvable (litellm 1.106 caps filelock <4). No change to maintainers or
install surface.

**pillow, filelock, virtualenv.** No new packages; the lock now holds
the single patched version the 3.11+ fork already had.

## Testing

- [x] Linting passes (`ruff check .`, `ruff format --check .`)
- [x] Type checking passes (`mypy headroom`): 1 error, identical to main
(`langchain/chat_model.py:380`)
- [x] Unit tests (targeted, see below)

### Test Output

```text
$ pytest -q tests/test_litellm_optional.py tests/test_dependency_overrides.py tests/test_release_workflows.py tests/test_image_decoder_guard.py tests/test_optional_dependencies.py tests/test_onnx_dependency_contract.py
74 passed in 3.07s

$ grep -rl -E "headroom\.release_version|headroom\.providers\.codex\.project_context|headroom\.cli\.wrap" tests | xargs pytest -q
4 failed, 1043 passed in 28.03s     # same 4 in tests/test_cli/test_wrap_persistent.py fail on main

$ uv run --extra strands --extra dev -m pytest -q tests/integrations/test_strands tests/test_strands_tokenizer.py
18 failed, 87 passed in 52.30s      # the 18 are *Real classes needing live AWS Bedrock creds; main fails the same 18 on 1.24.0

$ uv export --frozen --no-dev --no-emit-project --no-hashes --extra all --format requirements-txt > requirements-prod.txt
$ uvx pip-audit==2.10.1 -r requirements-prod.txt --no-deps --disable-pip
No known vulnerabilities found

$ cd e2e/wrap/tools && npm audit --package-lock-only --json > audit.json && <security.yml check script>
unexpected: []  stale: []  seen: 6
```

## Real Behavior Proof

- Environment: macOS 27.2 arm64; uv-managed CPython 3.11.16 and 3.10;
the lock from this branch.
- Exact command / steps:
  ```text
$ uv run --python 3.11 --all-extras python -c "import sys, platform,
headroom, PIL, filelock, virtualenv, git, strands, litellm,
importlib.metadata as m; ..."
$ uv venv -p 3.10 /tmp/py310-venv && uv pip install --python
/tmp/py310-venv/bin/python --dry-run .
  ```
- Observed result:
  ```text
  macOS-27.2-arm64-arm-64bit
  python 3.11.16
  pillow 13.0.0
  filelock 4.2.4
  virtualenv 21.14.13
  gitpython 3.2.1
  strands-agents 1.62.0
  litellm 1.101.3

(3.10) ... headroom-ai==0.42.0 depends on Python>=3.11, we can conclude
that headroom-ai==0.42.0 cannot be used.
And because only headroom-ai==0.42.0 is available and you require
headroom-ai, we can conclude that your requirements are unsatisfiable.
  ```
- Not tested: Linux and Windows installs (CI wheel matrix covers them);
a live Bedrock run of the strands integration; the Docker image build.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: installs on Python 3.10 are refused
at resolve time; no runtime behavior change on 3.11+
- Kill switch / disable path: n/a
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert the PR

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] New and existing unit tests pass locally with my changes (targeted
runs above; pre-existing failures noted)
- [x] I did **not** edit `CHANGELOG.md`
- [ ] New tests added: n/a, dependency and metadata change; existing
contract tests cover the floor and the pillow override

## Additional Notes

Follow-ups, not in this PR:
- ruff `target-version = "py311"` plus the pyupgrade fixes
- remaining `tomli` fallbacks in `tests/` and the `sys.version_info <
(3, 11)` branches they guard
- `python_version < '3.11'` branches in the onnxruntime markers (now
dead but harmless)
- `pyo3` `abi3-py310` in `Cargo.toml` could move to `abi3-py311`
- the 3 remaining Dependabot alerts (bundled undici/ip-address in npm)
until an npm release replaces them

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-28 07:28:07 -07:00
Tejas ChopraandClaude Opus 5 b10dd8db6e fix(memory): pin LF on memory writers and guard the learn-writer newline contract (#3706)
Closes #3698. Follow-up to #3594, which fixed `headroom/learn/writer.py`
correctly but left three gaps.

## 1. The write half had no regression guard

`test_apply_does_not_accumulate_carriage_returns_on_crlf_file` passes on
`main` with the fix reverted — its assertion (`raw.count(b"\r") ==
raw.count(b"\r\n")`) holds for a CRLF-preserving file too. So the
`newline="\n"` pins, which *are* the fix, were unguarded.

This cannot be caught by asserting on file bytes on POSIX: CPython's C
`TextIOWrapper` picks the newline translation target at compile time
(`#ifdef MS_WINDOWS`), so monkeypatching `os.linesep` does not simulate
Windows.

The new test spies on `Path.write_text` and drives the real writer
`.write()` methods. Stripping the kwargs from all seven sites:

```
tests/test_learn/test_writer.py ................................F
E   AssertionError: learn writers wrote without newline='\n': [
E     .../data/memory/MEMORY.md, .../instructions.md, .../myproject/AGENTS.md,
E     .../myproject/CLAUDE.local.md, .../myproject/CLAUDE.md,
E     .../myproject/GEMINI.md, .../myproject/GROK.md]
=================== 1 failed, 32 passed ===================
```

All seven named — and note the other 32 pass, including the old test,
confirming it was never a guard.

## 2. The same bug was still live in the memory writers

Ten call sites, all nine from the issue plus
**`headroom/memory/sync.py:137`** (`_save_sync_state`), which the issue
missed:

`writers/base.py:168` · `writers/claude_writer.py:119` ·
`writers/cursor_writer.py:130` · `bridge.py:126, 394, 650` ·
`sync.py:137` · `sync_adapters/codex_agent.py:124` ·
`sync_adapters/claude_code.py:196, 239`

These write files that **overlap** with the learn writers
(`~/.claude/CLAUDE.md`, `AGENTS.md`), so on Windows a file flipped
between LF and CRLF depending on which subsystem wrote last.

**No live accumulation bug:** every reader of these files uses
`read_text()`, which normalizes — that is the key difference from
`learn/writer.py`'s `read_bytes().decode()`, which is what let `\r` pile
up. Checked all of them (`bridge.py:114, 222, 617`,
`writers/base.py:193`, `writers/cursor_writer.py:103`,
`sync_adapters/claude_code.py:106, 163, 178, 216`,
`sync_adapters/codex_agent.py:48, 83`, `sync.py:127`).

**But the churn is more than cosmetic**, which the issue did not note:
`claude_code.py:252` and `codex_agent.py:135` read via `read_bytes()`
for `fingerprint()` change-detection hashing. An EOL flip changes the
hash, so a CRLF/LF flip reads as a content change and triggers a
spurious re-sync.

Three new tests cover the writer, bridge and sync-adapter paths; all
three fail with the pins stripped.

## 3. No unit test had ever run on Windows

The sharded `test` job is ubuntu-only, and `build-wheel-windows` builds
without testing — which is how a Windows-only bug shipped twice. Added
`test-windows-newline`: consumes the existing `headroom-wheel-windows`
artifact and runs only tests marked `windows_newline`. Marker registered
in `pyproject.toml`.

**Known limitation, documented in the job comment:** it is gated on the
`packaging` paths-filter (that is what builds the wheel), so a
pure-Python PR skips it. The ubuntu shards still run the same marked
tests — they assert the kwarg, which fails on any platform — so this is
the Windows-side backstop, not the only guard. Making it fire on every
writer change would mean gating the Windows Rust wheel build on `code`,
which is too expensive to do unasked.

## Verification

- 4 guards proven to fail before, pass after.
- `tests/test_learn/ tests/test_memory/ tests/test_memory_sync.py` →
**950 passed, 4 skipped**.
- Adjacent suites → 168 passed. `pytest tests -m windows_newline` → 4
passed, no marker warning.
- `actionlint .github/workflows/*.yml` → exit 0. Action versions match
the file's conventions (`checkout@v7`, `setup-python@v7`,
`download-artifact@v8`).

`CONTRIBUTING.md` states the invariant once under Coding standards:
Headroom writes LF and normalizes on read, on every platform.

## Not in this PR

Issue section 3's release-note line about the one-time EOL churn on
Windows (the first `--apply` rewrites the whole file to LF). Harmless
under `autocrlf=true`, but worth a release note; `CHANGELOG.md` edits
are blocked by `changelog-guard.yml`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-29 11:18:03 -05:00
Tejas ChopraandClaude Opus 5 96dfc7005f chore: finish the org and docs-domain migration (#3389)
Two stale identities left over from moves that were only half applied.

## GitHub org

`install/state.py` already migrated Docker images to
`ghcr.io/headroomlabs-ai/headroom` and carries a
`_DEPRECATED_IMAGE_REPO` constant that rewrites the old path on load —
so this move was decided long ago. Everything else still said
`chopratejas/headroom`.

Rewritten across packaging (`pyproject.toml`, `Cargo.toml`), both plugin
marketplaces, the agent-hooks manifests, install scripts, CI templates,
crate docs and tests.

**Two deliberate exclusions:**
- **`ghcr.io/chopratejas/headroom` is untouched everywhere.** It is the
*input* to `_migrate_deprecated_image()` and to the tests covering it.
Rewriting it would silently disable the migration.
- **`CHANGELOG.md` keeps its 238 historical references.** GitHub's
rename redirect resolves them, and rewriting would bury this diff in
noise.

**HuggingFace model ids are NOT affected and were never in scope.**
`chopratejas/kompress-base`, `kompress-v2-base`, `kompress-finance`,
`technique-router`, `technique-router-onnx` and
`siglip-image-encoder-onnx` are account-scoped identifiers on a
different service. All six were validated against the HF API before this
change:

| Model | HTTP |
|---|---|
| `kompress-base` | 200 |
| `kompress-v2-base` | 200 |
| `technique-router` | 200 |
| `technique-router-onnx` | 200 |
| `siglip-image-encoder-onnx` | 200 |
| `kompress-finance` | **401 (private)** |

The 401 is unrelated to this migration, but worth knowing:
`kompress_compressor.py:1255` references it, so that path is not
reachable by an OSS user without access.

**One functional fix, not cosmetic:** `_marketplace_source()`
(`headroom/cli/init.py`) returned the old org as its fallback, so plugin
installs were pointed at the retired repo.

## Docs domain

The site moved to `docs.headroomlabs.ai`, but eleven references still
named the vercel.app host — including **`llms.txt` (27 links)**, which
is served at `docs.headroomlabs.ai/llms.txt` and read by LLM crawlers,
the **dashboard's own Documentation link**, and a `headroom wrap` help
message. The docs app's canonical-URL fallbacks were fixed separately in
#3388.

## Also folded in

`RUST_DEV.md` corrections found while verifying the above:
- `make build-wheel` points at `Cargo.toml`, not `pyproject.toml`
- the Rust toolchain is pinned, not tracking `stable`
- `headroom-simulators` was missing from the workspace listing
- the Python `CompressionStore` defaults to **SQLite**, not in-memory,
when `HEADROOM_CCR_BACKEND` is unset (verified by execution) — this one
matters for multi-worker reasoning

And the install scripts pointed at `docs/docker-install.md`, a path that
no longer exists; they now point at the live docs page.

## Verification

297 tests pass, including the plugin-manifest, install-state and
release-workflow suites that assert on these exact strings. `ruff check`
clean. Unrelated lockfile churn (`uv.lock`, both `package-lock.json`) is
deliberately excluded.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01HRaEPjQcCSAwD2xbQMNENu

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-02 15:53:35 +05:30
Tejas Chopra e7340aee65 ci(changelog): stop the CHANGELOG cascade — release-please owns it (#2329)
## Description

Stops the recurring **CHANGELOG cascade** where several concurrent PRs
all edit `CHANGELOG.md`'s `## Unreleased` section, so the first to merge
turns the rest `DIRTY` — forcing a serial rebase-per-merge grind.

Root cause: **release-please already generates `CHANGELOG.md`** from
Conventional Commit titles (see `.release-please-config.json`
`changelog-sections`), so the hand-written `## Unreleased` entries are
*both redundant with release-please and the sole source of the
conflicts*. The PR template and CONTRIBUTING were actively telling
contributors to keep hand-editing it. `.gitattributes merge=union`
(#2138) does not help — GitHub squash-merge ignores merge drivers.

Fix: make release-please the only author of the changelog and stop
hand-edits at the source.

Closes #

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue) — CI/process

## Changes Made

- **`.github/workflows/changelog-guard.yml`** (new): fails any PR that
modifies `CHANGELOG.md`, except release-please's own release PR (head
branch `release-please--*`). Uses the preinstalled `gh` CLI — no
third-party action to pin.
- **`.github/PULL_REQUEST_TEMPLATE.md`**: flips the "I have updated the
CHANGELOG.md" checkbox to "I did **not** edit CHANGELOG.md —
release-please generates it from my Conventional Commit PR title."
- **`CONTRIBUTING.md`**: replaces step 6 ("Update `CHANGELOG.md`") with
the release-please policy.

## Testing

- [x] `actionlint .github/workflows/changelog-guard.yml` — clean
- [x] YAML parses (`yaml.safe_load`)
- [x] Guard match logic unit-checked locally: fires on root
`CHANGELOG.md`, ignores nested paths (`docs/CHANGELOG.md`) and PRs that
don't touch it.

### Test Output

```text
YAML OK
actionlint OK
root CHANGELOG.md         -> FIRES
nested docs/CHANGELOG.md  -> pass
no changelog              -> pass
```

## Real Behavior Proof

- Environment: local clone + `actionlint`.
- Exact steps: created the workflow, validated with actionlint + a YAML
parse, and exercised the `grep -qx 'CHANGELOG.md'` decision against
representative changed-file lists.
- Observed result: guard fires only on a root-level `CHANGELOG.md` edit;
the release-please branch is exempted via the job-level `if`.
- Not tested: a live PR run in Actions (will exercise on this PR itself
— note this PR does **not** touch `CHANGELOG.md`, so the guard should
pass green here).

## Additional Notes

- To *enforce* (block merge, not just show red), add **Changelog Guard /
no-manual-changelog** to the branch's required status checks.
- Follow-up: the ~10 currently-open PRs that hand-edit `CHANGELOG.md`
will need that edit removed (a clean deletion now, not a conflict
resolution) before they merge — after which the cascade is gone for
good.
2026-07-16 14:28:57 -07:00
Tejas Chopra bd76235f5c fix(cli): harden all CLI surfaces + fix docs accuracy (#1491)
## Summary

Full CLI audit + documentation accuracy pass. All 5 commits on this
branch:

### CLI Hardening (4 commits)
- **Clean errors instead of tracebacks**: corrupt manifests, missing
Docker, malformed JSONL, bad `--profile`, invalid env-var values all now
raise `click.ClickException` with helpful messages
- **Range validation**: ~25 numeric flags across 10 files now use
`click.IntRange`/`FloatRange` — `--port 0`, `--hours -1`, `--limit 0`
etc. produce clean usage errors instead of silent wrong behavior
- **Flag combination warnings**: conflicting combos (`--no-rate-limit` +
`--rpm`, `--no-optimize` + `--target-ratio`, `--telemetry` +
`--no-telemetry`) emit yellow warnings on stderr
- **`memory --db-path` default fixed**: was resolving to
`headroom_memory.db` (wrong bare file); now uses project store
`./.headroom/memory.db` if present, else `~/.headroom/memory.db`
- **`memory list --search` + filters**: `--scope`/`--session`/`--since`
were silently ignored when `--search` was also set; now filters are
applied to search results
- **`learn --verbosity --apply` now works**: the output shaper is off by
default (`HEADROOM_OUTPUT_SHAPER`); `--apply` now hot-enables it via
`POST /admin/runtime-env` on a running proxy, or prints explicit `export
HEADROOM_OUTPUT_SHAPER=1` instructions when no proxy is running
- **`perf --hours` overflow**: `1e9` hours no longer raises
`OverflowError`; treated as "all data"
- **`evals memory --categories` invalid input**: `abc,1,2` now raises
`BadParameter` instead of a raw `ValueError` traceback

### Documentation (1 commit, 20 files)

Corrected factual errors found by 3 parallel audit agents across root
docs, wiki, and the published Fumadocs site:

**Critical (caused runtime errors or wrong behavior if followed):**
- `simulation.mdx`: `plan.transforms_applied` -> `plan.transforms`;
`plan.savings_percent` -> computed from available fields (both raised
`AttributeError`)
- `shared-context.mdx`: `import { SharedContext } from "headroom"` ->
`"headroom-ai"` (5x `ImportError`)
- `claude-code-azure-foundry.mdx`: `pip install headroom` -> `pip
install headroom-ai`
- `api-reference.mdx` + `configuration.mdx`: `from headroom import
GoogleProvider` -> `from headroom.providers import GoogleProvider`
- `ccr.mdx`: CCR TTL default 300s -> 1800s (30 min)

**Fabricated flags removed:**
- `wiki/proxy.md` + `wiki/cli.md`: `--no-intelligent-context`,
`--no-intelligent-scoring`, `--no-compress-first` (none exist); replaced
with real CCR flags
- `wiki/configuration.md`: `--no-ccr-responses`, `--no-ccr-expansion`
(none exist); replaced with real flags
- `wiki/troubleshooting.md`, `wiki/metrics.md`,
`docs/troubleshooting.mdx`: `headroom proxy --log-level debug` (flag
doesn't exist)

**Stale content corrected:**
- `llms.txt`: telemetry stated as enabled-by-default (it's opt-in); wrap
list had 5 tools (now 11)
- `README.md`: compatibility matrix added 5 missing `wrap` targets;
`unwrap`, `doctor`, `init`/`install`, savings-analytics now mentioned
- `SECURITY.md`: supported version table showed 0.2.x (current: 0.27.x)
- `wiki/learn.md`: 5 missing flags added; verbosity shaper-off behavior
documented
- `wiki/quickstart.md`: "Configuration Reference" linked to `api.md`
(wrong) -> `configuration.md`
- `CacheAlignerConfig.enabled` default corrected: `True` -> `False`
- `opencode.mdx`: `--port` default wrong ("random") -> 8787; `openai`
backend removed
- `CONTRIBUTING.md`: broken Markdown table cell fixed
- `docs/meta.json`: `claude-code-azure-foundry` added to nav (was
unreachable orphan page)
- `configuration.mdx`: SDK modes vs proxy `--mode` now clearly
distinguished

## Test plan

- [x] `python -m pytest tests/ -x -q` — 857 passed, 0 failures
- [x] 41-combination CLI smoke test (all flag combos across 8 commands)
— 0 tracebacks
- [x] `ruff check` on all modified Python files — clean
- [x] Docs changes are removals/corrections of fabricated or stale
content; no new claims introduced
2026-06-27 14:48:43 -07:00
Joel Belangerandjbelanger 0b4a4bd483 fix: support Copilot Business subscription auth (#641)
## Description

Adds a first-party `headroom copilot-auth login` flow for Copilot
subscription
mode and uses the resulting Copilot OAuth token to perform GitHub's
Copilot
token exchange before launching the wrapped Copilot CLI.

This fixes Business/Enterprise Cloud accounts where a generic
GitHub/Copilot
token can read Copilot account metadata but is rejected by the Copilot
token
exchange endpoint. It also avoids treating GitHub.com Enterprise Cloud
account
URLs such as `github.com/enterprises/acme` as API hostnames.

Fixes #635
Related: #488, #610
Builds on #576

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [x] Documentation update
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Adds `headroom copilot-auth login` and `headroom copilot-auth status`.
- Stores a Headroom-specific Copilot OAuth token under Headroom's state
dir.
- Exchanges reusable Copilot OAuth tokens with Copilot Chat-compatible
headers before subscription-mode launch.
- Carries the resolved Copilot API endpoint into `headroom wrap copilot
--subscription`.
- Handles GitHub.com Enterprise Cloud URLs without synthesizing invalid
`api.github.com/enterprises/...` hosts.
- Adds focused unit tests and README guidance for subscription login.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```console
ruff check headroom/copilot_auth.py headroom/cli/copilot_auth.py headroom/cli/main.py headroom/cli/__init__.py headroom/cli/wrap.py tests/test_copilot_auth.py tests/test_cli/test_copilot_auth.py tests/test_cli/test_wrap_copilot.py tests/test_copilot_subscription_smoke.py
# All checks passed!

ruff format --check headroom/copilot_auth.py headroom/cli/copilot_auth.py headroom/cli/main.py headroom/cli/__init__.py headroom/cli/wrap.py tests/test_copilot_auth.py tests/test_cli/test_copilot_auth.py tests/test_cli/test_wrap_copilot.py tests/test_copilot_subscription_smoke.py
# 9 files already formatted

python -m py_compile headroom/copilot_auth.py headroom/cli/copilot_auth.py headroom/cli/main.py headroom/cli/__init__.py headroom/cli/wrap.py tests/test_copilot_auth.py tests/test_cli/test_copilot_auth.py tests/test_cli/test_wrap_copilot.py tests/test_copilot_subscription_smoke.py

uv run --no-project --with pytest --with pytest-asyncio --with click --with rich --with opentelemetry-api --with pydantic --with tiktoken --with 'litellm==1.82.3' --with fastapi --with uvicorn --with 'httpx[http2]' --with openai --with mcp --with magika --with zstandard --with websockets --with onnxruntime --with transformers --with watchdog --with sqlite-vec pytest tests/test_copilot_auth.py tests/test_cli/test_copilot_auth.py tests/test_cli/test_wrap_copilot.py tests/test_cli_proxy_env.py tests/test_copilot_subscription_smoke.py
# 127 passed
```

Local note: `uv run pytest ...` against the project currently fails
before
running tests because `uv.lock` has an unrelated `gitpython`
wheel/version
mismatch.

## Manual Validation

I tested this with an existing GitHub Copilot Business subscription
associated with a GitHub.com Enterprise Cloud account.

The Enterprise Cloud value I tested was in the form:

```text
github.com/enterprises/<enterprise>
```

The tested flow was:

```text
headroom copilot-auth login
headroom wrap copilot --subscription -- --model gpt-5.4
```

This validated that Headroom does not treat
github.com/enterprises/<enterprise> as a Copilot API hostname. Instead,
token exchange uses GitHub.com and Headroom routes subscription-mode
traffic to the Copilot API endpoint returned by GitHub for the signed-in
account.

I did not test this with GitHub Enterprise Server or a custom enterprise
domain such as ghe.example.com.

No tokens, request IDs, or organization-specific identifiers are
included in this PR.

## Real Behavior Proof

- Environment: macOS Darwin, Python 3.12.7, local checkout on
`codex/copilot-business-auth`.
- Exact command / steps: Ran `headroom copilot-auth login`, then
launched `headroom wrap copilot --subscription -- --model gpt-5.4` with
a GitHub Copilot Business subscription tied to a GitHub.com Enterprise
Cloud account.
- Observed result: Headroom did not treat
`github.com/enterprises/<enterprise>` as a Copilot API hostname; token
exchange used GitHub.com and subscription traffic was routed to the
Copilot API endpoint returned for the signed-in account. The latest
focused Copilot auth/proxy tests pass locally (`127 passed`).
- Not tested: GitHub Enterprise Server or custom enterprise domains such
as `ghe.example.com`; Windows Credential Manager integration still needs
confirmation from someone on Windows.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing targeted unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable

## Screenshots (if applicable)

N/A

## Additional Notes

Acknowledgement: the OAuth/token-exchange behavior was informed by
`anomalyco/opencode-copilot-auth` by Aiden Cline.

No tokens are printed by the new login/status commands; only a short
SHA-256
fingerprint is displayed for troubleshooting.

The interactive login is included because the missing piece is not just
an
Enterprise URL or routing hint. For GitHub.com Enterprise Cloud
accounts,
URLs like `github.com/enterprises/acme` identify the enterprise account
but
are not Copilot API hostnames; token exchange still happens through
GitHub.com
and then returns the account-specific Copilot API endpoint. A
command-line
enterprise argument can help for true GitHub Enterprise
Server/custom-domain
deployments, but it cannot produce the Copilot OAuth token class that
the
token-exchange endpoint accepts.

Ideally, Headroom would avoid an extra interactive login and reuse an
existing
GitHub/Copilot CLI session everywhere. In practice, some
reusable-looking
tokens can read Copilot account metadata but are rejected by Copilot
token
exchange, which leaves Business/Enterprise Cloud users with missing
model
catalogs. The explicit login command is the smallest independent way to
obtain
and persist the token needed for that exchange without asking users to
pass a
secret on the command line.

---------

Co-authored-by: jbelanger <your-username@users.noreply.github.com>
2026-06-12 20:46:38 -05:00
96a7d7cbbe Fix CI lint failure by formatting PR governance scripts (#933)
`CI / lint (pull_request)` failed because `ruff format --check` detected
formatting drift in the new PR governance script and its tests. This PR
aligns those files with repository formatting rules so the lint job can
pass.

- **Root cause**
  - `ruff format --check .` reported two files as non-canonical:
    - `scripts/pr-governance.py`
    - `scripts/tests/test_pr_governance.py`

- **Change set**
  - Applied `ruff` formatting to only the two flagged files.
- No behavioral or logic changes; edits are line-wrap/format
normalization only.

- **Representative update**
  ```python
  parser.add_argument(
"--event", type=Path, required=True, help="Path to the GitHub event
payload JSON."
  )
  ```

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
2026-06-12 17:11:39 -05:00
AshishandClaude Sonnet 4.6 3db6cd430f chore: wire pre-commit ruff hooks into make install-git-hooks (#786)
## Problem

`.pre-commit-config.yaml` already has `ruff` + `ruff-format` configured,
and `pre-commit>=3.0.0` is already in `[dev]` deps — but `make
install-git-hooks` never called `pre-commit install`. Every
contributor's repo had the hook **config** but no running hook.

PR #772 merged with inline-comment spacing and import-order violations
that ruff would have caught automatically. The maintainer had to add a
separate fixup commit (`fix: format issue 728 regression test`) to clean
it up.

## Changes

**`scripts/install-git-hooks.sh`** — after installing the pre-push hook,
also run `pre-commit install`. Falls back to `.venv/bin/pre-commit` when
`pre-commit` is not on `PATH`, with a clear warning if neither is found:

```
✅ installed: .git/hooks/pre-push
   Runs 'make ci-precheck' before every git push.
✅ installed: .git/hooks/pre-commit (ruff lint + format via pre-commit)
```

**`CONTRIBUTING.md`** — update PR workflow step 2 to mention `make
install-git-hooks` so contributors know to run it after `pip install`:

```
2. pip install -e ".[dev]" then make install-git-hooks — installs ruff on
   every commit and ci-precheck on every push.
```

## No behaviour change for existing code

Only the local dev setup script is touched. Nothing in the proxy, tests,
or CI pipeline changes.

## Real behavior proof

- **OS**: macOS darwin arm64
- **Steps**: ran `bash scripts/install-git-hooks.sh` with venv
available, then attempted a commit with a badly-formatted file
- **Result**: ruff caught and auto-fixed it before the commit landed

```
✅ installed: .git/hooks/pre-push
   Runs 'make ci-precheck' before every git push.
   Bypass (use sparingly): git push --no-verify
pre-commit installed at .git/hooks/pre-commit
✅ installed: .git/hooks/pre-commit (ruff lint + format via pre-commit)
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-09 23:09:22 -05:00
Devanshi Vyas 264271b595 docs: update contributing.md 2026-06-05 22:02:28 -07:00
JerrettDavisandCopilot a1beb08d53 feat: add reproducible devcontainers
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>
2026-04-10 12:58:35 -05:00
Tejas Chopra e782723ac3 Update CONTRIBUTING.md 2026-01-10 15:05:16 -08:00
chopratejas 175746cc26 Prepare for OSS release v0.2.0
This commit prepares Headroom for public open source release with
comprehensive documentation, licensing, and community infrastructure.

License & Legal:
- Add Apache 2.0 LICENSE file
- Add NOTICE file with third-party attributions
- Add SECURITY.md for vulnerability reporting

Community:
- Add CONTRIBUTING.md with contribution guidelines
- Add CODE_OF_CONDUCT.md (Contributor Covenant)
- Add GitHub issue templates (bug report, feature request)
- Add pull request template

Documentation:
- Update README.md with compelling value proposition
- Add docs/getting-started.md
- Add docs/proxy.md for proxy server documentation
- Add docs/transforms.md for transform reference
- Add docs/api.md for API reference
- Add examples/README.md

Package Infrastructure:
- Add headroom/py.typed for PEP 561 compliance
- Add headroom/cli.py for CLI entry point
- Add .github/workflows/ci.yml for CI pipeline
- Add .github/workflows/publish.yml for PyPI publishing
- Update pyproject.toml with proper metadata

New Features:
- Add multi-provider support (Google, Cohere, LiteLLM, OpenAI-compatible)
- Add universal tokenizer registry with multiple backends
- Add model registry with pricing and context limits
- Add production proxy server with caching and rate limiting

Code Quality:
- Fix 83 lint issues via ruff auto-fix
- Fix version consistency (benchmarks 0.1.0 → 0.2.0)
- Add skip decorators for optional dependency tests
2026-01-07 11:36:44 -08:00