@mobileai/react-native 0.9.17 → 0.9.19

package/lib/typescript/src/components/AIAgent.d.ts

@@ -8,7 +8,8 @@
  * - Agent runtime context for useAction hooks
  */
 import React from 'react';
-import type { ExecutionResult, ToolDefinition, AgentStep, TokenUsage, KnowledgeBaseConfig, ChatBarTheme, AIProviderName, ScreenMap, ProactiveHelpConfig, InteractionMode } from '../core/types';
+import type { AIConsentConfig } from './AIConsentDialog';
+import type { ExecutionResult, ToolDefinition, AgentStep, TokenUsage, KnowledgeBaseConfig, ChatBarTheme, AIProviderName, ScreenMap, ProactiveHelpConfig, InteractionMode, CustomerSuccessConfig, OnboardingConfig } from '../core/types';
 interface AIAgentProps {
     /**
      * API key (for local prototyping only).
@@ -92,6 +93,8 @@ interface AIAgentProps {
     /**
      * Domain knowledge the AI can query via the query_knowledge tool.
      * Pass a static KnowledgeEntry[] or a { retrieve(query, screen) } function.
+     * If omitted and analyticsKey is configured, the SDK will query the project
+     * knowledge configured in the MobileAI dashboard automatically.
      */
     knowledgeBase?: KnowledgeBaseConfig;
     /** Max token budget for knowledge retrieval (default: 2000) */
@@ -189,7 +192,30 @@ interface AIAgentProps {
      * Default: true (shows once, then remembered via AsyncStorage)
      */
     showDiscoveryTooltip?: boolean;
+    /**
+     * Custom discovery tooltip copy shown above the chat FAB.
+     * Pass a string to override the default onboarding message for this app.
+     */
+    discoveryTooltipMessage?: string;
+    /**
+     * Health score configuration. Enable to automatically track screen
+     * flow, feature adoption, and success milestones for the MobileAI Dashboard.
+     */
+    customerSuccess?: CustomerSuccessConfig;
+    /**
+     * Onboarding journey configuration.
+     * Proactively guides users through structured steps when the app launches.
+     */
+    onboarding?: OnboardingConfig;
+    /**
+     * AI consent configuration (Apple Guideline 5.1.2(i)).
+     * Consent is REQUIRED by default — a consent dialog is shown before
+     * the first AI interaction. The agent will NOT send any data to
+     * the AI provider until the user explicitly consents.
+     * To opt out: `consent={{ required: false }}`.
+     */
+    consent?: AIConsentConfig;
 }
-export declare function AIAgent({ apiKey, proxyUrl, proxyHeaders, voiceProxyUrl, voiceProxyHeaders, provider: providerName, model, navRef, maxSteps, showChatBar, children, onResult, interactiveBlacklist, interactiveWhitelist, onBeforeStep, onAfterStep, onBeforeTask, onAfterTask, transformScreenContent, customTools, instructions, stepDelay, mcpServerUrl, router, pathname, enableVoice, onTokenUsage, debug, knowledgeBase, knowledgeMaxTokens, enableUIControl, accentColor, theme, screenMap, useScreenMap, maxTokenBudget, maxCostUSD, analyticsKey, analyticsProxyUrl, analyticsProxyHeaders, proactiveHelp, userContext, pushToken, pushTokenType, interactionMode, showDiscoveryTooltip: showDiscoveryTooltipProp, }: AIAgentProps): import("react/jsx-runtime").JSX.Element;
+export declare function AIAgent({ apiKey, proxyUrl, proxyHeaders, voiceProxyUrl, voiceProxyHeaders, provider: providerName, model, navRef, maxSteps, showChatBar, children, onResult, interactiveBlacklist, interactiveWhitelist, onBeforeStep, onAfterStep, onBeforeTask, onAfterTask, transformScreenContent, customTools, instructions, stepDelay, mcpServerUrl, router, pathname, enableVoice, onTokenUsage, debug, knowledgeBase, knowledgeMaxTokens, enableUIControl, accentColor, theme, screenMap, useScreenMap, maxTokenBudget, maxCostUSD, analyticsKey, analyticsProxyUrl, analyticsProxyHeaders, proactiveHelp, userContext, pushToken, pushTokenType, interactionMode, showDiscoveryTooltip: showDiscoveryTooltipProp, discoveryTooltipMessage, customerSuccess, onboarding, consent, }: AIAgentProps): import("react/jsx-runtime").JSX.Element;
 export {};
 //# sourceMappingURL=AIAgent.d.ts.map

package/lib/typescript/src/components/AIConsentDialog.d.ts

@@ -0,0 +1,153 @@
+/**
+ * AIConsentDialog — Apple App Store Guideline 5.1.2(i) compliant consent flow.
+ *
+ * Displays a modal before the first AI interaction that:
+ * 1. Names the specific third-party AI provider (e.g., "Google Gemini")
+ * 2. Explains what data is shared (screen content, messages)
+ * 3. Collects explicit user consent via affirmative tap
+ *
+ * Persists consent via AsyncStorage so the dialog is shown once per device.
+ * If AsyncStorage is unavailable, consent is session-scoped (per app launch).
+ *
+ * ## Business rationale
+ * Apple rejects apps that silently send personal data to third-party AI services.
+ * This component ensures compliance WITHOUT the app developer needing to build
+ * their own consent flow — they just set `requireConsent={true}` on <AIAgent>.
+ */
+import type { AIProviderName } from '../core/types';
+declare const DEFAULT_THEME: {
+    backdrop: string;
+    cardBackground: string;
+    cardBorder: string;
+    iconBackground: string;
+    iconColor: string;
+    title: string;
+    body: string;
+    muted: string;
+    sectionBackground: string;
+    sectionBorder: string;
+    bullet: string;
+    badgeBackground: string;
+    badgeText: string;
+    secondaryButtonBackground: string;
+    secondaryButtonText: string;
+    primaryButtonBackground: string;
+    primaryButtonText: string;
+    link: string;
+};
+export interface AIConsentConfig {
+    /**
+     * Whether consent is required before AI interactions.
+     * When true, the agent will NOT send any data to the AI provider
+     * until the user explicitly consents.
+     * @default true
+     */
+    required?: boolean;
+    /**
+     * Whether to persist the consent decision across app restarts.
+     * When false, the user must consent every time they launch the app.
+     * When true, the decision is saved locally (e.g. AsyncStorage) and
+     * the dialog is shown only once per device.
+     * @default false
+     */
+    persist?: boolean;
+    /**
+     * Optional custom title for the consent dialog.
+     * Default: "AI Assistant"
+     */
+    title?: string;
+    /**
+     * Optional custom body text.
+     * Default: Auto-generated based on provider name.
+     */
+    body?: string;
+    /**
+     * Optional custom title for the consent dialog (Arabic).
+     * Default: "مساعد الذكاء الاصطناعي"
+     */
+    titleAr?: string;
+    /**
+     * Optional custom body text (Arabic).
+     * Default: Auto-generated based on provider name.
+     */
+    bodyAr?: string;
+    /**
+     * URL to the app's privacy policy.
+     * If provided, a "Privacy Policy" link is shown in the dialog.
+     */
+    privacyPolicyUrl?: string;
+    /**
+     * Callback fired when user grants consent.
+     */
+    onConsent?: () => void;
+    /**
+     * Callback fired when user declines consent.
+     */
+    onDecline?: () => void;
+    /**
+     * Optional developer-controlled provider label.
+     * Example: "FoodApp AI" or "Secure AI Service".
+     * If omitted, the dialog uses a neutral generic label by default.
+     */
+    providerLabel?: string;
+    /**
+     * Optional provider company/owner name shown in the description.
+     */
+    providerCompany?: string;
+    /**
+     * Optional URL to provider terms or documentation.
+     */
+    providerUrl?: string;
+    /**
+     * Show or hide the small provider badge.
+     * Default: false
+     */
+    showProviderBadge?: boolean;
+    /**
+     * Optional override for the provider badge text.
+     */
+    providerBadgeText?: string;
+    /**
+     * Optional softer explanation shown above the shared-data list.
+     */
+    summary?: string;
+    /**
+     * Optional calmer explanation shown above the shared-data list (Arabic).
+     */
+    summaryAr?: string;
+    /**
+     * Optional custom list of shared-data lines.
+     */
+    sharedDataItems?: string[];
+    /**
+     * Optional custom list of shared-data lines (Arabic).
+     */
+    sharedDataItemsAr?: string[];
+    /**
+     * Theme colors for the consent dialog.
+     */
+    theme?: Partial<typeof DEFAULT_THEME>;
+}
+interface AIConsentDialogProps {
+    visible: boolean;
+    provider: AIProviderName;
+    config: AIConsentConfig;
+    onConsent: () => void;
+    onDecline: () => void;
+    language?: 'en' | 'ar';
+}
+export declare function AIConsentDialog({ visible, provider, config, onConsent, onDecline, language, }: AIConsentDialogProps): import("react/jsx-runtime").JSX.Element | null;
+/**
+ * Manages consent state persistence via AsyncStorage.
+ * Falls back to session-scoped state if AsyncStorage is unavailable.
+ *
+ * @returns [hasConsented, grantConsent, revokeConsent, isLoading]
+ */
+export declare function useAIConsent(persist?: boolean): [
+    hasConsented: boolean,
+    grantConsent: () => Promise<void>,
+    revokeConsent: () => Promise<void>,
+    isLoading: boolean
+];
+export {};
+//# sourceMappingURL=AIConsentDialog.d.ts.map

package/lib/typescript/src/components/AgentChatBar.d.ts

@@ -3,11 +3,12 @@
  * Supports two modes: Text and Voice.
  * Does not block underlying UI natively.
  */
-import type { ExecutionResult, AgentMode, ChatBarTheme, AIMessage } from '../core/types';
+import type { ExecutionResult, AgentMode, ChatBarTheme, AIMessage, ConversationSummary } from '../core/types';
 import type { SupportTicket } from '../support/types';
 interface AgentChatBarProps {
     onSend: (message: string) => void;
     isThinking: boolean;
+    statusText?: string;
     lastResult: ExecutionResult | null;
     language: 'en' | 'ar';
     onDismiss?: () => void;
@@ -52,9 +53,21 @@ interface AgentChatBarProps {
     totalUnread?: number;
     /** Show first-use discovery tooltip above FAB */
     showDiscoveryTooltip?: boolean;
+    /** Custom discovery tooltip copy */
+    discoveryTooltipMessage?: string;
     /** Called when discovery tooltip is dismissed */
     onTooltipDismiss?: () => void;
+    /** Past conversation sessions fetched from backend */
+    conversations?: ConversationSummary[];
+    /** True while history is loading from backend */
+    isLoadingHistory?: boolean;
+    /** Called when user taps a past conversation */
+    onConversationSelect?: (conversationId: string) => void;
+    /** Called when user starts a new conversation */
+    onNewConversation?: () => void;
+    pendingApprovalQuestion?: string | null;
+    onPendingApprovalAction?: (action: 'approve' | 'reject') => void;
 }
-export declare function AgentChatBar({ onSend, isThinking, lastResult, language, onDismiss, availableModes, mode, onModeChange, onMicToggle, onSpeakerToggle, isMicActive, isSpeakerMuted, isAISpeaking, isVoiceConnected, onStopSession, theme, tickets, selectedTicketId, onTicketSelect, autoExpandTrigger, lastUserMessage, unreadCounts, totalUnread, showDiscoveryTooltip, onTooltipDismiss, }: AgentChatBarProps): import("react/jsx-runtime").JSX.Element;
+export declare function AgentChatBar({ onSend, isThinking, statusText, lastResult, language, availableModes, mode, onModeChange, onMicToggle, onSpeakerToggle, isMicActive, isSpeakerMuted, isAISpeaking, isVoiceConnected, onStopSession, theme, tickets, selectedTicketId, onTicketSelect, autoExpandTrigger, unreadCounts, totalUnread, showDiscoveryTooltip, discoveryTooltipMessage, onTooltipDismiss, chatMessages, conversations, isLoadingHistory, onConversationSelect, onNewConversation, pendingApprovalQuestion, onPendingApprovalAction, }: AgentChatBarProps): import("react/jsx-runtime").JSX.Element;
 export {};
 //# sourceMappingURL=AgentChatBar.d.ts.map

package/lib/typescript/src/components/DiscoveryTooltip.d.ts

@@ -9,7 +9,9 @@ interface DiscoveryTooltipProps {
     language: 'en' | 'ar';
     primaryColor?: string;
     onDismiss: () => void;
+    side?: 'left' | 'right';
+    message?: string;
 }
-export declare function DiscoveryTooltip({ language, primaryColor, onDismiss, }: DiscoveryTooltipProps): import("react/jsx-runtime").JSX.Element;
+export declare function DiscoveryTooltip({ language, primaryColor, onDismiss, side, message, }: DiscoveryTooltipProps): import("react/jsx-runtime").JSX.Element;
 export {};
 //# sourceMappingURL=DiscoveryTooltip.d.ts.map

package/lib/typescript/src/components/FloatingOverlayWrapper.d.ts

@@ -0,0 +1,51 @@
+/**
+ * FloatingOverlayWrapper — Cross-platform elevated overlay.
+ *
+ * Platform strategy (in priority order):
+ *
+ * iOS:
+ *   1. `FullWindowOverlay` from react-native-screens (optional peer dep).
+ *      Creates a separate UIWindow at UIWindow.Level.alert+1.
+ *      Renders ABOVE all native Modals, system alerts, and navigation chrome.
+ *   2. Falls back to plain View if react-native-screens is not installed.
+ *
+ * Android (both Old and New Architecture):
+ *   1. Native `MobileAIFloatingOverlay` ViewManager (bundled in this library).
+ *      Creates a Dialog window with TYPE_APPLICATION_PANEL (z=1000),
+ *      above normal app Dialog windows (TYPE_APPLICATION, z=2).
+ *      No SYSTEM_ALERT_WINDOW permission needed — scoped to app's own window.
+ *   2. Falls back to plain View if the app hasn't been rebuilt after install
+ *      (graceful degradation with DEV warning).
+ *
+ * Usage:
+ *   <FloatingOverlayWrapper fallbackStyle={styles.floatingLayer}>
+ *     <View pointerEvents="box-none" style={StyleSheet.absoluteFill}>
+ *       {chatBar}
+ *       {consentDialog} ← must be INSIDE the wrapper, AFTER the chat bar in JSX
+ *     </View>
+ *   </FloatingOverlayWrapper>
+ *
+ * Note: FullWindowOverlay on iOS does NOT officially accept style props in its TS definition,
+ * but passing StyleSheet.absoluteFill is often necessary to prevent dimensions collapsing conditionally.
+ */
+/**
+ * True when a native elevated overlay is available on the current platform.
+ * Used by AIConsentDialog to decide whether to render as View vs Modal.
+ *
+ * iOS + react-native-screens installed → true
+ * Android + native rebuild done        → true
+ * Everything else (fallback)           → false
+ */
+export declare const isNativeOverlayActive: boolean;
+interface FloatingOverlayWrapperProps {
+    children: React.ReactNode;
+    /**
+     * Style applied to the View wrapper when no native overlay is available.
+     * Ignored on iOS (FullWindowOverlay creates its own UIWindow) and
+     * Android (native module creates its own Dialog window).
+     */
+    fallbackStyle?: any;
+}
+export declare function FloatingOverlayWrapper({ children, fallbackStyle, }: FloatingOverlayWrapperProps): React.ReactElement;
+export {};
+//# sourceMappingURL=FloatingOverlayWrapper.d.ts.map

package/lib/typescript/src/components/Icons.d.ts

@@ -40,4 +40,12 @@ export declare function CloseIcon({ size, color }: {
 export declare function AIBadge({ size }: {
     size?: number;
 }): import("react/jsx-runtime").JSX.Element;
+export declare function HistoryIcon({ size, color }: {
+    size?: number;
+    color?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function NewChatIcon({ size, color }: {
+    size?: number;
+    color?: string;
+}): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=Icons.d.ts.map

package/lib/typescript/src/config/endpoints.d.ts

@@ -9,10 +9,12 @@
  */
 export declare const ENDPOINTS: {
     /** Telemetry event ingest — receives batched SDK events */
-    readonly telemetryIngest: "http://localhost:3001/api/v1/events";
+    readonly telemetryIngest: `${string}/api/v1/events`;
     /** Feature flag sync — fetches remote flags for this analyticsKey */
-    readonly featureFlags: "http://localhost:3001/api/v1/flags";
+    readonly featureFlags: `${string}/api/v1/flags`;
     /** Live agent escalation (support handoff) */
-    readonly escalation: "http://localhost:3001";
+    readonly escalation: string;
+    /** AI conversation history — save and retrieve per-user AI chat sessions */
+    readonly conversations: `${string}/api/v1/conversations`;
 };
 //# sourceMappingURL=endpoints.d.ts.map

package/lib/typescript/src/core/AgentRuntime.d.ts

@@ -22,10 +22,13 @@ export declare class AgentRuntime {
     private knowledgeService;
     private uiControlOverride?;
     private lastDehydratedRoot;
+    private currentTraceId;
     private originalErrorHandler;
     private lastSuppressedError;
     private graceTimer;
     private originalReportErrorsAsExceptions;
+    private appActionApproved;
+    private static readonly APP_ACTION_TOOLS;
     getConfig(): AgentConfig;
     constructor(provider: AIProvider, config: AgentConfig, rootRef: any, navRef: any);
     private registerBuiltInTools;
@@ -116,6 +119,7 @@ export declare class AgentRuntime {
      * Returns error string if validation fails, null if valid.
      */
     private validateToolArgs;
+    private emitTrace;
     /** Write tools that can mutate state — only these are checked for aiConfirm */
     private static readonly WRITE_TOOLS;
     /**

package/lib/typescript/src/core/FiberAdapter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * FiberAdapter — Defense in depth for React internals.
+ *
+ * Centralizes all direct access to React Fiber internal properties.
+ * If React renames an internal property (e.g., in React 19/20), we only
+ * need to update it here instead of auditing the entire codebase.
+ *
+ * These are intentionally simple getter functions, not a complex class abstraction,
+ * to ensure maximum performance during tree walk.
+ */
+export declare function getChild(node: any): any | null;
+export declare function getSibling(node: any): any | null;
+export declare function getParent(node: any): any | null;
+export declare function getProps(node: any): Record<string, any>;
+export declare function getStateNode(node: any): any | null;
+export declare function getType(node: any): any | null;
+export declare function getDisplayName(node: any): string | null;
+/**
+ * Common heuristic to find the Fiber node attached to a native view.
+ *
+ * Old Architecture (Bridge): __reactFiber$<hash> or __reactInternalInstance$<hash>
+ * New Architecture (Fabric): __internalInstanceHandle (ReactNativeElement)
+ */
+export declare function getFiberFromNativeNode(nativeNode: any): any | null;
+//# sourceMappingURL=FiberAdapter.d.ts.map

package/lib/typescript/src/core/FiberTreeWalker.d.ts

@@ -14,6 +14,8 @@ export interface WalkConfig {
     interactiveWhitelist?: React.RefObject<any>[];
     /** Optional screen name to scope interactives to the active screen */
     screenName?: string;
+    /** Whether to inject intercepted native UI elements */
+    interceptNativeAlerts?: boolean;
 }
 /**
  * Check if a node has ANY event handler prop (on* function).

package/lib/typescript/src/core/IdleDetector.d.ts

@@ -11,6 +11,13 @@ export interface IdleDetectorConfig {
     onReset: () => void;
     /** Dynamic context suggestion generator based on current screen */
     generateSuggestion?: () => string;
+    /** Configured behavior triggers */
+    behaviorTriggers?: Array<{
+        screen: string;
+        type: string;
+        message?: string;
+        delayMs?: number;
+    }>;
 }
 export declare class IdleDetector {
     private pulseTimer;
@@ -21,6 +28,10 @@ export declare class IdleDetector {
     reset(): void;
     dismiss(): void;
     destroy(): void;
+    /**
+     * Instantly trigger proactive help if the behavior matches a configured trigger.
+     */
+    triggerBehavior(type: string, currentScreen: string): void;
     private resetTimers;
     private clearTimers;
 }

package/lib/typescript/src/core/NativeAlertInterceptor.d.ts

@@ -0,0 +1,55 @@
+/**
+ * NativeAlertInterceptor — Gray-box interception for React Native Alert dialogs.
+ *
+ * Pattern: same approach used by Jest/RNTL (jest.spyOn(Alert, 'alert')) and
+ * inspired by Detox's gray-box native dialog detection.
+ *
+ * How it works:
+ * 1. install()  — patches Alert.alert / Alert.prompt at agent execution start
+ * 2. The patched function STILL calls the original (so the user sees the native alert)
+ *    AND captures the metadata (title, message, buttons) into a registry.
+ * 3. FiberTreeWalker reads hasActiveAlert() / getActiveAlert() and injects
+ *    virtual elements into the dehydrated screen so the LLM can see them.
+ * 4. tapTool routes virtual alert element taps to dismissAlert().
+ * 5. uninstall() — restores originals at execution end (in finally block).
+ *
+ * Safety:
+ * - Patch is ONLY active while the agent is running.
+ * - Original Alert is always restored — even on unhandled errors.
+ * - Active alert auto-clears after ALERT_AUTO_CLEAR_MS to prevent stale state.
+ */
+export interface AlertButton {
+    text: string;
+    style?: 'default' | 'cancel' | 'destructive';
+    /** Original onPress callback from the app */
+    onPress?: () => void;
+}
+export interface ActiveAlert {
+    title: string;
+    message: string;
+    buttons: AlertButton[];
+    /** Timestamp when the alert appeared */
+    capturedAt: number;
+}
+/**
+ * Install the Alert interceptor.
+ * Patches Alert.alert and Alert.prompt — stores originals for restoration.
+ * Safe to call multiple times (idempotent).
+ */
+export declare function installAlertInterceptor(): void;
+/**
+ * Uninstall the Alert interceptor — restores original Alert methods.
+ * Called in the agent's finally block after execution ends.
+ */
+export declare function uninstallAlertInterceptor(): void;
+/** Returns the currently active alert metadata, or null if no alert is showing. */
+export declare function getActiveAlert(): ActiveAlert | null;
+/** Returns true if a native alert is currently intercepted and active. */
+export declare function hasActiveAlert(): boolean;
+/**
+ * Dismiss the active alert by calling the button's onPress callback.
+ * @param buttonIndex - 0-based index of the button to tap
+ * @returns true if successfully dismissed, false if no alert or invalid index
+ */
+export declare function dismissAlert(buttonIndex: number): boolean;
+//# sourceMappingURL=NativeAlertInterceptor.d.ts.map

package/lib/typescript/src/core/types.d.ts

@@ -40,6 +40,15 @@ export interface InteractiveElement {
      * Set automatically by the FiberTreeWalker when the element has aiConfirm={true} prop.
      */
     requiresConfirmation?: boolean;
+    /**
+     * If set, this is a virtual element injected by NativeAlertInterceptor.
+     * Not backed by a real Fiber node — tapTool routes it to the interceptor instead.
+     */
+    virtual?: {
+        kind: 'alert_button';
+        /** 0-based index of the button in the active alert */
+        alertButtonIndex: number;
+    };
 }
 export interface DehydratedScreen {
     /** Current screen name (from navigation state) */
@@ -54,6 +63,7 @@ export interface DehydratedScreen {
 export interface ScreenMapEntry {
     title?: string;
     description: string;
+    navigatesTo?: string[];
 }
 export interface ScreenMap {
     generatedAt: string;
@@ -70,6 +80,18 @@ export interface AgentStep {
         output: string;
     };
 }
+export interface AgentTraceEvent {
+    traceId: string;
+    stage: string;
+    timestamp?: string;
+    stepIndex?: number;
+    screenName?: string;
+    data?: Record<string, unknown>;
+}
+export interface AskUserRequest {
+    question: string;
+    kind?: 'freeform' | 'approval';
+}
 export interface AgentConfig {
     /**
      * Which LLM provider to use for text mode.
@@ -180,6 +202,8 @@ export interface AgentConfig {
     /**
      * Called after each step with token usage data.
      * Use to track cost, enforce budgets, or display usage to the user.
+     * NOTE: Estimated costs are raw provider rates. They do not include the
+     * dashboard's hosted proxy tier multiplier.
      */
     onTokenUsage?: (usage: TokenUsage) => void;
     /**
@@ -188,7 +212,7 @@ export interface AgentConfig {
      * If not set, ask_user tool will break the loop (legacy behavior).
      * @example onAskUser: (q) => new Promise(resolve => showPrompt(q, resolve))
      */
-    onAskUser?: (question: string) => Promise<string>;
+    onAskUser?: (request: AskUserRequest | string) => Promise<string>;
     /**
      * Called immediately before and after each agent tool execution.
      * Used by AIAgent to toggle isAgentActing on TelemetryService so that
@@ -196,6 +220,11 @@ export interface AgentConfig {
      * @param active - true = agent is acting, false = agent finished acting
      */
     onToolExecute?: (active: boolean) => void;
+    /**
+     * Called whenever the runtime emits a detailed audit trace event.
+     * Intended for backend persistence of high-signal execution trails.
+     */
+    onTrace?: (event: AgentTraceEvent) => void;
     /**
      * Expo Router instance (from useRouter()).
      * When provided, the navigate tool uses router.push('/path') instead of navRef.navigate().
@@ -227,6 +256,8 @@ export interface AgentConfig {
      * Maximum estimated cost (USD) allowed per task.
      * The agent loop auto-stops when this budget is exceeded, returning partial results.
      * Cost is estimated based on the provider's pricing (see provider source for rates).
+     * NOTE: This represents raw provider cost (Gemini's base pricing).
+     * It does NOT include the MobileAI dashboard tier-based markup multiplier.
      */
     maxCostUSD?: number;
     /**
@@ -235,6 +266,15 @@ export interface AgentConfig {
      * from external AI agents (like OpenClaw, Claude Desktop, etc).
      */
     mcpServerUrl?: string;
+    /**
+     * When true, the agent monkey-patches Alert.alert and Alert.prompt during execution
+     * to capture native dialog metadata and inject virtual elements into the Fiber tree.
+     * This lets the agent see and tap alert buttons that are normally invisible.
+     *
+     * Default: false (opt-in — only enable if your app uses Alert dialogs the agent needs
+     * to interact with)
+     */
+    interceptNativeAlerts?: boolean;
 }
 export interface ExecutionResult {
     success: boolean;
@@ -308,6 +348,28 @@ export interface AIMessage {
     timestamp: number;
     /** Attached execution result (assistant messages only) */
     result?: ExecutionResult;
+    /** Optional UI hint for rendering assistant prompts */
+    promptKind?: 'approval';
+}
+/**
+ * A past conversation session summary returned by the history list endpoint.
+ * Used to populate the history panel in AgentChatBar.
+ */
+export interface ConversationSummary {
+    /** Unique conversation ID (backend cuid) */
+    id: string;
+    /** Auto-generated title from the first user message */
+    title: string;
+    /** Preview text — last message content, truncated */
+    preview: string;
+    /** Role of the last message ('user' | 'assistant') */
+    previewRole: string;
+    /** Total number of messages in the conversation */
+    messageCount: number;
+    /** Unix ms — when the conversation was created */
+    createdAt: number;
+    /** Unix ms — when it was last updated */
+    updatedAt: number;
 }
 /** Color customization for the floating chat bar / popup. */
 export interface ChatBarTheme {
@@ -406,5 +468,48 @@ export interface ProactiveHelpConfig {
     dismissForSession?: boolean;
     /** Dynamic context suggestion generator based on current screen */
     generateSuggestion?: (screenName: string) => string;
+    /**
+     * Behavior-based triggers to detect user struggle (e.g., rage tapping) and show help instantly.
+     */
+    behaviorTriggers?: Array<{
+        /** Exact screen name or '*' for all screens */
+        screen: string;
+        /** Type of struggle behavior to detect */
+        type: 'rage_tap' | 'error_screen' | 'repeated_navigation';
+        /** Custom badge message when triggered */
+        message?: string;
+        /** Delay before showing badge once triggered (ms) */
+        delayMs?: number;
+    }>;
+}
+export interface CustomerSuccessConfig {
+    /** Enable background collection of health and adoption signals */
+    enabled: boolean;
+    /** Key features to track adoption for */
+    keyFeatures?: string[];
+    /** Milestones that indicate the user is "succeeding" */
+    successMilestones?: Array<{
+        name: string;
+        /** Screen or action that indicates this milestone */
+        screen?: string;
+        action?: string;
+    }>;
+}
+export interface OnboardingConfig {
+    /** Automatically guide the user through these steps */
+    enabled: boolean;
+    /** Steps in the onboarding journey */
+    steps: Array<{
+        screen: string;
+        message: string;
+        /** Element index to highlight via guide tool (optional) */
+        highlightIndex?: number;
+        /** Auto-complete action if user agrees (optional) */
+        action?: string;
+    }>;
+    /** Only show on the very first time the app is launched. Default: true */
+    firstLaunchOnly?: boolean;
+    /** Callback fired when the final step is completed */
+    onComplete?: () => void;
 }
 //# sourceMappingURL=types.d.ts.map