Add managed local plugin lifecycle (#3222)

* feat(plugins): add local plugin surfaces and RPCs

Keep plugin execution scoped to its daemon while allowing one local TypeScript entry point to contribute validated RPCs and native client surfaces. Paseo owns host selection, navigation chrome, and per-installation query caches.

* feat(plugins): add Linear attachment source

* fix(nix): refresh npm dependency hash

* test(server): exclude internal sessions from Hub counts

* test(server): distinguish Hub execution sessions

* feat(plugins): make local plugins explicitly opt-in

Keep plugin loading dormant until configuration enables it, and collect unsupported examples under one directory.

* refactor(plugins): establish host boundaries

* fix(nix): refresh plugin dependency hash

* fix(plugins): complete packaging and startup rollback

* feat(plugins): add managed local lifecycle

Make trusted local plugins recoverable and authorable through daemon-owned lifecycle operations, host settings, and a capability-gated CLI. Reloads fully stop the previous plugin before starting new code, while generated projects provide strict TSX checking without changing runtime dependency ownership.

* fix(nix): refresh plugin dependency hash

packages/app/src/plugins/attachments/index.ts

@@ -0,0 +1,5 @@
+export {
+  PluginResourceComposerAttachmentSchema,
+  pluginResourceAttachmentToAgentAttachment,
+  type PluginResourceComposerAttachment,
+} from "./model";

packages/app/src/plugins/attachments/model.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+import {
+  createPluginResourceAttachment,
+  PluginResourceComposerAttachmentSchema,
+  pluginResourceAttachmentToAgentAttachment,
+  togglePluginResourceAttachment,
+} from "./model";
+import { splitComposerAttachmentsForSubmit } from "@/composer/attachments/submit";
+
+const source = {
+  pluginId: "linear",
+  sourceId: "issues",
+  sourceTitle: "Linear issue",
+  sourceIcon: "CircleDot",
+};
+
+const item = {
+  id: "issue-uuid",
+  identifier: "ENG-123",
+  title: "Plugin attachments",
+  subtitle: "In progress · Mohamed",
+  url: "https://linear.app/acme/issue/ENG-123/plugin-attachments",
+  text: "Linear issue ENG-123: Plugin attachments\nStatus: In progress",
+  resourceType: "issue",
+};
+
+describe("plugin resource attachments", () => {
+  it("creates a draft-safe composer attachment", () => {
+    const attachment = createPluginResourceAttachment(source, item);
+
+    expect(PluginResourceComposerAttachmentSchema.parse(attachment)).toEqual({
+      kind: "plugin_resource",
+      ...source,
+      item,
+    });
+  });
+
+  it("toggles one resource by plugin, source, and stable item id", () => {
+    const attachment = createPluginResourceAttachment(source, item);
+
+    expect(togglePluginResourceAttachment([], attachment)).toEqual([attachment]);
+    expect(togglePluginResourceAttachment([attachment], attachment)).toEqual([]);
+  });
+
+  it("submits through the backward-compatible text attachment", () => {
+    const attachment = createPluginResourceAttachment(source, item);
+
+    const agentAttachment = pluginResourceAttachmentToAgentAttachment(attachment);
+    expect(agentAttachment).toEqual({
+      type: "text",
+      mimeType: "text/plain",
+      title: "ENG-123 Plugin attachments",
+      text: item.text,
+      externalResource: {
+        provider: "linear",
+        providerLabel: "Linear issue",
+        resourceType: "issue",
+        id: "issue-uuid",
+        identifier: "ENG-123",
+        title: "Plugin attachments",
+        url: item.url,
+      },
+    });
+    expect(splitComposerAttachmentsForSubmit([attachment])).toEqual({
+      images: [],
+      attachments: [agentAttachment],
+    });
+  });
+});

packages/app/src/plugins/attachments/model.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import type { AgentAttachment } from "@getpaseo/protocol/messages";
+import { PluginAttachmentItemSchema, type PluginAttachmentItem } from "@paseo/plugin";
+import type { UserComposerAttachment } from "@/attachments/types";
+
+export const PluginResourceComposerAttachmentSchema = z.object({
+  kind: z.literal("plugin_resource"),
+  pluginId: z.string().min(1),
+  sourceId: z.string().min(1),
+  sourceTitle: z.string().min(1),
+  sourceIcon: z.string().min(1),
+  item: PluginAttachmentItemSchema,
+});
+
+export type PluginResourceComposerAttachment = z.infer<
+  typeof PluginResourceComposerAttachmentSchema
+>;
+
+export interface PluginResourceSourceIdentity {
+  pluginId: string;
+  sourceId: string;
+  sourceTitle: string;
+  sourceIcon: string;
+}
+
+export function createPluginResourceAttachment(
+  source: PluginResourceSourceIdentity,
+  item: PluginAttachmentItem,
+): PluginResourceComposerAttachment {
+  return {
+    kind: "plugin_resource",
+    ...source,
+    item,
+  };
+}
+
+export function togglePluginResourceAttachment(
+  current: UserComposerAttachment[],
+  attachment: PluginResourceComposerAttachment,
+): UserComposerAttachment[] {
+  const matches = (candidate: UserComposerAttachment) =>
+    candidate.kind === "plugin_resource" &&
+    candidate.pluginId === attachment.pluginId &&
+    candidate.sourceId === attachment.sourceId &&
+    candidate.item.id === attachment.item.id;
+  if (current.some(matches)) {
+    return current.filter((candidate) => !matches(candidate));
+  }
+  return [...current, attachment];
+}
+
+export function pluginResourceAttachmentToAgentAttachment(
+  attachment: PluginResourceComposerAttachment,
+): AgentAttachment {
+  return {
+    type: "text",
+    mimeType: "text/plain",
+    title: `${attachment.item.identifier} ${attachment.item.title}`,
+    text: attachment.item.text,
+    externalResource: {
+      provider: attachment.pluginId,
+      providerLabel: attachment.sourceTitle,
+      resourceType: attachment.item.resourceType,
+      id: attachment.item.id,
+      identifier: attachment.item.identifier,
+      title: attachment.item.title,
+      url: attachment.item.url,
+    },
+  };
+}

packages/app/src/plugins/attachments/picker.tsx

@@ -0,0 +1,179 @@
+import { useCallback, useMemo, useState, type ReactElement, type RefObject } from "react";
+import { View } from "react-native";
+import { withUnistyles } from "react-native-unistyles";
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import type { PluginAttachmentItem, PluginAttachmentSourceContribution } from "@paseo/plugin";
+import { searchPluginAttachments } from "@paseo/plugin/host";
+import type { LucideIcon } from "lucide-react-native";
+import type { UserComposerAttachment } from "@/attachments/types";
+import type { AttachmentMenuItem } from "@/composer/input/input";
+import { Combobox, type ComboboxOption } from "@/components/ui/combobox";
+import { useFetchQuery } from "@/data/query";
+import { ICON_SIZE, type Theme } from "@/styles/theme";
+import { resolvePluginIcon } from "../icons";
+import { useInstalledPlugins } from "../registry";
+import type { InstalledPlugin } from "../types";
+import { createPluginResourceAttachment, togglePluginResourceAttachment } from "./model";
+
+const SEARCH_STALE_TIME_MS = 30_000;
+const EMPTY_ATTACHMENT_ITEMS: PluginAttachmentItem[] = [];
+const iconColorMapping = (theme: Theme) => ({ color: theme.colors.foregroundMuted });
+
+function SourceIcon({ Icon, color = "" }: { Icon: LucideIcon; color?: string }) {
+  return <Icon size={ICON_SIZE.md} color={color} />;
+}
+
+const ThemedSourceIcon = withUnistyles(SourceIcon);
+
+interface InstalledAttachmentSource {
+  plugin: InstalledPlugin;
+  source: PluginAttachmentSourceContribution;
+  key: string;
+}
+
+interface PluginAttachmentPickerInput {
+  serverId: string;
+  client: DaemonClient | null;
+  connected: boolean;
+  attachments: UserComposerAttachment[];
+  onChangeAttachments: (attachments: UserComposerAttachment[]) => void;
+  anchorRef: RefObject<View | null>;
+}
+
+interface PluginAttachmentPickerBinding {
+  menuItems: AttachmentMenuItem[];
+  picker: ReactElement | null;
+}
+
+function searchEmptyText(error: unknown, isFetching: boolean): string {
+  if (error instanceof Error) return error.message;
+  if (error) return String(error);
+  return isFetching ? "Searching..." : "No results";
+}
+
+function installedAttachmentSources(
+  plugins: InstalledPlugin[],
+  serverId: string,
+): InstalledAttachmentSource[] {
+  return plugins
+    .filter((plugin) => plugin.serverId === serverId)
+    .flatMap((plugin) =>
+      plugin.attachmentSources.map((source) => ({
+        plugin,
+        source,
+        key: `${plugin.id}/${source.id}`,
+      })),
+    );
+}
+
+function attachmentOptions(items: PluginAttachmentItem[]): ComboboxOption[] {
+  return items.map((item) => ({
+    id: item.id,
+    label: `${item.identifier} ${item.title}`,
+    description: item.subtitle,
+  }));
+}
+
+export function usePluginAttachmentPicker(
+  input: PluginAttachmentPickerInput,
+): PluginAttachmentPickerBinding {
+  const plugins = useInstalledPlugins();
+  const sources = useMemo(
+    () => installedAttachmentSources(plugins, input.serverId),
+    [input.serverId, plugins],
+  );
+  const [activeKey, setActiveKey] = useState<string | null>(null);
+  const [query, setQuery] = useState("");
+  const active = sources.find((candidate) => candidate.key === activeKey) ?? null;
+  const trimmedQuery = query.trim();
+  const search = useFetchQuery(
+    {
+      queryKey: [
+        "plugin-attachment-search",
+        input.serverId,
+        active?.plugin.id ?? "",
+        active?.source.id ?? "",
+        trimmedQuery,
+      ],
+      queryFn: async () => {
+        if (!input.client || !active) throw new Error("Plugin host is offline");
+        const client = input.client;
+        return searchPluginAttachments(
+          active.source,
+          (method, rpcInput) => client.invokePluginRpc(active.plugin.id, method, rpcInput),
+          trimmedQuery,
+        );
+      },
+      enabled: input.connected && active !== null,
+      dataShape: "list",
+      staleTimeMs: SEARCH_STALE_TIME_MS,
+    },
+    active?.plugin.queryClient,
+  );
+  const items = search.error
+    ? EMPTY_ATTACHMENT_ITEMS
+    : (search.data?.items ?? EMPTY_ATTACHMENT_ITEMS);
+  const options = useMemo(() => attachmentOptions(items), [items]);
+  const close = useCallback(() => {
+    setActiveKey(null);
+    setQuery("");
+  }, []);
+  const handleOpenChange = useCallback(
+    (open: boolean) => {
+      if (!open) close();
+    },
+    [close],
+  );
+  const handleSelect = useCallback(
+    (itemId: string) => {
+      if (!active) return;
+      const item = items.find((candidate) => candidate.id === itemId);
+      if (!item) return;
+      const attachment = createPluginResourceAttachment(
+        {
+          pluginId: active.plugin.id,
+          sourceId: active.source.id,
+          sourceTitle: active.source.title,
+          sourceIcon: active.source.icon,
+        },
+        item,
+      );
+      input.onChangeAttachments(togglePluginResourceAttachment(input.attachments, attachment));
+      close();
+    },
+    [active, close, input, items],
+  );
+  const menuItems = useMemo(
+    () =>
+      sources.map(({ key, source }) => {
+        const Icon = resolvePluginIcon(source.icon);
+        return {
+          id: `plugin:${key}`,
+          label: `Attach ${source.title}`,
+          icon: <ThemedSourceIcon Icon={Icon} uniProps={iconColorMapping} />,
+          onSelect: () => setActiveKey(key),
+        };
+      }),
+    [sources],
+  );
+  if (!active) return { menuItems, picker: null };
+  return {
+    menuItems,
+    picker: (
+      <Combobox
+        options={options}
+        value=""
+        onSelect={handleSelect}
+        searchable
+        searchPlaceholder={active.source.searchPlaceholder}
+        title={active.source.pickerTitle}
+        open
+        onOpenChange={handleOpenChange}
+        onSearchQueryChange={setQuery}
+        desktopPlacement="top-start"
+        anchorRef={input.anchorRef}
+        emptyText={searchEmptyText(search.error, search.isFetching)}
+      />
+    ),
+  };
+}

packages/app/src/plugins/attachments/pill.tsx

@@ -0,0 +1,65 @@
+import { useCallback, useMemo } from "react";
+import { withUnistyles } from "react-native-unistyles";
+import { AttachmentLabel, AttachmentPill } from "@/components/attachment-pill";
+import type { ComposerAttachment } from "@/attachments/types";
+import { ICON_SIZE, type Theme } from "@/styles/theme";
+import { resolvePluginIcon } from "../icons";
+import type { PluginResourceComposerAttachment } from "./model";
+
+const iconColorMapping = (theme: Theme) => ({ color: theme.colors.foregroundMuted });
+
+function ResourceIcon({
+  Icon,
+  color = "",
+}: {
+  Icon: ReturnType<typeof resolvePluginIcon>;
+  color?: string;
+}) {
+  return <Icon size={ICON_SIZE.sm} color={color} />;
+}
+
+const ThemedResourceIcon = withUnistyles(ResourceIcon);
+
+interface PluginResourceAttachmentPillProps {
+  attachment: PluginResourceComposerAttachment;
+  index: number;
+  disabled: boolean;
+  onOpen: (attachment: ComposerAttachment) => void;
+  onRemove: (index: number) => void;
+  openLabel: (kind: string, identifier: string) => string;
+  removeLabel: (kind: string, identifier: string) => string;
+}
+
+export function PluginResourceAttachmentPill({
+  attachment,
+  index,
+  disabled,
+  onOpen,
+  onRemove,
+  openLabel,
+  removeLabel,
+}: PluginResourceAttachmentPillProps) {
+  const Icon = resolvePluginIcon(attachment.sourceIcon);
+  const handleOpen = useCallback(() => onOpen(attachment), [attachment, onOpen]);
+  const handleRemove = useCallback(() => onRemove(index), [index, onRemove]);
+  const icon = useMemo(
+    () => <ThemedResourceIcon Icon={Icon} uniProps={iconColorMapping} />,
+    [Icon],
+  );
+  return (
+    <AttachmentPill
+      testID="composer-plugin-resource-attachment-pill"
+      onOpen={handleOpen}
+      onRemove={handleRemove}
+      openAccessibilityLabel={openLabel(attachment.sourceTitle, attachment.item.identifier)}
+      removeAccessibilityLabel={removeLabel(attachment.sourceTitle, attachment.item.identifier)}
+      disabled={disabled}
+    >
+      <AttachmentLabel
+        icon={icon}
+        title={attachment.item.title}
+        subtitle={`${attachment.sourceTitle} ${attachment.item.identifier}`}
+      />
+    </AttachmentPill>
+  );
+}

packages/app/src/plugins/catalog-sync.test.tsx

@@ -0,0 +1,91 @@
+/**
+ * @vitest-environment jsdom
+ */
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+
+const connection = vi.hoisted(() => ({ connected: true, supported: true }));
+
+vi.mock("@/runtime/host-runtime", () => ({
+  useHostRuntimeIsConnected: () => connection.connected,
+}));
+
+vi.mock("@/runtime/host-features", () => ({
+  useHostFeature: () => connection.supported,
+}));
+
+import { PluginCatalogSync } from "./catalog-sync";
+import { pluginRegistry } from "./registry";
+
+function bundle(): string {
+  return `(function() { return { default: function(plugin) {
+    plugin.addSurface("main", function() { return null; });
+    return function() { globalThis.__catalogSyncCleanups = (globalThis.__catalogSyncCleanups || 0) + 1; };
+  } }; })`;
+}
+
+const unsubscribe = vi.fn();
+const catalogClient = {
+  getPluginCatalog: vi.fn(async () => [{ id: "example", clientBundle: bundle() }]),
+  on: vi.fn(() => unsubscribe),
+} as unknown as DaemonClient;
+
+describe("PluginCatalogSync", () => {
+  let container: HTMLElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.stubGlobal("React", React);
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    connection.connected = true;
+    connection.supported = true;
+    unsubscribe.mockReset();
+    vi.mocked(catalogClient.getPluginCatalog).mockClear();
+    vi.mocked(catalogClient.on).mockClear();
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    pluginRegistry.removeHost("host-a");
+    container.remove();
+    Reflect.deleteProperty(globalThis, "__catalogSyncCleanups");
+    vi.unstubAllGlobals();
+  });
+
+  async function renderSync(): Promise<void> {
+    await act(async () => {
+      root.render(<PluginCatalogSync serverId="host-a" client={catalogClient} />);
+      await Promise.resolve();
+    });
+  }
+
+  it("tears down through disconnect and unmount boundaries exactly once each", async () => {
+    await renderSync();
+    const first = pluginRegistry.getSnapshot()[0];
+    expect(first?.id).toBe("example");
+    first?.queryClient.setQueryData(["owned"], "state");
+
+    connection.connected = false;
+    await renderSync();
+
+    expect(Reflect.get(globalThis, "__catalogSyncCleanups")).toBe(1);
+    expect(first?.queryClient.getQueryCache().getAll()).toEqual([]);
+    expect(pluginRegistry.getSnapshot()).toEqual([]);
+
+    connection.connected = true;
+    await renderSync();
+    expect(pluginRegistry.getSnapshot()).toHaveLength(1);
+
+    act(() => root.unmount());
+    root = createRoot(container);
+
+    expect(Reflect.get(globalThis, "__catalogSyncCleanups")).toBe(2);
+    expect(pluginRegistry.getSnapshot()).toEqual([]);
+    expect(unsubscribe).toHaveBeenCalledTimes(2);
+  });
+});

packages/app/src/plugins/catalog-sync.tsx

@@ -0,0 +1,62 @@
+import { useEffect } from "react";
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import { useHostFeature } from "@/runtime/host-features";
+import { useHostRuntimeIsConnected } from "@/runtime/host-runtime";
+import { pluginRegistry } from "./registry";
+
+export function PluginCatalogSync({
+  serverId,
+  client,
+}: {
+  serverId: string;
+  client: DaemonClient;
+}) {
+  const connected = useHostRuntimeIsConnected(serverId);
+  const supported = useHostFeature(serverId, "plugins");
+
+  useEffect(() => {
+    let cancelled = false;
+    let refreshQueue = Promise.resolve();
+    if (!supported) {
+      pluginRegistry.removeHost(serverId);
+      return;
+    }
+    if (!connected) {
+      pluginRegistry.removeHost(serverId);
+      return;
+    }
+    const refresh = (replacePluginId?: string) => {
+      refreshQueue = refreshQueue.then(() =>
+        client
+          .getPluginCatalog()
+          .then((catalog) => {
+            if (!cancelled) {
+              pluginRegistry.installCatalog(serverId, catalog, { replacePluginId });
+            }
+            return undefined;
+          })
+          .catch((error) => {
+            if (!cancelled) {
+              console.warn(`[Plugins] Failed to load catalog for ${serverId}`, error);
+            }
+            return undefined;
+          }),
+      );
+      return refreshQueue;
+    };
+    void refresh();
+    const unsubscribe = client.on("status", (message) => {
+      if (message.payload.status === "plugin_catalog_changed") {
+        const pluginId = message.payload.pluginId;
+        if (typeof pluginId === "string") void refresh(pluginId);
+      }
+    });
+    return () => {
+      cancelled = true;
+      unsubscribe();
+    };
+  }, [client, connected, serverId, supported]);
+
+  useEffect(() => () => pluginRegistry.removeHost(serverId), [serverId]);
+  return null;
+}

packages/app/src/plugins/evaluate.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from "vitest";
+import { evaluatePluginClientBundle } from "./evaluate";
+
+function bundle(body: string): string {
+  return `(function() {
+    const module = { exports: {} };
+    module.exports.default = function(plugin) { ${body}; return function() {}; };
+    return module.exports;
+  })`;
+}
+
+describe("evaluatePluginClientBundle", () => {
+  it("collects a surface and its sidebar placement", () => {
+    const plugin = evaluatePluginClientBundle(
+      "example",
+      bundle(`
+        function Surface() { return null; }
+        plugin.addSurface("main", Surface);
+        plugin.addSidebarItem({ id: "main", title: "Example", icon: "Blocks", surface: "main" });
+      `),
+    );
+
+    expect(plugin.id).toBe("example");
+    expect(plugin.surfaces.map((surface) => surface.id)).toEqual(["main"]);
+    expect(plugin.sidebarItems).toEqual([
+      { id: "main", title: "Example", icon: "Blocks", surface: "main" },
+    ]);
+  });
+
+  it("collects a declarative attachment source", () => {
+    const plugin = evaluatePluginClientBundle(
+      "linear",
+      bundle(`
+        plugin.addAttachmentSource({
+          id: "issues",
+          title: "Linear issue",
+          icon: "CircleDot",
+          pickerTitle: "Attach Linear issue",
+          searchPlaceholder: "Search by identifier or title",
+          search: { name: "issues.search", input: {}, output: {} },
+        });
+      `),
+    );
+
+    expect(plugin.attachmentSources).toEqual([
+      {
+        id: "issues",
+        title: "Linear issue",
+        icon: "CircleDot",
+        pickerTitle: "Attach Linear issue",
+        searchPlaceholder: "Search by identifier or title",
+        search: { name: "issues.search", input: {}, output: {} },
+      },
+    ]);
+  });
+
+  it("rejects duplicate attachment source ids", () => {
+    expect(() =>
+      evaluatePluginClientBundle(
+        "linear",
+        bundle(`
+          const source = {
+            id: "issues",
+            title: "Linear issue",
+            icon: "CircleDot",
+            pickerTitle: "Attach Linear issue",
+            searchPlaceholder: "Search",
+            search: { name: "issues.search", input: {}, output: {} },
+          };
+          plugin.addAttachmentSource(source);
+          plugin.addAttachmentSource(source);
+        `),
+      ),
+    ).toThrow("Duplicate attachment source: issues");
+  });
+
+  it("rejects a sidebar placement whose surface does not exist", () => {
+    expect(() =>
+      evaluatePluginClientBundle(
+        "example",
+        bundle(`
+          plugin.addSidebarItem({ id: "main", title: "Example", icon: "Blocks", surface: "missing" });
+        `),
+      ),
+    ).toThrow("references missing surface missing");
+  });
+
+  it("rejects a bundle without a default contribution function", () => {
+    expect(() => evaluatePluginClientBundle("example", `(function() { return {}; })`)).toThrow(
+      "must default export a function",
+    );
+  });
+
+  it("requires a cleanup function", () => {
+    expect(() =>
+      evaluatePluginClientBundle("example", `(function() { return { default: function() {} }; })`),
+    ).toThrow("must return a cleanup function");
+  });
+
+  it("does not publish partial contributions when setup fails", () => {
+    expect(() =>
+      evaluatePluginClientBundle(
+        "example",
+        `(function() { return { default: function(plugin) {
+          plugin.addSurface("main", function() { return null; });
+          throw new Error("setup exploded");
+        } }; })`,
+      ),
+    ).toThrow("setup exploded");
+  });
+});

packages/app/src/plugins/evaluate.ts

@@ -0,0 +1,135 @@
+import * as React from "react";
+import * as ReactJsxRuntime from "react/jsx-runtime";
+import * as ReactNative from "react-native";
+// eslint-disable-next-line no-restricted-imports -- plugin bundles receive TanStack's real runtime, not Paseo's query wrappers.
+import * as ReactQuery from "@tanstack/react-query";
+import * as Zod from "zod";
+import {
+  defineAttachmentSource,
+  defineRpc,
+  type PluginAttachmentSourceContribution,
+  type PluginSidebarContribution,
+  type PluginSurfaceProps,
+  useRpc,
+} from "@paseo/plugin";
+import { createPluginContext, type PluginRegistrationCollector } from "@paseo/plugin/host";
+import type { EvaluatedPlugin } from "./types";
+import type { ComponentType } from "react";
+import { resolvePluginIcon } from "./icons";
+
+const CONTRIBUTION_ID = /^[a-z][a-z0-9-]*$/;
+
+function requireId(value: string, label: string): string {
+  const id = value.trim();
+  if (!CONTRIBUTION_ID.test(id)) throw new Error(`Invalid ${label}: ${value}`);
+  return id;
+}
+
+export function evaluatePluginClientBundle(id: string, bundle: string): EvaluatedPlugin {
+  const collector: PluginRegistrationCollector = {
+    surfaces: [],
+    sidebarItems: [],
+    attachmentSources: [],
+  };
+  const surfaceIds = new Set<string>();
+  const sidebarItemIds = new Set<string>();
+  const attachmentSourceIds = new Set<string>();
+  const pluginContext = createPluginContext({
+    addSurface(surfaceId: string, Component: ComponentType<PluginSurfaceProps>) {
+      const normalizedId = requireId(surfaceId, "surface id");
+      if (surfaceIds.has(normalizedId)) throw new Error(`Duplicate surface: ${normalizedId}`);
+      if (typeof Component !== "function")
+        throw new Error(`Surface ${normalizedId} is not a component`);
+      surfaceIds.add(normalizedId);
+      collector.surfaces.push({ id: normalizedId, Component });
+    },
+    addSidebarItem(contribution: PluginSidebarContribution) {
+      const normalizedId = requireId(contribution.id, "sidebar item id");
+      if (sidebarItemIds.has(normalizedId))
+        throw new Error(`Duplicate sidebar item: ${normalizedId}`);
+      if (!contribution.title.trim()) throw new Error(`Sidebar item ${normalizedId} has no title`);
+      if (!contribution.icon.trim()) throw new Error(`Sidebar item ${normalizedId} has no icon`);
+      resolvePluginIcon(contribution.icon.trim());
+      sidebarItemIds.add(normalizedId);
+      collector.sidebarItems.push({
+        id: normalizedId,
+        title: contribution.title.trim(),
+        icon: contribution.icon.trim(),
+        surface: requireId(contribution.surface, "sidebar surface id"),
+      });
+    },
+    addAttachmentSource(contribution: PluginAttachmentSourceContribution) {
+      const normalizedId = requireId(contribution.id, "attachment source id");
+      if (attachmentSourceIds.has(normalizedId)) {
+        throw new Error(`Duplicate attachment source: ${normalizedId}`);
+      }
+      const title = contribution.title.trim();
+      const icon = contribution.icon.trim();
+      const pickerTitle = contribution.pickerTitle.trim();
+      const searchPlaceholder = contribution.searchPlaceholder.trim();
+      const method = contribution.search.name.trim();
+      if (!title) throw new Error(`Attachment source ${normalizedId} has no title`);
+      if (!icon) throw new Error(`Attachment source ${normalizedId} has no icon`);
+      if (!pickerTitle) throw new Error(`Attachment source ${normalizedId} has no picker title`);
+      if (!searchPlaceholder) {
+        throw new Error(`Attachment source ${normalizedId} has no search placeholder`);
+      }
+      if (!method) throw new Error(`Attachment source ${normalizedId} has no search RPC`);
+      resolvePluginIcon(icon);
+      attachmentSourceIds.add(normalizedId);
+      collector.attachmentSources.push({
+        id: normalizedId,
+        title,
+        icon,
+        pickerTitle,
+        searchPlaceholder,
+        search: { ...contribution.search, name: method },
+      });
+    },
+  });
+  const runtimeRequire = (name: string): unknown => {
+    if (name === "react") return React;
+    if (name === "react/jsx-runtime") return ReactJsxRuntime;
+    if (name === "react-native") return ReactNative;
+    if (name === "@paseo/plugin") return { defineAttachmentSource, defineRpc, useRpc };
+    if (name === "@tanstack/react-query") return ReactQuery;
+    if (name === "zod") return Zod;
+    throw new Error(`Module "${name}" is not available in plugin client code`);
+  };
+  const evaluate: (source: string) => unknown = globalThis.eval;
+  const factory = evaluate(bundle);
+  if (typeof factory !== "function")
+    throw new Error(`Plugin ${id} client bundle is not executable`);
+  const exports = factory(runtimeRequire);
+  const setup =
+    exports !== null && typeof exports === "object" ? Reflect.get(exports, "default") : undefined;
+  if (typeof setup !== "function") {
+    throw new Error(`Plugin ${id} must default export a function`);
+  }
+  const cleanup = setup(pluginContext);
+  if (typeof cleanup !== "function") {
+    throw new Error(`Plugin ${id} contribution must return a cleanup function`);
+  }
+
+  try {
+    for (const item of collector.sidebarItems) {
+      if (!surfaceIds.has(item.surface)) {
+        throw new Error(`Sidebar item ${item.id} references missing surface ${item.surface}`);
+      }
+    }
+  } catch (error) {
+    try {
+      cleanup();
+    } catch (cleanupError) {
+      console.warn(`[Plugins] Cleanup failed after setup error for ${id}`, cleanupError);
+    }
+    throw error;
+  }
+  return {
+    id,
+    cleanup,
+    surfaces: collector.surfaces,
+    sidebarItems: collector.sidebarItems,
+    attachmentSources: collector.attachmentSources,
+  };
+}

packages/app/src/plugins/icons.ts

@@ -0,0 +1,11 @@
+import * as LucideIcons from "lucide-react-native";
+import type { LucideIcon } from "lucide-react-native";
+
+export function resolvePluginIcon(name: string): LucideIcon {
+  const candidate = Reflect.get(LucideIcons, name);
+  const isComponent =
+    typeof candidate === "function" ||
+    (typeof candidate === "object" && candidate !== null && "$$typeof" in candidate);
+  if (!isComponent) throw new Error(`Unknown Lucide icon: ${name}`);
+  return candidate as LucideIcon;
+}

packages/app/src/plugins/index.ts

@@ -0,0 +1,5 @@
+export { PluginCatalogSync } from "./catalog-sync";
+export { PluginSidebarItems } from "./sidebar-items";
+export { PluginSurfaceScreen } from "./surface-screen";
+export { usePluginAttachmentPicker } from "./attachments/picker";
+export { PluginResourceAttachmentPill } from "./attachments/pill";

packages/app/src/plugins/registry.test.ts

@@ -0,0 +1,140 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { pluginRegistry } from "./registry";
+
+function bundle(marker: string): string {
+  return `(function() {
+    const module = { exports: {} };
+    module.exports.default = function(plugin) {
+      function Surface() { return ${JSON.stringify(marker)}; }
+      plugin.addSurface("main", Surface);
+      plugin.addSidebarItem({ id: "main", title: "Example", icon: "Blocks", surface: "main" });
+      return function() { globalThis.__pluginCleanups = (globalThis.__pluginCleanups || 0) + 1; };
+    };
+    return module.exports;
+  })`;
+}
+
+afterEach(() => {
+  pluginRegistry.removeHost("host-a");
+  pluginRegistry.removeHost("host-b");
+  Reflect.deleteProperty(globalThis, "__pluginCleanups");
+});
+
+describe("PluginRegistry", () => {
+  it("preserves a plugin query cache when the same bundle reconnects", () => {
+    const clientBundle = bundle("one");
+    pluginRegistry.installCatalog("host-a", [{ id: "example", clientBundle }]);
+    const first = pluginRegistry.getSnapshot()[0];
+    first?.queryClient.setQueryData(["counter"], 3);
+
+    pluginRegistry.installCatalog("host-a", [{ id: "example", clientBundle }]);
+
+    const second = pluginRegistry.getSnapshot()[0];
+    expect(second).toBe(first);
+    expect(second?.queryClient).toBe(first?.queryClient);
+    expect(second?.queryClient.getQueryData(["counter"])).toBe(3);
+  });
+
+  it("replaces the query cache when the plugin bundle changes", () => {
+    pluginRegistry.installCatalog("host-a", [{ id: "example", clientBundle: bundle("one") }]);
+    const first = pluginRegistry.getSnapshot()[0];
+    first?.queryClient.setQueryData(["counter"], 3);
+
+    pluginRegistry.installCatalog("host-a", [{ id: "example", clientBundle: bundle("two") }]);
+
+    const second = pluginRegistry.getSnapshot()[0];
+    expect(second?.queryClient).not.toBe(first?.queryClient);
+    expect(second?.queryClient.getQueryData(["counter"])).toBeUndefined();
+    expect(first?.queryClient.getQueryData(["counter"])).toBeUndefined();
+    expect(Reflect.get(globalThis, "__pluginCleanups")).toBe(1);
+  });
+
+  it("isolates query caches between hosts", () => {
+    const clientBundle = bundle("same");
+    pluginRegistry.installCatalog("host-a", [{ id: "example", clientBundle }]);
+    pluginRegistry.installCatalog("host-b", [{ id: "example", clientBundle }]);
+    const [hostA, hostB] = pluginRegistry.getSnapshot();
+    hostA?.queryClient.setQueryData(["counter"], 3);
+
+    expect(hostB?.queryClient.getQueryData(["counter"])).toBeUndefined();
+  });
+
+  it("cleans up the old installation before evaluating its replacement", () => {
+    pluginRegistry.installCatalog("host-a", [{ id: "example", clientBundle: bundle("one") }]);
+    const replacement = `(function() { return { default: function(plugin) {
+      globalThis.__cleanupSeenByReplacement = globalThis.__pluginCleanups || 0;
+      plugin.addSurface("main", function() { return null; });
+      return function() {};
+    } }; })`;
+
+    pluginRegistry.installCatalog("host-a", [{ id: "example", clientBundle: replacement }]);
+
+    expect(Reflect.get(globalThis, "__cleanupSeenByReplacement")).toBe(1);
+    Reflect.deleteProperty(globalThis, "__cleanupSeenByReplacement");
+  });
+
+  it("replaces an unchanged bundle when explicit reload names the plugin", () => {
+    const clientBundle = bundle("same");
+    pluginRegistry.installCatalog("host-a", [{ id: "example", clientBundle }]);
+    const first = pluginRegistry.getSnapshot()[0];
+    first?.queryClient.setQueryData(["attachment-search"], "cached");
+
+    pluginRegistry.installCatalog("host-a", [{ id: "example", clientBundle }], {
+      replacePluginId: "example",
+    });
+
+    const second = pluginRegistry.getSnapshot()[0];
+    expect(second).not.toBe(first);
+    expect(first?.queryClient.getQueryData(["attachment-search"])).toBeUndefined();
+    expect(Reflect.get(globalThis, "__pluginCleanups")).toBe(1);
+  });
+
+  it.each(["disable", "remove"])("cleans a catalog entry exactly once on %s", () => {
+    pluginRegistry.installCatalog("host-a", [{ id: "example", clientBundle: bundle("one") }]);
+
+    pluginRegistry.installCatalog("host-a", []);
+    pluginRegistry.installCatalog("host-a", []);
+
+    expect(Reflect.get(globalThis, "__pluginCleanups")).toBe(1);
+    expect(pluginRegistry.getSnapshot()).toEqual([]);
+  });
+
+  it("cancels an in-flight attachment query during teardown", async () => {
+    pluginRegistry.installCatalog("host-a", [{ id: "example", clientBundle: bundle("one") }]);
+    const plugin = pluginRegistry.getSnapshot()[0];
+    if (!plugin) throw new Error("Expected installed plugin");
+    let observeAbort: () => void = () => undefined;
+    const aborted = new Promise<void>((resolve) => {
+      observeAbort = resolve;
+    });
+    void plugin.queryClient
+      .fetchQuery({
+        queryKey: ["plugin-attachment-search", "example"],
+        queryFn: ({ signal }) =>
+          new Promise<never>((_resolve, reject) => {
+            signal.addEventListener("abort", () => {
+              observeAbort();
+              reject(new Error("aborted"));
+            });
+          }),
+      })
+      .catch(() => undefined);
+
+    pluginRegistry.installCatalog("host-a", []);
+
+    await aborted;
+    expect(plugin.queryClient.getQueryCache().getAll()).toEqual([]);
+  });
+
+  it("continues host teardown when cleanup throws", () => {
+    const throwing = `(function() { return { default: function(plugin) {
+      plugin.addSurface("main", function() { return null; });
+      return function() { throw new Error("cleanup exploded"); };
+    } }; })`;
+    pluginRegistry.installCatalog("host-a", [{ id: "example", clientBundle: throwing }]);
+    pluginRegistry.getSnapshot()[0]?.queryClient.setQueryData(["counter"], 3);
+
+    expect(() => pluginRegistry.removeHost("host-a")).not.toThrow();
+    expect(pluginRegistry.getSnapshot()).toEqual([]);
+  });
+});

packages/app/src/plugins/registry.ts

@@ -0,0 +1,139 @@
+import { useSyncExternalStore } from "react";
+import { QueryClient } from "@tanstack/react-query";
+import { evaluatePluginClientBundle } from "./evaluate";
+import type { InstalledPlugin } from "./types";
+
+interface CatalogPlugin {
+  id: string;
+  clientBundle: string;
+}
+
+class PluginRegistry {
+  private readonly byHost = new Map<string, InstalledPlugin[]>();
+  private readonly listeners = new Set<() => void>();
+  private snapshot: InstalledPlugin[] = [];
+  private readonly disposed = new WeakSet<InstalledPlugin>();
+  private readonly evaluationErrors = new Map<string, string>();
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  getSnapshot = (): InstalledPlugin[] => this.snapshot;
+
+  getEvaluationError(serverId: string, pluginId: string): string | undefined {
+    return this.evaluationErrors.get(`${serverId}/${pluginId}`);
+  }
+
+  installCatalog(
+    serverId: string,
+    catalog: CatalogPlugin[],
+    options: { replacePluginId?: string } = {},
+  ): void {
+    const previous = this.byHost.get(serverId) ?? [];
+    const preserved = catalog.flatMap((entry) => {
+      const existing = previous.find(
+        (plugin) =>
+          plugin.id !== options.replacePluginId &&
+          plugin.id === entry.id &&
+          plugin.clientBundle === entry.clientBundle,
+      );
+      return existing ? [existing] : [];
+    });
+    const removed = previous.filter((plugin) => !preserved.includes(plugin));
+    if (removed.length > 0) {
+      this.byHost.set(serverId, preserved);
+      this.publish();
+      for (const plugin of removed) this.dispose(plugin);
+    }
+    const installed = catalog.flatMap((entry) => {
+      const key = `${serverId}/${entry.id}`;
+      try {
+        const existing = preserved.find(
+          (plugin) => plugin.id === entry.id && plugin.clientBundle === entry.clientBundle,
+        );
+        if (existing) {
+          this.evaluationErrors.delete(key);
+          return [existing];
+        }
+        const queryClient = new QueryClient();
+        const evaluated = [
+          {
+            ...evaluatePluginClientBundle(entry.id, entry.clientBundle),
+            serverId,
+            clientBundle: entry.clientBundle,
+            queryClient,
+          },
+        ];
+        this.evaluationErrors.delete(key);
+        return evaluated;
+      } catch (error) {
+        this.evaluationErrors.set(key, error instanceof Error ? error.message : String(error));
+        console.warn(`[Plugins] Failed to evaluate ${serverId}/${entry.id}`, error);
+        return [];
+      }
+    });
+    const configuredIds = new Set(catalog.map((entry) => entry.id));
+    for (const key of this.evaluationErrors.keys()) {
+      if (key.startsWith(`${serverId}/`) && !configuredIds.has(key.slice(serverId.length + 1))) {
+        this.evaluationErrors.delete(key);
+      }
+    }
+    this.byHost.set(serverId, installed);
+    this.publish();
+  }
+
+  removeHost(serverId: string): void {
+    const installed = this.byHost.get(serverId);
+    if (!installed) return;
+    for (const plugin of installed) this.dispose(plugin);
+    for (const key of this.evaluationErrors.keys()) {
+      if (key.startsWith(`${serverId}/`)) this.evaluationErrors.delete(key);
+    }
+    this.byHost.delete(serverId);
+    this.publish();
+  }
+
+  private dispose(plugin: InstalledPlugin): void {
+    if (this.disposed.has(plugin)) return;
+    this.disposed.add(plugin);
+    plugin.queryClient.clear();
+    try {
+      plugin.cleanup();
+    } catch (error) {
+      console.warn(`[Plugins] Cleanup failed for ${plugin.serverId}/${plugin.id}`, error);
+    }
+  }
+
+  private publish(): void {
+    this.snapshot = [...this.byHost.values()]
+      .flat()
+      .sort((left, right) =>
+        `${left.serverId}/${left.id}`.localeCompare(`${right.serverId}/${right.id}`),
+      );
+    for (const listener of this.listeners) listener();
+  }
+}
+
+export const pluginRegistry = new PluginRegistry();
+
+export function useInstalledPlugins(): InstalledPlugin[] {
+  return useSyncExternalStore(
+    pluginRegistry.subscribe,
+    pluginRegistry.getSnapshot,
+    pluginRegistry.getSnapshot,
+  );
+}
+
+export function useInstalledPlugin(serverId: string, pluginId: string): InstalledPlugin | null {
+  return (
+    useInstalledPlugins().find(
+      (plugin) => plugin.serverId === serverId && plugin.id === pluginId,
+    ) ?? null
+  );
+}
+
+export function usePluginInstallations(pluginId: string): InstalledPlugin[] {
+  return useInstalledPlugins().filter((plugin) => plugin.id === pluginId);
+}

packages/app/src/plugins/routes.ts

@@ -0,0 +1,17 @@
+export function buildPluginSurfaceRoute(
+  serverId: string,
+  pluginId: string,
+  contributionId: string,
+): `/h/${string}/plugin/${string}/${string}` {
+  return `/h/${encodeURIComponent(serverId)}/plugin/${encodeURIComponent(pluginId)}/${encodeURIComponent(contributionId)}`;
+}
+
+export function hostIdFromPathname(pathname: string): string | null {
+  const encoded = /^\/h\/([^/]+)/.exec(pathname)?.[1];
+  if (!encoded) return null;
+  try {
+    return decodeURIComponent(encoded);
+  } catch {
+    return null;
+  }
+}

packages/app/src/plugins/sidebar-groups.test.ts

@@ -0,0 +1,45 @@
+import { QueryClient } from "@tanstack/react-query";
+import { describe, expect, it } from "vitest";
+import type { InstalledPlugin } from "./types";
+import { groupPluginSidebarContributions } from "./sidebar-groups";
+
+function installed(serverId: string, contributionId = "main"): InstalledPlugin {
+  return {
+    id: "example",
+    cleanup: () => undefined,
+    serverId,
+    clientBundle: serverId,
+    queryClient: new QueryClient(),
+    surfaces: [{ id: "surface", Component: () => null }],
+    sidebarItems: [
+      {
+        id: contributionId,
+        title: "Example",
+        icon: "Blocks",
+        surface: "surface",
+      },
+    ],
+    attachmentSources: [],
+  };
+}
+
+describe("groupPluginSidebarContributions", () => {
+  it("coalesces the same plugin contribution across hosts", () => {
+    const groups = groupPluginSidebarContributions([installed("host-a"), installed("host-b")]);
+
+    expect(groups).toHaveLength(1);
+    expect(groups[0]?.targets.map((target) => target.plugin.serverId)).toEqual([
+      "host-a",
+      "host-b",
+    ]);
+  });
+
+  it("keeps different contribution ids separate", () => {
+    const groups = groupPluginSidebarContributions([
+      installed("host-a", "main"),
+      installed("host-b", "settings"),
+    ]);
+
+    expect(groups.map((group) => group.key)).toEqual(["example/main", "example/settings"]);
+  });
+});

packages/app/src/plugins/sidebar-groups.ts

@@ -0,0 +1,48 @@
+import type { InstalledPlugin, PluginSidebarContribution } from "./types";
+
+const preferredHosts = new Map<string, string>();
+
+export interface PluginSidebarTarget {
+  plugin: InstalledPlugin;
+  item: PluginSidebarContribution;
+}
+
+export interface PluginSidebarGroup {
+  key: string;
+  pluginId: string;
+  contributionId: string;
+  title: string;
+  icon: string;
+  targets: PluginSidebarTarget[];
+}
+
+export function groupPluginSidebarContributions(plugins: InstalledPlugin[]): PluginSidebarGroup[] {
+  const groups = new Map<string, PluginSidebarGroup>();
+  for (const plugin of plugins) {
+    for (const item of plugin.sidebarItems) {
+      const key = `${plugin.id}/${item.id}`;
+      const existing = groups.get(key);
+      if (existing) {
+        existing.targets.push({ plugin, item });
+      } else {
+        groups.set(key, {
+          key,
+          pluginId: plugin.id,
+          contributionId: item.id,
+          title: item.title,
+          icon: item.icon,
+          targets: [{ plugin, item }],
+        });
+      }
+    }
+  }
+  return [...groups.values()];
+}
+
+export function getPreferredPluginContributionHost(groupKey: string): string | null {
+  return preferredHosts.get(groupKey) ?? null;
+}
+
+export function rememberPluginContributionHost(groupKey: string, serverId: string): void {
+  preferredHosts.set(groupKey, serverId);
+}

packages/app/src/plugins/sidebar-items.tsx

@@ -0,0 +1,80 @@
+import { router, usePathname } from "expo-router";
+import { useCallback, useMemo } from "react";
+import { SidebarHeaderRow } from "@/components/sidebar/sidebar-header-row";
+import { resolvePluginIcon } from "./icons";
+import { useInstalledPlugins } from "./registry";
+import { buildPluginSurfaceRoute, hostIdFromPathname } from "./routes";
+import {
+  groupPluginSidebarContributions,
+  getPreferredPluginContributionHost,
+  rememberPluginContributionHost,
+  type PluginSidebarGroup,
+  type PluginSidebarTarget,
+} from "./sidebar-groups";
+
+function selectTarget(
+  group: PluginSidebarGroup,
+  currentHostId: string | null,
+): PluginSidebarTarget {
+  const current = group.targets.find((target) => target.plugin.serverId === currentHostId);
+  if (current) return current;
+  const rememberedHostId = getPreferredPluginContributionHost(group.key);
+  const remembered = group.targets.find((target) => target.plugin.serverId === rememberedHostId);
+  return remembered ?? group.targets[0];
+}
+
+export function PluginSidebarItems({ onBeforeNavigate }: { onBeforeNavigate?: () => void }) {
+  const plugins = useInstalledPlugins();
+  const pathname = usePathname();
+  const groups = useMemo(() => groupPluginSidebarContributions(plugins), [plugins]);
+  const currentHostId = hostIdFromPathname(pathname);
+
+  return groups.map((group) => (
+    <PluginSidebarItemRow
+      key={group.key}
+      group={group}
+      currentHostId={currentHostId}
+      pathname={pathname}
+      onBeforeNavigate={onBeforeNavigate}
+    />
+  ));
+}
+
+function PluginSidebarItemRow({
+  group,
+  currentHostId,
+  pathname,
+  onBeforeNavigate,
+}: {
+  group: PluginSidebarGroup;
+  currentHostId: string | null;
+  pathname: string;
+  onBeforeNavigate?: () => void;
+}) {
+  const target = selectTarget(group, currentHostId);
+  const route = buildPluginSurfaceRoute(
+    target.plugin.serverId,
+    group.pluginId,
+    group.contributionId,
+  );
+  const isActive = group.targets.some(
+    (candidate) =>
+      pathname ===
+      buildPluginSurfaceRoute(candidate.plugin.serverId, group.pluginId, group.contributionId),
+  );
+  const navigate = useCallback(() => {
+    rememberPluginContributionHost(group.key, target.plugin.serverId);
+    onBeforeNavigate?.();
+    router.push(route);
+  }, [group.key, onBeforeNavigate, route, target.plugin.serverId]);
+  return (
+    <SidebarHeaderRow
+      icon={resolvePluginIcon(group.icon)}
+      label={group.title}
+      onPress={navigate}
+      isActive={isActive}
+      testID={`plugin-sidebar-${group.pluginId}-${group.contributionId}`}
+      variant="compact"
+    />
+  );
+}

packages/app/src/plugins/surface-error-boundary.test.tsx

@@ -0,0 +1,79 @@
+/**
+ * @vitest-environment jsdom
+ */
+import React, { act, useEffect, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Text } from "react-native";
+import { SurfaceErrorBoundary } from "./surface-error-boundary";
+
+let oldSurfaceCleanups = 0;
+function FailingSurface() {
+  const [failed, setFailed] = useState(false);
+  useEffect(() => {
+    setFailed(true);
+    return () => {
+      oldSurfaceCleanups += 1;
+    };
+  }, []);
+  if (failed) throw new Error("old render exploded");
+  return <Text>Old surface mounted</Text>;
+}
+function CorrectedSurface() {
+  return <Text>Corrected surface</Text>;
+}
+const oldInstallation = {};
+const correctedInstallation = {};
+
+describe("SurfaceErrorBoundary", () => {
+  const roots: Array<ReturnType<typeof createRoot>> = [];
+  const containers: HTMLElement[] = [];
+
+  afterEach(() => {
+    for (const root of roots.splice(0)) act(() => root.unmount());
+    for (const container of containers.splice(0)) container.remove();
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+    oldSurfaceCleanups = 0;
+  });
+
+  it("recovers a mounted failed route when its installation and surface are replaced", async () => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+    const container = document.createElement("div");
+    containers.push(container);
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    roots.push(root);
+
+    await act(async () => {
+      root.render(
+        <SurfaceErrorBoundary
+          key="host/plugin/surface"
+          installation={oldInstallation}
+          Surface={FailingSurface}
+        >
+          <FailingSurface />
+        </SurfaceErrorBoundary>,
+      );
+    });
+    expect(container.textContent).toBe("Plugin failed: old render exploded");
+    expect(oldSurfaceCleanups).toBe(1);
+
+    await act(async () => {
+      root.render(
+        <SurfaceErrorBoundary
+          key="host/plugin/surface"
+          installation={correctedInstallation}
+          Surface={CorrectedSurface}
+        >
+          <CorrectedSurface />
+        </SurfaceErrorBoundary>,
+      );
+    });
+
+    expect(container.textContent).toBe("Corrected surface");
+    expect(oldSurfaceCleanups).toBe(1);
+  });
+});

packages/app/src/plugins/surface-error-boundary.tsx

@@ -0,0 +1,51 @@
+import React, { Component, type ErrorInfo, type ReactNode } from "react";
+import { Text } from "react-native";
+import { StyleSheet } from "react-native-unistyles";
+
+interface SurfaceErrorBoundaryProps {
+  children: ReactNode;
+  installation: object;
+  Surface: unknown;
+}
+
+interface SurfaceErrorBoundaryState {
+  error: string | null;
+}
+
+export class SurfaceErrorBoundary extends Component<
+  SurfaceErrorBoundaryProps,
+  SurfaceErrorBoundaryState
+> {
+  state: SurfaceErrorBoundaryState = { error: null };
+
+  static getDerivedStateFromError(error: unknown): SurfaceErrorBoundaryState {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo): void {
+    console.warn("[Plugins] Surface render failed", error, info.componentStack);
+  }
+
+  componentDidUpdate(previous: SurfaceErrorBoundaryProps): void {
+    if (
+      this.state.error &&
+      (previous.installation !== this.props.installation || previous.Surface !== this.props.Surface)
+    ) {
+      this.setState({ error: null });
+    }
+  }
+
+  render() {
+    if (this.state.error) {
+      return <Text style={styles.errorText}>Plugin failed: {this.state.error}</Text>;
+    }
+    return this.props.children;
+  }
+}
+
+const styles = StyleSheet.create((theme) => ({
+  errorText: {
+    color: theme.colors.statusDanger,
+    padding: theme.spacing[4],
+  },
+}));

packages/app/src/plugins/surface-screen.tsx

@@ -0,0 +1,270 @@
+import { router, useLocalSearchParams } from "expo-router";
+import { QueryClientProvider } from "@tanstack/react-query";
+import type { PluginSurfaceProps } from "@paseo/plugin";
+import { PluginRpcProvider } from "@paseo/plugin/host";
+import { ChevronDown, X } from "lucide-react-native";
+import { useCallback, useMemo, useRef, useState, type ComponentType } from "react";
+import { Platform, Pressable, Text, View } from "react-native";
+import { StyleSheet, withUnistyles } from "react-native-unistyles";
+import { HeaderIconBadge } from "@/components/headers/header-icon-badge";
+import { HeaderToggleButton } from "@/components/headers/header-toggle-button";
+import { ScreenHeader } from "@/components/headers/screen-header";
+import { ScreenTitle } from "@/components/headers/screen-title";
+import { HostPicker } from "@/components/hosts/host-picker";
+import { useIsCompactFormFactor } from "@/constants/layout";
+import { useHostRuntimeClient, useHosts } from "@/runtime/host-runtime";
+import type { Theme } from "@/styles/theme";
+import type { ShortcutKey } from "@/utils/format-shortcut";
+import { resolvePluginIcon } from "./icons";
+import { useInstalledPlugin, usePluginInstallations } from "./registry";
+import { buildPluginSurfaceRoute } from "./routes";
+import { rememberPluginContributionHost } from "./sidebar-groups";
+import { SurfaceErrorBoundary } from "./surface-error-boundary";
+
+const EMPTY_SHORTCUT_KEYS: ShortcutKey[] = [];
+const EMPTY_THEME_DTO: Record<string, unknown> = {};
+const mutedColorMapping = (theme: Theme) => ({ color: theme.colors.foregroundMuted });
+const pluginThemeMapping = (theme: Theme) => ({
+  themeDto: JSON.parse(JSON.stringify(theme)) as Record<string, unknown>,
+});
+const ThemedX = withUnistyles(X);
+const ThemedChevronDown = withUnistyles(ChevronDown);
+
+function routeParam(value: string | string[] | undefined): string {
+  return typeof value === "string" ? value : "";
+}
+
+function PluginHeaderIcon({
+  Icon,
+  color = "",
+}: {
+  Icon: ReturnType<typeof resolvePluginIcon>;
+  color?: string;
+}) {
+  return <Icon size={16} color={color} />;
+}
+
+const ThemedPluginHeaderIcon = withUnistyles(PluginHeaderIcon);
+
+function SurfaceRenderer({
+  Surface,
+  invoke,
+  plugin,
+  layout,
+  host,
+  themeDto = EMPTY_THEME_DTO,
+}: {
+  Surface: ComponentType<PluginSurfaceProps>;
+  invoke(method: string, input: unknown): Promise<unknown>;
+  plugin: NonNullable<ReturnType<typeof useInstalledPlugin>>;
+  layout: PluginSurfaceProps["layout"];
+  host: PluginSurfaceProps["host"];
+  themeDto?: Record<string, unknown>;
+}) {
+  return (
+    <QueryClientProvider client={plugin.queryClient}>
+      <PluginRpcProvider invoke={invoke}>
+        <Surface theme={themeDto} host={host} layout={layout} />
+      </PluginRpcProvider>
+    </QueryClientProvider>
+  );
+}
+
+const ThemedSurfaceRenderer = withUnistyles(SurfaceRenderer);
+
+function resolvePlatform(): PluginSurfaceProps["layout"]["platform"] {
+  if (Platform.OS === "ios") return "ios";
+  if (Platform.OS === "android") return "android";
+  return "web";
+}
+
+function PluginHostSwitcher({
+  serverId,
+  pluginId,
+  contributionId,
+  serverIds,
+}: {
+  serverId: string;
+  pluginId: string;
+  contributionId: string;
+  serverIds: string[];
+}) {
+  const allHosts = useHosts();
+  const hosts = useMemo(
+    () => allHosts.filter((host) => serverIds.includes(host.serverId)),
+    [allHosts, serverIds],
+  );
+  const [open, setOpen] = useState(false);
+  const anchorRef = useRef<View | null>(null);
+  const selectedLabel = hosts.find((host) => host.serverId === serverId)?.label ?? serverId;
+  const selectHost = useCallback(
+    (nextServerId: string) => {
+      rememberPluginContributionHost(`${pluginId}/${contributionId}`, nextServerId);
+      router.replace(buildPluginSurfaceRoute(nextServerId, pluginId, contributionId));
+    },
+    [contributionId, pluginId],
+  );
+  const openPicker = useCallback(() => setOpen(true), []);
+  const show = serverIds.length > 1 && hosts.length > 1;
+  if (!show) return null;
+
+  return (
+    <HostPicker
+      hosts={hosts}
+      value={serverId}
+      onSelect={selectHost}
+      open={open}
+      onOpenChange={setOpen}
+      anchorRef={anchorRef}
+      title="Choose plugin host"
+      desktopPlacement="bottom-start"
+    >
+      <View ref={anchorRef} collapsable={false}>
+        <Pressable
+          accessibilityRole="button"
+          accessibilityLabel={`Plugin host: ${selectedLabel}`}
+          testID="plugin-host-switcher"
+          onPress={openPicker}
+          style={styles.hostSwitcher}
+        >
+          <Text numberOfLines={1} style={styles.hostSwitcherText}>
+            {selectedLabel}
+          </Text>
+          <ThemedChevronDown size={14} uniProps={mutedColorMapping} />
+        </Pressable>
+      </View>
+    </HostPicker>
+  );
+}
+
+export function PluginSurfaceScreen() {
+  const params = useLocalSearchParams<{
+    serverId?: string | string[];
+    pluginId?: string | string[];
+    surfaceId?: string | string[];
+  }>();
+  const serverId = routeParam(params.serverId);
+  const pluginId = routeParam(params.pluginId);
+  const contributionId = routeParam(params.surfaceId);
+  const plugin = useInstalledPlugin(serverId, pluginId);
+  const installations = usePluginInstallations(pluginId);
+  const hosts = useHosts();
+  const client = useHostRuntimeClient(serverId);
+  const compact = useIsCompactFormFactor();
+  const sidebarItem = plugin?.sidebarItems.find((entry) => entry.id === contributionId) ?? null;
+  const surface = plugin?.surfaces.find((entry) => entry.id === sidebarItem?.surface) ?? null;
+  const hostLabel = hosts.find((host) => host.serverId === serverId)?.label ?? serverId;
+  const contributionServerIds = useMemo(
+    () =>
+      installations
+        .filter((entry) => entry.sidebarItems.some((item) => item.id === contributionId))
+        .map((entry) => entry.serverId),
+    [contributionId, installations],
+  );
+  const title = sidebarItem?.title ?? (pluginId || "Plugin");
+  const Icon = sidebarItem ? resolvePluginIcon(sidebarItem.icon) : null;
+  const invoke = useCallback(
+    async (method: string, input: unknown) => {
+      if (!client) throw new Error("Plugin host is offline");
+      return client.invokePluginRpc(pluginId, method, input);
+    },
+    [client, pluginId],
+  );
+  const close = useCallback(() => {
+    if (router.canGoBack()) router.back();
+    else router.replace(`/h/${encodeURIComponent(serverId)}`);
+  }, [serverId]);
+  const layout = useMemo(() => ({ compact, platform: resolvePlatform() }), [compact]);
+  const host = useMemo(() => ({ id: serverId, label: hostLabel }), [hostLabel, serverId]);
+  const headerLeft = useMemo(
+    () => (
+      <>
+        {Icon ? (
+          <HeaderIconBadge>
+            <ThemedPluginHeaderIcon Icon={Icon} uniProps={mutedColorMapping} />
+          </HeaderIconBadge>
+        ) : null}
+        <ScreenTitle>{title}</ScreenTitle>
+      </>
+    ),
+    [Icon, title],
+  );
+  const headerRight = useMemo(
+    () => (
+      <>
+        <PluginHostSwitcher
+          serverId={serverId}
+          pluginId={pluginId}
+          contributionId={contributionId}
+          serverIds={contributionServerIds}
+        />
+        <HeaderToggleButton
+          accessibilityLabel="Close plugin"
+          onPress={close}
+          testID="plugin-surface-close"
+          tooltipKeys={EMPTY_SHORTCUT_KEYS}
+          tooltipLabel="Close"
+          tooltipSide="bottom"
+        >
+          <ThemedX size={18} uniProps={mutedColorMapping} />
+        </HeaderToggleButton>
+      </>
+    ),
+    [close, contributionId, contributionServerIds, pluginId, serverId],
+  );
+
+  return (
+    <View style={styles.screen}>
+      <ScreenHeader left={headerLeft} right={headerRight} />
+      <View style={styles.body}>
+        {plugin && surface ? (
+          <SurfaceErrorBoundary
+            key={`${serverId}/${pluginId}/${contributionId}`}
+            installation={plugin}
+            Surface={surface.Component}
+          >
+            <ThemedSurfaceRenderer
+              Surface={surface.Component}
+              invoke={invoke}
+              plugin={plugin}
+              host={host}
+              layout={layout}
+              uniProps={pluginThemeMapping}
+            />
+          </SurfaceErrorBoundary>
+        ) : (
+          <Text style={styles.errorText}>This plugin surface is unavailable.</Text>
+        )}
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create((theme) => ({
+  screen: {
+    flex: 1,
+    backgroundColor: theme.colors.surface0,
+  },
+  body: {
+    flex: 1,
+  },
+  errorText: {
+    color: theme.colors.statusDanger,
+    padding: theme.spacing[4],
+  },
+  hostSwitcher: {
+    maxWidth: 180,
+    minHeight: 32,
+    paddingHorizontal: theme.spacing[2],
+    flexDirection: "row",
+    alignItems: "center",
+    gap: theme.spacing[1],
+    borderRadius: theme.borderRadius.md,
+    backgroundColor: theme.colors.surface1,
+  },
+  hostSwitcherText: {
+    flexShrink: 1,
+    color: theme.colors.foregroundMuted,
+    fontSize: theme.fontSize.sm,
+  },
+}));

packages/app/src/plugins/types.ts

@@ -0,0 +1,26 @@
+import type { QueryClient } from "@tanstack/react-query";
+import type {
+  PluginAttachmentSourceContribution,
+  PluginSidebarContribution,
+  PluginSurfaceContribution,
+} from "@paseo/plugin";
+
+export interface EvaluatedPlugin {
+  id: string;
+  cleanup: () => void;
+  surfaces: PluginSurfaceContribution[];
+  sidebarItems: PluginSidebarContribution[];
+  attachmentSources: PluginAttachmentSourceContribution[];
+}
+
+export interface InstalledPlugin extends EvaluatedPlugin {
+  serverId: string;
+  clientBundle: string;
+  queryClient: QueryClient;
+}
+
+export type {
+  PluginAttachmentSourceContribution,
+  PluginSidebarContribution,
+  PluginSurfaceContribution,
+};