Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
# Per-account probe and manual model discovery

Status: implemented on `feat/antigravity-account-probe`.

## Problem

1. `POST /api/providers/test` resolves only the active account's token, so an operator with a
pool of Google Antigravity accounts cannot tell which individual accounts still work. Accounts
that started returning `permission_denied` could only be checked with an out-of-tree script.
2. Model discovery runs implicitly (catalog convergence, `liveModels`). There is no per-provider
"discover now" action, and recent arrivals only show as small NEW badges on the Models page.

## 1. Per-account probe

`POST /api/oauth/accounts/probe` — body `{ "provider": "google-antigravity", "accountId"?: string }`.
Omitting `accountId` probes every stored account (concurrency 4). Response:

```json
{ "provider": "google-antigravity", "probedAt": "<iso>",
"results": [{ "accountId": "…", "maskedLabel": "a***b@example.com", "active": true, "paused": false,
"status": "ok", "httpStatus": 200, "reason": null, "message": null,
"expiresAt": 0, "latencyMs": 412, "quota": { "customWindows": [] } }] }
```

`status` is one of:

| status | meaning | rule |
| --- | --- | --- |
| `ok` | usable | HTTP 200 |
| `paused` | account is paused by the operator; not tested | `account.paused === true`; no request is sent |
| `token_expired` | stored access token expired, not refreshed | `credential.expires <= now`; no request is sent |
| `suspended` | upstream says the account is suspended/disabled | 403 whose reason/message names suspension, disablement or ToS |
| `verification_required` | upstream asks the user to verify the account | 403 with `details[].reason == VALIDATION_REQUIRED` or "verify your account" wording |
| `rate_limited` | throttled / quota exhausted | 429 or `RESOURCE_EXHAUSTED` |
| `permission_denied` | other 403 | 403 |
| `error` | anything else (401, 5xx, transport, missing project) | `httpStatus` and `reason` carry the detail |

Read-only by construction:

- Uses the account's stored access token exactly as read through `getAccountSet()`; never calls
`getValidAccessToken`, never refreshes, never writes the auth store, never changes pause,
active, cooldown or health state. Paused accounts are skipped with status `paused` and no
request: an operator who parked an account has said not to use it, and a probe is still a use.
To test one, resume it first.
- One request: `POST https://daily-cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary`
with `{ "project": <projectId> }` and `User-Agent: antigravityCliUserAgent()`. Unlike the quota
poller there is no 403 retry under the IDE UA and no `fetchAvailableModels` fallback: the
first answer is the evidence, and the CLI fingerprint is the one that reports the Gemini group.
- Goes through the pinned provider-outbound transport used by the quota poller.
- The response carries no token. `message` is Google's error message passed through
`sanitizeUpstreamErrorText` and truncated to 300 characters.

Only `google-antigravity` is supported for now; other providers get HTTP 400
`account probe is not supported for this provider`. The request/response shape is provider-neutral
so another provider can plug in a probe function later.

CLI: `ocx account probe <provider> [<account-id|alias>] [--json]` (capability registered in
`src/cli/capabilities-accounts.ts`).

GUI: Providers → Google Antigravity → Available accounts. Each account row gets a **Test** button;
the result renders under the row as a coloured badge plus `HTTP <code> · <reason> · <message>`.
The section head gets **Test all**.

## 2. Manual model discovery

`POST /api/model-discovery/refresh` — body `{ "provider": "<name>" }`.

1. 404 for an unknown provider; `{ ok: false, applicable: false, reason: "static_catalog" }` when the
provider has `liveModels: false` (no live endpoint to ask).
2. Snapshot the provider's `recentArrivals` ids, `clearModelCache(provider)`, then run the normal
catalog convergence (`convergeCodexCatalog`), which re-fetches the provider and records new
arrivals through the existing new-model policy.
3. Respond with `{ ok, provider, discovery, liveModelCount, newArrivals, recentArrivals, catalogRefresh }`,
where `newArrivals` are the arrivals recorded by this call and `discovery` is the provider's
discovery status (`ok` / `failed` + reason / http status).

CLI: `ocx models discover <provider> [--json]`.

GUI: provider settings, directly under the "Discover models from provider" toggle: a
**Discover now** button and a "Recently added" list (newest first, with date and whether the model
was auto-disabled by the new-model policy).

## Not changed

- `POST /api/providers/test` and the active-account path.
- Token refresh, re-login, pause/resume semantics.
18 changes: 18 additions & 0 deletions docs-site/src/content/docs/reference/cli/providers-accounts.md
Original file line number Diff line number Diff line change
Expand Up @@ -985,6 +985,24 @@ token re-login or a plain account-list re-read. `--json` returns
failures exit 1; an upstream quota probe that fails or times out degrades to a null or stale report
instead (exit 0), matching the dashboard's quota bars.

### `ocx account probe google-antigravity [id|alias] [--json]`

Read-only per-account check for Google Antigravity. Each account gets one
`retrieveUserQuotaSummary` request with its own stored access token, under the CLI fingerprint, and
the result is classified as `ok`, `rate_limited`, `verification_required`, `suspended`,
`permission_denied` or `error` (with the HTTP status and Google's reason). Two outcomes are decided
locally and send nothing: `paused` (the account is paused; resume it to test it) and `token_expired`
(the stored token has expired). The probe never refreshes a token, never writes the auth store and
never changes pause, active, cooldown or health state. The dashboard's **Test** and **Test all**
buttons on Antigravity account rows call the same endpoint, `POST /api/oauth/accounts/probe`.

### `ocx models discover <provider> [--json]`

Runs the provider's live model discovery now instead of waiting for the next scheduled refresh, and
prints how many live models it saw and which ones are new. It is the same action as **Discover now**
under the provider's settings (`POST /api/model-discovery/refresh`). Providers without live
discovery report that discovery is off.

### `ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]`

Controls the `openai` Codex pool threshold, or stores a threshold for a generic OAuth pool. `on` stores 80%, `off` stores 0%, and `threshold <n>` accepts 0–100. A generic pool threshold steers selection only while `pool.kernel` is on with `strategy: "fill-first"`; with the flag off, saving one does not enable threshold-based switching. It never changes the provider enablement override or disables reactive 429 rotation. `status` and mutation output for generic pools use the confirmed server response. For generic pools, `poolEnabled` is the stored provider override (`null` means unspecified), not inherited effective state; `inert: true` means the threshold is stored but not applied, `inert: false` means the pool is applying it, and an absent `inert` is an unknown capability, which never reports `enabled: true`. API-key providers and invalid values are rejected.
Expand Down
53 changes: 53 additions & 0 deletions gui/src/components/provider-workspace/AccountProbe.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
import { useT } from "../../i18n/shared";
import type { AccountProbeController, AccountProbeEntry, AccountProbeStatus } from "../../hooks/useAccountProbe";

function statusBadgeClass(status: AccountProbeStatus): string {
if (status === "ok") return "badge badge-green";
if (status === "token_expired" || status === "paused") return "badge badge-muted";
return "badge badge-amber";
}

export function AccountProbeButton({ controller, accountId, label, disabled }: {
controller: AccountProbeController; accountId: string; label: string; disabled?: boolean;
}) {
const t = useT();
const pending = controller.isPending(accountId);
return (
<button type="button" className="btn btn-ghost btn-sm"
aria-label={`${t("acctProbe.test")} — ${label}`}
title={t("acctProbe.hint")}
aria-busy={pending}
disabled={disabled || pending}
onClick={() => { void controller.probeOne(accountId); }}>
{pending ? t("acctProbe.testing") : t("acctProbe.test")}
</button>
);
}

/** One line under the account row: verdict badge, then HTTP code, reason and upstream message. */
export function AccountProbeResultLine({ entry }: { entry: AccountProbeEntry | undefined }) {
const t = useT();
if (!entry) return null;
const time = new Date(entry.at).toLocaleTimeString();
if ("failed" in entry) {
return <div className="pwi-auth-row-secondary pws-status-warn" role="status">{`${t("acctProbe.failed")} · ${time}`}</div>;
}
const { result } = entry;
const evidence = [
result.httpStatus !== null ? `HTTP ${result.httpStatus}` : null,
result.reason,
result.message,
].filter((part): part is string => Boolean(part)).join(" · ");
const windows = (result.quota?.customWindows ?? [])
.map(window => `${window.label} ${Math.max(0, Math.round(100 - window.percent))}%`)
.join(" · ");
return (
<div className="pwi-auth-row-secondary" role="status" data-probe-status={result.status}
style={{ display: "flex", flexWrap: "wrap", alignItems: "center", gap: 6 }}>
<span className={statusBadgeClass(result.status)}>{t(`acctProbe.status.${result.status}`)}</span>
{evidence && <span className={result.status === "ok" ? "faint" : "pws-status-warn"}>{evidence}</span>}
{windows && <span className="faint">{windows}</span>}
<span className="faint">{time}</span>
</div>
);
}
124 changes: 124 additions & 0 deletions gui/src/components/provider-workspace/AccountQuotaTable.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
import { useEffect, useState, type CSSProperties, type ReactNode } from "react";
import { useT, type TKey } from "../../i18n/shared";
import {
buildQuotaTable, formatCountdown,
type AccountFlag, type PoolCell, type PoolKey, type QuotaTableAccount, type QuotaTableRow,
} from "../../provider-workspace/account-quota-table";
import "./account-quota-table.css";

const FLAG_TONE: Record<AccountFlag, "ok" | "warn" | "muted"> = {
ok: "ok", slow: "warn", stale: "muted", warning: "warn", probeFailed: "warn",
rateLimited: "warn", quotaLimited: "warn", reauth: "warn", paused: "muted",
};

function useMinuteClock(): number {
const [now, setNow] = useState(() => Date.now());
useEffect(() => {
const id = window.setInterval(() => setNow(Date.now()), 30_000);
return () => window.clearInterval(id);
}, []);
return now;
}

function PoolBar({ label, cell, now }: { label: string; cell: PoolCell; now: number }) {
const t = useT();
const remaining = Math.round(cell.remaining);
const tone = remaining <= 20 ? "bar-warn" : "bar-green";
const countdown = cell.resetAt === undefined ? null : formatCountdown(cell.resetAt, now);
return (
<div className="aqt-bar" title={cell.resetAt === undefined ? undefined : new Date(cell.resetAt).toLocaleString()}>
<span className="aqt-bar-label">{label}</span>
<div className="bar"><div className={`bar-fill ${tone}`} style={{ "--bar-scale": remaining / 100 } as CSSProperties} /></div>
<span className="aqt-bar-value">{remaining}%</span>
<span className="aqt-bar-reset">{countdown ? t("acctTable.resetsIn", { time: countdown }) : ""}</span>
</div>
);
}

export interface AccountQuotaTableProps {
accounts: readonly QuotaTableAccount[];
/** Pause/resume through the provider's existing account API; omitted hides the button. */
onTogglePause?: (accountId: string, paused: boolean) => void;
pauseDisabled?: boolean;
/** Per-account probe button (the existing read-only probe), when the provider supports it. */
renderProbe?: (account: QuotaTableAccount) => ReactNode;
}

/**
* Every account of one provider side by side: plan, each quota pool's 5-hour and weekly
* remaining with a reset countdown, and one status flag. Actions reuse the existing account
* APIs; the table adds no endpoint.
*/
export function AccountQuotaTable({ accounts, onTogglePause, pauseDisabled, renderProbe }: AccountQuotaTableProps) {
const t = useT();
const now = useMinuteClock();
const table = buildQuotaTable(accounts, now);
if (table.rows.length === 0 || table.pools.length === 0) return null;
const flagText = (row: QuotaTableRow) => row.flag === "probeFailed"
? t(`acctProbe.status.${row.probeStatus}` as TKey)
: t(`acctTable.flag.${row.flag}` as TKey);
const poolLabel = (key: PoolKey) => t(`acctTable.pool.${key}` as TKey);
return (
<div className="aqt" data-testid="account-quota-table">
<p className="aqt-policy faint">{t("acctTable.policy")}</p>
<div className="aqt-scroll">
<table className="aqt-table">
<thead>
<tr>
<th scope="col">{t("acctTable.account")}</th>
<th scope="col">{t("acctTable.plan")}</th>
{table.pools.map(pool => (
<th scope="col" key={pool.key}>
{poolLabel(pool.key)}
{pool.scarce && <span className="aqt-scarce">{t("acctTable.scarce")}</span>}
</th>
))}
<th scope="col">{t("acctTable.status")}</th>
{(onTogglePause || renderProbe) && <th scope="col">{t("acctTable.actions")}</th>}
</tr>
</thead>
<tbody>
{table.rows.map(row => (
<tr key={row.account.id} className={row.account.active ? "aqt-row--active" : undefined} data-flag={row.flag}>
<th scope="row" className="aqt-account">
<span className={`pwi-auth-dot ${row.account.active && !row.account.paused ? "pwi-auth-dot--ok" : "pwi-auth-dot--off"}`} aria-hidden="true" />
{row.account.label}
</th>
<td>
{row.plan
? <span className="badge badge-green" title={row.account.plan ? t("acctTable.planSource", { tier: row.account.plan }) : undefined}>{row.plan}</span>
: <span className="badge badge-muted">{t("acctTable.unknownPlan")}</span>}
</td>
{table.pools.map(pool => {
const cell = row.cells[pool.key];
return (
<td key={pool.key} className="aqt-pool">
{cell ? <>
{cell.fiveHour && <PoolBar label={t("acctTable.fiveHour")} cell={cell.fiveHour} now={now} />}
{cell.weekly && <PoolBar label={t("acctTable.weekly")} cell={cell.weekly} now={now} />}
{row.next.includes(pool.key) && <span className="badge badge-primary aqt-next" title={t("acctTable.nextHint")}>{t("acctTable.next")}</span>}
</> : <span className="faint">{t("acctTable.noReading")}</span>}
</td>
);
})}
<td><span className={`aqt-flag aqt-flag--${FLAG_TONE[row.flag]}`}>{flagText(row)}</span></td>
{(onTogglePause || renderProbe) && (
<td className="aqt-actions">
{onTogglePause && (
<button type="button" className="btn btn-ghost btn-sm" disabled={pauseDisabled}
aria-label={`${t(row.account.paused ? "codexAuth.resume" : "codexAuth.pause")} — ${row.account.label}`}
onClick={() => onTogglePause(row.account.id, !row.account.paused)}>
{t(row.account.paused ? "codexAuth.resume" : "codexAuth.pause")}
</button>
)}
{renderProbe?.(row.account)}
</td>
)}
</tr>
))}
</tbody>
</table>
</div>
</div>
);
}
Loading
Loading