feat(wrap): add headroom wrap droid for Factory Droid (#4143)

## Description

Add `headroom wrap droid` so Factory subscription traffic, including
Droid Core, can be compressed on the existing Factory plan.

Droid ignores `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` for
Factory-served models. It honors `FACTORY_API_BASE_URL`. This wrapper
points that at the local proxy and gives the proxy a Factory upstream
(`--factory-api-url` / `FACTORY_TARGET_API_URL`, default
`https://api.factory.ai`).

With a Factory upstream configured the proxy registers:

- `POST /api/llm/a/v1/messages` — compressed with the existing Anthropic
pipeline and forwarded to `{factory}/api/llm/a/v1/messages`. A
client-sent `x-headroom-base-url` is ignored. `x-headroom-*` headers are
stripped. Operator Anthropic extra headers are withheld from the
untrusted Factory host.
- Every other `/api/*` path — forwarded verbatim to Factory, except
Hermes Studio's scoped prefixes and requests that name their own
`x-headroom-base-url`.

Nothing outside `/api/` is sent to Factory.
`select_passthrough_base_url` and `upstream_trust` are untouched, so a
leftover Codex, Claude, or Copilot config pointed at a Factory-mode
proxy keeps its own upstream and credentials. That is the deliberate
difference from https://github.com/headroomlabs-ai/headroom/pull/2352,
which is still open and which this does not close. #2352 sends every
unrouted request on a Factory-mode proxy to Factory.

`wrap droid` writes no Droid config. It threads `factory_api_url`
through the existing proxy-reuse logic. With `--no-proxy` it refuses
unless `/health` shows a Headroom proxy serving the same Factory
upstream. OpenAI-shaped `/api/llm/o/*` traffic is forwarded
uncompressed. Those routes are deferred.

This commit is `74c889fb` rebased onto current `main` (`0dd8e0b5`). The
only conflicts were `docs/content/docs/meta.json` (kept both the new
`hermes` page and `droid`) and the `--no-proxy` branch in
`headroom/cli/wrap.py` (kept upstream's OpenAI upstream check and the
Factory check).

Refs #2351

## Type of Change

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

## Changes Made

- `headroom wrap droid` sets `FACTORY_API_BASE_URL` to the local proxy
and resolves the Factory upstream from `--factory-api-url`, then
`FACTORY_API_BASE_URL`, then `https://api.factory.ai`. Loopback,
credential, query, and fragment URLs are rejected.
- Factory inference and `/api/*` passthrough routes are registered only
when a Factory upstream is configured. The default proxy is unchanged.
- `/health` reports `factory_api_url`.
- Docs: `docs/content/docs/droid.mdx`.

## Testing

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

### Test Output

Rebased tree `/home/hermes/workspace/headroom-rebase` at `0dd8e0b5`,
importing that tree via `PYTHONPATH` and the existing venv at
`/home/hermes/workspace/headroom/.venv` (Python 3.11.16).

```text
tests/test_cli/test_wrap_droid.py ............................           [ 31%]
tests/test_provider_droid_runtime.py ................................    [ 66%]
```

60 passed. Those are the wrap launch-env tests and the Factory runtime
tests.

`tests/test_proxy/test_factory_decoy_proof.py` did not complete in this
worktree. The proxy refuses to start because `headroom._core` is not
built here (`ModuleNotFoundError`, exit 78). Setting
`HEADROOM_REQUIRE_RUST_CORE=false` still did not finish within 180s. The
decoy proof (decoy upstream stays silent, Factory stand-in receives the
inference request, spoofed `x-headroom-*` headers, REST passthrough,
`--no-proxy` refusals) was written for this change and passed in the
pre-rebase review session. It was not re-run to a green result after
this rebase.

`ruff` and `mypy` were not re-run after the rebase.

## Real Behavior Proof

- Environment: Linux, Python 3.11.16, rebased commit `0dd8e0b5` on top
of `upstream/main` `8c1beb20`. No Factory token. No call to
`api.factory.ai`.
- Exact command / steps:
`PYTHONPATH=/home/hermes/workspace/headroom-rebase
/home/hermes/workspace/headroom/.venv/bin/python -m pytest
tests/test_cli/test_wrap_droid.py tests/test_provider_droid_runtime.py`
- Observed result: 60 passed.
- Not tested: a live Factory subscription, `droid` itself, the socket
decoy proof on this rebased commit (blocked locally by the missing Rust
extension), `ruff`, `mypy`, and CI on GitHub.

## Runtime Rollout Safety

- Rollout-managed feature(s): none. Factory routes register only when
`factory_api_url` / `--factory-api-url` is set.
- Minimum rollout channel: stable. Default proxy behavior is unchanged.
- Stable/default behavior changed: no, unless a Factory upstream is
configured.
- Kill switch / disable path: do not pass `--factory-api-url` and do not
set `FACTORY_TARGET_API_URL`. `wrap droid` is opt-in.
- Unsafe override required: no.
- Qualification impact: none on the default proxy.
- Rollback path: revert this commit. No config is written into Droid.

## Review Readiness

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

The pre-rebase commit `74c889fb` was approved by a fresh Claude Opus 5.5
high review with an empty blocking list. This commit is that change
rebased onto current main. The two conflict resolutions are described
above and have not had a second Opus pass.

## 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
- [ ] 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 unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A

## Additional Notes

Does not close #2352. That PR is the prior attempt. This one is a
current-main rebuild with the catch-all leak removed: only `/api/*` is
forwarded to Factory.

akbarkanso is not a Headroom maintainer. Please do not expect this
account to merge.

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4143"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

### Maintainer current-main requalification

Exact head `e28dfe6422dfcb9b2cbd5ce0fe673196d3b6ad40`, upstream main
`e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`.

Updated against upstream/main e4a60ed7. Resolved the OpenAI passthrough
overlap by retaining main's prepared-request/model/timing parameters and
soft-passthrough guard alongside the contributor's verbatim flag;
generic compression requires both guards to permit it. Re-reviewed
Factory direct-routing/verbatim semantics and existing discussion. All
93 wrapper/runtime/Factory passthrough/socket-decoy tests pass with
existing native extension; changed-file Ruff lint/format and whitespace
checks pass. No contributor routing policy was rewritten.

Independently reran the official Droid1.3.0 CLI with isolated home,
dummy API key, actual Headroom/Uvicorn proxy and controlled LAN HTTP
upstream on this exact combined head. The CLI consumed the controlled
Anthropic SSE reply and exited zero with HEADROOM_QUALIFICATION_OK. The
message request preserved dummy Authorization and forwarded no
x-headroom headers. This is controlled transport/runtime qualification,
not a live Factory subscription or savings benchmark, and not a fresh
native build. Applied shared test-only Gemini fixture repair for
independently established main failures; all ten cases pass. Formal
approval awaits exact-head hosted qualification.


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.


### Maintainer current-main requalification

Exact head `7dd0725a9ac4dd8103dedf78552ceca886fc3620`, upstream main
`c01cf07d943d816cfd9d97e6838ed4e38f1ff9a4`.

Clean mechanical merge with upstream main
c01cf07d94. Re-reviewed current
Factory/Droid routing and author/Devin discussion. Factory inference
retains force_direct to bypass translating backends; Factory passthrough
retains verbatim alongside main's soft-passthrough/prepared-request
guards. Hermes scoped proxy prefixes remain excluded from Factory
dispatch; the existing standalone environment precedence is
intentionally consistent with sibling targets, while Click/wrap retain
flag precedence. No contributor routing policy rewritten.

Fresh wrapper/runtime/Factory passthrough/socket-decoy/Hermes
verification: 100 passed, with test-client/runpy warnings only. All 14
changed Python files pass Ruff lint/format; main-relative whitespace
clean and owned tree clean. Tests use the current-main native DLL for
local startup. Earlier official Droid 1.3.0 controlled-upstream runtime
proof remains scoped to its original run; no fresh official CLI replay,
Factory subscription inference, savings benchmark or branch-native build
is claimed. No new blocker found; approval awaits exact-head hosted
checks. 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: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
This commit is contained in:
akbarkanso
2026-11-07 20:48:53 -06:00
committed by GitHub
co-authored by Claude Opus 5.5 JerrettDavis
parent 602ca65126
commit bb8d18a56a
19 changed files with 1773 additions and 48 deletions
+2 -1
View File
@@ -87,7 +87,7 @@ Zero code changes. [Agent compatibility](#agent-compatibility) ·
- **Library** — `compress(messages)` in Python or TypeScript, inline in any app.
- **Proxy** — `headroom proxy --port 8787`, zero code changes, any language.
- **Agent wrap** — `headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|zcode` in one command; undo with `headroom unwrap <tool>`.
- **Agent wrap** — `headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|droid|zcode` in one command; undo with `headroom unwrap <tool>`.
- **MCP server** — `headroom_compress`, `headroom_retrieve`, `headroom_stats` for any MCP client.
- **Cross-agent memory** — one shared store across Claude, Codex, Gemini and Grok, with automatic dedup.
- **`headroom learn`** — mines failed sessions and writes corrections to `CLAUDE.local.md` (default, gitignored), `CLAUDE.md`, `AGENTS.md`, `GEMINI.md` or `GROK.md`.
@@ -292,6 +292,7 @@ Saved** card then reads `measured` rather than `estimated`, with the band.
| OpenHands | ✅ | starts proxy + launches |
| Mistral Vibe | ✅ | starts proxy + launches |
| Oh My Pi | ✅ | Anthropic + OpenAI/Codex · injects config · starts proxy + launches |
| Factory Droid | ✅ | routes via `FACTORY_API_BASE_URL`; Anthropic-model turns compressed, other Factory traffic passed through |
| Cortex Code | Library only | 60–65% savings in library mode; no `wrap` |
| Kimi CLI | ✅ | OAuth bearer forwarded — log in once |
| ZCode | ✅ | starts the proxy and prints base URLs for ZCode settings |
+73
View File
@@ -0,0 +1,73 @@
---
title: Factory Droid
description: Route Factory Droid through Headroom so Anthropic-model turns are compressed on your existing Factory subscription.
---
Use `headroom wrap droid` to run [Factory Droid](https://docs.factory.ai) through the local Headroom proxy. Droid keeps talking to Factory with its own login; Headroom sits in between and compresses the Anthropic-shaped inference requests.
## Quick Start
```bash
headroom wrap droid
```
Pass Droid arguments after `--`:
```bash
headroom wrap droid -- exec "fix the failing test"
```
There is nothing to undo. The wrapper writes no Droid config and no `customModels`; it only sets an environment variable on the `droid` process it launches.
## What `wrap droid` Does
| Step | What happens |
|---|---|
| Upstream | Resolves the real Factory upstream (see [Upstream precedence](#upstream-precedence)) |
| Proxy | Starts or reuses a Headroom proxy started with `--factory-api-url <upstream>` |
| Launch | Runs `droid` with `FACTORY_API_BASE_URL=http://127.0.0.1:<port>` |
If the requested port is busy, or a proxy with different routing is running there, the wrapper picks a free port and points `FACTORY_API_BASE_URL` at it. You do not need to pass `--port` yourself.
## What Is Compressed
| Path | Behaviour |
|---|---|
| `POST /api/llm/a/v1/messages` | Compressed with the same pipeline as `/v1/messages`, then forwarded to `<upstream>/api/llm/a/v1/messages` |
| Any other `/api/*` path | Forwarded verbatim to the upstream (method, query string, headers and body unchanged) |
| Anything outside `/api/` | Never sent to Factory; keeps the proxy's normal routing |
OpenAI-shaped traffic under `/api/llm/o/` is **not compressed yet**. It still reaches Factory, but is forwarded verbatim and buffered rather than streamed incrementally. Models Droid serves over that route see no savings.
A few `/api/*` requests keep the proxy's normal behaviour instead of going to Factory: requests that set `x-headroom-base-url`, and Hermes Studio's `/api/codex-proxy/` and `/api/claude-code-proxy/` paths.
On the compressed route, Headroom ignores a client-sent `x-headroom-base-url` and strips every `x-headroom-*` header before forwarding. Your Factory `Authorization` header is forwarded unchanged. Operator-configured Anthropic extra headers (`ANTHROPIC_TARGET_API_HEADERS`) are **not** sent to Factory.
## Upstream Precedence
1. `--factory-api-url <url>`
2. An existing `FACTORY_API_BASE_URL` in your shell (for example an enterprise or regional gateway)
3. `https://api.factory.ai`
The upstream must be an `http(s)` URL with no credentials, query string or fragment. Loopback hosts (`localhost`, `127.x`, `[::1]`) are rejected, which stops a leftover `FACTORY_API_BASE_URL` from an earlier wrapped session from pointing the proxy at itself. If you see that error, unset `FACTORY_API_BASE_URL` and run the command again.
## Using an Existing Proxy
With `--no-proxy`, the wrapper does not start a proxy. It refuses to launch Droid unless the port answers `/health` as a Headroom proxy that serves the same Factory upstream:
```bash
headroom proxy --port 8787 --factory-api-url https://api.factory.ai
headroom wrap droid --no-proxy --port 8787
```
A non-Headroom listener, a proxy without Factory routing, or a proxy for a different Factory upstream is an error, so Droid's credentials never go to a listener that was not set up for them.
## Options
| Option | Description |
|---|---|
| `--port`, `-p` | Proxy port (default: `$HEADROOM_PORT`, else 8787) |
| `--factory-api-url` | Real Factory upstream (default: `$FACTORY_API_BASE_URL`, else `https://api.factory.ai`) |
| `--no-proxy` | Use an existing Factory-mode proxy instead of starting one |
| `--learn` | Enable live traffic learning |
| `--memory` | Enable persistent cross-session memory |
+1
View File
@@ -47,6 +47,7 @@
"opencode-deepseek",
"grok-build",
"hermes",
"droid",
"oauth2-upstream",
"agent-hooks",
"openclaw",
+1
View File
@@ -65,6 +65,7 @@ Disable it with `HEADROOM_BEACON=off`, `HEADROOM_TELEMETRY=off` (or `--no-teleme
| `--gemini-api-url` | Gemini default | Custom Gemini API URL |
| `--backend` | `anthropic` | Backend: `anthropic`, `bedrock`, `openrouter`, `anyllm`, or `litellm-<provider>` |
| `--bedrock-api-url` | None | Bedrock InvokeModel upstream for the `/model/{id}/invoke` passthrough routes (see [Bedrock via a local gateway](#bedrock-via-a-local-gateway)) |
| `--factory-api-url` | None | Factory Droid upstream (env: `FACTORY_TARGET_API_URL`). Registers `/api/*` routes: `/api/llm/a/v1/messages` is compressed, other `/api/*` paths pass through verbatim. Paths outside `/api/` are never sent to Factory. Set automatically by `headroom wrap droid` (see [Factory Droid](/docs/droid)) |
| `--telemetry` | `false` | Enable local, in-process usage stats (for your own `/stats` and dashboard; nothing leaves the machine) |
| `--no-telemetry` | `false` | Force local telemetry off (already the default) |
| `--stateless` | `false` | Disable filesystem writes and keep runtime state in memory |
+18 -1
View File
@@ -1157,6 +1157,15 @@ def dashboard(port: int | None, no_open: bool) -> None:
"(env: BEDROCK_TARGET_API_URL)"
),
)
@click.option(
"--factory-api-url",
default=None,
help=(
"Factory Droid upstream for /api/* (used by `headroom wrap droid`). "
"/api/llm/a/v1/messages is compressed; other /api/* paths pass "
"through verbatim. (env: FACTORY_TARGET_API_URL)"
),
)
@click.option(
"--telemetry",
is_flag=True,
@@ -1296,6 +1305,7 @@ def proxy(
bedrock_region: str | None,
bedrock_profile: str | None,
bedrock_api_url: str | None,
factory_api_url: str | None,
telemetry: bool,
no_telemetry: bool,
stateless: bool,
@@ -1677,6 +1687,7 @@ def proxy(
# CLI flag > env > unset. Matches the BEDROCK_TARGET_API_URL naming of
# the sibling *_TARGET_API_URL passthrough overrides.
bedrock_api_url=bedrock_api_url or os.environ.get("BEDROCK_TARGET_API_URL"),
factory_api_url=factory_api_url or os.environ.get("FACTORY_TARGET_API_URL"),
anyllm_provider=effective_anyllm_provider,
# License / Usage Reporting (managed/enterprise)
license_key=license_key,
@@ -1722,6 +1733,12 @@ def proxy(
openai_url = provider_api_targets.openai
cloudcode_url = provider_api_targets.cloudcode
vertex_url = provider_api_targets.vertex
factory_route_line = (
f"\n /api/* → {config.factory_api_url} "
"(Factory Droid; /api/llm/a/v1/messages compressed)"
if config.factory_api_url
else ""
)
backend_section = ""
if config.backend == "anyllm" or config.backend.startswith("anyllm-"):
@@ -1927,7 +1944,7 @@ Routing:
/v1/chat/completions → {openai_url}
/v1/responses → {openai_url} (HTTP + WebSocket)
/v1internal:streamGenerateContent → {cloudcode_url}
/v1/projects/.../publishers/... → {vertex_url}
/v1/projects/.../publishers/... → {vertex_url}{factory_route_line}
Usage:
{usage_section}
+130 -4
View File
@@ -166,6 +166,12 @@ from headroom.providers.copilot import (
validate_configuration as _validate_copilot_configuration,
)
from headroom.providers.cursor import render_setup_lines as _render_cursor_setup_lines
from headroom.providers.droid import (
DEFAULT_FACTORY_API_URL,
canonical_factory_api_url,
resolve_factory_upstream,
)
from headroom.providers.droid import proxy_base_url as droid_proxy_base_url
from headroom.providers.grok import (
DEFAULT_API_URL as _GROK_DEFAULT_API_URL,
)
@@ -768,6 +774,7 @@ def _start_proxy(
copilot_api_token: str | None = None,
copilot_refresh_oauth_token: str | None = None,
copilot_api_token_expires_at: float | None = None,
factory_api_url: str | None = None,
proxy_extensions: list[str] | None = None,
) -> subprocess.Popen:
"""Start Headroom proxy as a background subprocess.
@@ -830,6 +837,8 @@ def _start_proxy(
if vertex_api_url:
cmd.extend(["--vertex-api-url", vertex_api_url])
if factory_api_url:
cmd.extend(["--factory-api-url", factory_api_url])
# Extensions carried over from the proxy this one replaces (see
# ``_dedicated_proxy_extensions``). The flag outranks the envvar in click,
# so callers must not pass this when HEADROOM_PROXY_EXTENSIONS is set;
@@ -890,6 +899,8 @@ def _start_proxy(
proxy_env.pop("VERTEX_TARGET_API_URL", None)
if vertex_api_url:
proxy_env["VERTEX_TARGET_API_URL"] = vertex_api_url
if factory_api_url:
proxy_env["FACTORY_TARGET_API_URL"] = factory_api_url
# Pin the wrapper-validated Copilot token for this proxy instance only.
# Injected into the subprocess env here (not the parent's os.environ) so it
# never leaks into shared state. The proxy's CopilotTokenProvider honours
@@ -4271,9 +4282,9 @@ def _proxy_needs_version_restart(payload: dict[str, Any] | None) -> bool:
# Upstream-URL config keys that decide where a running proxy forwards
# traffic. A running proxy is only reusable when every key matches the
# requested value. This build's /health config payload only serializes the
# first five keys; the augment/factory entries catch proxies built from
# feature branches or other versions that DO expose them (exactly the
# requested value. This build's /health config payload serializes the first
# five keys plus factory_api_url; the augment entry catches proxies built from
# feature branches or other versions that DO expose it (exactly the
# mixed-fleet shape of the 2026-08-22 incident, where a 0.34-era proxy
# reported augment_api_url). Keys absent from the running config simply
# compare equal to an unrequested (None) value, so they are inert, never
@@ -4333,6 +4344,7 @@ def _effective_requested_proxy_routing(
anthropic_api_url: str | None,
vertex_api_url: str | None,
clear_vertex_api_url: bool,
factory_api_url: str | None = None,
) -> tuple[str, dict[str, str | None]]:
"""Resolve the routing a newly started proxy would inherit."""
from headroom.providers.registry import resolve_api_overrides
@@ -4353,7 +4365,7 @@ def _effective_requested_proxy_routing(
"cloudcode_api_url": overrides.cloudcode,
"vertex_api_url": None if clear_vertex_api_url else overrides.vertex,
"augment_api_url": os.environ.get("AUGMENT_TARGET_API_URL"),
"factory_api_url": os.environ.get("FACTORY_TARGET_API_URL"),
"factory_api_url": factory_api_url or os.environ.get("FACTORY_TARGET_API_URL"),
},
)
@@ -4877,6 +4889,7 @@ def _ensure_proxy_unlocked(
copilot_api_token: str | None = None,
copilot_refresh_oauth_token: str | None = None,
copilot_api_token_expires_at: float | None = None,
factory_api_url: str | None = None,
) -> tuple[subprocess.Popen | None, int]:
"""Start or verify proxy. Returns (process_handle, actual_port).
@@ -4897,6 +4910,7 @@ def _ensure_proxy_unlocked(
anthropic_api_url=anthropic_api_url,
vertex_api_url=vertex_api_url,
clear_vertex_api_url=clear_vertex_api_url,
factory_api_url=factory_api_url,
)
# Set True when the proxy on the requested port belongs to a persistent
# deployment whose routing config does not match this wrap: the deployment
@@ -5351,6 +5365,7 @@ def _ensure_proxy_unlocked(
copilot_api_token=copilot_api_token,
copilot_refresh_oauth_token=copilot_refresh_oauth_token,
copilot_api_token_expires_at=copilot_api_token_expires_at,
factory_api_url=factory_api_url,
proxy_extensions=proxy_extensions,
),
)
@@ -5366,6 +5381,26 @@ def _ensure_proxy_unlocked(
running_config = _require_no_proxy_openai_upstream(port, openai_api_url)
click.echo(f" Proxy on port {port} already targets {openai_api_url}")
_warn_proxy_mode_mismatch(running_config)
if factory_api_url is not None:
# Droid is pointed at this port unconditionally, so an unverified
# listener would receive its Factory credentials. Require a
# Headroom proxy that serves exactly the requested Factory upstream.
payload = helpers._query_proxy_health(port) if helpers._check_proxy(port) else None
running_config = helpers._proxy_health_config(payload)
if not (
isinstance(payload, dict)
and payload.get("service") == "headroom-proxy"
and running_config is not None
and _normalize_proxy_api_url(
running_config.get("factory_api_url"), strip_provider_v1=False
)
== _normalize_proxy_api_url(factory_api_url, strip_provider_v1=False)
):
raise click.ClickException(
f"--no-proxy requires a Headroom proxy on port {port} serving Factory "
f"upstream {factory_api_url}; start one with headroom proxy "
f"--factory-api-url {factory_api_url} or omit --no-proxy."
)
elif not helpers._check_proxy(port):
click.echo(f" Warning: No proxy detected on port {port}")
elif (
@@ -5622,6 +5657,7 @@ def _launch_tool(
copilot_api_token: str | None = None,
copilot_refresh_oauth_token: str | None = None,
copilot_api_token_expires_at: float | None = None,
factory_api_url: str | None = None,
configure_launch: Callable[
[int, tuple, dict[str, str], list[str]],
tuple[tuple, dict[str, str], list[str]],
@@ -5665,6 +5701,7 @@ def _launch_tool(
copilot_api_token=copilot_api_token,
copilot_refresh_oauth_token=copilot_refresh_oauth_token,
copilot_api_token_expires_at=copilot_api_token_expires_at,
factory_api_url=factory_api_url,
)
if actual_port != port:
_unregister_proxy_client(port)
@@ -9248,6 +9285,95 @@ def unwrap_omp(port: int, no_stop_proxy: bool) -> None:
click.echo()
# =============================================================================
# Factory Droid
# =============================================================================
@wrap.command(context_settings={"ignore_unknown_options": True})
@_retired_context_tool_option
@proxy_port_option()
@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")
@click.option("--learn", is_flag=True, help="Enable live traffic learning")
@click.option("--memory", is_flag=True, help="Enable persistent cross-session memory")
@click.option(
"--factory-api-url",
default=None,
help=(
"Real Factory upstream the proxy forwards to (default: $FACTORY_API_BASE_URL, "
f"else {DEFAULT_FACTORY_API_URL})"
),
)
@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
@click.option("--prepare-only", is_flag=True, hidden=True)
@click.argument("droid_args", nargs=-1, type=click.UNPROCESSED)
def droid(
port: int,
no_proxy: bool,
learn: bool,
memory: bool,
factory_api_url: str | None,
verbose: bool,
prepare_only: bool,
droid_args: tuple,
) -> None:
"""Launch Factory Droid through Headroom proxy.
\b
Sets FACTORY_API_BASE_URL for the droid process only, pointing it at the
proxy, which forwards to the real Factory upstream. The Anthropic-shaped
/api/llm/a/v1/messages route is compressed; every other /api/* path is
forwarded verbatim (OpenAI-shaped /api/llm/o/* traffic is not compressed
yet). Nothing durable is written: no Droid config, no customModels.
\b
Examples:
headroom wrap droid # Start proxy + droid
headroom wrap droid -- exec "fix the bug" # Non-interactive run
headroom wrap droid --factory-api-url https://factory.example.com
"""
upstream = canonical_factory_api_url(resolve_factory_upstream(factory_api_url))
if upstream is None:
raise click.ClickException(
"Factory upstream must be an http(s) URL with a non-loopback host and no "
"credentials, query or fragment (from --factory-api-url, else "
"FACTORY_API_BASE_URL). If FACTORY_API_BASE_URL still points at a local "
"proxy from an earlier session, unset it."
)
if prepare_only:
click.echo(f"FACTORY_API_BASE_URL={droid_proxy_base_url(port)}")
click.echo(f"upstream={upstream}")
return
droid_bin = shutil.which("droid")
if not droid_bin:
click.echo("Error: 'droid' not found in PATH.")
click.echo("Install Factory Droid: see https://docs.factory.ai")
raise SystemExit(1)
env = os.environ.copy()
env["FACTORY_API_BASE_URL"] = droid_proxy_base_url(port)
env_vars_display = [
f"FACTORY_API_BASE_URL={env['FACTORY_API_BASE_URL']}",
f"Factory upstream: {upstream}",
]
_launch_tool(
binary=droid_bin,
args=droid_args,
env=env,
port=port,
no_proxy=no_proxy,
tool_label="DROID",
env_vars_display=env_vars_display,
learn=learn,
memory=memory,
agent_type="droid",
factory_api_url=upstream,
)
# =============================================================================
# Grok CLI (unwrap)
# =============================================================================
+17
View File
@@ -0,0 +1,17 @@
"""Factory Droid provider integration for `headroom wrap droid`."""
from __future__ import annotations
from .runtime import (
DEFAULT_FACTORY_API_URL,
canonical_factory_api_url,
proxy_base_url,
resolve_factory_upstream,
)
__all__ = [
"DEFAULT_FACTORY_API_URL",
"canonical_factory_api_url",
"proxy_base_url",
"resolve_factory_upstream",
]
+104
View File
@@ -0,0 +1,104 @@
"""Runtime helpers for Factory Droid integration.
``headroom wrap droid`` routes Droid through Headroom by pointing Droid's
Factory gateway at the local proxy via the ``FACTORY_API_BASE_URL`` environment
variable. The proxy compresses the Anthropic-shaped ``/api/llm/a/v1/messages``
inference route and forwards every other Factory ``/api/*`` path verbatim to
the real upstream resolved here. OpenAI-shaped ``/api/llm/o/*`` traffic is
forwarded uncompressed for now.
"""
from __future__ import annotations
import ipaddress
import os
import re
import socket
from urllib.parse import urlsplit, urlunsplit
DEFAULT_FACTORY_API_URL = "https://api.factory.ai"
_DNS_HOST_RE = re.compile(
r"(?=.{1,253}\.?$)"
r"(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)*"
r"[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.?"
)
def _is_valid_host(host: str) -> bool:
"""Return whether `host` is an IP literal or a syntactically valid DNS name."""
try:
ipaddress.ip_address(host.rstrip("."))
except ValueError:
return _DNS_HOST_RE.fullmatch(host) is not None
return True
def _is_self_host(host: str) -> bool:
"""Return whether `host` names this machine (loopback or the unspecified address).
Forwarding there would loop the proxy back to itself when a leftover proxy
address sits in ``FACTORY_API_BASE_URL``.
"""
normalized = host.rstrip(".").lower()
if normalized == "localhost" or normalized.endswith(".localhost"):
return True
try:
address = ipaddress.ip_address(normalized)
except ValueError:
try:
address = ipaddress.ip_address(socket.inet_aton(normalized))
except OSError:
return False
return address.is_loopback or address.is_unspecified
def canonical_factory_api_url(value: object) -> str | None:
"""Return a strict Factory upstream URL, or None when unsafe or malformed.
Only for resolving and validating the upstream; running-vs-requested proxy
comparisons use the wrap module's shared URL normaliser.
"""
if not isinstance(value, str):
return None
try:
parsed = urlsplit(value.strip())
port = parsed.port
except ValueError:
return None
scheme = parsed.scheme.lower()
host = parsed.hostname
if (
scheme not in {"http", "https"}
or not host
or not _is_valid_host(host)
or parsed.username is not None
or parsed.password is not None
or parsed.query
or parsed.fragment
or _is_self_host(host)
):
return None
host = host.lower()
rendered_host = f"[{host}]" if ":" in host else host
if port is not None and not (
(scheme == "http" and port == 80) or (scheme == "https" and port == 443)
):
rendered_host = f"{rendered_host}:{port}"
return urlunsplit((scheme, rendered_host, parsed.path.rstrip("/"), "", ""))
def proxy_base_url(port: int) -> str:
"""Return the local Headroom base URL Droid targets via FACTORY_API_BASE_URL."""
return f"http://127.0.0.1:{port}"
def resolve_factory_upstream(explicit: str | None = None) -> str:
"""Resolve the real Factory upstream the proxy forwards to.
Precedence: an explicit ``--factory-api-url``, then the caller's existing
``FACTORY_API_BASE_URL`` (an enterprise or EU gateway they already use),
then the public default.
"""
candidate = explicit or os.environ.get("FACTORY_API_BASE_URL") or DEFAULT_FACTORY_API_URL
return candidate.strip().rstrip("/")
+8 -3
View File
@@ -25,6 +25,11 @@ _CLAUDE_TEXT_PART_TYPES = frozenset({"text"})
_RESPONSES_TEXT_PART_TYPES = frozenset({"text", "input_text", "output_text"})
_CODEX_RESPONSES_SUFFIX = "/v1/responses"
_CLAUDE_MESSAGES_SUFFIX = "/v1/messages"
# Hermes Studio's scoped proxy prefixes. They live under `/api/`, so a
# Factory-mode proxy must keep every path below them on the normal catch-all.
CODEX_PROXY_PREFIX = "/api/codex-proxy/"
CLAUDE_CODE_PROXY_PREFIX = "/api/claude-code-proxy/"
SCOPED_PATH_PREFIXES = (CODEX_PROXY_PREFIX, CLAUDE_CODE_PROXY_PREFIX)
def build_launch_env(
@@ -76,8 +81,8 @@ def unsupported_provider_error(hermes_args: tuple[str, ...] | list[str]) -> str
def is_scoped_coding_agent_path(path: str) -> bool:
"""Return whether *path* is a Hermes scoped coding-agent endpoint."""
return (path.startswith("/api/codex-proxy/") and path.endswith(_CODEX_RESPONSES_SUFFIX)) or (
path.startswith("/api/claude-code-proxy/") and path.endswith(_CLAUDE_MESSAGES_SUFFIX)
return (path.startswith(CODEX_PROXY_PREFIX) and path.endswith(_CODEX_RESPONSES_SUFFIX)) or (
path.startswith(CLAUDE_CODE_PROXY_PREFIX) and path.endswith(_CLAUDE_MESSAGES_SUFFIX)
)
@@ -105,7 +110,7 @@ def compress_scoped_passthrough_body(
if not model:
return body
if path.startswith("/api/claude-code-proxy/"):
if path.startswith(CLAUDE_CODE_PROXY_PREFIX):
field_name = "messages"
route_name = "claude-code"
else:
+84 -33
View File
@@ -21,6 +21,7 @@ from headroom.providers.codex.live import (
)
from headroom.providers.codex.responses import handle_chatgpt_codex_responses_subpath
from headroom.providers.codex.runtime import resolve_codex_routing
from headroom.providers.hermes import SCOPED_PATH_PREFIXES as HERMES_SCOPED_PATH_PREFIXES
from headroom.providers.model_metadata import (
MODEL_METADATA_LIST_ENDPOINT,
handle_model_metadata_endpoint,
@@ -308,6 +309,46 @@ def _register_openai_image_routes(app: FastAPI, proxy: Any) -> None:
def register_provider_routes(app: FastAPI, proxy: Any) -> None:
"""Register provider-specific proxy endpoints."""
async def _default_passthrough(request: Request, path: str):
"""Catch-all forwarding for paths no provider route claims.
``path`` is the request path without its leading slash, as the
``/{path:path}`` catch-all captures it.
"""
custom_base = request.headers.get("x-headroom-base-url")
if custom_base:
if not await is_safe_upstream_url_async(custom_base):
logger.warning("rejecting unsafe x-headroom-base-url: %r", custom_base)
raise HTTPException(status_code=400, detail="Rejected unsafe upstream base URL")
base_url = custom_base.rstrip("/")
endpoint_name, provider_name = _custom_base_passthrough_telemetry(
request.method,
path,
base_url,
)
return await proxy.handle_passthrough(
request,
base_url,
endpoint_name,
provider_name,
)
normalized_cloudcode_path = normalize_cloudcode_passthrough_path(path)
if normalized_cloudcode_path is not None:
normalize_request_path(request, normalized_cloudcode_path)
return await proxy.handle_passthrough(
request,
_api_target(proxy, "cloudcode"),
)
return await proxy.handle_passthrough(
request,
# The path matters here: this is where unrouted paths land, and
# Copilot's inline completions are one of them (#3076).
_select_passthrough_base_url(proxy, dict(request.headers), request.url.path),
)
async def vertex_publisher_passthrough(request: Request, publisher: str, action: str):
return await proxy.handle_passthrough(
request,
@@ -367,6 +408,48 @@ def register_provider_routes(app: FastAPI, proxy: Any) -> None:
async def bedrock_invoke_stream(request: Request, model_id: str):
return await proxy.handle_bedrock_invoke(request, model_id, stream=True)
# Factory Droid. Registered ONLY when an upstream is configured
# (`--factory-api-url` / FACTORY_TARGET_API_URL, set by `headroom wrap
# droid`). Droid sends everything under `/api/`; nothing outside `/api/`
# ever goes to Factory, so another tool still pointed at this port (a
# leftover Codex/Claude config) keeps its usual upstream and its
# credentials never reach Factory.
factory_api_url = getattr(proxy.config, "factory_api_url", None)
if factory_api_url:
factory_base = factory_api_url.rstrip("/")
@app.post("/api/llm/a/v1/messages")
async def factory_anthropic_messages(request: Request):
# Anthropic-shaped inference: compressed, then forwarded to
# `{factory}/api/llm/a/v1/messages`. A client-sent
# `x-headroom-base-url` is deliberately ignored (the handler strips
# `x-headroom-*`), and Factory is not a trusted host, so operator
# Anthropic extra headers are withheld. `force_direct` keeps a
# configured translating backend or route advice from taking it.
return await proxy.handle_anthropic_messages(
request,
upstream_base_url=factory_base,
provider_name="factory",
force_direct=True,
)
@app.api_route(
"/api/{path:path}", methods=["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]
)
async def factory_passthrough(request: Request, path: str):
# Hermes Studio's scoped proxies and callers that name their own
# upstream are not Droid traffic: keep the catch-all behaviour.
if request.headers.get(
"x-headroom-base-url", ""
).strip() or request.url.path.startswith(HERMES_SCOPED_PATH_PREFIXES):
return await _default_passthrough(request, request.url.path[1:])
# Factory REST (and, for now, OpenAI-shaped `/api/llm/o/*`):
# verbatim and buffered, even with `compress_passthrough` on. No
# endpoint name, so no LLM telemetry.
return await proxy.handle_passthrough(
request, factory_base, None, "factory", verbatim=True
)
_register_openai_responses_routes(app, proxy)
_register_provider_handler_routes(app, proxy)
@@ -615,36 +698,4 @@ def register_provider_routes(app: FastAPI, proxy: Any) -> None:
@app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE", "HEAD"])
async def passthrough(request: Request, path: str):
custom_base = request.headers.get("x-headroom-base-url")
if custom_base:
if not await is_safe_upstream_url_async(custom_base):
logger.warning("rejecting unsafe x-headroom-base-url: %r", custom_base)
raise HTTPException(status_code=400, detail="Rejected unsafe upstream base URL")
base_url = custom_base.rstrip("/")
endpoint_name, provider_name = _custom_base_passthrough_telemetry(
request.method,
path,
base_url,
)
return await proxy.handle_passthrough(
request,
base_url,
endpoint_name,
provider_name,
)
normalized_cloudcode_path = normalize_cloudcode_passthrough_path(path)
if normalized_cloudcode_path is not None:
normalize_request_path(request, normalized_cloudcode_path)
return await proxy.handle_passthrough(
request,
_api_target(proxy, "cloudcode"),
)
return await proxy.handle_passthrough(
request,
# The path matters here: this is where unrouted paths land, and
# Copilot's inline completions are one of them (#3076).
_select_passthrough_base_url(proxy, dict(request.headers), request.url.path),
)
return await _default_passthrough(request, path)
+17 -4
View File
@@ -1313,8 +1313,15 @@ class AnthropicHandlerMixin:
provider_name: str = "anthropic",
model_override: str | None = None,
force_stream: bool = False,
force_direct: bool = False,
) -> Response | StreamingResponse:
"""Handle Anthropic /v1/messages endpoint."""
"""Handle Anthropic /v1/messages endpoint.
``force_direct`` forwards over HTTP to ``upstream_base_url`` without
consulting the backend resolver: neither ``self.anthropic_backend``
nor route advice can take the request (or rewrite ``body["model"]``).
Used by routes whose upstream is fixed, such as Factory.
"""
if not hasattr(self, "pipeline_extensions"):
from headroom.pipeline import PipelineExtensionManager
@@ -4175,7 +4182,10 @@ class AnthropicHandlerMixin:
str(model)
if (
not upstream_base_url
or getattr(self, "anthropic_backend", None) is not None
or (
getattr(self, "anthropic_backend", None) is not None
and not force_direct
)
or _is_googleapis_endpoint(upstream_base_url)
)
else None
@@ -4250,10 +4260,13 @@ class AnthropicHandlerMixin:
# it names a provider we do not already speak, serve this ONE
# request from a translating backend for it. Absent, unresolvable,
# or same-protocol -> `self.anthropic_backend`, i.e. exactly the
# behaviour this line had before.
# behaviour this line had before. `force_direct` skips the
# resolver entirely: the caller's upstream is the only target.
from headroom.proxy.route_advice import resolver_for
request_backend = resolver_for(self).for_request(request, body=body)
request_backend = (
None if force_direct else resolver_for(self).for_request(request, body=body)
)
if request_backend is not None:
# Route through Bedrock backend
try:
+5 -1
View File
@@ -12227,6 +12227,7 @@ class OpenAIHandlerMixin:
endpoint_name: str | None = None,
provider: str | None = None,
*,
verbatim: bool = False,
_upstream_request: httpx.Request | None = None,
_model: str | None = None,
_start_time: float | None = None,
@@ -12238,6 +12239,8 @@ class OpenAIHandlerMixin:
base_url: The upstream API base URL
endpoint_name: Optional name for stats tracking (e.g., "models", "embeddings")
provider: Optional provider name for stats (e.g., "openai", "anthropic", "gemini")
verbatim: Skip the opt-in ``compress_passthrough`` Responses
compressor, so the body reaches the upstream unchanged.
"""
from fastapi.responses import Response
@@ -12339,7 +12342,8 @@ class OpenAIHandlerMixin:
# the exact same ContentRouter/Kompress path the native handler runs.
_pt_config = getattr(self, "config", None)
if (
not soft_passthrough
not verbatim
and not soft_passthrough
and getattr(_pt_config, "compress_passthrough", False)
and getattr(_pt_config, "optimize", False)
and request.method == "POST"
+6
View File
@@ -192,6 +192,12 @@ class ProxyConfig:
# SigV4 signature. Leave unset (default) to keep `--backend bedrock`'s
# direct-to-AWS, re-signing behavior unchanged.
bedrock_api_url: str | None = None
# Factory Droid upstream (`--factory-api-url` / FACTORY_TARGET_API_URL).
# When set, `/api/llm/a/v1/messages` is compressed and forwarded here and
# every other `/api/*` path is passed through verbatim; it serves `/api/*`
# only and never becomes the catch-all upstream. Leave unset (default) to
# keep `/api/*` on the normal catch-all.
factory_api_url: str | None = None
anyllm_provider: str = "openai"
# Optimization mode: "token" (rewrite for max compression) or
+11
View File
@@ -4062,6 +4062,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
"gemini_api_url": config.gemini_api_url,
"cloudcode_api_url": config.cloudcode_api_url,
"vertex_api_url": config.vertex_api_url,
"factory_api_url": config.factory_api_url,
"savings_profile": config.savings_profile,
# Enabled extension names only (no plugin state): `headroom
# wrap` carries them over when it has to start a dedicated
@@ -6667,6 +6668,7 @@ def _proxy_config_from_env() -> ProxyConfig:
bedrock_region=_get_env_str("HEADROOM_BEDROCK_REGION", "us-west-2"),
bedrock_profile=os.environ.get("AWS_PROFILE"),
bedrock_api_url=os.environ.get("BEDROCK_TARGET_API_URL"),
factory_api_url=os.environ.get("FACTORY_TARGET_API_URL"),
anyllm_provider=_get_env_str("HEADROOM_ANYLLM_PROVIDER", "openai"),
disable_kompress=_get_env_bool("HEADROOM_DISABLE_KOMPRESS", False),
disable_kompress_fallback=_get_env_bool("HEADROOM_DISABLE_KOMPRESS_FALLBACK", False),
@@ -7199,6 +7201,14 @@ if __name__ == "__main__":
"(env: BEDROCK_TARGET_API_URL)"
),
)
parser.add_argument(
"--factory-api-url",
help=(
"Factory Droid upstream for /api/* — /api/llm/a/v1/messages is "
"compressed, other /api/* paths pass through "
"(env: FACTORY_TARGET_API_URL)"
),
)
parser.add_argument(
"--openrouter-api-key",
help="OpenRouter API key (or set OPENROUTER_API_KEY env var)",
@@ -7501,6 +7511,7 @@ if __name__ == "__main__":
bedrock_region=_get_env_str("HEADROOM_BEDROCK_REGION", args.bedrock_region),
bedrock_profile=args.bedrock_profile or os.environ.get("AWS_PROFILE"),
bedrock_api_url=_get_env_str("BEDROCK_TARGET_API_URL", args.bedrock_api_url),
factory_api_url=_get_env_str("FACTORY_TARGET_API_URL", args.factory_api_url),
anyllm_provider=_get_env_str("HEADROOM_ANYLLM_PROVIDER", args.anyllm_provider),
optimize=optimize,
min_tokens_to_crush=_get_env_int("HEADROOM_MIN_TOKENS", args.min_tokens),
+1 -1
View File
@@ -21,7 +21,7 @@ The canonical, always-current documentation index lives at the docs site below.
- TypeScript / Node: `npm install headroom-ai` (or `pnpm add headroom-ai`, `bun add headroom-ai`)
- Docker local: `docker run --rm -p 127.0.0.1:8787:8787 ghcr.io/headroomlabs-ai/headroom:latest --host 0.0.0.0`
- Run the proxy: `headroom proxy --port 8787` then point any client at `http://127.0.0.1:8787`
- Wrap an agent in one command: `headroom wrap claude` (also: `codex`, `grok`, `copilot`, `cursor`, `aider`, `opencode`, `cline`, `continue`, `goose`, `openhands`, `openclaw`, `vibe`, `omp`, `zcode`)
- Wrap an agent in one command: `headroom wrap claude` (also: `codex`, `grok`, `copilot`, `cursor`, `aider`, `opencode`, `cline`, `continue`, `goose`, `openhands`, `openclaw`, `vibe`, `omp`, `zcode`, `droid`)
- Zero-network check, no provider key: `HEADROOM_OFFLINE=1 python -c "from headroom import compress; log='\n'.join(f'INFO step {i} ok' for i in range(3000))+'\nFATAL disk full'; r=compress([{'role':'user','content':'What failed?'},{'role':'assistant','content':None,'tool_calls':[{'id':'c1','type':'function','function':{'name':'logs','arguments':'{}'}}]},{'role':'tool','tool_call_id':'c1','content':log}], model='gpt-4o'); print(r.tokens_before, '->', r.tokens_after, 'FATAL kept:', 'FATAL' in str(r.messages))"` (prints roughly `20000 -> 95 FATAL kept: True`)
## By task (plain-language jobs this package does)
+331
View File
@@ -0,0 +1,331 @@
"""Tests for ``headroom wrap droid`` (Factory Droid).
The command points Droid's ``FACTORY_API_BASE_URL`` at the local proxy and
starts (or reuses) a proxy whose ``factory_api_url`` is the real Factory
upstream. Nothing durable is written. Every proxy/launch seam is patched, so
no proxy starts and no Droid binary runs.
"""
from __future__ import annotations
import subprocess
from typing import Any
import click
import pytest
from click.testing import CliRunner
import headroom.cli.wrap as wrap_cli
from headroom.cli.main import main
FACTORY = "https://api.factory.ai"
OTHER_FACTORY = "https://eu.factory.example"
@pytest.fixture(autouse=True)
def _hermetic(monkeypatch: pytest.MonkeyPatch, tmp_path) -> None:
monkeypatch.chdir(tmp_path)
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / ".headroom"))
for name in (
"FACTORY_API_BASE_URL",
"FACTORY_TARGET_API_URL",
"ANTHROPIC_TARGET_API_URL",
"OPENAI_TARGET_API_URL",
"GEMINI_TARGET_API_URL",
"CLOUDCODE_TARGET_API_URL",
"VERTEX_TARGET_API_URL",
"AUGMENT_TARGET_API_URL",
"HEADROOM_BACKEND",
):
monkeypatch.delenv(name, raising=False)
monkeypatch.setattr(wrap_cli, "_live_proxy_clients", lambda *a, **kw: [])
monkeypatch.setattr(wrap_cli, "_find_persistent_manifest", lambda port: None)
def _boom(message: str):
def _raise(*args: Any, **kwargs: Any):
raise AssertionError(message)
return _raise
def _invoke(args: list[str], env: dict[str, str] | None = None):
return CliRunner().invoke(main, ["wrap", "droid", *args], env=env)
# ── command: env, precedence, rejection, missing binary ───────────────
def test_launch_env_points_droid_at_proxy(monkeypatch: pytest.MonkeyPatch) -> None:
captured: dict[str, Any] = {}
monkeypatch.setattr(wrap_cli.shutil, "which", lambda name: "/usr/bin/droid")
monkeypatch.setattr(wrap_cli, "_launch_tool", lambda **kw: captured.update(kw))
result = _invoke(["--port", "8787", "--", "exec", "hi"])
assert result.exit_code == 0, result.output
assert captured["binary"] == "/usr/bin/droid"
assert captured["args"] == ("exec", "hi")
assert captured["env"]["FACTORY_API_BASE_URL"] == "http://127.0.0.1:8787"
assert captured["factory_api_url"] == FACTORY
assert captured["agent_type"] == "droid"
assert captured["tool_label"] == "DROID"
def test_fallback_port_rewrites_child_env(monkeypatch: pytest.MonkeyPatch) -> None:
captured: dict[str, Any] = {}
ensure_kwargs: dict[str, Any] = {}
def _ensure(port: int, no_proxy: bool, **kwargs: Any):
ensure_kwargs.update(kwargs)
return None, 8799
def _run(cmd: list[str], env: dict[str, str]):
captured["cmd"] = cmd
captured["env"] = env
return subprocess.CompletedProcess(cmd, 0)
monkeypatch.setattr(wrap_cli.shutil, "which", lambda name: "/usr/bin/droid")
monkeypatch.setattr(wrap_cli, "_ensure_proxy", _ensure)
monkeypatch.setattr(wrap_cli, "_push_runtime_env", lambda *a, **kw: None)
monkeypatch.setattr(wrap_cli.subprocess, "run", _run)
result = _invoke(["--port", "8787"])
assert result.exit_code == 0, result.output
assert captured["env"]["FACTORY_API_BASE_URL"] == "http://127.0.0.1:8799"
assert ensure_kwargs["factory_api_url"] == FACTORY
@pytest.mark.parametrize(
("args", "env", "expected"),
[
([], {}, FACTORY),
([], {"FACTORY_API_BASE_URL": "https://EU.factory.example/"}, OTHER_FACTORY),
(
["--factory-api-url", "https://flag.factory.example"],
{"FACTORY_API_BASE_URL": OTHER_FACTORY},
"https://flag.factory.example",
),
],
)
def test_upstream_precedence(args: list[str], env: dict[str, str], expected: str) -> None:
result = _invoke([*args, "--port", "8787", "--prepare-only"], env=env)
assert result.exit_code == 0, result.output
assert "FACTORY_API_BASE_URL=http://127.0.0.1:8787" in result.output
assert f"upstream={expected}" in result.output
@pytest.mark.parametrize(
("args", "env"),
[
(["--factory-api-url", "http://127.0.0.1:8787"], {}),
([], {"FACTORY_API_BASE_URL": "http://127.0.0.1:8787"}),
(["--factory-api-url", "http://localhost:9000"], {}),
(["--factory-api-url", "https://user:pw@api.factory.ai"], {}),
(["--factory-api-url", "https://api.factory.ai?x=1"], {}),
(["--factory-api-url", "https://api.factory.ai#frag"], {}),
],
)
def test_rejected_upstreams_never_launch(
monkeypatch: pytest.MonkeyPatch, args: list[str], env: dict[str, str]
) -> None:
monkeypatch.setattr(wrap_cli.shutil, "which", lambda name: "/usr/bin/droid")
monkeypatch.setattr(wrap_cli, "_launch_tool", _boom("must not launch"))
monkeypatch.setattr(wrap_cli, "_ensure_proxy", _boom("must not start a proxy"))
result = _invoke([*args, "--port", "8787"], env=env)
assert result.exit_code != 0
assert "FACTORY_API_BASE_URL" in result.output
def test_missing_binary_exits_before_proxy_work(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setattr(wrap_cli.shutil, "which", lambda name: None)
monkeypatch.setattr(wrap_cli, "_ensure_proxy", _boom("must not ensure a proxy"))
monkeypatch.setattr(wrap_cli, "_start_proxy", _boom("must not start a proxy"))
result = _invoke(["--port", "8787"])
assert result.exit_code == 1
assert "'droid' not found" in result.output
# ── proxy routing plumbing ────────────────────────────────────────────
def test_requested_routing_uses_explicit_factory(monkeypatch: pytest.MonkeyPatch) -> None:
kwargs = {
"backend": None,
"openai_api_url": None,
"anthropic_api_url": None,
"vertex_api_url": None,
"clear_vertex_api_url": False,
}
_, urls = wrap_cli._effective_requested_proxy_routing(**kwargs, factory_api_url=FACTORY)
assert urls["factory_api_url"] == FACTORY
monkeypatch.setenv("FACTORY_TARGET_API_URL", OTHER_FACTORY)
_, urls = wrap_cli._effective_requested_proxy_routing(**kwargs)
assert urls["factory_api_url"] == OTHER_FACTORY
_, urls = wrap_cli._effective_requested_proxy_routing(**kwargs, factory_api_url=FACTORY)
assert urls["factory_api_url"] == FACTORY
def test_start_proxy_forwards_factory_flag_and_env(monkeypatch: pytest.MonkeyPatch, tmp_path):
captured: dict[str, Any] = {}
class _Proc:
returncode = None
def poll(self):
return None
def _popen(cmd, **kwargs):
captured["cmd"] = cmd
captured["env"] = kwargs["env"]
return _Proc()
monkeypatch.setattr(wrap_cli, "_get_log_path", lambda port=None: tmp_path / "proxy.log")
monkeypatch.setattr(
wrap_cli, "_get_proxy_stdio_log_path", lambda port=None: tmp_path / "stdio.log"
)
monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: True)
monkeypatch.setattr(wrap_cli.subprocess, "Popen", _popen)
wrap_cli._start_proxy(8787, agent_type="droid", factory_api_url=FACTORY)
cmd = captured["cmd"]
assert cmd[cmd.index("--factory-api-url") + 1] == FACTORY
assert captured["env"]["FACTORY_TARGET_API_URL"] == FACTORY
def _health(config: dict[str, Any], *, sessions: int = 0) -> dict[str, Any]:
return {
"service": "headroom-proxy",
"version": wrap_cli._HEADROOM_VERSION,
"runtime": {"websocket_sessions": {"active_sessions": sessions, "active_relay_tasks": 0}},
"config": {"pid": 4242, "backend": "anthropic", **config},
}
def test_idle_non_factory_proxy_is_restarted_in_factory_mode(
monkeypatch: pytest.MonkeyPatch,
) -> None:
calls: list[Any] = []
monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: True)
monkeypatch.setattr(wrap_cli, "_query_proxy_health", lambda port: _health({}))
monkeypatch.setattr(
wrap_cli, "_kill_proxy_by_pid", lambda pid, port: calls.append(("kill", pid)) or True
)
monkeypatch.setattr(wrap_cli, "_find_available_port", lambda start, **kw: start)
monkeypatch.setattr(
wrap_cli, "_start_proxy", lambda port, **kw: calls.append(("start", port, kw))
)
assert wrap_cli._ensure_proxy(8787, False, factory_api_url=FACTORY) == (None, 8787)
assert calls[0] == ("kill", 4242)
assert calls[1][0] == "start"
assert calls[1][1] == 8787
assert calls[1][2]["factory_api_url"] == FACTORY
def test_attached_non_factory_proxy_pushes_droid_to_dedicated_port(
monkeypatch: pytest.MonkeyPatch,
) -> None:
calls: list[Any] = []
monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: True)
monkeypatch.setattr(wrap_cli, "_query_proxy_health", lambda port: _health({}))
monkeypatch.setattr(wrap_cli, "_live_proxy_clients", lambda *a, **kw: [{"pid": 1}])
monkeypatch.setattr(wrap_cli, "_kill_proxy_by_pid", _boom("attached proxy must survive"))
monkeypatch.setattr(
wrap_cli,
"_find_available_port",
lambda start, **kw: calls.append(("find", start)) or 8799,
)
monkeypatch.setattr(
wrap_cli, "_start_proxy", lambda port, **kw: calls.append(("start", port, kw))
)
assert wrap_cli._ensure_proxy(8787, False, factory_api_url=FACTORY) == (None, 8799)
assert calls[0] == ("find", 8787)
assert calls[1][1] == 8799
assert calls[1][2]["factory_api_url"] == FACTORY
def test_matching_factory_proxy_is_reused(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: True)
monkeypatch.setattr(
wrap_cli,
"_query_proxy_health",
lambda port: _health({"factory_api_url": f"{FACTORY}/"}),
)
monkeypatch.setattr(wrap_cli, "_kill_proxy_by_pid", _boom("must reuse"))
monkeypatch.setattr(wrap_cli, "_find_available_port", _boom("must reuse"))
monkeypatch.setattr(wrap_cli, "_start_proxy", _boom("must reuse"))
assert wrap_cli._ensure_proxy(8787, False, factory_api_url=FACTORY) == (None, 8787)
# ── --no-proxy ────────────────────────────────────────────────────────
_NO_PROXY_REFUSALS = {
"no-listener": (False, None),
"foreign-service": (
True,
{"service": "something-else", "config": {"factory_api_url": FACTORY}},
),
"config-less": (True, {"service": "headroom-proxy"}),
"non-factory": (True, _health({})),
"other-factory": (True, _health({"factory_api_url": OTHER_FACTORY})),
}
@pytest.mark.parametrize("case", sorted(_NO_PROXY_REFUSALS))
def test_no_proxy_refuses_unverified_listener(monkeypatch: pytest.MonkeyPatch, case: str) -> None:
listening, payload = _NO_PROXY_REFUSALS[case]
monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: listening)
monkeypatch.setattr(wrap_cli, "_query_proxy_health", lambda port: payload)
monkeypatch.setattr(wrap_cli, "_query_proxy_config", lambda port: None)
with pytest.raises(click.ClickException, match="--no-proxy requires a Headroom proxy"):
wrap_cli._ensure_proxy(8787, True, factory_api_url=FACTORY)
@pytest.mark.parametrize("case", sorted(_NO_PROXY_REFUSALS))
def test_no_proxy_refusal_never_launches_droid(monkeypatch: pytest.MonkeyPatch, case: str) -> None:
listening, payload = _NO_PROXY_REFUSALS[case]
monkeypatch.setattr(wrap_cli.shutil, "which", lambda name: "/usr/bin/droid")
monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: listening)
monkeypatch.setattr(wrap_cli, "_query_proxy_health", lambda port: payload)
monkeypatch.setattr(wrap_cli, "_query_proxy_config", lambda port: None)
monkeypatch.setattr(wrap_cli.subprocess, "run", _boom("droid must not launch"))
result = _invoke(["--port", "8787", "--no-proxy"])
assert result.exit_code != 0
assert "--no-proxy requires a Headroom proxy" in result.output
def test_no_proxy_matching_factory_launches(monkeypatch: pytest.MonkeyPatch) -> None:
captured: dict[str, Any] = {}
def _run(cmd: list[str], env: dict[str, str]):
captured["env"] = env
return subprocess.CompletedProcess(cmd, 0)
monkeypatch.setattr(wrap_cli.shutil, "which", lambda name: "/usr/bin/droid")
monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: True)
monkeypatch.setattr(
wrap_cli, "_query_proxy_health", lambda port: _health({"factory_api_url": FACTORY})
)
monkeypatch.setattr(wrap_cli, "_push_runtime_env", lambda *a, **kw: None)
monkeypatch.setattr(wrap_cli, "_start_proxy", _boom("--no-proxy must not start a proxy"))
monkeypatch.setattr(wrap_cli.subprocess, "run", _run)
result = _invoke(["--port", "8787", "--no-proxy"])
assert result.exit_code == 0, result.output
assert captured["env"]["FACTORY_API_BASE_URL"] == "http://127.0.0.1:8787"
+87
View File
@@ -0,0 +1,87 @@
"""Tests for the Factory Droid runtime helpers behind ``headroom wrap droid``."""
from __future__ import annotations
import pytest
from headroom.providers.droid import (
DEFAULT_FACTORY_API_URL,
canonical_factory_api_url,
proxy_base_url,
resolve_factory_upstream,
)
@pytest.fixture(autouse=True)
def _no_inherited_factory_env(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.delenv("FACTORY_API_BASE_URL", raising=False)
def test_default_upstream_is_public_factory() -> None:
assert DEFAULT_FACTORY_API_URL == "https://api.factory.ai"
assert resolve_factory_upstream(None) == DEFAULT_FACTORY_API_URL
def test_env_beats_default(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setenv("FACTORY_API_BASE_URL", "https://eu.factory.example/")
assert resolve_factory_upstream(None) == "https://eu.factory.example"
def test_explicit_flag_beats_env(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setenv("FACTORY_API_BASE_URL", "https://eu.factory.example")
assert resolve_factory_upstream("https://flag.factory.example") == (
"https://flag.factory.example"
)
def test_proxy_base_url_is_loopback_without_v1() -> None:
assert proxy_base_url(8799) == "http://127.0.0.1:8799"
@pytest.mark.parametrize(
("raw", "expected"),
[
("https://API.Factory.AI", "https://api.factory.ai"),
("https://api.factory.ai/", "https://api.factory.ai"),
("https://api.factory.ai:443", "https://api.factory.ai"),
("http://gw.example:80/", "http://gw.example"),
("https://gw.example:8443/factory/", "https://gw.example:8443/factory"),
(" https://api.factory.ai ", "https://api.factory.ai"),
("https://[2001:db8::1]:8443", "https://[2001:db8::1]:8443"),
],
)
def test_canonicalisation(raw: str, expected: str) -> None:
assert canonical_factory_api_url(raw) == expected
@pytest.mark.parametrize(
"raw",
[
# loopback, in every spelling that reaches this host
"http://127.0.0.1:8787",
"http://localhost:8787",
"http://LOCALHOST",
"http://x.localhost",
"http://[::1]:8787",
"http://127.1:8787",
"http://0.0.0.0:8787",
# credentials, query, fragment
"https://user:pw@api.factory.ai",
"https://user@api.factory.ai",
"https://api.factory.ai?x=1",
"https://api.factory.ai#frag",
# schemes and malformed values
"ftp://api.factory.ai",
"file:///etc/passwd",
"api.factory.ai",
"https://",
"https://api.factory.ai:99999",
"https://api.factory.ai:notaport",
"https://bad_host!.example",
"",
None,
42,
],
)
def test_rejections(raw: object) -> None:
assert canonical_factory_api_url(raw) is None
@@ -0,0 +1,346 @@
"""Local decoy proof for Factory Droid routing, over real sockets.
Two local HTTP servers stand in for the outside world:
* a **decoy**, configured as the proxy's Anthropic and OpenAI upstream (and
allowlisted as a client-named base), which must stay silent for every
Factory-bound request, and
* a **Factory stand-in**, configured as ``factory_api_url``, which must
receive Droid's inference request and its non-inference REST calls.
The proxy runs under a real uvicorn server. ``headroom wrap droid --no-proxy``
then probes real listeners and either refuses or launches a fake ``droid``
executable. Nothing here contacts Factory or needs a Factory token.
"""
from __future__ import annotations
import json
import os
import signal
import socket
import stat
import sys
import threading
import time
from collections.abc import Iterator
from dataclasses import dataclass, field
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from typing import Any
import pytest
pytest.importorskip("fastapi")
httpx = pytest.importorskip("httpx")
uvicorn = pytest.importorskip("uvicorn")
from click.testing import CliRunner # noqa: E402
from headroom.cli.main import main # noqa: E402
from headroom.proxy.server import ProxyConfig, create_app # noqa: E402
MESSAGES = "/api/llm/a/v1/messages"
UNCONTACTED_FACTORY = "https://factory.invalid"
def _free_port() -> int:
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
sock.bind(("127.0.0.1", 0))
return int(sock.getsockname()[1])
@dataclass
class _Seen:
method: str
path: str
headers: dict[str, str]
body: bytes
@dataclass
class _Upstream:
name: str
server: ThreadingHTTPServer
seen: list[_Seen] = field(default_factory=list)
@property
def url(self) -> str:
return f"http://127.0.0.1:{self.server.server_address[1]}"
def _start_upstream(name: str) -> _Upstream:
upstream: _Upstream
class _Handler(BaseHTTPRequestHandler):
def _serve(self) -> None:
length = int(self.headers.get("content-length") or 0)
body = self.rfile.read(length) if length else b""
upstream.seen.append(
_Seen(
self.command,
self.path,
{k.lower(): v for k, v in self.headers.items()},
body,
)
)
if self.path.split("?")[0].endswith("/v1/messages"):
reply: dict[str, Any] = {
"id": "msg_1",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-4-5",
"content": [{"type": "text", "text": f"from {name}"}],
"stop_reason": "end_turn",
"usage": {"input_tokens": 10, "output_tokens": 3},
}
else:
reply = {"served_by": name, "path": self.path}
payload = json.dumps(reply).encode()
self.send_response(200)
self.send_header("content-type", "application/json")
self.send_header("content-length", str(len(payload)))
self.end_headers()
self.wfile.write(payload)
do_GET = do_POST = do_PATCH = do_PUT = do_DELETE = _serve
def log_message(self, *args: Any) -> None:
pass
server = ThreadingHTTPServer(("127.0.0.1", 0), _Handler)
server.daemon_threads = True
upstream = _Upstream(name, server)
threading.Thread(target=server.serve_forever, daemon=True).start()
return upstream
class _ProxyThread:
def __init__(self, config: ProxyConfig) -> None:
self.port = _free_port()
config.port = self.port
self.server = uvicorn.Server(
uvicorn.Config(
create_app(config),
host="127.0.0.1",
port=self.port,
log_level="warning",
loop="asyncio",
lifespan="on",
ws="none",
)
)
self.thread = threading.Thread(target=self.server.run, daemon=True)
@property
def url(self) -> str:
return f"http://127.0.0.1:{self.port}"
def start(self) -> None:
self.thread.start()
deadline = time.perf_counter() + 30.0
while time.perf_counter() < deadline:
if self.server.started:
return
time.sleep(0.05)
raise RuntimeError("proxy failed to start within 30s")
def stop(self) -> None:
self.server.should_exit = True
self.thread.join(timeout=10.0)
def _config(**overrides: Any) -> ProxyConfig:
base: dict[str, Any] = {
"optimize": True,
"cache_enabled": False,
"rate_limit_enabled": False,
"cost_tracking_enabled": False,
"log_requests": False,
}
base.update(overrides)
return ProxyConfig(**base)
@dataclass
class _Stack:
decoy: _Upstream
factory: _Upstream
factory_proxy: _ProxyThread
plain_proxy: _ProxyThread
uncontacted_factory_proxy: _ProxyThread
@pytest.fixture
def stack(monkeypatch: pytest.MonkeyPatch, tmp_path) -> Iterator[_Stack]:
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / ".headroom"))
# Allowlist the loopback decoy as a client-named base, so a spoofed
# x-headroom-base-url pointing at it would pass the SSRF guard if it were
# honoured. The decoy staying silent then proves the route ignores it.
monkeypatch.setenv("HEADROOM_ALLOWED_BASE_URLS", "127.0.0.1")
for name in ("FACTORY_API_BASE_URL", "FACTORY_TARGET_API_URL"):
monkeypatch.delenv(name, raising=False)
saved_signals = {
sig: signal.getsignal(sig)
for sig in (signal.SIGINT, signal.SIGTERM, getattr(signal, "SIGHUP", None))
if sig is not None
}
decoy = _start_upstream("decoy")
factory = _start_upstream("factory")
# Provider targets are process-wide, so every in-process proxy gets the
# decoy; otherwise the last one created would reset them to the public
# defaults and stray traffic would leave the machine.
decoy_targets = {"anthropic_api_url": decoy.url, "openai_api_url": decoy.url}
proxies = [
_ProxyThread(_config(factory_api_url=factory.url, **decoy_targets)),
_ProxyThread(_config(**decoy_targets)),
_ProxyThread(_config(factory_api_url=UNCONTACTED_FACTORY, **decoy_targets)),
]
try:
for proxy in proxies:
proxy.start()
yield _Stack(decoy, factory, *proxies)
finally:
for proxy in proxies:
proxy.stop()
decoy.server.shutdown()
factory.server.shutdown()
for sig, handler in saved_signals.items():
signal.signal(sig, handler)
def test_inference_reaches_factory_stand_in_and_decoy_stays_silent(stack: _Stack) -> None:
body = {
"model": "claude-sonnet-4-5",
"max_tokens": 16,
"messages": [{"role": "user", "content": "lorem ipsum dolor " * 400}],
}
response = httpx.post(
f"{stack.factory_proxy.url}{MESSAGES}",
headers={
"authorization": "Bearer fk-local-dummy",
"anthropic-version": "2023-06-01",
# Spoofed Headroom control headers: none may redirect the request.
"x-headroom-base-url": stack.decoy.url,
"x-headroom-provider": "openai",
"x-headroom-target": stack.decoy.url,
},
json=body,
timeout=60,
)
assert response.status_code == 200, response.text
assert response.json()["content"][0]["text"] == "from factory"
assert stack.decoy.seen == []
[seen] = stack.factory.seen
assert (seen.method, seen.path) == ("POST", MESSAGES)
assert seen.headers["authorization"] == "Bearer fk-local-dummy"
assert not [k for k in seen.headers if k.startswith("x-headroom-")]
def test_non_inference_factory_paths_pass_through(stack: _Stack) -> None:
get = httpx.get(
f"{stack.factory_proxy.url}/api/sessions?limit=5",
headers={"authorization": "Bearer fk-local-dummy"},
timeout=30,
)
patch = httpx.patch(
f"{stack.factory_proxy.url}/api/sessions/s1",
headers={"authorization": "Bearer fk-local-dummy"},
content=b'{"title":"x"}',
timeout=30,
)
assert get.json() == {"served_by": "factory", "path": "/api/sessions?limit=5"}
assert patch.json()["served_by"] == "factory"
assert [(s.method, s.path) for s in stack.factory.seen] == [
("GET", "/api/sessions?limit=5"),
("PATCH", "/api/sessions/s1"),
]
assert stack.factory.seen[1].body == b'{"title":"x"}'
assert stack.decoy.seen == []
def test_unmatched_traffic_never_reaches_factory(stack: _Stack) -> None:
unrouted = httpx.get(
f"{stack.factory_proxy.url}/totally/unrouted",
headers={"authorization": "Bearer sk-other-tool"},
timeout=30,
)
hermes = httpx.post(
f"{stack.factory_proxy.url}/api/codex-proxy/s1/v1/responses",
headers={"authorization": "Bearer sk-hermes"},
json={"model": "gpt-4o-mini", "input": "hi"},
timeout=30,
)
assert unrouted.json()["served_by"] == "decoy"
assert hermes.json()["served_by"] == "decoy"
assert stack.factory.seen == []
assert [s.path for s in stack.decoy.seen] == [
"/totally/unrouted",
"/api/codex-proxy/s1/v1/responses",
]
@pytest.fixture
def fake_droid(tmp_path, monkeypatch: pytest.MonkeyPatch):
record = tmp_path / "droid-env.txt"
bin_dir = tmp_path / "bin"
bin_dir.mkdir()
script = bin_dir / "droid"
script.write_text(f'#!/bin/sh\nprintf "%s" "$FACTORY_API_BASE_URL" > "{record}"\n')
script.chmod(script.stat().st_mode | stat.S_IXUSR)
if sys.platform == "win32":
# `shutil.which("droid")` ignores the extensionless script on Windows
# but finds `droid.cmd` via PATHEXT. Python does the write so the
# record has no trailing newline, matching `printf "%s"`.
write = (
"import os, pathlib, sys; "
"pathlib.Path(sys.argv[1]).write_text(os.environ.get('FACTORY_API_BASE_URL', ''))"
)
(bin_dir / "droid.cmd").write_bytes(
f'@echo off\r\n"{sys.executable}" -c "{write}" "{record}"\r\n'.encode()
)
monkeypatch.setenv("PATH", f"{bin_dir}{os.pathsep}{os.environ.get('PATH', '')}")
return record
def _wrap_droid_no_proxy(port: int, upstream: str):
return CliRunner().invoke(
main,
["wrap", "droid", "--no-proxy", "--port", str(port), "--factory-api-url", upstream],
)
def test_no_proxy_refuses_non_factory_listener(stack: _Stack, fake_droid) -> None:
result = _wrap_droid_no_proxy(stack.plain_proxy.port, UNCONTACTED_FACTORY)
assert result.exit_code != 0
assert "--no-proxy requires a Headroom proxy" in result.output
assert not fake_droid.exists()
def test_no_proxy_refuses_mismatched_factory_listener(stack: _Stack, fake_droid) -> None:
result = _wrap_droid_no_proxy(
stack.uncontacted_factory_proxy.port, "https://eu.factory.example"
)
assert result.exit_code != 0
assert "--no-proxy requires a Headroom proxy" in result.output
assert not fake_droid.exists()
def test_no_proxy_refuses_absent_listener(stack: _Stack, fake_droid) -> None:
result = _wrap_droid_no_proxy(_free_port(), UNCONTACTED_FACTORY)
assert result.exit_code != 0
assert not fake_droid.exists()
def test_no_proxy_launches_against_matching_listener(stack: _Stack, fake_droid) -> None:
port = stack.uncontacted_factory_proxy.port
result = _wrap_droid_no_proxy(port, f"{UNCONTACTED_FACTORY}/")
assert result.exit_code == 0, result.output
assert fake_droid.read_text() == f"http://127.0.0.1:{port}"
@@ -0,0 +1,531 @@
"""Tests for the Factory Droid routes registered when ``factory_api_url`` is set.
``headroom wrap droid`` points Droid's ``FACTORY_API_BASE_URL`` at the proxy.
With a Factory upstream configured, the proxy:
1. compresses ``POST /api/llm/a/v1/messages`` and forwards it to
``{factory}/api/llm/a/v1/messages`` (never to a client-named base);
2. forwards every other ``/api/*`` request verbatim to the Factory upstream,
except Hermes Studio's scoped prefixes and requests that name their own
``x-headroom-base-url``, which keep the normal catch-all behaviour;
3. never sends traffic outside ``/api/*`` to Factory (the leak guard).
Forwarding is intercepted with ``respx`` so no real upstream is contacted.
"""
from __future__ import annotations
import json
import runpy
import sys
from typing import Any
from unittest.mock import AsyncMock, MagicMock, patch
from urllib.parse import urlsplit
import pytest
fastapi = pytest.importorskip("fastapi")
httpx = pytest.importorskip("httpx")
respx = pytest.importorskip("respx")
from fastapi.testclient import TestClient # noqa: E402
from headroom.proxy.loopback_guard import require_loopback # noqa: E402
from headroom.proxy.server import ProxyConfig, create_app # noqa: E402
UPSTREAM = "https://factory.example"
UPSTREAM_HOST = "factory.example"
GATEWAY = "https://gateway.example"
MESSAGES = "/api/llm/a/v1/messages"
@pytest.fixture(autouse=True)
def _allow_reserved_test_upstream(monkeypatch: pytest.MonkeyPatch) -> None:
"""Admit the reserved, intentionally unresolvable client-named gateway."""
monkeypatch.setenv("HEADROOM_ALLOWED_BASE_URLS", "gateway.example")
monkeypatch.delenv("FACTORY_TARGET_API_URL", raising=False)
class _FakeResult:
"""Stand-in for TransformPipeline.apply's TransformResult."""
def __init__(self, messages: list[dict], tokens_before: int, tokens_after: int) -> None:
self.messages = messages
self.tokens_before = tokens_before
self.tokens_after = tokens_after
self.transforms_applied = ["smartcrush"]
self.timing = {"total": 1.0}
def _make_config(**overrides: Any) -> ProxyConfig:
base: dict[str, Any] = {
"factory_api_url": UPSTREAM,
"optimize": True,
"cache_enabled": False,
"rate_limit_enabled": False,
"cost_tracking_enabled": False,
"log_requests": False,
"mode": "token",
}
base.update(overrides)
return ProxyConfig(**base)
def _make_app(**overrides: Any):
app = create_app(_make_config(**overrides))
app.dependency_overrides[require_loopback] = lambda: None
return app
def _anthropic_reply() -> dict[str, Any]:
return {
"id": "msg_1",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-4-5",
"content": [{"type": "text", "text": "ok"}],
"stop_reason": "end_turn",
"usage": {"input_tokens": 10, "output_tokens": 1},
}
# Hosts the proxy contacts on its own at startup (pricing table fetch,
# subscription usage poll with the machine's own credentials); unrelated to
# the request under test.
_BACKGROUND_HOSTS = frozenset({"raw.githubusercontent.com", "api.anthropic.com"})
class _Recorder:
"""Capture every upstream request the proxy makes, on any host."""
def __init__(self) -> None:
self.requests: list[httpx.Request] = []
def __call__(self, request: httpx.Request) -> httpx.Response:
self.requests.append(request)
if request.url.path.endswith("/v1/messages"):
return httpx.Response(200, json=_anthropic_reply())
return httpx.Response(200, json={"ok": True, "path": request.url.path})
def to_host(self, host: str) -> list[httpx.Request]:
return [r for r in self.requests if r.url.host == host]
def proxied(self) -> list[httpx.Request]:
"""Requests forwarded on a client's behalf, minus proxy startup polls."""
return [r for r in self.requests if r.url.host not in _BACKGROUND_HOSTS]
def only(self, path: str) -> httpx.Request:
hits = [r for r in self.requests if r.url.path == path]
assert len(hits) == 1, [str(r.url) for r in self.requests]
return hits[0]
@pytest.fixture
def recorder():
rec = _Recorder()
with respx.mock(assert_all_called=False) as router:
router.route().mock(side_effect=rec)
yield rec
def _big_messages_body() -> dict[str, Any]:
return {
"model": "claude-sonnet-4-5",
"max_tokens": 16,
"messages": [{"role": "user", "content": "lorem ipsum " * 600}],
}
# ── route gating ──────────────────────────────────────────────────────
def _paths(cfg: ProxyConfig) -> list[str]:
return [r.path for r in create_app(cfg).routes if hasattr(r, "path")]
def test_routes_absent_when_factory_api_url_unset():
paths = _paths(ProxyConfig())
assert MESSAGES not in paths
assert "/api/{path:path}" not in paths
def test_routes_present_and_ordered_before_catch_all():
paths = _paths(_make_config())
assert MESSAGES in paths
assert "/api/{path:path}" in paths
assert paths.index(MESSAGES) < paths.index("/api/{path:path}")
assert paths.index("/api/{path:path}") < paths.index("/{path:path}")
# ── inference route ───────────────────────────────────────────────────
def test_messages_route_compresses_and_reaches_factory(recorder):
app = _make_app()
with TestClient(app) as client:
proxy = client.app.state.proxy
proxy._record_request_outcome = AsyncMock()
compressed = [{"role": "user", "content": "compressed"}]
proxy.anthropic_pipeline.apply = MagicMock(return_value=_FakeResult(compressed, 900, 100))
response = client.post(
MESSAGES,
headers={"authorization": "Bearer fk-test", "anthropic-version": "2023-06-01"},
json=_big_messages_body(),
)
assert response.status_code == 200, response.text
sent = recorder.only(MESSAGES)
assert str(sent.url) == f"{UPSTREAM}{MESSAGES}"
assert sent.headers["authorization"] == "Bearer fk-test"
assert json.loads(sent.content)["messages"] == compressed
assert proxy.anthropic_pipeline.apply.called
outcome = proxy._record_request_outcome.await_args.args[0]
assert outcome.provider == "factory"
def test_messages_route_bypasses_configured_backend_and_route_advice(recorder):
"""A translating backend (HEADROOM_BACKEND=bedrock, route advice) must not
swallow Factory inference: the route never consults the resolver."""
from headroom.backends.base import BackendResponse
from headroom.proxy.route_advice import BackendResolver
backend_calls: list[Any] = []
class _SentinelBackend:
name = "sentinel"
async def send_message(self, body: dict, headers: dict) -> BackendResponse:
backend_calls.append(body)
return BackendResponse(body={"error": "teapot"}, status_code=418)
resolver_calls: list[Any] = []
def _no_resolver(self: Any, request: Any, **kwargs: Any) -> Any:
resolver_calls.append(request)
raise AssertionError("Factory route consulted the backend resolver")
app = _make_app()
with (
TestClient(app) as client,
patch.object(BackendResolver, "for_request", _no_resolver),
):
proxy = client.app.state.proxy
proxy.anthropic_backend = _SentinelBackend()
compressed = [{"role": "user", "content": "compressed"}]
proxy.anthropic_pipeline.apply = MagicMock(return_value=_FakeResult(compressed, 900, 100))
response = client.post(
MESSAGES,
headers={"authorization": "Bearer fk-test", "anthropic-version": "2023-06-01"},
json=_big_messages_body(),
)
assert response.status_code == 200, response.text
assert backend_calls == []
assert resolver_calls == []
sent = recorder.only(MESSAGES)
assert sent.url.host == UPSTREAM_HOST
assert json.loads(sent.content)["messages"] == compressed
assert proxy.anthropic_pipeline.apply.called
def test_spoofed_headroom_headers_do_not_redirect_inference(recorder):
app = _make_app()
with TestClient(app) as client:
response = client.post(
MESSAGES,
headers={
"authorization": "Bearer fk-test",
"anthropic-version": "2023-06-01",
"x-headroom-base-url": "http://evil.example",
"x-headroom-provider": "openai",
"x-headroom-bypass": "true",
},
json=_big_messages_body(),
)
assert response.status_code == 200, response.text
assert [r.url.host for r in recorder.proxied()] == [UPSTREAM_HOST]
assert not recorder.to_host("evil.example")
sent = recorder.only(MESSAGES)
assert not [k for k in sent.headers if k.lower().startswith("x-headroom-")]
assert sent.headers["authorization"] == "Bearer fk-test"
def test_operator_extra_headers_withheld_from_factory(recorder):
app = _make_app(anthropic_extra_headers={"x-gateway-secret": "s3cret"})
with TestClient(app) as client:
response = client.post(
MESSAGES,
headers={"authorization": "Bearer fk-test", "anthropic-version": "2023-06-01"},
json=_big_messages_body(),
)
assert response.status_code == 200, response.text
sent = recorder.only(MESSAGES)
assert "x-gateway-secret" not in {k.lower() for k in sent.headers}
# ── REST passthrough ──────────────────────────────────────────────────
def test_rest_get_passes_through_with_query_and_auth(recorder):
app = _make_app()
with TestClient(app) as client:
response = client.get(
"/api/sessions?limit=5",
headers={"authorization": "Bearer fk-test"},
)
assert response.status_code == 200, response.text
sent = recorder.only("/api/sessions")
assert str(sent.url) == f"{UPSTREAM}/api/sessions?limit=5"
assert sent.headers["authorization"] == "Bearer fk-test"
def test_rest_patch_passes_through_byte_identical(recorder):
app = _make_app()
payload = b'{"title":"renamed"}'
with TestClient(app) as client:
response = client.patch(
"/api/sessions/s1",
headers={"authorization": "Bearer fk-test", "content-type": "application/json"},
content=payload,
)
assert response.status_code == 200, response.text
sent = recorder.only("/api/sessions/s1")
assert sent.method == "PATCH"
assert sent.url.host == UPSTREAM_HOST
assert sent.content == payload
def test_responses_passthrough_stays_verbatim_with_compress_passthrough(recorder):
"""`compress_passthrough` must not rewrite Droid's OpenAI-shaped traffic."""
app = _make_app(compress_passthrough=True)
payload = b'{"model":"gpt-5","input":"' + b"lorem ipsum " * 600 + b'"}'
with TestClient(app) as client:
proxy = client.app.state.proxy
proxy._maybe_compress_passthrough_responses = AsyncMock(return_value=b'{"rewritten":1}')
response = client.post(
"/api/llm/o/v1/responses",
headers={"authorization": "Bearer fk-test", "content-type": "application/json"},
content=payload,
)
assert response.status_code == 200, response.text
proxy._maybe_compress_passthrough_responses.assert_not_called()
sent = recorder.only("/api/llm/o/v1/responses")
assert sent.url.host == UPSTREAM_HOST
assert sent.content == payload
def test_compress_passthrough_still_applies_to_unrelated_catch_all(recorder):
"""Control: without Factory, the generic catch-all still compresses."""
app = create_app(
ProxyConfig(
optimize=True,
compress_passthrough=True,
cache_enabled=False,
rate_limit_enabled=False,
log_requests=False,
)
)
app.dependency_overrides[require_loopback] = lambda: None
path = "/api/llm/o/v1/responses"
with TestClient(app) as client:
proxy = client.app.state.proxy
proxy._maybe_compress_passthrough_responses = AsyncMock(return_value=b'{"rewritten":1}')
response = client.post(
path,
headers={"authorization": "Bearer sk-x", "content-type": "application/json"},
content=b'{"model":"gpt-5","input":"hi"}',
)
assert response.status_code == 200, response.text
proxy._maybe_compress_passthrough_responses.assert_awaited_once()
sent = recorder.only(path)
assert sent.url.host != UPSTREAM_HOST
assert sent.content == b'{"rewritten":1}'
# ── leak guard: unmatched traffic must never go to Factory ────────────
@pytest.mark.parametrize(
("method", "path", "headers", "expected_host"),
[
("GET", "/backend-api/me", {"chatgpt-account-id": "acct"}, "chatgpt.com"),
("POST", "/v1/engines/x/completions", {"authorization": "Bearer tid_fake_copilot"}, None),
(
"POST",
"/v1beta/models/m:generateContent",
{"x-goog-api-key": "g-key"},
"generativelanguage.googleapis.com",
),
(
"POST",
"/api/codex-proxy/s1/v1/responses",
{"authorization": "Bearer sk-hermes"},
"api.openai.com",
),
(
"POST",
"/api/codex-proxy/s1/other",
{"authorization": "Bearer sk-hermes"},
"api.openai.com",
),
(
"POST",
"/api/claude-code-proxy/s1/v1/messages",
{"authorization": "Bearer sk-hermes", "x-headroom-base-url": GATEWAY},
"gateway.example",
),
(
"GET",
"/api/anything",
{"authorization": "Bearer other", "x-headroom-base-url": GATEWAY},
"gateway.example",
),
("GET", "/totally/unrouted", {"authorization": "Bearer sk-x"}, "api.openai.com"),
],
)
def test_non_factory_traffic_never_reaches_factory(
recorder, method: str, path: str, headers: dict[str, str], expected_host: str | None
):
app = _make_app()
with TestClient(app) as client:
body = {"model": "m", "input": "hi"} if method == "POST" else None
client.request(method, path, headers=headers, json=body)
forwarded = [r for r in recorder.requests if urlsplit(str(r.url)).path.endswith(path)]
assert forwarded, [str(r.url) for r in recorder.requests]
assert not recorder.to_host(UPSTREAM_HOST), [str(r.url) for r in recorder.requests]
if expected_host is not None:
assert forwarded[0].url.host == expected_host
def test_unsafe_client_base_on_api_path_is_still_rejected(recorder):
app = _make_app()
with TestClient(app) as client:
response = client.get(
"/api/anything",
headers={"x-headroom-base-url": "http://169.254.169.254"},
)
assert response.status_code == 400
assert recorder.proxied() == []
# ── guard: unchanged behaviour without Factory configured ─────────────
def test_without_factory_messages_path_falls_through_to_catch_all(recorder):
app = create_app(
ProxyConfig(
optimize=True, cache_enabled=False, rate_limit_enabled=False, log_requests=False
)
)
app.dependency_overrides[require_loopback] = lambda: None
with TestClient(app) as client:
response = client.post(
MESSAGES,
headers={"authorization": "Bearer fk-test"},
json=_big_messages_body(),
)
assert response.status_code == 200, response.text
sent = recorder.only(MESSAGES)
assert sent.url.host != UPSTREAM_HOST
assert sent.url.host == "api.openai.com"
# ── config plumbing ───────────────────────────────────────────────────
def _loopback_client(app) -> TestClient:
return TestClient(app, base_url="http://127.0.0.1", client=("127.0.0.1", 12345))
def test_health_reports_factory_api_url():
app = _make_app()
with _loopback_client(app) as client:
payload = client.get("/health").json()
assert payload["config"]["factory_api_url"] == UPSTREAM
def test_health_reports_none_without_factory():
app = create_app(ProxyConfig())
with _loopback_client(app) as client:
payload = client.get("/health").json()
assert payload["config"]["factory_api_url"] is None
def test_env_var_feeds_config(monkeypatch):
from headroom.proxy.server import _proxy_config_from_env
monkeypatch.delenv("HEADROOM_PROXY_CONFIG_JSON", raising=False)
monkeypatch.setenv("FACTORY_TARGET_API_URL", UPSTREAM)
assert _proxy_config_from_env().factory_api_url == UPSTREAM
class _Captured(Exception):
pass
def test_standalone_argparse_flag_feeds_config(monkeypatch):
"""``python -m headroom.proxy.server --factory-api-url`` populates ProxyConfig."""
from headroom.proxy import models
real = models.ProxyConfig
seen: dict[str, Any] = {}
def _capture(*args: Any, **kwargs: Any):
if "factory_api_url" in kwargs:
seen.update(kwargs)
raise _Captured
return real(*args, **kwargs)
monkeypatch.setattr(sys, "argv", ["server", "--factory-api-url", UPSTREAM])
monkeypatch.setattr(models, "ProxyConfig", _capture)
with pytest.raises(_Captured):
runpy.run_module("headroom.proxy.server", run_name="__main__")
assert seen["factory_api_url"] == UPSTREAM
def test_cli_proxy_flag_feeds_config():
from click.testing import CliRunner
from headroom.cli.main import main
captured: dict[str, Any] = {}
def _run_server(config, **kwargs):
captured["config"] = config
with patch("headroom.proxy.server.run_server", _run_server):
result = CliRunner().invoke(
main, ["proxy", "--factory-api-url", UPSTREAM], catch_exceptions=False
)
assert result.exit_code == 0, result.output
assert captured["config"].factory_api_url == UPSTREAM
assert "Factory Droid" in result.output
def test_cli_proxy_env_feeds_config():
from click.testing import CliRunner
from headroom.cli.main import main
captured: dict[str, Any] = {}
def _run_server(config, **kwargs):
captured["config"] = config
with patch("headroom.proxy.server.run_server", _run_server):
result = CliRunner().invoke(
main, ["proxy"], env={"FACTORY_TARGET_API_URL": UPSTREAM}, catch_exceptions=False
)
assert result.exit_code == 0, result.output
assert captured["config"].factory_api_url == UPSTREAM