@byokit/accounts 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.8.0 (2026-09-30)
+
+- SECURITY: Desktop fileStore now requires a sealing adapter, rejects insecure Electron storage backends, and refuses symlink or permissive credential files. Plaintext stores must revoke old credentials and sign in again; previously sealed stores remain readable with the same adapter.
+- SECURITY: Credential writes use exclusive random temporary files with no-follow opens and file sync before atomic replacement when Node permissions allow it; default sign-in and discarded-credential revoke logs no longer include raw provider errors or member identifiers.
+
+## 0.7.1 (2026-09-30)
+
+- FIX: a cut-off answer is now reported as cut off: `respond` throws `IncompleteError` with its reason and partial output, and notifies `onEvent`, instead of returning it as finished.
+
 ## 0.7.0 (2026-09-30)
 
 - Add the portable `chatgptPlan` adapter for a host-validated official token-sharing session, checking

package/README.md

@@ -77,9 +77,11 @@ flows, pinned exactly:
 ```ts
 import { isolate } from '@byokit/accounts/isolate'; // first, before any Pi import
 isolate('/path/to/app/engine');                     // scrub inherited Pi settings and provider keys
-import { Accounts, fileStore } from '@byokit/accounts';
+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`) });
+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."
@@ -116,10 +118,10 @@ 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 0600 file (Node entry only), Keychain/Keystore, IndexedDB, or your own load and save |
+| `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 |
 | `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 |
+| `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 |
 | `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` |
@@ -135,7 +137,7 @@ and [`examples/pwa`](../../examples/pwa) (browser sign-in).
 | 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) |
+| 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
 listener on the computer the browser runs on, so it is desktop only: ChatGPT sends the browser back to
@@ -182,12 +184,12 @@ the local sign-in even if the revoke fails. A failed revoke rejects after local
 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
+cancelled sign-in finishes late, `onSignOutError` reports a failed revoke of its discarded credential (or a generic failure 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,
+`memoryStore()`, `fileStore(path, safeStorage)` (sealed, 0600), `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.
@@ -217,6 +219,14 @@ member's sign-in, refreshed first when due, and returns the whole text (`onText`
 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 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
+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.
+Successful return values are unchanged.
+
 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
@@ -291,3 +301,24 @@ including ID-token signature/issuer/audience/nonce verification and protected pe
 available to eligible open-source/local apps; paid/remote apps require approval. This adapter does not start an
 OAuth flow and does not convert the existing Codex `Accounts.login()` credential into a token-sharing session.
 It reads no environment or files, and remains portable to browsers and React Native.
+
+
+## Desktop credential storage security
+
+`fileStore(path, safeStorage)` requires a sealing adapter; there is no plaintext fallback.
+In Electron, pass `safeStorage` after `app.whenReady()`. The store refuses unavailable encryption
+and the Linux `basic_text` backend. Other adapters must protect their keys outside the credential
+file and provide authenticated encryption. For a Node service, use a host-owned keystore through
+`recordStore(load, save)`, or provide an equivalent sealing adapter; the kit never discovers a key
+or invokes an OS keyring itself. Use `memoryStore()` for temporary sign-ins.
+
+Use an app-owned directory: the immediate folder must be a real 0700 directory and credential
+files must be private regular files. Reuse one store instance for each path; a host lock is required
+if several processes write the same file. See [SECURITY.md](SECURITY.md) for the threat model and limits.
+
+**Migration from 0.7.x and earlier:** `fileStore(path)` is no longer accepted. Existing files already
+sealed with the same adapter remain readable. Plain JSON is never silently imported or overwritten.
+For a plaintext store, stop all writers, revoke the old credentials using the old app's sign-out flow,
+remove the old app-owned credential file, and sign in again with a sealing adapter. Old plaintext
+backups may retain tokens: delete them under the host's retention policy and revoke the affected
+credentials. Do not point this migration at another tool's sign-in directory.

package/SECURITY.md

@@ -0,0 +1,99 @@
+# Accounts security
+
+Review scope: accounts credential storage, sign-in failure logging, provider isolation and
+portable platform boundaries, reviewed 2026-09-30. This is a source review with offline
+regression tests, not an independent cryptographic audit or a live OS keychain certification.
+
+## Assets and trust boundaries
+
+OAuth access and refresh tokens, API keys, identity/plan claims, device sign-in codes and
+callback state are sensitive. The host selects each member's store, provider offer and
+platform adapter. The kit uses only those stores; it never imports another application's
+credentials. The computer engine is exactly pinned in package.json and isolated from
+ambient credential discovery. The Node entry has filesystem access; browser and React
+Native entries exclude runtime Node and engine imports.
+
+The provider and network are outside the storage boundary. OAuth sign-in sends codes and
+tokens only to the configured provider endpoints over TLS in production. Host-supplied
+endpoint overrides, adapters and fetch implementations are trusted code: production hosts
+must not substitute untrusted endpoints. Callback state binds the loopback return to the
+pending sign-in; a code or consent URL must be shown only to its intended member.
+
+## At rest
+
+`fileStore(path, adapter)` requires sealing. No encryption key is generated beside the
+credential file and no plaintext fallback exists. Electron hosts pass safeStorage after
+ready. When reported, unavailable encryption and the Linux basic_text backend are refused
+at construction and on each operation. An equivalent adapter is trusted to use authenticated
+encryption and keep its key outside this file, preferably in an OS keyring. An arbitrary
+adapter can lie about sealing; this seam cannot certify the host's implementation.
+
+New immediate directories are 0700; existing immediate directories must be real 0700
+directories. Reads use O_NOFOLLOW, then inspect the opened descriptor for a private regular
+file; nonblocking opens avoid waiting on a substituted FIFO. Writes seal before opening a
+random temporary path with O_EXCL (wx) and O_NOFOLLOW, mode 0600, sync the file (except under Node's permission model, which disables fsync), then rename
+it atomically. Cleanup removes only a temporary file this operation successfully created.
+A legacy predictable .tmp path is never opened. Decryption and parse failures propagate;
+corrupt or plaintext files are never replaced as an automatic recovery step.
+
+The host must own the entire parent path and prevent concurrent directory replacement.
+These POSIX checks do not resolve or pin every ancestor: malicious parent directories,
+mounts, a process running as the same OS user, root, and compromised host code are outside
+this boundary. Windows hosts must also configure private ACLs; POSIX mode bits and
+O_NOFOLLOW are not a substitute for Windows access controls. Atomic rename avoids partial
+records, but the directory is not synced: recovery after sudden power loss is not guaranteed.
+Use one store instance per path and a host lock for multiple processes. Encryption does
+not prevent deletion, rollback to an older sealed record, or leaking credentials in memory.
+
+Browser IndexedDB is origin-scoped plaintext accessible to scripts in that origin. The host
+must prevent XSS and untrusted scripts; a browser cannot promise OS-keychain protection.
+React Native secureStore delegates protection and device accessibility policy to the
+host's Keychain/Keystore adapter. memoryStore holds credentials only in process memory.
+Host-defined recordStore persistence inherits the host backend's security properties.
+
+## Logs, sign-out and isolation
+
+Default sign-in and discarded-credential revoke diagnostics contain fixed messages only,
+not raw provider errors, member identifiers, credentials, callback URLs or nested causes.
+The host's onSignOutError callback receives the underlying error for handling: do not log
+that error without sanitizing it. Other host-visible error/event payloads and model content
+can also be sensitive; the kit does not redact arbitrary host logging or dump memory.
+
+Sign-out attempts provider revocation and removes the local credential even on failure.
+A generation check discards late sign-ins/refreshes so they cannot restore a signed-out
+credential. Revocation failure means a copied token may remain usable at the provider.
+Deleting local files alone does not revoke tokens, and deletion cannot erase old backups.
+
+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.
+
+## Review record
+
+- [x] Required sealing; unavailable and basic_text Electron backends fail closed, including
+  availability changing after construction (`test/units.test.ts`).
+- [x] Sealed credentials round-trip without plaintext access/refresh tokens on disk;
+  existing sealed adapter format is preserved (`test/units.test.ts`).
+- [x] Target and immediate-directory symlinks and permissive modes are refused; a decoy
+  .tmp symlink is unchanged; encryption failure preserves the prior file and random temp
+  files are cleaned after successful replacement (`test/units.test.ts`).
+- [x] Sign-in and failed late-revoke logs use fixed messages, exercised with credential
+  canaries in injected failures (`test/accounts.test.ts`, `test/revoke.test.ts`).
+- [x] Revocation and late completion use offline fake-provider regression coverage
+  (`test/revoke.test.ts`); isolation and portable imports retain their existing tests
+  (`test/isolation.test.ts`, `test/portable.test.ts`).
+
+Run `npm run build`, `npm run check` and `npm test` to reproduce the review checks.
+Live Electron/OS keyring security and host adapter configuration remain the host's responsibility.
+
+## Reporting and migration
+
+Report a vulnerability privately through this repository's GitHub Security Advisories:
+https://github.com/umeranjum17/byokit/security/advisories/new . Do not include live tokens
+in an issue, logs, screenshots or a public reproduction. Include the package version,
+platform, affected seam and an offline reproduction using synthetic credentials.
+
+For legacy plaintext files, follow the README's migration: stop writers, revoke through
+the old app, remove only the app-owned credential file and sign in again using sealing.
+Previously sealed files need only the same adapter passed explicitly. There is no silent
+plaintext migration and no recovery by replacing a file that fails to decrypt.

package/dist/accounts.js

@@ -114,7 +114,7 @@ export class Accounts {
                             if (this.onSignOutError)
                                 this.onSignOutError(member, p.key, error);
                             else
-                                console.error(`sign-out ${p.key} for member ${member}:`, error);
+                                console.error('Sign-out of a discarded credential failed');
                             throw error;
                         }
                     }
@@ -391,8 +391,8 @@ export class Accounts {
             if (flow.state !== 'waiting')
                 return; // cancelled: already settled
             const error = String(e?.message ?? e);
-            console.error(`sign-in ${key} for member ${member}:`, error);
             const why = e?.why ?? (flow.timedOut ? 'tooLong' : failure(error));
+            console.error('Sign-in failed');
             Object.assign(flow, { state: 'failed', url: undefined, code: undefined, expiresAt: undefined, why,
                 error: why === 'busy' || why === 'tooLong' ? say(`signIn.${why}`, { name: p.name }) : signInError(p.name, error) });
         }

package/dist/node-stores.d.ts

@@ -1,10 +1,13 @@
 import type { CredentialStore } from '@earendil-works/pi-ai';
-/** The parts of Electron's `safeStorage` this uses; pass `safeStorage` from 'electron' (main process, after `ready`). */
+/** Pass Electron's safeStorage from the main process after ready, or an equivalent trusted sealing adapter.
+ * Adapters without capability methods are responsible for ensuring their key is protected. */
 export type SafeStorageLike = {
     encryptString(text: string): Uint8Array;
     decryptString(data: Buffer): string;
+    isEncryptionAvailable?(): boolean;
+    getSelectedStorageBackend?(): string;
 };
-/** One person's sign-ins in a JSON file the app chooses (0600, in a 0700 folder), in the same shape as Pi's auth.json.
- *  With Electron's `safeStorage` the file is sealed with the OS keychain's key instead of plain JSON.
- *  ponytail: writes are serialized within this process only; add a file lock if two processes ever share one file. */
-export declare function fileStore(path: string, safeStorage?: SafeStorageLike): CredentialStore;
+/** One person's sealed sign-ins in an app-owned 0600 file inside a private 0700 folder.
+ * No plaintext fallback. Writes are serialized per store instance; use one instance per path and a host lock
+ * if multiple processes share it. The host owns the adapter and its key, separately from this file. */
+export declare function fileStore(path: string, safeStorage: SafeStorageLike): CredentialStore;

package/dist/node-stores.js

@@ -1,27 +1,81 @@
-// Desktop stores: a file the app chooses, optionally sealed with Electron's safeStorage (the OS keychain's key).
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+// Desktop stores: sealed with a host-supplied adapter, such as Electron's safeStorage.
+import { constants, closeSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
 import { dirname } from 'node:path';
 import { recordStore } from "./stores.js";
-/** One person's sign-ins in a JSON file the app chooses (0600, in a 0700 folder), in the same shape as Pi's auth.json.
- *  With Electron's `safeStorage` the file is sealed with the OS keychain's key instead of plain JSON.
- *  ponytail: writes are serialized within this process only; add a file lock if two processes ever share one file. */
+/** One person's sealed sign-ins in an app-owned 0600 file inside a private 0700 folder.
+ * No plaintext fallback. Writes are serialized per store instance; use one instance per path and a host lock
+ * if multiple processes share it. The host owns the adapter and its key, separately from this file. */
 export function fileStore(path, safeStorage) {
+    const ready = () => {
+        if (!safeStorage || typeof safeStorage.encryptString !== 'function' || typeof safeStorage.decryptString !== 'function') {
+            throw new TypeError('fileStore requires a sealing adapter');
+        }
+        if (safeStorage.isEncryptionAvailable?.() === false || safeStorage.getSelectedStorageBackend?.() === 'basic_text') {
+            throw new Error('Secure credential storage is unavailable');
+        }
+    };
+    ready();
+    const folder = dirname(path);
+    const privateFolder = () => {
+        const st = lstatSync(folder);
+        if (!st.isDirectory() || (st.mode & 0o777) !== 0o700)
+            throw new Error('Credential storage requires a private 0700 folder');
+    };
     const load = async () => {
+        ready();
+        let fd;
         try {
-            const raw = readFileSync(path);
-            return JSON.parse(safeStorage ? safeStorage.decryptString(raw) : raw.toString('utf8'));
+            privateFolder();
+            fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
         }
         catch (e) {
             if (e?.code === 'ENOENT')
                 return {};
             throw e;
         }
+        try {
+            const st = fstatSync(fd);
+            if (!st.isFile() || (st.mode & 0o077))
+                throw new Error('Credential storage requires a private regular file');
+            return JSON.parse(safeStorage.decryptString(readFileSync(fd)));
+        }
+        finally {
+            closeSync(fd);
+        }
     };
     const save = async (data) => {
-        const text = JSON.stringify(data, null, 2);
-        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-        writeFileSync(`${path}.tmp`, safeStorage ? safeStorage.encryptString(text) : text, { mode: 0o600 });
-        renameSync(`${path}.tmp`, path);
+        ready();
+        const sealed = safeStorage.encryptString(JSON.stringify(data, null, 2));
+        mkdirSync(folder, { recursive: true, mode: 0o700 });
+        privateFolder();
+        const tmp = `${path}.${process.pid}.${randomBytes(12).toString('hex')}.tmp`;
+        let created = false;
+        try {
+            // O_EXCL is the numeric equivalent of wx; O_NOFOLLOW also forbids a symlink.
+            const fd = openSync(tmp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+            created = true;
+            try {
+                writeFileSync(fd, sealed);
+                // Node's permission model disables fsync even for permitted descriptors.
+                if (!process.permission)
+                    fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+            renameSync(tmp, path);
+        }
+        finally {
+            if (created)
+                try {
+                    unlinkSync(tmp);
+                }
+                catch (e) {
+                    if (e?.code !== 'ENOENT')
+                        throw e;
+                }
+        }
     };
     return recordStore(load, save);
 }

package/dist/portable.d.ts

@@ -2,7 +2,7 @@ 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, 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 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';
 export { chatgptPlan, UnsupportedAccountError, type ChatGPTPlanAccount, type ChatGPTPlanSession } from './chatgpt-plan.ts';

package/dist/portable.js

@@ -4,7 +4,7 @@ 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, isFunctionCall, limitResponse, respond, sseReader } from "./responses.js";
+export { IncompleteError, 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";
 export { chatgptPlan, UnsupportedAccountError } from "./chatgpt-plan.js";

package/dist/responses.d.ts

@@ -6,6 +6,12 @@ export declare class ResponseError extends Error {
     until: number;
     constructor(message: string, kind: Kind | null, until?: number);
 }
+/** An answer the provider cut off. Partial output is available, but never returned as a successful answer. */
+export declare class IncompleteError extends ResponseError {
+    reason: string;
+    result: ResponseResult;
+    constructor(reason: string, result: ResponseResult);
+}
 /** A ChatGPT HTTP error as the kind, when to come back, and the message (fixtures/conformance/limit-responses.json). */
 export declare function limitResponse(status: number, body: string, now?: number): {
     kind: Kind | null;
@@ -129,6 +135,9 @@ export type ResponseResult = {
 };
 /** What streams besides the words: each text piece, each tool call as it builds and lands, and each output item. */
 export type ResponseStreamEvent = {
+    type: 'incomplete';
+    reason: string;
+} | {
     type: 'text_delta';
     delta: string;
 } | {
@@ -149,7 +158,8 @@ export type ResponseStreamEvent = {
  *  `result` for the text with every output item. `onEvent` sees each tool call and output item as it lands.
  *  Events split on any blank line (LF, CRLF or bare CR). A data line that is not JSON throws a ResponseError;
  *  a stream ending with nothing to show throws too. The text is the streamed deltas; the completed envelope
- *  only fills in when no deltas arrived. An error event throws a ResponseError. */
+ *  only fills in when no deltas arrived. An error event throws a ResponseError. An incomplete answer
+ *  emits an incomplete event and throws IncompleteError with its reason and partial result. */
 export declare function sseReader(onText?: (delta: string) => void, onEvent?: (event: ResponseStreamEvent) => void): {
     push(chunk: string): void;
     end(): string;
@@ -173,7 +183,7 @@ export type Ask = {
     text?: ResponseText;
     /** Each piece of the answer as it streams. */
     onText?: (delta: string) => void;
-    /** Each tool call and output item as it lands. */
+    /** Each text piece, tool call, output item, and incomplete answer notification. */
     onEvent?: (event: ResponseStreamEvent) => void;
     signal?: AbortSignal;
     /** The app's own originator header value. Default: 'byokit'. */
@@ -187,7 +197,8 @@ type Access = {
     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. */
+ *  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 & {
     tools?: undefined;
 }): Promise<string>;

package/dist/responses.js

@@ -16,6 +16,17 @@ export class ResponseError extends Error {
     until;
     constructor(message, kind, until = 0) { super(message); this.kind = kind; this.until = until; }
 }
+/** An answer the provider cut off. Partial output is available, but never returned as a successful answer. */
+export class IncompleteError extends ResponseError {
+    reason;
+    result;
+    constructor(reason, result) {
+        super('ChatGPT cut off its answer before it was complete.', null);
+        this.name = 'IncompleteError';
+        this.reason = reason;
+        this.result = result;
+    }
+}
 /** A ChatGPT HTTP error as the kind, when to come back, and the message (fixtures/conformance/limit-responses.json). */
 export function limitResponse(status, body, now = Date.now()) {
     let err = {};
@@ -41,10 +52,12 @@ export const isFunctionCall = (item) => isRecord(item) && item.type === 'functio
  *  `result` for the text with every output item. `onEvent` sees each tool call and output item as it lands.
  *  Events split on any blank line (LF, CRLF or bare CR). A data line that is not JSON throws a ResponseError;
  *  a stream ending with nothing to show throws too. The text is the streamed deltas; the completed envelope
- *  only fills in when no deltas arrived. An error event throws a ResponseError. */
+ *  only fills in when no deltas arrived. An error event throws a ResponseError. An incomplete answer
+ *  emits an incomplete event and throws IncompleteError with its reason and partial result. */
 export function sseReader(onText, onEvent) {
     let buffer = '', text = '', completed;
     let done = false, finished;
+    let incomplete;
     const output = [];
     const emitted = new Set();
     const calls = new Map();
@@ -100,7 +113,7 @@ export function sseReader(onText, onEvent) {
             }
             land(e.item, e.output_index ?? 0);
         }
-        if (e.type === 'response.completed' || e.type === 'response.incomplete') {
+        if (e.type === 'response.completed' || e.type === 'response.incomplete' || e.response?.status === 'incomplete') {
             done = true;
             if (Array.isArray(e.response?.output)) {
                 for (const [i, item] of e.response.output.entries())
@@ -108,6 +121,11 @@ export function sseReader(onText, onEvent) {
                 completed = e.response.output.flatMap((o) => o?.content ?? []).filter((c) => c?.type === 'output_text').map((c) => c.text ?? '').join('');
             }
         }
+        if ((e.type === 'response.incomplete' || e.response?.status === 'incomplete') && incomplete === undefined) {
+            const reason = typeof e.response?.incomplete_details?.reason === 'string' ? e.response.incomplete_details.reason : 'unknown';
+            incomplete = reason;
+            onEvent?.({ type: 'incomplete', reason });
+        }
         const failed = e.type === 'error' ? e : e.type === 'response.failed' ? e.response?.error : undefined;
         if (failed) {
             const message = String(failed.message ?? 'Request failed');
@@ -133,12 +151,14 @@ export function sseReader(onText, onEvent) {
             if (!done)
                 throw new ResponseError('ChatGPT stopped before completing its answer.', 'network');
             const whole = text !== '' ? text : (completed ?? '');
-            if (whole === '' && output.length === 0)
+            if (incomplete === undefined && whole === '' && output.length === 0)
                 throw new ResponseError('ChatGPT stopped before completing its answer.', 'network');
             if (text === '' && whole !== '')
                 onText?.(whole);
             finished = { text: whole, output };
         }
+        if (incomplete !== undefined)
+            throw new IncompleteError(incomplete, finished);
         return finished;
     };
     return {
@@ -173,7 +193,18 @@ export async function respond(o) {
     }
     const reader = sseReader(o.onText, o.onEvent);
     const body = res.body;
-    if (body?.getReader && typeof TextDecoder !== 'undefined') {
+    if (res.headers?.get('content-type')?.includes('application/json')) {
+        let response;
+        try {
+            response = JSON.parse(await res.text());
+        }
+        catch {
+            throw new ResponseError("ChatGPT's answer could not be read.", null);
+        }
+        const type = isRecord(response) ? `response.${String(response.status)}` : '';
+        reader.push(`data: ${JSON.stringify({ type, response })}\n\n`);
+    }
+    else if (body?.getReader && typeof TextDecoder !== 'undefined') {
         const r = body.getReader();
         const decoder = new TextDecoder();
         for (let c = await r.read(); !c.done; c = await r.read())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/accounts",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Sign in with the AI plan you already pay for, into your app's own store.",
   "license": "Apache-2.0",
   "type": "module",
@@ -40,7 +40,8 @@
   },
   "files": [
     "dist",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "SECURITY.md"
   ],
   "scripts": {
     "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"