@chipmobilesdk/rn-ai 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @chipmobilesdk/rn-ai
 
+## 0.4.0
+
+### Minor Changes
+
+- A 401 retry now gets a token the provider had to fetch again. `TokenProvider.requestAccessToken` takes `{ forceRefresh }`, which rn-auth implements by dropping the cached token for that resource, so the retry no longer re-sends the token the gateway had just refused — a cached token is still unexpired by the device's clock when the server rejects it. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  Failures an app can tell apart. `network` is a request that never arrived (no connection, a timeout, a dropped stream) and is retryable; `session-expired` is a session the user must renew. `AiError.cause` carries the code from the layer underneath — the gateway's own code, or rn-auth's — so a screen can explain *why*, and `retryAfterSeconds` is read from the `Retry-After` header when the body omits it. Both new codes have user copy, and the gateway's full code list is mapped rather than guessed from the status.
+
+  The remote behavior config is checked before it is trusted. `configUrl` and the document's `api.baseUrl` must be https (localhost excepted), the document must name the app it is for, its `schemaVersion` must be one this release understands, and `allowedHosts` pins where the client may send its bearer token. A broken TTL no longer means a revalidation on every request, and a retry count is bounded. A not-modified answer against a cache that is no longer there asks again without the ETag instead of reporting the 304 as a failure.
+
+  `configCacheFromKeyValue(port)` makes a durable config cache out of rn-core's `KeyValuePort`, so a second launch uses the last-good document instead of waiting for the network.
+
+  One quota figure: a chat's `done` event and `getQuota()` both record it on the client (`lastQuota()`), so `useAiQuota` and `useAiChat` cannot disagree, and a quota response that does not match the contract is refused rather than displayed. `getQuota()` recovers like a chat: a designated 404/410 reloads the configuration and retries, and a 401 retries once.
+
+  Streamed text reaches the screen on an interval (50 ms by default, `useAiChat(client, { flushIntervalMs })`) rather than once per token, and whatever arrived is flushed with the terminal state, so a half-answer stays on screen when a stream fails. A stream framed with CRLF is parsed incrementally, as the SSE specification allows. The transport seam is a published `StreamTransport` port instead of the internal reader's signature.
+
+- The gateway↔client contract has one definition. `GatewayErrorCode`, `GATEWAY_ERROR_STATUS`, `QUOTA_HEADERS`, `GatewayErrorBody`, `GatewayStreamEvent`, `GatewayQuota`, `GatewayUsage` and `SSE_DONE_SENTINEL` are exported from this package, and the gateway service imports the same types, so an error code, a header name or a stream event added on one side does not compile until the other handles it. The three codes the gateway could already answer with and the client had never heard of — `BAD_REQUEST`, `ENDPOINT_RETIRED`, `INTERNAL` — now map to a typed error instead of a guess from the HTTP status. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+### Patch Changes
+
+- The gateway service (not published to npm) now shares one credential across the process and refuses unauthenticated requests before reading storage. No client-facing change; the entry is here so the release notes record the service work that went with this version. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+- Internal: no module in these packages is over 500 lines any more. The camera controller's session I/O moved to `sessionRuntime` and its contract to `contract.ts`; the Play adapter's shape translation to `iapShapes`; the purchase flow's failure mapping and its receipt-validation hook to modules of their own; the AI client's quota request to `quotaRequest`; the in-memory adapter's attachments and the fake ads engine's clock likewise. Behaviour is unchanged — the splits are by responsibility, and every package's suite passes as it stood. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  The repository also measures what it promised: `npm run perf` prints the median of nine runs of the deterministic hot paths against written budgets (recurrence expansion, theme construction, translation lookup, chart geometry, filter compilation), the demo app has a Performance screen reporting startup phases, time to interactive and the same benchmarks on Hermes, and `npm run check:file-size` keeps the limit from drifting. The budgets and the measured figures are recorded in `docs/standards.md` §VI.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -12,9 +12,12 @@ OpenAI directly and hold no AI credentials.
 - **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)
-- Behavior config: [app-behavior-config](../../specs/005-azure-ai-gateway/contracts/app-behavior-config.md)
+- **Gateway contract**: the error codes, quota headers and stream events this
+  client and the gateway share are exported from this package
+  (`GatewayErrorCode`, `QUOTA_HEADERS`, `GatewayStreamEvent`), and the gateway
+  imports the same definitions — see `## Public API`. The feature's original
+  contract documents live in the repository under
+  `specs/005-azure-ai-gateway/legacy/contracts/` and are not shipped here.
 
 ## Install
 
@@ -39,7 +42,10 @@ resources: [
 2. Create the client (one per app):
 
 ```ts
-import { createAiClient } from '@chipmobilesdk/rn-ai';
+import { configCacheFromKeyValue, createAiClient } from '@chipmobilesdk/rn-ai';
+import { openDurable } from '@chipmobilesdk/rn-core';
+import { createMMKV } from 'react-native-mmkv';
+
 import { auth } from './auth/setup';
 
 export const aiClient = createAiClient({
@@ -47,10 +53,21 @@ export const aiClient = createAiClient({
   configUrl: 'https://<config-host>/appconfig/config/scan-food.json',
   resourceKey: 'ai-gateway',
   auth,
-  // storage: inject a persistent AiConfigCache for offline launches
+  // Cache the behavior config where it survives a restart, so the next launch
+  // does not wait for the network. Any `AiConfigCache` will do; this one is
+  // rn-core's key-value port over MMKV.
+  storage: configCacheFromKeyValue(openDurable(() => createMMKV({ id: 'app.ai' }))),
+  // Optional: pin the hosts the remote config may point the client at.
+  allowedHosts: ['gw.example.com'],
 });
 ```
 
+The config document decides where this client sends its bearer token, so both
+`configUrl` and the document's `api.baseUrl` must be `https` (plain `http` is
+accepted only for `localhost`), the document must name this `appId`, and its
+`schemaVersion` must be one this release understands. Anything else is a
+`config-unavailable` error rather than a request to an unvetted host.
+
 3. Use the hooks:
 
 ```tsx
@@ -83,30 +100,46 @@ send({
   waiting `recovery.retryBackoffMs[n]` (the last step repeats, each capped at
   30 s), at most `recovery.maxSilentRetries` times. A chat cancelled during the
   wait is not retried.
-- **Auth**: acquires tokens via rn-auth (`requestAccessToken('ai-gateway')`);
-  on `401`, reacquires a token and retries once.
+- **Auth**: acquires tokens via rn-auth
+  (`requestAccessToken('ai-gateway')`); on `401` it asks for a token the
+  provider had to fetch again (`{ forceRefresh: true }`) and retries once. The
+  cached token is unexpired by the device's clock after a 401, so without that
+  the retry would re-send the token the gateway just refused.
+- **Quota**: one figure, wherever it came from. A chat's `done` event and
+  `getQuota()` both record it on the client, so `useAiQuota` and `useAiChat`
+  never disagree, and a quota display does not go stale when a chat finishes.
+  `getQuota()` recovers like a chat does: a designated `404`/`410` reloads the
+  configuration and retries, and a `401` retries once with a fresh token.
 - **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`, `retryable: true` |
-  | `idleMs` — silence between two stream chunks | 30 s | `upstream-error`, `retryable: true` |
+  | `connectMs` — chat request sent → headers | 30 s | `network`, `retryable: true` |
+  | `idleMs` — silence between two stream chunks | 30 s | `network`, `retryable: true` |
   | `configMs` — behavior-config fetch | 10 s | stale cache if any, else `config-unavailable` |
-  | `quotaMs` — quota fetch | 10 s | `upstream-error`, `retryable: true` |
+  | `quotaMs` — quota fetch | 10 s | `network`, `retryable: 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 `retryable: true`.
+  `network` with `retryable: true`: the request never reached the service, which
+  is a different thing to tell the user than a service that failed.
 - **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`.
+- **Streamed text** reaches the screen on an interval (50 ms by default), not
+  once per token: `useAiChat(client, { flushIntervalMs })` tunes it, and `0`
+  renders per token. Whatever had arrived is always flushed with the terminal
+  state, so a half-answer stays on screen when a stream fails.
+- **Typed errors** (`AiError.code`): `auth-invalid`, `session-expired`,
+  `not-entitled`, `user-blocked`, `app-unknown`, `rate-limited`,
+  `upstream-busy`, `payload-too-large`, `modality-not-allowed`,
+  `config-unavailable`, `network`, `upstream-error`, `internal`.
+  `AiError.cause` carries the code the layer underneath used — the gateway's own
+  code, or rn-auth's — so a screen can say *why*. `retryAfterSeconds` is read
+  from the body, or from the `Retry-After` header when the body omits it.
 - **Copy keys**: `ai.*` defaults in `aiMessages` — map through your i18n.
 
 ## Public API
@@ -114,13 +147,22 @@ send({
 Everything is exported from `@chipmobilesdk/rn-ai`; internal `config/`,
 `transport/`, `core/`, `react/`, and `diagnostics/` paths are not public.
 
-- Client: `createAiClient`, `AiClient`, `AiClientConfig`, `TokenProvider`
+- Client: `createAiClient`, `AiClient`, `AiClientConfig`, `TokenProvider`,
+  `AccessTokenRequestOptions`
 - Chat: `ChatRequest`, `ChatMessage`, `ContentPart`, `ChatStreamHandlers`,
   `ChatHandle`, `Usage`
 - Behavior and cache: `AppBehaviorConfig`, `AiBehaviorState`, `BehaviorState`,
-  `AiConfigCache`, `QuotaSnapshot`
+  `AiConfigCache`, `configCacheFromKeyValue`, `SUPPORTED_SCHEMA_VERSION`,
+  `QuotaSnapshot`
+- Transport: `StreamTransport` and its `SseRequest` / `SseHandlers` /
+  `SseHandle` / `SseResponseInfo` types. `createAiClient({ transport })` takes
+  any implementation; the default is an XHR reader.
+- The gateway contract, shared with the service so both sides cannot drift:
+  `GatewayErrorCode`, `GatewayErrorBody`, `GatewayQuota`, `GatewayUsage`,
+  `GatewayStreamEvent`, `GATEWAY_ERROR_STATUS`, `QUOTA_HEADERS`,
+  `SSE_DONE_SENTINEL`
 - React: `useAiChat`, `useAiQuota`, `useAiBehaviorState`, `AiChatStatus`,
-  `UseAiChatResult`, `UseAiQuotaResult`. `useAiBehaviorState(client)` re-renders when
+  `UseAiChatOptions`, `UseAiChatResult`, `UseAiQuotaResult`. `useAiBehaviorState(client)` re-renders when
   the config loads or the `aiEnabled` kill switch flips; `client.subscribe` and
   `client.getBehaviorState()` give the same outside React.
 - Diagnostics and copy: `AiError`, `AiErrorCode`, `isAiError`, `aiMessages`,
@@ -144,10 +186,6 @@ Everything is exported from `@chipmobilesdk/rn-ai`; internal `config/`,
 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:

package/package.json

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

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

@@ -31,18 +31,49 @@ read it before assuming a behaviour is built in.
 screen unmounts, otherwise the response resolves against a dead component. Verify
 teardown on every screen that uses it.
 
+## Cache the config, or every launch waits for the network
+
+`createAiClient({ storage })` takes an `AiConfigCache`. Without one the behavior config
+lives in memory only, so each cold start blocks the first chat on a network fetch.
+`configCacheFromKeyValue(port)` adapts rn-core's `KeyValuePort` (MMKV through
+`openDurable`), which is how the demo app wires it.
+
+## What the config document is allowed to say
+
+`configUrl` and the document's `api.baseUrl` must be https (localhost excepted), the
+document must name the same `appId`, and its `schemaVersion` must be one the installed
+release supports. `allowedHosts` pins the hosts the document may point at. A document
+that breaks any of these is a `config-unavailable` error, not a request sent anyway:
+this is where the app's bearer token would go.
+
+## Errors carry a reason
+
+`AiError.code` is what happened; `AiError.cause` is the code underneath (the gateway's,
+or rn-auth's). `network` means the request never arrived and a retry may work;
+`session-expired` means sign-in is needed; `not-entitled` means premium. Use
+`messageKeyForError(error)` for the copy — one key per code, nothing to map by hand.
+
 ## Public API
 
 Runtime:
 
-- `createAiClient(...)` — transport-level client
-- `useAiChat(...)` → `UseAiChatResult`, with `AiChatStatus` for state
-- `useAiQuota(...)` → `UseAiQuotaResult`
+- `createAiClient(...)` — the client: `chat`, `getQuota`, `lastQuota`, `reloadConfig`,
+  `getBehaviorState`, `subscribe`
+- `useAiChat(client, { flushIntervalMs })` → `UseAiChatResult` (`send`, `cancel`,
+  `status`, `text`, `error`, `retryAt`, `quota`), with `AiChatStatus` for state
+- `useAiQuota(...)` → `UseAiQuotaResult`; `useAiBehaviorState(...)` for the kill switch
+- `configCacheFromKeyValue(port)`, `SUPPORTED_SCHEMA_VERSION`
 - `AiError`, `isAiError` — narrow before reading `AiErrorCode`
-- `aiMessages`, `aiMessage` — user-facing strings keyed by `AiMessageKey`
+- `aiMessages`, `aiMessage`, `aiMessageSet`, `messageKeyForError`
+- `GATEWAY_ERROR_STATUS`, `QUOTA_HEADERS`, `SSE_DONE_SENTINEL` — the gateway contract
 
 Use `aiMessage` for anything shown to the user. Never render `AiError.message` directly.
 
+## Streamed text is batched
+
+`useAiChat` flushes accumulated deltas every 50 ms rather than rendering per token; pass
+`flushIntervalMs: 0` for per-token rendering. Do not add your own buffering on top.
+
 ## Where the detail lives
 
 Read one section of `node_modules/@chipmobilesdk/rn-ai/README.md`:

package/src/config/behaviorConfig.ts

@@ -1,4 +1,4 @@
-import { createListenerSet, createSingleFlight } from '@chipmobilesdk/rn-core';
+import { createListenerSet, createSingleFlight, type KeyValuePort } from '@chipmobilesdk/rn-core';
 
 import { AiError } from '../diagnostics/errors';
 import { DEFAULT_AI_TIMEOUTS, withTimeout } from '../transport/timeouts';
@@ -35,18 +35,84 @@ export class MemoryConfigCache implements AiConfigCache {
 	}
 }
 
+/**
+ * An `AiConfigCache` over rn-core's synchronous `KeyValuePort` (AI-10).
+ *
+ * Without a durable cache every launch waits for the network before the first
+ * chat, which is exactly what the cache-first design exists to avoid. Open the
+ * port the way the app opens its other durable state, for example
+ * `openDurable(() => createMMKV({ id: 'app' }))`.
+ */
+export function configCacheFromKeyValue(port: KeyValuePort): AiConfigCache {
+	return {
+		async get(key) {
+			return port.getString(key) ?? null;
+		},
+		async set(key, value) {
+			port.set(key, value);
+		},
+	};
+}
+
 export type BehaviorState = 'unloaded' | 'ready-network' | 'ready-cache' | 'unavailable';
 
+/** The newest document layout this release understands. */
+export const SUPPORTED_SCHEMA_VERSION = 1;
+
+/** Bounds on the remote-configured recovery, so a bad document cannot stall a chat. */
+const MAX_SILENT_RETRIES = 5;
+const MIN_REFRESH_TTL_SECONDS = 30;
+const DEFAULT_REFRESH_TTL_SECONDS = 21_600;
+
 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 {
+const positiveInt = (value: unknown, fallback: number): number =>
+	typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+
+function invalid(reason: string): never {
+	throw new AiError('config-unavailable', `behavior config ${reason}`);
+}
+
+/** https, or http on a development machine: a bearer token travels to this host. */
+export function isTrustedUrl(url: string): boolean {
+	if (/^https:\/\//i.test(url)) {
+		return true;
+	}
+	return /^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?(\/|$)/i.test(url);
+}
+
+function hostOf(url: string): string {
+	return url
+		.replace(/^[a-z]+:\/\//i, '')
+		.split(/[/:?#]/)[0]!
+		.toLowerCase();
+}
+
+export interface ParseBehaviorConfigOptions {
+	/** The app this document must be for; a document for another app is refused. */
+	expectedAppId?: string;
+	/** Hosts `api.baseUrl` may name. Any host is accepted when omitted. */
+	allowedHosts?: readonly string[];
+}
+
+/**
+ * Parse + validate; unknown fields ignored (forward compatibility).
+ *
+ * Every field this package acts on is checked here, because the document is
+ * remote and the alternative is a TypeError inside an XHR callback, a revalidate
+ * on every single request, or a bearer token sent to a host nobody vetted
+ * (AI-06, AI-07).
+ */
+export function parseBehaviorConfig(
+	json: string,
+	options: ParseBehaviorConfigOptions = {},
+): AppBehaviorConfig {
 	let raw: Record<string, unknown>;
 	try {
 		raw = JSON.parse(json) as Record<string, unknown>;
 	} catch {
-		throw new AiError('config-unavailable', 'behavior config is not valid JSON');
+		invalid('is not valid JSON');
 	}
 	const api = raw.api as Partial<AppBehaviorConfig['api']> | undefined;
 	if (
@@ -54,17 +120,42 @@ export function parseBehaviorConfig(json: string): AppBehaviorConfig {
 		typeof api?.baseUrl !== 'string' ||
 		!Array.isArray(api.scopes)
 	) {
-		throw new AiError('config-unavailable', 'behavior config is missing required fields');
+		invalid('is missing required fields');
+	}
+
+	const schemaVersion = positiveInt(raw.schemaVersion, 1);
+	if (schemaVersion > SUPPORTED_SCHEMA_VERSION) {
+		// A newer layout may mean something different by the same field names.
+		invalid(`declares schema version ${schemaVersion}, newer than ${SUPPORTED_SCHEMA_VERSION}`);
+	}
+	if (options.expectedAppId !== undefined && raw.appId !== options.expectedAppId) {
+		// The cache key and the request path carry the app id; a document for
+		// another app would send this app's traffic somewhere else entirely.
+		invalid(`is for another app (${raw.appId})`);
+	}
+
+	const baseUrl = api.baseUrl.replace(/\/$/, '');
+	if (!isTrustedUrl(baseUrl)) {
+		invalid('names a baseUrl that is not https');
 	}
+	if (options.allowedHosts && !options.allowedHosts.includes(hostOf(baseUrl))) {
+		invalid(`names a baseUrl outside the allowed hosts (${hostOf(baseUrl)})`);
+	}
+
 	const recovery = (raw.recovery ?? {}) as Partial<AppBehaviorConfig['recovery']>;
 	const features = (raw.features ?? {}) as Partial<AppBehaviorConfig['features']>;
 	return {
-		schemaVersion: Number(raw.schemaVersion ?? 1),
+		schemaVersion,
 		appId: raw.appId,
-		configVersion: Number(raw.configVersion ?? 0),
-		refreshTtlSeconds: Number(raw.refreshTtlSeconds ?? 21600),
+		configVersion: positiveInt(raw.configVersion, 0),
+		// A TTL that was NaN made `isFresh` false forever, so every request
+		// revalidated over the network (AI-06).
+		refreshTtlSeconds: Math.max(
+			MIN_REFRESH_TTL_SECONDS,
+			positiveInt(raw.refreshTtlSeconds, DEFAULT_REFRESH_TTL_SECONDS),
+		),
 		api: {
-			baseUrl: api.baseUrl.replace(/\/$/, ''),
+			baseUrl,
 			scopes: api.scopes.filter((s): s is string => typeof s === 'string'),
 			supportsStreaming: api.supportsStreaming !== false,
 		},
@@ -73,9 +164,12 @@ export function parseBehaviorConfig(json: string): AppBehaviorConfig {
 		// throw a TypeError inside the XHR error callback, where nothing caught it.
 		recovery: {
 			reloadOnHttpStatus: numbers(recovery.reloadOnHttpStatus) ?? [404, 410],
-			maxSilentRetries: Number.isFinite(recovery.maxSilentRetries)
-				? Number(recovery.maxSilentRetries)
-				: 1,
+			maxSilentRetries: Math.min(
+				MAX_SILENT_RETRIES,
+				Number.isFinite(recovery.maxSilentRetries)
+					? Math.max(0, Number(recovery.maxSilentRetries))
+					: 1,
+			),
 			retryBackoffMs: numbers(recovery.retryBackoffMs) ?? [500, 2000],
 		},
 		features: { aiEnabled: features.aiEnabled !== false },
@@ -96,6 +190,8 @@ export interface BehaviorConfigDeps {
 	now?: () => number;
 	/** Limit on one config fetch, body included. Defaults to 10 s. */
 	timeoutMs?: number;
+	/** Hosts the document's `api.baseUrl` may name. */
+	allowedHosts?: readonly string[];
 }
 
 /**
@@ -113,7 +209,7 @@ export class BehaviorConfigManager {
 	 * chat and a quota call together, and each used to fetch the config itself.
 	 */
 	private readonly cacheRead = createSingleFlight<void>();
-	private readonly networkFetch = createSingleFlight<AppBehaviorConfig | undefined>();
+	private readonly networkFetch = createSingleFlight<AppBehaviorConfig>();
 	private currentState: BehaviorState = 'unloaded';
 	private readonly stateListeners = createListenerSet<[]>();
 
@@ -134,12 +230,24 @@ export class BehaviorConfigManager {
 	}
 
 	constructor(private deps: BehaviorConfigDeps) {
+		if (!isTrustedUrl(deps.configUrl)) {
+			// The document decides where the tokens go, so where it comes from
+			// matters as much (AI-07).
+			throw new AiError('config-unavailable', 'configUrl must be https');
+		}
 		this.cacheKey = `rn-ai:config:${deps.appId}`;
 		this.cache = deps.cache ?? new MemoryConfigCache();
 		this.fetchFn = deps.fetchFn ?? fetch;
 		this.now = deps.now ?? Date.now;
 	}
 
+	private parse(json: string): AppBehaviorConfig {
+		return parseBehaviorConfig(json, {
+			expectedAppId: this.deps.appId,
+			...(this.deps.allowedHosts ? { allowedHosts: this.deps.allowedHosts } : {}),
+		});
+	}
+
 	private isFresh(envelope: CacheEnvelope, config: AppBehaviorConfig): boolean {
 		return this.now() - envelope.fetchedAt < config.refreshTtlSeconds * 1000;
 	}
@@ -154,44 +262,62 @@ export class BehaviorConfigManager {
 		if (!stored) return;
 		try {
 			const envelope = JSON.parse(stored) as CacheEnvelope;
-			this.current = { config: parseBehaviorConfig(envelope.configJson), envelope };
+			this.current = { config: this.parse(envelope.configJson), envelope };
 			this.setState('ready-cache');
 		} catch {
 			// corrupted cache entries are ignored, not fatal
 		}
 	}
 
-	private fetchNetwork(): Promise<AppBehaviorConfig | undefined> {
+	private fetchNetwork(): Promise<AppBehaviorConfig> {
 		return this.networkFetch.run(() => this.fetchFromNetwork());
 	}
 
-	private async fetchFromNetwork(): Promise<AppBehaviorConfig | undefined> {
+	/** One attempt; `conditional` sends the stored ETag when there is one. */
+	private async fetchOnce(
+		conditional: boolean,
+	): Promise<{ status: number; text: string; etag?: string }> {
 		const headers: Record<string, string> = {};
-		if (this.current?.envelope.etag) {
-			headers['If-None-Match'] = this.current.envelope.etag;
+		const etag = this.current?.envelope.etag;
+		if (conditional && etag) {
+			headers['If-None-Match'] = etag;
 		}
 		// Bounded: with no cache, a hung fetch used to block every chat and quota call.
-		const { response, configJson } = await withTimeout(
+		return 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() : '' };
+				const response = await this.fetchFn(this.deps.configUrl, { headers, signal });
+				return {
+					status: response.status,
+					text: response.ok && response.status !== 304 ? await response.text() : '',
+					etag: response.headers.get('etag') ?? undefined,
+				};
 			},
 			() => 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);
-			this.setState('ready-network');
-			return this.current.config;
+	}
+
+	private async fetchFromNetwork(): Promise<AppBehaviorConfig> {
+		let result = await this.fetchOnce(true);
+		if (result.status === 304) {
+			if (this.current) {
+				this.current.envelope.fetchedAt = this.now();
+				await this.persist(this.current.envelope);
+				this.setState('ready-network');
+				return this.current.config;
+			}
+			// Not-modified against a cache that is no longer there (it was cleared,
+			// or it failed to parse). Asking again without the ETag is the answer;
+			// reporting `config fetch failed: 304` was not (AI-17).
+			result = await this.fetchOnce(false);
 		}
-		if (!response.ok) {
-			throw new AiError('config-unavailable', `config fetch failed: ${response.status}`);
+		if (result.status < 200 || result.status >= 300) {
+			throw new AiError('config-unavailable', `config fetch failed: ${result.status}`);
 		}
-		const config = parseBehaviorConfig(configJson);
+		const config = this.parse(result.text);
 		const envelope: CacheEnvelope = {
-			configJson,
-			etag: response.headers.get('etag') ?? undefined,
+			configJson: result.text,
+			etag: result.etag,
 			fetchedAt: this.now(),
 		};
 		this.current = { config, envelope };
@@ -218,16 +344,11 @@ export class BehaviorConfigManager {
 			return this.current.config;
 		}
 		try {
-			const fetched = await this.fetchNetwork();
-			if (fetched) return fetched;
+			return await this.fetchNetwork();
 		} catch (e) {
 			if (this.current) return this.current.config; // stale beats broken
 			this.setState('unavailable');
 			throw e instanceof AiError ? e : new AiError('config-unavailable', String(e));
 		}
-		// fetchNetwork only returns undefined when a 304 raced an empty cache.
-		if (this.current) return (this.current as { config: AppBehaviorConfig }).config;
-		this.setState('unavailable');
-		throw new AiError('config-unavailable', 'no configuration available');
 	}
 }

package/src/contract/gateway.ts

@@ -0,0 +1,91 @@
+/**
+ * The gateway↔client contract: error codes, quota headers, stream events.
+ *
+ * One definition, imported by both sides (GW-13). The gateway's own codes and
+ * the client's map of them were two hand-maintained lists, and they had already
+ * drifted: `BAD_REQUEST`, `ENDPOINT_RETIRED` and `INTERNAL` existed on the
+ * server and were unknown to the client, which fell back to a guess from the
+ * status. Adding a code now fails to compile on whichever side has not handled
+ * it.
+ *
+ * Types and plain constants only, and no import of anything: the gateway runs
+ * on Node and imports this file for its types alone.
+ */
+
+/** Every error the gateway answers with (`error.code` in the body). */
+export type GatewayErrorCode =
+	| 'BAD_REQUEST'
+	| 'AUTH_INVALID'
+	| 'NOT_ENTITLED'
+	| 'USER_BLOCKED'
+	| 'APP_UNKNOWN'
+	| 'ENDPOINT_RETIRED'
+	| 'PAYLOAD_TOO_LARGE'
+	| 'MODALITY_NOT_ALLOWED'
+	| 'RATE_LIMITED'
+	| 'UPSTREAM_BUSY'
+	| 'UPSTREAM_ERROR'
+	| 'INTERNAL';
+
+/** The HTTP status each code is sent with. */
+export const GATEWAY_ERROR_STATUS: Readonly<Record<GatewayErrorCode, number>> = {
+	BAD_REQUEST: 400,
+	AUTH_INVALID: 401,
+	NOT_ENTITLED: 403,
+	USER_BLOCKED: 403,
+	APP_UNKNOWN: 404,
+	ENDPOINT_RETIRED: 410,
+	PAYLOAD_TOO_LARGE: 413,
+	MODALITY_NOT_ALLOWED: 415,
+	RATE_LIMITED: 429,
+	UPSTREAM_BUSY: 429,
+	UPSTREAM_ERROR: 500,
+	INTERNAL: 500,
+};
+
+/** The error body. `message` is safe to log; it never carries upstream detail. */
+export interface GatewayErrorBody {
+	error: {
+		code: GatewayErrorCode;
+		message: string;
+		retryAfterSeconds?: number;
+	};
+}
+
+/** The quota headers, by name. A rename here breaks both sides' compile. */
+export const QUOTA_HEADERS = {
+	minuteRemaining: 'X-Quota-Minute-Remaining',
+	dayRemaining: 'X-Quota-Day-Remaining',
+	dayTokensRemaining: 'X-Quota-Day-Tokens-Remaining',
+} as const;
+
+/** The names field by field, so a side declaring its own literals is checked exactly. */
+export type QuotaHeaderNames = typeof QUOTA_HEADERS;
+export type QuotaHeaderName = QuotaHeaderNames[keyof QuotaHeaderNames];
+
+/** What is left of an app's allowance, as the gateway reports it. */
+export interface GatewayQuota {
+	minuteRemaining: number;
+	dayRemaining: number;
+	dayTokensRemaining: number;
+}
+
+/** What one answer cost. */
+export interface GatewayUsage {
+	promptTokens: number;
+	completionTokens: number;
+	totalTokens: number;
+}
+
+/** The `data:` payloads of a chat stream, before the `[DONE]` sentinel. */
+export type GatewayStreamEvent =
+	| { type: 'delta'; text: string }
+	| { type: 'done'; usage: GatewayUsage; quota?: GatewayQuota }
+	| { type: 'error'; code: GatewayErrorCode };
+
+/** The last `data:` line of a stream that completed. */
+export const SSE_DONE_SENTINEL = '[DONE]';
+export type SseDoneSentinel = typeof SSE_DONE_SENTINEL;
+
+/** The `Retry-After` header, which a 429 always carries. */
+export const RETRY_AFTER_HEADER = 'Retry-After';