Enforce shared, client, and server plugin SDK boundaries (#4347)

* fix(plugins): keep React out of the server plugin host

* fix(plugins): align SDK guidance and tests with runtime boundaries

* fix(plugin): loosen the react peer to ~19.1.0

The plugin SDK pins its react peer to exactly 19.1.0, and that pin is
what a downstream `npm i -g @getpaseo/cli` resolves against. So every
user ends up with react 19.1.0 in their global node_modules, where
corporate dependency scanners flag it: the CVE-2025-55182 advisory range
covers 19.1.0 even though the vulnerability itself lives in
react-server-dom-webpack/-parcel/-turbopack, none of which the CLI
installs. The user is then left hand-patching node_modules or
uninstalling Paseo.

Widening the peer to ~19.1.0 lets a downstream install pick the latest
19.1.x patch (19.1.9 today) while this repo stays on 19.1.0, which the
root override still pins.

Keeping the repo itself on 19.1.0 is deliberate. react-native 0.81.5
embeds a 19.1.0 Paper renderer that hard-throws "Incompatible React
versions" on any exact mismatch, and it is reachable from Fabric builds
too: RendererImplementation.js requires the Paper shim unconditionally
in findNodeHandle, unstable_batchedUpdates, sendAccessibilityEvent and
three other entry points, and react-native-gesture-handler re-exports
findNodeHandle. Bumping the app's react is therefore not safe until
react-native moves.

The published CLI tree contains no react-native, so downstream installs
are not subject to that constraint.

Supersedes the earlier 19.1.5/19.1.9 version-bump approach on this
branch, which would have broken the mobile app.

* Enforce example import ownership including client types

* Update Nix dependency hash for plugin peer metadata

* Group plugin APIs under client and server entry trees

* Resolve plugin type dependencies through declarations

* Validate declarations for implicit plugin type imports

* Preserve optional imports and validate declaration references

* Refresh Nix hash for plugin declaration resolver

* Canonicalize plugin paths consistently on Windows

* Normalize plugin ownership paths across resolver boundaries

---------

Co-authored-by: liujin0506 <liujin0506@qq.com>
Co-authored-by: Mohamed Boudra <boudra.moha@gmail.com>

plugin-examples/agent-configuration/index.server.ts

@@ -1,4 +1,4 @@
-import type { PluginServerContext } from "@getpaseo/plugin";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
 
 export default function contribute(server: PluginServerContext) {
   server.before("agent.create", ({ request }) => {

plugin-examples/catppuccin/index.client.ts

@@ -1,4 +1,4 @@
-import type { PluginClientContext } from "@getpaseo/plugin";
+import type { PluginClientContext } from "@getpaseo/plugin/client";
 
 export default function contribute(client: PluginClientContext) {
   client.addTheme({

plugin-examples/inline-thinking/client/thinking.tsx

@@ -1,5 +1,5 @@
-import type { PluginTimelineItemProps } from "@getpaseo/plugin";
-import { useRevealedText } from "@getpaseo/plugin/react-native";
+import type { PluginTimelineItemProps } from "@getpaseo/plugin/client";
+import { useRevealedText } from "@getpaseo/plugin/client/react-native";
 import { useMemo } from "react";
 import { Text } from "react-native";
 import { z } from "zod";

plugin-examples/inline-thinking/index.client.tsx

@@ -1,4 +1,4 @@
-import type { PluginClientContext } from "@getpaseo/plugin";
+import type { PluginClientContext } from "@getpaseo/plugin/client";
 import { InlineThinking, inlineThinkingSchema } from "./client/thinking";
 
 export default function contribute(client: PluginClientContext) {

plugin-examples/lifecycle-actions/index.server.ts

@@ -1,4 +1,4 @@
-import type { PluginServerContext } from "@getpaseo/plugin";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
 import { latestOutputText, shellCommand } from "./server/inspect";
 
 export default function contribute(server: PluginServerContext) {

plugin-examples/lifecycle-logger/index.server.ts

@@ -1,4 +1,4 @@
-import type { PluginServerContext } from "@getpaseo/plugin";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
 import { logHook } from "./server/log";
 
 export default function contribute(server: PluginServerContext) {

plugin-examples/linear/index.client.ts

@@ -1,4 +1,4 @@
-import type { PluginClientContext } from "@getpaseo/plugin";
+import type { PluginClientContext } from "@getpaseo/plugin/client";
 import { issueAttachments } from "./shared/issues";
 
 export default function contribute(client: PluginClientContext) {

plugin-examples/linear/index.server.ts

@@ -1,4 +1,4 @@
-import type { PluginServerContext } from "@getpaseo/plugin";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
 import { searchIssues } from "./server/issues";
 import { searchIssuesRpc } from "./shared/issues";
 

plugin-examples/local-plugin/client/main.tsx

@@ -1,13 +1,13 @@
 import { useMutation } from "@tanstack/react-query";
+import { Icon } from "@getpaseo/plugin/client/react-native";
 import {
-  Icon,
   type PluginClientContext,
   type PluginComposerPillProps,
   type PluginWorkspacePanelProps,
   useAgent,
   useRpc,
   useWorkspace,
-} from "@getpaseo/plugin";
+} from "@getpaseo/plugin/client";
 import { useCallback, useMemo } from "react";
 import { Pressable, Text, View } from "react-native";
 import { incrementRpc } from "../shared/increment";

plugin-examples/local-plugin/index.client.tsx

@@ -1,4 +1,4 @@
-import type { PluginClientContext } from "@getpaseo/plugin";
+import type { PluginClientContext } from "@getpaseo/plugin/client";
 import { contributeClient, ExamplePanel } from "./client/main";
 
 export default function contribute(client: PluginClientContext) {

plugin-examples/local-plugin/index.server.ts

@@ -1,4 +1,4 @@
-import type { PluginServerContext } from "@getpaseo/plugin";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
 import { increment } from "./server/increment";
 import { incrementRpc } from "./shared/increment";
 

plugin-examples/modal-ui/client/examples.tsx

@@ -1,4 +1,4 @@
-import type { PluginSurfaceProps } from "@getpaseo/plugin";
+import type { PluginSurfaceProps } from "@getpaseo/plugin/client";
 import {
   Modal,
   ScrollView,
@@ -6,7 +6,7 @@ import {
   TextInput,
   copyText,
   useToast,
-} from "@getpaseo/plugin/react-native";
+} from "@getpaseo/plugin/client/react-native";
 import { useCallback, useMemo, useRef, useState } from "react";
 import {
   Pressable,

plugin-examples/modal-ui/index.client.tsx

@@ -1,4 +1,4 @@
-import type { PluginClientContext } from "@getpaseo/plugin";
+import type { PluginClientContext } from "@getpaseo/plugin/client";
 import { ModalExamples } from "./client/examples";
 
 export default function contribute(plugin: PluginClientContext) {

plugin-examples/provider-acp-transformer/index.server.ts

@@ -1,5 +1,5 @@
-import type { PluginServerContext } from "@getpaseo/plugin";
-import { runAcpProvider } from "@getpaseo/plugin/acp";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { runAcpProvider } from "@getpaseo/plugin/server/acp";
 import { vendorEditTransformer } from "./server/vendor-edit.js";
 
 export default function contribute(server: PluginServerContext) {

plugin-examples/provider-acp-transformer/server/vendor-edit.ts

@@ -1,4 +1,4 @@
-import type { AcpTransformer } from "@getpaseo/plugin/acp";
+import type { AcpTransformer } from "@getpaseo/plugin/server/acp";
 import { z } from "zod";
 
 const vendorEditInputSchema = z.object({

plugin-examples/provider-direct/client/provider-result.tsx

@@ -1,4 +1,4 @@
-import type { PluginTimelineItemProps } from "@getpaseo/plugin";
+import type { PluginTimelineItemProps } from "@getpaseo/plugin/client";
 import { useMemo } from "react";
 import { Text, View } from "react-native";
 import type { z } from "zod";

plugin-examples/provider-direct/index.client.tsx

@@ -1,4 +1,4 @@
-import type { PluginClientContext } from "@getpaseo/plugin";
+import type { PluginClientContext } from "@getpaseo/plugin/client";
 import { ProviderResult } from "./client/provider-result";
 import { providerResultKind, providerResultSchema } from "./shared/provider-result";
 

plugin-examples/provider-direct/index.server.ts

@@ -1,4 +1,4 @@
-import type { PluginServerContext } from "@getpaseo/plugin";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
 import { createDirectExampleProvider } from "./server/provider";
 
 export default function contribute(server: PluginServerContext) {

plugin-examples/provider-direct/server/provider.test.ts

@@ -1,4 +1,4 @@
-import type { ProviderEvent } from "@getpaseo/plugin/provider";
+import type { ProviderEvent } from "@getpaseo/plugin/server/provider";
 import { describe, expect, it } from "vitest";
 import { createDirectExampleProvider } from "./provider.js";
 

plugin-examples/provider-direct/server/provider.ts

@@ -8,7 +8,7 @@ import {
   type ProviderPersistence,
   type ProviderRegistration,
   type ProviderSessionConfig,
-} from "@getpaseo/plugin/provider";
+} from "@getpaseo/plugin/server/provider";
 import { randomUUID } from "node:crypto";
 import { providerResultKind } from "../shared/provider-result.js";
 

plugin-examples/settings/client/display-settings.tsx

@@ -1,6 +1,7 @@
 import { useCallback, useMemo, useState } from "react";
 import { Text, View } from "react-native";
-import { useSettings, type PluginSurfaceProps, type SettingsState } from "@getpaseo/plugin";
+import { useSettings, type PluginSurfaceProps } from "@getpaseo/plugin/client";
+import type { SettingsState } from "@getpaseo/plugin/client";
 import {
   SettingsAction,
   SettingsCard,
@@ -9,7 +10,7 @@ import {
   SettingsSection,
   SettingsSelect,
   SettingsSwitch,
-} from "@getpaseo/plugin/ui";
+} from "@getpaseo/plugin/client/ui";
 import { preferences } from "../shared/preferences";
 
 const grouping = [

plugin-examples/settings/index.client.tsx

@@ -1,4 +1,4 @@
-import type { PluginClientContext } from "@getpaseo/plugin";
+import type { PluginClientContext } from "@getpaseo/plugin/client";
 import { DisplaySettings } from "./client/display-settings";
 
 export default function contribute(client: PluginClientContext) {

plugin-examples/settings/index.server.ts

@@ -1,4 +1,4 @@
-import type { PluginServerContext } from "@getpaseo/plugin";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
 import { preferences } from "./shared/preferences";
 
 export default function contribute(server: PluginServerContext) {

plugin-examples/timeline-items/client/pi-tasks.tsx

@@ -1,4 +1,4 @@
-import type { PluginTimelineItemProps } from "@getpaseo/plugin";
+import type { PluginTimelineItemProps } from "@getpaseo/plugin/client";
 import { useMemo } from "react";
 import { Text, View } from "react-native";
 import type { z } from "zod";

plugin-examples/timeline-items/client/transform-pi-tasks.ts

@@ -0,0 +1,72 @@
+import type { PluginTimelineTransformerContribution } from "@getpaseo/plugin/client";
+import { z } from "zod";
+import { piTaskListSchema } from "../shared/pi-tasks";
+
+const rpivDetailsSchema = z.object({
+  tasks: z.array(
+    z
+      .object({
+        subject: z.string(),
+        status: z.enum(["pending", "in_progress", "completed", "deleted"]),
+      })
+      .passthrough(),
+  ),
+});
+
+const piExampleDetailsSchema = z.object({
+  todos: z.array(
+    z
+      .object({
+        id: z.number().int().optional(),
+        text: z.string(),
+        done: z.boolean(),
+      })
+      .passthrough(),
+  ),
+});
+
+type PiTask = z.output<typeof piTaskListSchema>["tasks"][number];
+type ToolCallTransformer = PluginTimelineTransformerContribution<"tool_call">["transform"];
+
+function replacement(tasks: PiTask[]) {
+  if (tasks.length === 0) return;
+  return {
+    items: [
+      {
+        type: "plugin" as const,
+        kind: "pi-task-list",
+        version: 1,
+        data: { tasks },
+      },
+    ],
+  };
+}
+
+export const transformPiTodoToolCall: ToolCallTransformer = ({ item }) => {
+  if (item.name !== "todo" || item.detail.type !== "unknown") {
+    return;
+  }
+
+  const result = item.detail.output;
+  if (!result || typeof result !== "object" || Array.isArray(result)) return;
+  const details = Reflect.get(result, "details");
+
+  const rpiv = rpivDetailsSchema.safeParse(details);
+  if (rpiv.success) {
+    return replacement(
+      rpiv.data.tasks.flatMap((task): PiTask[] =>
+        task.status === "deleted" ? [] : [{ text: task.subject, status: task.status }],
+      ),
+    );
+  }
+
+  const piExample = piExampleDetailsSchema.safeParse(details);
+  if (piExample.success) {
+    return replacement(
+      piExample.data.todos.map((todo) => ({
+        text: todo.text,
+        status: todo.done ? "completed" : "pending",
+      })),
+    );
+  }
+};

plugin-examples/timeline-items/index.client.tsx

@@ -1,6 +1,7 @@
-import type { PluginClientContext } from "@getpaseo/plugin";
+import type { PluginClientContext } from "@getpaseo/plugin/client";
 import { PiTaskList } from "./client/pi-tasks";
-import { piTaskListSchema, transformPiTodoToolCall } from "./shared/pi-tasks";
+import { piTaskListSchema } from "./shared/pi-tasks";
+import { transformPiTodoToolCall } from "./client/transform-pi-tasks";
 
 export default function contribute(client: PluginClientContext) {
   client.addTimelineTransformer({

plugin-examples/timeline-items/pi-tasks.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { transformPiTodoToolCall } from "./shared/pi-tasks";
+import { transformPiTodoToolCall } from "./client/transform-pi-tasks";
 
 function completedTodo(output: unknown) {
   return {

plugin-examples/timeline-items/shared/pi-tasks.ts

@@ -1,31 +1,7 @@
-import type { PluginTimelineTransformerContribution } from "@getpaseo/plugin";
 import { z } from "zod";
 
 const taskStatusSchema = z.enum(["pending", "in_progress", "completed"]);
 
-const rpivDetailsSchema = z.object({
-  tasks: z.array(
-    z
-      .object({
-        subject: z.string(),
-        status: z.enum(["pending", "in_progress", "completed", "deleted"]),
-      })
-      .passthrough(),
-  ),
-});
-
-const piExampleDetailsSchema = z.object({
-  todos: z.array(
-    z
-      .object({
-        id: z.number().int().optional(),
-        text: z.string(),
-        done: z.boolean(),
-      })
-      .passthrough(),
-  ),
-});
-
 export const piTaskListSchema = z.object({
   tasks: z.array(
     z.object({
@@ -34,49 +10,3 @@ export const piTaskListSchema = z.object({
     }),
   ),
 });
-
-type PiTask = z.output<typeof piTaskListSchema>["tasks"][number];
-type ToolCallTransformer = PluginTimelineTransformerContribution<"tool_call">["transform"];
-
-function replacement(tasks: PiTask[]) {
-  if (tasks.length === 0) return;
-  return {
-    items: [
-      {
-        type: "plugin" as const,
-        kind: "pi-task-list",
-        version: 1,
-        data: { tasks },
-      },
-    ],
-  };
-}
-
-export const transformPiTodoToolCall: ToolCallTransformer = ({ item }) => {
-  if (item.name !== "todo" || item.detail.type !== "unknown") {
-    return;
-  }
-
-  const result = item.detail.output;
-  if (!result || typeof result !== "object" || Array.isArray(result)) return;
-  const details = Reflect.get(result, "details");
-
-  const rpiv = rpivDetailsSchema.safeParse(details);
-  if (rpiv.success) {
-    return replacement(
-      rpiv.data.tasks.flatMap((task): PiTask[] =>
-        task.status === "deleted" ? [] : [{ text: task.subject, status: task.status }],
-      ),
-    );
-  }
-
-  const piExample = piExampleDetailsSchema.safeParse(details);
-  if (piExample.success) {
-    return replacement(
-      piExample.data.todos.map((todo) => ({
-        text: todo.text,
-        status: todo.done ? "completed" : "pending",
-      })),
-    );
-  }
-};