docs(plugins): add example plugins and record plugin trust constraints

apps/desktop/src/window/DesktopWindow.ts

@@ -36,6 +36,7 @@ import * as ElectronApp from "../electron/ElectronApp.ts";
 import * as DesktopRendererHistory from "../telemetry/DesktopRendererHistory.ts";
 import { makeQuitShortcutHandler } from "./QuitHold.ts";
 import { copyContextMenuImage } from "./ContextMenuImage.ts";
+import { shouldVetoViewFrameNavigation } from "./pluginViewNavigation.ts";
 
 const TITLEBAR_HEIGHT = 40;
 // Match --workspace-topbar-height in apps/web/src/index.css; native macOS buttons stay 14 points at any zoom.
@@ -626,6 +627,30 @@ export const make = Effect.gen(function* () {
         void runPromise(electronShell.openExternal(url));
       }
     });
+    // Plugin views may not navigate themselves; see pluginViewNavigation.ts.
+    window.webContents.on("will-frame-navigate", (event) => {
+      if (event.isMainFrame) return;
+      if (
+        !shouldVetoViewFrameNavigation({
+          url: event.url,
+          frame: event.frame,
+          initiator: event.initiator,
+          mainFrame: window.webContents.mainFrame,
+        })
+      )
+        return;
+      event.preventDefault();
+      // Only where it tried to go: a path or query can carry the view's data.
+      const target = URL.parse(event.url);
+      void runPromise(
+        logWindowInfo(
+          "refused a plugin view navigation",
+          target === null
+            ? { protocol: "invalid" }
+            : { protocol: target.protocol, host: target.host },
+        ),
+      );
+    });
 
     const quitShortcutHandler = makeQuitShortcutHandler({
       platform: environment.platform,

apps/desktop/src/window/pluginViewNavigation.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { type NavigationFrame, shouldVetoViewFrameNavigation } from "./pluginViewNavigation.ts";
+
+const frame = (
+  frameToken: string,
+  url: string,
+  origin: string,
+  parent: NavigationFrame | null,
+  name = "",
+): NavigationFrame => ({ frameToken, url, origin, parent, name });
+
+const app = frame("app", "t3code-dev://app/", "t3code-dev://app", null);
+const view = frame("view", "about:srcdoc", "null", app, "t3-plugin-view");
+const wrapper = frame("wrapper", "about:srcdoc", "null", app, "t3-plugin-view");
+const wrappedView = frame("inner", "about:srcdoc", "null", wrapper);
+
+describe("shouldVetoViewFrameNavigation", () => {
+  it("refuses a view navigating itself, including through a policy wrapper", () => {
+    for (const target of [view, wrappedView]) {
+      for (const url of ["about:blank", "http://127.0.0.1:7391/page.html", "data:text/html,x"]) {
+        expect(
+          shouldVetoViewFrameNavigation({ url, frame: target, initiator: target, mainFrame: app }),
+        ).toBe(true);
+      }
+    }
+  });
+
+  it("refuses a navigation with no known initiator", () => {
+    expect(
+      shouldVetoViewFrameNavigation({
+        url: "http://127.0.0.1:7391/redirect",
+        frame: view,
+        initiator: null,
+        mainFrame: app,
+      }),
+    ).toBe(true);
+  });
+
+  it("lets the app mount, wrap and dispose views", () => {
+    const fresh = frame("fresh", "about:blank", "t3code-dev://app", app);
+    expect(
+      shouldVetoViewFrameNavigation({
+        url: "about:srcdoc",
+        frame: fresh,
+        initiator: app,
+        mainFrame: app,
+      }),
+    ).toBe(false);
+    const freshInner = frame("fresh-inner", "about:blank", "null", wrapper);
+    expect(
+      shouldVetoViewFrameNavigation({
+        url: "about:srcdoc",
+        frame: freshInner,
+        initiator: wrapper,
+        mainFrame: app,
+      }),
+    ).toBe(false);
+    expect(
+      shouldVetoViewFrameNavigation({
+        url: "about:blank",
+        frame: view,
+        initiator: app,
+        mainFrame: app,
+      }),
+    ).toBe(false);
+  });
+
+  it("leaves frames outside views alone", () => {
+    const other = frame("other", "https://example.com/", "https://example.com", app);
+    const font = frame("font", "about:srcdoc", "null", app);
+    const fontChild = frame("font-child", "about:srcdoc", "null", font);
+    for (const target of [other, font, fontChild]) {
+      expect(
+        shouldVetoViewFrameNavigation({
+          url: "https://example.com/next",
+          frame: target,
+          initiator: target,
+          mainFrame: app,
+        }),
+      ).toBe(false);
+    }
+  });
+});

apps/desktop/src/window/pluginViewNavigation.ts

@@ -0,0 +1,27 @@
+// A document's CSP cannot stop frame navigation; Electron vetoes isolated-subtree navigation unless the main frame starts it.
+// Allow about:srcdoc mounting; wrapper CSP blocks data: navigation and ping liveness detects about:blank.
+
+export interface NavigationFrame {
+  readonly url: string;
+  readonly origin: string;
+  readonly frameToken: string;
+  readonly name: string;
+  readonly parent: NavigationFrame | null;
+}
+
+const isViewDocument = (frame: NavigationFrame) =>
+  frame.name === "t3-plugin-view" && frame.url === "about:srcdoc" && frame.origin === "null";
+
+export function shouldVetoViewFrameNavigation(input: {
+  readonly url: string;
+  readonly frame: NavigationFrame | null;
+  readonly initiator: NavigationFrame | null | undefined;
+  readonly mainFrame: NavigationFrame;
+}): boolean {
+  let insideView = false;
+  for (let frame = input.frame; frame !== null; frame = frame.parent) {
+    if (isViewDocument(frame)) insideView = true;
+  }
+  if (!insideView || input.url === "about:srcdoc") return false;
+  return input.initiator?.frameToken !== input.mainFrame.frameToken;
+}

apps/mobile/src/Stack.tsx

@@ -46,6 +46,7 @@ import {
   type RenderFailureProps,
 } from "./components/RenderErrorBoundary";
 import { ArchivedThreadsRouteScreen } from "./features/archive/ArchivedThreadsRouteScreen";
+import { PluginNotificationBannerHost } from "./features/plugins/PluginNotificationBannerHost";
 import { ConnectOnboardingRouteScreen } from "./features/cloud/ConnectOnboardingRouteScreen";
 import { AttachmentFileScreen } from "./features/files/AttachmentFileScreen";
 import { ThreadFilesTreeScreen, ThreadFileScreen } from "./features/files/ThreadFilesRouteScreen";
@@ -95,6 +96,10 @@ import { SettingsNavigationRouteScreen } from "./features/settings/SettingsNavig
 import { SettingsAppearanceRouteScreen } from "./features/settings/SettingsAppearanceRouteScreen";
 import { SettingsClientStorageRouteScreen } from "./features/settings/SettingsClientStorageRouteScreen";
 import { SettingsDiagnosticsRouteScreen } from "./features/diagnostics/SettingsDiagnosticsRouteScreen";
+import {
+  SettingsPluginRouteScreen,
+  SettingsPluginsRouteScreen,
+} from "./features/settings/SettingsPluginsRouteScreen";
 import { SettingsProviderAccountsRouteScreen } from "./features/settings/SettingsProviderAccountsRouteScreen";
 import { SettingsAuthRouteScreen } from "./features/settings/SettingsAuthRouteScreen";
 import { SettingsEnvironmentDetailRouteScreen } from "./features/settings/SettingsEnvironmentDetailRouteScreen";
@@ -390,6 +395,15 @@ const SETTINGS_SCREENS = {
       headerTitleStyle: { fontSize: 16, fontWeight: "800" },
     },
   }),
+  SettingsPlugins: createNativeStackScreen({
+    screen: SettingsPluginsRouteScreen,
+    linking: "settings/plugins",
+    options: { ...SETTINGS_PAGE_OPTIONS, title: "Plugins" },
+  }),
+  SettingsPlugin: createNativeStackScreen({
+    screen: SettingsPluginRouteScreen,
+    options: { ...SETTINGS_PAGE_OPTIONS, title: "Plugin" },
+  }),
   SettingsScheduledTaskNew: createNativeStackScreen({
     screen: SettingsScheduledTaskNewRouteScreen,
     linking: "settings/scheduled-tasks/new",
@@ -544,6 +558,7 @@ function RootStackLayout(props: {
               </AdaptiveWorkspaceLayout>
             </AndroidWorkspaceTabsProvider>
           </WorkspaceConnectionStatusProvider>
+          <PluginNotificationBannerHost />
         </SettingsEnvironmentFilterProvider>
       </HardwareKeyboardCommandProvider>
     </NewTaskFlowProvider>

apps/mobile/src/features/keyboard/CommandPalette.tsx

@@ -8,7 +8,11 @@ import {
   type EnvironmentThreadSearchMatch,
   type ShownOrder,
 } from "@t3tools/client-runtime/state/thread-search";
-import { isListedThreadLineage, THREAD_JUMP_KEYBINDING_COMMANDS } from "@t3tools/contracts";
+import {
+  AuthOrchestrationOperateScope,
+  isListedThreadLineage,
+  THREAD_JUMP_KEYBINDING_COMMANDS,
+} from "@t3tools/contracts";
 import {
   foldSearchQuery,
   PALETTE_MESSAGE_LIMIT,
@@ -53,6 +57,8 @@ import { requestThreadMessageJump } from "../threads/threadMessageJump";
 import { threadEnvironment } from "../../state/threads";
 import { useAtomCommand } from "../../state/use-atom-command";
 import { serverEnvironment } from "../../state/server";
+import { runPluginAction, usePluginActions } from "../../state/plugin-actions";
+import { useEnvironmentScope } from "../../state/session";
 import { useWorkspaceEnvironments } from "../../state/workspace";
 import { useSavedRemoteConnections } from "../../state/use-remote-environment-registry";
 import { useAppearancePreferences } from "../settings/appearance/AppearancePreferencesProvider";
@@ -62,6 +68,7 @@ import { useStartTriage } from "../triage/useStartTriage";
 import { useNewTaskFlow } from "../threads/new-task-flow-provider";
 import { useActiveNewTask } from "../../state/active-new-task";
 import {
+  buildPluginActionPaletteItems,
   filterCommandPaletteItems,
   nextPaletteIndex,
   type CommandPaletteItem,
@@ -102,6 +109,7 @@ const ACTION_ICONS: Record<string, AppSymbolName> = {
 
 function itemIcon(item: CommandPaletteItem): AppSymbolName {
   if (item.kind === "thread") return "text.bubble";
+  if (item.key.startsWith("plugin-action:")) return "cube";
   return ACTION_ICONS[item.key] ?? "ellipsis";
 }
 
@@ -231,6 +239,17 @@ export function CommandPalette(props: {
   const activeThread = useThreadShell(activeThreadRef);
   const visitThread = useAtomCommand(threadEnvironment.visit, { reportFailure: false });
   const environments = useWorkspaceEnvironments();
+  // Plugin actions belong to the open thread's environment, else the first connected one.
+  const pluginActionEnvironmentId =
+    activeThreadRef?.environmentId ??
+    environments.find((environment) => environment.connectionState === "connected")
+      ?.environmentId ??
+    null;
+  const pluginActions = usePluginActions(pluginActionEnvironmentId);
+  const canRunPluginActions = useEnvironmentScope(
+    pluginActionEnvironmentId,
+    AuthOrchestrationOperateScope,
+  );
   const { savedConnectionsById } = useSavedRemoteConnections();
   const [query, setQuery] = useState("");
   // Ranking is relative to when the palette opened, so rows do not reorder as time passes.
@@ -401,6 +420,18 @@ export function CommandPalette(props: {
         })),
       );
     }
+    if (pluginActionEnvironmentId !== null) {
+      actions.push(
+        ...buildPluginActionPaletteItems({
+          actions: pluginActions,
+          canOperate: canRunPluginActions,
+          environmentId: pluginActionEnvironmentId,
+          threadId: activeThread?.id ?? null,
+          projectId: activeThread?.projectId ?? null,
+          runAction: (input) => void runPluginAction(input),
+        }),
+      );
+    }
     const openProjects = projects.filter((project) => project.archivedAt == null);
     const projectItems: CommandPaletteItem[] = [
       ...openProjects.filter((project) => project.pinnedAt != null),
@@ -467,6 +498,9 @@ export function CommandPalette(props: {
     environments.length,
     canTriage,
     navigation,
+    canRunPluginActions,
+    pluginActionEnvironmentId,
+    pluginActions,
     projects,
     runCommand,
     savedConnectionsById,

apps/mobile/src/features/keyboard/commandPaletteItems.test.ts

@@ -1,6 +1,17 @@
-import { describe, expect, it } from "vite-plus/test";
+import {
+  EnvironmentId,
+  PluginActionId,
+  ProjectId,
+  ThreadId,
+  type PluginAction,
+} from "@t3tools/contracts";
+import { describe, expect, it, vi } from "vite-plus/test";
 
-import { filterCommandPaletteItems, type CommandPaletteItem } from "./commandPaletteItems";
+import {
+  buildPluginActionPaletteItems,
+  filterCommandPaletteItems,
+  type CommandPaletteItem,
+} from "./commandPaletteItems";
 
 const NOW = Date.UTC(2026, 9, 23);
 
@@ -54,3 +65,78 @@ describe("filterCommandPaletteItems", () => {
     expect(filterCommandPaletteItems(items, "> layout", ["siva:one"], NOW)).toEqual([]);
   });
 });
+describe("buildPluginActionPaletteItems", () => {
+  const environmentId = EnvironmentId.make("environment-1");
+  const thread = {
+    environmentId,
+    threadId: ThreadId.make("thread-1"),
+    projectId: ProjectId.make("project-1"),
+  };
+  const deploy: PluginAction = {
+    id: PluginActionId.make("installation-1:1:deploy"),
+    pluginId: "acme.deploy",
+    pluginName: "Deploy",
+    name: "deploy",
+    title: "Deploy this branch",
+    target: "thread",
+    placements: ["command-palette"],
+  };
+  const refresh: PluginAction = {
+    ...deploy,
+    id: PluginActionId.make("installation-1:1:refresh"),
+    name: "refresh",
+    title: "Refresh caches",
+    target: "environment",
+  };
+
+  it("runs an offered action in the open thread's environment", () => {
+    const runAction = vi.fn();
+    const offered = buildPluginActionPaletteItems({
+      actions: [deploy],
+      canOperate: true,
+      ...thread,
+      runAction,
+    });
+    expect(offered.map((item) => item.title)).toEqual(["Deploy this branch"]);
+
+    offered[0]?.run();
+
+    expect(runAction).toHaveBeenCalledWith({
+      environmentId: thread.environmentId,
+      action: deploy,
+      target: { _tag: "thread", threadId: thread.threadId },
+    });
+  });
+
+  it("offers environment actions when no thread is open", () => {
+    const runAction = vi.fn();
+    const offered = buildPluginActionPaletteItems({
+      actions: [deploy, refresh],
+      canOperate: true,
+      environmentId,
+      threadId: null,
+      projectId: null,
+      runAction,
+    });
+    expect(offered.map((item) => item.title)).toEqual(["Refresh caches"]);
+
+    offered[0]?.run();
+
+    expect(runAction).toHaveBeenCalledWith({
+      environmentId,
+      action: refresh,
+      target: { _tag: "environment" },
+    });
+  });
+
+  it("offers nothing to a connection that cannot operate the environment", () => {
+    expect(
+      buildPluginActionPaletteItems({
+        actions: [deploy],
+        canOperate: false,
+        ...thread,
+        runAction: vi.fn(),
+      }),
+    ).toEqual([]);
+  });
+});