@byokit/accounts 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## 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.

package/README.md

@@ -118,7 +118,7 @@ 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, models and source |
@@ -256,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.
@@ -332,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
@@ -589,3 +600,22 @@ Native status reads resolve within 15 seconds. Claude stdout is capped at 256 KB
 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/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`). */
@@ -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

@@ -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/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/portable.d.ts

@@ -2,10 +2,10 @@ export { Accounts, planOf, portable, type AccountsOptions, type ClaudePlanAsk, t
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/accounts",
-  "version": "0.14.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",
@@ -52,7 +52,7 @@
     "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
   },
   "dependencies": {
-    "@byokit/usage": "0.4.0",
+    "@byokit/usage": "0.5.0",
     "@earendil-works/pi-ai": "0.87.1"
   },
   "publishConfig": {