@byokit/accounts 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 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
@@ -119,7 +121,7 @@ and [`examples/pwa`](../../examples/pwa) (browser sign-in).
 | `Accounts` | Sign-in, status, sign-out, asking and limits for each member: `login`, `finished`, `status`, `plan`, `logout`, `respond`, `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.
 ```
@@ -438,8 +443,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 +554,38 @@ 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.

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

@@ -55,7 +55,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 +112,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;

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;

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.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,5 +1,5 @@
 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';

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.14.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.4.0",
     "@earendil-works/pi-ai": "0.87.1"
   },
   "publishConfig": {