@mobileai/react-native 0.9.16 → 0.9.18

package/src/core/types.ts

@@ -1,521 +0,0 @@
-/**
- * Core types for the React Native AI SDK.
- */
-
-// ─── Agent Modes ──────────────────────────────────────────────
-
-export type AgentMode = 'text' | 'voice' | 'human';
-
-/**
- * Controls how the agent handles irreversible actions.
- * 'copilot' (default): AI pauses before final commit actions (place order, delete, submit).
- *   The prompt instructs the AI to ask_user before the final irreversible step.
- *   Elements with aiConfirm={true} also trigger a code-level confirmation gate.
- * 'autopilot': Full autonomy — all actions execute without confirmation.
- */
-export type InteractionMode = 'copilot' | 'autopilot';
-
-// ─── Provider Names ──────────────────────────────────────────
-
-export type AIProviderName = 'gemini' | 'openai';
-
-// ─── Interactive Element (discovered from Fiber tree) ─────────
-
-export type ElementType = 'pressable' | 'text-input' | 'switch' | 'scrollable'
-  | 'slider' | 'picker' | 'date-picker';
-
-export interface InteractiveElement {
-  /** Unique index assigned during tree walk */
-  index: number;
-  /** Element type */
-  type: ElementType;
-  /** Human-readable label (extracted from Text children or accessibilityLabel) */
-  label: string;
-  /** Declarative AI priority explicitly set by the developer */
-  aiPriority?: 'high' | 'low';
-  /** The nearest enclosing AIZone ID (if any) */
-  zoneId?: string;
-  /** Reference to the Fiber node for execution */
-  fiberNode: any;
-  /**
-   * Props snapshot from the fiber node.
-   * Record<string, any> because RN components have diverse props:
-   * - Pressable: onPress, onLongPress
-   * - Slider: onValueChange, onSlidingComplete, minimumValue, maximumValue
-   * - Picker: onValueChange, items, selectedValue
-   * - DatePicker: onChange, onDateChange, mode
-   * - Switch: onValueChange, value
-   */
-  props: Record<string, any>;
-  /**
-   * If true, AI interaction with this element requires user confirmation (copilot safety net).
-   * Set automatically by the FiberTreeWalker when the element has aiConfirm={true} prop.
-   */
-  requiresConfirmation?: boolean;
-}
-
-// ─── Dehydrated Screen State ──────────────────────────────────
-
-export interface DehydratedScreen {
-  /** Current screen name (from navigation state) */
-  screenName: string;
-  /** All available screen names (from routeNames) */
-  availableScreens: string[];
-  /** Indexed interactive elements as text */
-  elementsText: string;
-  /** Raw elements array */
-  elements: InteractiveElement[];
-}
-
-// ─── Screen Map (generated by CLI) ───────────────────────────
-
-export interface ScreenMapEntry {
-  title?: string;
-  description: string;
-}
-
-export interface ScreenMap {
-  generatedAt: string;
-  framework: 'expo-router' | 'react-navigation';
-  screens: Record<string, ScreenMapEntry>;
-  chains?: string[][];
-}
-
-// ─── Agent Types ──────────────────────────────────────────────
-
-export interface AgentStep {
-  stepIndex: number;
-  reflection: AgentReasoning;
-  action: {
-    name: string;
-    input: Record<string, any>;
-    output: string;
-  };
-}
-
-export interface AgentConfig {
-  /**
-   * Which LLM provider to use for text mode.
-   * Default: 'gemini'
-   */
-  provider?: AIProviderName;
-
-  /** 
-   * API key (for prototyping only).
-   * Do not use in production. Use proxyUrl instead.
-   */
-  apiKey?: string;
-
-  /**
-   * The URL of your secure backend proxy (for production).
-   * Routes all Gemini API requests through your server.
-   */
-  proxyUrl?: string;
-
-  /**
-   * Optional headers to send to your proxyUrl (e.g., auth tokens).
-   */
-  proxyHeaders?: Record<string, string>;
-
-  /**
-   * Optional specific URL for Voice Mode (WebSockets).
-   * Useful if you use Serverless for text, but need a dedicated server for voice.
-   */
-  voiceProxyUrl?: string;
-
-  /**
-   * Optional specific headers for voiceProxyUrl.
-   */
-  voiceProxyHeaders?: Record<string, string>;
-
-  model?: string;  
-  
-  /** Maximum steps per task */
-  maxSteps?: number;
-
-  /**
-   * Controls how the agent handles irreversible actions.
-   * 'copilot' (default): AI pauses before final commit actions.
-   * 'autopilot': Full autonomy, no pauses.
-   */
-  interactionMode?: InteractionMode;
-
-  /**
-   * MCP server mode — controls whether external agents can discover and invoke actions.
-   * 'auto' (default): enabled in __DEV__, disabled in production
-   * 'enabled': always on (opt-in for production)
-   * 'disabled': always off
-   */
-  mcpServerMode?: 'auto' | 'enabled' | 'disabled';
-
-  // ─── Element Gating ──
-
-  /**
-   * React refs of elements the AI must NOT interact with.
-   * Refs of elements the AI must NOT interact with.
-   * The Fiber walker skips any node whose ref matches one in this list.
-   */
-  interactiveBlacklist?: React.RefObject<any>[];
-
-  /**
-   * If set, the AI can ONLY interact with these elements.
-   * If set, AI can ONLY interact with these elements.
-   */
-  interactiveWhitelist?: React.RefObject<any>[];
-
-  // ─── Lifecycle Hooks ───────
-
-  /** Called before each agent step. */
-  onBeforeStep?: (stepCount: number) => Promise<void> | void;
-
-  /** Called after each agent step with full history. */
-  onAfterStep?: (history: AgentStep[]) => Promise<void> | void;
-
-  /** Called before task execution starts. */
-  onBeforeTask?: () => Promise<void> | void;
-
-  /** Called after task completes (success or failure). */
-  onAfterTask?: (result: ExecutionResult) => Promise<void> | void;
-
-  // ─── Content Masking ──────────
-
-  /**
-   * Transform dehydrated screen text before sending to LLM.
-   * Use to mask sensitive data (credit cards, PII, etc).
-   * Transform screen content before the LLM sees it (for data masking).
-   */
-  transformScreenContent?: (content: string) => Promise<string> | string;
-
-  // ─── Custom Tools ─────────────────────
-
-  /**
-   * Override or remove built-in tools.
-   * Set tool to `null` to remove it (e.g., `{ navigate: null }`).
-   * Override or remove built-in tools (null = remove).
-   */
-  customTools?: Record<string, ToolDefinition | null>;
-
-  // ─── Instructions ────────────────────
-
-  /** Instructions to guide the agent's behavior. */
-  instructions?: {
-    /** Global system-level instructions, applied to all tasks. */
-    system?: string;
-    /**
-     * Dynamic per-screen instructions callback.
-     * Called before each step to get instructions for the current screen.
-     * Per-screen instructions callback.
-     */
-    getScreenInstructions?: (screenName: string) => string | undefined | null;
-  };
-
-  /**
-   * Enable or disable UI control tools (tap, type, navigate, ask_user, capture_screenshot).
-   * When false, the AI operates as a knowledge-only assistant — it can read the screen
-   * and answer questions via query_knowledge, but cannot interact with UI elements.
-   * Default: true
-   */
-  enableUIControl?: boolean;
-
-  /** Delay between steps in ms. */
-  stepDelay?: number;
-
-  // ─── Screen Map ───────────────────────────────────────────────────────────
-
-  /**
-   * Pre-generated screen map from `npx react-native-ai-agent generate-map`.
-   * Gives the AI knowledge of all screens, their content, and navigation chains.
-   * Without this, the AI only sees the currently rendered screen.
-   */
-  screenMap?: ScreenMap;
-
-  // ─── Status Updates ──────────────────────────────────────────────────────
-
-  /**
-   * Called with a human-readable status string at each step.
-   * Use this to show dynamic loading text (e.g., "Tapping 'Add'...").
-   */
-  onStatusUpdate?: (status: string) => void;
-
-  /**
-   * Called after each step with token usage data.
-   * Use to track cost, enforce budgets, or display usage to the user.
-   */
-  onTokenUsage?: (usage: TokenUsage) => void;
-
-  /**
-   * Callback for when agent needs user input (ask_user tool).
-   * The agent loop blocks until the user responds.
-   * 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>;
-
-  /**
-   * Called immediately before and after each agent tool execution.
-   * Used by AIAgent to toggle isAgentActing on TelemetryService so that
-   * AI-driven taps are not double-counted as user interactions.
-   * @param active - true = agent is acting, false = agent finished acting
-   */
-  onToolExecute?: (active: boolean) => void;
-
-  // ─── Expo Router Support ─────────────────────────────────────────────────
-
-  /**
-   * Expo Router instance (from useRouter()).
-   * When provided, the navigate tool uses router.push('/path') instead of navRef.navigate().
-   */
-  router?: {
-    push: (href: string) => void;
-    replace: (href: string) => void;
-    back: () => void;
-  };
-
-  /**
-   * Current pathname from Expo Router (from usePathname()).
-   * Used to determine the current screen when using Expo Router.
-   */
-  pathname?: string;
-
-  // ─── Knowledge Base ────────────────────────────────────────────────────────
-
-  /**
-   * Domain knowledge the AI can query via the query_knowledge tool.
-   * Pass a static array of KnowledgeEntry[] (SDK handles keyword matching),
-   * or a KnowledgeRetriever with a custom async retrieve() function.
-   */
-  knowledgeBase?: KnowledgeBaseConfig;
-
-  /** Max tokens for knowledge retrieval results (~4 chars per token). Default: 2000 */
-  knowledgeMaxTokens?: number;
-
-  // ─── Budget Guards ──────────────────────────────────────────────────────
-
-  /**
-   * Maximum total tokens (prompt + completion) allowed per task.
-   * The agent loop auto-stops when this budget is exceeded, returning partial results.
-   */
-  maxTokenBudget?: number;
-
-  /**
-   * 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).
-   */
-  maxCostUSD?: number;
-
-  // ─── MCP Bridge Integration ──────────────────────────────────────────────
-
-  /**
-   * Optional URL of the companion Node.js MCP server bridge (e.g. ws://localhost:3101).
-   * If set, the SDK will connect to this server and listen for execution requests
-   * from external AI agents (like OpenClaw, Claude Desktop, etc).
-   */
-  mcpServerUrl?: string;
-}
-
-export interface ExecutionResult {
-  success: boolean;
-  message: string;
-  steps: AgentStep[];
-  /** Accumulated token usage for the entire task */
-  tokenUsage?: TokenUsage;
-}
-
-// ─── Tool Types ───────────────────────────────────────────────
-
-export interface ToolDefinition {
-  name: string;
-  description: string;
-  parameters: Record<string, ToolParam>;
-  execute: (args: Record<string, any>) => Promise<string>;
-}
-
-export interface ToolParam {
-  type: 'string' | 'number' | 'boolean';
-  description: string;
-  required?: boolean;
-  enum?: string[];
-}
-
-// ─── Action (optional useAction hook) ─────────────────────────
-
-export interface ActionParameterDef {
-  /** The primitive type of the parameter. Maps to MCP schemas and native iOS/Android types. */
-  type: 'string' | 'number' | 'boolean';
-  /** A clear description of what the parameter is for (read by the AI). */
-  description: string;
-  /** Whether the AI must provide this parameter. Defaults to true. */
-  required?: boolean;
-  /** If provided, the AI is restricted to these specific string values. */
-  enum?: string[];
-}
-
-export interface ActionDefinition {
-  name: string;
-  description: string;
-  parameters: Record<string, string | ActionParameterDef>;
-  handler: (args: Record<string, any>) => any;
-}
-
-// ─── Knowledge Base ───────────────────────────────────────────
-
-/** A single knowledge entry the AI can retrieve. */
-export interface KnowledgeEntry {
-  /** Unique identifier */
-  id: string;
-  /** Human-readable title (also used for keyword matching) */
-  title: string;
-  /** The knowledge text content */
-  content: string;
-  /** Optional tags for keyword matching (e.g., ['refund', 'policy']) */
-  tags?: string[];
-  /** Optional: only surface this entry on these screens */
-  screens?: string[];
-  /** Priority 0-10 — higher = preferred when multiple match (default: 5) */
-  priority?: number;
-}
-
-/** Async retriever function — consumer brings their own retrieval logic. */
-export interface KnowledgeRetriever {
-  retrieve: (query: string, screenName: string) => Promise<KnowledgeEntry[]>;
-}
-
-/**
- * Knowledge base configuration — accepts either:
- * - A static array of KnowledgeEntry[] (SDK handles keyword matching)
- * - A KnowledgeRetriever object with a custom retrieve() function
- */
-export type KnowledgeBaseConfig = KnowledgeEntry[] | KnowledgeRetriever;
-
-// ─── Chat Messages ───────────────────────────────────────────
-
-/** A single message in the conversation history. */
-export interface AIMessage {
-  /** Unique message ID */
-  id: string;
-  /** Who sent this message */
-  role: 'user' | 'assistant';
-  /** Text content */
-  content: string;
-  /** Unix timestamp (ms) */
-  timestamp: number;
-  /** Attached execution result (assistant messages only) */
-  result?: ExecutionResult;
-}
-
-// ─── Chat Bar Theme ──────────────────────────────────────────
-
-/** Color customization for the floating chat bar / popup. */
-export interface ChatBarTheme {
-  /** Primary accent color — FAB background, send button, active tab indicator.
-   *  Default: '#1a1a2e' */
-  primaryColor?: string;
-  /** Expanded popup background color. Default: 'rgba(26, 26, 46, 0.95)' */
-  backgroundColor?: string;
-  /** Text and icon color. Default: '#ffffff' */
-  textColor?: string;
-  /** User input field background. Default: 'rgba(255, 255, 255, 0.1)' */
-  inputBackgroundColor?: string;
-  /** Success result bubble background. Default: 'rgba(40, 167, 69, 0.2)' */
-  successColor?: string;
-  /** Error result bubble background. Default: 'rgba(220, 53, 69, 0.2)' */
-  errorColor?: string;
-}
-
-// ─── Provider Interface ──────────────────────────────────────
-
-/** Structured reasoning returned per step via the agent_step tool. */
-export interface AgentReasoning {
-  /** Assessment of whether the previous action succeeded or failed. */
-  previousGoalEval: string;
-  /** What to remember for future steps (progress, items found, etc). */
-  memory: string;
-  /** The immediate next goal and why. */
-  plan: string;
-}
-
-// ─── Token Usage ──────────────────────────────────────────────
-
-/** Token usage metrics for cost tracking. */
-export interface TokenUsage {
-  /** Tokens in the input prompt */
-  promptTokens: number;
-  /** Tokens generated by the model */
-  completionTokens: number;
-  /** Total tokens (prompt + completion) */
-  totalTokens: number;
-  /** Estimated cost in USD (based on model pricing) */
-  estimatedCostUSD: number;
-}
-
-/** Result from the AI provider's generateContent call. */
-export interface ProviderResult {
-  /** Extracted action tool call (action_name + params). */
-  toolCalls: Array<{ name: string; args: Record<string, any> }>;
-  /** Structured reasoning from MacroTool (evaluation, memory, next_goal). */
-  reasoning: AgentReasoning;
-  /** Raw text response (if any). */
-  text?: string;
-  /** Token usage for this specific call */
-  tokenUsage?: TokenUsage;
-}
-
-export interface AIProvider {
-  generateContent(
-    systemPrompt: string,
-    userMessage: string,
-    tools: ToolDefinition[],
-    history: AgentStep[],
-    /** Optional base64-encoded JPEG screenshot for vision */
-    screenshot?: string,
-  ): Promise<ProviderResult>;
-}
-
-// ─── AI-Native UI (Pillar B) ───────────────────────────────────────────────────
-
-/**
- * Configuration for an AIZone declarative boundary.
- */
-export interface AIZoneConfig {
-  /** Unique identifier for this zone on the current screen */
-  id: string;
-  /** Whether the AI is allowed to use guide_user() to highlight elements here */
-  allowHighlight?: boolean;
-  /** Whether the AI is allowed to inject tooltip hints here */
-  allowInjectHint?: boolean;
-  /** Whether the AI is allowed to hide children marked with aiPriority="low" */
-  allowSimplify?: boolean;
-  /** Whether the AI is allowed to inject custom cards here */
-  allowInjectCard?: boolean;
-  /** 
-   * Whitelist of React component templates the AI can instantiate.
-   * Required if allowInjectCard is true.
-   * IMPORTANT: The AI receives the displayName of these components 
-   * and can only produce props for them. It cannot generate JSX.
-   */
-  templates?: React.ComponentType<any>[];
-}
-
-/**
- * Internal representation of a registered zone.
- */
-export interface RegisteredZone extends AIZoneConfig {
-  /** React ref to the zone's container View */
-  ref: React.RefObject<any>;
-}
-
-export interface ProactiveHelpConfig {
-  /** Enable proactive help (default: true) */
-  enabled?: boolean;
-  /** Time in minutes before a subtle pulse (default: 2) */
-  pulseAfterMinutes?: number;
-  /** Time in minutes before showing a help badge (default: 4) */
-  badgeAfterMinutes?: number;
-  /** Default text for the badge (default: "Need help with this screen?") */
-  badgeText?: string;
-  /** If true, dismissing the badge disables proactive help for the rest of the session (default: true) */
-  dismissForSession?: boolean;
-  /** Dynamic context suggestion generator based on current screen */
-  generateSuggestion?: (screenName: string) => string;
-}

package/src/hooks/useAction.ts

@@ -1,182 +0,0 @@
-/**
- * useAction — Register non-UI actions for the AI agent.
- * useAI    — Bridge hook to read AIAgent's state (send, isLoading, status).
- *
- * Both hooks consume AgentContext, which is provided by <AIAgent>.
- */
-
-import React, { useEffect, useContext, createContext, useCallback, useRef } from 'react';
-import type { AgentRuntime } from '../core/AgentRuntime';
-import type { ExecutionResult, AIMessage } from '../core/types';
-
-// ─── Context ──────────────────────────────────────────────────
-
-export interface AgentContextValue {
-  runtime: AgentRuntime | null;
-  /** Send a text message to the agent (same as typing in the chat bar). */
-  send: (message: string, options?: { onResult?: (result: ExecutionResult) => void }) => void;
-  /** Whether the agent is currently executing (thinking / tapping / navigating). */
-  isLoading: boolean;
-  /** Live status text — e.g. "Analyzing screen...", "Tapping element 3..." */
-  status: string;
-  /** The result of the last completed execution. */
-  lastResult: ExecutionResult | null;
-  /** The full conversation history for custom chat UIs. */
-  messages: AIMessage[];
-  /** Clear conversation history. */
-  clearMessages: () => void;
-  /** Cancel currently running task. */
-  cancel: () => void;
-}
-
-const DEFAULT_CONTEXT: AgentContextValue = {
-  runtime: null,
-  send: () => {},
-  isLoading: false,
-  status: '',
-  lastResult: null,
-  messages: [],
-  clearMessages: () => {},
-  cancel: () => {},
-};
-
-export const AgentContext = createContext<AgentContextValue>(DEFAULT_CONTEXT);
-
-import { actionRegistry } from '../core/ActionRegistry';
-import type { ActionParameterDef } from '../core/types';
-
-/**
- * Register a non-UI action that the AI agent can call by name.
- *
- * The handler is always kept fresh via an internal ref — no stale closure bugs,
- * even when it captures mutable state like cart contents or form values.
- *
- * The optional `deps` array controls when the action is *re-registered* (i.e. when
- * `name`, `description`, or `parameters` need to change at runtime). You rarely
- * need this — the handler is always up-to-date regardless.
- *
- * @example Basic (handler always fresh — no deps needed)
- * ```tsx
- * const { cart } = useCart();
- * useAction('checkout', 'Place the order', {}, async () => {
- *   if (cart.length === 0) return { success: false, message: 'Cart is empty' };
- *   // cart is always current — no stale closure
- * });
- * ```
- *
- * @example Dynamic description (re-register when item count changes)
- * ```tsx
- * useAction(
- *   'checkout',
- *   `Place the order (${cart.length} items in cart)`,
- *   {},
- *   handler,
- *   [cart.length],   // re-register so the AI sees the updated description
- * );
- * ```
- */
-export function useAction(
-  name: string,
-  description: string,
-  parameters: Record<string, string | ActionParameterDef>,
-  handler: (args: Record<string, any>) => any,
-  deps?: React.DependencyList,
-): void {
-  // Keep a ref to the latest handler so the registered action always calls
-  // the current closure — even without re-registering the action.
-  // This is the canonical React pattern for "always-fresh callbacks"
-  // (used by react-use, ahooks, TanStack Query internally).
-  const handlerRef = useRef(handler);
-  useEffect(() => {
-    handlerRef.current = handler;
-  });
-
-  // Registration effect — only re-runs when name/description/parameters change,
-  // OR when the consumer explicitly passes deps (e.g. for a dynamic description).
-  useEffect(() => {
-    actionRegistry.register({
-      name,
-      description,
-      parameters,
-      // Delegate to the ref — always calls the latest handler.
-      handler: (args) => handlerRef.current(args),
-    });
-
-    return () => {
-      actionRegistry.unregister(name);
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, deps ? [name, description, ...deps] : [name, description]);
-}
-
-
-// ─── useAI ────────────────────────────────────────────────────
-
-/**
- * Bridge hook — reads the parent <AIAgent>'s state.
- *
- * Must be used inside an <AIAgent> tree.
- *
- * ```tsx
- * <AIAgent showChatBar={false} apiKey="..." navRef={navRef}>
- *   <MyApp />
- * </AIAgent>
- *
- * // Inside any screen:
- * const { send, isLoading, status, lastResult } = useAI({ enableUIControl: false }); // knowledge-only for this screen
- * ```
- */
-export function useAI(options?: {
-  /** 
-   * Dynamically override the global `enableUIControl` setting.
-   * Useful to force "knowledge-only" mode for a specific screen without changing root layout props.
-   */
-  enableUIControl?: boolean;
-  /**
-   * Override the global `onResult` callback for tasks triggered from this hook.
-   * Useful for navigating the user back to this specific screen after the AI finishes.
-   */
-  onResult?: (result: ExecutionResult) => void;
-}) {
-  const ctx = useContext(AgentContext);
-
-  useEffect(() => {
-    if (options?.enableUIControl !== undefined && ctx.runtime) {
-      ctx.runtime.setUIControlOverride(options.enableUIControl);
-      
-      // Cleanup: revert to global config when unmounted
-      return () => {
-        ctx.runtime?.setUIControlOverride(undefined);
-      };
-    }
-    return undefined;
-  }, [options?.enableUIControl, ctx.runtime]);
-
-  // Track the latest onResult callback in a ref to keep `send`'s identity perfectly stable.
-  // This prevents infinite render loops if `send` is used as a dependency in child useEffects.
-  const onResultRef = useRef(options?.onResult);
-  useEffect(() => {
-    onResultRef.current = options?.onResult;
-  }, [options?.onResult]);
-
-  const send = useCallback((message: string) => {
-    ctx.send(message, { onResult: onResultRef.current });
-  }, [ctx]);
-
-  return {
-    /** Send a message to the AI agent. */
-    send,
-    /** Whether the agent is currently executing. */
-    isLoading: ctx.isLoading,
-    /** Live status text (e.g. "Navigating to profile..."). */
-    status: ctx.status,
-    /** Result of the last completed execution. */
-    lastResult: ctx.lastResult,
-    /** The full conversation history. */
-    messages: ctx.messages,
-    /** Clear the conversation history. */
-    clearMessages: ctx.clearMessages,
-    /** Cancel the currently running task. The current step will complete before stopping. */
-    cancel: ctx.cancel,
-  };
-}