feat(plugins): server plugins can post notes into threads

apps/desktop/src/electron/ElectronProtocol.test.ts

@@ -99,7 +99,7 @@ describe("ElectronProtocol", () => {
           assert.equal(yield* Effect.promise(() => response.text()), "ok");
           assert.include(
             response.headers.get("content-security-policy") ?? "",
-            "script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval' https://clerk.t3.codes https://challenges.cloudflare.com",
+            "script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval' blob: https://clerk.t3.codes https://challenges.cloudflare.com",
           );
           assert.include(
             response.headers.get("content-security-policy") ?? "",

apps/desktop/src/electron/ElectronProtocol.ts

@@ -74,6 +74,8 @@ function makeDesktopContentSecurityPolicy(input: DesktopProtocolRegistrationInpu
     "'self'",
     "'unsafe-inline'",
     "'wasm-unsafe-eval'",
+    // Web plugins run from object URLs: their bundles are fetched with the session's credentials.
+    "blob:",
     ...(clerkOrigin ? [clerkOrigin] : []),
     "https://challenges.cloudflare.com",
   ];

apps/server/package.json

@@ -77,6 +77,7 @@
     "@effect/vitest": "catalog:",
     "@opencode-ai/sdk": "^1.3.15",
     "@t3tools/contracts": "workspace:*",
+    "@t3tools/plugin-sdk": "workspace:*",
     "@t3tools/provider-testing": "workspace:*",
     "@t3tools/secret-provider-core": "workspace:*",
     "@t3tools/secret-provider-definitions": "workspace:*",

apps/server/src/auth/RpcAuthorization.test.ts

@@ -68,6 +68,16 @@ describe("RPC authorization scopes", () => {
     }
   });
 
+  it("keeps enabling, reloading and configuring plugins, which runs their code, behind settings write", () => {
+    for (const method of [
+      WS_METHODS.pluginsSetEnabled,
+      WS_METHODS.pluginsReload,
+      WS_METHODS.pluginsSettingsUpdate,
+    ]) {
+      expect(requiredScopeForRpcMethod(method)).toBe(AuthSettingsWriteScope);
+    }
+  });
+
   it("rejects unknown RPC method names", () => {
     for (const method of ["server.notRegistered", "toString", "constructor"]) {
       expect(() => requiredScopeForRpcMethod(method)).toThrow(

apps/server/src/auth/RpcAuthorization.ts

@@ -205,6 +205,13 @@ export const RPC_REQUIRED_SCOPES = {
   [WS_METHODS.deviceDetail]: AuthOrchestrationReadScope,
   [WS_METHODS.deviceAction]: AuthOrchestrationOperateScope,
   [WS_METHODS.subscribeDeviceState]: AuthOrchestrationReadScope,
+  // `plugins.invoke` also needs the operate scope for methods a plugin registered as writes;
+  // PluginHost checks that against the plugin's own declaration. Channels are reads.
+  [WS_METHODS.pluginsList]: AuthOrchestrationReadScope,
+  [WS_METHODS.pluginsSubscribeStates]: AuthOrchestrationReadScope,
+  [WS_METHODS.pluginsSettingsGet]: AuthOrchestrationReadScope,
+  [WS_METHODS.pluginsInvoke]: AuthOrchestrationReadScope,
+  [WS_METHODS.pluginsSubscribe]: AuthOrchestrationReadScope,
   [WS_METHODS.subscribeServerConfig]: AuthOrchestrationReadScope,
   [WS_METHODS.subscribeServerLifecycle]: AuthOrchestrationReadScope,
   [WS_METHODS.subscribeAuthAccess]: AuthAccessReadScope,

apps/server/src/environment/ServerEnvironment.ts

@@ -243,6 +243,7 @@ export const make = Effect.gen(function* () {
       threadSnooze: true,
       threadForceStop: true,
       environmentThemes: true,
+      plugins: true,
       usageLimitSources: true,
       providerWorkspaceSnapshotsOnDemand: true,
       usagePriceOverrides: true,

apps/server/src/environmentTheme.test.ts

@@ -90,6 +90,41 @@ it.layer(NodeServices.layer)("environment theme", (it) => {
     ),
   );
 
+  it.effect("adds plugin themes after the environment's own, which win on the same id", () =>
+    withEnvironmentThemes(
+      { "nightfall.json": encodeThemeFile(NIGHTFALL_THEME) },
+      Effect.gen(function* () {
+        const environmentTheme = yield* EnvironmentTheme.EnvironmentThemeService;
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const pluginThemes = yield* fs.makeTempDirectoryScoped({ prefix: "t3code-plugin-themes-" });
+        yield* fs.writeFileString(
+          path.join(pluginThemes, "nightfall.json"),
+          encodeThemeFile({ ...NIGHTFALL_THEME, name: "Plugin Nightfall" }),
+        );
+        yield* fs.writeFileString(
+          path.join(pluginThemes, "shared-light.json"),
+          encodeThemeFile(SHARED_THEME),
+        );
+
+        yield* environmentTheme.setPluginThemeDirectories([pluginThemes]);
+        assert.deepEqual(
+          (yield* currentThemes).map((theme) => [theme.id, theme.name]),
+          [
+            ["nightfall", "Nightfall"],
+            ["shared-light", "Shared Light"],
+          ],
+        );
+
+        yield* environmentTheme.setPluginThemeDirectories([]);
+        assert.deepEqual(
+          (yield* currentThemes).map((theme) => theme.id),
+          ["nightfall"],
+        );
+      }),
+    ),
+  );
+
   it.effect("never replays a set older than the snapshot it started from", () =>
     withEnvironmentThemes(
       { "nightfall.json": encodeThemeFile(NIGHTFALL_THEME) },

apps/server/src/environmentTheme.ts

@@ -50,6 +50,12 @@ export class EnvironmentThemeService extends Context.Service<
 
     /** Subscribes before reading to retain changes during connection. */
     readonly streamChanges: Stream.Stream<ReadonlyArray<EnvironmentTheme>>;
+
+    /**
+     * Theme folders of active plugins, read after the environment's own folder. The first theme
+     * with an id wins, so a plugin cannot replace a theme the user published.
+     */
+    readonly setPluginThemeDirectories: (directories: ReadonlyArray<string>) => Effect.Effect<void>;
   }
 >()("t3/environmentTheme/EnvironmentThemeService") {}
 
@@ -158,16 +164,26 @@ const make = Effect.gen(function* () {
   // Sequence numbers let subscribers drop queued events older than their initial snapshot.
   const changes = yield* PubSub.sliding<PublishedThemes>(1);
   const published = yield* Ref.make<PublishedThemes>({ seq: 0, themes: [] });
+  const pluginDirectories = yield* Ref.make<ReadonlyArray<string>>([]);
   // Serialize read/compare/publish so slow older reads cannot publish with newer sequence numbers.
   const refreshSemaphore = yield* Semaphore.make(1);
   const watcherScope = yield* Scope.make("sequential");
   yield* Effect.addFinalizer(() => Scope.close(watcherScope, Exit.void));
 
   const refresh = refreshSemaphore.withPermits(1)(
     Effect.gen(function* () {
-      const themes = yield* readPublishedThemes(environmentThemesDir).pipe(
-        Effect.provideService(FileSystem.FileSystem, fs),
-      );
+      const themes: Array<EnvironmentTheme> = [];
+      const ids = new Set<string>();
+      for (const directory of [environmentThemesDir, ...(yield* Ref.get(pluginDirectories))]) {
+        const found = yield* readPublishedThemes(directory).pipe(
+          Effect.provideService(FileSystem.FileSystem, fs),
+        );
+        for (const theme of found) {
+          if (ids.has(theme.id)) continue;
+          ids.add(theme.id);
+          themes.push(theme);
+        }
+      }
       // Compare the whole value so new fields cannot silently miss republishes.
       const [changed, next] = yield* Ref.modify(
         published,
@@ -198,6 +214,13 @@ const make = Effect.gen(function* () {
 
   return {
     current: Effect.map(refresh, (state) => state.themes),
+    setPluginThemeDirectories: Effect.fn("EnvironmentThemeService.setPluginThemeDirectories")(
+      function* (directories) {
+        const previous = yield* Ref.getAndSet(pluginDirectories, directories);
+        if (Equal.equals(previous, directories)) return;
+        yield* refresh;
+      },
+    ),
     get streamChanges() {
       return Stream.unwrap(
         Effect.gen(function* () {

apps/server/src/http.ts

@@ -288,7 +288,7 @@ function resolveDevRedirectUrl(devUrl: URL, requestUrl: URL): string {
   return redirectUrl.toString();
 }
 
-const authenticateRawRouteWithScope =
+export const authenticateRawRouteWithScope =
   /* Request instrumentation already owns the span; keep this helper in that context. */
   Effect.fnUntraced(function* (
     scope: typeof AuthOrchestrationReadScope | typeof AuthOrchestrationOperateScope,

apps/server/src/mcp/McpHttpServer.ts

@@ -31,6 +31,7 @@ import * as HtmlRender from "../htmlRender/HtmlRender.ts";
 import * as ThreadCommandExecutor from "../orchestration-v2/ThreadCommandExecutor.ts";
 import * as ThreadManagementService from "../orchestration-v2/ThreadManagementService.ts";
 import * as ProviderRegistry from "../provider/ProviderRegistry.ts";
+import * as PluginMcpTools from "../plugins/PluginMcpTools.ts";
 import * as AnalyticsService from "../telemetry/AnalyticsService.ts";
 import {
   type AgentThread,
@@ -1140,6 +1141,53 @@ export const layerDeviceToolkit = Layer.mergeAll(
   layerDeviceScreenshotRegistration,
 );
 
+const isJsonObject = Schema.is(Schema.JsonObject);
+
+const pluginToolResult = (output: Schema.Json) =>
+  new McpSchema.CallToolResult({
+    isError: false,
+    ...(isJsonObject(output) ? { structuredContent: output } : {}),
+    content: [{ type: "text", text: JSON.stringify(output) }],
+  });
+
+const pluginToolFailure = (error: { readonly message: string }) =>
+  new McpSchema.CallToolResult({ isError: true, content: [{ type: "text", text: error.message }] });
+
+/**
+ * Plugins add tools while the server runs, so they register here directly instead of through
+ * a toolkit. Kept out of `layerTools`: with no plugin installed there are none to measure.
+ */
+export const layerPluginTools = Layer.effectDiscard(
+  Effect.gen(function* () {
+    const server = yield* McpServer.McpServer;
+    const plugins = yield* PluginMcpTools.PluginMcpTools;
+    const threads = yield* ThreadManagementService.ThreadManagementService;
+    yield* plugins.attach((entry) => {
+      const call = McpToolAccess.dynamic(entry.access, entry.call);
+      return server.addTool({
+        tool: new McpSchema.Tool({
+          name: entry.name,
+          description: entry.description,
+          inputSchema: entry.inputSchema,
+          annotations: { readOnlyHint: entry.access === "read" },
+        }),
+        annotations: Context.empty(),
+        handle: (payload) =>
+          Effect.withFiber((fiber) =>
+            call(isJsonObject(payload) ? payload : {}).pipe(
+              Effect.provideService(
+                McpInvocationContext.McpInvocationContext,
+                Context.getUnsafe(fiber.context, McpInvocationContext.McpInvocationContext),
+              ),
+              Effect.provideService(ThreadManagementService.ThreadManagementService, threads),
+              Effect.match({ onFailure: pluginToolFailure, onSuccess: pluginToolResult }),
+            ),
+          ),
+      });
+    });
+  }),
+).pipe(Layer.provide(McpServer.McpServer.layer));
+
 export const layerMcpTransport = McpServer.layerHttp({
   name: "T3 Code",
   version: packageJson.version,
@@ -1148,7 +1196,7 @@ export const layerMcpTransport = McpServer.layerHttp({
   allowSessionTermination: true,
 }).pipe(Layer.provide(layerMcpAuthMiddleware));
 
-/** Every tool the T3 MCP server advertises. AgentContextBudget.test.ts measures this set. */
+/** Every built-in tool the T3 MCP server advertises. AgentContextBudget.test.ts measures this set. */
 export const layerTools = Layer.mergeAll(
   layerPreviewToolkit,
   layerOrchestratorToolkit,
@@ -1163,4 +1211,6 @@ export const layerTools = Layer.mergeAll(
   layerHtmlToolkit,
 );
 
-export const layer = layerTools.pipe(Layer.provideMerge(layerMcpTransport));
+export const layer = Layer.merge(layerTools, layerPluginTools).pipe(
+  Layer.provideMerge(layerMcpTransport),
+);

apps/server/src/mcp/McpToolAccess.ts

@@ -173,6 +173,23 @@ export const writesWithCapability = <P, A, E, R>(handle: (params: P) => Effect.E
     () => writingCaller,
   );
 
+/**
+ * For tools whose access is data, registered while the server runs (plugin tools): `read`
+ * checks like `reads`; `write` like `writesEnvironment`, because a plugin tool can do anything
+ * the plugin can, and its handler never sees the caller's limits. Returns the checked handler.
+ */
+export const dynamic = <P, A, E, R>(
+  access: "read" | "write",
+  handle: (params: P) => Effect.Effect<A, E, R>,
+) => {
+  const declaration: Declaration<
+    (params: P) => Effect.Effect<A, E | OrchestratorMcpFailure, R | WritingServices>
+  > = access === "read" ? reads(handle) : writesEnvironment((params: P) => handle(params));
+  return checkedHandler(declaration);
+};
+
+type WritingServices = Effect.Services<typeof writingCaller>;
+
 export const writesThreads = <P, A, E, R>(
   threads: (params: P) => ReadonlyArray<ThreadId | undefined>,
   handle: (params: P) => Effect.Effect<A, E, R>,

apps/server/src/observability/RpcInstrumentation.ts

@@ -87,6 +87,17 @@ const RPC_AGGREGATES = {
   [WS_METHODS.serverRefreshUsageRates]: "server",
   [WS_METHODS.serverSignalProcess]: "server",
   [WS_METHODS.serverReportClientActivity]: "server",
+  [WS_METHODS.pluginsList]: "plugins",
+  [WS_METHODS.pluginsSubscribeStates]: "plugins",
+  [WS_METHODS.pluginsSetEnabled]: "plugins",
+  [WS_METHODS.pluginsReload]: "plugins",
+  [WS_METHODS.pluginsInstall]: "plugins",
+  [WS_METHODS.pluginsUninstall]: "plugins",
+  [WS_METHODS.pluginsUpdate]: "plugins",
+  [WS_METHODS.pluginsSettingsGet]: "plugins",
+  [WS_METHODS.pluginsSettingsUpdate]: "plugins",
+  [WS_METHODS.pluginsInvoke]: "plugins",
+  [WS_METHODS.pluginsSubscribe]: "plugins",
   [WS_METHODS.scheduledTasksSubscribe]: "scheduledTasks",
   [WS_METHODS.scheduledTasksUpsert]: "scheduledTasks",
   [WS_METHODS.scheduledTasksSetEnabled]: "scheduledTasks",

apps/server/src/orchestration-v2/Orchestrator.control-reads.test.ts

@@ -260,6 +260,63 @@ it.effect("marks a never-visited thread's first completion unread", () =>
   }).pipe(Effect.provide(layerTest)),
 );
 
+it.effect("files a plugin note under the latest finished run without starting a run", () =>
+  Effect.gen(function* () {
+    const orchestrator = yield* Orchestrator.OrchestratorV2;
+    const projections = yield* ProjectionStore.ProjectionStoreV2;
+    const threadId = ThreadId.make("thread:plugin-note");
+    yield* orchestrator.dispatch({
+      type: "thread.create",
+      commandId: CommandId.make("create-plugin-note"),
+      threadId,
+      projectId: ProjectId.make("project:plugin-note"),
+      title: "Plugin note",
+      modelSelection,
+      runtimeMode: "full-access",
+      interactionMode: "default",
+      branch: null,
+      worktreePath: null,
+      createdBy: "user",
+      creationSource: "web",
+    });
+    const dispatch = (id: string) =>
+      orchestrator.dispatch({
+        type: "message.dispatch",
+        commandId: CommandId.make(id),
+        threadId,
+        messageId: MessageId.make(id),
+        text: "Run in the background",
+        attachments: [],
+        dispatchMode: { type: "defer_start" },
+        createdBy: "agent",
+        creationSource: "mcp",
+      });
+    yield* dispatch("plugin-note-finished");
+    const finished = (yield* projections.getThreadProjection(threadId)).runs[0]!;
+    yield* orchestrator.dispatch({
+      type: "run.interrupt",
+      commandId: CommandId.make("interrupt-plugin-note"),
+      threadId,
+      runId: finished.id,
+    });
+    // A later run that hasn't finished must not receive the note.
+    yield* dispatch("plugin-note-pending");
+    yield* orchestrator.dispatch({
+      type: "thread.notification.record",
+      commandId: CommandId.make("record-plugin-note"),
+      threadId,
+      turnItemId: TurnItemId.make("plugin-note"),
+      notification: { source: { kind: "system" }, outcome: "updated", summary: "Digest: done" },
+    });
+    const projection = yield* projections.getThreadProjection(threadId);
+    assert.equal(projection.runs.length, 2);
+    const finishedItems = projection.turnItems.filter((item) => item.runId === finished.id);
+    const note = finishedItems.find((item) => item.id === "plugin-note");
+    assert.equal(note?.type, "notification");
+    assert.equal(note?.ordinal, Math.max(...finishedItems.map((item) => item.ordinal)));
+  }).pipe(Effect.provide(layerTest)),
+);
+
 const completeAndSnoozeThread = Effect.fn("test.completeAndSnoozeThread")(function* (
   name: string,
   snoozeMinutes: number,