@chipmobilesdk/rn-ai 0.4.0 → 0.5.0

package/lib/module/config/behaviorConfig.js

@@ -0,0 +1,275 @@
+"use strict";
+
+import { createListenerSet, createSingleFlight } from '@chipmobilesdk/rn-core';
+import { AiError } from "../diagnostics/errors.js";
+import { DEFAULT_AI_TIMEOUTS, withTimeout } from "../transport/timeouts.js";
+
+/** App behavior configuration (contracts/app-behavior-config.md). */
+
+/** Persistence port; default is in-memory (inject a durable store for offline launch). */
+
+export class MemoryConfigCache {
+  map = new Map();
+  async get(key) {
+    return this.map.get(key) ?? null;
+  }
+  async set(key, value) {
+    this.map.set(key, value);
+  }
+}
+
+/**
+ * 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) {
+  return {
+    async get(key) {
+      return port.getString(key) ?? null;
+    },
+    async set(key, value) {
+      port.set(key, value);
+    }
+  };
+}
+/** 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 => Array.isArray(value) ? value.filter(n => Number.isFinite(n)) : undefined;
+const positiveInt = (value, fallback) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+function invalid(reason) {
+  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) {
+  if (/^https:\/\//i.test(url)) {
+    return true;
+  }
+  return /^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?(\/|$)/i.test(url);
+}
+function hostOf(url) {
+  return url.replace(/^[a-z]+:\/\//i, '').split(/[/:?#]/)[0].toLowerCase();
+}
+/**
+ * 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, options = {}) {
+  let raw;
+  try {
+    raw = JSON.parse(json);
+  } catch {
+    invalid('is not valid JSON');
+  }
+  const api = raw.api;
+  if (typeof raw.appId !== 'string' || typeof api?.baseUrl !== 'string' || !Array.isArray(api.scopes)) {
+    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 ?? {};
+  const features = raw.features ?? {};
+  return {
+    schemaVersion,
+    appId: raw.appId,
+    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,
+      scopes: api.scopes.filter(s => typeof s === 'string'),
+      supportsStreaming: api.supportsStreaming !== false
+    },
+    limitsDisplay: raw.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: numbers(recovery.reloadOnHttpStatus) ?? [404, 410],
+      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
+    }
+  };
+}
+/**
+ * Cache-first behavior config (FR-018): launch never blocks on the network;
+ * TTL revalidation uses ETag; designated errors force a reload.
+ */
+export class BehaviorConfigManager {
+  /**
+   * One cache read and one network fetch at a time (AI-08): a cold start makes a
+   * chat and a quota call together, and each used to fetch the config itself.
+   */
+  cacheRead = createSingleFlight();
+  networkFetch = createSingleFlight();
+  currentState = 'unloaded';
+  stateListeners = createListenerSet();
+
+  /** Where the config came from, or why there is none. */
+  get state() {
+    return this.currentState;
+  }
+
+  /** Called whenever `state` changes (AI-09). */
+  subscribe(listener) {
+    return this.stateListeners.add(listener);
+  }
+  setState(next) {
+    if (next === this.currentState) return;
+    this.currentState = next;
+    this.stateListeners.notify();
+  }
+  constructor(deps) {
+    this.deps = deps;
+    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;
+  }
+  parse(json) {
+    return parseBehaviorConfig(json, {
+      expectedAppId: this.deps.appId,
+      ...(this.deps.allowedHosts ? {
+        allowedHosts: this.deps.allowedHosts
+      } : {})
+    });
+  }
+  isFresh(envelope, config) {
+    return this.now() - envelope.fetchedAt < config.refreshTtlSeconds * 1000;
+  }
+  loadFromCache() {
+    return this.current ? Promise.resolve() : this.cacheRead.run(() => this.readCache());
+  }
+  async readCache() {
+    if (this.current) return;
+    const stored = await this.cache.get(this.cacheKey).catch(() => null);
+    if (!stored) return;
+    try {
+      const envelope = JSON.parse(stored);
+      this.current = {
+        config: this.parse(envelope.configJson),
+        envelope
+      };
+      this.setState('ready-cache');
+    } catch {
+      // corrupted cache entries are ignored, not fatal
+    }
+  }
+  fetchNetwork() {
+    return this.networkFetch.run(() => this.fetchFromNetwork());
+  }
+
+  /** One attempt; `conditional` sends the stored ETag when there is one. */
+  async fetchOnce(conditional) {
+    const headers = {};
+    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.
+    return withTimeout(this.deps.timeoutMs ?? DEFAULT_AI_TIMEOUTS.configMs, async signal => {
+      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'));
+  }
+  async fetchFromNetwork() {
+    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 (result.status < 200 || result.status >= 300) {
+      throw new AiError('config-unavailable', `config fetch failed: ${result.status}`);
+    }
+    const config = this.parse(result.text);
+    const envelope = {
+      configJson: result.text,
+      etag: result.etag,
+      fetchedAt: this.now()
+    };
+    this.current = {
+      config,
+      envelope
+    };
+    await this.persist(envelope);
+    this.setState('ready-network');
+    return config;
+  }
+  async persist(envelope) {
+    await this.cache.set(this.cacheKey, JSON.stringify(envelope)).catch(() => undefined);
+  }
+
+  /**
+   * Cache-first read. Fresh cache returns immediately; stale cache returns
+   * immediately too while a background revalidation runs; no cache at all
+   * falls through to the network (or `config-unavailable`).
+   */
+  async getConfig(options = {}) {
+    await this.loadFromCache();
+    if (!options.forceReload && this.current) {
+      if (!this.isFresh(this.current.envelope, this.current.config)) {
+        this.fetchNetwork().catch(() => undefined); // background revalidate
+      }
+      return this.current.config;
+    }
+    try {
+      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));
+    }
+  }
+}
+//# sourceMappingURL=behaviorConfig.js.map

package/lib/module/config/behaviorConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createListenerSet","createSingleFlight","AiError","DEFAULT_AI_TIMEOUTS","withTimeout","MemoryConfigCache","map","Map","get","key","set","value","configCacheFromKeyValue","port","getString","SUPPORTED_SCHEMA_VERSION","MAX_SILENT_RETRIES","MIN_REFRESH_TTL_SECONDS","DEFAULT_REFRESH_TTL_SECONDS","numbers","Array","isArray","filter","n","Number","isFinite","undefined","positiveInt","fallback","Math","floor","invalid","reason","isTrustedUrl","url","test","hostOf","replace","split","toLowerCase","parseBehaviorConfig","json","options","raw","JSON","parse","api","appId","baseUrl","scopes","schemaVersion","expectedAppId","allowedHosts","includes","recovery","features","configVersion","refreshTtlSeconds","max","s","supportsStreaming","limitsDisplay","reloadOnHttpStatus","maxSilentRetries","min","retryBackoffMs","aiEnabled","BehaviorConfigManager","cacheRead","networkFetch","currentState","stateListeners","state","subscribe","listener","add","setState","next","notify","constructor","deps","configUrl","cacheKey","cache","fetchFn","fetch","now","Date","isFresh","envelope","config","fetchedAt","loadFromCache","current","Promise","resolve","run","readCache","stored","catch","configJson","fetchNetwork","fetchFromNetwork","fetchOnce","conditional","headers","etag","timeoutMs","configMs","signal","response","status","text","ok","result","persist","stringify","getConfig","forceReload","e","String"],"sourceRoot":"../../../src","sources":["config/behaviorConfig.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/contract/gateway.js

@@ -0,0 +1,56 @@
+"use strict";
+
+/**
+ * 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). */
+
+/** The HTTP status each code is sent with. */
+export const GATEWAY_ERROR_STATUS = {
+  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. */
+
+/** 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'
+};
+
+/** The names field by field, so a side declaring its own literals is checked exactly. */
+
+/** What is left of an app's allowance, as the gateway reports it. */
+
+/** What one answer cost. */
+
+/** The `data:` payloads of a chat stream, before the `[DONE]` sentinel. */
+
+/** The last `data:` line of a stream that completed. */
+export const SSE_DONE_SENTINEL = '[DONE]';
+/** The `Retry-After` header, which a 429 always carries. */
+export const RETRY_AFTER_HEADER = 'Retry-After';
+//# sourceMappingURL=gateway.js.map

package/lib/module/contract/gateway.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["GATEWAY_ERROR_STATUS","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","QUOTA_HEADERS","minuteRemaining","dayRemaining","dayTokensRemaining","SSE_DONE_SENTINEL","RETRY_AFTER_HEADER"],"sourceRoot":"../../../src","sources":["contract/gateway.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;;AAeA;AACA,OAAO,MAAMA,oBAAgE,GAAG;EAC/EC,WAAW,EAAE,GAAG;EAChBC,YAAY,EAAE,GAAG;EACjBC,YAAY,EAAE,GAAG;EACjBC,YAAY,EAAE,GAAG;EACjBC,WAAW,EAAE,GAAG;EAChBC,gBAAgB,EAAE,GAAG;EACrBC,iBAAiB,EAAE,GAAG;EACtBC,oBAAoB,EAAE,GAAG;EACzBC,YAAY,EAAE,GAAG;EACjBC,aAAa,EAAE,GAAG;EAClBC,cAAc,EAAE,GAAG;EACnBC,QAAQ,EAAE;AACX,CAAC;;AAED;;AASA;AACA,OAAO,MAAMC,aAAa,GAAG;EAC5BC,eAAe,EAAE,0BAA0B;EAC3CC,YAAY,EAAE,uBAAuB;EACrCC,kBAAkB,EAAE;AACrB,CAAU;;AAEV;;AAIA;;AAOA;;AAOA;;AAMA;AACA,OAAO,MAAMC,iBAAiB,GAAG,QAAQ;AAGzC;AACA,OAAO,MAAMC,kBAAkB,GAAG,aAAa","ignoreList":[]}

package/lib/module/core/aiClient.js

@@ -0,0 +1,327 @@
+"use strict";
+
+import { createDiagnosticChannel, createListenerSet, realScheduler } from '@chipmobilesdk/rn-core';
+import { BehaviorConfigManager } from "../config/behaviorConfig.js";
+import { SSE_DONE_SENTINEL } from "../contract/gateway.js";
+import { AiError, errorFromHttp } from "../diagnostics/errors.js";
+import { requestSse } from "../transport/sseClient.js";
+import { createQuotaRequest } from "./quotaRequest.js";
+import { DEFAULT_AI_TIMEOUTS } from "../transport/timeouts.js";
+
+/** Every failure a caller receives also goes to the app's SDK sinks (CORE-08). */
+const channel = createDiagnosticChannel('rn-ai');
+function report(operation, error) {
+  channel.emit(error.code, error.retryable ? 'warn' : 'error', {
+    operation,
+    retryable: error.retryable
+  });
+}
+
+/** Minimal slice of the rn-auth `Auth` controller the client needs. */
+
+/** What one answer cost, as the gateway reports it. */
+
+/** What is left of the app's allowance. */
+
+/** Ceiling on one remote-configured backoff step, so a bad document cannot stall a chat. */
+const MAX_RETRY_BACKOFF_MS = 30_000;
+
+/** The wait before silent retry `index` (0-based); the last configured step repeats. */
+function backoffBefore(steps, index) {
+  const step = steps[Math.min(index, steps.length - 1)] ?? 0;
+  return Math.min(Math.max(0, step), MAX_RETRY_BACKOFF_MS);
+}
+/** A quota from the wire, or nothing: a malformed one is not displayed (AI-13). */
+function asQuota(value) {
+  if (typeof value !== 'object' || value === null) {
+    return undefined;
+  }
+  const candidate = value;
+  const fields = [candidate.minuteRemaining, candidate.dayRemaining, candidate.dayTokensRemaining];
+  if (!fields.every(field => typeof field === 'number' && Number.isFinite(field))) {
+    return undefined;
+  }
+  return {
+    minuteRemaining: candidate.minuteRemaining,
+    dayRemaining: candidate.dayRemaining,
+    dayTokensRemaining: candidate.dayTokensRemaining
+  };
+}
+export function createAiClient(clientConfig) {
+  const resourceKey = clientConfig.resourceKey ?? 'ai-gateway';
+  const transport = clientConfig.transport ?? requestSse;
+  const fetchFn = clientConfig.fetchFn ?? fetch;
+  const timeouts = {
+    ...DEFAULT_AI_TIMEOUTS,
+    ...clientConfig.timeouts
+  };
+  const scheduler = clientConfig.scheduler ?? realScheduler;
+  const configManager = new BehaviorConfigManager({
+    configUrl: clientConfig.configUrl,
+    appId: clientConfig.appId,
+    cache: clientConfig.storage,
+    fetchFn: clientConfig.fetchFn,
+    timeoutMs: timeouts.configMs,
+    ...(clientConfig.allowedHosts ? {
+      allowedHosts: clientConfig.allowedHosts
+    } : {})
+  });
+  let lastConfig;
+  const behaviorListeners = createListenerSet();
+  let snapshot;
+  let quota;
+
+  /** Rebuilt only when a field changes, so useSyncExternalStore sees a stable object. */
+  function behaviorState() {
+    const config = configManager.state;
+    const aiEnabled = lastConfig?.features.aiEnabled ?? true;
+    if (!snapshot || snapshot.config !== config || snapshot.aiEnabled !== aiEnabled) {
+      snapshot = {
+        config,
+        aiEnabled
+      };
+    }
+    return snapshot;
+  }
+  function setLastConfig(next) {
+    const wasEnabled = lastConfig?.features.aiEnabled ?? true;
+    lastConfig = next;
+    if (next.features.aiEnabled !== wasEnabled) behaviorListeners.notify();
+  }
+
+  /** One place records the quota, whichever call learned it (AI-13). */
+  function setQuota(next) {
+    if (!next || quota && shallowSameQuota(quota, next)) {
+      return;
+    }
+    quota = next;
+    behaviorListeners.notify();
+  }
+  async function acquire(options = {}) {
+    const config = await configManager.getConfig();
+    setLastConfig(config);
+    if (!config.features.aiEnabled) {
+      throw new AiError('config-unavailable', 'AI is disabled for this app', {
+        recoverable: false
+      });
+    }
+    const tokenResult = await clientConfig.auth.requestAccessToken(resourceKey, {
+      forceRefresh: options.forceRefresh === true
+    });
+    if (tokenResult.status !== 'success' || !tokenResult.token) {
+      // What the auth layer called it, kept as the cause: a screen has to tell
+      // "sign in again" from "you are offline" (AI-11).
+      throw tokenError(tokenResult.status, tokenResult.errorCode);
+    }
+    return {
+      config,
+      token: tokenResult.token
+    };
+  }
+  const endpoint = (config, path) => `${config.api.baseUrl}/api/v1/apps/${clientConfig.appId}/${path}`;
+  function chat(request, handlers) {
+    let cancelled = false;
+    let settled = false;
+    let inner;
+
+    // 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) {
+        if (!cancelled && !settled) handlers.onDelta(text);
+      },
+      done(result) {
+        if (cancelled || settled) return;
+        settled = true;
+        setQuota(result.quota);
+        handlers.onDone(result);
+      },
+      error(error) {
+        if (cancelled || settled) return;
+        settled = true;
+        inner?.cancel();
+        report('chat', error);
+        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 => emit.error(e instanceof AiError ? e : new AiError('internal', e instanceof Error ? e.message : String(e)));
+    const guarded = fn => (...args) => {
+      try {
+        fn(...args);
+      } catch (e) {
+        fail(e);
+      }
+    };
+    const attempt = async state => {
+      const {
+        config,
+        token
+      } = await acquire({
+        forceRefresh: state.authRetries > 0
+      });
+      if (cancelled) return;
+      let done;
+      let streamErrorCode;
+      inner = transport({
+        url: endpoint(config, 'chat'),
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${token}`,
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(request),
+        connectTimeoutMs: timeouts.connectMs,
+        idleTimeoutMs: timeouts.idleMs
+      }, {
+        onData: guarded(payload => {
+          if (payload === SSE_DONE_SENTINEL) return;
+          let event;
+          try {
+            event = JSON.parse(payload);
+          } catch {
+            return;
+          }
+          if (event.type === 'delta' && typeof event.text === 'string') {
+            emit.delta(event.text);
+          } else if (event.type === 'done' && event.usage) {
+            done = {
+              usage: event.usage,
+              quota: asQuota(event.quota)
+            };
+          } else if (event.type === 'error') {
+            streamErrorCode = event.code ?? 'UPSTREAM_ERROR';
+          }
+        }),
+        onEnd: guarded(() => {
+          if (streamErrorCode) {
+            emit.error(new AiError('upstream-error', 'the AI service failed mid-response', {
+              cause: streamErrorCode
+            }));
+          } else if (done) {
+            emit.done(done);
+          } else {
+            // Headers said 200 and the body stopped short: the connection
+            // dropped mid-answer, which is a network failure, not a fault
+            // of the service.
+            emit.error(new AiError('network', 'the stream ended before it completed'));
+          }
+        }),
+        onError: guarded((status, bodyText, response) => {
+          if (cancelled) return;
+          recover(status, bodyText, state, {
+            ...(response ? {
+              getHeader: name => response.getHeader(name)
+            } : {})
+          }, next => attempt(next).catch(fail), fail, emit.error);
+        })
+      });
+    };
+    attempt({
+      configReloads: 0,
+      authRetries: 0
+    }).catch(fail);
+    return {
+      cancel() {
+        cancelled = true;
+        inner?.cancel();
+      }
+    };
+  }
+
+  /**
+   * The two recoveries the contract promises, in one place so chat and quota
+   * cannot drift (AI-13): a designated status reloads the configuration and
+   * retries after the configured backoff, and a 401 retries once with a token
+   * the provider had to fetch again.
+   */
+  function recover(status, bodyText, state, context, retry, onFailure, onGiveUp) {
+    const config = lastConfig;
+    if (config && config.recovery.reloadOnHttpStatus.includes(status) && state.configReloads < config.recovery.maxSilentRetries) {
+      // Waits `recovery.retryBackoffMs` first (AI-05): a gateway mid-rollout
+      // that answered 410 a moment ago may well answer it again at once.
+      const retryAfter = backoffBefore(config.recovery.retryBackoffMs, state.configReloads);
+      configManager.getConfig({
+        forceReload: true
+      }).then(reloaded => {
+        setLastConfig(reloaded);
+        scheduler.setTimeout(() => retry({
+          ...state,
+          configReloads: state.configReloads + 1
+        }), retryAfter);
+      }, e => onFailure(e instanceof AiError ? e : new AiError('config-unavailable', String(e))));
+      return;
+    }
+    // Expired server-side session → one retry with a token the provider
+    // actually re-fetched.
+    if (status === 401 && state.authRetries < 1) {
+      retry({
+        ...state,
+        authRetries: state.authRetries + 1
+      });
+      return;
+    }
+    onGiveUp(errorFromHttp(status, bodyText, context));
+  }
+  const {
+    getQuota
+  } = createQuotaRequest({
+    fetchFn,
+    timeouts,
+    acquire,
+    endpoint,
+    asQuota,
+    recover,
+    report: error => report('quota', error),
+    setQuota
+  });
+  return {
+    chat,
+    getQuota,
+    lastQuota: () => quota,
+    getBehaviorState: () => behaviorState(),
+    subscribe: listener => {
+      const fromManager = configManager.subscribe(listener);
+      const fromClient = behaviorListeners.add(listener);
+      return () => {
+        fromManager();
+        fromClient();
+      };
+    },
+    reloadConfig: async () => {
+      setLastConfig(await configManager.getConfig({
+        forceReload: true
+      }));
+    }
+  };
+}
+function shallowSameQuota(a, b) {
+  return a.minuteRemaining === b.minuteRemaining && a.dayRemaining === b.dayRemaining && a.dayTokensRemaining === b.dayTokensRemaining;
+}
+
+/**
+ * What the auth layer's refusal means for a chat. The code rn-auth gave is kept
+ * as the cause, and it decides the copy: "sign in again" and "you are offline"
+ * are different answers, and both used to arrive as `auth-invalid` (AI-11).
+ */
+function tokenError(status, errorCode) {
+  const cause = errorCode ? {
+    cause: errorCode
+  } : {};
+  switch (errorCode) {
+    case 'session-expired':
+      return new AiError('session-expired', 'the session ended; sign in again', cause);
+    case 'network-unavailable':
+      return new AiError('network', 'no connection to the identity provider', cause);
+    case 'consent-denied':
+      return new AiError('not-entitled', 'access to the AI resource was denied', cause);
+    default:
+      return new AiError('auth-invalid', status === 'denied' ? 'access to the AI resource was refused' : 'could not acquire an access token', cause);
+  }
+}
+//# sourceMappingURL=aiClient.js.map