react-native-agentic-ai 0.0.2 → 0.3.0

package/src/components/AIAgent.tsx

@@ -0,0 +1,262 @@
+/**
+ * AIAgent — Root provider component for the AI agent.
+ *
+ * Wraps the app and provides:
+ * - Fiber tree root ref for element auto-detection
+ * - Navigation ref for auto-navigation
+ * - Floating chat bar for user input
+ * - Agent runtime context for useAction hooks
+ */
+
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { View, StyleSheet } from 'react-native';
+import { AgentRuntime } from '../core/AgentRuntime';
+import { GeminiProvider } from '../providers/GeminiProvider';
+import { AgentContext } from '../hooks/useAction';
+import { AgentChatBar } from './AgentChatBar';
+import { AgentOverlay } from './AgentOverlay';
+import { logger } from '../utils/logger';
+import { MCPBridge } from '../core/MCPBridge';
+import type { AgentConfig, ExecutionResult, ToolDefinition, AgentStep } from '../core/types';
+
+// ─── Context ───────────────────────────────────────────────────
+
+
+// ─── Props ─────────────────────────────────────────────────────
+
+interface AIAgentProps {
+  /** Gemini API key */
+  apiKey: string;
+  /** Gemini model name */
+  model?: string;
+  /** Navigation container ref (from useNavigationContainerRef) */
+  navRef?: any;
+  /** UI language */
+  language?: 'en' | 'ar';
+  /** Max agent steps per request */
+  maxSteps?: number;
+  /** Show/hide the chat bar */
+  showChatBar?: boolean;
+  /** Children — the actual app */
+  children: React.ReactNode;
+  /** Callback when agent completes */
+  onResult?: (result: ExecutionResult) => void;
+
+  // ── Security (mirrors page-agent.js) ──────────────────────
+
+  /** Refs of elements the AI must NOT interact with */
+  interactiveBlacklist?: React.RefObject<any>[];
+  /** If set, AI can ONLY interact with these elements */
+  interactiveWhitelist?: React.RefObject<any>[];
+  /** Called before each step */
+  onBeforeStep?: (stepCount: number) => Promise<void> | void;
+  /** Called after each step */
+  onAfterStep?: (history: AgentStep[]) => Promise<void> | void;
+  /** Called before task starts */
+  onBeforeTask?: () => Promise<void> | void;
+  /** Called after task completes */
+  onAfterTask?: (result: ExecutionResult) => Promise<void> | void;
+  /** Transform screen content before LLM sees it (for data masking) */
+  transformScreenContent?: (content: string) => Promise<string> | string;
+  /** Override or remove built-in tools (null = remove) */
+  customTools?: Record<string, ToolDefinition | null>;
+  /** Instructions to guide agent behavior */
+  instructions?: {
+    system?: string;
+    getScreenInstructions?: (screenName: string) => string | undefined | null;
+  };
+  /** Delay between steps in ms */
+  stepDelay?: number;
+  /** WebSocket URL to companion MCP server bridge (e.g., ws://localhost:3101) */
+  mcpServerUrl?: string;
+  /** Expo Router instance (from useRouter()) */
+  router?: {
+    push: (href: string) => void;
+    replace: (href: string) => void;
+    back: () => void;
+  };
+  /** Expo Router pathname (from usePathname()) */
+  pathname?: string;
+}
+
+// ─── Component ─────────────────────────────────────────────────
+
+export function AIAgent({
+  apiKey,
+  model = 'gemini-2.5-flash',
+  navRef,
+  language = 'en',
+  maxSteps = 10,
+  showChatBar = true,
+  children,
+  onResult,
+  // Security props
+  interactiveBlacklist,
+  interactiveWhitelist,
+  onBeforeStep,
+  onAfterStep,
+  onBeforeTask,
+  onAfterTask,
+  transformScreenContent,
+  customTools,
+  instructions,
+  stepDelay,
+  mcpServerUrl,
+  router,
+  pathname,
+}: AIAgentProps) {
+  const rootViewRef = useRef<any>(null);
+  const [isThinking, setIsThinking] = useState(false);
+  const [statusText, setStatusText] = useState('');
+  const [lastResult, setLastResult] = useState<ExecutionResult | null>(null);
+
+  // Ref-based resolver for ask_user — stays alive across renders
+  const askUserResolverRef = useRef<((answer: string) => void) | null>(null);
+
+  // ─── Create Runtime ──────────────────────────────────────────
+
+  const config: AgentConfig = useMemo(() => ({
+    apiKey,
+    model,
+    language,
+    maxSteps,
+    interactiveBlacklist,
+    interactiveWhitelist,
+    onBeforeStep,
+    onAfterStep,
+    onBeforeTask,
+    onAfterTask,
+    transformScreenContent,
+    customTools,
+    instructions,
+    stepDelay,
+    mcpServerUrl,
+    router,
+    pathname,
+    onStatusUpdate: setStatusText,
+    // Page-agent pattern: block the agent loop until user responds
+    onAskUser: (question: string) => {
+      return new Promise<string>((resolve) => {
+        askUserResolverRef.current = resolve;
+        // Show question in chat bar, allow user input
+        setLastResult({ success: true, message: `❓ ${question}`, steps: [] });
+        setIsThinking(false);
+        setStatusText('');
+      });
+    },
+  }), [
+    apiKey, model, language, maxSteps,
+    interactiveBlacklist, interactiveWhitelist,
+    onBeforeStep, onAfterStep, onBeforeTask, onAfterTask,
+    transformScreenContent, customTools, instructions, stepDelay,
+    mcpServerUrl, router, pathname,
+  ]);
+
+  const provider = useMemo(() => new GeminiProvider(apiKey, model), [apiKey, model]);
+
+  const runtime = useMemo(
+    () => new AgentRuntime(provider, config, rootViewRef.current, navRef),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [provider, config],
+  );
+
+  // Update refs when they change
+  useEffect(() => {
+    runtime.updateRefs(rootViewRef.current, navRef);
+  }, [runtime, navRef]);
+
+  // ─── MCP Bridge ──────────────────────────────────────────────
+
+  useEffect(() => {
+    if (!mcpServerUrl) return;
+
+    logger.info('AIAgent', `Setting up MCP bridge at ${mcpServerUrl}`);
+    const bridge = new MCPBridge(mcpServerUrl, runtime);
+
+    return () => {
+      bridge.destroy();
+    };
+  }, [mcpServerUrl, runtime]);
+
+  // ─── Execute ──────────────────────────────────────────────────
+
+  const handleSend = useCallback(async (message: string) => {
+    if (!message.trim()) return;
+
+    logger.info('AIAgent', `User message: "${message}"`);
+
+    // If there's a pending ask_user, resolve it instead of starting a new execution
+    if (askUserResolverRef.current) {
+      const resolver = askUserResolverRef.current;
+      askUserResolverRef.current = null;
+      setIsThinking(true);
+      setStatusText('Processing your answer...');
+      setLastResult(null);
+      resolver(message);
+      return;
+    }
+
+    // Normal execution — new task
+    setIsThinking(true);
+    setStatusText('Thinking...');
+    setLastResult(null);
+
+    try {
+      // Ensure we have the latest Fiber tree ref
+      runtime.updateRefs(rootViewRef.current, navRef);
+
+      const result = await runtime.execute(message);
+
+      setLastResult(result);
+      onResult?.(result);
+
+      logger.info('AIAgent', `Result: ${result.success ? '✅' : '❌'} ${result.message}`);
+    } catch (error: any) {
+      logger.error('AIAgent', 'Execution failed:', error);
+      setLastResult({
+        success: false,
+        message: `Error: ${error.message}`,
+        steps: [],
+      });
+    } finally {
+      setIsThinking(false);
+      setStatusText('');
+    }
+  }, [runtime, navRef, onResult]);
+
+  // ─── Render ──────────────────────────────────────────────────
+
+  return (
+    <AgentContext.Provider value={runtime}>
+      <View ref={rootViewRef} style={styles.root} collapsable={false}>
+        {children}
+      </View>
+
+      {/* Overlay (shown while thinking) */}
+      <AgentOverlay visible={isThinking} statusText={statusText} />
+
+      {/* Chat bar */}
+      {showChatBar && (
+        <AgentChatBar
+          onSend={handleSend}
+          isThinking={isThinking}
+          lastResult={lastResult}
+          language={language}
+          onDismiss={() => setLastResult(null)}
+        />
+      )}
+    </AgentContext.Provider>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: {
+    flex: 1,
+  },
+});

package/src/components/AgentChatBar.tsx

@@ -0,0 +1,258 @@
+/**
+ * AgentChatBar — Floating, draggable, compressible chat widget.
+ * Does not block underlying UI natively.
+ */
+
+import { useState, useRef } from 'react';
+import {
+  View,
+  TextInput,
+  Pressable,
+  Text,
+  StyleSheet,
+  Animated,
+  PanResponder,
+  useWindowDimensions,
+} from 'react-native';
+import type { ExecutionResult } from '../core/types';
+
+interface AgentChatBarProps {
+  onSend: (message: string) => void;
+  isThinking: boolean;
+  lastResult: ExecutionResult | null;
+  language: 'en' | 'ar';
+  onDismiss?: () => void;
+}
+
+export function AgentChatBar({ onSend, isThinking, lastResult, language, onDismiss }: AgentChatBarProps) {
+  const [text, setText] = useState('');
+  const [isExpanded, setIsExpanded] = useState(false);
+  const { height } = useWindowDimensions();
+  const isArabic = language === 'ar';
+
+  // Initial position: Bottom right for FAB, Bottom center for Expanded
+  // For simplicity, we just initialize to a safe generic spot on screen.
+  const pan = useRef(new Animated.ValueXY({ x: 10, y: height - 200 })).current;
+
+  // PanResponder for dragging the widget
+  const panResponder = useRef(
+    PanResponder.create({
+      onMoveShouldSetPanResponder: (_, gestureState) => {
+        // Only trigger drag if moving more than 5px (allows taps to register inside)
+        return Math.abs(gestureState.dx) > 5 || Math.abs(gestureState.dy) > 5;
+      },
+      onPanResponderGrant: () => {
+        pan.setOffset({
+          x: (pan.x as any)._value,
+          y: (pan.y as any)._value,
+        });
+        pan.setValue({ x: 0, y: 0 });
+      },
+      onPanResponderMove: Animated.event(
+        [null, { dx: pan.x, dy: pan.y }],
+        { useNativeDriver: false }
+      ),
+      onPanResponderRelease: () => {
+        pan.flattenOffset();
+      },
+    })
+  ).current;
+
+  const handleSend = () => {
+    if (text.trim() && !isThinking) {
+      onSend(text.trim());
+      setText('');
+    }
+  };
+
+  // ─── Compressed State (FAB) ───
+  if (!isExpanded) {
+    return (
+      <Animated.View style={[styles.fabContainer, pan.getLayout()]} {...panResponder.panHandlers}>
+        <Pressable 
+          style={styles.fab} 
+          onPress={() => setIsExpanded(true)}
+          accessibilityLabel="Open AI Agent Chat"
+        >
+          <Text style={styles.fabIcon}>{isThinking ? '⏳' : '🤖'}</Text>
+        </Pressable>
+      </Animated.View>
+    );
+  }
+
+  // ─── Expanded State (Widget) ───
+  return (
+    <Animated.View style={[styles.expandedContainer, pan.getLayout()]}>
+      {/* Drag Handle Area */}
+      <View {...panResponder.panHandlers} style={styles.dragHandleArea} accessibilityLabel="Drag AI Agent">
+        <View style={styles.dragGrip} />
+        <Pressable onPress={() => setIsExpanded(false)} style={styles.minimizeBtn} accessibilityLabel="Minimize AI Agent">
+          <Text style={styles.minimizeText}>—</Text>
+        </Pressable>
+      </View>
+
+      {/* Result message */}
+      {lastResult && (
+        <View style={[styles.resultBubble, lastResult.success ? styles.resultSuccess : styles.resultError]}>
+          <Text style={styles.resultText}>{lastResult.message}</Text>
+          {onDismiss && (
+            <Pressable style={styles.dismissButton} onPress={onDismiss} hitSlop={12}>
+              <Text style={styles.dismissText}>✕</Text>
+            </Pressable>
+          )}
+        </View>
+      )}
+
+      {/* Input row */}
+      <View style={styles.inputRow}>
+        <TextInput
+          style={[styles.input, isArabic && styles.inputRTL]}
+          placeholder={isArabic ? 'اكتب طلبك...' : 'Ask AI...'}
+          placeholderTextColor="#999"
+          value={text}
+          onChangeText={setText}
+          onSubmitEditing={handleSend}
+          returnKeyType="send"
+          editable={!isThinking}
+          multiline={false}
+        />
+        <Pressable
+          style={[styles.sendButton, isThinking && styles.sendButtonDisabled]}
+          onPress={handleSend}
+          disabled={isThinking || !text.trim()}
+          accessibilityLabel="Send request to AI Agent"
+        >
+          <Text style={styles.sendButtonText}>
+            {isThinking ? '⏳' : '🚀'}
+          </Text>
+        </Pressable>
+      </View>
+    </Animated.View>
+  );
+}
+
+const styles = StyleSheet.create({
+  // FAB Styles
+  fabContainer: {
+    position: 'absolute',
+    zIndex: 9999,
+  },
+  fab: {
+    width: 60,
+    height: 60,
+    borderRadius: 30,
+    backgroundColor: '#1a1a2e',
+    justifyContent: 'center',
+    alignItems: 'center',
+    elevation: 5,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 4 },
+    shadowOpacity: 0.3,
+    shadowRadius: 6,
+  },
+  fabIcon: {
+    fontSize: 28,
+  },
+
+  // Expanded Styles
+  expandedContainer: {
+    position: 'absolute',
+    zIndex: 9999,
+    width: 340,
+    backgroundColor: 'rgba(26, 26, 46, 0.95)',
+    borderRadius: 24,
+    padding: 16,
+    paddingTop: 8,
+    elevation: 8,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 8 },
+    shadowOpacity: 0.4,
+    shadowRadius: 10,
+  },
+  dragHandleArea: {
+    width: '100%',
+    height: 30,
+    justifyContent: 'center',
+    alignItems: 'center',
+    marginBottom: 8,
+  },
+  dragGrip: {
+    width: 40,
+    height: 5,
+    backgroundColor: 'rgba(255, 255, 255, 0.3)',
+    borderRadius: 4,
+  },
+  minimizeBtn: {
+    position: 'absolute',
+    right: 0,
+    top: 0,
+    padding: 8,
+  },
+  minimizeText: {
+    color: '#fff',
+    fontSize: 18,
+    fontWeight: 'bold',
+  },
+  
+  // Results & Input
+  resultBubble: {
+    borderRadius: 12,
+    padding: 12,
+    marginBottom: 12,
+    flexDirection: 'row',
+    alignItems: 'flex-start',
+  },
+  resultSuccess: {
+    backgroundColor: 'rgba(40, 167, 69, 0.2)',
+  },
+  resultError: {
+    backgroundColor: 'rgba(220, 53, 69, 0.2)',
+  },
+  resultText: {
+    color: '#fff',
+    fontSize: 14,
+    lineHeight: 20,
+    flex: 1,
+  },
+  dismissButton: {
+    marginLeft: 8,
+    padding: 2,
+  },
+  dismissText: {
+    color: 'rgba(255, 255, 255, 0.6)',
+    fontSize: 14,
+    fontWeight: 'bold',
+  },
+  inputRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 8,
+  },
+  input: {
+    flex: 1,
+    backgroundColor: 'rgba(255, 255, 255, 0.1)',
+    borderRadius: 20,
+    paddingHorizontal: 16,
+    paddingVertical: 10,
+    color: '#fff',
+    fontSize: 16,
+  },
+  inputRTL: {
+    textAlign: 'right',
+    writingDirection: 'rtl',
+  },
+  sendButton: {
+    width: 40,
+    height: 40,
+    borderRadius: 20,
+    backgroundColor: 'rgba(255, 255, 255, 0.15)',
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  sendButtonDisabled: {
+    opacity: 0.5,
+  },
+  sendButtonText: {
+    fontSize: 18,
+  },
+});

package/src/components/AgentOverlay.tsx

@@ -0,0 +1,48 @@
+/**
+ * AgentOverlay — Subtle thinking indicator shown while the AI agent is processing.
+ */
+
+import { View, Text, StyleSheet, ActivityIndicator } from 'react-native';
+
+interface AgentOverlayProps {
+  visible: boolean;
+  statusText: string;
+}
+
+export function AgentOverlay({ visible, statusText }: AgentOverlayProps) {
+  if (!visible) return null;
+
+  return (
+    <View style={styles.overlay} pointerEvents="none">
+      <View style={styles.pill}>
+        <ActivityIndicator size="small" color="#fff" />
+        <Text style={styles.text}>{statusText || 'Thinking...'}</Text>
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  overlay: {
+    position: 'absolute',
+    top: 60,
+    left: 0,
+    right: 0,
+    alignItems: 'center',
+    zIndex: 9999,
+  },
+  pill: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 8,
+    backgroundColor: 'rgba(26, 26, 46, 0.9)',
+    paddingHorizontal: 16,
+    paddingVertical: 10,
+    borderRadius: 20,
+  },
+  text: {
+    color: '#fff',
+    fontSize: 14,
+    fontWeight: '500',
+  },
+});