@byokit/accounts 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 0.5.0 (2026-09-29)
+
+- `respond` passes the whole question through: a message array (many turns, pictures with `input_image`, a `function_call` with its `function_call_output`), `tools` and `tool_choice` (the app's own function tools and built-ins, including `image_generation`), how hard the model thinks (`reasoning.effort`), and how long the answer is with the shape it must follow (`text.verbosity`, `text.format`). With `tools` the result is the text with every output item (`isFunctionCall` spots a call); without, the plain text as before. `onEvent` sees each tool call and output item as it streams.
+
 ## 0.4.1 (2026-09-29)
 
 - FIX: the packed `dist/words.d.ts` keeps `with { type: 'json' }` on its `./words.json` import, so a strict NodeNext consumer with `skipLibCheck: false` no longer fails with TS1543.

package/README.md

@@ -1,10 +1,75 @@
-# @byokit/accounts
+<h1 align="center">@byokit/accounts</h1>
 
-Sign in with the AI plan you already pay for (ChatGPT on every platform; OpenRouter on computers when an app offers it
-(API billing, never by default); Grok and GitHub Copilot hidden by default), inside your own app, 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 align="center">
+  <a href="https://www.npmjs.com/package/@byokit/accounts"><img alt="npm" src="https://img.shields.io/npm/v/@byokit/accounts?style=flat&label=npm" /></a>
+  <a href="https://github.com/umeranjum17/byokit/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/umeranjum17/byokit/ci.yml?style=flat&branch=main" /></a>
+  <a href="LICENSE"><img alt="Apache 2.0" src="https://img.shields.io/badge/license-Apache--2.0-666?style=flat" /></a>
+  <img alt="Node | Electron | browsers | React Native" src="https://img.shields.io/badge/platform-Node%20%7C%20Electron%20%7C%20browsers%20%7C%20React%20Native-666?style=flat" />
+</p>
+
+<p align="center"><strong>Sign in with the AI plan you already pay for, inside your own app.</strong><br/>
+ChatGPT on every platform; OpenRouter on computers when an app offers it (API billing, never by default); Grok and
+GitHub Copilot hidden by default. 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>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/docs/images/pwa-1-signed-out.png" width="240" alt="The page &quot;byokit in a browser&quot;, signed out: &quot;ChatGPT isn't signed in yet.&quot; above a Sign in with ChatGPT button" />
+  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/docs/images/pwa-2-code.png" width="240" alt="The same page signing in: &quot;Signing in to ChatGPT…&quot;, &quot;On the ChatGPT page, type this code:&quot; WDJB-MJHT, an Open ChatGPT link and a Cancel button" />
+  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/docs/images/pwa-3-connected.png" width="240" alt="The same page signed in: &quot;ChatGPT is connected.&quot;, sara@example.com, plus plan, with Check the sign-in and Sign out buttons" />
+</p>
+<p align="center"><sub><a href="../../examples/pwa"><code>examples/pwa</code></a> signing in by device code in headless Chromium (Playwright), against the kit's stand-in OpenAI (<code>mockOpenAI()</code>), not the real one; the pictured code is in OpenAI's format.</sub></p>
+
+## Install
+
+```sh
+npm install @byokit/accounts
+```
+
+[![npm](https://img.shields.io/npm/v/@byokit/accounts?style=flat&label=)](https://www.npmjs.com/package/@byokit/accounts) · [Latest release](https://github.com/umeranjum17/byokit/releases?q=accounts-v) · [All releases](https://github.com/umeranjum17/byokit/releases)
+
+## Quickstart
+
+```sh
+npm install @byokit/accounts
+```
+
+The whole ChatGPT flow, run against the stand-in OpenAI so it needs no account and no network beyond loopback: sign in
+by device code, see the status, ask.
+
+```ts
+import { Accounts, portable } from '@byokit/accounts';
+import { mockOpenAI } from '@byokit/accounts/testing';
+
+const openai = await mockOpenAI(); // a stand-in OpenAI on 127.0.0.1, no account needed
+const accounts = new Accounts(
+  { authBase: openai.base, apiBase: openai.base }, // default store: in memory
+  portable, // device code with fetch alone, as on a phone or in a browser
+);
+
+const shown = await accounts.login(1, 'chatgpt');
+console.log(shown?.state, shown?.via, shown?.code);
+openai.approve(shown!.code!); // the person types the code on the provider's page
+
+await accounts.finished(1, 'chatgpt'); // the whole sign-in, once the code is approved
+console.log((await accounts.status(1, 'chatgpt')).words);
+
+const answer = await accounts.respond(1, { instructions: 'Answer briefly.', input: 'Plan my day', onText: (d) => process.stdout.write(d) });
+console.log('\nfinal:', answer);
+await openai.close();
+```
+
+```text
+waiting code MOCK-10001
+ChatGPT is connected.
+You said: Plan my day
+final: You said: Plan my day
+```
+
+The stand-in echoes the question. In an app, drop `authBase`, `apiBase` and `portable`, and give each person a store,
+as below.
+
+### On a computer
 
 On a computer it uses Pi's [`@earendil-works/pi-ai`](https://www.npmjs.com/package/@earendil-works/pi-ai) sign-in
 flows, pinned exactly:
@@ -20,8 +85,10 @@ const shown = await accounts.login(1, 'chatgpt', { via: 'code' }); // { state: '
 (await accounts.status(1, 'chatgpt')).words;                     // "ChatGPT is connected."
 ```
 
-On a phone or in a browser the same `Accounts` signs in to ChatGPT by device code with `fetch` alone (Pi's flows need
-Node), into the phone's secure storage or the browser's IndexedDB:
+### On a phone or in a browser
+
+The same `Accounts` signs in to ChatGPT by device code with `fetch` alone (Pi's flows need Node), into the phone's
+secure storage or the browser's IndexedDB:
 
 ```ts
 import * as SecureStore from 'expo-secure-store';
@@ -32,23 +99,41 @@ const accounts = new Accounts({ store: (member) => secureStore(SecureStore, `byo
 const shown = await accounts.login(1, 'chatgpt'); // { state: 'waiting', via: 'code', code, url }: open url, show code
 ```
 
-Then ask ChatGPT with that sign-in, showing streamed pieces while it runs and the returned final answer when it finishes
-(the completion can correct earlier pieces):
+Then ask ChatGPT with that sign-in, showing streamed pieces while it runs and the returned final answer when it
+finishes (the completion can correct earlier pieces):
 
 ```ts
 const answer = await accounts.respond(1, { instructions: 'Answer briefly.', input: 'Plan my day', onText: (d) => show(d) });
 show(answer);
 ```
 
-Examples: [`examples/expo`](../../examples/expo) (iOS and Android bundles; Android emulator sign-in, asking, pairing) and
-[`examples/pwa`](../../examples/pwa) (browser sign-in).
+Examples: [`examples/expo`](../../examples/expo) (iOS and Android bundles; Android emulator sign-in, asking, pairing)
+and [`examples/pwa`](../../examples/pwa) (browser sign-in).
+
+## API at a glance
+
+| 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` |
+| `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 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 |
+| `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`, `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 |
+| `classify`, `REST_MS` | An error's kind (limit, overload, plan without this use, lapsed sign-in, network) and default rest times |
+| `planOf`, `claims` | The ChatGPT plan and email behind a sign-in, from its own token |
+| `deviceStart`, `devicePoll`, `credentialOf`, `portableEngine`, `PORTABLE` | The device-code flow, the sign-in built from a token answer, and the engine under `portable` |
+| `isolate`, `INHERITED`, `emptyAuthContext` (`/isolate`) | Scrub inherited Pi settings and provider keys; ambient discovery off |
+| `mockOpenAI`, `mockJwt`, `decoy`, `traceFs`, `CANARY` (`/testing`) | A stand-in OpenAI, and the decoy-HOME harness and fs tracer for isolation tests |
+
+`computer`, `loopback` and `fileStore` come from the Node entry only; `isolate` and `/testing` need Node too.
 
 ## Which sign-in works where
 
 | | Computer (Node, Electron main) | Browser (PWA, Electron renderer) | Phone (React Native: iOS, Android) |
 |---|---|---|---|
-| ChatGPT | Its own page, straight back to this computer (port 1455); a code when asked or stuck | Device code | Device code |
-| OpenRouter | Its own page, back to this computer (Pi's flow), when an app offers it (API billing, never by default) | Not yet | Not yet |
+| ChatGPT (subscription) | Its own page, straight back to this computer (port 1455); a code when asked or stuck | Device code | Device code |
+| 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 |
 | Where sign-ins are kept | `fileStore(path)`, sealed with Electron's `safeStorage` when given | `browserStore(name)` (IndexedDB) | `secureStore(SecureStore, name)` (Keychain, Keystore) |
 
@@ -57,46 +142,137 @@ listener on the computer the browser runs on, so it is desktop only: ChatGPT sen
 `localhost:1455`, fixed for the client this signs in as. A web page can't call ChatGPT's model endpoint itself (it
 doesn't answer other web pages), so a PWA's model calls go through the app's own server or relay.
 
-- **Catalogue** (`catalogue.json`): 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.
-  Claude plan sign-in is never offered: Anthropic reserves it for its own apps.
-- **Sign-in**: on computers, the provider's own page by default. For ChatGPT, whose page returns to this computer's
-  port 1455, the kit listens there itself, so the tab shows your app's words (`new Accounts({ app: 'My App' })`) and only once they are
-  true. A code takes over when asked ("Having trouble?"), when the page never comes back, or when the port is taken by
-  another sign-in. A 15-minute cap, nothing kept unless the engine can use it, and every failure is one plain sentence
-  (`words.json`) with a `why` for apps that word it themselves. `plan(member)` tells a work ChatGPT from a personal one.
-- **Sign-out**: `logout(member, key)` attempts to revoke a ChatGPT token at OpenAI (`POST auth.openai.com/oauth/revoke`),
-  then deletes the local sign-in even if the revoke fails. A failed revoke rejects after local deletion; report it because
-  the remote sign-in may remain active. Within one store instance, a refresh already in progress finishes first, so
-  sign-out uses its rotated token. If a cancelled sign-in finishes late, `onSignOutError` reports a failed revoke of its
-  discarded credential (or it is logged when no handler is set).
-- **One person, one store**: `memoryStore()`, `fileStore(path)` (0600, the same shape as Pi's `auth.json`),
-  `secureStore(SecureStore, name, options?)` or `browserStore(name)`; any other storage with `recordStore(load, save)`. Writes are
-  serialized within a store instance; `browserStore` also uses Web Locks across tabs for the same provider when available.
-  Never a shared fallback. Browser storage is readable by scripts on your page: avoid untrusted scripts. On a phone, pass
-  `{ keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY }` as `options` (to every get, set and delete) so
-  tokens never migrate to a new device through an iCloud/iTunes backup; without it Expo's default (`WHEN_UNLOCKED`)
-  applies. iOS Keychain items survive an app reinstall under the same bundle id (Android data is gone): apps that must
-  forget on reinstall keep a first-run marker outside the Keychain (e.g. `expo-file-system` or `AsyncStorage`) and, when
-  it is missing, call `accounts.logout(member, key)` for each offered key before first use, which revokes and wipes. Using another
-  engine with the same seam (Pi's coding-agent `ModelRuntime`)? Override `open(member)` with an engine whose
-  `credentialStore` is made with `boundStore(member, engineStore)` and whose `readCredential(id)` reads that store.
-- **Asking**: `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 `ResponseError` with the words to show and the kind acted on. Rules: [conformance fixtures](../../fixtures/README.md).
-  A web page can't call this endpoint itself (it answers no other web page): ask from the app's own server or over
-  `@byokit/link`.
-- **Limits**: `failed(member, key, error)` rests an account until the provider said (or a default), marks a plan that
-  doesn't include this use, and signs out only a sign-in that no longer refreshes. `ladder()` picks the next usable
-  account; `keepFresh()` refreshes ahead of expiry. Limits come from errors only; no undocumented usage endpoint is read.
-- **Isolation**: ambient discovery is off (no environment variable or credential file is ever consulted), and
-  `@byokit/accounts/testing` has the decoy-HOME harness and fs tracer to prove it in your own tests. `decoy(root)`
-  writes only under the caller-supplied root; the caller owns its creation and cleanup.
-- **A stand-in OpenAI**: `mockOpenAI()` from `@byokit/accounts/testing` (or `node .../testing/mock-openai.ts [port]`)
-  answers device code, its page where a person types the code, token exchange, refresh, revoke and streamed answers
-  (echoing the question), so tests and demos sign in and ask end to end with no account. Point the kit at it with
-  `new Accounts({ authBase, apiBase })`.
+## 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.
+
+Claude plan sign-in is never offered: Anthropic reserves it for its own apps.
+
+```ts
+import { Accounts, billingWords, offered } from '@byokit/accounts';
+
+console.log(new Accounts().providers.map((p) => p.key)); // the default offer on a computer
+for (const p of offered(['chatgpt', 'openrouter'])) console.log(`${p.name}: ${billingWords(p)}`);
+```
+
+```text
+[ 'chatgpt' ]
+ChatGPT: Uses your ChatGPT plan.
+OpenRouter: Charged per use to your OpenRouter account, not a plan.
+```
+
+## Sign-in
+
+On computers, the provider's own page by default. For ChatGPT, whose page returns to this computer's port 1455, the
+kit listens there itself, so the tab shows your app's words (`new Accounts({ app: 'My App' })`) and only once they are
+true. A code takes over when asked ("Having trouble?"), when the page never comes back, or when the port is taken by
+another sign-in.
+
+A 15-minute cap, nothing kept unless the engine can use it, and every failure is one plain sentence (`words.json`)
+with a `why` for apps that word it themselves. `plan(member)` tells a work ChatGPT from a personal one.
+
+## Sign-out
+
+`logout(member, key)` attempts to revoke a ChatGPT token at OpenAI (`POST auth.openai.com/oauth/revoke`), then deletes
+the local sign-in even if the revoke fails. A failed revoke rejects after local deletion; report it because the remote
+sign-in may remain active.
+
+Within one store instance, a refresh already in progress finishes first, so sign-out uses its rotated token. If a
+cancelled sign-in finishes late, `onSignOutError` reports a failed revoke of its discarded credential (or it is logged
+when no handler is set).
+
+## One person, one store
+
+`memoryStore()`, `fileStore(path)` (0600, the same shape as Pi's `auth.json`), `secureStore(SecureStore, name,
+options?)` or `browserStore(name)`; any other storage with `recordStore(load, save)`. Writes are serialized within a
+store instance; `browserStore` also uses Web Locks across tabs for the same provider when available. Never a shared
+fallback.
+
+- **Browser**: browser storage is readable by scripts on your page: avoid untrusted scripts.
+- **Phone**: pass `{ keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY }` as `options` (to every get, set
+  and delete) so tokens never migrate to a new device through an iCloud/iTunes backup; without it Expo's default
+  (`WHEN_UNLOCKED`) applies.
+- **Reinstall**: iOS Keychain items survive an app reinstall under the same bundle id (Android data is gone). Apps that
+  must forget on reinstall keep a first-run marker outside the Keychain (e.g. `expo-file-system` or `AsyncStorage`)
+  and, when it is missing, call `accounts.logout(member, key)` for each offered key before first use, which revokes and
+  wipes.
+- **Another engine**: using another engine with the same seam (Pi's coding-agent `ModelRuntime`)? Override
+  `open(member)` with an engine whose `credentialStore` is made with `boundStore(member, engineStore)` and whose
+  `readCredential(id)` reads that store.
+
+```ts
+const accounts = new Accounts({
+  store: (member) => secureStore(SecureStore, `byokit.${member}`, { keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY }),
+});
+```
+
+## Asking
+
+`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
+`ResponseError` with the words to show and the kind acted on. Rules: [conformance fixtures](../../fixtures/README.md).
+
+The whole question passes through: `input` takes the turns so far (messages, with `input_image` where the person
+attached a picture), `tools` and `tool_choice` take the app's own function tools and built-ins (including
+`image_generation`), `reasoning.effort` how hard the model thinks, and `text` how long the answer is with the shape it
+must follow (`text.format`). With `tools` the result is the text with every output item; without, the plain text as
+before. `onEvent` sees each tool call and output item as it streams:
+
+```ts
+const result = await accounts.respond(1, {
+  instructions: 'Answer briefly.',
+  input: 'What time is it in Norwich?',
+  tools: [{ type: 'function', name: 'get_time', description: 'The time somewhere.', parameters: { type: 'object', properties: { place: { type: 'string' } } } }],
+  onEvent: (e) => { if (e.type === 'function_call') console.log('calling', e.name, e.arguments); },
+});
+if (isFunctionCall(result.output[0])) {
+  const answer = await accounts.respond(1, {
+    instructions: 'Answer briefly.',
+    input: [
+      { role: 'user', content: [{ type: 'input_text', text: 'What time is it in Norwich?' }] },
+      result.output[0],
+      { type: 'function_call_output', call_id: result.output[0].call_id!, output: 'noon' },
+    ],
+  });
+  show(answer); // 'You did: noon' against the stand-in; the model's own sentence live
+}
+```
+
+A web page can't call this endpoint itself (it answers no other web page): ask from the app's own server or over
+`@byokit/link`.
+
+## Limits
+
+`failed(member, key, error)` rests an account until the provider said (or a default), marks a plan that doesn't
+include this use, and signs out only a sign-in that no longer refreshes. `ladder()` picks the next usable account;
+`keepFresh()` refreshes ahead of expiry. Limits come from errors only; no undocumented usage endpoint is read.
+
+## Isolation
+
+Ambient discovery is off (no environment variable or credential file is ever consulted), and
+`@byokit/accounts/testing` has the decoy-HOME harness and fs tracer to prove it in your own tests. `decoy(root)` writes
+only under the caller-supplied root; the caller owns its creation and cleanup.
+
+## A stand-in OpenAI
+
+`mockOpenAI()` from `@byokit/accounts/testing` (or, from a repo checkout, `node packages/accounts/src/testing/mock-openai.ts [port]`) answers device code, its
+page where a person types the code, token exchange, refresh, revoke and streamed answers (echoing the question), so
+tests and demos sign in and ask end to end with no account. Point the kit at it with
+`new Accounts({ authBase, apiBase })`, as the [Quickstart](#quickstart) does.
+
+## Links
+
+- [byokit](../../README.md): every package and example
+- [`examples/pwa`](../../examples/pwa) (browser sign-in) and [`examples/expo`](../../examples/expo) (React Native, iOS
+  and Android)
+- [Conformance fixtures](../../fixtures/README.md)
+- [CHANGELOG](CHANGELOG.md)
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](../../NOTICE).

package/dist/accounts.d.ts

@@ -1,7 +1,7 @@
 import type { CredentialStore, Models } from '@earendil-works/pi-ai';
 import { type Provider } from './catalogue.ts';
 import { type Kind } from './limits.ts';
-import { ResponseError, type Ask } from './responses.ts';
+import { ResponseError, type Ask, type ResponseResult, type ResponseTool } from './responses.ts';
 import { type EndingStore } 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`). */
@@ -130,8 +130,15 @@ export declare class Accounts<R extends AuthHost = AuthHost, M extends Member =
      *  or null for an error that is not about the account; `network` changes nothing. */
     /** Ask ChatGPT with this member's own sign-in, the answer streaming into `onText`; refreshed first when due. A
      *  failure about the account (a limit, a lapsed sign-in) is acted on as `failed()` does, then thrown as a
-     *  ResponseError with the words to show. */
-    respond(member: M, ask: Ask): Promise<string>;
+     *  ResponseError with the words to show. Without `tools` the answer is the plain text, as before: pass `input` as
+     *  words or as turns (messages with `input_image`, then the `function_call` with its `function_call_output`). With
+     *  `tools` it is the text with every output item, and `onEvent` sees each tool call as it lands. */
+    respond(member: M, ask: Ask & {
+        tools?: undefined;
+    }): Promise<string>;
+    respond(member: M, ask: Ask & {
+        tools: ResponseTool[];
+    }): Promise<ResponseResult>;
     failed(member: M, key: string, error: string | ResponseError): Promise<{
         kind: Kind;
         until: number;

package/dist/accounts.js

@@ -216,13 +216,6 @@ export class Accounts {
         const r = this.rests.get(`${member}:${key}`);
         return r && r.until > Date.now() ? r.until : 0;
     }
-    /** 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,
-     *  or null for an error that is not about the account; `network` changes nothing. */
-    /** Ask ChatGPT with this member's own sign-in, the answer streaming into `onText`; refreshed first when due. A
-     *  failure about the account (a limit, a lapsed sign-in) is acted on as `failed()` does, then thrown as a
-     *  ResponseError with the words to show. */
     async respond(member, ask) {
         const key = 'chatgpt';
         const p = this.offer(key);
@@ -243,7 +236,8 @@ export class Accounts {
         if (!access || c?.type !== 'oauth')
             throw new ResponseError(say('status.signedOut', { name: p.name }), 'signed_out');
         try {
-            return await respond({ ...ask, access, accountId: String(c.accountId ?? ''), model: ask.model ?? p.models.strong, base: this.opts.apiBase, fetch: this.opts.fetch });
+            const base = { ...ask, access, accountId: String(c.accountId ?? ''), model: ask.model ?? p.models.strong, base: this.opts.apiBase, fetch: this.opts.fetch };
+            return ask.tools ? await respond({ ...base, tools: ask.tools }) : await respond({ ...base, tools: undefined });
         }
         catch (e) {
             if (e instanceof ResponseError && e.kind && e.kind !== 'network') {

package/dist/portable.d.ts

@@ -2,6 +2,6 @@ export { Accounts, planOf, portable, type AccountsOptions, type AuthHost, type L
 export { PROVIDERS, offered, provider, type Billing, type Provider, type Terms } from './catalogue.ts';
 export { PORTABLE, claims, credentialOf, devicePoll, deviceStart, portableEngine, type EngineOptions, type Poll } from './engine.ts';
 export { REST_MS, classify, type Kind } from './limits.ts';
-export { ResponseError, limitResponse, respond, sseReader, type Ask } from './responses.ts';
+export { 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 { browserStore, memoryStore, recordStore, secureStore, type SecureStoreLike } from './stores.ts';
 export { WORDS, billingWords, callbackPage, clock, failure, say, signInError, type WordKey, type Why } from './words.ts';

package/dist/portable.js

@@ -4,6 +4,6 @@ export { Accounts, planOf, portable } from "./accounts.js";
 export { PROVIDERS, offered, provider } from "./catalogue.js";
 export { PORTABLE, claims, credentialOf, devicePoll, deviceStart, portableEngine } from "./engine.js";
 export { REST_MS, classify } from "./limits.js";
-export { ResponseError, limitResponse, respond, sseReader } from "./responses.js";
+export { ResponseError, isFunctionCall, limitResponse, respond, sseReader } from "./responses.js";
 export { browserStore, memoryStore, recordStore, secureStore } from "./stores.js";
 export { WORDS, billingWords, callbackPage, clock, failure, say, signInError } from "./words.js";

package/dist/responses.d.ts

@@ -12,28 +12,182 @@ export declare function limitResponse(status: number, body: string, now?: number
     until: number | null;
     message: string;
 };
-/** Reads a streamed answer (fixtures/conformance/sse.json): `push` each piece as it arrives, `end` for the whole text.
+/** One piece of a message the model is given: words, a picture, or anything else the endpoint accepts. */
+export type ResponseInputContent = {
+    type: 'input_text';
+    text: string;
+} | {
+    type: 'input_image';
+    image_url?: string;
+    file_id?: string;
+    detail?: 'auto' | 'low' | 'high';
+} | {
+    type: string;
+    [k: string]: unknown;
+};
+/** What the model is told, in turn: a message (one turn of the conversation), a call it made, or a tool's answer. */
+export type ResponseInputItem = {
+    type?: 'message';
+    role: 'user' | 'assistant' | 'system' | 'developer';
+    content: string | ResponseInputContent[];
+} | {
+    type: 'function_call';
+    call_id?: string;
+    id?: string;
+    name: string;
+    arguments: string;
+} | {
+    type: 'function_call_output';
+    call_id: string;
+    output: string;
+} | {
+    type: string;
+    [k: string]: unknown;
+};
+/** A tool the model may call: one of the app's functions, or a built-in such as image generation. */
+export type ResponseTool = {
+    type: 'function';
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown> | null;
+    strict?: boolean;
+} | {
+    type: 'image_generation';
+    model?: string;
+    size?: string;
+    quality?: string;
+    [k: string]: unknown;
+} | {
+    type: string;
+    [k: string]: unknown;
+};
+/** Which tool the model must use: any, a named function, none, or whatever it wants. */
+export type ResponseToolChoice = 'auto' | 'required' | 'none' | {
+    type: 'function';
+    name: string;
+} | {
+    type: string;
+    [k: string]: unknown;
+};
+/** How hard the model thinks. Default: none, as before. */
+export type ResponseReasoning = {
+    effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+    [k: string]: unknown;
+};
+/** The shape of the answer: how wordy, and optionally a schema it must follow. */
+export type ResponseTextFormat = {
+    type: 'text';
+} | {
+    type: 'json_object';
+} | {
+    type: 'json_schema';
+    name: string;
+    schema: Record<string, unknown>;
+    strict?: boolean;
+} | {
+    type: string;
+    [k: string]: unknown;
+};
+export type ResponseText = {
+    verbosity?: 'low' | 'medium' | 'high';
+    format?: ResponseTextFormat;
+    [k: string]: unknown;
+};
+/** One item of the model's answer: a message, a function call, or anything else the endpoint returns. */
+export type ResponseOutputMessage = {
+    type: 'message';
+    id?: string;
+    role?: string;
+    content?: {
+        type: 'output_text' | 'refusal';
+        text: string;
+        annotations?: unknown[];
+    }[];
+    [k: string]: unknown;
+};
+export type ResponseFunctionCall = {
+    type: 'function_call';
+    id?: string;
+    call_id?: string;
+    name: string;
+    arguments: string;
+    [k: string]: unknown;
+};
+export type ResponseOutputItem = ResponseOutputMessage | ResponseFunctionCall | {
+    type: 'reasoning';
+    [k: string]: unknown;
+} | {
+    type: string;
+    [k: string]: unknown;
+};
+/** 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. */
+export type ResponseResult = {
+    text: string;
+    output: ResponseOutputItem[];
+};
+/** What streams besides the words: each text piece, each tool call as it builds and lands, and each output item. */
+export type ResponseStreamEvent = {
+    type: 'text_delta';
+    delta: string;
+} | {
+    type: 'function_call_delta';
+    name?: string;
+    callId?: string;
+    delta: string;
+} | {
+    type: 'function_call';
+    name: string;
+    arguments: string;
+    callId?: string;
+} | {
+    type: 'output_item';
+    item: ResponseOutputItem;
+};
+/** Reads a streamed answer (fixtures/conformance/sse.json): `push` each piece as it arrives, `end` for the whole text,
+ *  `result` for the text with every output item. `onEvent` sees each tool call and output item as it lands.
  *  An error event throws a ResponseError. */
-export declare function sseReader(onText?: (delta: string) => void): {
+export declare function sseReader(onText?: (delta: string) => void, onEvent?: (event: ResponseStreamEvent) => void): {
     push(chunk: string): void;
     end(): string;
+    result(): ResponseResult;
 };
 export type Ask = {
     /** What the model is told to be. */
     instructions: string;
-    /** The person's words. */
-    input: string;
+    /** The person's words, or the turns so far: messages (with `input_image` where the person attached one) and, after a
+     *  tool call, the `function_call` with its `function_call_output`. */
+    input: string | ResponseInputItem[];
     /** Default: the provider's strong model in the catalogue. */
     model?: string;
+    /** The tools the model may call. Passed, the result carries the output items next to the text. */
+    tools?: ResponseTool[];
+    /** Which tool the model must use. Default: whatever it wants. */
+    tool_choice?: ResponseToolChoice;
+    /** How hard the model thinks. Default: none. */
+    reasoning?: ResponseReasoning;
+    /** How wordy the answer is, and the schema it must follow. Default: low verbosity, free text. */
+    text?: ResponseText;
     /** Each piece of the answer as it streams. */
     onText?: (delta: string) => void;
+    /** Each tool call and output item as it lands. */
+    onEvent?: (event: ResponseStreamEvent) => void;
     signal?: AbortSignal;
 };
-/** Ask ChatGPT with a signed-in token. `fetch`: pass one that streams (Expo's `expo/fetch`); any fetch works. */
-export declare function respond(o: Ask & {
+type Access = {
     access: string;
     accountId: string;
     model: string;
     base?: string;
     fetch?: typeof fetch;
+};
+/** 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. */
+export declare function respond(o: Ask & Access & {
+    tools?: undefined;
 }): Promise<string>;
+export declare function respond(o: Ask & Access & {
+    tools: ResponseTool[];
+}): Promise<ResponseResult>;
+export {};

package/dist/responses.js

@@ -1,6 +1,11 @@
 // One question to ChatGPT, answered as it streams, with fetch alone: what a phone or browser app asks the model with
 // the sign-in it holds. Rules are the shared fixtures (sse.json, limit-responses.json). A fetch that can't stream (React
 // Native's own) still works: the whole answer arrives at once. Expo's `fetch` from 'expo/fetch' streams.
+//
+// The pass-through is complete but typed: a message array (multi-turn, with `input_image` and `function_call_output`
+// turns), `tools` and `tool_choice` (function tools and built-ins, including `image_generation`), `reasoning.effort`,
+// and `text.verbosity` with the `text.format` schema. Without `tools` the answer is the plain text, as before; with
+// `tools` the result carries the output items (`function_call` and the rest) next to the text.
 import { classify } from "./limits.js";
 const limitKind = (code) => code === 'usage_not_included' ? 'not_included'
     : /^(usage_limit_reached|rate_limit_exceeded)$/.test(code) ? 'rate_limit' : null;
@@ -28,11 +33,32 @@ export function limitResponse(status, body, now = Date.now()) {
     const kind = status === 401 || status === 403 ? 'signed_out' : [500, 502, 503, 504].includes(status) ? 'overloaded' : null;
     return { kind, until: null, message: (typeof err.message === 'string' && err.message) || body || 'Request failed' };
 }
-/** Reads a streamed answer (fixtures/conformance/sse.json): `push` each piece as it arrives, `end` for the whole text.
+const isRecord = (v) => typeof v === 'object' && v !== null;
+const itemKey = (item, fallback) => typeof item.call_id === 'string' ? item.call_id : typeof item.id === 'string' ? item.id : `${String(item.type)}:${String(fallback)}`;
+/** Whether an output item is a function call, so an app can answer it with a `function_call_output` turn. */
+export const isFunctionCall = (item) => isRecord(item) && item.type === 'function_call' && typeof item.name === 'string' && typeof item.arguments === 'string';
+/** Reads a streamed answer (fixtures/conformance/sse.json): `push` each piece as it arrives, `end` for the whole text,
+ *  `result` for the text with every output item. `onEvent` sees each tool call and output item as it lands.
  *  An error event throws a ResponseError. */
-export function sseReader(onText) {
+export function sseReader(onText, onEvent) {
     let buffer = '', text = '', completed;
-    let done = false;
+    let done = false, finished;
+    const output = [];
+    const emitted = new Set();
+    const calls = new Map();
+    const callKey = (e) => typeof e.item_id === 'string' ? e.item_id : `index:${String(e.output_index ?? 0)}`;
+    const land = (item, fallback) => {
+        if (!isRecord(item) || typeof item.type !== 'string')
+            return;
+        const key = itemKey(item, fallback);
+        if (emitted.has(key))
+            return;
+        emitted.add(key);
+        output.push(item);
+        onEvent?.({ type: 'output_item', item: item });
+        if (item.type === 'function_call' && typeof item.name === 'string' && typeof item.arguments === 'string')
+            onEvent?.({ type: 'function_call', name: item.name, arguments: item.arguments, callId: typeof item.call_id === 'string' ? item.call_id : undefined });
+    };
     const event = (block) => {
         const data = block.split('\n').filter((l) => l.startsWith('data:')).map((l) => l.slice(5).replace(/^ /, '')).join('\n');
         if (!data || data === '[DONE]')
@@ -47,11 +73,38 @@ export function sseReader(onText) {
         if (e.type === 'response.output_text.delta' && typeof e.delta === 'string') {
             text += e.delta;
             onText?.(e.delta);
+            onEvent?.({ type: 'text_delta', delta: e.delta });
+        }
+        if (e.type === 'response.output_item.added' && isRecord(e.item)) {
+            const key = typeof e.item.call_id === 'string' ? e.item.call_id : callKey(e);
+            const at = calls.get(key) ?? { args: '' };
+            if (typeof e.item.name === 'string')
+                at.name = e.item.name;
+            if (typeof e.item.call_id === 'string')
+                at.callId = e.item.call_id;
+            calls.set(key, at);
         }
-        if (e.type === 'response.completed') {
+        if (e.type === 'response.function_call_arguments.delta' && typeof e.delta === 'string') {
+            const at = calls.get(callKey(e)) ?? { args: '' };
+            at.args += e.delta;
+            calls.set(callKey(e), at);
+            onEvent?.({ type: 'function_call_delta', name: at.name, callId: at.callId, delta: e.delta });
+        }
+        if (e.type === 'response.output_item.done' && isRecord(e.item)) {
+            if (e.item.type === 'function_call' && typeof e.item.arguments !== 'string') {
+                const at = calls.get(callKey(e));
+                if (at && at.args)
+                    e.item = { ...e.item, arguments: at.args };
+            }
+            land(e.item, e.output_index ?? 0);
+        }
+        if (e.type === 'response.completed' || e.type === 'response.incomplete') {
             done = true;
-            if (Array.isArray(e.response?.output))
+            if (Array.isArray(e.response?.output)) {
+                for (const [i, item] of e.response.output.entries())
+                    land(item, i);
                 completed = e.response.output.flatMap((o) => o?.content ?? []).filter((c) => c?.type === 'output_text').map((c) => c.text ?? '').join('');
+            }
         }
         const failed = e.type === 'error' ? e : e.type === 'response.failed' ? e.response?.error : undefined;
         if (failed) {
@@ -66,23 +119,33 @@ export function sseReader(onText) {
         for (const b of blocks)
             event(b);
     };
-    return {
-        push(chunk) { buffer += chunk; drain(false); },
-        end() {
+    const finish = () => {
+        if (!finished) {
             drain(true);
             if (!done)
                 throw new ResponseError('ChatGPT stopped before completing its answer.', 'network');
+            let whole = text;
             if (completed !== undefined && completed !== text) {
                 if (completed.startsWith(text))
                     onText?.(completed.slice(text.length));
-                return completed;
+                whole = completed;
             }
-            return text;
-        },
+            finished = { text: whole, output };
+        }
+        return finished;
+    };
+    return {
+        push(chunk) { buffer += chunk; drain(false); },
+        end() { return finish().text; },
+        result() { return finish(); },
     };
 }
-/** Ask ChatGPT with a signed-in token. `fetch`: pass one that streams (Expo's `expo/fetch`); any fetch works. */
 export async function respond(o) {
+    const input = typeof o.input === 'string'
+        ? [{ role: 'user', content: [{ type: 'input_text', text: o.input }] }]
+        : o.input;
+    const { verbosity = 'low', format, ...textRest } = o.text ?? {};
+    const { effort = 'none', ...reasoningRest } = o.reasoning ?? {};
     const res = await (o.fetch ?? fetch)(`${o.base ?? 'https://chatgpt.com/backend-api'}/codex/responses`, {
         method: 'POST', signal: o.signal,
         headers: {
@@ -90,16 +153,18 @@ export async function respond(o) {
             'chatgpt-account-id': o.accountId, 'OpenAI-Beta': 'responses=experimental', originator: 'byokit',
         },
         body: JSON.stringify({
-            model: o.model, store: false, stream: true, instructions: o.instructions,
-            input: [{ role: 'user', content: [{ type: 'input_text', text: o.input }] }],
-            text: { verbosity: 'low' }, reasoning: { effort: 'none' },
+            model: o.model, store: false, stream: true, instructions: o.instructions, input,
+            ...(o.tools ? { tools: o.tools } : {}),
+            ...(o.tool_choice !== undefined ? { tool_choice: o.tool_choice } : {}),
+            text: { verbosity, ...(format ? { format } : {}), ...textRest },
+            reasoning: { effort, ...reasoningRest },
         }),
     });
     if (!res.ok) {
         const e = limitResponse(res.status, await res.text().catch(() => ''));
         throw new ResponseError(e.message, e.kind, e.until ?? 0);
     }
-    const reader = sseReader(o.onText);
+    const reader = sseReader(o.onText, o.onEvent);
     const body = res.body;
     if (body?.getReader && typeof TextDecoder !== 'undefined') {
         const r = body.getReader();
@@ -110,5 +175,5 @@ export async function respond(o) {
     else {
         reader.push(await res.text()); // a fetch that can't stream: the whole answer at once
     }
-    return reader.end();
+    return o.tools ? reader.result() : reader.end();
 }

package/dist/testing/mock-openai.js

@@ -100,7 +100,41 @@ export async function mockOpenAI({ port = 0, host = '127.0.0.1', plan = 'plus',
                 }
                 if (![...state.live].some((r) => accessOf.get(r) === bearer) || req.headers['chatgpt-account-id'] !== 'acct-1')
                     return send(401, { error: { message: 'Provided authentication token is expired. Please try signing in again.' } });
-                const text = `You said: ${json().input?.[0]?.content?.[0]?.text ?? ''}`;
+                const asked = json();
+                const turns = Array.isArray(asked.input) ? asked.input : [];
+                const said = [];
+                let answered;
+                for (const item of turns) {
+                    if (item?.type === 'function_call_output') {
+                        answered ??= String(item.output ?? '');
+                        continue;
+                    }
+                    const content = typeof item?.content === 'string' ? [{ type: 'input_text', text: item.content }] : Array.isArray(item?.content) ? item.content : [];
+                    for (const part of content)
+                        if (part?.type === 'input_text' && typeof part.text === 'string')
+                            said.push(part.text);
+                }
+                const words = said.join(' ');
+                const schema = asked.text?.format?.type === 'json_schema';
+                const 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) {
+                    // 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');
+                    const args = JSON.stringify({ input: words });
+                    res.writeHead(200, { 'content-type': 'text/event-stream' });
+                    res.write(`event: response.output_item.added\ndata: ${JSON.stringify({ type: 'response.output_item.added', output_index: 0, item: { type: 'function_call', call_id: 'call_1', name, arguments: '' } })}\n\n`);
+                    for (const delta of args.match(/[\s\S]{1,4}/g) ?? []) {
+                        res.write(`event: response.function_call_arguments.delta\ndata: ${JSON.stringify({ type: 'response.function_call_arguments.delta', output_index: 0, item_id: 'call_1', delta })}\n\n`);
+                        await new Promise((r) => setTimeout(r, 5));
+                    }
+                    const item = { type: 'function_call', call_id: 'call_1', name, arguments: args };
+                    res.write(`event: response.output_item.done\ndata: ${JSON.stringify({ type: 'response.output_item.done', output_index: 0, item })}\n\n`);
+                    return res.end(`event: response.completed\ndata: ${JSON.stringify({ type: 'response.completed', response: { status: 'completed', output: [item] } })}\n\ndata: [DONE]\n\n`);
+                }
                 res.writeHead(200, { 'content-type': 'text/event-stream' });
                 for (const delta of text.match(/[\s\S]{1,4}/g) ?? []) {
                     res.write(`event: response.output_text.delta\ndata: ${JSON.stringify({ type: 'response.output_text.delta', delta })}\n\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/accounts",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Sign in with the AI plan you already pay for, into your app's own store.",
   "license": "Apache-2.0",
   "type": "module",