feat(cli): add headroom wrap auggie

[rNoz]

Description

Add headroom wrap auggie, which routes an AugmentCode Auggie session through the local Headroom proxy with a single command, mirroring the shipped wrap droid / wrap copilot.

Auggie reads its tenant URL from its OAuth session (~/.augment/session.json) and calls that host for every request. This command rewrites ONLY the session tenantURL to the local proxy (the access token is preserved byte-for-byte), passes the rewritten session to Auggie via AUGMENT_SESSION_AUTH, and starts the proxy in Auggie mode. The proxy forwards every Auggie tenant path verbatim to the real tenant and tags the POST /chat-stream inference call as the augment provider in /stats. All models (including Prism routing) stay on the user's Augment subscription, with no API keys and no persistent config edits.

Auggie's tenant wire is Augment-proprietary (/chat-stream uses a bespoke request/response shape, not Anthropic/OpenAI), so this first version forwards inference bodies unchanged. The value delivered is the single-command redirect plus proxy observability. Request compression and output-token shaping for the Augment shape are follow-ups.

Closes #2719

Type of Change

• New feature (non-breaking change that adds functionality)
• Documentation update

Changes Made

• headroom/proxy/models.py: add ProxyConfig.augment_api_url: str | None.
• headroom/proxy/server.py: thread augment_api_url through the /health config report, _proxy_config_from_env (AUGMENT_TARGET_API_URL), the argparse --augment-api-url flag, and the CLI config build.
• headroom/cli/proxy.py: add the --augment-api-url click option (env AUGMENT_TARGET_API_URL).
• headroom/providers/proxy_routes.py: when augment_api_url is set, register POST /chat-stream -> handle_passthrough(request, <tenant>, "chat-stream", "augment"). Registered only when configured (mirrors the Bedrock precedent). The upstream is an explicit argument, not resolved from a client-controllable header, so there is no routing-header spoofing vector to harden against.
• headroom/providers/proxy_targets.py: select_passthrough_base_url returns the Augment tenant upstream first when set, so every other Auggie REST call (/get-models, /agents/list-remote-tools, /settings/get-mcp-*-configs, /find-missing) reaches the tenant via the catch-all.
• headroom/providers/augment/ (new): runtime.py (resolve_augment_upstream, build_redirected_session, load_session with defensive errors, proxy_base_url), __init__.py.
• headroom/cli/wrap.py: new @wrap.command auggie. Reads the session (friendly errors on missing/malformed), rewrites tenantURL, scrubs inherited AUGMENT_* env, sets AUGMENT_SESSION_AUTH, and launches via _launch_tool(..., agent_type="augment", augment_api_url=<tenant>). augment_api_url is threaded through _launch_tool -> _ensure_proxy -> _start_proxy (new optional param, default None, so all other wrappers are unchanged). A reuse guard refuses to reuse a non-Auggie proxy on the target port, since its missing /chat-stream route would misroute Auggie, and points at a dedicated port instead.
• Docs: new docs/content/docs/auggie.mdx (registered in meta.json); README.md feature list and compatibility matrix; llms.txt. No CHANGELOG.md edit, release-please generates that entry from this PR title.
• Tests: tests/test_cli/test_wrap_auggie.py (16) plus /chat-stream route present/absent and passthrough-forward cases in tests/test_provider_proxy_routes.py, and an Augment target case in tests/test_provider_proxy_targets.py.

Testing

• Unit tests pass (pytest)
• Linting passes (ruff check .)
• Type checking passes (mypy headroom)
• New tests added for new functionality
• Manual testing performed

Test Output

$ uv run pytest tests/test_cli/test_wrap_auggie.py tests/test_provider_proxy_routes.py tests/test_provider_proxy_targets.py
52 passed (re-verified 2026-08-04 after merging current upstream/main)

$ uv run ruff format --check . && uv run ruff check . && uv run mypy headroom
clean on all touched files

Real Behavior Proof

• Environment: macOS, Auggie @augmentcode/auggie (interactive), model haiku4.5 (cheapest), Headroom current-tree build, isolated proxy port 8790 (not the shared 8787).
• Exact command / steps: headroom wrap auggie --port 8790 -- -m haiku4.5, then at the Auggie prompt: Reply with exactly the single word: PONG.
• Observed result: wrap output showed Auggie tenant URL rewritten -> http://127.0.0.1:8790 and Auggie tenant upstream: https://xlb.api.augmentcode.com; Auggie replied PONG. GET http://127.0.0.1:8790/stats showed "by_provider": {"augment": 2} and "agent_usage" attributing both requests to the augment provider, confirming real subscription traffic flowed through the proxy via the rewritten session. The model shows as passthrough:chat-stream because v1 does not parse Auggie's proprietary response for the real model id or token counts, which is the documented follow-up. Session-integrity check: md5 of ~/.augment/session.json was unchanged before and after a wrapped run, and its tenantURL remained the real tenant, confirming the env-only redirect writes nothing to disk.
• Not tested: a BYOK / third_party_override model (no third-party provider key available in the test env); request/response compression (out of scope for v1, proprietary wire); streaming UX beyond the buffered response shown above (token-by-token streaming and JSON-lines usage parsing is a follow-up).

A real session, a screenshot of my terminal, how AugmentCode/Auggie has been supported, the real proofs:

Detection in dashboard (telemetry):

Review Readiness

• I have performed a self-review
• This PR is ready for human review

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I did not edit CHANGELOG.md, it is generated by release-please from my Conventional Commit PR title

Additional Notes

One logical change, minimal diff, mirrors wrap droid exactly. No changes to default proxy behavior, since the route and target selection are gated on augment_api_url. No persistent config writes and no unwrap auggie needed, since nothing durable is written. No credential is stored, logged, or fabricated, the token is preserved byte-for-byte and forwarded untouched.

Follow-ups not in this PR: parsing the /chat-stream JSON-lines response for the real model id, token usage, and cost so /stats shows real tokens and cost; streaming /chat-stream instead of buffering; an Augment-shape request compressor and output-token shaping (the response reports tool_definitions_tokens ~= 34k per turn).

[github-actions]

PR governance

This PR does not yet satisfy the required template fields:

• Missing required section Runtime Rollout Safety.

Please update the PR body, or move the PR back to draft while it is still in progress.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[JerrettDavis]

The dedicated-proxy path is thoughtfully isolated by tenant, but --no-proxy bypasses that safety check entirely. The preflight guard is wrapped in if not no_proxy and _check_proxy(port), and _ensure_proxy only warns when no_proxy=True; it does not compare augment_api_url. The wrapper then injects the OAuth-bearing session with tenantURL=http://127.0.0.1:<port> regardless. Thus headroom wrap auggie --no-proxy can send the Augment access token to a non-Auggie Headroom proxy (which will route /chat-stream elsewhere/404) or any unrelated local service on that port, contradicting the docs’ promise that a non-Auggie proxy is rejected. Please require an existing healthy Headroom proxy whose normalized config.augment_api_url exactly matches the resolved tenant before launching in --no-proxy mode; otherwise fail closed with a dedicated-port instruction. Add regressions for no service, non-Headroom service/unavailable config, non-Auggie config, wrong tenant, and matching tenant. The branch is also currently conflicting with main; once this safety boundary is fixed, resolve the drift while preserving main’s newer proxy-target/routing changes. Since this remains a draft, I am not approving it as merge-ready.

[vercel]

Someone is attempting to deploy a commit to the Headroom Labs Team on Vercel.

A member of the Team first needs to authorize it.

[JerrettDavis]

Re-reviewed the refreshed head after merging current main; the focused Auggie suite is green locally (52 tests), and the merge resolution is clean. The prior security blocker remains: AUGMENT_SESSION_AUTH contains the OAuth-bearing redirected session, while the wrapped child can still receive --no-proxy (or another argument path that prevents the local proxy from being used). That can leave the real Augment tenant URL paired with the injected credential-bearing environment value. Please reject proxy-bypass arguments for wrap auggie, or otherwise prove the credential-bearing redirected session cannot be sent directly to the tenant. A focused regression test for the bypass case would make the invariant explicit.

[rNoz]

I'll work on these minor improvements when the other 3 PRs I have accepted for 3-5 weeks are merged.

[JerrettDavis]

Re-reviewed exact head 4af4b2a after the main sync. The security invariant remains unresolved: wrap auggie still accepts --no-proxy and still injects the OAuth-bearing redirected AUGMENT_SESSION_AUTH, allowing the child to launch without establishing the local proxy path. Please reject that combination (or otherwise prove direct tenant use is impossible) and add the focused regression requested previously.