@byokit/accounts 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## 0.15.0 (2026-10-01)
+
+- Dependency update: pins @byokit/usage 0.5.0.
+
+- FIX: ChatGPT subscription respond() now retains reported token usage with result: true or tools, including partial results for incomplete answers.
+- Bind an existing ChatGPT subscription login to a member-bound chatgpt() handle without exposing credentials.
+- Script mockOpenAI answers with string, regex or function prompt matchers and optional token usage.
+
+## 0.14.0 (2026-10-01)
+
+- Dependency update: pins @byokit/usage 0.4.0.
+
+- SECURITY: Add a Node-only managed CLI account boundary for subscription sign-in: only app-owned folders and explicitly passed absolute binaries, no default login access, no credential-file reads, no token output, and launch environment credential shedding.
+- Add managed CLI account creation, marker-gated sign-in, status, rename, cancellation, history links and removal, with legacy roster and terms compatibility.
+- Share the portable chooser's AccountLike type and accept normalized subscription usage with millisecond reset times.
+- Bound native status deadlines even when a passed CLI ignores termination; stdout is capped and only the owned child is terminated.
+- Offer every subscription catalogue row by default on supported platforms, adding Kimi, Meta, Qwen and MiniMax labels; preserve Claude Pro/Max sign-in and remove terms and visibility gates. API key (billed per use) rows remain opt-in. Simplify the ChatGPT plan-use error words.
+
 ## 0.13.0 (2026-10-01)
 
 

package/README.md

@@ -8,8 +8,8 @@
 </p>
 
 <p align="center"><strong>Sign in with the AI plan you already pay for, inside your own app.</strong><br/>
-ChatGPT and Claude Pro/Max on every platform (Claude needs Web Crypto); OpenRouter on computers when an app offers it (API billing, never by default); Grok and
-GitHub Copilot hidden by default. Anthropic uses an app-passed API key (billed per use), explicitly opted in. Sign-ins go into your app's own store: on a computer (Node, Electron), in a browser
+ChatGPT and Claude Pro/Max on every platform (Claude needs Web Crypto); Grok, GitHub Copilot, Kimi and Meta on computers.
+OpenRouter and Anthropic API keys are billed per use and require explicit app opt-in. Sign-ins go into your app's own store: on a computer (Node, Electron), in a browser
 (a PWA, Electron's renderer) and on a phone (React Native and Expo, iOS and Android). One import; your bundler picks
 the platform's side (`package.json`'s `react-native` and `browser` conditions).</p>
 
@@ -75,16 +75,18 @@ On a computer it uses Pi's [`@earendil-works/pi-ai`](https://www.npmjs.com/packa
 flows, pinned exactly:
 
 ```ts
+import type { SafeStorageLike } from '@byokit/accounts';
 import { isolate } from '@byokit/accounts/isolate'; // first, before any Pi import
 isolate('/path/to/app/engine');                     // scrub inherited Pi settings and provider keys
-const { Accounts, fileStore } = await import('@byokit/accounts');
-const { app, safeStorage } = await import('electron');
-await app.whenReady();
-
-const accounts = new Accounts({ store: (member) => fileStore(`/path/to/app/people/${member}/auth.json`, safeStorage) });
-const shown = await accounts.login(1, 'chatgpt', { via: 'code' }); // { state: 'waiting', code, url }
-// show shown.code and shown.url; the sign-in finishes by itself
-(await accounts.status(1, 'chatgpt')).words;                     // "ChatGPT is connected."
+
+// Your Electron main process waits for app.whenReady(), then passes its safeStorage here.
+export async function connect(safeStorage: SafeStorageLike) {
+  const { Accounts, fileStore } = await import('@byokit/accounts');
+  const accounts = new Accounts({ store: (member) => fileStore(`/path/to/app/people/${member}/auth.json`, safeStorage) });
+  const shown = await accounts.login(1, 'chatgpt', { via: 'code' }); // { state: 'waiting', code, url }
+  // show shown.code and shown.url; the sign-in finishes by itself
+  return { shown, status: await accounts.status(1, 'chatgpt') };
+}
 ```
 
 ### On a phone or in a browser
@@ -116,10 +118,10 @@ and [`examples/pwa`](../../examples/pwa) (browser sign-in).
 
 | Export | What it does |
 |---|---|
-| `Accounts` | Sign-in, status, sign-out, asking and limits for each member: `login`, `finished`, `status`, `plan`, `logout`, `respond`, `failed`, `ladder`, `keepFresh` |
+| `Accounts` | Sign-in, status, sign-out, asking and limits for each member: `login`, `finished`, `status`, `plan`, `logout`, `respond`, `chatgpt`, `failed`, `ladder`, `keepFresh` |
 | `portable`, `computer`, `loopback` | The platform `Accounts` runs on: device code with `fetch` alone, or (Node entry only) Pi's flows and the loopback listener |
 | `memoryStore`, `fileStore`, `secureStore`, `browserStore`, `recordStore` | One store per person: in memory, a sealed 0600 file (Node entry only), Keychain/Keystore, IndexedDB, or your own load and save |
-| `offered`, `provider`, `PROVIDERS` | The catalogue: each provider's billing, terms status, reason and source |
+| `offered`, `provider`, `PROVIDERS` | The catalogue: each provider's billing, models and source |
 | `billingWords`, `say`, `WORDS`, `signInError`, `failure`, `clock`, `callbackPage` | The plain sentences every app shows the same way (`words.json`), a time in words, and the page a browser sees after a sign-in |
 | `respond`, `ResponseError`, `IncompleteError`, `sseReader`, `limitResponse`, `isFunctionCall` | Ask ChatGPT's answers endpoint with a sign-in, with tools, pictures, thinking effort and an answer shape; the error with the words to show and the kind acted on |
 | `classifyFailure`, `classify`, `REST_MS` | An error's kind (limit, overload, plan without this use, lapsed sign-in, network) and default rest times |
@@ -138,7 +140,7 @@ and [`examples/pwa`](../../examples/pwa) (browser sign-in).
 | Claude Pro/Max (subscription) | Provider page, paste its code back | Same PKCE flow; token endpoint CORS required | Same PKCE flow; app supplies Web Crypto |
 | Anthropic (API key, billed per use) | App passes its own key, explicitly | Same fetch-only Messages provider | Same fetch-only Messages provider |
 | OpenRouter (API billing) | Its own page, back to this computer (Pi's flow), when an app offers it (never by default) | Not yet | Not yet |
-| Grok, Copilot (hidden) | Pi's flows | No | No |
+| Grok, Copilot, Kimi, Meta | Pi's flows | No | No |
 | Where sign-ins are kept | `fileStore(path, safeStorage)`, sealing required | `browserStore(name)` (IndexedDB) | `secureStore(SecureStore, name)` (Keychain, Keystore) |
 
 Device code works everywhere: OpenAI's sign-in endpoints answer any web page. The page-straight-back sign-in needs a
@@ -148,13 +150,16 @@ doesn't answer other web pages), so a PWA's model calls go through the app's own
 
 ## Catalogue and billing
 
-`catalogue.json` holds each provider with its billing (`subscription`, `api`) and terms status (`allowed`, `grey`,
-`partner`), a one-line reason and a source. The kit labels; your app decides what to offer
-(`new Accounts({ offer: ['chatgpt'] })`). Without an explicit `offer`, only subscription sign-ins supported on this
-platform are shown: OpenRouter is API-billed and never offered by default. An explicit list is not platform-filtered,
-so choose from the table above. Show `billingWords(p)` next to every provider you list.
+`catalogue.json` holds each provider's billing (`subscription`, `api`), models and source.
+All subscription rows are offered by default on platforms that support their sign-in. API-billed rows
+are offered only when the app names them. An explicit `offer` list is not platform-filtered.
+The `Provider` shape no longer has `terms`, `hidden` or `why`, and `Terms` is no longer exported.
+Qwen and MiniMax have subscription catalogue rows; their paste and portal sign-in flows follow in later work packages.
+Each provider's own terms apply to how you use your plan.
+Anthropic Messages uses an app-passed API key (billed per use); authentication is separate from the Messages request.
 
-Anthropic Messages uses an app-passed API key (billed per use), with explicit opt-in; its authentication is separate from the Messages request.
+Native Claude CLI sign-in uses the managed-folder entry.
+Approved exception: the `./cli` entry reads and runs only app-managed per-account folders under `stateDir` and the absolute CLI binaries the app passes; it never touches the person's default login; tokens never leave the device and are never logged.
 
 ```ts
 import { Accounts, billingWords, offered } from '@byokit/accounts';
@@ -164,7 +169,7 @@ for (const p of offered(['chatgpt', 'openrouter'])) console.log(`${p.name}: ${bi
 ```
 
 ```text
-[ 'chatgpt', 'claude' ]
+[ 'chatgpt', 'grok', 'copilot', 'claude', 'kimi', 'meta', 'qwen', 'minimax' ]
 ChatGPT: Uses your ChatGPT plan.
 OpenRouter: Charged per use to your OpenRouter account, not a plan.
 ```
@@ -251,12 +256,15 @@ const accounts = new Accounts({
 
 `respond(member, { instructions, input, model?, onText?, signal? })` asks ChatGPT's own answers endpoint with the
 member's sign-in, refreshed first when due, and returns the whole text (`onText` gets each piece as it streams; the
-returned completion is authoritative). A limit or a lapsed sign-in is acted on as `failed()` does, then thrown as a
+returned completion is authoritative). Pass `result: true` to receive `{ text, output, usage? }` even without tools.
+`usage` retains provider-reported `input_tokens`, `output_tokens` and native details in the same shape as the
+Messages route; absent usage stays absent. Subscription token counts do not imply an API-key charge.
+A limit or a lapsed sign-in is acted on as `failed()` does, then thrown as a
 `ResponseError` with the words to show and the kind acted on. Rules: [conformance fixtures](../../fixtures/README.md).
 
 A cut-off answer always throws `IncompleteError` (a `ResponseError` with `kind: null`), with or without tools.
 Its `reason` preserves the provider's `incomplete_details.reason`, including `max_output_tokens` and
-`content_filter` (`unknown` when absent). Its `result` holds the partial `{ text, output }` for apps that want to
+`content_filter` (`unknown` when absent). Its `result` holds the partial `{ text, output, usage? }` for apps that want to
 show it as unfinished. `onEvent` also receives `{ type: 'incomplete', reason }` before rejection; `onText` may
 already have shown partial words. This covers `response.incomplete` events and `status: 'incomplete'` envelopes,
 whether fetch streams SSE, buffers it, or returns JSON. The account stays signed in and is not put to rest.
@@ -327,6 +335,14 @@ tests and demos sign in and ask end to end with no account. Point the kit at it
 
 Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](../../NOTICE).
 
+## ChatGPT subscription handles
+
+After `Accounts.login(member, 'chatgpt')` finishes, `accounts.chatgpt(member)` returns a member-bound
+subscription handle for `openai({ auth: 'account', account: handle, model })` in `@byokit/decide`.
+It routes requests through `Accounts.respond`, which keeps tokens in the app's store and refreshes them
+before use. The handle contains no credentials, follows sign-out, and needs no additional sign-in or
+API key (billed per use). ChatGPT remains offered by default. Use the handle only where the sign-in lives.
+
 ## Official ChatGPT plan token-sharing adapter
 
 `chatgptPlan({ session })`, also exported from `@byokit/accounts/chatgpt-plan`, binds a single person's
@@ -438,8 +454,6 @@ fetch such as Expo's. `betas` explicitly opts into native beta headers.
 
 ## Claude Pro/Max subscription
 
-Anthropic's [developer guidance](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use) prohibits third-party Claude.ai login without approval; BYOKit has no approval, and this route may stop working or lead to account restrictions (the separately billed API-key route is the documented alternative).
-
 Claude is available by default. Open its page, then paste the returned `code#state` into the app:
 
 ```ts
@@ -551,3 +565,57 @@ Identity and re-authentication stay with the host's canonical device store or en
 scoped by member/provider proves identity; names and emails do not. The TypeScript identity fixture records
 wrong-account, duplicate identity, changed-email, absent-identity, removal/refresh and extension-field boundaries
 for runtime integration; the chooser consumes host-validated state and never adopts credentials itself.
+
+## Managed CLI accounts (Node only)
+
+`@byokit/accounts/cli` exports `cliAccounts`, `CliAccountError`, `CliProvider`, `CliAccount`, `CliOptions` and `SignInCommand`. Accounts use subscription billing. The portable entries and the `Accounts` class retain their existing sign-in flows.
+
+`CliAccount` extends the portable chooser's `AccountLike`. Pass normalized usage through `@byokit/usage`'s `roomOf(reading, nowMs)` when selecting an account, preserving millisecond reset times and the original measurement time.
+
+```ts
+import { cliAccounts } from '@byokit/accounts/cli';
+const accounts = cliAccounts({
+  stateDir: '/app/state/plans',
+  bins: { claude: '/app/bin/claude', codex: '/app/bin/codex' },
+  env: { HOME: '/app/home', PATH: '/app/bin:/usr/bin:/bin' },
+  historyFrom: { claude: '/app/history/projects', codex: '/app/history/sessions' },
+  prepare: async (folder, provider) => { /* app-owned setup, such as installing hooks */ },
+});
+const { account, signIn } = await accounts.add('claude');
+// Run signIn.shell in the app's sign-in tab, or run signIn.argv with signIn.env
+// and create signIn.completion privately only after that command succeeds.
+const current = await accounts.status(account.id);
+const { set, unset } = accounts.launchEnv(account.id);
+// Apply unset to the launch environment, then apply set, before starting the agent.
+```
+
+`stateDir` must be an absolute app-owned directory with an existing parent. The kit creates it at 0700 and creates private `<provider>/<hex>` account folders below it. `bins` are absolute paths; PATH is never used to find the CLI. Status and login use an environment built from nothing plus the app's `env`, after removing provider credential overrides and adding the managed-folder variable. Pass proxy or temporary-directory settings explicitly if needed. `launchEnv` returns the folder variable in `set` and the provider overrides in `unset`; hosts must apply both so a stray API key (billed per use) cannot override the chosen subscription.
+
+`add` returns a `signing` account and the native login command. `status` stays `signing` until the completion marker exists, including after a host restart, and does not run a second native client during pending sign-in. The shell uses a private per-folder lock and marks completion only after successful login. Stop the app's sign-in tab before `cancel` or `remove`; the kit does not supervise that tab. `signInAgain` reuses a pending command or starts a new completion cycle; if an account operation is already in flight it throws `prepare-failed`, so await that operation before retrying. Native CLIs own their refresh transactions; the kit neither copies credentials nor refreshes grants. A crashed sign-in shell can leave its lock; the host should stop that process and remove only that managed lock before retrying.
+
+`list` probes managed folders concurrently; `status`, `rename`, `remove` and `cancel` serialize operations per account. Only signed-in state (`ready` or `signed_out`), email and plan come from native status output; no credential file is opened and raw CLI errors and output are discarded. `rename` accepts a trimmed name of 1–64 characters. `cancel` removes only folders added by this instance; for existing accounts it ends the pending completion cycle without deleting the account. `remove` deletes only a validated managed folder. `historyFrom` creates a history symlink inside that folder; it never creates or writes the target, even when it is missing. A throwing `prepare` rolls back the new folder.
+
+Native status reads resolve within 15 seconds. Claude stdout is capped at 256 KB and identity JSON at 64 KB; the shared Codex client caps stdout at 64 KB. Timeout or excess output terminates only that owned child, with SIGTERM followed by SIGKILL after one second if it is still alive.
+
+The existing `accounts-v1.json` `{version:1,accounts:[{id,provider,name,folder,found}]}` and `auto-terms-v1.json` `{acknowledged:true}` encodings remain unchanged, with 0600 files and atomic replacement. The kit preserves but excludes `found-*` and `found:true` rows, which belong to the host's default-login adapter. Legacy managed rows without kit completion sidecars retain their native signed-in status; new or re-signing rows require the completion marker. Symlinked account folders and records outside the provider/hex layout are refused.
+
+`usageSource(id)` returns a Codex Source for `@byokit/usage`; Claude returns `undefined`, and its usage Source is `{provider:'claude', folder:set.CLAUDE_CONFIG_DIR, headers}` in a usage reader whose `stateDir` is the same managed root. `kinds` serves only the matching native agent (`claude` or `codex`); Pi is excluded until its folder mapping is verified. `resumeArgs` accepts an `id` conversation reference for these kinds. `termsAcknowledged` and `acknowledgeTerms` keep the host's existing terms bit; they do not gate sign-in. `suggestName` uses the first part of an email, falling back to the provider's name.
+
+
+## Scripted sign-in stand-in
+
+`mockOpenAI({ answers })` from `@byokit/accounts/testing` runs the normal device-code sign-in and
+ChatGPT response path on loopback. Each script has `{ match, text, usage? }`: a string matches a
+substring of joined input text, a regex tests it, and a function receives it and returns a boolean.
+The first match wins, including on repeat requests; unmatched input retains echo/tool behavior.
+Replace `mock.state.answers` between requests to change scripts. Counts are explicit fake data.
+
+```ts
+import { mockOpenAI } from '@byokit/accounts/testing';
+
+const mock = await mockOpenAI({ email: 'umer@example.com', answers: [
+  { match: 'Umer', text: 'Ready.', usage: { input_tokens: 12, output_tokens: 3 } },
+  { match: /finished/i, text: 'Done.' },
+  { match: (prompt) => prompt.includes('help'), text: 'I can help.' },
+] });
+```

package/SECURITY.md

@@ -66,7 +66,7 @@ Deleting local files alone does not revoke tokens, and deletion cannot erase old
 
 Tests use fake providers, temporary homes, filesystem canaries and Node permissions;
 `npm test` blocks outbound networking and checks the owner's existing setup byte for byte.
-The kit never invokes the owner's installed tools or borrows environment API keys.
+The kit never borrows environment API keys. Its Node-only `./cli` exception invokes only app-passed absolute CLI binaries against app-managed folders; it never opens credential files or the person's default login. Native CLI credentials remain on the device under the CLI's own storage policy; they do not pass through `fileStore` sealing.
 
 ## Review record
 

package/dist/accounts.d.ts

@@ -3,6 +3,7 @@ import { type ClaudePlanOptions } from './claude-plan.ts';
 import { type AnthropicAsk, type AnthropicResult, type AnthropicTool } from './anthropic.ts';
 import { type Provider } from './catalogue.ts';
 import { ResponseError, type Ask, type ResponseResult, type ResponseTool } from './responses.ts';
+import type { ChatGPTRespondAccount } from './chatgpt-plan.ts';
 import { type EndingStore, type RefreshStore } from './stores.ts';
 import { type Why } from './words.ts';
 /** What signing in needs from an engine: Pi's `Models`, or anything shaped like it (the coding agent's `ModelRuntime`). */
@@ -55,7 +56,7 @@ export type AnthropicAccountAsk = AnthropicAsk & {
     key: string;
 };
 export type AccountsOptions<M extends Member = Member> = {
-    /** The accounts this app offers, in order. Default: supported subscription providers not hidden. */
+    /** The accounts this app offers, in order. Default: every subscription provider supported on this platform. */
     offer?: readonly string[];
     /** Each member's own store. Default: in memory. */
     store?: (member: M) => CredentialStore;
@@ -112,7 +113,7 @@ export declare class Accounts<R extends AuthHost = AuthHost, M extends Member =
     onExpired?: (member: M, key: string) => void;
     onSignOutError?: (member: M, key: string, error: Error) => void;
     private platform;
-    /** Offered: the providers named in `offer`, else every provider not hidden that this platform can sign in to. */
+    /** Offered: the providers named in `offer`, else every subscription provider that this platform can sign in to. */
     constructor(opts?: AccountsOptions<M>, platform?: Platform);
     /** A member's own store. */
     protected store(member: M): EndingStore;
@@ -171,12 +172,20 @@ export declare class Accounts<R extends AuthHost = AuthHost, M extends Member =
         result?: false;
     }): Promise<string>;
     respond(member: M, ask: AnthropicAccountAsk): Promise<string | AnthropicResult>;
+    respond(member: M, ask: Ask & {
+        result: true;
+    }): Promise<ResponseResult>;
     respond(member: M, ask: Ask & {
         tools?: undefined;
+        result?: false;
     }): Promise<string>;
     respond(member: M, ask: Ask & {
         tools: ResponseTool[];
     }): Promise<ResponseResult>;
+    respond(member: M, ask: Ask): Promise<string | ResponseResult>;
+    /** Bind this member's existing ChatGPT subscription login for consumers such as decide. Each request uses
+     * the current sign-in and Accounts' refresh/limit/sign-out handling; the handle exposes no credentials. */
+    chatgpt(member: M): ChatGPTRespondAccount;
     /** An account's error, acted on. A limit or overload rests it (until when it said, or a default). A plan without this
      *  use is marked so. A refusal is checked: a sign-in that no longer refreshes is signed out for real, one that still
      *  does was a passing refusal and rests a few minutes (kind `overloaded`) rather than loop. Returns the kind acted on,

package/dist/accounts.js

@@ -51,7 +51,7 @@ export class Accounts {
     onExpired;
     onSignOutError;
     platform;
-    /** Offered: the providers named in `offer`, else every provider not hidden that this platform can sign in to. */
+    /** Offered: the providers named in `offer`, else every subscription provider that this platform can sign in to. */
     constructor(opts = {}, platform = portable) {
         this.opts = opts;
         this.platform = platform;
@@ -300,7 +300,7 @@ export class Accounts {
         const { access, accountId } = await this.access(member);
         try {
             const base = { ...ask, access, accountId, model: ask.model ?? p.models.strong, base: this.opts.apiBase, fetch: this.opts.fetch, originator: ask.originator ?? this.opts.originator };
-            return ask.tools ? await respond({ ...base, tools: ask.tools }) : await respond({ ...base, tools: undefined });
+            return await respond(base);
         }
         catch (e) {
             if (e instanceof ResponseError && e.kind && e.kind !== 'network') {
@@ -311,6 +311,12 @@ export class Accounts {
             throw e;
         }
     }
+    /** Bind this member's existing ChatGPT subscription login for consumers such as decide. Each request uses
+     * the current sign-in and Accounts' refresh/limit/sign-out handling; the handle exposes no credentials. */
+    chatgpt(member) {
+        this.offer('chatgpt');
+        return { billing: 'subscription', respond: (ask) => this.respond(member, ask) };
+    }
     /** An account's error, acted on. A limit or overload rests it (until when it said, or a default). A plan without this
      *  use is marked so. A refusal is checked: a sign-in that no longer refreshes is signed out for real, one that still
      *  does was a passing refusal and rests a few minutes (kind `overloaded`) rather than loop. Returns the kind acted on,

package/dist/catalogue.d.ts

@@ -1,9 +1,8 @@
-export type Terms = 'allowed' | 'grey' | 'partner' | 'forbidden';
 /** How the person pays: their plan (`subscription`), or per-use charges to their account (`api`, never offered by default). */
 export type Billing = 'subscription' | 'api';
 /** Terms assessment for choosing between several accounts; descriptive, never an eligibility gate. */
 export type MultiAccountTerms = {
-    terms: Terms;
+    terms: 'allowed' | 'grey' | 'partner' | 'forbidden';
     why: string;
     source: string;
 };
@@ -25,14 +24,11 @@ export type Provider = {
     auth?: 'api-key' | 'oauth';
     label?: string;
     offer?: boolean;
-    terms: Terms;
-    hidden: boolean;
-    why: string;
     source: string;
     multiAccount: MultiAccountTerms;
 };
 export declare const PROVIDERS: Record<string, Provider>;
 export declare function provider(key: string): Provider;
-/** What an app offers: the keys it names, in its order, or every subscription provider not hidden by default.
+/** What an app offers: the keys it names, in its order, or every subscription provider by default.
  *  API-billed rows are never in the default: an app offers them only by naming them. */
 export declare const offered: (keys?: readonly string[]) => Provider[];

package/dist/catalogue.js

@@ -1,7 +1,3 @@
-// The AI accounts a person can bring, by the name they know, with each provider's billing and terms status as data
-// (catalogue.json, readable from Kotlin too). The kit labels; the app decides what to offer. API-billed rows are never
-// offered by default; an app names them explicitly. Anthropic here is the app-passed API-key route; authentication
-// is separate from Messages, allowing additional opt-in auth routes to be implemented independently.
 import CATALOGUE from './catalogue.json' with { type: 'json' };
 export const PROVIDERS = Object.fromEntries(Object.entries(CATALOGUE).map(([key, p]) => [key, { key, ...p }]));
 export function provider(key) {
@@ -10,6 +6,6 @@ export function provider(key) {
         throw Object.assign(new Error('no such AI account'), { status: 404 });
     return p;
 }
-/** What an app offers: the keys it names, in its order, or every subscription provider not hidden by default.
+/** What an app offers: the keys it names, in its order, or every subscription provider by default.
  *  API-billed rows are never in the default: an app offers them only by naming them. */
-export const offered = (keys) => keys ? keys.map(provider) : Object.values(PROVIDERS).filter((p) => !p.hidden && p.offer !== false && p.billing === 'subscription');
+export const offered = (keys) => keys ? keys.map(provider) : Object.values(PROVIDERS).filter((p) => p.billing === 'subscription');

package/dist/catalogue.json

@@ -11,9 +11,6 @@
         "clientId": "app_EMoamEEZ73f0CkXaXp7hrann",
         "revoke": "https://auth.openai.com/oauth/revoke",
         "billing": "subscription",
-        "terms": "grey",
-        "hidden": false,
-        "why": "Signs in through Codex's own sign-in. OpenAI documents it for Codex, not for other apps, and has endorsed one other app using it.",
         "source": "https://developers.openai.com/codex/auth",
         "multiAccount": {
             "terms": "grey",
@@ -29,9 +26,6 @@
             "strong": "moonshotai/kimi-k2.6"
         },
         "billing": "api",
-        "terms": "allowed",
-        "hidden": false,
-        "why": "Documented sign-in for any app, no registration. Pay-as-you-go credits, not a subscription.",
         "source": "https://openrouter.ai/docs/guides/overview/auth/oauth",
         "multiAccount": {
             "terms": "grey",
@@ -47,9 +41,6 @@
             "strong": "grok-4.7"
         },
         "billing": "subscription",
-        "terms": "partner",
-        "hidden": true,
-        "why": "xAI allows plan sign-in only in apps it has partnered with.",
         "source": "https://x.ai/news/grok-opencode",
         "multiAccount": {
             "terms": "grey",
@@ -65,9 +56,6 @@
             "strong": "gpt-5.4"
         },
         "billing": "subscription",
-        "terms": "partner",
-        "hidden": true,
-        "why": "GitHub allows Copilot sign-in only in apps it has partnered with; this uses VS Code's client.",
         "source": "https://github.blog/changelog/2026-01-16-github-copilot-now-supports-opencode",
         "multiAccount": {
             "terms": "grey",
@@ -83,12 +71,9 @@
             "strong": "claude-opus-5-5"
         },
         "billing": "api",
-        "terms": "allowed",
-        "hidden": false,
         "auth": "api-key",
         "label": "API key (billed per use)",
         "offer": false,
-        "why": "The app passes an Anthropic API key explicitly. API key (billed per use), never a default or subscription fallback.",
         "source": "https://platform.claude.com/docs/en/api/overview",
         "multiAccount": {
             "terms": "grey",
@@ -107,14 +92,73 @@
         "clientId": "9d1c250a-e61b-44d9-88ed-5944d1962f5e",
         "billing": "subscription",
         "auth": "oauth",
-        "terms": "grey",
-        "hidden": false,
-        "why": "Anthropic prohibits third-party Claude.ai sign-in without approval; this route may stop working or lead to account restrictions.",
         "source": "https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use",
         "multiAccount": {
             "terms": "grey",
             "why": "This source does not explicitly document choosing between several accounts of this service in another app.",
             "source": "https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use"
         }
+    },
+    "kimi": {
+        "pi": "kimi-coding",
+        "name": "Kimi",
+        "company": "Moonshot AI",
+        "models": {
+            "strong": "k3",
+            "fast": "kimi-for-coding-highspeed"
+        },
+        "billing": "subscription",
+        "source": "https://www.kimi.com",
+        "multiAccount": {
+            "terms": "grey",
+            "why": "This source does not explicitly document choosing between several accounts of this service in another app.",
+            "source": "https://www.kimi.com"
+        }
+    },
+    "meta": {
+        "pi": "meta",
+        "name": "Meta",
+        "company": "Meta",
+        "models": {
+            "strong": "muse-spark-1.3"
+        },
+        "billing": "subscription",
+        "source": "https://www.meta.ai",
+        "multiAccount": {
+            "terms": "grey",
+            "why": "This source does not explicitly document choosing between several accounts of this service in another app.",
+            "source": "https://www.meta.ai"
+        }
+    },
+    "qwen": {
+        "pi": "qwen-portal",
+        "name": "Qwen",
+        "company": "Alibaba",
+        "models": {
+            "strong": "qwen3-coder-plus"
+        },
+        "billing": "subscription",
+        "source": "https://chat.qwen.ai",
+        "multiAccount": {
+            "terms": "grey",
+            "why": "This source does not explicitly document choosing between several accounts of this service in another app.",
+            "source": "https://chat.qwen.ai"
+        }
+    },
+    "minimax": {
+        "pi": "minimax",
+        "name": "MiniMax",
+        "company": "MiniMax",
+        "models": {
+            "strong": "MiniMax-M3",
+            "fast": "MiniMax-M2.7-highspeed"
+        },
+        "billing": "subscription",
+        "source": "https://www.minimax.io",
+        "multiAccount": {
+            "terms": "grey",
+            "why": "This source does not explicitly document choosing between several accounts of this service in another app.",
+            "source": "https://www.minimax.io"
+        }
     }
 }

package/dist/chatgpt-plan.d.ts

@@ -1,3 +1,11 @@
+import type { Ask, ResponseResult } from './responses.ts';
+/** A member-bound Accounts ChatGPT subscription handle. Credentials stay inside Accounts. */
+export type ChatGPTRespondAccount = {
+    readonly billing: 'subscription';
+    respond(ask: Ask & {
+        result: true;
+    }): Promise<ResponseResult>;
+};
 /** A host-owned, validated Sign in with ChatGPT token-sharing session. The host completes the official
  * OAuth flow (including ID-token verification), stores it per person, and refreshes it before returning it.
  * This adapter never discovers credentials, starts a login, or substitutes a Codex credential. */

package/dist/chatgpt-plan.js

@@ -12,7 +12,7 @@ export function chatgptPlan(o) {
             const session = await o.session(signal);
             if (!session || !Array.isArray(session.scopes) || !session.scopes.includes('chatgpt.tokens.use.direct') ||
                 !session.scopes.includes('resource.invoke') || typeof session.accessToken !== 'string' || !session.accessToken.trim()) {
-                throw new UnsupportedAccountError('ChatGPT plan usage needs a consented token-sharing session.');
+                throw new UnsupportedAccountError('This needs a ChatGPT sign-in that allows plan use.');
             }
             return session.accessToken;
         },

package/dist/cli.d.ts

@@ -0,0 +1,65 @@
+import type { AccountLike } from './multi.ts';
+export type CliProvider = 'claude' | 'codex';
+/** Shared selection surface; the CLI entry remains Node-only. */
+export type CliAccount = AccountLike & {
+    provider: CliProvider;
+    billing: 'subscription';
+    email?: string;
+    plan?: string;
+};
+export type CliOptions = {
+    stateDir: string;
+    bins: Partial<Record<CliProvider, string>>;
+    env: {
+        PATH: string;
+        HOME: string;
+    } & Record<string, string>;
+    historyFrom?: Partial<Record<CliProvider, string>>;
+    prepare?: (folder: string, provider: CliProvider) => Promise<void>;
+};
+export type SignInCommand = {
+    argv: string[];
+    env: Record<string, string>;
+    completion: string;
+    shell: string;
+};
+export declare class CliAccountError extends Error {
+    name: string;
+    readonly code: 'unknown-account' | 'invalid-name' | 'kind-mismatch' | 'prepare-failed' | 'bad-option';
+    constructor(code: CliAccountError['code']);
+}
+/** Only app-managed folders and explicitly supplied absolute CLI binaries. */
+export declare function cliAccounts(options: CliOptions): {
+    list: () => Promise<CliAccount[]>;
+    add(provider: CliProvider): Promise<{
+        account: CliAccount;
+        signIn: SignInCommand;
+    }>;
+    signInAgain: (id: string) => SignInCommand;
+    status: (id: string) => Promise<CliAccount>;
+    cancel(id: string): Promise<{
+        removed: boolean;
+    }>;
+    rename(id: string, name: string): Promise<CliAccount>;
+    remove: (id: string) => Promise<void>;
+    launchEnv: (id: string) => {
+        set: {
+            [x: string]: string;
+        };
+        unset: string[];
+    };
+    kinds: (provider: CliProvider) => string[];
+    resumeArgs(kind: string, ref: {
+        kind: "id" | "path";
+        value: string;
+    }): string[];
+    usageSource(id: string): {
+        provider: "codex";
+        bin: string;
+        home: string;
+        env: Record<string, string>;
+    } | undefined;
+    termsAcknowledged: () => boolean;
+    acknowledgeTerms: () => void;
+    suggestName: (email: string | undefined, provider: CliProvider) => string;
+};

package/dist/cli.js

@@ -0,0 +1,337 @@
+import { spawn } from 'node:child_process';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { chmodSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { identity } from '@byokit/usage';
+import { say } from "./words.js";
+export class CliAccountError extends Error {
+    name = 'CliAccountError';
+    code;
+    constructor(code) {
+        super(say({ 'unknown-account': 'cli.unknownAccount', 'invalid-name': 'cli.invalidName', 'kind-mismatch': 'cli.kindMismatch', 'prepare-failed': 'cli.prepareFailed', 'bad-option': 'cli.badOption' }[code]));
+        this.code = code;
+    }
+}
+const record = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const text = (v) => typeof v === 'string' && !v.includes('\0');
+const providers = ['claude', 'codex'];
+const shed = {
+    claude: ['CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY', 'CLAUDE_CODE_USE_ANTHROPIC_AWS', 'CLAUDE_CODE_USE_MANTLE', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_API_KEY', 'CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_PROFILE', 'ANTHROPIC_FEDERATION_RULE_ID'],
+    codex: ['OPENAI_API_KEY', 'CODEX_API_KEY'],
+};
+const folderVar = (p) => p === 'claude' ? 'CLAUDE_CONFIG_DIR' : 'CODEX_HOME';
+const quote = (v) => `'${v.replaceAll("'", "'\\''")}'`;
+const complete = (r) => join(r.folder, '.byokit-signin-complete');
+const pending = (r) => join(r.folder, '.byokit-signin-pending');
+function marker(file) {
+    try {
+        const stat = lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new CliAccountError('bad-option');
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+function json(file) {
+    let fd;
+    try {
+        fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.size > 256 * 1024)
+            return undefined;
+        const data = Buffer.alloc(256 * 1024 + 1);
+        let n = 0;
+        while (n < data.length) {
+            const count = readSync(fd, data, n, data.length - n, null);
+            if (!count)
+                break;
+            n += count;
+        }
+        return n < data.length ? JSON.parse(data.subarray(0, n).toString('utf8')) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function directory(path, create = false) {
+    try {
+        const s = lstatSync(path);
+        return s.isDirectory() && !s.isSymbolicLink();
+    }
+    catch (error) {
+        if (create && error.code === 'ENOENT') {
+            mkdirSync(path, { mode: 0o700 });
+            return true;
+        }
+        return false;
+    }
+}
+/** Only app-managed folders and explicitly supplied absolute CLI binaries. */
+export function cliAccounts(options) {
+    if (!record(options) || !text(options.stateDir) || !isAbsolute(options.stateDir) || !record(options.bins) || !record(options.env) || !text(options.env.PATH) || !text(options.env.HOME) || !isAbsolute(options.env.HOME))
+        throw new CliAccountError('bad-option');
+    if (Object.entries(options.env).some(([k, v]) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(k) || !text(v)))
+        throw new CliAccountError('bad-option');
+    if (Object.entries(options.bins).some(([p, bin]) => !providers.includes(p) || !text(bin) || !isAbsolute(bin)))
+        throw new CliAccountError('bad-option');
+    if (options.historyFrom && (!record(options.historyFrom) || Object.entries(options.historyFrom).some(([p, path]) => !providers.includes(p) || !text(path) || !isAbsolute(path))))
+        throw new CliAccountError('bad-option');
+    const stateDir = resolve(options.stateDir);
+    const env = { ...options.env };
+    const bins = { ...options.bins };
+    const history = { ...options.historyFrom };
+    for (const path of ['.claude', '.codex', '.pi']) {
+        const own = join(resolve(env.HOME), path);
+        if (stateDir === own || stateDir.startsWith(own + '/'))
+            throw new CliAccountError('bad-option');
+    }
+    // Parents must already be app-owned. Never follow a state/provider/folder symlink.
+    try {
+        if (realpathSync(dirname(stateDir)) !== dirname(stateDir))
+            throw new CliAccountError('bad-option');
+    }
+    catch {
+        throw new CliAccountError('bad-option');
+    }
+    if (!directory(stateDir, true))
+        throw new CliAccountError('bad-option');
+    chmodSync(stateDir, 0o700);
+    const file = join(stateDir, 'accounts-v1.json');
+    const created = new Set();
+    const operations = new Map();
+    function safe(r) {
+        const parent = join(stateDir, r.provider);
+        return resolve(r.folder) === r.folder && r.folder.startsWith(parent + '/') && /^[a-f0-9]+$/.test(r.folder.slice(parent.length + 1)) && directory(stateDir) && realpathSync(stateDir) === stateDir && directory(parent) && directory(r.folder);
+    }
+    function load() {
+        if (!directory(stateDir) || realpathSync(stateDir) !== stateDir)
+            throw new CliAccountError('bad-option');
+        const saved = json(file);
+        if (!record(saved) || !Array.isArray(saved.accounts))
+            return [];
+        const seen = new Set();
+        const rows = [];
+        for (const candidate of saved.accounts) {
+            if (!record(candidate) || !text(candidate.id) || !candidate.id || candidate.id.length > 128 || seen.has(candidate.id) || !providers.includes(candidate.provider) || !text(candidate.name) || candidate.name.length > 64 || !text(candidate.folder) || typeof candidate.found !== 'boolean')
+                continue;
+            const r = { id: candidate.id, provider: candidate.provider, name: candidate.name, folder: candidate.folder, found: candidate.found };
+            // Host-owned rows remain byte-compatible in the roster, without touching their folder.
+            if (!r.found && !r.id.startsWith('found-') && !safe(r))
+                continue;
+            seen.add(r.id);
+            rows.push(r);
+        }
+        return rows;
+    }
+    function atomic(path, value) {
+        if (!directory(stateDir) || realpathSync(stateDir) !== stateDir)
+            throw new CliAccountError('bad-option');
+        const tmp = `${path}.${randomUUID()}.tmp`;
+        try {
+            writeFileSync(tmp, JSON.stringify(value), { mode: 0o600, flag: 'wx' });
+            renameSync(tmp, path);
+        }
+        catch {
+            throw new CliAccountError('prepare-failed');
+        }
+        finally {
+            rmSync(tmp, { force: true });
+        }
+    }
+    const save = (rows) => atomic(file, { version: 1, accounts: rows });
+    function row(id) {
+        const r = load().find((r) => r.id === id && !r.found && !r.id.startsWith('found-'));
+        if (!r)
+            throw new CliAccountError('unknown-account');
+        return r;
+    }
+    function binary(p) { const bin = bins[p]; if (!bin)
+        throw new CliAccountError('bad-option'); return bin; }
+    function launch(r) { return { set: { [folderVar(r.provider)]: r.folder }, unset: [...shed[r.provider]] }; }
+    function spawnEnv(r) {
+        const out = { ...env };
+        for (const key of shed[r.provider])
+            delete out[key];
+        delete out.CLAUDE_CONFIG_DIR;
+        delete out.CODEX_HOME;
+        return { ...out, ...launch(r).set };
+    }
+    function command(r) {
+        const argv = r.provider === 'claude' ? [binary(r.provider), 'auth', 'login', '--claudeai'] : [binary(r.provider), 'login', '--device-auth'];
+        const passed = spawnEnv(r);
+        const completion = complete(r);
+        const lock = join(r.folder, '.byokit-signin-lock');
+        const login = ['/usr/bin/env', '-i', ...Object.entries(passed).map(([k, v]) => `${k}=${v}`), ...argv].map(quote).join(' ');
+        // Cross-process guard: a native CLI owns any refresh transaction; the kit never copies or refreshes its grants.
+        const shell = `(umask 077; /bin/mkdir ${quote(lock)} || exit 1; trap ${quote(`/bin/rmdir ${quote(lock)}`)} EXIT; ${login} && (set -C; printf complete > ${quote(completion)}))`;
+        return { argv, env: passed, completion, shell };
+    }
+    function begin(r) {
+        const result = command(r);
+        // Refuse overlapping sign-in starts; reuse the pending command until completion or cancel.
+        if (!marker(pending(r)) || marker(complete(r))) {
+            rmSync(complete(r), { force: true });
+            if (!marker(pending(r)))
+                writeFileSync(pending(r), '', { mode: 0o600, flag: 'wx' });
+        }
+        return result;
+    }
+    function serial(id, action) {
+        const task = (operations.get(id) ?? Promise.resolve()).then(action, action);
+        operations.set(id, task);
+        return task.finally(() => { if (operations.get(id) === task)
+            operations.delete(id); });
+    }
+    async function readIdentity(r) {
+        if (r.provider === 'codex')
+            return identity({ provider: 'codex', bin: binary('codex'), home: r.folder, env: spawnEnv(r) });
+        return new Promise((accept) => {
+            const child = spawn(binary('claude'), ['auth', 'status'], { env: spawnEnv(r), stdio: ['ignore', 'pipe', 'ignore'] });
+            let stdout = '';
+            let bytes = 0;
+            let settled = false;
+            let escalation;
+            const finish = (answer) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (child.exitCode === null && child.signalCode === null) {
+                    child.kill('SIGTERM');
+                    escalation = setTimeout(() => { if (child.exitCode === null && child.signalCode === null)
+                        child.kill('SIGKILL'); }, 1000);
+                }
+                accept(answer);
+            };
+            const timer = setTimeout(() => finish({ signedIn: false }), 15_000);
+            child.once('error', () => finish({ signedIn: false }));
+            child.stdout.setEncoding('utf8');
+            child.stdout.on('data', (chunk) => {
+                if (settled)
+                    return;
+                bytes += Buffer.byteLength(chunk);
+                if (bytes > 256 * 1024) {
+                    finish({ signedIn: false });
+                    return;
+                }
+                stdout += chunk;
+            });
+            child.once('close', () => {
+                clearTimeout(escalation);
+                if (settled)
+                    return;
+                if (bytes > 64 * 1024) {
+                    finish({ signedIn: false });
+                    return;
+                }
+                let raw;
+                try {
+                    raw = JSON.parse(stdout);
+                }
+                catch {
+                    finish({ signedIn: false });
+                    return;
+                }
+                if (!record(raw) || raw.loggedIn !== true) {
+                    finish({ signedIn: false });
+                    return;
+                }
+                const email = typeof raw.email === 'string' && raw.email.length <= 320 && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(raw.email) ? raw.email : undefined;
+                const plan = [raw.subscriptionType, raw.plan, raw.planName, raw.tier].find((v) => typeof v === 'string' && /^[a-zA-Z][a-zA-Z0-9 _+-]{0,63}$/.test(v));
+                finish({ signedIn: true, ...(email ? { email } : {}), ...(typeof plan === 'string' ? { plan } : {}) });
+            });
+        });
+    }
+    function suggestName(email, provider) {
+        const first = email?.split('@')[0]?.split(/[._-]+/).find(Boolean);
+        return first ? (first[0].toUpperCase() + first.slice(1).toLowerCase()).slice(0, 64) : provider === 'claude' ? 'Claude' : 'Codex';
+    }
+    async function status(id) {
+        return serial(id, async () => {
+            const r = row(id);
+            const signing = marker(pending(r)) && !marker(complete(r));
+            if (signing)
+                return { id: r.id, provider: r.provider, name: r.name.trim() || suggestName(undefined, r.provider), billing: 'subscription', state: 'signing' };
+            const info = await readIdentity(r);
+            if (marker(pending(r)))
+                rmSync(pending(r), { force: true });
+            // Pre-existing roster rows have no kit marker; their native status remains authoritative.
+            return { id: r.id, provider: r.provider, name: r.name.trim() || suggestName(info.email, r.provider), billing: 'subscription', state: info.signedIn ? 'ready' : 'signed_out', ...(info.email ? { email: info.email } : {}), ...(info.plan ? { plan: info.plan } : {}) };
+        });
+    }
+    async function remove(id) {
+        return serial(id, async () => { const r = row(id); rmSync(r.folder, { recursive: true, force: true }); save(load().filter((v) => v.id !== id)); created.delete(id); });
+    }
+    return {
+        list: async () => Promise.all(load().filter((r) => !r.found && !r.id.startsWith('found-')).map((r) => status(r.id))),
+        async add(provider) {
+            if (!providers.includes(provider))
+                throw new CliAccountError('bad-option');
+            binary(provider);
+            const parent = join(stateDir, provider);
+            if (!directory(stateDir) || !directory(parent, true))
+                throw new CliAccountError('bad-option');
+            chmodSync(parent, 0o700);
+            const r = { id: `pa_${randomBytes(9).toString('hex')}`, provider, name: '', folder: join(parent, randomBytes(8).toString('hex')), found: false };
+            mkdirSync(r.folder, { mode: 0o700 });
+            try {
+                if (history[provider])
+                    symlinkSync(history[provider], join(r.folder, provider === 'claude' ? 'projects' : 'sessions'), 'dir');
+                const signIn = begin(r);
+                await options.prepare?.(r.folder, provider);
+                if (!safe(r))
+                    throw new CliAccountError('prepare-failed');
+                save([...load(), r]);
+                created.add(r.id);
+                return { account: { id: r.id, provider, name: suggestName(undefined, provider), billing: 'subscription', state: 'signing' }, signIn };
+            }
+            catch {
+                rmSync(r.folder, { recursive: true, force: true });
+                throw new CliAccountError('prepare-failed');
+            }
+        },
+        signInAgain: (id) => {
+            if (operations.has(id))
+                throw new CliAccountError('prepare-failed');
+            return begin(row(id));
+        },
+        status,
+        async cancel(id) {
+            if (created.has(id)) {
+                await remove(id);
+                return { removed: true };
+            }
+            return serial(id, async () => { const r = row(id); rmSync(pending(r), { force: true }); return { removed: false }; });
+        },
+        async rename(id, name) {
+            if (!text(name) || !name.trim() || name.trim().length > 64 || /[\x00-\x1f\x7f]/.test(name))
+                throw new CliAccountError('invalid-name');
+            await serial(id, async () => { row(id); const rows = load(); rows.find((r) => r.id === id).name = name.trim(); save(rows); });
+            return status(id);
+        },
+        remove,
+        launchEnv: (id) => launch(row(id)),
+        kinds: (provider) => providers.includes(provider) ? [provider] : [],
+        resumeArgs(kind, ref) {
+            if (!text(ref.value) || !ref.value || (kind !== 'claude' && kind !== 'codex') || (kind === 'claude' && ref.kind !== 'id') || (kind === 'codex' && ref.kind !== 'id'))
+                throw new CliAccountError('kind-mismatch');
+            return kind === 'claude' ? ['--resume', ref.value] : ['resume', ref.value];
+        },
+        usageSource(id) {
+            const r = row(id);
+            return r.provider === 'codex' ? { provider: 'codex', bin: binary('codex'), home: r.folder, env: spawnEnv(r) } : undefined;
+        },
+        termsAcknowledged: () => { if (!directory(stateDir))
+            throw new CliAccountError('bad-option'); const saved = json(join(stateDir, 'auto-terms-v1.json')); return record(saved) && saved.acknowledged === true; },
+        acknowledgeTerms: () => atomic(join(stateDir, 'auto-terms-v1.json'), { acknowledged: true }),
+        suggestName,
+    };
+}

package/dist/portable.d.ts

@@ -1,11 +1,11 @@
 export { Accounts, planOf, portable, type AccountsOptions, type ClaudePlanAsk, type AnthropicAccountAsk, type AuthHost, type Loopback, type Member, type Platform, type SignIn, type Status } from './accounts.ts';
-export { PROVIDERS, offered, provider, type Billing, type MultiAccountTerms, type Provider, type Terms } from './catalogue.ts';
+export { PROVIDERS, offered, provider, type Billing, type MultiAccountTerms, type Provider } from './catalogue.ts';
 export { PORTABLE, claims, credentialOf, devicePoll, deviceStart, portableEngine, type EngineOptions, type Poll } from './engine.ts';
 export { REST_MS, classify, classifyFailure, type Failure, type Kind } from './limits.ts';
-export { IncompleteError, ResponseError, isFunctionCall, limitResponse, respond, sseReader, type Ask, type ResponseFunctionCall, type ResponseInputItem, type ResponseOutputItem, type ResponseOutputMessage, type ResponseReasoning, type ResponseResult, type ResponseStreamEvent, type ResponseText, type ResponseTextFormat, type ResponseTool, type ResponseToolChoice } from './responses.ts';
+export { IncompleteError, ResponseError, isFunctionCall, limitResponse, respond, sseReader, type Ask, type ResponseFunctionCall, type ResponseInputItem, type ResponseOutputItem, type ResponseOutputMessage, type ResponseReasoning, type ResponseResult, type ResponseUsage, type ResponseStreamEvent, type ResponseText, type ResponseTextFormat, type ResponseTool, type ResponseToolChoice } from './responses.ts';
 export { browserStore, keystoreStore, memoryStore, recordStore, secureStore, RefreshRequiredError, type RefreshStore, type SecureStoreLike } from './stores.ts';
 export { WORDS, billingWords, callbackPage, clock, failure, say, signInError, type WordKey, type Why } from './words.ts';
-export { chatgptPlan, UnsupportedAccountError, type ChatGPTPlanAccount, type ChatGPTPlanSession } from './chatgpt-plan.ts';
+export { chatgptPlan, UnsupportedAccountError, type ChatGPTPlanAccount, type ChatGPTRespondAccount, type ChatGPTPlanSession } from './chatgpt-plan.ts';
 export { anthropic, anthropicSseReader, AnthropicIncompleteError, type AnthropicAsk, type AnthropicCacheControl, type AnthropicContent, type AnthropicImage, type AnthropicMessage, type AnthropicOptions, type AnthropicRequest, type AnthropicResponse, type AnthropicResult, type AnthropicStreamEvent, type AnthropicText, type AnthropicThinking, type AnthropicTool, type AnthropicToolChoice, type AnthropicToolUse, type AnthropicUsage } from './anthropic.ts';
 export { ClaudePlanExpiredError, ClaudePlanPlatformError, claudeAuthorization, claudeCode, type ClaudePlanOptions } from './claude-plan.ts';
 export { chooseAccount, resolveSelection, roomOf, roomWords, type AccountLike, type AccountPick, type Considered, type Defaults, type PickWhy, type Room, type RoomSpan, type RunSelection, type SignInState } from './multi.ts';

package/dist/responses.d.ts

@@ -128,10 +128,17 @@ export type ResponseOutputItem = ResponseOutputMessage | ResponseFunctionCall |
 };
 /** Whether an output item is a function call, so an app can answer it with a `function_call_output` turn. */
 export declare const isFunctionCall: (item: ResponseOutputItem) => item is ResponseFunctionCall;
-/** The model's answer: the text (`onText` saw it piece by piece) and every output item. */
+/** Provider-reported token counts, with native details retained. Missing usage is never guessed. */
+export type ResponseUsage = {
+    input_tokens: number;
+    output_tokens: number;
+    [key: string]: unknown;
+};
+/** The model's answer: text, output items and token usage when the provider reports it. */
 export type ResponseResult = {
     text: string;
     output: ResponseOutputItem[];
+    usage?: ResponseUsage;
 };
 /** What streams besides the words: each text piece, each tool call as it builds and lands, and each output item. */
 export type ResponseStreamEvent = {
@@ -166,6 +173,8 @@ export declare function sseReader(onText?: (delta: string) => void, onEvent?: (e
     result(): ResponseResult;
 };
 export type Ask = {
+    /** Return text, output items and reported usage even without tools. */
+    result?: boolean;
     /** What the model is told to be. */
     instructions: string;
     /** The person's words, or the turns so far: messages (with `input_image` where the person attached one) and, after a
@@ -201,10 +210,15 @@ type Access = {
 /** Ask ChatGPT with a signed-in token. `fetch`: pass one that streams (Expo's `expo/fetch`); any fetch works.
  *  Without `tools` the answer is the plain text, as before; with `tools` it is the text with every output item.
  *  Incomplete answers always throw IncompleteError and notify onEvent, including with tools. */
+export declare function respond(o: Ask & Access & {
+    result: true;
+}): Promise<ResponseResult>;
 export declare function respond(o: Ask & Access & {
     tools?: undefined;
+    result?: false;
 }): Promise<string>;
 export declare function respond(o: Ask & Access & {
     tools: ResponseTool[];
 }): Promise<ResponseResult>;
+export declare function respond(o: Ask & Access): Promise<string | ResponseResult>;
 export {};

package/dist/responses.js

@@ -58,6 +58,7 @@ export function sseReader(onText, onEvent) {
     let buffer = '', text = '', completed;
     let done = false, finished;
     let incomplete;
+    let usage;
     const output = [];
     const emitted = new Set();
     const calls = new Map();
@@ -115,6 +116,8 @@ export function sseReader(onText, onEvent) {
         }
         if (e.type === 'response.completed' || e.type === 'response.incomplete' || e.response?.status === 'incomplete') {
             done = true;
+            if (isRecord(e.response?.usage))
+                usage = { ...e.response.usage };
             if (Array.isArray(e.response?.output)) {
                 for (const [i, item] of e.response.output.entries())
                     land(item, i);
@@ -155,7 +158,7 @@ export function sseReader(onText, onEvent) {
                 throw new ResponseError('ChatGPT stopped before completing its answer.', 'network');
             if (text === '' && whole !== '')
                 onText?.(whole);
-            finished = { text: whole, output };
+            finished = { text: whole, output, ...(usage && { usage }) };
         }
         if (incomplete !== undefined)
             throw new IncompleteError(incomplete, finished);
@@ -214,5 +217,5 @@ export async function respond(o) {
     else {
         reader.push(await res.text()); // a fetch that can't stream: the whole answer at once
     }
-    return o.tools ? reader.result() : reader.end();
+    return o.tools || o.result ? reader.result() : reader.end();
 }

package/dist/testing/index.d.ts

@@ -18,4 +18,4 @@ export declare function decoy(root: string): {
     /** Marks left by the decoy's extension or CLIs: something ran code from someone else's setup. */
     ran: () => string[];
 };
-export { mockJwt, mockOpenAI, type MockOpenAIOptions } from './mock-openai.ts';
+export { mockJwt, mockOpenAI, type MockOpenAIAnswer, type MockOpenAIOptions } from './mock-openai.ts';

package/dist/testing/mock-openai.d.ts

@@ -1,14 +1,23 @@
+import type { ResponseUsage } from '../responses.ts';
+/** First matching script wins. Strings match a substring; regexes and predicates inspect the joined input text.
+ * Unmatched prompts retain the echo/tool behavior. Counts are supplied explicitly, never estimated. */
+export type MockOpenAIAnswer = {
+    match: string | RegExp | ((prompt: string) => boolean);
+    text: string;
+    usage?: ResponseUsage;
+};
 export type MockOpenAIOptions = {
     port?: number;
     host?: string;
     plan?: string;
     email?: string;
     expiresIn?: number;
+    answers?: readonly MockOpenAIAnswer[];
     log?: (line: string) => void;
 };
 /** An access token as OpenAI shapes it: the account, the plan and the email in its claims. */
 export declare const mockJwt: (plan?: string, email?: string, n?: number) => string;
-export declare function mockOpenAI({ port, host, plan, email, expiresIn, log }?: MockOpenAIOptions): Promise<{
+export declare function mockOpenAI({ port, host, plan, email, expiresIn, answers, log }?: MockOpenAIOptions): Promise<{
     base: string;
     state: {
         /** Refresh tokens OpenAI still honours; a refresh spends the old one (rotation), sign-out revokes one. */
@@ -17,6 +26,8 @@ export declare function mockOpenAI({ port, host, plan, email, expiresIn, log }?:
             path: string;
             body: string;
         }[];
+        /** Scripts may be replaced between requests, without restarting the sign-in stand-in. */
+        answers: MockOpenAIAnswer[];
         /** Refuse every refresh, as when the person signed out elsewhere. */
         refuse: boolean;
         /** Seconds each issued token lives. */

package/dist/testing/mock-openai.js

@@ -11,13 +11,15 @@ export const mockJwt = (plan = 'plus', email = 'sara@example.com', n = 0) => ['e
         // As long as a real one, whose claims fill about 1.5 kB.
         scp: ['openid', 'profile', 'email', 'offline_access'], pad: 'x'.repeat(1200),
     })).toString('base64url'), 'sig'].join('.');
-export async function mockOpenAI({ port = 0, host = '127.0.0.1', plan = 'plus', email = 'sara@example.com', expiresIn = 864_000, log } = {}) {
+export async function mockOpenAI({ port = 0, host = '127.0.0.1', plan = 'plus', email = 'sara@example.com', expiresIn = 864_000, answers = [], log } = {}) {
     const codes = new Map();
     let issued = 0, asked = 0;
     const state = {
         /** Refresh tokens OpenAI still honours; a refresh spends the old one (rotation), sign-out revokes one. */
         live: new Set(),
         requests: [],
+        /** Scripts may be replaced between requests, without restarting the sign-in stand-in. */
+        answers: [...answers],
         /** Refuse every refresh, as when the person signed out elsewhere. */
         refuse: false,
         /** Seconds each issued token lives. */
@@ -115,12 +117,20 @@ export async function mockOpenAI({ port = 0, host = '127.0.0.1', plan = 'plus',
                             said.push(part.text);
                 }
                 const words = said.join(' ');
+                let scripted;
+                try {
+                    scripted = state.answers.find(({ match }) => typeof match === 'string' ? words.includes(match)
+                        : typeof match === 'function' ? match(words) : new RegExp(match.source, match.flags).test(words));
+                }
+                catch {
+                    return send(500, { error: { message: 'The stand-in could not match this prompt.' } });
+                }
                 const schema = asked.text?.format?.type === 'json_schema';
-                const text = answered !== undefined ? `You did: ${answered}`
+                const text = scripted ? scripted.text : answered !== undefined ? `You did: ${answered}`
                     : schema ? JSON.stringify({ echo: words ? `You said: ${words}` : 'You said nothing' })
                         : `You said: ${words}`;
                 const called = Array.isArray(asked.tools) ? asked.tools.filter((t) => t?.type === 'function') : [];
-                if (called.length > 0 && answered === undefined) {
+                if (!scripted && called.length > 0 && answered === undefined) {
                     // A tool turn: the model calls the first function tool, streamed as argument deltas and one finished item,
                     // then the completion with the output list. The app answers with a `function_call_output` turn next.
                     const name = String(called[0].name ?? 'tool');
@@ -140,7 +150,9 @@ export async function mockOpenAI({ port = 0, host = '127.0.0.1', plan = 'plus',
                     res.write(`event: response.output_text.delta\ndata: ${JSON.stringify({ type: 'response.output_text.delta', delta })}\n\n`);
                     await new Promise((r) => setTimeout(r, 5));
                 }
-                return res.end('event: response.completed\ndata: {"type":"response.completed","response":{"status":"completed"}}\n\ndata: [DONE]\n\n');
+                return res.end(`event: response.completed\ndata: ${JSON.stringify({ type: 'response.completed', response: {
+                        status: 'completed', ...(scripted?.usage && { usage: scripted.usage }),
+                    } })}\n\ndata: [DONE]\n\n`);
             }
             case '/oauth/revoke':
                 state.live.delete(json().token);

package/dist/words.json

@@ -57,5 +57,10 @@
     "pick.age": "Read {ago} ago",
     "pick.ageUnknown": "Reading time unknown",
     "ago.minutes": "{n} minutes",
-    "ago.hours": "{n} hours"
+    "ago.hours": "{n} hours",
+    "cli.unknownAccount": "Choose an account from the list.",
+    "cli.invalidName": "Give the account a name up to 64 characters.",
+    "cli.kindMismatch": "That agent cannot use this account.",
+    "cli.prepareFailed": "Could not prepare the account. Try again.",
+    "cli.badOption": "The app supplied invalid account options."
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/accounts",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Sign in with the AI plan you already pay for, into your app's own store.",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,6 +29,10 @@
       "types": "./dist/isolate.d.ts",
       "default": "./dist/isolate.js"
     },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "default": "./dist/cli.js"
+    },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "default": "./dist/testing/index.js"
@@ -48,6 +52,7 @@
     "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
   },
   "dependencies": {
+    "@byokit/usage": "0.5.0",
     "@earendil-works/pi-ai": "0.87.1"
   },
   "publishConfig": {