Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* Antigravity shared OAuth token — read / refresh / write.
*
* Antigravity's own CLI (`agy`) stores its OAuth token in the macOS login
* keychain, and claudish shares that SAME store so a single sign-in covers both
* tools (Jack's explicit requirement). agy OWNS the refresh lifecycle too:
* claudish never handles the Antigravity client secret in ANY form (no embed, no
* scrape, no token exchange). When the shared token is expired, claudish asks agy
* to refresh it — running `agy models` (a lightweight authed command that lists
* served models, no generation quota) makes agy mint a fresh token with ITS OWN
* current secret and write it back to the shared store. claudish then simply
* RE-READS the store.
*
* Store layout (macOS login keychain):
* service = "gemini", account = "antigravity"
* value = "go-keyring-base64:" + base64(JSON) (zalando/go-keyring format)
* JSON = { token: { access_token, token_type, refresh_token, expiry(RFC3339) },
* id_token, auth_method }
*
* Why delegate refresh: Antigravity's client_secret is a static literal baked
* into the `agy` binary, and agy AUTO-UPDATES — each release rotates the secret
* and Google revokes the old one — so any secret claudish embedded or scraped
* would break within days, and there's no dynamic client registration. Letting
* agy do the refresh means claudish is always current, holds no secret, and stays
* out of the OAuth-client business entirely.
*
* Every side effect (keychain read/write/delete, the agy refresh command, clock)
* is behind an injectable `deps` object so the module is fully testable with no
* real keychain and no real agy process.
*/
import { execFileSync } from "node:child_process";
import { existsSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
import { log, logStderr } from "../logger.js";
import { findGenericPasswordPresence, startGenericPasswordRead } from "../providers/keychain.js";
import {
agyClientVersionReadFor,
getAgyClientVersion,
recordAgyClientVersionRead,
} from "./antigravity-client-version.js";
import { terminalCredentialError } from "./credentials/credential-error.js";
// ---------------------------------------------------------------------------
// Constants
// ---------------------------------------------------------------------------
/** Keychain service used by the shared agy/claudish token item. */
const KC_SERVICE = "gemini";
/** Keychain account used by the shared agy/claudish token item. */
const KC_ACCOUNT = "antigravity";
/** go-keyring single-item value prefix. Chunked values use other prefixes (unsupported). */
const PREFIX = "go-keyring-base64:";
/** Refresh when the access token is within this window of its expiry (~2 min). */
const EXPIRY_SKEW_MS = 120_000;
/**
* Max time to wait for `agy models` to refresh the shared token.
*
* MUST STAY BELOW THE SHORTEST CALLER DEADLINE. This was 40s while the config
* TUI's provider probe aborts its whole request at 15s
* (`tui/hooks/useRouteProbe.ts`) — so the refresh was granted 2.7× longer than
* the operation containing it, and a slow refresh was killed from outside
* before it could report anything. The user saw `timeout · 15004ms` on the
* provider row, with no indication that a refresh had been in flight, and the
* next attempt reported the still-expired token as an unrecoverable session.
*
* At 12s the refresh now fails INSIDE its own timeout, so it can say what
* happened and recommend waiting rather than a pointless re-login. A healthy
* refresh is a single network round-trip (~1-3s); the only thing 12s cannot
* absorb is agy self-updating, which no caller-side ceiling could absorb either
* and which is precisely the case the "timeout" message now names.
*/
const AGY_REFRESH_TIMEOUT_MS = 12_000;
/** Max time to wait for `agy --version` (measured at 0.04 s). */
const AGY_VERSION_TIMEOUT_MS = 5_000;
// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------
/** The OAuth token as stored under `token` in the shared store's JSON. */
export interface AntigravityToken {
access_token: string;
token_type: string;
refresh_token: string;
/** RFC3339 timestamp of access-token expiry (Go time.Time format). */
expiry: string;
}
/** The full decoded shared-store record. Unknown fields are preserved on write. */
interface SharedStoreRecord {
token: AntigravityToken;
id_token?: string;
auth_method?: string;
[key: string]: unknown;
}
/**
* Injectable side-effect seams. Tests supply fakes so no real keychain, agy
* process, or clock is ever touched.
*/
/**
* What happened when we asked the Antigravity CLI to refresh.
*
* `detail` carries agy's own stderr, truncated. agy explains its failures
* perfectly well; claudish was throwing that explanation away and substituting a
* guess.
*/
export type AgyRefreshOutcome =
| { kind: "ran" }
| { kind: "not-installed" }
| { kind: "timeout" }
| { kind: "failed"; detail: string };
export interface AntigravityTokenDeps {
/** Read the raw keychain value (with the `go-keyring-base64:` prefix), or null. */
readStore: () => string | null;
/** Write the raw keychain value (with the prefix). */
writeStore: (rawValue: string) => void;
/** Delete the shared keychain item entirely (logout). Optional; defaults to `security delete-generic-password`. */
deleteStore?: () => void;
/**
* Ask the Antigravity CLI to refresh the shared token — the real implementation
* runs `agy models` (a lightweight authed command), which makes agy mint a fresh
* token with its OWN current secret and write it back to the shared store.
* claudish never touches the client secret itself.
*
* Returns WHY it did not work, rather than nothing. The previous signature was
* `() => void` with the failure swallowed by a bare `catch {}` and agy's output
* sent to `stdio: "ignore"` — so three genuinely different situations (agy not
* installed / agy failed or timed out / agy succeeded but the session is
* revoked) all surfaced as one message telling the user to re-login. Only the
* third is actually fixed by re-logging in; for the second the fix is usually
* to wait, because agy AUTO-UPDATES and a 177MB self-update makes `agy models`
* take minutes.
*/
runAgyRefresh: () => AgyRefreshOutcome;
/**
* Read the installed agy's version (`agy --version` → `1.3.5`), or null when
* agy is absent or the read fails. The Antigravity backend gates discovery
* AND generation on the version in the User-Agent, so claudish presents the
* version agy reports rather than a pinned one; see
* `antigravity-client-version.ts`.
*
* Optional so a test fake that omits it captures nothing (and never spawns a
* real agy); `defaultDeps` always supplies it.
*/
readAgyVersion?: () => string | null;
/** Current time in ms since epoch (defaults to Date.now). */
now: () => number;
}
// ---------------------------------------------------------------------------
// Default (real) deps
// ---------------------------------------------------------------------------
/**
* Burst memo for the raw keychain READ.
*
* `defaultReadStore` spawns `security`, and since `antigravity` became visible in
* the model picker that spawn sits on the picker-open path: the picker resolves
* `credentials.isAvailable()` for every offered provider, which lands here. One
* open can therefore fork `security` several times for an answer that cannot have
* changed in between.
*
* A process-lifetime cache would be WRONG — `agy` signs in and out underneath us,
* writing the same keychain item from another process — so the TTL is deliberately
* short. The goal is collapsing a burst inside ONE operation, not caching across a
* session. Every write path claudish owns invalidates it explicitly (see
* `invalidateReadStoreMemo` callers), because a stale read after a refresh would
* hand back the token that was just replaced.
*/
const READ_STORE_TTL_MS = 3000;
let cachedRawStore: { at: number; value: string | null } | null = null;
/** Drop the read memo — call after ANY mutation of the shared keychain item. */
function invalidateReadStoreMemo(): void {
cachedRawStore = null;
}
/** Read the shared token via macOS `security`. Non-darwin → null (with a warning). */
function defaultReadStore(): string | null {
if (process.platform !== "darwin") {
logStderr(
"[Antigravity] Shared token store is macOS-only for now (other keyring backends are a follow-up)."
);
return null;
}
const now = Date.now();
if (cachedRawStore && now - cachedRawStore.at < READ_STORE_TTL_MS) return cachedRawStore.value;
let value: string | null = null;
try {
// `stdio` MUST be named. Node documents execFileSync's default as "pipe",
// but carves out stderr: without an explicit `stdio` the child writes fd 2
// straight to the PARENT's terminal. The miss here is the common case — a
// user who is not signed in to Antigravity — and `security` announces it
// with "security: SecKeychainSearchCopyNext: The specified item could not
// be found in the keychain." The catch below cannot suppress that: it owns
// the exception, while the CHILD already owned the file descriptor.
//
// That line is not an error. It is "not signed in", which this function
// reports as `null` by design. Printing it corrupts the config TUI, which
// shares its terminal with the Claude Code TUI, and it repeats forever
// because READ_STORE_TTL_MS is 3s and the provider list is rebuilt on
// every render. Same policy as providers/keychain.ts — see the spawn
// comment there, and terminal-isolation.ts for the display corruption.
//
// stdout stays PIPED because it carries the token; ignoring it the way the
// write/delete siblings do would make every read return null. stdin is
// ignored so this can never interact with a parent terminal in raw mode.
const out = execFileSync(
"security",
["find-generic-password", "-s", KC_SERVICE, "-a", KC_ACCOUNT, "-w"],
{ encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }
);
const trimmed = out.trim();
value = trimmed.length > 0 ? trimmed : null;
} catch {
// Item not found (agy not signed in) or `security` unavailable.
value = null;
}
// Memoize the MISS too: "not signed in" is the case that repeats hardest on the
// picker path, and it costs a failed spawn each time.
cachedRawStore = { at: now, value };
return value;
}
/** Write the shared token via macOS `security` (upsert with -U). */
function defaultWriteStore(rawValue: string): void {
if (process.platform !== "darwin") {
throw new Error("[Antigravity] Cannot write the shared token store on a non-macOS platform.");
}
// Invalidate BEFORE the write, so a throwing `security` still leaves the memo
// dropped rather than serving a value the store may or may not still hold.
invalidateReadStoreMemo();
execFileSync(
"security",
["add-generic-password", "-U", "-s", KC_SERVICE, "-a", KC_ACCOUNT, "-w", rawValue],
{ stdio: ["ignore", "ignore", "ignore"] }
);
}
/**
* Locate the user's agy binary: `which agy`, else ~/.local/bin/agy.
* Exported so the login-delegation flow (antigravity-oauth.ts) uses the SAME
* locator as the refresh scrape.
*/
export function locateAgyBinary(): string | null {
try {
const p = execFileSync("which", ["agy"], { encoding: "utf8" }).trim();
if (p.length > 0) return p;
} catch {
// fall through to the conventional install path
}
const fallback = join(homedir(), ".local", "bin", "agy");
return existsSync(fallback) ? fallback : null;
}
/** Delete the shared token via macOS `security` (idempotent — missing item is fine). */
function defaultDeleteStore(): void {
if (process.platform !== "darwin") return;
invalidateReadStoreMemo();
try {
execFileSync("security", ["delete-generic-password", "-s", KC_SERVICE, "-a", KC_ACCOUNT], {
stdio: ["ignore", "ignore", "ignore"],
});
} catch {
// Item not found / already gone — logout is idempotent.
}
}
/**
* Ask the Antigravity CLI to refresh the shared token.
*
* `agy models` is a lightweight authed command (lists served models — no
* generation quota). Running it when the stored token is expired makes agy mint a
* fresh token with ITS OWN current secret and write it back to the shared store;
* claudish then simply re-reads it. No-op (silent) when agy isn't installed — the
* caller re-reads, sees the token is still stale, and throws an actionable error.
* claudish never handles the client secret in any form.
*/
function defaultRunAgyRefresh(): AgyRefreshOutcome {
const agy = locateAgyBinary();
if (!agy) return { kind: "not-installed" };
try {
// stderr is CAPTURED, not discarded. It is the only account of why a refresh
// failed, and sending it to /dev/null is what forced the caller to guess.
execFileSync(agy, ["models"], {
stdio: ["ignore", "ignore", "pipe"],
encoding: "utf8",
timeout: AGY_REFRESH_TIMEOUT_MS,
});
return { kind: "ran" };
} catch (err) {
const e = err as { code?: string; signal?: string; stderr?: string };
// A killed child reports no exit code. `agy` self-updates (a ~177MB
// download), and during that window `agy models` can far exceed any sane
// ceiling — a timeout here means "busy", not "signed out".
if (e.code === "ETIMEDOUT" || e.signal === "SIGTERM") return { kind: "timeout" };
return { kind: "failed", detail: (e.stderr ?? "").trim().slice(0, 300) };
} finally {
// agy writes the refreshed token into the SAME keychain item from ANOTHER
// process, and `resolveValidToken` re-reads immediately after this returns.
// Without this drop, that re-read would replay the expired token from the
// memo and the successful refresh would be reported as "couldn't be
// refreshed". In the `finally` because a timed-out agy may still have
// written before we gave up on it.
invalidateReadStoreMemo();
}
}
/**
* Read the installed agy's version via `agy --version` (prints `1.3.5`, 0.04 s).
* Null on any failure — agy absent, non-zero exit, timeout, or output without a
* dotted version — so the caller keeps whatever version it already had.
*/
function defaultReadAgyVersion(): string | null {
const agy = locateAgyBinary();
if (!agy) return null;
try {
// `stdio` MUST be named, for the reason spelled out in `defaultReadStore`:
// without it the child's stderr goes straight to the parent's terminal,
// which the Claude Code TUI shares. stdout stays piped — it is the answer.
const out = execFileSync(agy, ["--version"], {
encoding: "utf8",
stdio: ["ignore", "pipe", "ignore"],
timeout: AGY_VERSION_TIMEOUT_MS,
});
return out.match(/\d+(\.\d+)+/)?.[0] ?? null;
} catch {
return null;
}
}
const defaultDeps: AntigravityTokenDeps = {
readStore: defaultReadStore,
writeStore: defaultWriteStore,
deleteStore: defaultDeleteStore,
runAgyRefresh: defaultRunAgyRefresh,
readAgyVersion: defaultReadAgyVersion,
now: () => Date.now(),
};
/**
* A fresh copy of the real deps, for a caller that wraps some of them, for
* example to record whether `runAgyRefresh` ran and what it reported. A copy,
* so wrapping one never changes what the other callers of this module get.
*/
export function defaultAntigravityTokenDeps(): AntigravityTokenDeps {
return { ...defaultDeps };
}
// ---------------------------------------------------------------------------
// Classified, bounded store read (for callers that must not block or guess)
// ---------------------------------------------------------------------------
/**
* The outcome of one bounded read of the shared token item.
*
* `defaultReadStore` maps every `security` failure to null, so to its callers
* a LOCKED keychain reads as "not signed in". It also has no deadline. A caller
* with no user to answer a dialog needs the two told apart, and a deadline.
*/
export type AntigravityStoreRead =
| { kind: "present"; raw: string }
| { kind: "absent" }
| { kind: "locked" }
| { kind: "timeout" }
| { kind: "failed" };
/**
* `security` exit codes that mean the keychain is locked or would have to ask:
* the low byte of the negated OSStatus. 128 is errSecUserCanceled, which a
* locked file answers to a `-w` read when the unlock request is cancelled
* (measured on a temporary keychain, 2026-10-21). 36 is
* errSecInteractionNotAllowed and 51 is errSecAuthFailed; both are derived
* from the same arithmetic, which reproduces the measured 44 for "not found".
*/
const KEYCHAIN_LOCKED_EXIT_CODES: ReadonlySet<number> = new Set([36, 51, 128]);
/** Race `work` against an absolute deadline. The loser is left running, never killed. */
async function raceDeadline<T>(work: Promise<T>, deadlineAt: number): Promise<T | "timeout"> {
let timer: ReturnType<typeof setTimeout> | undefined;
const timedOut = new Promise<"timeout">((resolve) => {
timer = setTimeout(() => resolve("timeout"), Math.max(0, deadlineAt - Date.now()));
});
try {
return await Promise.race([work, timedOut]);
} finally {
if (timer) clearTimeout(timer);
}
}
function classifyKeychainFailure(code: number): AntigravityStoreRead {
return KEYCHAIN_LOCKED_EXIT_CODES.has(code) ? { kind: "locked" } : { kind: "failed" };
}
/**
* Read the shared token item, bounded by `deadlineMs`, and say WHY when there
* is no value. Never kills `security`: a `security` killed mid-transaction once
* made macOS restart `securityd` (keychain.md). When the deadline passes, the
* caller stops waiting and `security` finishes on its own.
*
* Two steps, through `providers/keychain.ts`:
* 1. Presence (no `-w`) reads no item data. It separates "absent" (exit 44)
* from the rest. It is NOT a lock probe: a locked keychain still answers
* it with exit 0 (measured).
* 2. The value read (`-w`) is what a locked keychain refuses.
*
* `security`'s stderr is never carried in the result. Nothing here writes to
* the store, reads stdin, or opens a browser. `CLAUDISH_DISABLE_KEYCHAIN=1` (the
* test suite's escape hatch) answers `failed` without spawning anything.
*/
export async function readAntigravityStoreClassified(
deadlineMs: number
): Promise<AntigravityStoreRead> {
if (process.env.CLAUDISH_DISABLE_KEYCHAIN === "1") return { kind: "failed" };
const deadlineAt = Date.now() + deadlineMs;
const query = { service: KC_SERVICE, account: KC_ACCOUNT };
const presence = await raceDeadline(findGenericPasswordPresence(query), deadlineAt);
if (presence === "timeout") return { kind: "timeout" };
if (presence.kind === "absent") return { kind: "absent" };
if (presence.kind === "failed") return classifyKeychainFailure(presence.code);
const read = await raceDeadline(startGenericPasswordRead(query).done, deadlineAt);
if (read === "timeout") return { kind: "timeout" };
if (read.kind === "absent") return { kind: "absent" };
if (read.kind === "failed") return classifyKeychainFailure(read.code);
// Trimmed like `defaultReadStore`, so both reads hand `parseRecord` the same string.
const raw = (read.value ?? "").trim();
return raw.length > 0 ? { kind: "present", raw } : { kind: "absent" };
}
// ---------------------------------------------------------------------------
// Encode / decode
// ---------------------------------------------------------------------------
/** Decode the raw store value into a record. Returns null when absent/unsupported. */
function parseRecord(raw: string | null): SharedStoreRecord | null {
if (!raw) return null;
if (!raw.startsWith(PREFIX)) {
// go-keyring chunks values that exceed the keychain item limit under other
// prefixes; that layout is unsupported for now.
logStderr(
"[Antigravity] Shared token is in an unsupported keyring format (not go-keyring-base64) — skipping."
);
return null;
}
try {
const json = Buffer.from(raw.slice(PREFIX.length), "base64").toString("utf8");
const rec = JSON.parse(json) as SharedStoreRecord;
if (!rec?.token?.access_token) return null;
return rec;
} catch (err) {
log(`[Antigravity] Failed to decode shared token: ${err}`);
return null;
}
}
/** Encode a record back into the raw `go-keyring-base64:` store value. */
function encodeRecord(rec: SharedStoreRecord): string {
return PREFIX + Buffer.from(JSON.stringify(rec), "utf8").toString("base64");
}
// ---------------------------------------------------------------------------
// Public: read / write
// ---------------------------------------------------------------------------
/** Read the current shared Antigravity token, or null if absent/unsupported. */
export function readSharedAntigravityToken(
deps: AntigravityTokenDeps = defaultDeps
): AntigravityToken | null {
const rec = parseRecord(deps.readStore());
return rec ? rec.token : null;
}
/**
* Memoized "is an Antigravity token present in the shared store" — for the SYNC
* readiness classifier that the config TUI's React render path calls on every
* frame. `readSharedAntigravityToken()` shells out to `security`, so cache the
* boolean for a few seconds; the TTL means signing into Antigravity is reflected
* without a claudish restart, without spawning a process per render.
*/
let cachedHasToken: { at: number; value: boolean } | null = null;
const HAS_TOKEN_TTL_MS = 5000;
export function hasSharedAntigravityToken(deps: AntigravityTokenDeps = defaultDeps): boolean {
const now = Date.now();
if (cachedHasToken && now - cachedHasToken.at < HAS_TOKEN_TTL_MS) return cachedHasToken.value;
let value = false;
try {
value = readSharedAntigravityToken(deps) != null;
} catch {
value = false;
}
cachedHasToken = { at: now, value };
return value;
}
/**
* Write an updated Antigravity token back to the shared store, PRESERVING every
* other field (id_token / auth_method / unknown keys) — only the token's
* access_token / refresh_token / expiry / token_type are replaced. This is the
* refresh write-back; agy owns the FULL record on first login.
*/
export function writeSharedAntigravityToken(
tok: AntigravityToken,
deps: AntigravityTokenDeps = defaultDeps
): void {
const existing = parseRecord(deps.readStore());
const base: SharedStoreRecord = existing ?? { token: tok };
const merged: SharedStoreRecord = {
...base,
token: { ...base.token, ...tok },
};
deps.writeStore(encodeRecord(merged));
}
/**
* Delete the shared Antigravity token (logout). Idempotent — a missing item is
* not an error. Also clears the memoized presence flag so the config TUI reflects
* the logout immediately.
*/
export function deleteSharedAntigravityToken(deps: AntigravityTokenDeps = defaultDeps): void {
(deps.deleteStore ?? defaultDeleteStore)();
_resetAntigravityTokenState();
}
// ---------------------------------------------------------------------------
// Refresh
// ---------------------------------------------------------------------------
/** True when the access token is expired or within EXPIRY_SKEW_MS of expiry. */
function needsRefresh(tok: AntigravityToken, now: number): boolean {
const expMs = Date.parse(tok.expiry);
// An unparseable/absent expiry is treated as needing refresh (fail safe).
if (Number.isNaN(expMs)) return true;
return now >= expMs - EXPIRY_SKEW_MS;
}
// ---------------------------------------------------------------------------
// Client version (captured once per auth session)
// ---------------------------------------------------------------------------
/**
* Capture agy's version for the auth session this access token belongs to.
*
* Re-read only when the token differs from the one the last read was made for:
* a new token means agy ran (it refreshed or re-minted), and agy auto-updates,
* so that is exactly when the version can have changed. Same token → reuse, at
* the cost of a string compare per request. A failed read keeps the previous
* good version; see `recordAgyClientVersionRead`.
*/
function captureAgyClientVersion(accessToken: string, deps: AntigravityTokenDeps): void {
if (!deps.readAgyVersion || agyClientVersionReadFor(accessToken)) return;
const read = deps.readAgyVersion();
recordAgyClientVersionRead(read, accessToken);
if (read) {
log(`[Antigravity] Client version from agy: ${read}`);
} else {
const kept = getAgyClientVersion();
log(
"[Antigravity] Could not read the agy version" +
(kept ? `; keeping ${kept}.` : "; using the fallback version.")
);
}
}
// ---------------------------------------------------------------------------
// Public: valid access token (single-flight)
// ---------------------------------------------------------------------------
/** In-flight resolve promise — collapses concurrent callers onto one refresh. */
let inFlight: Promise<string> | null = null;
async function resolveValidToken(deps: AntigravityTokenDeps): Promise<string> {
if (process.platform !== "darwin") {
throw terminalCredentialError(
"[Antigravity] The shared Antigravity token store is macOS-only for now. " +
"Use g@<model> with GEMINI_API_KEY on this platform."
);
}
const rec = parseRecord(deps.readStore());
if (!rec) {
throw terminalCredentialError(
"[Antigravity] No Antigravity session found. Sign in with `claudish login antigravity`, " +
"or use g@<model> with GEMINI_API_KEY " +
"(get one at https://aistudio.google.com/app/apikey)."
);
}
if (!needsRefresh(rec.token, deps.now())) {
captureAgyClientVersion(rec.token.access_token, deps);
return rec.token.access_token;
}
// Expired/near-expiry → ask agy to refresh (it owns the secret). Running `agy
// models` mints a fresh token into the shared store; we then RE-READ it.
log("[Antigravity] Access token expired/near-expiry — asking the Antigravity CLI to refresh.");
const outcome = deps.runAgyRefresh();
const refreshedRec = parseRecord(deps.readStore());
if (refreshedRec && !needsRefresh(refreshedRec.token, deps.now())) {
log("[Antigravity] Shared token refreshed by the Antigravity CLI.");
captureAgyClientVersion(refreshedRec.token.access_token, deps);
return refreshedRec.token.access_token;
}
// Still stale. WHY decides what the user should actually do — and only one of
// these four is fixed by signing in again. Reporting them all as "session
// expired, re-login" sent users through an OAuth flow that could not help,
// most often while agy was simply mid-self-update.
// What the outcome says about the login decides the error's class: a slow or
// failing `agy` is not a dead session (retryable), a missing CLI or a revoked
// session is (terminal). `credential-error.ts`.
const message = `[Antigravity] ${describeRefreshFailure(outcome)}`;
if (outcome.kind === "timeout")
throw Object.assign(new Error(message), { transient: true as const });
if (outcome.kind === "failed") throw new Error(message);
throw terminalCredentialError(message);
}
/** Turn a refresh outcome into the remediation that actually applies to it. */
function describeRefreshFailure(outcome: AgyRefreshOutcome): string {
switch (outcome.kind) {
case "not-installed":
return (
"The Antigravity CLI (`agy`) is not installed, so the expired session could not be " +
"refreshed. Run `claudish login antigravity` — it installs and authenticates it."
);
case "timeout":
return (
`The Antigravity CLI did not finish within ${Math.round(AGY_REFRESH_TIMEOUT_MS / 1000)}s, ` +
"so the session could not be refreshed. `agy` auto-updates itself (a large download) " +
"and is unusably slow while it does — this usually clears on its own. Try again in a " +
"minute; run `agy models` to see what it is doing. You are most likely still signed in."
);
case "failed":
return (
"The Antigravity CLI could not refresh the session" +
(outcome.detail ? `: ${outcome.detail}` : ".") +
" If it reports being signed out, run `claudish login antigravity`."
);
default:
// agy ran cleanly and the token is STILL stale — the session really is
// revoked, which is the one case a fresh sign-in fixes.
return (
"The Antigravity session is expired and the Antigravity CLI refreshed it without " +
"producing a valid token — the session has most likely been revoked. " +
"Run `claudish login antigravity`."
);
}
}
/**
* Read → refresh-if-needed (via agy) → return a valid Antigravity access token.
* Single-flight: concurrent callers share one in-flight resolution so only ONE
* `agy models` refresh runs even under a parallel spawn. Throws a clear,
* actionable error when the store is missing (not signed in), when agy can't
* refresh it, or on a non-macOS platform.
*/
export function getValidAntigravityAccessToken(
deps: AntigravityTokenDeps = defaultDeps
): Promise<string> {
if (inFlight) return inFlight;
inFlight = resolveValidToken(deps).finally(() => {
inFlight = null;
});
return inFlight;
}
// ---------------------------------------------------------------------------
// Public: forced refresh (the backend rejected the token we presented)
// ---------------------------------------------------------------------------
/**
* Re-mint the shared Antigravity token even though it is not locally expired.
*
* `needsRefresh()` only ever asks the CLOCK. A token Google invalidated
* server-side — session revoked, signed in elsewhere, OAuth client rotated —
* still carries a future `expiry`, so claudish considers itself healthy and
* keeps presenting a dead credential until the clock catches up. This is the
* escape hatch for the one moment when we hold better evidence than the clock:
* the backend has just REJECTED the token.
*
* Stamping the stored expiry into the past before calling agy is LOAD-BEARING.
* `agy models` re-mints only when AGY believes the token is expired, so against
* a locally-valid record it would authenticate with the same dead token, exit 0,
* and the "refresh" would be a silent no-op — the caller then retries with the
* credential that just failed. Marking the record expired is honest (the backend
* already told us it is dead), and a failed re-mint restores exactly what we
* found, so an absent or broken agy cannot leave the store worse than it was.
*
* Throws rather than returning null: the caller is mid-retry, and a null would
* send it back upstream with the same rejected credential instead of surfacing
* an actionable message.
*/
export async function forceRefreshAntigravityToken(
deps: AntigravityTokenDeps = defaultDeps
): Promise<string> {
if (process.platform !== "darwin") {
throw terminalCredentialError(
"[Antigravity] The shared Antigravity token store is macOS-only for now. " +
"Use g@<model> with GEMINI_API_KEY on this platform."
);
}
// Drop the single-flight promise AND the read memo first, so nothing below can
// be handed back the very token the backend just rejected.
_resetAntigravityTokenState();
const rec = parseRecord(deps.readStore());
if (!rec) {
throw terminalCredentialError(
"[Antigravity] No Antigravity session found. Sign in with `claudish login antigravity`, " +
"or use g@<model> with GEMINI_API_KEY " +
"(get one at https://aistudio.google.com/app/apikey)."
);
}
const original = rec.token;
log("[Antigravity] Upstream rejected the current token — asking the Antigravity CLI to re-mint.");
writeSharedAntigravityToken(
{ ...original, expiry: new Date(deps.now() - 1000).toISOString() },
deps
);
const outcome = deps.runAgyRefresh();
const refreshed = parseRecord(deps.readStore());
const token = refreshed?.token;
if (token && token.access_token !== original.access_token && !needsRefresh(token, deps.now())) {
log("[Antigravity] Shared token re-minted by the Antigravity CLI.");
captureAgyClientVersion(token.access_token, deps);
return token.access_token;
}
// Restore ONLY when agy never wrote (the store still holds our own expiry
// stamp). If agy did write something — even something we can't use — that
// record is more current than ours, and clobbering it would undo a real
// sign-in. Our stamp was a means to provoke the re-mint, never a verdict to
// persist.
if (!refreshed || refreshed.token.access_token === original.access_token) {
writeSharedAntigravityToken(original, deps);
}
_resetAntigravityTokenState();
// The same distinctions as the expiry path: a slow or failing `agy` (mid
// self-update, most often) says nothing about the session, so it is
// retryable; only a CLI that ran and still produced nothing, or is missing,
// is a dead session (`credential-error.ts`).
if (outcome.kind === "timeout" || outcome.kind === "failed") {
const message = `[Antigravity] ${describeRefreshFailure(outcome)}`;
if (outcome.kind === "timeout") {
throw Object.assign(new Error(message), { transient: true as const });
}
throw new Error(message);
}
if (outcome.kind === "not-installed") {
throw terminalCredentialError(`[Antigravity] ${describeRefreshFailure(outcome)}`);
}
throw terminalCredentialError(
"[Antigravity] The Antigravity session was rejected upstream and could not be re-minted. " +
"Run `claudish login antigravity` to sign in again."
);
}
// ---------------------------------------------------------------------------
// Test seam
// ---------------------------------------------------------------------------
/**
* Clear the in-flight promise, the memoized presence flag, and the raw read memo
* (between tests, and after any out-of-band change to the shared store).
*
* The read memo is included so callers that already documented themselves as
* "reset, then read FRESH" — antigravity-oauth's `readToken` — keep that
* guarantee now that the default read is memoized at all.
*/
export function _resetAntigravityTokenState(): void {
inFlight = null;
cachedHasToken = null;
invalidateReadStoreMemo();
}