@ateam-ai-mobile/plugin-runtime 0.1.0

package/src/api/plugins.ts

@@ -0,0 +1,257 @@
+import { apiFetch } from '@ateam-ai-mobile/core';
+import { getCoreApiUrl } from '@ateam-ai-mobile/core';
+
+/**
+ * Summary returned by cp.listContextPlugins — no `render` field.
+ * Used for the plugin grid (name, icon, description).
+ */
+export interface PluginSurfaceMeta {
+  type: 'drawer' | 'card' | 'fullscreen' | 'header' | 'ambient' | 'nudge';
+  visibility?: 'always' | 'user' | 'engine';
+  trigger?: { from?: string; gesture?: string };
+  icon?: string;
+  title?: string;
+  subtitle?: string;
+  privacy?: boolean;
+  prompt?: string;
+}
+
+export interface PluginSummary {
+  id: string;
+  name: string;
+  version: string;
+  description?: string;
+  _source?: string;        // "mcp" for connector plugins
+  _connectorId?: string;
+  /** Declarative surface placement — added by the surface-SDK migration */
+  surface?: PluginSurfaceMeta;
+}
+
+/**
+ * Native capability flags (declared in manifest).
+ */
+export interface NativeCapabilities {
+  camera?: boolean;
+  location?: boolean;
+  biometrics?: boolean;
+  offline?: boolean;
+  backgroundTasks?: boolean;
+  fileSystem?: boolean;
+  notifications?: boolean;
+  bluetooth?: boolean;
+  haptics?: boolean;
+}
+
+/**
+ * Lifecycle hooks for service/hybrid plugins.
+ */
+export interface PluginHooks {
+  onAppStart?: boolean;
+  onPushReceived?: boolean;
+  onConnectivity?: boolean;
+  onForeground?: boolean;
+  onBackground?: boolean;
+}
+
+/**
+ * Render mode — polymorphic.
+ * - 'iframe': existing WebView (backward compat)
+ * - 'react-native': native RN component only
+ * - 'adaptive': both web and native, host picks best
+ */
+export type PluginRenderMode =
+  | { mode: 'iframe'; iframeUrl: string; bundleUrl?: string; bundleHash?: string; external?: boolean }
+  | { mode: 'react-native'; component: string; bundleUrl?: string; bundleHash?: string; bundleId?: string }
+  | {
+      mode: 'adaptive';
+      iframe: { iframeUrl: string; external?: boolean };
+      reactNative: { component: string; bundleUrl?: string; bundleHash?: string; bundleId?: string };
+    };
+
+/**
+ * Full manifest returned by cp.getContextPlugin.
+ * Extended to support native mobile plugins alongside existing web plugins.
+ */
+export interface PluginManifest extends PluginSummary {
+  type?: 'ui' | 'service' | 'hybrid';
+  render: PluginRenderMode;
+  native?: NativeCapabilities;
+  hooks?: PluginHooks;
+  channels?: string[] | {
+    events: string[];
+    actions: string[];
+  };
+  capabilities?: Record<string, unknown>;
+  _mcpEndpoint?: string;
+}
+
+/**
+ * Determine if a manifest supports native rendering.
+ */
+export function supportsNative(manifest: PluginManifest): boolean {
+  const mode = manifest.render?.mode;
+  return mode === 'react-native' || mode === 'adaptive';
+}
+
+/**
+ * Get the native component ID from a manifest (if it has native support).
+ */
+export function getNativeComponentId(manifest: PluginManifest): string | null {
+  if (manifest.render?.mode === 'react-native') return manifest.render.component;
+  if (manifest.render?.mode === 'adaptive') return manifest.render.reactNative?.component;
+  return null;
+}
+
+/**
+ * Get the native bundle URL from a manifest (if it has native support).
+ */
+export function getNativeBundleUrl(manifest: PluginManifest): string | null {
+  // Check direct bundleUrl on manifest or within render structure
+  const direct = (manifest as any).bundleUrl;
+  if (direct) return direct;
+
+  const render = manifest.render;
+  if (render.mode === 'react-native') return render.bundleUrl || null;
+  if (render.mode === 'adaptive') return render.reactNative?.bundleUrl || null;
+
+  return null;
+}
+
+/**
+ * Get the SHA-256 integrity hash for a native bundle, if the server provided one.
+ * Used post-download to verify the bundle bytes weren't tampered in transit
+ * — a MITM-replaced bundle gets `eval`'d as RN code with full capability access.
+ */
+export function getNativeBundleHash(manifest: PluginManifest): string | null {
+  const direct = (manifest as any).bundleHash;
+  if (direct) return direct;
+  const render = manifest.render;
+  if (render.mode === 'react-native') return (render as any).bundleHash || null;
+  if (render.mode === 'adaptive') return render.reactNative?.bundleHash || null;
+  return null;
+}
+
+/**
+ * Check if a manifest can be rendered as a WebView (iframe or adaptive with iframe).
+ */
+export function supportsWebView(manifest: PluginManifest): boolean {
+  return manifest.render?.mode === 'iframe' || manifest.render?.mode === 'adaptive';
+}
+
+/**
+ * List all available UI plugins via MCP JSON-RPC.
+ * Returns summary data only (no render field).
+ * Protocol: cp.listContextPlugins → core plugins + MCP connector plugins.
+ */
+export async function listPlugins(): Promise<PluginSummary[]> {
+  const res = await apiFetch<{
+    result: {
+      content: Array<{ type: string; text: string }>;
+      structuredContent?: { plugins?: PluginSummary[] };
+    };
+  }>('/mcp', {
+    method: 'POST',
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: Date.now(),
+      method: 'tools/call',
+      params: {
+        name: 'cp.listContextPlugins',
+        arguments: {},
+      },
+    }),
+  });
+
+  // Accept multiple response formats (matches web mcpClient.js fallback chain)
+  const structured = res.result?.structuredContent?.plugins;
+  if (structured) return structured;
+
+  const text = res.result?.content?.[0]?.text;
+  if (!text) return [];
+  try {
+    const parsed = JSON.parse(text);
+    return parsed.plugins || parsed || [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Get a specific plugin's FULL manifest (with render.iframeUrl).
+ * Protocol: cp.getContextPlugin({ id }) → resolves iframeUrl for core/MCP/external.
+ *
+ * IMPORTANT: The backend parameter is `id`, not `pluginId`.
+ */
+export async function getPlugin(pluginId: string): Promise<PluginManifest | null> {
+  const res = await apiFetch<{
+    result: {
+      content: Array<{ type: string; text: string }>;
+      structuredContent?: PluginManifest;
+    };
+  }>('/mcp', {
+    method: 'POST',
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: Date.now(),
+      method: 'tools/call',
+      params: {
+        name: 'cp.getContextPlugin',
+        arguments: { id: pluginId },  // Backend expects { id }, NOT { pluginId }
+      },
+    }),
+  });
+
+  // Accept structured or text response
+  if (res.result?.structuredContent) return res.result.structuredContent;
+
+  const text = res.result?.content?.[0]?.text;
+  if (!text) return null;
+  try {
+    const parsed = JSON.parse(text);
+    // Backend may return error object
+    if (parsed.error) {
+      console.warn('[getPlugin] Backend error:', parsed.error);
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve plugin iframe URL to a full URL for WebView.
+ * Matches the web frontend's PluginHost.jsx logic:
+ * - External (absolute http): append ?tenant=
+ * - MCP plugin (/mcp-ui/...): inject tenant into path → /mcp-ui/{tenant}/{connectorId}/...
+ * - Core plugin (/assets/...): prepend getCoreApiUrl()
+ */
+export function resolvePluginUrl(manifest: PluginManifest, tenant?: string): string {
+  // Extract iframeUrl from different render modes.
+  // Adaptive manifests in the wild use a flat shape — `render.iframeUrl` —
+  // not the nested `render.iframe.iframeUrl` from the type. Accept both.
+  const render = manifest.render as any;
+  let url: string | undefined;
+  if (render?.mode === 'iframe') {
+    url = render.iframeUrl;
+  } else if (render?.mode === 'adaptive') {
+    url = render.iframeUrl || render.iframe?.iframeUrl;
+  }
+  // react-native only → no URL
+  if (!url) return '';
+
+  // Already absolute URL (external plugins like Voice)
+  if (url.startsWith('http')) {
+    const sep = url.includes('?') ? '&' : '?';
+    return tenant ? `${url}${sep}tenant=${encodeURIComponent(tenant)}` : url;
+  }
+
+  // MCP plugin — inject tenant into path: /mcp-ui/{connectorId}/... → /mcp-ui/{tenant}/{connectorId}/...
+  if (tenant && url.startsWith('/mcp-ui/')) {
+    const tenantUrl = url.replace('/mcp-ui/', `/mcp-ui/${encodeURIComponent(tenant)}/`);
+    return `${getCoreApiUrl()}${tenantUrl}`;
+  }
+
+  // Core plugin — prepend core API base
+  return `${getCoreApiUrl()}${url}`;
+}

package/src/bridge/native.ts

@@ -0,0 +1,266 @@
+/**
+ * Native bridge for React Native plugins.
+ * Direct function calls — no postMessage, no serialization.
+ *
+ * Identity comes from @ateam-ai-mobile/core config (host-owned auth); tool calls go
+ * through the same MCP layer as everything else.
+ */
+import { useCallback, useMemo, useRef, useEffect } from 'react';
+import type { MutableRefObject } from 'react';
+import {
+  connectorCall,
+  mcpFetch as mcpFetchApi,
+  unwrapMcpResult,
+  postCommandResult,
+  getTenant,
+  getUser,
+  pluginCommandEmitter,
+  useChatStore,
+} from '@ateam-ai-mobile/core';
+import type { PluginBridge, PluginContext } from '../sdk/types';
+
+type CommandListener = (type: string, payload: any) => void;
+
+function buildContext(pluginId: string, connectorId?: string): PluginContext {
+  const user = getUser();
+  return {
+    tenant: getTenant(),
+    pluginId,
+    connectorId,
+    user: user ? { id: user.actorId || '', name: user.name || '', roles: [] } : undefined,
+  };
+}
+
+export function useNativeBridge(pluginId: string, connectorId?: string, commandBufferRef?: MutableRefObject<any[]>): PluginBridge {
+  const initCallbackRef = useRef<((ctx: PluginContext) => void) | null>(null);
+  const commandListenersRef = useRef<Set<CommandListener>>(new Set());
+  const initializedRef = useRef(false);
+
+  const fireInit = useCallback(() => {
+    if (initializedRef.current || !initCallbackRef.current) return;
+    initCallbackRef.current(buildContext(pluginId, connectorId));
+    initializedRef.current = true;
+  }, [pluginId, connectorId]);
+
+  const onInit = useCallback((cb: (ctx: PluginContext) => void) => {
+    initCallbackRef.current = cb;
+    setTimeout(fireInit, 0);
+  }, [fireInit]);
+
+  const mcpCall = useCallback(async (toolOrConnector: string, argsOrTool: any, cIdOrArgs?: any): Promise<any> => {
+    // Support BOTH argument orders:
+    //   (tool, args, connectorId?)         — bridge standard
+    //   (connectorId, tool, args?)         — plugin convenience (matches useApi pattern)
+    // Detect: if 2nd arg is a string, caller used (connector, tool, args) order
+    let tool: string;
+    let args: any;
+    let cId: string | undefined;
+
+    if (typeof argsOrTool === 'string') {
+      // (connectorId, tool, args) order
+      cId = toolOrConnector;
+      tool = argsOrTool;
+      args = cIdOrArgs || {};
+    } else {
+      // Standard (tool, args, connectorId?) order
+      tool = toolOrConnector;
+      args = argsOrTool;
+      cId = typeof cIdOrArgs === 'string' ? cIdOrArgs : undefined;
+    }
+
+    const targetConnector = cId || connectorId;
+    if (!targetConnector) {
+      console.warn(`[NativeBridge:${pluginId}] mcpCall failed — no connectorId. tool=${tool}`);
+      throw new Error(`[NativeBridge:${pluginId}] mcpCall requires a connectorId`);
+    }
+
+    try {
+      const data = await connectorCall(targetConnector, tool, args);
+
+      if (!data.ok && data.error) {
+        throw new Error(data.error);
+      }
+      return unwrapMcpResult(data.result);
+    } catch (err) {
+      console.warn(`[NativeBridge:${pluginId}] mcpCall failed → connector=${targetConnector} tool=${tool}:`, (err as any)?.message || err);
+      throw err;
+    }
+  }, [pluginId, connectorId]);
+
+  const mcpFetch = useCallback(async (body: any): Promise<any> => {
+    return mcpFetchApi(body);
+  }, []);
+
+  const sendCommand = useCallback((type: string, payload: any) => {
+    // Handle command results — mirror web PluginHost pattern
+    if (type === 'plugin.command.result' && payload?.correlationId) {
+      postCommandResult(payload.correlationId, payload.result, payload.error);
+      return;
+    }
+  }, [pluginId]);
+
+  const onCommand = useCallback((cb: CommandListener): (() => void) => {
+    commandListenersRef.current.add(cb);
+    // Flush buffered commands immediately when a listener registers —
+    // the buffer may have commands that arrived before the plugin mounted.
+    if (commandBufferRef) {
+      const buf = commandBufferRef.current;
+      const remaining: any[] = [];
+      for (const cmd of buf) {
+        if (cmd.pluginId === pluginId && cmd.command !== '__focus') {
+          try { cb(cmd.command, { ...cmd.args, correlationId: cmd.correlationId }); } catch {}
+        } else {
+          remaining.push(cmd);
+        }
+      }
+      commandBufferRef.current = remaining;
+    }
+    // Also drain the emitter's own recent-commands buffer (covers the
+    // surface-dispatcher path which has no commandBufferRef).
+    for (const cmd of pluginCommandEmitter.drainPluginCommands(pluginId)) {
+      try { cb(cmd.command, { ...cmd.args, correlationId: cmd.correlationId }); } catch {}
+    }
+    return () => {
+      commandListenersRef.current.delete(cb);
+    };
+  }, [pluginId, commandBufferRef]);
+
+  // Dispatch live plugin commands to registered listeners
+  useEffect(() => {
+    const unsub = pluginCommandEmitter.on('plugin-command', (cmd: any) => {
+      if (cmd.pluginId !== pluginId) return;
+      if (cmd.command === '__focus') return; // Focus-only, no dispatch
+      commandListenersRef.current.forEach(fn => {
+        try { fn(cmd.command, { ...cmd.args, correlationId: cmd.correlationId }); } catch {}
+      });
+    });
+    return unsub;
+  }, [pluginId]);
+
+  // Flush buffered commands on mount (commands that arrived before plugin
+  // was ready). Two sources, both safe to drain:
+  //   1. The parent-passed `commandBufferRef` (legacy overlay path).
+  //   2. The emitter's own recent-commands buffer (surface-dispatcher path).
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      const dispatch = (cmd: any) => {
+        commandListenersRef.current.forEach(fn => {
+          try { fn(cmd.command, { ...cmd.args, correlationId: cmd.correlationId }); } catch {}
+        });
+      };
+
+      if (commandBufferRef) {
+        const remaining: any[] = [];
+        for (const cmd of commandBufferRef.current) {
+          if (cmd.pluginId === pluginId && cmd.command !== '__focus') dispatch(cmd);
+          else remaining.push(cmd);
+        }
+        commandBufferRef.current = remaining;
+      }
+
+      // Always drain the emitter buffer too — the dispatcher path has no
+      // parent buffer, and the legacy path may still have lost commands here
+      // if they arrived before the parent's listener registered.
+      for (const cmd of pluginCommandEmitter.drainPluginCommands(pluginId)) {
+        dispatch(cmd);
+      }
+    }, 500); // Delay to let plugin register its onCommand listener
+    return () => clearTimeout(timer);
+  }, [pluginId, commandBufferRef]);
+
+  useEffect(() => {
+    return () => {
+      commandListenersRef.current.clear();
+      initializedRef.current = false;
+    };
+  }, []);
+
+  const close = useCallback(() => {
+    pluginCommandEmitter.emit('plugin-close', { pluginId });
+  }, [pluginId]);
+
+  /** Send a chat message into the user's thread (e.g. confirmed "connect my
+   *  Gmail"). Pair with bridge.close() to land the user on chat. */
+  const sendMessage = useCallback((text: string) => {
+    const t = (text || '').trim();
+    if (!t) return;
+    try {
+      useChatStore.getState().sendMessage(t);
+    } catch (err) {
+      console.warn('[bridge.sendMessage] failed:', err instanceof Error ? err.message : String(err));
+    }
+  }, []);
+
+  /** Prepare (pre-fill) the chat composer without sending. The host chat
+   *  screen listens for `prepare-chat-message` and stuffs `text` into its
+   *  input state. Pair with bridge.close(). */
+  const prepareMessage = useCallback((text: string) => {
+    const t = (text || '').trim();
+    if (!t) return;
+    pluginCommandEmitter.emit('prepare-chat-message', { text: t });
+  }, []);
+
+  // Memoize the bridge object to prevent child re-renders — a new object
+  // every render → useApi recreates → fetch effects refire → flicker loop.
+  return useMemo(
+    () => ({ onInit, mcpCall, mcpFetch, sendCommand, onCommand, close, sendMessage, prepareMessage }),
+    [onInit, mcpCall, mcpFetch, sendCommand, onCommand, close, sendMessage, prepareMessage],
+  );
+}
+
+/**
+ * Non-hook version for service plugins (no React lifecycle).
+ */
+export function createNativeBridge(pluginId: string, connectorId?: string): PluginBridge {
+  const commandListeners = new Set<CommandListener>();
+
+  return {
+    onInit(cb) {
+      setTimeout(() => {
+        cb(buildContext(pluginId, connectorId));
+      }, 0);
+    },
+
+    async mcpCall(tool: string, args: any, cId?: string) {
+      const targetConnector = cId || connectorId;
+      if (!targetConnector) {
+        throw new Error(`[NativeBridge:${pluginId}] mcpCall requires a connectorId`);
+      }
+      const data = await connectorCall(targetConnector, tool, args);
+      if (!data.ok && data.error) throw new Error(data.error);
+      return unwrapMcpResult(data.result);
+    },
+
+    async mcpFetch(body: any) {
+      return mcpFetchApi(body);
+    },
+
+    sendCommand(_type: string, _payload: any) {
+    },
+
+    onCommand(cb: CommandListener) {
+      commandListeners.add(cb);
+      return () => { commandListeners.delete(cb); };
+    },
+
+    close() {
+      pluginCommandEmitter.emit('plugin-close', { pluginId });
+    },
+
+    sendMessage(text: string) {
+      const t = (text || '').trim();
+      if (!t) return;
+      try {
+        useChatStore.getState().sendMessage(t);
+      } catch (err) {
+        console.warn('[bridge.sendMessage] failed:', err instanceof Error ? err.message : String(err));
+      }
+    },
+
+    prepareMessage(text: string) {
+      const t = (text || '').trim();
+      if (!t) return;
+      pluginCommandEmitter.emit('prepare-chat-message', { text: t });
+    },
+  } as PluginBridge;
+}