Finalize mobile portability boundary

Generated-By: PostHog Code
Task-Id: 40c57a59-b4e1-4760-8e56-ecd03e9c2f0f

Author: richardsolomou

apps/mobile/README.md

@@ -32,7 +32,7 @@ pnpm --filter @posthog/mobile start
 
 ### Feature Folders
 
-Code is organized by feature in `src/features/`. Each feature is self-contained with its own components, hooks, stores, and API logic.
+Code is organized by feature in `src/features/`. Features own native components, one-source hooks, and view state. They do not own copies of cloud contracts, transport, orchestration, or presentation rules.
 
 ```
 src/features/
@@ -46,18 +46,31 @@ src/features/
 │   ├── hooks/
 │   ├── stores/
 │   └── types.ts
-├── conversations/  # PostHog AI conversation list & management
-│   ├── api.ts
+├── inbox/          # Native inbox rendering and query hooks
 │   ├── components/
 │   ├── hooks/
 │   └── stores/
-└── tasks/          # Task management
-    ├── api.ts
+└── tasks/          # Native cloud-task rendering and host adapters
     ├── components/
     ├── hooks/
+    ├── services/
     └── stores/
 ```
 
+### Portability boundary
+
+Mobile and desktop use the same cloud-task architecture. New work must preserve these ownership rules:
+
+- `@posthog/shared` owns runtime contracts and Zod schemas.
+- `@posthog/api-client` owns authenticated PostHog HTTPS transport and its request/response types.
+- `@posthog/core` owns cloud-task orchestration and headless presentation decisions, including sessions, queues, permissions, models, repositories, inbox rules, and automation semantics.
+- `apps/mobile` owns Expo lifecycle, React Native rendering, gestures, sheets, notifications, audio, secure storage, and small persisted view-state stores.
+- `@posthog/ui` owns the DOM/Quill renderer and web view state.
+
+Do not add a mobile API facade, duplicate a shared type, or re-export a core helper through a mobile file. Import the owning package directly. If desktop and mobile need different visuals, add a headless descriptor or decision function to core and keep two thin renderers.
+
+Intentional host differences are limited to platform capabilities and view state. Mobile may persist native navigation state, cached picker snapshots, optimistic attachment echoes, and notification preferences; it must not implement retries, reconnection, transport parsing, task lifecycle, or cross-store decisions in those stores.
+
 ### File-Based Routing
 
 Routes for the screens are defined by the file structure in `src/app/` using expo-router. 
@@ -270,4 +283,4 @@ Defined in `eas.json`:
 
 **Local vs Cloud builds:**
 - Cloud (default): Runs on Expo's servers, no local Xcode needed
-- Local (`--local`): Runs on your machine, faster iteration, requires Xcode/Android SDK
+- Local (`--local`): Runs on your machine, faster iteration, requires Xcode/Android SDK

apps/mobile/src/app/mcp-servers/add-custom.tsx

@@ -1,4 +1,5 @@
 import { Text } from "@components/text";
+import type { McpAuthType } from "@posthog/api-client/types";
 import { router } from "expo-router";
 import { Lock } from "phosphor-react-native";
 import { useState } from "react";
@@ -14,7 +15,6 @@ import {
 import { FloatingMcpHeader } from "@/features/mcp/components/FloatingMcpHeader";
 import { useMcpInstallations } from "@/features/mcp/hooks";
 import { installCustomWithOAuth } from "@/features/mcp/oauth";
-import type { McpAuthType } from "@/features/mcp/types";
 import { useScreenInsets } from "@/hooks/useScreenInsets";
 import { logger } from "@/lib/logger";
 import { useThemeColors } from "@/lib/theme";

apps/mobile/src/app/mcp-servers/index.tsx

@@ -1,4 +1,8 @@
 import { Text } from "@components/text";
+import type {
+  McpRecommendedServer,
+  McpServerInstallation,
+} from "@posthog/api-client/types";
 import { useRouter } from "expo-router";
 import { MagnifyingGlass, Plus, PuzzlePiece } from "phosphor-react-native";
 import { useMemo, useState } from "react";
@@ -17,10 +21,6 @@ import {
   recommendedToRowProps,
 } from "@/features/mcp/components/McpServerRow";
 import { useMcpInstallations, useMcpMarketplace } from "@/features/mcp/hooks";
-import type {
-  McpRecommendedServer,
-  McpServerInstallation,
-} from "@/features/mcp/types";
 import { useScreenInsets } from "@/hooks/useScreenInsets";
 import { useThemeColors } from "@/lib/theme";
 

apps/mobile/src/app/mcp-servers/installation/[id].tsx

@@ -1,4 +1,6 @@
 import { Text } from "@components/text";
+import type { McpApprovalState } from "@posthog/api-client/types";
+import { isStdioMcpServer } from "@posthog/core/mcp-servers/presentation";
 import { router, useLocalSearchParams } from "expo-router";
 import {
   ArrowsClockwise,
@@ -28,8 +30,6 @@ import {
 } from "@/features/mcp/hooks";
 import { reauthorizeInstallation } from "@/features/mcp/oauth";
 import { getMcpConnectionManager } from "@/features/mcp/service";
-import type { McpApprovalState } from "@/features/mcp/types";
-import { isStdioServer } from "@/features/mcp/types";
 import { useScreenInsets } from "@/hooks/useScreenInsets";
 import { logger } from "@/lib/logger";
 import { useThemeColors } from "@/lib/theme";
@@ -75,7 +75,7 @@ export default function McpInstallationDetailScreen() {
     );
   }
 
-  const stdio = isStdioServer(installation);
+  const stdio = isStdioMcpServer(installation);
 
   const handleEnabledChange = (enabled: boolean) => {
     updateMutation.mutate({

apps/mobile/src/app/mcp-servers/template/[id].tsx

@@ -1,4 +1,5 @@
 import { Text } from "@components/text";
+import { isStdioMcpServer } from "@posthog/core/mcp-servers/presentation";
 import { router, useLocalSearchParams } from "expo-router";
 import { Lock, Warning } from "phosphor-react-native";
 import { useMemo, useState } from "react";
@@ -17,7 +18,6 @@ import {
   useMcpMarketplace,
 } from "@/features/mcp/hooks";
 import { installTemplateWithOAuth } from "@/features/mcp/oauth";
-import { isStdioServer } from "@/features/mcp/types";
 import { useScreenInsets } from "@/hooks/useScreenInsets";
 import { logger } from "@/lib/logger";
 import { openExternalUrl } from "@/lib/openExternalUrl";
@@ -71,7 +71,7 @@ export default function McpTemplateDetailScreen() {
     );
   }
 
-  const stdio = isStdioServer(template);
+  const stdio = isStdioMcpServer(template);
 
   const handleInstall = async () => {
     if (!template) return;

apps/mobile/src/features/chat/components/ToolMessage.tsx

@@ -3,6 +3,7 @@ import {
   getPostHogExecDisplay,
   isPostHogExecTool,
 } from "@posthog/core/sessions/posthogExecDisplay";
+import { parseMcpToolName } from "@posthog/shared";
 import { useRouter } from "expo-router";
 import {
   ArrowsClockwise,
@@ -28,7 +29,6 @@ import {
   View,
 } from "react-native";
 import { McpAppHost } from "@/features/mcp/components/McpAppHost";
-import { isMcpToolName } from "@/features/mcp/utils/mcpToolName";
 import {
   getColorForClass,
   highlightCode,
@@ -942,7 +942,8 @@ export function ToolMessage({
   // MCP App tools render via the WebView host — skip PostHog exec (which has
   // its own renderer above) and only kick in once the tool finished or while
   // it's running so we don't show empty WebView shells for pending tools.
-  const isMcpAppTool = !isPostHogExec && isMcpToolName(effectiveToolName);
+  const isMcpAppTool =
+    !isPostHogExec && parseMcpToolName(effectiveToolName) !== undefined;
 
   if (isMcpAppTool && !isPending) {
     return (

apps/mobile/src/features/mcp/components/McpAppHost.tsx

@@ -1,7 +1,7 @@
 import { Text } from "@components/text";
 import type { McpUiDisplayMode } from "@modelcontextprotocol/ext-apps/app-bridge";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { isSafeExternalUrl } from "@posthog/shared";
+import { isSafeExternalUrl, parseMcpToolName } from "@posthog/shared";
 import * as WebBrowser from "expo-web-browser";
 import { ArrowsIn, ArrowsOut, Warning } from "phosphor-react-native";
 import { useCallback, useMemo, useRef, useState } from "react";
@@ -22,7 +22,6 @@ import { sandboxProxyHtml } from "../sandbox/sandboxProxyHtml";
 import { useMcpUiResource } from "../sandbox/useMcpUiResource";
 import { type Phase, useMobileAppBridge } from "../sandbox/useMobileAppBridge";
 import { getMcpConnectionManager } from "../service";
-import { parseMcpToolName } from "../utils/mcpToolName";
 
 interface McpAppHostProps {
   /** Raw tool name from the agent — `mcp__<server>__<tool>`. */
@@ -60,14 +59,12 @@ export function McpAppHost(props: McpAppHostProps) {
   const installations = useMcpInstallations();
   const installation = useMemo(() => {
     if (!parsed) return null;
-    return (
-      installations.data?.find((i) => i.name === parsed.serverName) ?? null
-    );
+    return installations.data?.find((i) => i.name === parsed.server) ?? null;
   }, [installations.data, parsed]);
 
   const uiResource = useMcpUiResource({
     installation,
-    toolName: parsed?.toolName ?? "",
+    toolName: parsed?.tool ?? "",
   });
 
   const webViewRef = useRef<WebView | null>(null);
@@ -122,7 +119,7 @@ export function McpAppHost(props: McpAppHostProps) {
   const { handleWebViewMessage } = useMobileAppBridge({
     webViewRef,
     uiResource: uiResource.data?.resource ?? null,
-    serverName: parsed?.serverName ?? "",
+    serverName: parsed?.server ?? "",
     toolDefinition: uiResource.data?.tool ?? null,
     toolInput: props.toolArgs ?? null,
     existingToolResult:

apps/mobile/src/features/mcp/components/McpServerRow.tsx

@@ -1,10 +1,13 @@
 import { Text } from "@components/text";
+import type {
+  McpRecommendedServer,
+  McpServerInstallation,
+} from "@posthog/api-client/types";
+import { isStdioMcpServer } from "@posthog/core/mcp-servers/presentation";
 import { CaretRight, Lock, Warning } from "phosphor-react-native";
 import type { ReactNode } from "react";
 import { Pressable, View } from "react-native";
 import { useThemeColors } from "@/lib/theme";
-import type { McpRecommendedServer, McpServerInstallation } from "../types";
-import { isStdioServer } from "../types";
 import { ServerIcon } from "./ServerIcon";
 
 interface McpServerRowProps {
@@ -119,7 +122,7 @@ export function recommendedToRowProps(
     title: template.name,
     description: template.description,
     authType: template.auth_type,
-    isStdio: isStdioServer(template),
+    isStdio: isStdioMcpServer(template),
     installed: installedNames.has(template.name),
     iconKey: template.icon_key,
     onPress: () => onPress(template),
@@ -134,7 +137,7 @@ export function installationToRowProps(
     title: installation.display_name || installation.name,
     subtitle: installation.url,
     authType: installation.auth_type,
-    isStdio: isStdioServer(installation),
+    isStdio: isStdioMcpServer(installation),
     needsReauth: installation.needs_reauth,
     installed: true,
     iconKey: installation.icon_key,

apps/mobile/src/features/mcp/hooks.ts

@@ -1,11 +1,11 @@
-import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { getPostHogApiClient } from "@/lib/posthogApiClient";
 import type {
   InstallCustomMcpServerOptions,
   InstallMcpTemplateOptions,
   McpApprovalState,
   UpdateMcpServerInstallationOptions,
-} from "./types";
+} from "@posthog/api-client/types";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { getPostHogApiClient } from "@/lib/posthogApiClient";
 
 const mcpKeys = {
   all: ["mcp"] as const,

apps/mobile/src/features/mcp/mcpUiResource.ts

@@ -0,0 +1,6 @@
+export interface McpUiResource {
+  uri: string;
+  html: string;
+  csp?: Record<string, unknown>;
+  permissions?: Record<string, Record<string, unknown>>;
+}