@cortexkit/pi-openai-auth 0.11.1 → 1.0.0

package/README.md

@@ -8,10 +8,12 @@ This package is part of the CortexKit OpenAI Auth monorepo, which supports both
 
 ## Install
 
+Requires Pi 1.0.1 or newer.
+
 Install with Pi's package manager:
 
 ```bash
-pi install npm:@cortexkit/pi-openai-auth@0.11.1
+pi install npm:@cortexkit/pi-openai-auth@1.0.0
 ```
 
 For an unpinned install:
@@ -34,18 +36,18 @@ Restart Pi after installing, then authenticate through Pi's normal login flow:
 
 ## Commands
 
-The extension registers three commands in Pi:
+The extension registers one command in Pi, `openai`, which opens a menu: Accounts (add a fallback account via OAuth, disable, enable, move or remove one), Quota (check now), Routing (`ordered`, `main-first`, `fallback-first`, `sticky-balanced`, and the roster order), Limits (the killswitch and per-account floors), Pi login (the quota of the account you signed in to Pi with, routed as `main`), This session (clear the session's pin) and Vault.
+
+The Vault section connects Pi to a [Claustrum](https://github.com/cortexkit/claustrum) vault: Connect proposes the enrollment `openai-auth-pi` and shows the `ck auth enroll approve --request-id <id>` and `ck auth grant --principal enrolled:openai-auth-pi --selector-kind category --selector openai-native --operation read` commands to run; Pi tells you when the approval lands. While Pi is connected (vault mode), the OpenAI accounts the vault serves it are the only ones routed, each request fetching its token from the vault; Pi's own login and the pool are neither used, refreshed nor polled. The provider and model names stay the same: use `openai-codex/<model>` in either mode. Before Pi reloads auth, the plugin saves Pi's original login in an owner-only stash under its vault state directory and puts a non-secret placeholder in Pi's `auth.json`, so Pi cannot refresh that login while the vault serves. Disconnect restores the original entry and forgets Pi's vault token. If a new Pi login was added while connected, disconnect reports a conflict and keeps both the new login and the stashed original without overwriting either. Each vault account can be disabled or enabled on Pi alone.
+
+## How requests are routed
+
+Every request goes out with one account's token, chosen by the routing mode:
 
-- `openai-account` — list configured fallback accounts, `openai-account add [label]` to add a fallback account via OAuth (browser or `--headless`), or `openai-account remove <id>` to remove one.
-- `openai-quota` — show the quota last recorded for each stored fallback account.
-- `openai-routing` — set the routing order (`main-first`, `fallback-first`, `sticky-balanced`) or reset session pins.
+- `main-first` tries your Pi login first, then the fallbacks in order; `fallback-first` tries the fallbacks first and your Pi login last. When an account answers with a rate-limit or auth error before anything was streamed, the next one is tried.
+- `sticky-balanced` keeps each Pi session on one account, spreading sessions by remaining quota, and moves a session for good only when its account is confirmed exhausted.
 
-These manage the account store. **Pi requests do not yet route through it** — the
-extension streams through the credential Pi itself supplies, so a routing choice is
-recorded but does not move traffic between accounts, and quota shows the last values
-written to the store rather than fetching current ones. The OpenCode plugin is where
-routing is live today. The store format is shared between the two, so what you configure
-here is what Pi will use once its request path reads it.
+Your Pi login stays where Pi keeps it: Pi refreshes it and the extension only uses the token Pi hands it. Fallback accounts live in the extension's own store (`openai-auth.json` in Pi's agent directory, `~/.pi/agent` unless `PI_AGENT_DIR` says otherwise, or the file `PI_OPENAI_AUTH_FILE` names), are refreshed there, and a fallback that is the same ChatGPT account as your Pi login is never used twice. An account is used only once its quota is known: each account's quota is checked as soon as the extension sees it, and quota from every response keeps it current. A store written by an earlier version is converted to the account-pool format the first time it is read, keeping its accounts.
 
 ## License