@chipmobilesdk/rn-ai 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog — @chipmobilesdk/rn-ai
 
+## [0.2.0] — 2026-11-01
+
+Fixes a chat or quota call that could hang forever, and errors that never
+reached the app. **No code change is required.**
+
+### Fixed
+
+- **Every network call has a time limit.** The chat stream had none, and
+  neither did the config or quota fetch, so on a stalled mobile connection
+  `useAiChat` stayed in `loading`/`streaming` and `useAiQuota` in `loading`
+  until the user gave up — and with no cached config, one hung fetch blocked
+  every call. New `timeouts: { connectMs, idleMs, configMs, quotaMs }` option
+  (defaults 30 s, 30 s, 10 s, 10 s). The idle limit restarts on every chunk.
+- **No error is swallowed.** Every chat path ended in `.catch(() => undefined)`,
+  so a transport that threw (an invalid URL from remote config, for example)
+  left the UI in `loading` with nothing to show. Such failures now arrive as
+  `AiError('internal')`. The remote `recovery` block is type-checked when
+  parsed, so a mistyped value can no longer throw inside the XHR callback.
+- **A cancelled or replaced request stays silent.** A token or config failure
+  that landed after `cancel()` (or after the next `send()`) still called
+  `onError` and flipped that screen to `error`. The client now routes every
+  callback through one guard (nothing after cancel, exactly one of
+  `onDone`/`onError`), and `useAiChat` and `useAiQuota` drop callbacks from
+  older requests.
+
+### Changed
+
+- A stalled stream, a timed-out quota fetch and a dropped connection (status 0)
+  report `upstream-error` with `recoverable: true`; status 0 was
+  `recoverable: false`.
+
+### Added
+
+- `AiClientConfig.timeouts` and the `AiTimeouts` type.
+
 ## 0.1.0 — 2026-07-05
 
 Initial release (feature `005-azure-ai-gateway`).

package/README.md

@@ -3,14 +3,14 @@
 AI gateway client for ChipMobileSdk-family React Native apps. Streams
 multimodal (text + image + audio in, text out) AI responses through the
 platform gateway with per-user rate limiting — apps never talk to Azure
-OpenAI directly and hold no AI credentials.
-
-> **License:** `UNLICENSED`. Published publicly for use by the owner's
-> applications; no open-source license is granted.
-
-- **Version**: `0.1.0`
-- **Entrypoint**: `@chipmobilesdk/rn-ai`
-- **Native code**: none
+OpenAI directly and hold no AI credentials.
+
+> **License:** `UNLICENSED`. Published publicly for use by the owner's
+> applications; no open-source license is granted.
+
+- **Version**: `0.2.x` (see [CHANGELOG](CHANGELOG.md))
+- **Entrypoint**: `@chipmobilesdk/rn-ai`
+- **Native code**: none
 
 - Contract: [rn-ai-public-api](../../specs/005-azure-ai-gateway/contracts/rn-ai-public-api.md)
 - Gateway API: [gateway-api](../../specs/005-azure-ai-gateway/contracts/gateway-api.md)
@@ -53,12 +53,12 @@ export const aiClient = createAiClient({
 
 3. Use the hooks:
 
-```tsx
-import { useAiChat, useAiQuota } from '@chipmobilesdk/rn-ai';
-import { aiClient } from './ai/setup';
-
-const { send, cancel, status, text, error, retryAt } = useAiChat(aiClient);
-const { quota } = useAiQuota(aiClient);
+```tsx
+import { useAiChat, useAiQuota } from '@chipmobilesdk/rn-ai';
+import { aiClient } from './ai/setup';
+
+const { send, cancel, status, text, error, retryAt } = useAiChat(aiClient);
+const { quota } = useAiQuota(aiClient);
 
 send({
   messages: [{
@@ -71,37 +71,54 @@ send({
 });
 ```
 
-## Runtime behavior
-
-- **Config-driven endpoint**: resolved lazily on the first quota or chat
-  request. A fresh cache entry is used immediately; a stale entry is used
-  immediately and revalidated in the background with its ETag. With no cache,
-  the first operation waits for the config request. Designated `404`/`410`
-  responses invalidate config and retry against the refreshed endpoint.
-- **Auth**: acquires tokens via rn-auth (`requestAccessToken('ai-gateway')`);
-  on `401`, reacquires a token and retries once.
+## Runtime behavior
+
+- **Config-driven endpoint**: resolved lazily on the first quota or chat
+  request. A fresh cache entry is used immediately; a stale entry is used
+  immediately and revalidated in the background with its ETag. With no cache,
+  the first operation waits for the config request, for at most `configMs`.
+  Designated `404`/`410`
+  responses invalidate config and retry against the refreshed endpoint.
+- **Auth**: acquires tokens via rn-auth (`requestAccessToken('ai-gateway')`);
+  on `401`, reacquires a token and retries once.
+- **Timeouts**: every network call is bounded. Override any of them with
+  `createAiClient({ timeouts: { ... } })`:
+
+  | | Default | Fails with |
+  |---|---|---|
+  | `connectMs` — chat request sent → headers | 30 s | `upstream-error`, `recoverable: true` |
+  | `idleMs` — silence between two stream chunks | 30 s | `upstream-error`, `recoverable: true` |
+  | `configMs` — behavior-config fetch | 10 s | stale cache if any, else `config-unavailable` |
+  | `quotaMs` — quota fetch | 10 s | `upstream-error`, `recoverable: true` |
+
+  The gateway sends headers only after the model answers, so `connectMs` also
+  covers time to first token. A dropped connection (HTTP status 0) is likewise
+  `upstream-error` with `recoverable: true`.
+- **Callbacks**: each `chat()` delivers exactly one of `onDone` / `onError`,
+  and nothing after `cancel()`. An unexpected exception anywhere on the way
+  (including in your own `onDelta`) is reported as `internal`, never dropped.
 - **Rate limits**: `429` surfaces as `status: 'rate-limited'` with `retryAt`;
   the SDK never hammers and never enforces limits locally (display only).
 - **Typed errors** (`AiError.code`): `auth-invalid`, `not-entitled`,
   `user-blocked`, `app-unknown`, `rate-limited`, `upstream-busy`,
   `payload-too-large`, `modality-not-allowed`, `config-unavailable`,
   `upstream-error`, `internal`.
-- **Copy keys**: `ai.*` defaults in `aiMessages` — map through your i18n.
-
-## Public API
-
-Everything is exported from `@chipmobilesdk/rn-ai`; internal `config/`,
-`transport/`, `core/`, `react/`, and `diagnostics/` paths are not public.
-
-- Client: `createAiClient`, `AiClient`, `AiClientConfig`, `TokenProvider`
-- Chat: `ChatRequest`, `ChatMessage`, `ContentPart`, `ChatStreamHandlers`,
-  `ChatHandle`, `Usage`
-- Behavior and cache: `AppBehaviorConfig`, `AiBehaviorState`, `BehaviorState`,
-  `AiConfigCache`, `QuotaSnapshot`
-- React: `useAiChat`, `useAiQuota`, `AiChatStatus`, `UseAiChatResult`,
-  `UseAiQuotaResult`
-- Diagnostics and copy: `AiError`, `AiErrorCode`, `isAiError`, `aiMessages`,
-  `aiMessage`, `AiMessageKey`
+- **Copy keys**: `ai.*` defaults in `aiMessages` — map through your i18n.
+
+## Public API
+
+Everything is exported from `@chipmobilesdk/rn-ai`; internal `config/`,
+`transport/`, `core/`, `react/`, and `diagnostics/` paths are not public.
+
+- Client: `createAiClient`, `AiClient`, `AiClientConfig`, `TokenProvider`
+- Chat: `ChatRequest`, `ChatMessage`, `ContentPart`, `ChatStreamHandlers`,
+  `ChatHandle`, `Usage`
+- Behavior and cache: `AppBehaviorConfig`, `AiBehaviorState`, `BehaviorState`,
+  `AiConfigCache`, `QuotaSnapshot`
+- React: `useAiChat`, `useAiQuota`, `AiChatStatus`, `UseAiChatResult`,
+  `UseAiQuotaResult`
+- Diagnostics and copy: `AiError`, `AiErrorCode`, `isAiError`, `aiMessages`,
+  `aiMessage`, `AiMessageKey`
 
 ## App responsibilities
 
@@ -114,21 +131,21 @@ Everything is exported from `@chipmobilesdk/rn-ai`; internal `config/`,
 - Respect `payload-too-large` (default cap 10 MB/request) by resizing images
   and bounding audio length.
 
-## Compatibility
-
-React ≥19 · React Native ≥0.85 (Hermes) · iOS + Android · Node ≥22.11 for
-tooling.
-
-The repository contains `src/screens/AiDemoScreen.tsx` and its component test.
-The current demo sidebar does not expose that screen yet, so it must be wired
-into `ScreenKey`, `Sidebar`, and `ActiveScreen` before it is reachable in-app.
-
-## Validation
-
-Run from the repository root:
-
-```bash
-npm run typecheck:ai
-npm run pack:ai
-npm run validate:ai
-```
+## Compatibility
+
+React ≥19 · React Native ≥0.85 (Hermes) · iOS + Android · Node ≥22.11 for
+tooling.
+
+The repository contains `src/screens/AiDemoScreen.tsx` and its component test.
+The current demo sidebar does not expose that screen yet, so it must be wired
+into `ScreenKey`, `Sidebar`, and `ActiveScreen` before it is reachable in-app.
+
+## Validation
+
+Run from the repository root:
+
+```bash
+npm run typecheck:ai
+npm run pack:ai
+npm run validate:ai
+```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-ai",
-	"version": "0.1.1",
+	"version": "0.2.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",

package/skills/sdk-rn-ai/SKILL.md

@@ -1,57 +1,57 @@
----
-name: sdk-rn-ai
-description: "AI chat and quota via @chipmobilesdk/rn-ai: createAiClient, useAiChat, useAiQuota, streaming status, AI error codes. Use when adding an AI chat feature, showing quota, or handling AI request failures and cancellation."
-metadata:
-  package: "@chipmobilesdk/rn-ai"
-  packageVersion: "0.1.0"
-user-invocable: true
-disable-model-invocation: false
----
-
-# @chipmobilesdk/rn-ai
-
-Client and React hooks for AI chat backed by the gateway, including quota reporting
-and a typed error model.
-
-## Use this when
-
-- Adding an AI chat screen or message composer
-- Displaying remaining quota
-- Handling AI request failure, cancellation, or streaming state
-- Localising AI-related user messages
-
-## The app owns more than you expect
-
-This package deliberately does not handle everything. The README has an
-`## App responsibilities` section listing what the consuming app must implement —
-read it before assuming a behaviour is built in.
-
-## Cancellation is required, not optional
-
-`useAiChat` exposes streaming status. An in-flight request MUST be cancelled when the
-screen unmounts, otherwise the response resolves against a dead component. Verify
-teardown on every screen that uses it.
-
-## Public API (v0.1.0)
-
-Runtime:
-
-- `createAiClient(...)` — transport-level client
-- `useAiChat(...)` → `UseAiChatResult`, with `AiChatStatus` for state
-- `useAiQuota(...)` → `UseAiQuotaResult`
-- `AiError`, `isAiError` — narrow before reading `AiErrorCode`
-- `aiMessages`, `aiMessage` — user-facing strings keyed by `AiMessageKey`
-
-Use `aiMessage` for anything shown to the user. Never render `AiError.message` directly.
-
-## Where the detail lives
-
-Read one section of `node_modules/@chipmobilesdk/rn-ai/README.md`:
-
-| Need | Section |
-|---|---|
-| First integration | `## Install`, `## Setup` |
-| Streaming, retries, timeouts | `## Runtime behavior` |
-| Full export list | `## Public API` |
-| What the app must implement | `## App responsibilities` |
-| Version/peer constraints | `## Compatibility` |
+---
+name: sdk-rn-ai
+description: "AI chat and quota via @chipmobilesdk/rn-ai: createAiClient, useAiChat, useAiQuota, streaming status, AI error codes. Use when adding an AI chat feature, showing quota, or handling AI request failures and cancellation."
+metadata:
+  package: "@chipmobilesdk/rn-ai"
+  packageVersion: "0.1.0"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# @chipmobilesdk/rn-ai
+
+Client and React hooks for AI chat backed by the gateway, including quota reporting
+and a typed error model.
+
+## Use this when
+
+- Adding an AI chat screen or message composer
+- Displaying remaining quota
+- Handling AI request failure, cancellation, or streaming state
+- Localising AI-related user messages
+
+## The app owns more than you expect
+
+This package deliberately does not handle everything. The README has an
+`## App responsibilities` section listing what the consuming app must implement —
+read it before assuming a behaviour is built in.
+
+## Cancellation is required, not optional
+
+`useAiChat` exposes streaming status. An in-flight request MUST be cancelled when the
+screen unmounts, otherwise the response resolves against a dead component. Verify
+teardown on every screen that uses it.
+
+## Public API (v0.2.0)
+
+Runtime:
+
+- `createAiClient(...)` — transport-level client
+- `useAiChat(...)` → `UseAiChatResult`, with `AiChatStatus` for state
+- `useAiQuota(...)` → `UseAiQuotaResult`
+- `AiError`, `isAiError` — narrow before reading `AiErrorCode`
+- `aiMessages`, `aiMessage` — user-facing strings keyed by `AiMessageKey`
+
+Use `aiMessage` for anything shown to the user. Never render `AiError.message` directly.
+
+## Where the detail lives
+
+Read one section of `node_modules/@chipmobilesdk/rn-ai/README.md`:
+
+| Need | Section |
+|---|---|
+| First integration | `## Install`, `## Setup` |
+| Streaming, retries, timeouts | `## Runtime behavior` |
+| Full export list | `## Public API` |
+| What the app must implement | `## App responsibilities` |
+| Version/peer constraints | `## Compatibility` |

package/src/config/behaviorConfig.ts

@@ -1,4 +1,5 @@
 import { AiError } from '../diagnostics/errors';
+import { DEFAULT_AI_TIMEOUTS, withTimeout } from '../transport/timeouts';
 
 /** App behavior configuration (contracts/app-behavior-config.md). */
 export interface AppBehaviorConfig {
@@ -34,6 +35,9 @@ export class MemoryConfigCache implements AiConfigCache {
 
 export type BehaviorState = 'unloaded' | 'ready-network' | 'ready-cache' | 'unavailable';
 
+const numbers = (value: unknown): number[] | undefined =>
+	Array.isArray(value) ? value.filter((n): n is number => Number.isFinite(n)) : undefined;
+
 /** Parse + validate; unknown fields ignored (forward compatibility). */
 export function parseBehaviorConfig(json: string): AppBehaviorConfig {
 	let raw: Record<string, unknown>;
@@ -63,10 +67,14 @@ export function parseBehaviorConfig(json: string): AppBehaviorConfig {
 			supportsStreaming: api.supportsStreaming !== false,
 		},
 		limitsDisplay: raw.limitsDisplay as AppBehaviorConfig['limitsDisplay'],
+		// Typed here, once: a remote document with `reloadOnHttpStatus: "404"` used to
+		// throw a TypeError inside the XHR error callback, where nothing caught it.
 		recovery: {
-			reloadOnHttpStatus: recovery.reloadOnHttpStatus ?? [404, 410],
-			maxSilentRetries: recovery.maxSilentRetries ?? 1,
-			retryBackoffMs: recovery.retryBackoffMs ?? [500, 2000],
+			reloadOnHttpStatus: numbers(recovery.reloadOnHttpStatus) ?? [404, 410],
+			maxSilentRetries: Number.isFinite(recovery.maxSilentRetries)
+				? Number(recovery.maxSilentRetries)
+				: 1,
+			retryBackoffMs: numbers(recovery.retryBackoffMs) ?? [500, 2000],
 		},
 		features: { aiEnabled: features.aiEnabled !== false },
 	};
@@ -84,6 +92,8 @@ export interface BehaviorConfigDeps {
 	cache?: AiConfigCache;
 	fetchFn?: typeof fetch;
 	now?: () => number;
+	/** Limit on one config fetch, body included. Defaults to 10 s. */
+	timeoutMs?: number;
 }
 
 /**
@@ -127,7 +137,15 @@ export class BehaviorConfigManager {
 		if (this.current?.envelope.etag) {
 			headers['If-None-Match'] = this.current.envelope.etag;
 		}
-		const response = await this.fetchFn(this.deps.configUrl, { headers });
+		// Bounded: with no cache, a hung fetch used to block every chat and quota call.
+		const { response, configJson } = await withTimeout(
+			this.deps.timeoutMs ?? DEFAULT_AI_TIMEOUTS.configMs,
+			async signal => {
+				const res = await this.fetchFn(this.deps.configUrl, { headers, signal });
+				return { response: res, configJson: res.ok && res.status !== 304 ? await res.text() : '' };
+			},
+			() => new AiError('config-unavailable', 'config fetch timed out'),
+		);
 		if (response.status === 304 && this.current) {
 			this.current.envelope.fetchedAt = this.now();
 			await this.persist(this.current.envelope);
@@ -137,7 +155,6 @@ export class BehaviorConfigManager {
 		if (!response.ok) {
 			throw new AiError('config-unavailable', `config fetch failed: ${response.status}`);
 		}
-		const configJson = await response.text();
 		const config = parseBehaviorConfig(configJson);
 		const envelope: CacheEnvelope = {
 			configJson,

package/src/core/aiClient.ts

@@ -6,6 +6,7 @@ import {
 } from '../config/behaviorConfig';
 import { AiError, errorFromHttp } from '../diagnostics/errors';
 import { requestSse, type SseHandle } from '../transport/sseClient';
+import { DEFAULT_AI_TIMEOUTS, withTimeout, type AiTimeouts } from '../transport/timeouts';
 
 /** Minimal slice of the rn-auth `Auth` controller the client needs. */
 export interface TokenProvider {
@@ -66,6 +67,8 @@ export interface AiClientConfig {
 	fetchFn?: typeof fetch;
 	/** Test seam for the SSE transport. */
 	transport?: typeof requestSse;
+	/** Overrides for the network time limits; see `AiTimeouts` for the defaults. */
+	timeouts?: Partial<AiTimeouts>;
 }
 
 export interface AiClient {
@@ -87,11 +90,13 @@ export function createAiClient(clientConfig: AiClientConfig): AiClient {
 	const resourceKey = clientConfig.resourceKey ?? 'ai-gateway';
 	const transport = clientConfig.transport ?? requestSse;
 	const fetchFn = clientConfig.fetchFn ?? fetch;
+	const timeouts: AiTimeouts = { ...DEFAULT_AI_TIMEOUTS, ...clientConfig.timeouts };
 	const configManager = new BehaviorConfigManager({
 		configUrl: clientConfig.configUrl,
 		appId: clientConfig.appId,
 		cache: clientConfig.storage,
 		fetchFn: clientConfig.fetchFn,
+		timeoutMs: timeouts.configMs,
 	});
 	let lastConfig: AppBehaviorConfig | undefined;
 
@@ -115,17 +120,51 @@ export function createAiClient(clientConfig: AiClientConfig): AiClient {
 
 	function chat(request: ChatRequest, handlers: ChatStreamHandlers): ChatHandle {
 		let cancelled = false;
+		let settled = false;
 		let inner: SseHandle | undefined;
 
+		// Every callback to the app goes through here. Nothing is delivered after
+		// cancel() — an acquire() or config reload that failed after the user
+		// cancelled (or sent the next message) used to flip that screen to
+		// `error` — and exactly one terminal callback is delivered.
+		const emit = {
+			delta(text: string) {
+				if (!cancelled && !settled) handlers.onDelta(text);
+			},
+			done(result: { usage: Usage; quota?: QuotaSnapshot }) {
+				if (cancelled || settled) return;
+				settled = true;
+				handlers.onDone(result);
+			},
+			error(error: AiError) {
+				if (cancelled || settled) return;
+				settled = true;
+				inner?.cancel();
+				handlers.onError(error);
+			},
+		};
+
+		// Any exception on the way becomes a reported error. Each path used to end
+		// in `.catch(() => undefined)`, so a transport that threw (a bad URL from
+		// remote config, say) left the UI in `loading` with nothing to show.
+		const fail = (e: unknown) =>
+			emit.error(
+				e instanceof AiError
+					? e
+					: new AiError('internal', e instanceof Error ? e.message : String(e)),
+			);
+		const guarded =
+			<A extends unknown[]>(fn: (...args: A) => void) =>
+			(...args: A) => {
+				try {
+					fn(...args);
+				} catch (e) {
+					fail(e);
+				}
+			};
+
 		const attempt = async (state: { configReloads: number; authRetries: number }) => {
-			let config: AppBehaviorConfig;
-			let token: string;
-			try {
-				({ config, token } = await acquire());
-			} catch (e) {
-				handlers.onError(e instanceof AiError ? e : new AiError('internal', String(e)));
-				return;
-			}
+			const { config, token } = await acquire();
 			if (cancelled) return;
 
 			let done: { usage: Usage; quota?: QuotaSnapshot } | undefined;
@@ -139,9 +178,11 @@ export function createAiClient(clientConfig: AiClientConfig): AiClient {
 						'Content-Type': 'application/json',
 					},
 					body: JSON.stringify(request),
+					connectTimeoutMs: timeouts.connectMs,
+					idleTimeoutMs: timeouts.idleMs,
 				},
 				{
-					onData: payload => {
+					onData: guarded(payload => {
 						if (payload === '[DONE]') return;
 						let event: StreamEvent;
 						try {
@@ -150,52 +191,56 @@ export function createAiClient(clientConfig: AiClientConfig): AiClient {
 							return;
 						}
 						if (event.type === 'delta' && typeof event.text === 'string') {
-							handlers.onDelta(event.text);
+							emit.delta(event.text);
 						} else if (event.type === 'done' && event.usage) {
 							done = { usage: event.usage, quota: event.quota };
 						} else if (event.type === 'error') {
 							streamErrorCode = event.code ?? 'UPSTREAM_ERROR';
 						}
-					},
-					onEnd: () => {
-						if (cancelled) return;
+					}),
+					onEnd: guarded(() => {
 						if (streamErrorCode) {
-							handlers.onError(new AiError('upstream-error', 'the AI service failed mid-response'));
+							emit.error(new AiError('upstream-error', 'the AI service failed mid-response'));
 						} else if (done) {
-							handlers.onDone(done);
+							emit.done(done);
 						} else {
-							handlers.onError(new AiError('internal', 'stream ended without completion'));
+							emit.error(new AiError('internal', 'stream ended without completion'));
 						}
-					},
-					onError: (status, bodyText) => {
+					}),
+					onError: guarded((status, bodyText) => {
 						if (cancelled) return;
+						if (status === 0 && bodyText === 'timeout') {
+							emit.error(
+								new AiError('upstream-error', 'the AI service stopped responding', {
+									recoverable: true,
+								}),
+							);
+							return;
+						}
 						// Designated config-stale signals → silent reload + retry once (FR-018).
 						if (
 							config.recovery.reloadOnHttpStatus.includes(status) &&
 							state.configReloads < config.recovery.maxSilentRetries
 						) {
-							configManager
-								.getConfig({ forceReload: true })
-								.then(() => attempt({ ...state, configReloads: state.configReloads + 1 }))
-								.catch(e =>
-									handlers.onError(
-										e instanceof AiError ? e : new AiError('config-unavailable', String(e)),
-									),
-								);
+							configManager.getConfig({ forceReload: true }).then(
+								() => attempt({ ...state, configReloads: state.configReloads + 1 }).catch(fail),
+								e =>
+									fail(e instanceof AiError ? e : new AiError('config-unavailable', String(e))),
+							);
 							return;
 						}
 						// Expired server-side session → one fresh-token retry.
 						if (status === 401 && state.authRetries < 1) {
-							attempt({ ...state, authRetries: state.authRetries + 1 }).catch(() => undefined);
+							attempt({ ...state, authRetries: state.authRetries + 1 }).catch(fail);
 							return;
 						}
-						handlers.onError(errorFromHttp(status, bodyText));
-					},
+						emit.error(errorFromHttp(status, bodyText));
+					}),
 				},
 			);
 		};
 
-		attempt({ configReloads: 0, authRetries: 0 }).catch(() => undefined);
+		attempt({ configReloads: 0, authRetries: 0 }).catch(fail);
 		return {
 			cancel() {
 				cancelled = true;
@@ -206,14 +251,20 @@ export function createAiClient(clientConfig: AiClientConfig): AiClient {
 
 	async function getQuota(): Promise<QuotaSnapshot> {
 		const { config, token } = await acquire();
-		const response = await fetchFn(
-			`${config.api.baseUrl}/api/v1/apps/${clientConfig.appId}/quota`,
-			{ headers: { Authorization: `Bearer ${token}` } },
+		return withTimeout(
+			timeouts.quotaMs,
+			async signal => {
+				const response = await fetchFn(
+					`${config.api.baseUrl}/api/v1/apps/${clientConfig.appId}/quota`,
+					{ headers: { Authorization: `Bearer ${token}` }, signal },
+				);
+				if (!response.ok) {
+					throw errorFromHttp(response.status, await response.text());
+				}
+				return (await response.json()) as QuotaSnapshot;
+			},
+			() => new AiError('upstream-error', 'quota request timed out', { recoverable: true }),
 		);
-		if (!response.ok) {
-			throw errorFromHttp(response.status, await response.text());
-		}
-		return (await response.json()) as QuotaSnapshot;
 	}
 
 	return {

package/src/diagnostics/errors.ts

@@ -67,5 +67,9 @@ export function errorFromHttp(status: number, bodyText: string): AiError {
 			message = 'network failure';
 		}
 	}
-	return new AiError(code, message, { retryAfterSeconds });
+	// Status 0 is a dropped connection, which a retry may well fix.
+	return new AiError(code, message, {
+		retryAfterSeconds,
+		recoverable: status === 0 ? true : undefined,
+	});
 }

package/src/index.ts

@@ -25,6 +25,7 @@ export type {
 	BehaviorState,
 } from './config/behaviorConfig';
 
+export type { AiTimeouts } from './transport/timeouts';
 export { useAiChat, useAiQuota } from './react/hooks';
 export type { AiChatStatus, UseAiChatResult, UseAiQuotaResult } from './react/hooks';
 

package/src/react/hooks.ts

@@ -33,24 +33,33 @@ export function useAiChat(client: AiClient): UseAiChatResult {
 	const [retryAt, setRetryAt] = useState<Date | undefined>();
 	const [quota, setQuota] = useState<QuotaSnapshot | undefined>();
 	const handleRef = useRef<ChatHandle | null>(null);
+	// Bumped by every send, cancel and unmount. A callback from an older request
+	// is dropped, so it can never overwrite the state of the one on screen —
+	// defence in depth behind the client's own cancel guard.
+	const requestRef = useRef(0);
 
 	const send = useCallback(
 		(request: ChatRequest) => {
 			handleRef.current?.cancel();
+			const id = ++requestRef.current;
+			const current = () => requestRef.current === id;
 			setText('');
 			setError(undefined);
 			setRetryAt(undefined);
 			setStatus('loading');
 			handleRef.current = client.chat(request, {
 				onDelta: delta => {
+					if (!current()) return;
 					setStatus('streaming');
 					setText(previous => previous + delta);
 				},
 				onDone: result => {
+					if (!current()) return;
 					if (result.quota) setQuota(result.quota);
 					setStatus('done');
 				},
 				onError: aiError => {
+					if (!current()) return;
 					setError(aiError);
 					if (aiError.code === 'rate-limited') {
 						setStatus('rate-limited');
@@ -67,11 +76,18 @@ export function useAiChat(client: AiClient): UseAiChatResult {
 	);
 
 	const cancel = useCallback(() => {
+		requestRef.current += 1;
 		handleRef.current?.cancel();
 		setStatus('idle');
 	}, []);
 
-	useEffect(() => () => handleRef.current?.cancel(), []);
+	useEffect(
+		() => () => {
+			requestRef.current += 1;
+			handleRef.current?.cancel();
+		},
+		[],
+	);
 
 	return { send, cancel, status, text, error, retryAt, quota };
 }
@@ -86,18 +102,23 @@ export function useAiQuota(client: AiClient): UseAiQuotaResult {
 	const [quota, setQuota] = useState<QuotaSnapshot | undefined>();
 	const [status, setStatus] = useState<'loading' | 'ready' | 'error'>('loading');
 	const alive = useRef(true);
+	// Only the latest refresh may settle the state; an older, slower one that
+	// lands afterwards is stale.
+	const latest = useRef(0);
 
 	const refresh = useCallback(() => {
+		const id = ++latest.current;
+		const current = () => alive.current && latest.current === id;
 		setStatus('loading');
 		client
 			.getQuota()
 			.then(snapshot => {
-				if (!alive.current) return;
+				if (!current()) return;
 				setQuota(snapshot);
 				setStatus('ready');
 			})
 			.catch(() => {
-				if (alive.current) setStatus('error');
+				if (current()) setStatus('error');
 			});
 	}, [client]);
 

package/src/transport/sseClient.ts

@@ -14,7 +14,12 @@ export interface SseRequest {
 	headers?: Record<string, string>;
 	/** JSON string body for POST requests. */
 	body?: string;
+	/** Hard limit on the whole request. Rarely right for a stream; prefer the two below. */
 	timeoutMs?: number;
+	/** Fails with `onError(0, 'timeout')` if response headers have not arrived by then. */
+	connectTimeoutMs?: number;
+	/** Fails with `onError(0, 'timeout')` when no chunk arrives for this long. Reset per chunk. */
+	idleTimeoutMs?: number;
 }
 
 export interface SseHandlers {
@@ -56,15 +61,44 @@ export function requestSse(request: SseRequest, handlers: SseHandlers): SseHandl
 	let finished = false;
 	let cancelled = false;
 
+	// One timer, re-armed as the request progresses: the connect limit until
+	// headers arrive, then the idle limit, restarted by every chunk.
+	let stallTimer: ReturnType<typeof setTimeout> | undefined;
+	const disarm = () => {
+		if (stallTimer !== undefined) {
+			clearTimeout(stallTimer);
+			stallTimer = undefined;
+		}
+	};
+
 	const finish = (fn: () => void) => {
+		disarm();
 		if (!finished && !cancelled) {
 			finished = true;
 			fn();
 		}
 	};
 
+	const stalled = () => {
+		stallTimer = undefined;
+		if (finished || cancelled) return;
+		finished = true;
+		try {
+			xhr.abort();
+		} catch {
+			// already settled
+		}
+		handlers.onError(0, 'timeout');
+	};
+
+	const arm = (ms: number | undefined) => {
+		disarm();
+		if (ms && !finished && !cancelled) stallTimer = setTimeout(stalled, ms);
+	};
+
 	const pump = () => {
 		if (xhr.status !== 200) return; // error path handled on load/error
+		arm(request.idleTimeoutMs);
 		const text: string = xhr.responseText ?? '';
 		seen = drainSseEvents(text, seen, handlers.onData);
 	};
@@ -78,6 +112,7 @@ export function requestSse(request: SseRequest, handlers: SseHandlers): SseHandl
 
 	xhr.onprogress = pump;
 	xhr.onreadystatechange = () => {
+		if (xhr.readyState === 2) arm(request.idleTimeoutMs); // HEADERS_RECEIVED
 		if (xhr.readyState === 3) pump(); // LOADING: incremental text
 	};
 	xhr.onload = () => {
@@ -92,10 +127,12 @@ export function requestSse(request: SseRequest, handlers: SseHandlers): SseHandl
 	xhr.ontimeout = () => finish(() => handlers.onError(0, 'timeout'));
 
 	xhr.send(request.body);
+	arm(request.connectTimeoutMs);
 
 	return {
 		cancel() {
 			cancelled = true;
+			disarm();
 			try {
 				xhr.abort();
 			} catch {

package/src/transport/timeouts.ts

@@ -0,0 +1,53 @@
+/**
+ * Time limits for every network call the client makes (AI-04).
+ *
+ * Without them a stalled mobile connection left `useAiChat` in `loading` or
+ * `streaming`, and `useAiQuota` in `loading`, until the user gave up.
+ */
+
+export interface AiTimeouts {
+	/** Request sent → response headers received, for the chat stream. */
+	connectMs: number;
+	/** Longest silence allowed between two chunks of the chat stream. */
+	idleMs: number;
+	/** Behavior-config fetch, including reading the body. */
+	configMs: number;
+	/** Quota fetch, including reading the body. */
+	quotaMs: number;
+}
+
+/**
+ * The gateway sends headers only once the model has answered, so `connectMs`
+ * also covers time to first token on a large image prompt.
+ */
+export const DEFAULT_AI_TIMEOUTS: AiTimeouts = {
+	connectMs: 30_000,
+	idleMs: 30_000,
+	configMs: 10_000,
+	quotaMs: 10_000,
+};
+
+/**
+ * Runs `run` with an abort signal and rejects with `onTimeout()` after `ms`.
+ * The race matters as much as the signal: an injected `fetchFn` (or an old
+ * polyfill) may ignore the signal entirely.
+ */
+export async function withTimeout<T>(
+	ms: number,
+	run: (signal: AbortSignal | undefined) => Promise<T>,
+	onTimeout: () => Error,
+): Promise<T> {
+	const controller = typeof AbortController === 'undefined' ? undefined : new AbortController();
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const expired = new Promise<never>((_, reject) => {
+		timer = setTimeout(() => {
+			controller?.abort();
+			reject(onTimeout());
+		}, ms);
+	});
+	try {
+		return await Promise.race([run(controller?.signal), expired]);
+	} finally {
+		clearTimeout(timer);
+	}
+}