@appilots/sdk 0.4.1 → 0.6.0

package/dist/{chunk-L2A4EZ6V.mjs → chunk-KUFWRJC4.mjs}

@@ -1,4 +1,4 @@
-import { getFiberRoot, getCurrentScreen, getActiveRouteNames, deriveInteractionElements, attachElementIdsToChoiceGroups, elementRegistry, appilotsDebugWarn, getDefaultRegistry, useAppilotsContext, ChatSessionMachine, getCurrentScreenSignature, ActionQueueMachine, getScreenMetadata, setCurrentScreen, useResolvedRegistry, listRegistry, componentRegistry, probeLoadingState, isListItemPressTarget, waitForLoadingSettle, appilotsDebugLog, waitForScreenSettle, screenDepartedBaseline, routesBelongToSameFeature, actionPressTargetId, getNavigationStateSnapshot, getNavigationRef, isOptionalStepAutomationFailure, OPTIONAL_STEP_AUTOMATION_HINT, normalize3, matchScore, idLooselyMatches, parseStableElementId, getAllScreens, snapshotShowsOpenCreateForm, looksDestructiveActionLabel, isGenericSelectValue } from './chunk-4GUPZDWT.mjs';
+import { getFiberRoot, recordIntrospectionFailure, getCurrentScreen, getActiveRouteNames, deriveInteractionElements, attachElementIdsToChoiceGroups, elementRegistry, appilotsDebugWarn, getDefaultRegistry, useAppilotsContext, ChatSessionMachine, getCurrentScreenSignature, ActionQueueMachine, getScreenMetadata, setCurrentScreen, useResolvedRegistry, listRegistry, componentRegistry, probeLoadingState, isListItemPressTarget, waitForLoadingSettle, appilotsDebugLog, waitForScreenSettle, screenDepartedBaseline, routesBelongToSameFeature, actionPressTargetId, getNavigationStateSnapshot, getNavigationRef, isOptionalStepAutomationFailure, OPTIONAL_STEP_AUTOMATION_HINT, normalize3, matchScore, idLooselyMatches, parseStableElementId, getAllScreens, snapshotShowsOpenCreateForm, looksDestructiveActionLabel, isGenericSelectValue } from './chunk-R4D34FEW.mjs';
 import { useMemo, useRef, useSyncExternalStore, useEffect, useCallback, useState } from 'react';
 import { Alert } from 'react-native';
 
@@ -748,6 +748,7 @@ function captureSnapshot() {
     console.warn(
       "[Appilots] captureSnapshot: fiber root not captured yet. Ensure <AppilotsProvider> has rendered before calling this."
     );
+    recordIntrospectionFailure("never-mounted", null);
     return {
       route: getCurrentScreen(),
       texts: [],

package/dist/{chunk-ZWPABTLA.js → chunk-KYFAXT6V.js}

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkJ75B2HWG_js = require('./chunk-J75B2HWG.js');
+var chunkDZ7QRFHD_js = require('./chunk-DZ7QRFHD.js');
 var React = require('react');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -15,11 +15,11 @@ function getActiveRouteName(state) {
   return route.name;
 }
 function AppilotsNavigationContainer({ children }) {
-  const { emit } = chunkJ75B2HWG_js.useAppilotsContext();
+  const { emit } = chunkDZ7QRFHD_js.useAppilotsContext();
   const internalRef = React.useRef(null);
   const handleRef = React.useCallback((instance) => {
     internalRef.current = instance;
-    chunkJ75B2HWG_js.setNavigationRef(instance);
+    chunkDZ7QRFHD_js.setNavigationRef(instance);
     const childRef = children.ref;
     if (typeof childRef === "function") childRef(instance);
     else if (childRef && typeof childRef === "object") childRef.current = instance;
@@ -32,7 +32,7 @@ function AppilotsNavigationContainer({ children }) {
       const routeName = getActiveRouteName(state);
       if (routeName) {
         console.log(`[Appilots] Screen changed \u2192 "${routeName}"`);
-        chunkJ75B2HWG_js.setCurrentScreen(routeName);
+        chunkDZ7QRFHD_js.setCurrentScreen(routeName);
         emit({
           type: "navigation:change",
           timestamp: Date.now(),
@@ -48,7 +48,7 @@ function AppilotsNavigationContainer({ children }) {
       const route = internalRef.current?.getCurrentRoute?.();
       if (route?.name) {
         console.log(`[Appilots] Initial screen \u2192 "${route.name}"`);
-        chunkJ75B2HWG_js.setCurrentScreen(route.name);
+        chunkDZ7QRFHD_js.setCurrentScreen(route.name);
         emit({
           type: "navigation:change",
           timestamp: Date.now(),

package/dist/{chunk-4GUPZDWT.mjs → chunk-R4D34FEW.mjs}

@@ -36,6 +36,21 @@ var StreamAbortError = class extends Error {
     this.partialContent = partialContent;
   }
 };
+var RateLimitedError = class extends Error {
+  retryAfterSeconds;
+  constructor(message, retryAfterSeconds) {
+    super(message);
+    this.name = "RateLimitedError";
+    this.retryAfterSeconds = retryAfterSeconds;
+  }
+};
+function parseRetryAfter(...candidates) {
+  for (const candidate of candidates) {
+    const seconds = Number(candidate);
+    if (Number.isFinite(seconds) && seconds > 0) return Math.ceil(seconds);
+  }
+  return 60;
+}
 var CONTINUATION_TIMEOUT_MS = 15e4;
 var AppilotsClient = class {
   baseUrl;
@@ -44,6 +59,7 @@ var AppilotsClient = class {
   timeout;
   debug;
   mcpVersion;
+  introspectionReporter;
   user;
   sessionId = null;
   /** Guard so identify fires at most once per client instance. */
@@ -54,6 +70,7 @@ var AppilotsClient = class {
     this.timeout = options.timeout ?? 6e4;
     this.debug = options.debug ?? false;
     this.mcpVersion = options.mcpVersion;
+    this.introspectionReporter = options.introspectionReporter;
     this.user = options.user;
     this.headers = {
       "Content-Type": "application/json",
@@ -98,6 +115,15 @@ var AppilotsClient = class {
       }
       if (!response.ok) {
         const errorMsg = json?.error?.message ?? json?.error ?? `HTTP ${response.status}`;
+        if (response.status === 429) {
+          throw new RateLimitedError(
+            errorMsg,
+            parseRetryAfter(
+              json?.error?.retryAfterSeconds,
+              response.headers?.get?.("retry-after")
+            )
+          );
+        }
         throw new Error(errorMsg);
       }
       return json.data ?? json;
@@ -156,6 +182,21 @@ var AppilotsClient = class {
   getSessionId() {
     return this.sessionId;
   }
+  /**
+   * Wire fragment for introspection health. Empty on the happy path —
+   * a working client sends nothing, so the field costs a byte only
+   * when something is actually wrong. Never throws: a broken reporter
+   * must not take the message down with it.
+   */
+  introspectionFragment() {
+    try {
+      const report = this.introspectionReporter?.();
+      if (!report || report.captured !== false) return {};
+      return { introspection: report };
+    } catch {
+      return {};
+    }
+  }
   // ── Messages ──────────────────────────────────────────────────
   async sendMessage(content, context) {
     if (!this.sessionId) {
@@ -169,7 +210,8 @@ var AppilotsClient = class {
         context,
         // Optional MCP version bundled with this app build. Server
         // compares vs the active MCP doc to detect stale uploads.
-        ...this.mcpVersion ? { mcpVersion: this.mcpVersion } : {}
+        ...this.mcpVersion ? { mcpVersion: this.mcpVersion } : {},
+        ...this.introspectionFragment()
       })
     });
     if (data.sessionId) {
@@ -326,11 +368,25 @@ var AppilotsClient = class {
         const contentType = String(xhr.getResponseHeader?.("content-type") ?? "");
         if (xhr.status !== 200 || !contentType.includes("text/event-stream")) {
           let message2 = `HTTP ${xhr.status || 0}`;
+          let retryAfterSeconds;
           try {
             const json = JSON.parse(xhr.responseText || "{}");
             message2 = json?.error?.message ?? json?.error ?? message2;
+            retryAfterSeconds = json?.error?.retryAfterSeconds;
           } catch {
           }
+          if (xhr.status === 429) {
+            fail(
+              new RateLimitedError(
+                message2,
+                parseRetryAfter(
+                  retryAfterSeconds,
+                  xhr.getResponseHeader?.("retry-after")
+                )
+              )
+            );
+            return;
+          }
           fail(
             sawAnyEvent ? new Error(message2) : new StreamTransportError(message2)
           );
@@ -396,7 +452,8 @@ var AppilotsClient = class {
           content,
           sessionId: this.sessionId,
           context,
-          ...this.mcpVersion ? { mcpVersion: this.mcpVersion } : {}
+          ...this.mcpVersion ? { mcpVersion: this.mcpVersion } : {},
+          ...this.introspectionFragment()
         })
       );
     });
@@ -917,25 +974,41 @@ function detectLocaleFromUserTexts(texts) {
 var copy = {
   pt: {
     rateLimit: "O provedor de IA atingiu o limite de uso durante a automa\xE7\xE3o. Aguarde um momento e pe\xE7a para continuar, ou aumente o limite de tokens por minuto.",
+    platformRateLimit: (wait) => `Recebi pedidos demais em pouco tempo e precisei pausar. Tente de novo em ${wait}.`,
     invalidInput: "N\xE3o consegui continuar a automa\xE7\xE3o por um problema interno de sincroniza\xE7\xE3o. Pode tentar de novo ou fazer essa parte manualmente?",
     generic: (detail) => `Perdi o fio da automa\xE7\xE3o (${detail}). Pode continuar manualmente ou me pedir de novo?`
   },
   es: {
     rateLimit: "El proveedor de IA alcanz\xF3 su l\xEDmite de uso durante la automatizaci\xF3n. Espera un momento y p\xEDdeme continuar, o aumenta el l\xEDmite de tokens por minuto.",
+    platformRateLimit: (wait) => `Recib\xED demasiadas solicitudes en poco tiempo y tuve que pausar. Int\xE9ntalo de nuevo en ${wait}.`,
     invalidInput: "No pude continuar la automatizaci\xF3n por un problema interno de sincronizaci\xF3n. \xBFPuedes intentarlo de nuevo o hacer esta parte manualmente?",
     generic: (detail) => `Perd\xED el hilo de la automatizaci\xF3n (${detail}). \xBFPuedes continuar manualmente o ped\xEDrmelo de nuevo?`
   },
   fr: {
     rateLimit: "Le fournisseur d'IA a atteint sa limite d'utilisation pendant l'automatisation. Attendez un instant et demandez-moi de continuer, ou augmentez la limite de tokens par minute.",
+    platformRateLimit: (wait) => `J'ai re\xE7u trop de demandes en peu de temps et j'ai d\xFB faire une pause. R\xE9essayez dans ${wait}.`,
     invalidInput: "Je n'ai pas pu poursuivre l'automatisation \xE0 cause d'un probl\xE8me interne de synchronisation. Pouvez-vous r\xE9essayer ou faire cette \xE9tape manuellement ?",
     generic: (detail) => `J'ai perdu le fil de l'automatisation (${detail}). Vous pouvez continuer manuellement ou me redemander ?`
   },
   en: {
     rateLimit: "Your AI provider hit its rate limit during automation. Wait a moment and ask me to continue, or raise your TPM limit.",
+    platformRateLimit: (wait) => `I got too many requests in a short time and had to pause. Try again in ${wait}.`,
     invalidInput: "I could not continue the automation because of an internal sync issue. You can try again or take over manually.",
     generic: (detail) => `I lost my footing during automation (${detail}). You can take over from here.`
   }
 };
+var waitPhrase = {
+  pt: (s) => s < 90 ? `${Math.ceil(s)} segundos` : `cerca de ${Math.ceil(s / 60)} minutos`,
+  es: (s) => s < 90 ? `${Math.ceil(s)} segundos` : `unos ${Math.ceil(s / 60)} minutos`,
+  fr: (s) => s < 90 ? `${Math.ceil(s)} secondes` : `environ ${Math.ceil(s / 60)} minutes`,
+  en: (s) => s < 90 ? `${Math.ceil(s)} seconds` : `about ${Math.ceil(s / 60)} minutes`
+};
+function buildRateLimitedMessage(retryAfterSeconds, recentUserTexts) {
+  const locale = detectLocaleFromUserTexts(recentUserTexts);
+  const strings = copy[locale] ?? copy.en;
+  const seconds = Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0 ? retryAfterSeconds : 60;
+  return strings.platformRateLimit(waitPhrase[locale](seconds));
+}
 function buildContinuationFailureMessage(rawError, recentUserTexts) {
   const locale = detectLocaleFromUserTexts(recentUserTexts);
   const strings = copy[locale] ?? copy.en;
@@ -1539,7 +1612,7 @@ var ChatSessionMachine = class {
       const raw = err instanceof Error ? err.message : "Continuation failed";
       this.warn("ChatSessionMachine: continuation failed \u2014", raw);
       const recentUserTexts = this.state.messages.filter((m) => m.role === "user").slice(-4).map((m) => m.content);
-      const friendly = buildContinuationFailureMessage(raw, recentUserTexts);
+      const friendly = err instanceof RateLimitedError ? buildRateLimitedMessage(err.retryAfterSeconds, recentUserTexts) : buildContinuationFailureMessage(raw, recentUserTexts);
       this.addAssistantMessage({
         id: `error_${++this.messageIdCounter}`,
         role: "assistant",
@@ -1701,6 +1774,17 @@ var ChatSessionMachine = class {
       removeStreamingPlaceholder();
       const errorMessage = err instanceof Error ? err.message : "Failed to send message";
       this.setState({ error: errorMessage });
+      if (err instanceof RateLimitedError) {
+        const recentUserTexts = this.state.messages.filter((m) => m.role === "user").slice(-4).map((m) => m.content);
+        this.addAssistantMessage({
+          id: `error_${++this.messageIdCounter}`,
+          role: "assistant",
+          content: buildRateLimitedMessage(err.retryAfterSeconds, recentUserTexts),
+          timestamp: Date.now()
+        });
+        this.setState({ isLoading: false, loadingStatusKey: "thinking" });
+        return;
+      }
       this.addAssistantMessage({
         id: `error_${++this.messageIdCounter}`,
         role: "assistant",
@@ -3622,15 +3706,32 @@ function getGlobalConfig() {
 
 // src/introspection/fiberRoot.ts
 var _fiberRoot = null;
+var _diagnostics = {
+  captured: false,
+  failureReason: null,
+  reactVersion: null,
+  failureCount: 0
+};
 function setFiberRoot(fiber) {
   if (_fiberRoot !== fiber) {
     console.log(`[Appilots] Introspection: fiber root captured (type=${typeName(fiber)})`);
     _fiberRoot = fiber;
   }
+  _diagnostics.captured = true;
 }
 function getFiberRoot() {
   return _fiberRoot;
 }
+function recordIntrospectionFailure(reason, reactVersion) {
+  _diagnostics.failureCount += 1;
+  if (_diagnostics.failureReason === null) {
+    _diagnostics.failureReason = reason;
+    _diagnostics.reactVersion = reactVersion;
+  }
+}
+function getIntrospectionDiagnostics() {
+  return { ..._diagnostics };
+}
 function typeName(fiber) {
   const t = fiber?.type ?? fiber?.elementType;
   if (!t) return "unknown";
@@ -3639,15 +3740,16 @@ function typeName(fiber) {
   if (typeof t === "object") return t.displayName ?? t.render?.displayName ?? t.render?.name ?? "forwardRef/memo";
   return String(t);
 }
-
-// src/introspection/AppilotsFiberRoot.tsx
 var FiberSentinel = class extends React2.Component {
   componentDidMount() {
     const fiber = this._reactInternals ?? this._reactInternalFiber ?? null;
     if (!fiber) {
+      const reactVersion = React2.version ?? null;
       console.warn(
-        "[Appilots] FiberSentinel: this._reactInternals is undefined; snapshot capture will fall back to render-time owner. React version may be incompatible."
+        `[Appilots] FiberSentinel: this._reactInternals is undefined; snapshot capture will fall back to render-time owner. React version may be incompatible (react=${reactVersion}).`
       );
+      recordIntrospectionFailure("sentinel-missing-internals", reactVersion);
+      this.props.onUnavailable?.({ reactVersion });
       return;
     }
     let top = fiber;
@@ -3658,13 +3760,16 @@ var FiberSentinel = class extends React2.Component {
     return this.props.children ?? null;
   }
 };
-function AppilotsFiberRoot({ children }) {
+function AppilotsFiberRoot({
+  children,
+  onUnavailable
+}) {
   const Internals = React2.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED_IN_THIS_VERSION_OF_REACT;
   const ownerFiber = Internals?.ReactCurrentOwner?.current;
   if (ownerFiber && !getFiberRoot()) {
     setFiberRoot(ownerFiber);
   }
-  return /* @__PURE__ */ React2.createElement(FiberSentinel, null, children);
+  return /* @__PURE__ */ React2.createElement(FiberSentinel, { onUnavailable }, children);
 }
 
 // src/debug/logger.ts
@@ -3721,6 +3826,16 @@ function AppilotsProvider({ config: configProp, children, client: externalClient
     recordAppilotsEventTrace(event);
     listenersRef.current.forEach((handler) => handler(event));
   }, []);
+  const handleIntrospectionUnavailable = useCallback(
+    ({ reactVersion }) => {
+      emit({
+        type: "sdk:introspection:unavailable",
+        timestamp: Date.now(),
+        data: { reason: "sentinel-missing-internals", reactVersion }
+      });
+    },
+    [emit]
+  );
   const client = useMemo(
     () => externalClient ?? new AppilotsClient({
       projectId: config.projectId,
@@ -3729,7 +3844,9 @@ function AppilotsProvider({ config: configProp, children, client: externalClient
       debug: config.debug,
       appVersion: config.appVersion,
       mcpVersion: config.mcpVersion,
-      user: config.user
+      user: config.user,
+      // Only reports a FAILED reading; the happy path sends nothing.
+      introspectionReporter: getIntrospectionDiagnostics
     }),
     [config.projectId, config.apiBaseUrl, config.apiKey, config.debug, config.appVersion, config.mcpVersion, config.user, externalClient]
   );
@@ -3750,7 +3867,7 @@ function AppilotsProvider({ config: configProp, children, client: externalClient
     () => ({ config, client, subscribe, emit, remotePersonalization }),
     [config, client, subscribe, emit, remotePersonalization]
   );
-  return /* @__PURE__ */ React2.createElement(AppilotsContext.Provider, { value }, /* @__PURE__ */ React2.createElement(AppilotsFiberRoot, null, children));
+  return /* @__PURE__ */ React2.createElement(AppilotsContext.Provider, { value }, /* @__PURE__ */ React2.createElement(AppilotsFiberRoot, { onUnavailable: handleIntrospectionUnavailable }, children));
 }
 function useAppilotsContext() {
   const context = useContext(AppilotsContext);
@@ -4269,4 +4386,4 @@ function clearScreenRegistry() {
   screenRegistry.clear();
 }
 
-export { ActionQueueMachine, AppilotsClient, AppilotsProvider, AppilotsRegistryProvider, ChatSessionMachine, OPTIONAL_STEP_AUTOMATION_HINT, SDK_VERSION, _patchJsxRuntimes, actionPressTargetId, appilotsDebugLog, appilotsDebugWarn, attachElementIdsToChoiceGroups, clearAppilotsDebugTraces, clearScreenRegistry, componentRegistry, createComponentRegistry, createElementRegistry, createListRegistry, defaultDarkTheme, defaultLightTheme, deriveInteractionElements, describeAction, elementRegistry, enableAppilotsAutoTracking, getActiveRouteNames, getAllScreens, getAppilotsDebugTraces, getCurrentScreen, getCurrentScreenSignature, getDefaultRegistry, getFiberRoot, getGlobalConfig, getNavigationRef, getNavigationStateSnapshot, getScreenMetadata, humanizeError, idLooselyMatches, initAppilots, isAutoTrackingEnabled, isGenericSelectValue, isListItemPressTarget, isOptionalStepAutomationFailure, listRegistry, looksDestructiveActionLabel, matchScore, mergeThemeTokens, normalize3, parseStableElementId, probeLoadingState, recordAppilotsDebugTrace, registerScreen, resolveBaseTheme, routesBelongToSameFeature, screenDepartedBaseline, setCurrentScreen, setNavigationRef, snapshotShowsOpenCreateForm, subscribeAppilotsDebugTraces, useAppilotsContext, useResolvedRegistry, waitForLoadingSettle, waitForScreenSettle };
+export { ActionQueueMachine, AppilotsClient, AppilotsProvider, AppilotsRegistryProvider, ChatSessionMachine, OPTIONAL_STEP_AUTOMATION_HINT, RateLimitedError, SDK_VERSION, _patchJsxRuntimes, actionPressTargetId, appilotsDebugLog, appilotsDebugWarn, attachElementIdsToChoiceGroups, clearAppilotsDebugTraces, clearScreenRegistry, componentRegistry, createComponentRegistry, createElementRegistry, createListRegistry, defaultDarkTheme, defaultLightTheme, deriveInteractionElements, describeAction, elementRegistry, enableAppilotsAutoTracking, getActiveRouteNames, getAllScreens, getAppilotsDebugTraces, getCurrentScreen, getCurrentScreenSignature, getDefaultRegistry, getFiberRoot, getGlobalConfig, getIntrospectionDiagnostics, getNavigationRef, getNavigationStateSnapshot, getScreenMetadata, humanizeError, idLooselyMatches, initAppilots, isAutoTrackingEnabled, isGenericSelectValue, isListItemPressTarget, isOptionalStepAutomationFailure, listRegistry, looksDestructiveActionLabel, matchScore, mergeThemeTokens, normalize3, parseStableElementId, probeLoadingState, recordAppilotsDebugTrace, recordIntrospectionFailure, registerScreen, resolveBaseTheme, routesBelongToSameFeature, screenDepartedBaseline, setCurrentScreen, setNavigationRef, snapshotShowsOpenCreateForm, subscribeAppilotsDebugTraces, useAppilotsContext, useResolvedRegistry, waitForLoadingSettle, waitForScreenSettle };

package/dist/hooks/index.d.mts

@@ -1,2 +1,2 @@
-export { H as SuggestedPrompt, O as UseAppilotsFieldOptions, Q as UseAppilotsSliderOptions, V as UseAppilotsTargetOptions, W as UseAppilotsToggleOptions, X as UseSuggestedPromptsOptions, Y as UseSuggestedPromptsReturn, a8 as useAppilots, a9 as useAppilotsActions, aa as useAppilotsChat, ac as useAppilotsField, ad as useAppilotsNavigation, ae as useAppilotsSlider, af as useAppilotsTarget, ag as useAppilotsToggle, ah as useSuggestedPrompts } from '../index-Cb0D6uKH.mjs';
+export { J as SuggestedPrompt, Q as UseAppilotsFieldOptions, V as UseAppilotsSliderOptions, W as UseAppilotsTargetOptions, X as UseAppilotsToggleOptions, Y as UseSuggestedPromptsOptions, Z as UseSuggestedPromptsReturn, a9 as useAppilots, aa as useAppilotsActions, ab as useAppilotsChat, ad as useAppilotsField, ae as useAppilotsNavigation, af as useAppilotsSlider, ag as useAppilotsTarget, ah as useAppilotsToggle, ai as useSuggestedPrompts } from '../index-nI-s3Exg.mjs';
 import 'react';

package/dist/hooks/index.d.ts

@@ -1,2 +1,2 @@
-export { H as SuggestedPrompt, O as UseAppilotsFieldOptions, Q as UseAppilotsSliderOptions, V as UseAppilotsTargetOptions, W as UseAppilotsToggleOptions, X as UseSuggestedPromptsOptions, Y as UseSuggestedPromptsReturn, a8 as useAppilots, a9 as useAppilotsActions, aa as useAppilotsChat, ac as useAppilotsField, ad as useAppilotsNavigation, ae as useAppilotsSlider, af as useAppilotsTarget, ag as useAppilotsToggle, ah as useSuggestedPrompts } from '../index-Cb0D6uKH.js';
+export { J as SuggestedPrompt, Q as UseAppilotsFieldOptions, V as UseAppilotsSliderOptions, W as UseAppilotsTargetOptions, X as UseAppilotsToggleOptions, Y as UseSuggestedPromptsOptions, Z as UseSuggestedPromptsReturn, a9 as useAppilots, aa as useAppilotsActions, ab as useAppilotsChat, ad as useAppilotsField, ae as useAppilotsNavigation, af as useAppilotsSlider, ag as useAppilotsTarget, ah as useAppilotsToggle, ai as useSuggestedPrompts } from '../index-nI-s3Exg.js';
 import 'react';

package/dist/hooks/index.js

@@ -1,43 +1,43 @@
 'use strict';
 
-var chunkYSLDAQV7_js = require('../chunk-YSLDAQV7.js');
-require('../chunk-J75B2HWG.js');
+var chunkHFRIB4YN_js = require('../chunk-HFRIB4YN.js');
+require('../chunk-DZ7QRFHD.js');
 
 
 
 Object.defineProperty(exports, "useAppilots", {
   enumerable: true,
-  get: function () { return chunkYSLDAQV7_js.useAppilots; }
+  get: function () { return chunkHFRIB4YN_js.useAppilots; }
 });
 Object.defineProperty(exports, "useAppilotsActions", {
   enumerable: true,
-  get: function () { return chunkYSLDAQV7_js.useAppilotsActions; }
+  get: function () { return chunkHFRIB4YN_js.useAppilotsActions; }
 });
 Object.defineProperty(exports, "useAppilotsChat", {
   enumerable: true,
-  get: function () { return chunkYSLDAQV7_js.useAppilotsChat; }
+  get: function () { return chunkHFRIB4YN_js.useAppilotsChat; }
 });
 Object.defineProperty(exports, "useAppilotsField", {
   enumerable: true,
-  get: function () { return chunkYSLDAQV7_js.useAppilotsField; }
+  get: function () { return chunkHFRIB4YN_js.useAppilotsField; }
 });
 Object.defineProperty(exports, "useAppilotsNavigation", {
   enumerable: true,
-  get: function () { return chunkYSLDAQV7_js.useAppilotsNavigation; }
+  get: function () { return chunkHFRIB4YN_js.useAppilotsNavigation; }
 });
 Object.defineProperty(exports, "useAppilotsSlider", {
   enumerable: true,
-  get: function () { return chunkYSLDAQV7_js.useAppilotsSlider; }
+  get: function () { return chunkHFRIB4YN_js.useAppilotsSlider; }
 });
 Object.defineProperty(exports, "useAppilotsTarget", {
   enumerable: true,
-  get: function () { return chunkYSLDAQV7_js.useAppilotsTarget; }
+  get: function () { return chunkHFRIB4YN_js.useAppilotsTarget; }
 });
 Object.defineProperty(exports, "useAppilotsToggle", {
   enumerable: true,
-  get: function () { return chunkYSLDAQV7_js.useAppilotsToggle; }
+  get: function () { return chunkHFRIB4YN_js.useAppilotsToggle; }
 });
 Object.defineProperty(exports, "useSuggestedPrompts", {
   enumerable: true,
-  get: function () { return chunkYSLDAQV7_js.useSuggestedPrompts; }
+  get: function () { return chunkHFRIB4YN_js.useSuggestedPrompts; }
 });

package/dist/hooks/index.mjs

@@ -1,2 +1,2 @@
-export { useAppilots, useAppilotsActions, useAppilotsChat, useAppilotsField, useAppilotsNavigation, useAppilotsSlider, useAppilotsTarget, useAppilotsToggle, useSuggestedPrompts } from '../chunk-L2A4EZ6V.mjs';
-import '../chunk-4GUPZDWT.mjs';
+export { useAppilots, useAppilotsActions, useAppilotsChat, useAppilotsField, useAppilotsNavigation, useAppilotsSlider, useAppilotsTarget, useAppilotsToggle, useSuggestedPrompts } from '../chunk-KUFWRJC4.mjs';
+import '../chunk-R4D34FEW.mjs';

package/dist/{index-Cb0D6uKH.d.mts → index-nI-s3Exg.d.mts}

@@ -281,7 +281,7 @@ interface AgentPermissions {
     blockedScreens?: string[];
     allowedActions?: AgentActionType[];
 }
-type AppilotsEventType = 'agent:action:start' | 'agent:action:complete' | 'agent:action:error' | 'agent:message' | 'navigation:change' | 'chat:open' | 'chat:close' | 'chat:escalation:start' | 'chat:escalation:message' | 'chat:escalation:end';
+type AppilotsEventType = 'agent:action:start' | 'agent:action:complete' | 'agent:action:error' | 'agent:message' | 'navigation:change' | 'chat:open' | 'chat:close' | 'chat:escalation:start' | 'chat:escalation:message' | 'chat:escalation:end' | 'sdk:introspection:unavailable';
 interface AppilotsEvent {
     type: AppilotsEventType;
     timestamp: number;
@@ -300,6 +300,17 @@ interface EscalationState {
     operatorName?: string;
 }
 
+/**
+ * Mirrors `introspectionDiagnosticsSchema` on the wire. Declared here
+ * rather than imported so client-core stays free of the server's
+ * validator package.
+ */
+interface IntrospectionDiagnosticsInput {
+    captured: boolean;
+    failureReason?: 'sentinel-missing-internals' | 'never-mounted' | null;
+    reactVersion?: string | null;
+    failureCount?: number;
+}
 interface AppilotsClientOptions {
     projectId: string;
     apiBaseUrl?: string;
@@ -318,6 +329,17 @@ interface AppilotsClientOptions {
      * from your app's package.json so it stays in lockstep with releases.
      */
     mcpVersion?: string;
+    /**
+     * Reports whether the platform binding could read the host app's UI
+     * tree. Called once per message; return `null` (or omit the option)
+     * when there is nothing to report.
+     *
+     * Only a FAILED reading is put on the wire. When introspection is
+     * dead every observation is empty but perfectly well-formed, so the
+     * server cannot tell a blind session from a user looking at empty
+     * screens — this is the only signal that distinguishes them.
+     */
+    introspectionReporter?: () => IntrospectionDiagnosticsInput | null | undefined;
     /**
      * The host app's version (e.g. from package.json or
      * react-native-device-info). Sent as `X-App-Version` on every request
@@ -364,6 +386,30 @@ interface SendMessageStreamOptions {
     /** Abort mid-generation (stop button). Rejects with name='AbortError'. */
     signal?: AbortSignal;
 }
+/**
+ * The server refused the request because this workspace (or this end
+ * user) is going too fast — HTTP 429, `error.code = 'RATE_LIMITED'`.
+ * See `apps/api/src/common/services/relay-rate-limit.ts`.
+ *
+ * A distinct type for two reasons, both of which the plain `Error` the
+ * transport used to throw could not express:
+ *
+ *  - It is a POLICY rejection, not a transport failure. On the streaming
+ *    path that distinction decides whether the caller retries: a stream
+ *    that dies before its first event is safely retried against the
+ *    non-streaming endpoint, but retrying a 429 immediately is exactly
+ *    the behaviour the limit exists to stop, and it earns a second 429.
+ *  - It carries `retryAfterSeconds`, so a caller can say WHEN instead of
+ *    "try again later", and can back off instead of spinning.
+ *
+ * `retryAfterSeconds` is read from the response envelope, falling back
+ * to the `Retry-After` header and then to 60 — a client that waits a
+ * minute is never wrong by much, and never zero.
+ */
+declare class RateLimitedError extends Error {
+    readonly retryAfterSeconds: number;
+    constructor(message: string, retryAfterSeconds: number);
+}
 /** Runtime context sent with every user message. */
 interface SendMessageContext {
     /**
@@ -417,6 +463,7 @@ declare class AppilotsClient {
     private readonly timeout;
     private readonly debug;
     private readonly mcpVersion;
+    private readonly introspectionReporter;
     private readonly user;
     private sessionId;
     /** Guard so identify fires at most once per client instance. */
@@ -434,6 +481,13 @@ declare class AppilotsClient {
     private identifyConfiguredUser;
     destroySession(): Promise<void>;
     getSessionId(): string | null;
+    /**
+     * Wire fragment for introspection health. Empty on the happy path —
+     * a working client sends nothing, so the field costs a byte only
+     * when something is actually wrong. Never throws: a broken reporter
+     * must not take the message down with it.
+     */
+    private introspectionFragment;
     sendMessage(content: string, context?: SendMessageContext): Promise<SendMessageResponse>;
     /**
      * Streaming variant of `sendMessage` — consumes the server's SSE
@@ -1540,4 +1594,4 @@ interface UseSuggestedPromptsReturn {
  */
 declare function useSuggestedPrompts(options: UseSuggestedPromptsOptions): UseSuggestedPromptsReturn;
 
-export { createComponentRegistry as $, type AppilotsThemeTokens as A, type BreadcrumbItem as B, type ComponentRegistry as C, SDK_VERSION as D, type EscalationState as E, type FieldEntry as F, type SliderEntry as G, type SuggestedPrompt as H, type InteractionElementSnapshot as I, type ToggleEntry as J, type ToggleSnapshot as K, type ListItemSnapshot as L, type MessageRole as M, type NavigationPayload as N, type UseAppilotsFieldOptions as O, type PartialThemeTokens as P, type UseAppilotsSliderOptions as Q, type RemotePersonalization as R, type ScreenSnapshot as S, type TargetEntry as T, type UIInteractionPayload as U, type UseAppilotsTargetOptions as V, type UseAppilotsToggleOptions as W, type UseSuggestedPromptsOptions as X, type UseSuggestedPromptsReturn as Y, clearAppilotsDebugTraces as Z, componentRegistry as _, type AppilotsLocale as a, defaultDarkTheme as a0, defaultLightTheme as a1, describeAction as a2, getAppilotsDebugTraces as a3, humanizeError as a4, mergeThemeTokens as a5, recordAppilotsDebugTrace as a6, subscribeAppilotsDebugTraces as a7, useAppilots as a8, useAppilotsActions as a9, useAppilotsChat as aa, useAppilotsContext as ab, useAppilotsField as ac, useAppilotsNavigation as ad, useAppilotsSlider as ae, useAppilotsTarget as af, useAppilotsToggle as ag, useSuggestedPrompts as ah, type AgentAction as b, type AgentPermissions as c, type AppilotsEvent as d, type AgentActionType as e, type AgentMessage as f, AppilotsClient as g, type AppilotsClientOptions as h, type AppilotsConfig as i, type AppilotsEventHandler as j, type AppilotsEventType as k, AppilotsProvider as l, type AppilotsProviderProps as m, type AppilotsTraceEntry as n, type AppilotsUser as o, type BreadcrumbState as p, type ButtonSnapshot as q, type ChatMessage as r, type ChoiceGroupSnapshot as s, type ChoiceOptionSnapshot as t, type ComponentEntry as u, type ComponentKind as v, type FormFillPayload as w, type InputSnapshot as x, type InteractionElementListContext as y, type ListSnapshot as z };
+export { componentRegistry as $, type AppilotsThemeTokens as A, type BreadcrumbItem as B, type ComponentRegistry as C, type RemotePersonalization as D, type EscalationState as E, type FieldEntry as F, SDK_VERSION as G, type SliderEntry as H, type InteractionElementSnapshot as I, type SuggestedPrompt as J, type ToggleEntry as K, type ListItemSnapshot as L, type MessageRole as M, type NavigationPayload as N, type ToggleSnapshot as O, type PartialThemeTokens as P, type UseAppilotsFieldOptions as Q, RateLimitedError as R, type ScreenSnapshot as S, type TargetEntry as T, type UIInteractionPayload as U, type UseAppilotsSliderOptions as V, type UseAppilotsTargetOptions as W, type UseAppilotsToggleOptions as X, type UseSuggestedPromptsOptions as Y, type UseSuggestedPromptsReturn as Z, clearAppilotsDebugTraces as _, type AppilotsLocale as a, createComponentRegistry as a0, defaultDarkTheme as a1, defaultLightTheme as a2, describeAction as a3, getAppilotsDebugTraces as a4, humanizeError as a5, mergeThemeTokens as a6, recordAppilotsDebugTrace as a7, subscribeAppilotsDebugTraces as a8, useAppilots as a9, useAppilotsActions as aa, useAppilotsChat as ab, useAppilotsContext as ac, useAppilotsField as ad, useAppilotsNavigation as ae, useAppilotsSlider as af, useAppilotsTarget as ag, useAppilotsToggle as ah, useSuggestedPrompts as ai, type AgentAction as b, type AgentPermissions as c, type AppilotsEvent as d, type AgentActionType as e, type AgentMessage as f, AppilotsClient as g, type AppilotsClientOptions as h, type AppilotsConfig as i, type AppilotsEventHandler as j, type AppilotsEventType as k, AppilotsProvider as l, type AppilotsProviderProps as m, type AppilotsTraceEntry as n, type AppilotsUser as o, type BreadcrumbState as p, type ButtonSnapshot as q, type ChatMessage as r, type ChoiceGroupSnapshot as s, type ChoiceOptionSnapshot as t, type ComponentEntry as u, type ComponentKind as v, type FormFillPayload as w, type InputSnapshot as x, type InteractionElementListContext as y, type ListSnapshot as z };

package/dist/{index-Cb0D6uKH.d.ts → index-nI-s3Exg.d.ts}

@@ -281,7 +281,7 @@ interface AgentPermissions {
     blockedScreens?: string[];
     allowedActions?: AgentActionType[];
 }
-type AppilotsEventType = 'agent:action:start' | 'agent:action:complete' | 'agent:action:error' | 'agent:message' | 'navigation:change' | 'chat:open' | 'chat:close' | 'chat:escalation:start' | 'chat:escalation:message' | 'chat:escalation:end';
+type AppilotsEventType = 'agent:action:start' | 'agent:action:complete' | 'agent:action:error' | 'agent:message' | 'navigation:change' | 'chat:open' | 'chat:close' | 'chat:escalation:start' | 'chat:escalation:message' | 'chat:escalation:end' | 'sdk:introspection:unavailable';
 interface AppilotsEvent {
     type: AppilotsEventType;
     timestamp: number;
@@ -300,6 +300,17 @@ interface EscalationState {
     operatorName?: string;
 }
 
+/**
+ * Mirrors `introspectionDiagnosticsSchema` on the wire. Declared here
+ * rather than imported so client-core stays free of the server's
+ * validator package.
+ */
+interface IntrospectionDiagnosticsInput {
+    captured: boolean;
+    failureReason?: 'sentinel-missing-internals' | 'never-mounted' | null;
+    reactVersion?: string | null;
+    failureCount?: number;
+}
 interface AppilotsClientOptions {
     projectId: string;
     apiBaseUrl?: string;
@@ -318,6 +329,17 @@ interface AppilotsClientOptions {
      * from your app's package.json so it stays in lockstep with releases.
      */
     mcpVersion?: string;
+    /**
+     * Reports whether the platform binding could read the host app's UI
+     * tree. Called once per message; return `null` (or omit the option)
+     * when there is nothing to report.
+     *
+     * Only a FAILED reading is put on the wire. When introspection is
+     * dead every observation is empty but perfectly well-formed, so the
+     * server cannot tell a blind session from a user looking at empty
+     * screens — this is the only signal that distinguishes them.
+     */
+    introspectionReporter?: () => IntrospectionDiagnosticsInput | null | undefined;
     /**
      * The host app's version (e.g. from package.json or
      * react-native-device-info). Sent as `X-App-Version` on every request
@@ -364,6 +386,30 @@ interface SendMessageStreamOptions {
     /** Abort mid-generation (stop button). Rejects with name='AbortError'. */
     signal?: AbortSignal;
 }
+/**
+ * The server refused the request because this workspace (or this end
+ * user) is going too fast — HTTP 429, `error.code = 'RATE_LIMITED'`.
+ * See `apps/api/src/common/services/relay-rate-limit.ts`.
+ *
+ * A distinct type for two reasons, both of which the plain `Error` the
+ * transport used to throw could not express:
+ *
+ *  - It is a POLICY rejection, not a transport failure. On the streaming
+ *    path that distinction decides whether the caller retries: a stream
+ *    that dies before its first event is safely retried against the
+ *    non-streaming endpoint, but retrying a 429 immediately is exactly
+ *    the behaviour the limit exists to stop, and it earns a second 429.
+ *  - It carries `retryAfterSeconds`, so a caller can say WHEN instead of
+ *    "try again later", and can back off instead of spinning.
+ *
+ * `retryAfterSeconds` is read from the response envelope, falling back
+ * to the `Retry-After` header and then to 60 — a client that waits a
+ * minute is never wrong by much, and never zero.
+ */
+declare class RateLimitedError extends Error {
+    readonly retryAfterSeconds: number;
+    constructor(message: string, retryAfterSeconds: number);
+}
 /** Runtime context sent with every user message. */
 interface SendMessageContext {
     /**
@@ -417,6 +463,7 @@ declare class AppilotsClient {
     private readonly timeout;
     private readonly debug;
     private readonly mcpVersion;
+    private readonly introspectionReporter;
     private readonly user;
     private sessionId;
     /** Guard so identify fires at most once per client instance. */
@@ -434,6 +481,13 @@ declare class AppilotsClient {
     private identifyConfiguredUser;
     destroySession(): Promise<void>;
     getSessionId(): string | null;
+    /**
+     * Wire fragment for introspection health. Empty on the happy path —
+     * a working client sends nothing, so the field costs a byte only
+     * when something is actually wrong. Never throws: a broken reporter
+     * must not take the message down with it.
+     */
+    private introspectionFragment;
     sendMessage(content: string, context?: SendMessageContext): Promise<SendMessageResponse>;
     /**
      * Streaming variant of `sendMessage` — consumes the server's SSE
@@ -1540,4 +1594,4 @@ interface UseSuggestedPromptsReturn {
  */
 declare function useSuggestedPrompts(options: UseSuggestedPromptsOptions): UseSuggestedPromptsReturn;
 
-export { createComponentRegistry as $, type AppilotsThemeTokens as A, type BreadcrumbItem as B, type ComponentRegistry as C, SDK_VERSION as D, type EscalationState as E, type FieldEntry as F, type SliderEntry as G, type SuggestedPrompt as H, type InteractionElementSnapshot as I, type ToggleEntry as J, type ToggleSnapshot as K, type ListItemSnapshot as L, type MessageRole as M, type NavigationPayload as N, type UseAppilotsFieldOptions as O, type PartialThemeTokens as P, type UseAppilotsSliderOptions as Q, type RemotePersonalization as R, type ScreenSnapshot as S, type TargetEntry as T, type UIInteractionPayload as U, type UseAppilotsTargetOptions as V, type UseAppilotsToggleOptions as W, type UseSuggestedPromptsOptions as X, type UseSuggestedPromptsReturn as Y, clearAppilotsDebugTraces as Z, componentRegistry as _, type AppilotsLocale as a, defaultDarkTheme as a0, defaultLightTheme as a1, describeAction as a2, getAppilotsDebugTraces as a3, humanizeError as a4, mergeThemeTokens as a5, recordAppilotsDebugTrace as a6, subscribeAppilotsDebugTraces as a7, useAppilots as a8, useAppilotsActions as a9, useAppilotsChat as aa, useAppilotsContext as ab, useAppilotsField as ac, useAppilotsNavigation as ad, useAppilotsSlider as ae, useAppilotsTarget as af, useAppilotsToggle as ag, useSuggestedPrompts as ah, type AgentAction as b, type AgentPermissions as c, type AppilotsEvent as d, type AgentActionType as e, type AgentMessage as f, AppilotsClient as g, type AppilotsClientOptions as h, type AppilotsConfig as i, type AppilotsEventHandler as j, type AppilotsEventType as k, AppilotsProvider as l, type AppilotsProviderProps as m, type AppilotsTraceEntry as n, type AppilotsUser as o, type BreadcrumbState as p, type ButtonSnapshot as q, type ChatMessage as r, type ChoiceGroupSnapshot as s, type ChoiceOptionSnapshot as t, type ComponentEntry as u, type ComponentKind as v, type FormFillPayload as w, type InputSnapshot as x, type InteractionElementListContext as y, type ListSnapshot as z };
+export { componentRegistry as $, type AppilotsThemeTokens as A, type BreadcrumbItem as B, type ComponentRegistry as C, type RemotePersonalization as D, type EscalationState as E, type FieldEntry as F, SDK_VERSION as G, type SliderEntry as H, type InteractionElementSnapshot as I, type SuggestedPrompt as J, type ToggleEntry as K, type ListItemSnapshot as L, type MessageRole as M, type NavigationPayload as N, type ToggleSnapshot as O, type PartialThemeTokens as P, type UseAppilotsFieldOptions as Q, RateLimitedError as R, type ScreenSnapshot as S, type TargetEntry as T, type UIInteractionPayload as U, type UseAppilotsSliderOptions as V, type UseAppilotsTargetOptions as W, type UseAppilotsToggleOptions as X, type UseSuggestedPromptsOptions as Y, type UseSuggestedPromptsReturn as Z, clearAppilotsDebugTraces as _, type AppilotsLocale as a, createComponentRegistry as a0, defaultDarkTheme as a1, defaultLightTheme as a2, describeAction as a3, getAppilotsDebugTraces as a4, humanizeError as a5, mergeThemeTokens as a6, recordAppilotsDebugTrace as a7, subscribeAppilotsDebugTraces as a8, useAppilots as a9, useAppilotsActions as aa, useAppilotsChat as ab, useAppilotsContext as ac, useAppilotsField as ad, useAppilotsNavigation as ae, useAppilotsSlider as af, useAppilotsTarget as ag, useAppilotsToggle as ah, useSuggestedPrompts as ai, type AgentAction as b, type AgentPermissions as c, type AppilotsEvent as d, type AgentActionType as e, type AgentMessage as f, AppilotsClient as g, type AppilotsClientOptions as h, type AppilotsConfig as i, type AppilotsEventHandler as j, type AppilotsEventType as k, AppilotsProvider as l, type AppilotsProviderProps as m, type AppilotsTraceEntry as n, type AppilotsUser as o, type BreadcrumbState as p, type ButtonSnapshot as q, type ChatMessage as r, type ChoiceGroupSnapshot as s, type ChoiceOptionSnapshot as t, type ComponentEntry as u, type ComponentKind as v, type FormFillPayload as w, type InputSnapshot as x, type InteractionElementListContext as y, type ListSnapshot as z };