Account selection for antigravity and apikey credentials: planned, or must callers pin auth.account? #3

Activity

1. broca-alfonso commented on Oct 24, 2026

   

   broca-alfonsoBot

   on Oct 24, 2026

   More actions

   Thanks, the reading of the code is accurate for today. We've since settled how account choice works, so here's that design.

   broca never chooses an account on its own logic. A routing module chooses, and broca carries out its answer.

   • Every credential kind is a pool. For every provider with credentials, including antigravity logins and apikey keys, the routing module picks the account for each run. Today only the oauth and chatgpt subscription methods work this way.
   • When broca asks. It asks when a run starts, and again when a step is refused because the account is out of quota.
   • Hold or move. If the limit that blocks the account resets soon, routing answers "wait" and the run keeps its account, which keeps the prompt cache. At the start of a run broca then refuses the send with the time to retry. Inside a run it pauses and resumes at that time. Otherwise routing names another account.
   • Switching inside a run. broca continues the same run on the new account, as long as it's the same kind of credential. It never switches kinds, for example from a subscription to an API key, because that changes the request itself. The switch is recorded in the session log, and the switched step misses the prompt cache, since the cache belongs to the old account.
   • Blocks lift on evidence. An account becomes usable again as soon as a fresh quota reading shows room, not only at a predicted reset time.
   • Without a routing module, broca still never chooses. The caller names the account with auth: {method, account}, and when that account runs out the run ends account_limit_exhausted, naming the credential and, where the provider gives one, the reset time.

   This isn't built yet. We'll update docs/module-surface.md when it ships, so a caller knows exactly what to send in each case.