Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

docs(antigravity): document the raw model list command

Jack Rudenko9637b8486a04
diff --git a/ai-docs/architecture/providers/antigravity.md b/ai-docs/architecture/providers/antigravity.md
index 31e1d770..b377db6e 100644
--- a/ai-docs/architecture/providers/antigravity.md
+++ b/ai-docs/architecture/providers/antigravity.md
@@ -199,3 +199,132 @@ That rule now governs only the fallback list. When the backend sends
**Model ids — LIVE discovery, no hardcoded map**: the Antigravity backend requires a reasoning-tier suffix (bare `gemini-3.6-flash` → 404), but which variants a subscription serves is **per-account and drifts**, so claudish never hardcodes a model list. `getServedAntigravityModels()` fetches the live set from the backend's own `v1internal:fetchAvailableModels` (body `{project}`) — the served ids are the response `models` keys, plus a backend `defaultAgentModelId` — cached with a TTL. `resolveAntigravityModelId(requested, servedIds, defaultId)` then resolves against that LIVE set: exact match passes through; a bare family (e.g. `gemini-3.6-flash`) resolves to the backend's `defaultAgentModelId` when it's a variant of that family, else to the strongest reasoning tier by a *rank rule* (`high>medium>low>extra-low>tiered` — a rule, like `rankCodeAssistModel`, not pinned ids); anything else passes through to the F1–F7 404 rewrite. The only literals are the tier-rank ordering and endpoint strings — no concrete model ids in source.
**Identity strings**: `User-Agent: antigravity/cli/<ver> (aidev_client; os_type=<platform>; arch=<arch>; auth_method=consumer)` + `metadata: { ideType: "ANTIGRAVITY" }`. The transport keeps all the F1–F7 improvements from the old codeassist path (terminal-error → 400 surfaced inline, the 404 rewrite that checks the dynamic models catalog, `rankCodeAssistModel`). Full reverse-engineering write-up: `ai-docs/sessions/antigravity-refactor-20260803-125333-d0791562/architecture.md` (write-up lost — predates the ai-docs tracking fix).
+
+## Raw model list for models-index (`claudish subscription models antigravity --raw --json`)
+
+**Why it exists.** The models-index catalog publishes no exact connections on route
+`google/antigravity-subscription`, so a bare `gemini-4-argon` routes to the metered Gemini API.
+The models-index wire-probe runner (a nightly macOS LaunchAgent with no TTY and no browser) runs this
+command, uploads stdout, and seals the body as evidence for the connections it publishes. Code:
+`subscription-models-command.ts`.
+
+**It reuses the `ag@` path; it does not copy it.**
+- `readAntigravityStoreClassified` is the bounded keychain read.
+- `getValidAntigravityAccessToken` (with observed deps) refreshes through `agy models` when the
+ token is expired.
+- `setupAntigravityUser` resolves the project.
+- `fetchAntigravityAvailableModelsRaw` returns the body BEFORE any processing.
+ `getServedAntigravityModels` calls the same function and processes its result: exclusions,
+ displayName, `agentModelSorts`. There is no cache, so every run is a live fetch.
+
+`--raw` and `--json` are both required in v1. Each of these is a usage error:
+- a missing flag;
+- the `ag` shortcut in place of `antigravity`;
+- an extra token.
+
+A usage error exits 2, with stdout empty and one fixed usage line on stderr. The bare form is
+kept free for a later human view.
+
+### Schema `claudish.subscription-model-list.v1`
+
+Exactly one JSON object on ONE stdout line, keys in this order:
+
+```
+schema, provider ("antigravity"), claudishVersion,
+fetchedAt?, sourceUrl?, clientVersion?, clientVersionSource?,
+tokenRefreshed, httpStatus?, failure?, body?
+```
+
+**Field-presence rule:** a field appears exactly when this run determined it.
+
+| Field | Present when |
+|---|---|
+| `tokenRefreshed` | always. True when this run asked agy to refresh, even if that refresh failed |
+| `clientVersion`, `clientVersionSource` | a valid token was obtained. The value is the version in the User-Agent actually sent. `"fallback"` means the 1.1.9 floor, which hides every `gemini-4-argon-*` id |
+| `sourceUrl` | `fetchAvailableModels` was attempted. It is `antigravityHost()` (honours `AICODE_ENDPOINT_URL`) with any userinfo stripped |
+| `fetchedAt`, `httpStatus` | `fetchAvailableModels` answered with a status |
+| `body` | success only. It is the 2xx body, verbatim: `JSON.parse`, then `JSON.stringify`, so values and key order are kept |
+| `failure` | `{ class, code, httpStatus? }`. Each is a fixed string, with no error text |
+
+A non-2xx `fetchAvailableModels` answer is **not a failure**: exit 0, with `httpStatus` and no `body`.
+
+### Failure taxonomy and exit codes
+
+| Class | `code` | Exit |
+|---|---|---|
+| — (success, or a non-2xx answer) | — | 0 |
+| `credential_missing` | `platform_unsupported`, `keychain_item_absent`, `token_unparseable` | 3 |
+| `keychain_locked` | `keychain_locked` (security exit 36/51/128), `keychain_read_timeout` (10 s), `keychain_read_failed` (any other exit) | 4 |
+| `mint_failed` | `agy_missing`, `agy_refresh_failed`, `agy_refresh_timeout`, `agy_refresh_no_valid_token` | 5 |
+| `mint_failed` | `load_code_assist_4xx` (with `httpStatus`), `load_code_assist_no_project`, `load_code_assist_bad_body` | 5 |
+| `network` | `load_code_assist_429`, `load_code_assist_5xx` (with `httpStatus`), `load_code_assist_network_error`, `load_code_assist_timeout` (30 s) | 6 |
+| `network` | `fetch_available_models_network_error` (unreachable, or a 2xx body that could not be read), `fetch_available_models_timeout` (30 s abort) | 6 |
+| `list_incomplete` | `models_absent`, `models_empty`, `body_not_json` (all 2xx, with `httpStatus`) | 7 |
+| outside the contract | usage error | 2, stdout empty |
+| outside the contract | internal error, or the secret guard tripped | 1, stdout empty, one fixed stderr line |
+
+A `loadCodeAssist` 429 or 5xx is `network`, not `mint_failed`: it is transient
+(`credential-error.ts`).
+
+A refresh failure is classified from what the run OBSERVED, never from message text. The command
+records whether `runAgyRefresh` was called, and its `AgyRefreshOutcome`:
+- No refresh was called: `token_unparseable`.
+- `not-installed`, `timeout` or `failed`: the matching `agy_*` code.
+- `ran`, but the re-read token is still stale: `agy_refresh_no_valid_token`.
+
+### Keychain lock handling
+
+`defaultReadStore` maps every `security` failure to null, so a locked keychain reads as "not signed
+in", and it has no deadline. The command uses `readAntigravityStoreClassified(10 s)` instead.
+
+**Step 1, presence.** `find-generic-password` without `-w` reads no item data.
+- Exit 44 is `absent`.
+- It is NOT a lock probe: on a locked temporary keychain it answered exit 0 with the full attribute
+ dump (measured 2026-10-21).
+
+**Step 2, the value read (`-w`).** This is the step a locked keychain refuses. Measured on a locked
+temporary keychain: exit **128** (errSecUserCanceled), empty stderr, after 1.5 s, and no call left
+running. `security` exits with the low byte of the negated OSStatus:
+- 44 (errSecItemNotFound) is measured.
+- 36 (errSecInteractionNotAllowed) and 51 (errSecAuthFailed) are derived from the same arithmetic.
+
+All three map to `keychain_locked`.
+
+Both steps race one 10 s deadline. **`security` is never killed** (keychain.md: a killed `security`
+once made macOS restart `securityd`). A LaunchAgent in the Aqua session may get a real unlock dialog.
+Then the deadline reports `keychain_read_timeout`, the dialog is left to the user, and the command
+exits explicitly, because the unkilled child would otherwise keep the event loop alive.
+
+The pre-read value is handed to the token module as its first `readStore` answer, so that module
+never spawns an unbounded read of its own. The one re-read after a refresh uses the default
+synchronous read, which has no deadline. This is accepted and recorded as risk R4 of the design.
+
+### LaunchAgent PATH
+
+`locateAgyBinary()` runs `which agy`, then `~/.local/bin/agy`. launchd's default PATH has no
+Homebrew prefix. An `agy` installed only under `/opt/homebrew/bin` is therefore invisible to a
+LaunchAgent, with two effects:
+- the version reads as `clientVersionSource: "fallback"`;
+- an expired token fails as `agy_missing`.
+
+**The plist must set PATH** to include the directory `agy` lives in.
+
+### Secret guard
+
+- stdout is built only from the typed envelope. An `err.message` is never printed: messages
+ embed vendor text (`loadCodeAssist` bodies) and agy's stderr.
+- Before writing, the serialized line is checked for these values, in full:
+ - the access token;
+ - the raw store value;
+ - every refresh token read;
+ - the project id.
+
+ A hit exits 1, with stdout empty and the stderr line
+ `[claudish subscription] refused: output contained a credential value`.
+- `log()` writes only to files, and only after `initLogger`, which this command never calls. The
+ project-id log lines in `antigravity-user.ts` therefore go nowhere.
+- stderr carries only fixed lines.
+
+The write is awaited before `process.exit`. Measured: an unawaited `process.stdout.write` of the
+200 KB line followed by `process.exit` reaches a pipe as exactly 65,536 bytes, 3 runs of 3. Awaiting
+the write callback delivers all of it.
diff --git a/docs/settings-reference.md b/docs/settings-reference.md
index b2a6aa6c..988f2c77 100644
--- a/docs/settings-reference.md
+++ b/docs/settings-reference.md
@@ -101,6 +101,7 @@ These are top-level subcommands recognized before flag parsing begins (checked i
| `claudish hooks init [dir]` | Write `example-hook.ts` and `claudish-hooks.d.ts` into `dir` (default `~/.claudish/hooks`); never overwrites |
| `claudish hooks corpus [--write] [--json]` | Replay recorded transcripts offline and count plan-mode divergences per model |
| `claudish hooks telemetry [--enable\|--disable]` | Show or set `hooks.telemetry.enabled` |
+| `claudish subscription models antigravity --raw --json` | Print the account's raw Antigravity `fetchAvailableModels` body as one JSON line (schema `claudish.subscription-model-list.v1`), for the models-index wire-probe runner. macOS only; never prompts. Exit 0 on any answer from the backend, 3–7 per failure class, 2 on a usage error. Contract: `ai-docs/architecture/providers/antigravity.md` § Raw model list for models-index |
**macOS Keychain (macOS only).** Keys are stored as one generic-password item per environment
variable under the service name `claudish`, so each is individually visible and deletable in