mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
docs: correct Antigravity IDE setup instructions (no third-party model providers) (#4258)
## Description Follow-up to the merged #3817. As flagged in the post-merge thread, the Antigravity IDE doesn’t expose third-party model-provider settings, so the setup text was telling users to add a custom model provider in a panel that doesn’t exist. The instructions now describe what the integration actually covers (MCP registration and the `/v1internal:streamGenerateContent` endpoint for `google-antigravity` clients) and distinguish the IDE from the Antigravity CLI (`agy`), which is the surface that accepts a custom endpoint via `GOOGLE_GEMINI_BASE_URL`. Follow-up fix (Devin review on this PR): the `agy` note mentioned `GOOGLE_GEMINI_BASE_URL` but only printed the OpenAI-compatible URL. It now prints the Gemini-compatible base URL (scheme://host, the Gemini API convention) as an explicit `GOOGLE_GEMINI_BASE_URL=...` assignment, and the OpenAI block is labeled for OpenAI-speaking clients. ## Type of Change - [ ] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom wrap antigravity` help text and printed setup instructions no longer reference IDE model-provider settings; they point at MCP registration and the native endpoint, and name the CLI separately. - The `agy` note now shows the Gemini-compatible base URL explicitly (`GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:<port>`), with the project prefix (`/p/<name>`) applied like the other URLs. - `docs/content/docs/proxy.mdx` Antigravity section corrected the same way. - Tests updated to assert the corrected wording. ## Testing - [x] Unit tests pass (`pytest`) ### Test Output ```text $ pytest tests/test_provider_antigravity.py -q 12 passed, 1 warning in 2.07s $ pytest tests/test_mcp_registry/test_antigravity_registrar.py -q 25 passed, 1 warning in 0.82s ``` (`test_cli/test_wrap_antigravity.py` was not run locally — `typer` is not installed in this environment; CI covers it.) ## Real Behavior Proof - Environment: docs/string-only change; no runtime behavior affected. - What was checked: the removed claim ("add a custom OpenAI-compatible model provider in Antigravity’s model-provider settings") was verified false three ways — the reporter’s own `~/.gemini/settings.json` has no model-provider keys; Antigravity IDE 2.5.5 exposes no third-party model-provider settings panel (upstream report plus current docs); and the `google-antigravity` clients the new text names really do speak Cloud Code Assist (`POST /v1internal:streamGenerateContent` is served by the proxy — see `CLOUDCODE_HANDLER_ROUTES` in `route_specs.py`). - Observed result: `render_setup_lines(8787)` now prints the corrected IDE/MCP/native-traffic text, `GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:8787` for `agy`, and the OpenAI block labeled for OpenAI-speaking clients; the 37 tests above pass. - Not tested: a live Antigravity IDE run — no Mac with the IDE installed in this environment, and nothing in this change touches a runtime path, so there is no behavior to smoke-test. ## Runtime Rollout Safety - Rollout-managed feature(s): none — documentation/strings only. - Minimum rollout channel: n/a. - Stable/default behavior changed: no; rendered CLI text only. - Kill switch / disable path: n/a. - Unsafe override required: n/a. - Qualification impact: none. - Rollback path: revert the commit. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project’s style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing 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) ## Additional Notes Docs-only PR; the remaining `wrap` CLI test module is covered by CI. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4258" 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-dark.svg?v=4" alt="Devin Review"></picture></a> <!-- devin-review-badge-end -->
This commit is contained in:
@@ -528,16 +528,21 @@ headroom wrap antigravity # Start proxy + print Antigravity setup instr
|
||||
headroom mcp install --agent antigravity # Register the Headroom MCP server in Antigravity
|
||||
```
|
||||
|
||||
`wrap antigravity` prints a custom OpenAI-compatible model-provider base URL
|
||||
to add in Antigravity's model-provider settings; Antigravity fetches the model
|
||||
list from `GET /v1/models` on its own. Native Cloud Code Assist traffic
|
||||
(`google-antigravity` clients) is accepted on
|
||||
[`POST /v1internal:streamGenerateContent`](#post-v1internalstreamgeneratecontent)
|
||||
and routed upstream like any other Cloud Code request.
|
||||
The Antigravity IDE does not support third-party model providers — its
|
||||
agent models are Google-managed, so there is no settings panel to point
|
||||
at the proxy. What the proxy does offer Antigravity users:
|
||||
|
||||
MCP registration writes to Antigravity's global `mcp_config.json` under
|
||||
`~/.gemini/` (preferring the install's current location when one already
|
||||
exists) and refuses to overwrite a config file that does not parse as JSON.
|
||||
- MCP tools: `mcp install` writes the Headroom server into Antigravity's
|
||||
global `mcp_config.json` under `~/.gemini/` (preferring the install's
|
||||
current location when one already exists) and refuses to overwrite a
|
||||
config file that does not parse as JSON.
|
||||
- Native traffic: `google-antigravity` clients are accepted on
|
||||
[`POST /v1internal:streamGenerateContent`](#post-v1internalstreamgeneratecontent)
|
||||
and routed upstream like any other Cloud Code request.
|
||||
|
||||
The Antigravity CLI (`agy`), unlike the IDE, accepts a custom endpoint
|
||||
via its `GOOGLE_GEMINI_BASE_URL` setting — the one Antigravity surface
|
||||
where a custom model endpoint is supported.
|
||||
|
||||
### `POST /v1/compress`
|
||||
|
||||
|
||||
+8
-10
@@ -7905,21 +7905,19 @@ def antigravity(
|
||||
verbose: bool,
|
||||
prepare_only: bool,
|
||||
) -> None:
|
||||
"""Start Headroom proxy for use with Antigravity IDE.
|
||||
"""Start Headroom proxy for use with the Antigravity IDE.
|
||||
|
||||
\b
|
||||
Antigravity reads its model endpoints from its model-provider settings,
|
||||
not from environment variables. This command starts the proxy and prints
|
||||
the settings to add as a custom OpenAI-compatible model provider.
|
||||
|
||||
\b
|
||||
After running this command, open Antigravity and add a custom model
|
||||
provider with the printed base URL. Antigravity fetches the model list
|
||||
from GET /v1/models automatically.
|
||||
The Antigravity IDE does not support third-party model providers —
|
||||
its agent models are Google-managed. This command starts the proxy
|
||||
and prints what the integration actually covers: MCP server
|
||||
registration (`headroom mcp install --agent antigravity`) and the
|
||||
native `POST /v1internal:streamGenerateContent` endpoint for
|
||||
`google-antigravity` clients.
|
||||
|
||||
\b
|
||||
Example:
|
||||
headroom wrap antigravity # Start proxy + Antigravity settings
|
||||
headroom wrap antigravity # Start proxy + Antigravity setup
|
||||
headroom wrap antigravity --port 9999 # Custom proxy port
|
||||
"""
|
||||
if prepare_only:
|
||||
|
||||
@@ -22,9 +22,9 @@ def build_proxy_targets(port: int, project: str | None = None) -> AntigravityPro
|
||||
"""Build the local proxy URLs shown to Antigravity users.
|
||||
|
||||
``project`` (the wrap launch directory) is encoded as a ``/p/<name>``
|
||||
base-URL prefix because Antigravity's custom model-provider settings
|
||||
cannot send custom headers; the proxy strips it and attributes savings
|
||||
per project.
|
||||
base-URL prefix because clients pointing at these URLs cannot be
|
||||
counted on to send custom headers; the proxy strips it and attributes
|
||||
savings per project.
|
||||
"""
|
||||
return AntigravityProxyTargets(
|
||||
openai_base_url=with_project_prefix(codex_proxy_base_url(port), project),
|
||||
@@ -35,17 +35,32 @@ def build_proxy_targets(port: int, project: str | None = None) -> AntigravityPro
|
||||
def render_setup_lines(port: int, project: str | None = None) -> list[str]:
|
||||
"""Render the Antigravity setup instructions for the local proxy."""
|
||||
targets = build_proxy_targets(port, project)
|
||||
# The Gemini-compatible base URL (scheme://host; Gemini clients append
|
||||
# /v1beta/...) — the one agy expects for GOOGLE_GEMINI_BASE_URL.
|
||||
gemini_base_url = with_project_prefix(f"http://127.0.0.1:{port}", project)
|
||||
lines = [
|
||||
" Headroom proxy is running. Configure Antigravity:",
|
||||
" Headroom proxy is running. Antigravity setup:",
|
||||
"",
|
||||
" Antigravity reads model endpoints from its model-provider settings,",
|
||||
" not from environment variables. Add a custom OpenAI-compatible",
|
||||
" model provider pointing at the proxy:",
|
||||
" The Antigravity IDE does not support third-party model providers —",
|
||||
" its agent models are Google-managed, so there is no settings panel",
|
||||
" to point at the proxy. What the proxy does offer Antigravity users:",
|
||||
"",
|
||||
" - MCP tools: `headroom mcp install --agent antigravity` registers",
|
||||
" the Headroom MCP server in Antigravity's global mcp_config.json.",
|
||||
" - Native traffic: the proxy accepts `google-antigravity` client",
|
||||
" traffic on POST /v1internal:streamGenerateContent, routed",
|
||||
" upstream like any other Cloud Code request.",
|
||||
"",
|
||||
" The Antigravity CLI (agy), unlike the IDE, accepts a custom",
|
||||
" endpoint via its GOOGLE_GEMINI_BASE_URL setting — point it at",
|
||||
" the proxy's Gemini-compatible base URL:",
|
||||
"",
|
||||
f" GOOGLE_GEMINI_BASE_URL={gemini_base_url}",
|
||||
"",
|
||||
" For OpenAI-speaking clients, the proxy's OpenAI-compatible",
|
||||
" base URL is:",
|
||||
"",
|
||||
f" Base URL: {targets.openai_base_url}",
|
||||
" API Key: your-openai-api-key",
|
||||
"",
|
||||
" Antigravity fetches the model list from GET /v1/models automatically,",
|
||||
" so there is nothing else to register.",
|
||||
]
|
||||
return lines + project_attribution_lines(project)
|
||||
|
||||
@@ -17,11 +17,12 @@ def test_wrap_help_lists_antigravity() -> None:
|
||||
assert "antigravity" in result.output
|
||||
|
||||
|
||||
def test_wrap_antigravity_help_mentions_custom_model_provider() -> None:
|
||||
def test_wrap_antigravity_help_says_ide_has_no_third_party_providers() -> None:
|
||||
result = CliRunner().invoke(main, ["wrap", "antigravity", "--help"])
|
||||
assert result.exit_code == 0, result.output
|
||||
assert "Antigravity" in result.output
|
||||
assert "OpenAI-compatible" in result.output
|
||||
assert "does not support third-party model providers" in result.output
|
||||
assert "custom OpenAI-compatible model provider" not in result.output
|
||||
|
||||
|
||||
def test_wrap_antigravity_prepare_only_exits_cleanly() -> None:
|
||||
|
||||
@@ -56,10 +56,16 @@ def test_antigravity_render_setup_lines_contains_proxy_url() -> None:
|
||||
assert "Antigravity" in joined
|
||||
|
||||
|
||||
def test_antigravity_render_setup_lines_mentions_custom_provider() -> None:
|
||||
def test_antigravity_setup_lines_do_not_claim_ide_provider_settings() -> None:
|
||||
joined = "\n".join(render_setup_lines(8787))
|
||||
assert "OpenAI-compatible" in joined
|
||||
assert "/v1/models" in joined
|
||||
assert "does not support third-party model providers" in joined
|
||||
assert "Add a custom OpenAI-compatible" not in joined
|
||||
assert "model-provider settings" not in joined
|
||||
assert "mcp install --agent antigravity" in joined
|
||||
assert "/v1internal:streamGenerateContent" in joined
|
||||
assert "GOOGLE_GEMINI_BASE_URL" in joined
|
||||
assert "GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:8787" in joined
|
||||
assert "For OpenAI-speaking clients" in joined
|
||||
|
||||
|
||||
def test_antigravity_render_setup_lines_project_attribution() -> None:
|
||||
|
||||
Reference in New Issue
Block a user