diff --git a/apps/desktop/src/window/DesktopWindow.ts b/apps/desktop/src/window/DesktopWindow.ts
index 10801089841d1..dec6764b00aed 100644
--- a/apps/desktop/src/window/DesktopWindow.ts
+++ b/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,
diff --git a/apps/desktop/src/window/pluginViewNavigation.test.ts b/apps/desktop/src/window/pluginViewNavigation.test.ts
new file mode 100644
index 0000000000000..7852ad0a71c7e
--- /dev/null
+++ b/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);
+ }
+ });
+});
diff --git a/apps/desktop/src/window/pluginViewNavigation.ts b/apps/desktop/src/window/pluginViewNavigation.ts
new file mode 100644
index 0000000000000..ac3902e8cadeb
--- /dev/null
+++ b/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;
+}
diff --git a/apps/mobile/src/Stack.tsx b/apps/mobile/src/Stack.tsx
index 872ca142c8aaa..cc209c139aa48 100644
--- a/apps/mobile/src/Stack.tsx
+++ b/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: {
+
diff --git a/apps/mobile/src/features/keyboard/CommandPalette.tsx b/apps/mobile/src/features/keyboard/CommandPalette.tsx
index 841eaae7c6dc2..4ec518df2540f 100644
--- a/apps/mobile/src/features/keyboard/CommandPalette.tsx
+++ b/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 = {
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,
diff --git a/apps/mobile/src/features/keyboard/commandPaletteItems.test.ts b/apps/mobile/src/features/keyboard/commandPaletteItems.test.ts
index b5a57c2e23ed5..3e4b106a019b7 100644
--- a/apps/mobile/src/features/keyboard/commandPaletteItems.test.ts
+++ b/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([]);
+ });
+});
diff --git a/apps/mobile/src/features/keyboard/commandPaletteItems.ts b/apps/mobile/src/features/keyboard/commandPaletteItems.ts
index 4207a85b095ef..51f6b28e5a498 100644
--- a/apps/mobile/src/features/keyboard/commandPaletteItems.ts
+++ b/apps/mobile/src/features/keyboard/commandPaletteItems.ts
@@ -1,3 +1,11 @@
+import { pluginActionLabels, pluginActionsAt } from "@t3tools/client-runtime/state/pluginActions";
+import type {
+ EnvironmentId,
+ PluginAction,
+ PluginActionTarget,
+ ProjectId,
+ ThreadId,
+} from "@t3tools/contracts";
import type { EnvironmentProject } from "@t3tools/client-runtime/state/shell";
import {
foldSearchQuery,
@@ -106,3 +114,37 @@ export function filterCommandPaletteItems(
export function nextPaletteIndex(index: number, direction: -1 | 1, count: number) {
return count === 0 ? 0 : (index + direction + count) % count;
}
+
+/**
+ * The palette plugin actions of one environment, for the open thread and its
+ * project when there is one. Running one needs `orchestration:operate`, so a
+ * connection without it is offered none.
+ */
+export function buildPluginActionPaletteItems(input: {
+ readonly actions: ReadonlyArray;
+ readonly canOperate: boolean;
+ readonly environmentId: EnvironmentId;
+ readonly threadId: ThreadId | null;
+ readonly projectId: ProjectId | null;
+ readonly runAction: (input: {
+ readonly environmentId: EnvironmentId;
+ readonly action: PluginAction;
+ readonly target: PluginActionTarget;
+ }) => void;
+}): CommandPaletteItem[] {
+ if (!input.canOperate) return [];
+ const { environmentId } = input;
+ const entries = pluginActionsAt(input.actions, "command-palette", {
+ threadId: input.threadId,
+ projectId: input.projectId,
+ });
+ const labels = pluginActionLabels(entries.map((entry) => entry.action));
+ return entries.map(({ action, target }, index) => ({
+ key: `plugin-action:${action.id}`,
+ kind: "action",
+ title: labels[index] ?? action.title,
+ detail: action.description ?? action.pluginName,
+ searchTerms: [action.name, action.pluginName, "plugin"],
+ run: () => input.runAction({ environmentId, action, target }),
+ }));
+}
diff --git a/apps/mobile/src/features/plugins/PluginNotificationBannerHost.tsx b/apps/mobile/src/features/plugins/PluginNotificationBannerHost.tsx
new file mode 100644
index 0000000000000..174ff24e7b226
--- /dev/null
+++ b/apps/mobile/src/features/plugins/PluginNotificationBannerHost.tsx
@@ -0,0 +1,168 @@
+import { useAtomValue } from "@effect/atom-react";
+import { useLinkTo } from "@react-navigation/native";
+import {
+ pluginNotificationChanges,
+ pluginNotificationDescription,
+ type PluginNotificationMark,
+ type ReceivedPluginNotification,
+} from "@t3tools/client-runtime/state/plugin-notifications";
+import type { ContributionStatusTone, EnvironmentId } from "@t3tools/contracts";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { AccessibilityInfo, Platform, Pressable, View } from "react-native";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+
+import { AppText as Text } from "../../components/ui/AppText";
+import { cn } from "../../lib/cn";
+import { useEnvironments } from "../../state/environments";
+import { pluginNotificationEnvironment } from "../../state/plugin-notifications";
+import {
+ type Banner,
+ queueBannerChanges,
+ removeEnvironmentBanners,
+} from "./plugin-notification-banners";
+
+const SHOWN_MS = 5_000;
+
+const TONE_DOT_CLASS = {
+ neutral: "bg-foreground-muted",
+ info: "bg-adaptive-sky-600-400",
+ success: "bg-adaptive-emerald-600-400",
+ warning: "bg-adaptive-amber-700-400",
+ error: "bg-adaptive-rose-600-400",
+} as const satisfies Record;
+
+// Deliver transient notifications to the mounted native client; retained history is suppressed.
+// Withdraw banners with server retention or environment removal, and announce each fresh banner to accessibility.
+export function PluginNotificationBannerHost() {
+ const { environments } = useEnvironments();
+ const [queue, setQueue] = useState>([]);
+ const onChanges = useCallback(
+ (
+ environmentId: EnvironmentId,
+ show: ReadonlyArray,
+ keep: ReadonlySet,
+ ) => setQueue((current) => queueBannerChanges(current, environmentId, show, keep)),
+ [],
+ );
+ const onRemoved = useCallback(
+ (environmentId: EnvironmentId) =>
+ setQueue((current) => removeEnvironmentBanners(current, environmentId)),
+ [],
+ );
+ const dismiss = useCallback(
+ (banner: Banner) => setQueue((current) => current.filter((each) => each !== banner)),
+ [],
+ );
+ const head = queue[0];
+
+ // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- Own the dismissal timer for the currently displayed native banner.
+ useEffect(() => {
+ if (head === undefined) return;
+ const timer = setTimeout(() => dismiss(head), SHOWN_MS);
+ return () => clearTimeout(timer);
+ }, [dismiss, head]);
+
+ return (
+ <>
+ {environments.map((environment) => (
+
+ ))}
+ {head === undefined ? null : (
+ // A fresh mount per notification, so two identical ones are both announced.
+
+ )}
+
+ );
+}
+
+function EnvironmentPluginNotifications(props: {
+ readonly environmentId: EnvironmentId;
+ readonly onChanges: (
+ environmentId: EnvironmentId,
+ show: ReadonlyArray,
+ keep: ReadonlySet,
+ ) => void;
+ readonly onRemoved: (environmentId: EnvironmentId) => void;
+}) {
+ const { environmentId, onChanges, onRemoved } = props;
+ const frame = useAtomValue(pluginNotificationEnvironment.frame(environmentId));
+ // The newest notification seen; banners themselves live in the host's queue.
+ const mark = useRef(undefined);
+
+ // Unmounting means the environment was removed, so no later frame will drop its banners.
+ // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- Withdraw this environment’s delivered banners when its subscription host unmounts.
+ useEffect(() => () => onRemoved(environmentId), [environmentId, onRemoved]);
+
+ // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- Consume retained server frames as delivery events while this notification host is mounted.
+ useEffect(() => {
+ const changes = pluginNotificationChanges(mark.current, frame);
+ mark.current = changes.mark;
+ onChanges(environmentId, changes.show, changes.keep);
+ }, [environmentId, frame, onChanges]);
+
+ return null;
+}
+
+function PluginNotificationBanner(props: {
+ readonly banner: Banner;
+ readonly onDone: (banner: Banner) => void;
+}) {
+ const { banner, onDone } = props;
+ const insets = useSafeAreaInsets();
+ const linkTo = useLinkTo();
+ const { threadId, title, tone } = banner.entry.notification;
+ const description = pluginNotificationDescription(banner.entry);
+ // The banner leaves on its own, so it is announced rather than waiting for
+ // focus: accessibilityLiveRegion reaches TalkBack, VoiceOver needs this.
+ // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- Announce each newly mounted banner to the native VoiceOver service.
+ useEffect(() => {
+ if (Platform.OS === "ios")
+ AccessibilityInfo.announceForAccessibility(`${title}. ${description}`);
+ }, [title, description]);
+
+ return (
+
+ {
+ onDone(banner);
+ if (threadId !== undefined)
+ linkTo(
+ `/threads/${encodeURIComponent(banner.environmentId)}/${encodeURIComponent(threadId)}`,
+ );
+ }}
+ >
+
+
+
+ {title}
+
+
+ {description}
+
+
+
+
+ );
+}
diff --git a/apps/mobile/src/features/plugins/PluginSettingsSections.tsx b/apps/mobile/src/features/plugins/PluginSettingsSections.tsx
new file mode 100644
index 0000000000000..ba95d13bf1762
--- /dev/null
+++ b/apps/mobile/src/features/plugins/PluginSettingsSections.tsx
@@ -0,0 +1,51 @@
+import { useAtomValue } from "@effect/atom-react";
+import { supportsPluginSettings } from "@t3tools/client-runtime/state/pluginSettings";
+import type { EnvironmentId, ExecutionEnvironmentCapabilities } from "@t3tools/contracts";
+import * as Option from "effect/Option";
+import { AsyncResult } from "effect/reactivity";
+
+import { AppText as Text } from "../../components/ui/AppText";
+import { pluginEnvironment } from "../../state/plugins";
+import { PluginSettingsValues } from "./PluginSettingsValues";
+
+/**
+ * The saved settings of each installed plugin that declares any, read-only:
+ * mobile always pairs with standard scopes, so it cannot save them. Renders
+ * nothing on a server without plugin settings or when no plugin declares any.
+ */
+export function PluginSettingsSections({
+ environmentId,
+ capabilities,
+}: {
+ readonly environmentId: EnvironmentId;
+ readonly capabilities: ExecutionEnvironmentCapabilities | undefined;
+}) {
+ if (!supportsPluginSettings(capabilities)) return null;
+ return ;
+}
+
+function InstalledPluginSettings({ environmentId }: { readonly environmentId: EnvironmentId }) {
+ const catalog = Option.getOrNull(
+ AsyncResult.value(useAtomValue(pluginEnvironment.catalog({ environmentId, input: {} }))),
+ );
+ if (catalog?._tag !== "available") return null;
+ const installations = catalog.installations.filter(
+ (installation) => (installation.manifest?.settings?.length ?? 0) > 0,
+ );
+ if (installations.length === 0) return null;
+ return (
+ <>
+ {installations.map((installation) => (
+
+ ))}
+
+ Plugin settings are view-only on mobile. Edit them from an administrative web or desktop
+ connection.
+
+
+ );
+}
diff --git a/apps/mobile/src/features/plugins/PluginSettingsValues.logic.test.ts b/apps/mobile/src/features/plugins/PluginSettingsValues.logic.test.ts
new file mode 100644
index 0000000000000..e3051a18f0c13
--- /dev/null
+++ b/apps/mobile/src/features/plugins/PluginSettingsValues.logic.test.ts
@@ -0,0 +1,58 @@
+import { pluginSettingRows } from "@t3tools/client-runtime/state/pluginSettings";
+import {
+ type PluginSettingField,
+ PluginInstallationId,
+ type PluginSettingsValues,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { describePluginSettingValue } from "./PluginSettingsValues.logic";
+
+const fields: ReadonlyArray = [
+ { type: "number", key: "retries", label: "Retries", min: 0, max: 5, integer: true, default: 2 },
+ {
+ type: "select",
+ key: "mode",
+ label: "Mode",
+ options: [
+ { value: "safe", label: "Safe" },
+ { value: "fast", label: "Fast" },
+ ],
+ default: "safe",
+ },
+ { type: "secret", key: "token", label: "Token" },
+];
+const shown = (saved: PluginSettingsValues["values"], secrets: ReadonlyArray = []) =>
+ pluginSettingRows(fields, {
+ installationId: PluginInstallationId.make("installation-1"),
+ values: saved,
+ secrets,
+ }).map(describePluginSettingValue);
+
+describe("describePluginSettingValue", () => {
+ it("marks defaults when nothing is saved", () => {
+ expect(shown([])).toEqual(["2 (default)", "Safe (default)", "Not set"]);
+ });
+
+ it("shows saved values that still fit without a default label", () => {
+ expect(
+ shown(
+ [
+ { key: "retries", value: 4 },
+ { key: "mode", value: "fast" },
+ ],
+ ["token"],
+ ),
+ ).toEqual(["4", "Fast", "Saved"]);
+ });
+
+ it("marks the default a saved value fell back to once it no longer fits", () => {
+ // Saved before an update narrowed the range and removed the option.
+ expect(
+ shown([
+ { key: "retries", value: 9 },
+ { key: "mode", value: "turbo" },
+ ]),
+ ).toEqual(["2 (default)", "Safe (default)", "Not set"]);
+ });
+});
diff --git a/apps/mobile/src/features/plugins/PluginSettingsValues.logic.ts b/apps/mobile/src/features/plugins/PluginSettingsValues.logic.ts
new file mode 100644
index 0000000000000..c515c1a88dc65
--- /dev/null
+++ b/apps/mobile/src/features/plugins/PluginSettingsValues.logic.ts
@@ -0,0 +1,17 @@
+import type { PluginSettingRow } from "@t3tools/client-runtime/state/pluginSettings";
+
+/** A field's value as text; a secret shows only whether one is saved. */
+export function describePluginSettingValue({ field, value, saved, isDefault }: PluginSettingRow) {
+ if (field.type === "secret") return saved ? "Saved" : "Not set";
+ if (value === undefined) return "Not set";
+ const text =
+ field.type === "boolean"
+ ? value === true
+ ? "On"
+ : "Off"
+ : field.type === "select"
+ ? (field.options.find((option) => option.value === value)?.label ?? String(value))
+ : String(value);
+ // A saved value that no longer fits falls back to the default, and says so.
+ return isDefault ? `${text} (default)` : text;
+}
diff --git a/apps/mobile/src/features/plugins/PluginSettingsValues.tsx b/apps/mobile/src/features/plugins/PluginSettingsValues.tsx
new file mode 100644
index 0000000000000..88bc9c81c96b7
--- /dev/null
+++ b/apps/mobile/src/features/plugins/PluginSettingsValues.tsx
@@ -0,0 +1,50 @@
+import { useAtomValue } from "@effect/atom-react";
+import { pluginSettingRows } from "@t3tools/client-runtime/state/pluginSettings";
+import type { EnvironmentId, PluginInstallation } from "@t3tools/contracts";
+import * as Option from "effect/Option";
+import { AsyncResult } from "effect/reactivity";
+import { View } from "react-native";
+
+import { AppText as Text } from "../../components/ui/AppText";
+import { pluginSettingsEnvironment } from "../../state/plugins";
+import { SettingsSection } from "../settings/components/SettingsSection";
+import { describePluginSettingValue } from "./PluginSettingsValues.logic";
+
+/**
+ * The settings one installation declares and what is saved for them, read-only.
+ * Renders nothing when the plugin declares none or the server cannot store them.
+ */
+export function PluginSettingsValues({
+ environmentId,
+ installation,
+}: {
+ readonly environmentId: EnvironmentId;
+ readonly installation: PluginInstallation;
+}) {
+ const fields = installation.manifest?.settings ?? [];
+ const result = useAtomValue(
+ pluginSettingsEnvironment.values({
+ environmentId,
+ input: { installationId: installation.installationId },
+ }),
+ );
+ const view = Option.getOrNull(AsyncResult.value(result));
+ if (fields.length === 0 || view === null || view._tag === "unsupported") return null;
+ return (
+
+ {pluginSettingRows(fields, view.values).map((row, index) => (
+ 0 ? "gap-1 border-t border-border-subtle px-4 py-3" : "gap-1 px-4 py-3"
+ }
+ >
+ {row.field.label}
+
+ {describePluginSettingValue(row)}
+
+
+ ))}
+
+ );
+}
diff --git a/apps/mobile/src/features/plugins/plugin-notification-banners.test.ts b/apps/mobile/src/features/plugins/plugin-notification-banners.test.ts
new file mode 100644
index 0000000000000..8ced7a29728fe
--- /dev/null
+++ b/apps/mobile/src/features/plugins/plugin-notification-banners.test.ts
@@ -0,0 +1,73 @@
+import {
+ pluginNotificationChanges,
+ type PluginNotificationMark,
+} from "@t3tools/client-runtime/state/plugin-notifications";
+import { EnvironmentId, type PluginNotificationFrame } from "@t3tools/contracts";
+import { expect, it } from "vite-plus/test";
+
+import {
+ type Banner,
+ queueBannerChanges,
+ removeEnvironmentBanners,
+} from "./plugin-notification-banners";
+
+const A = EnvironmentId.make("env-a");
+const B = EnvironmentId.make("env-b");
+
+/** The same epoch and sequences in each environment, so only the environment differs. */
+const frame = (titles: ReadonlyArray): PluginNotificationFrame => ({
+ epoch: "epoch-1",
+ notifications: titles.map((title, index) => ({
+ sequence: index + 1,
+ pluginId: "acme.notifier",
+ pluginName: "Notifier",
+ title,
+ createdAt: "2026-10-04T00:00:00.000Z",
+ })),
+});
+
+/** Feeds frames through the shared helper as each environment's host component does. */
+function receive(
+ queue: ReadonlyArray,
+ marks: Map,
+ environmentId: EnvironmentId,
+ next: PluginNotificationFrame,
+) {
+ const changes = pluginNotificationChanges(marks.get(environmentId), next);
+ marks.set(environmentId, changes.mark);
+ return queueBannerChanges(queue, environmentId, changes.show, changes.keep);
+}
+
+const shown = (queue: ReadonlyArray) =>
+ queue.map((banner) => `${banner.environmentId}:${banner.entry.notification.title}`);
+
+it("drops a removed environment's queued banners and keeps the others", () => {
+ const marks = new Map();
+ let queue: ReadonlyArray = [];
+ queue = receive(queue, marks, A, frame([]));
+ queue = receive(queue, marks, B, frame([]));
+ queue = receive(queue, marks, A, frame(["a1", "a2"]));
+ queue = receive(queue, marks, B, frame(["b1"]));
+ expect(shown(queue)).toEqual(["env-a:a1", "env-a:a2", "env-b:b1"]);
+
+ queue = removeEnvironmentBanners(queue, A);
+ expect(shown(queue)).toEqual(["env-b:b1"]);
+ expect(removeEnvironmentBanners(queue, A)).toBe(queue);
+});
+
+it("queues each notification once across reconnects and drops what left the set", () => {
+ const marks = new Map();
+ let queue: ReadonlyArray = [];
+ // Launch: what the server already held is not news.
+ queue = receive(queue, marks, A, frame(["old"]));
+ expect(shown(queue)).toEqual([]);
+ queue = receive(queue, marks, A, frame(["old", "first"]));
+ // Back online after missing one, then a second reconnect with nothing new.
+ queue = receive(queue, marks, A, frame(["old", "first", "missed"]));
+ const settled = receive(queue, marks, A, frame(["old", "first", "missed"]));
+ expect(settled).toBe(queue);
+ expect(shown(queue)).toEqual(["env-a:first", "env-a:missed"]);
+ // The plugin was disabled while the app was away: its banners go on reconnect.
+ queue = receive(queue, marks, A, frame(["old"]));
+ expect(shown(queue)).toEqual([]);
+});
diff --git a/apps/mobile/src/features/plugins/plugin-notification-banners.ts b/apps/mobile/src/features/plugins/plugin-notification-banners.ts
new file mode 100644
index 0000000000000..886253269a2a1
--- /dev/null
+++ b/apps/mobile/src/features/plugins/plugin-notification-banners.ts
@@ -0,0 +1,36 @@
+import type { ReceivedPluginNotification } from "@t3tools/client-runtime/state/plugin-notifications";
+import type { EnvironmentId } from "@t3tools/contracts";
+
+/** Banners waiting their turn; older ones are dropped past this. */
+const MAX_QUEUED_BANNERS = 5;
+
+export interface Banner {
+ readonly environmentId: EnvironmentId;
+ readonly entry: ReceivedPluginNotification;
+}
+
+/**
+ * Applies one environment's frame: drops its banners the server no longer
+ * retains and queues the new ones. Returns `queue` itself when nothing changed.
+ */
+export function queueBannerChanges(
+ queue: ReadonlyArray,
+ environmentId: EnvironmentId,
+ show: ReadonlyArray,
+ keep: ReadonlySet,
+): ReadonlyArray {
+ const kept = queue.filter(
+ (banner) => banner.environmentId !== environmentId || keep.has(banner.entry.key),
+ );
+ if (show.length === 0 && kept.length === queue.length) return queue;
+ return [...kept, ...show.map((entry) => ({ environmentId, entry }))].slice(-MAX_QUEUED_BANNERS);
+}
+
+/** Drops a removed environment's banners, which no later frame would. */
+export function removeEnvironmentBanners(
+ queue: ReadonlyArray,
+ environmentId: EnvironmentId,
+): ReadonlyArray {
+ const kept = queue.filter((banner) => banner.environmentId !== environmentId);
+ return kept.length === queue.length ? queue : kept;
+}
diff --git a/apps/mobile/src/features/settings/SettingsEnvironmentDetailRouteScreen.tsx b/apps/mobile/src/features/settings/SettingsEnvironmentDetailRouteScreen.tsx
index 5f83979197bbc..9217aa16ec8aa 100644
--- a/apps/mobile/src/features/settings/SettingsEnvironmentDetailRouteScreen.tsx
+++ b/apps/mobile/src/features/settings/SettingsEnvironmentDetailRouteScreen.tsx
@@ -27,6 +27,7 @@ import { useAtomCommand } from "../../state/use-atom-command";
import { useRemoteConnections } from "../../state/use-remote-environment-registry";
import { ConnectionEnvironmentRow } from "../connection/ConnectionEnvironmentRow";
import { EnvironmentRoutesSection } from "./EnvironmentRoutesSection";
+import { PluginSettingsSections } from "../plugins/PluginSettingsSections";
import { OutdatedServerUpdateSection } from "./OutdatedServerUpdateSection";
import { ListActionRow as SettingsActionRow } from "../../components/ui/ListActionRow";
import { SettingsScreen } from "./components/SettingsScreen";
@@ -364,6 +365,7 @@ function EnvironmentDetail({ environmentId }: { readonly environmentId: Environm
))}
+
) : null}
diff --git a/apps/mobile/src/features/settings/SettingsPluginsRouteScreen.tsx b/apps/mobile/src/features/settings/SettingsPluginsRouteScreen.tsx
new file mode 100644
index 0000000000000..3f45bf6009948
--- /dev/null
+++ b/apps/mobile/src/features/settings/SettingsPluginsRouteScreen.tsx
@@ -0,0 +1,587 @@
+import { useNavigation, type StaticScreenProps } from "@react-navigation/native";
+import type { NativeStackNavigationProp } from "@react-navigation/native-stack";
+import {
+ type EnvironmentId,
+ type PluginInstallation,
+ type PluginInstallationId,
+ type PluginInstallationManifest,
+ type PluginNpmPackage,
+ resolveEnvironmentMachineKind,
+} from "@t3tools/contracts";
+import {
+ describePluginCapabilities,
+ describePluginContributions,
+ type PluginOfferedViews,
+} from "@t3tools/client-runtime/state/pluginContributions";
+import {
+ describePluginNpmSource,
+ PLUGIN_NPM_INTEGRITY_STATEMENT,
+ pluginNpmListKey,
+ pluginNpmRowLabel,
+ resolvePluginNpmPackagesState,
+ resolvePluginNpmProvenance,
+ supportsPluginNpm,
+} from "@t3tools/client-runtime/state/pluginNpmPresentation";
+import {
+ describePluginSource,
+ presentPluginInstallation,
+ resolvePluginCatalogState,
+ resolvePluginDetail,
+ type PluginStateTone,
+} from "@t3tools/client-runtime/state/pluginPresentation";
+import { useEffect, useRef } from "react";
+import { Platform, Pressable, View } from "react-native";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+
+import { AppText as Text } from "../../components/ui/AppText";
+import { SymbolView } from "../../components/ui/AppSymbol";
+import { EnvironmentMachineSymbol } from "../../components/EnvironmentMachineSymbol";
+import { ScreenScrollView as ScrollView } from "../../components/ui/ScreenScrollView";
+import { usePluginActionsSnapshot } from "../../state/plugin-actions";
+import {
+ pluginEnvironment,
+ pluginNpmEnvironment,
+ pluginViewEnvironment,
+} from "../../state/plugins";
+import { useEnvironmentQuery } from "../../state/query";
+import { ListActionRow as SettingsActionRow } from "../../components/ui/ListActionRow";
+import {
+ AndroidSettingsEnvironmentFilter,
+ SettingsEnvironmentFilterHeader,
+} from "./components/SettingsEnvironmentFilterHeader";
+import { SettingsScreen } from "./components/SettingsScreen";
+import { SettingsSection } from "./components/SettingsSection";
+import { useSettingsEnvironmentFilter, type SettingsTarget } from "./settings-environment-filter";
+
+type PluginRoutes = {
+ SettingsPlugin: {
+ readonly environmentId: EnvironmentId;
+ readonly installationId: PluginInstallationId;
+ };
+};
+
+const TONE_TEXT: Record = {
+ neutral: "text-foreground-muted",
+ success: "text-foreground",
+ info: "text-foreground",
+ warning: "text-warning-foreground",
+ error: "text-danger-foreground",
+};
+
+/** Whether this environment's server has the plugin catalogue; older servers never get a plugin call. */
+export function supportsPlugins(target: SettingsTarget): boolean {
+ return target.serverConfig.environment.capabilities.plugins === true;
+}
+
+/**
+ * Mobile always pairs with standard scopes, so it never has the access:write that
+ * plugin management needs; it shows plugins without controls.
+ */
+const PLUGINS_VIEW_ONLY =
+ "Plugins are view-only on mobile. Add, install, approve, enable, update, or remove them from an administrative web or desktop connection.";
+
+function ViewOnlyNotice() {
+ return {PLUGINS_VIEW_ONLY};
+}
+
+/** The catalogue of a connected environment that supports plugins; anything else gets no call. */
+function usePluginCatalog(environmentId: EnvironmentId, environment: SettingsTarget | undefined) {
+ const supported = environment !== undefined && supportsPlugins(environment);
+ const catalog = useEnvironmentQuery(
+ supported ? pluginEnvironment.catalog({ environmentId, input: {} }) : null,
+ );
+ const state = resolvePluginCatalogState({
+ connected: environment !== undefined,
+ data: supported ? catalog.data : { _tag: "unsupported" },
+ error: catalog.error,
+ });
+ return { state, retry: catalog.refresh };
+}
+
+/** Calls `refresh` when `key` changes from one known value to another; never on a timer. */
+function useRefreshOnChange(key: string | null, refresh: () => void) {
+ const last = useRef(key);
+ // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- Invalidate the external npm query cache when catalogue provenance changes.
+ useEffect(() => {
+ const previous = last.current;
+ last.current = key;
+ if (previous !== null && key !== null && previous !== key) refresh();
+ }, [key, refresh]);
+}
+
+/**
+ * Where an environment's plugins came from on npm. An older server gets no call.
+ * The list is a query, so it is read again when installations or their files change.
+ */
+function usePluginNpmPackages(
+ environmentId: EnvironmentId,
+ environment: SettingsTarget | undefined,
+ installations: ReadonlyArray | null,
+) {
+ const supported =
+ environment !== undefined &&
+ supportsPluginNpm(environment.serverConfig.environment.capabilities);
+ const query = useEnvironmentQuery(
+ supported ? pluginNpmEnvironment.packages({ environmentId, input: {} }) : null,
+ );
+ useRefreshOnChange(
+ supported && installations !== null ? pluginNpmListKey(installations) : null,
+ query.refresh,
+ );
+ return {
+ state: resolvePluginNpmPackagesState({ supported, data: query.data, error: query.error }),
+ refresh: query.refresh,
+ };
+}
+
+const SCROLL_PROPS = {
+ keyboardShouldPersistTaps: "handled",
+ contentInsetAdjustmentBehavior: "automatic",
+ showsVerticalScrollIndicator: false,
+ className: "flex-1",
+ contentContainerClassName: "gap-5 px-5 pt-4",
+} as const;
+
+export function SettingsPluginsRouteScreen() {
+ const insets = useSafeAreaInsets();
+ const { availableTargets, selectedTargets } = useSettingsEnvironmentFilter();
+ const targets = selectedTargets.filter(supportsPlugins);
+ return (
+ <>
+
+ }>
+
+ {targets.length > 0 ? (
+ targets.map((target) => (
+
+ ))
+ ) : (
+
+ {availableTargets.length === 0
+ ? "Connect an environment to see its plugins."
+ : selectedTargets.length === 0
+ ? "Select an environment to see its plugins."
+ : "Update T3 Code on the selected environments to see their plugins."}
+
+ )}
+
+
+
+ );
+}
+
+function EnvironmentPlugins({ environment }: { readonly environment: SettingsTarget }) {
+ const navigation = useNavigation>();
+ const environmentId = environment.environmentId;
+ const catalog = usePluginCatalog(environmentId, environment);
+ const installations =
+ catalog.state._tag === "available" ? catalog.state.view.installations : null;
+ const npm = usePluginNpmPackages(environmentId, environment, installations);
+ if (catalog.state._tag === "unsupported") return null;
+ return (
+
+
+ }
+ >
+ {catalog.state._tag === "failed" ? (
+ <>
+ {catalog.state.message}
+
+
+
+
+ ) : installations === null ? (
+ Loading plugins…
+ ) : installations.length === 0 ? (
+ No plugins yet.
+ ) : (
+ installations.map((installation, index) => (
+
+ navigation.navigate("SettingsPlugin", {
+ environmentId,
+ installationId: installation.installationId,
+ })
+ }
+ />
+ ))
+ )}
+
+ {installations !== null ? : null}
+
+ );
+}
+
+/** The npm package behind a listed installation, from the list alone. */
+function npmPackageOf(
+ state: ReturnType,
+ installationId: PluginInstallationId,
+): PluginNpmPackage | null {
+ const provenance = resolvePluginNpmProvenance({ state, installationId, step: null });
+ return provenance._tag === "found" ? provenance.package : null;
+}
+
+function PluginListRow({
+ installation,
+ npmPackage,
+ first,
+ onPress,
+}: {
+ readonly installation: PluginInstallation;
+ readonly npmPackage: PluginNpmPackage | null;
+ readonly first: boolean;
+ readonly onPress: () => void;
+}) {
+ const view = presentPluginInstallation(installation);
+ return (
+
+
+
+ {view.title}
+ {installation.manifest ? (
+ {installation.manifest.version}
+ ) : null}
+
+
+ {view.stateLabel}
+ {view.detail ? ` · ${view.detail}` : ""}
+
+ {view.delivery ? (
+
+ {view.delivery.label}
+ {view.delivery.detail ? ` · ${view.delivery.detail}` : ""}
+
+ ) : null}
+ {npmPackage ? (
+
+ {pluginNpmRowLabel(npmPackage)}
+
+ ) : null}
+
+ {installation.directory}
+
+
+
+
+ );
+}
+
+/** Each declared capability on its own line, with what it lets the plugin do. */
+function capabilityLines(capabilities: ReadonlyArray): string {
+ if (capabilities.length === 0) return "None declared";
+ return describePluginCapabilities(capabilities)
+ .map((capability) =>
+ capability.meaning ? `${capability.name}: ${capability.meaning}` : capability.name,
+ )
+ .join("\n");
+}
+
+function DetailField({
+ label,
+ value,
+ mono = false,
+ first = false,
+}: {
+ readonly label: string;
+ readonly value: string;
+ readonly mono?: boolean;
+ readonly first?: boolean;
+}) {
+ return (
+
+ {label}
+
+ {value}
+
+
+ );
+}
+
+export function SettingsPluginRouteScreen({
+ route,
+}: StaticScreenProps) {
+ return (
+
+ );
+}
+
+function PluginDetail({
+ environmentId,
+ installationId,
+}: {
+ readonly environmentId: EnvironmentId;
+ readonly installationId: PluginInstallationId;
+}) {
+ const insets = useSafeAreaInsets();
+ const { availableTargets } = useSettingsEnvironmentFilter();
+ const environment = availableTargets.find((target) => target.environmentId === environmentId);
+ const label = environment?.label ?? "this environment";
+ const catalog = usePluginCatalog(environmentId, environment);
+ const detail = resolvePluginDetail({ catalog: catalog.state, installationId, added: null });
+ const npm = usePluginNpmPackages(
+ environmentId,
+ environment,
+ catalog.state._tag === "available" ? catalog.state.view.installations : null,
+ );
+
+ if (detail._tag !== "found") {
+ return (
+
+
+ {detail._tag === "failed" ? (
+
+
+ {detail.message}
+
+
+
+
+
+ ) : (
+
+ {detail._tag === "missing"
+ ? `This plugin is no longer installed on ${label}.`
+ : detail._tag === "loading"
+ ? "Loading plugin…"
+ : detail._tag === "disconnected"
+ ? `Reconnect ${label} to see its plugins.`
+ : `${label} does not support plugins. Update T3 Code there.`}
+
+ )}
+
+
+ );
+ }
+
+ const installation = detail.installation;
+ const view = presentPluginInstallation(installation);
+ const manifest = installation.manifest;
+ const digest = installation.source?.digest ?? null;
+ const provenance = resolvePluginNpmProvenance({ state: npm.state, installationId, step: null });
+ const npmPackage = provenance._tag === "found" ? provenance.package : null;
+
+ return (
+
+
+
+ {view.stateLabel}
+ {view.detail ? (
+
+ {view.detail}
+
+ ) : null}
+ {view.delivery ? (
+ <>
+
+ {view.delivery.label}
+
+ {view.delivery.detail ? (
+
+ {view.delivery.detail}
+
+ ) : null}
+
+ ) : null}
+
+
+ {manifest ? (
+ <>
+
+
+ {manifest.description ? (
+
+ ) : null}
+
+ ) : null}
+ {npmPackage ? (
+ <>
+
+
+
+ ) : provenance._tag === "unknown" ? (
+
+ ) : null}
+
+
+ {digest !== null ? : null}
+ {manifest ? (
+
+ ) : null}
+ {installation.problem ? (
+
+ ) : null}
+
+ {manifest ? (
+
+ ) : null}
+
+ {npm.state._tag === "failed" ? (
+
+
+ {npm.state.message}
+
+
+
+
+
+ ) : null}
+
+
+
+
+ );
+}
+
+/**
+ * What a plugin adds to T3 Code, from its manifest summary. For an enabled
+ * installation, the environment's action and view snapshots say what is offered
+ * now; listing them never starts the plugin.
+ */
+function PluginContributionsSection({
+ environmentId,
+ environment,
+ manifest,
+ installation,
+}: {
+ readonly environmentId: EnvironmentId;
+ readonly environment: SettingsTarget | undefined;
+ readonly manifest: PluginInstallationManifest;
+ readonly installation: PluginInstallation;
+}) {
+ const capabilities = environment?.serverConfig.environment.capabilities;
+ const offered = installation.enabled;
+ const actions = usePluginActionsSnapshot(
+ offered && capabilities?.pluginActions === true ? environmentId : null,
+ );
+ const views = useEnvironmentQuery(
+ offered && capabilities?.pluginViews === true
+ ? pluginViewEnvironment.views({ environmentId, input: {} })
+ : null,
+ ).data;
+ const offeredViews: PluginOfferedViews | null =
+ views?._tag === "available"
+ ? {
+ views: views.views.filter(
+ (view) =>
+ view.installationId === installation.installationId &&
+ view.generation === installation.generation,
+ ),
+ problems: views.problems.filter(
+ (problem) =>
+ problem.installationId === installation.installationId &&
+ problem.generation === installation.generation,
+ ),
+ }
+ : null;
+ const groups = describePluginContributions({
+ manifest,
+ installation,
+ actions: actions ?? null,
+ views: offeredViews,
+ });
+ return (
+
+ {groups.length === 0 ? (
+ Nothing declared
+ ) : (
+ groups.map((group, index) => (
+
+ {group.label}
+ {group.items.map((item) => (
+
+
+ {item.title}
+
+ {item.detail ? (
+
+ {item.detail}
+
+ ) : null}
+
+ ))}
+ {group.notice ? (
+ {group.notice}
+ ) : null}
+
+ ))
+ )}
+
+ );
+}
diff --git a/apps/mobile/src/features/settings/SettingsRouteScreen.tsx b/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
index 34de55fd44082..025c45281d2fd 100644
--- a/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
+++ b/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
@@ -35,6 +35,7 @@ import {
SettingsEnvironmentFilterHeader,
} from "./components/SettingsEnvironmentFilterHeader";
import { useSettingsEnvironmentFilter } from "./settings-environment-filter";
+import { supportsPlugins } from "./SettingsPluginsRouteScreen";
import { filterSettingsSections } from "./settings-search";
import { NativePrimaryColumnContext } from "../../native/v5-workspace-context";
@@ -258,6 +259,9 @@ function useSettingsIndexSections(): SettingsListSection[] {
serverPage("SettingsProviderAccounts", "person.crop.circle", "Providers"),
serverPage("SettingsThreads", "text.bubble", "Threads"),
page("SettingsScheduledTasks", "clock", "Scheduled tasks"),
+ ...(selectedTargets.some(supportsPlugins)
+ ? [page("SettingsPlugins", "cube", "Plugins")]
+ : []),
],
},
{
diff --git a/apps/mobile/src/features/settings/components/settings-page-targets.ts b/apps/mobile/src/features/settings/components/settings-page-targets.ts
index 6a98023f2ed7c..e07dae60000fc 100644
--- a/apps/mobile/src/features/settings/components/settings-page-targets.ts
+++ b/apps/mobile/src/features/settings/components/settings-page-targets.ts
@@ -18,6 +18,7 @@ export const SETTINGS_PAGE_TARGETS = [
"SettingsMicrophone",
"SettingsFollowUp",
"SettingsScheduledTasks",
+ "SettingsPlugins",
"SettingsProjectGrouping",
"SettingsClientStorage",
"SettingsDiagnostics",
diff --git a/apps/mobile/src/features/threads/ComposerCommandPopover.tsx b/apps/mobile/src/features/threads/ComposerCommandPopover.tsx
index cbe89f5fb8768..ea9d6d58573ea 100644
--- a/apps/mobile/src/features/threads/ComposerCommandPopover.tsx
+++ b/apps/mobile/src/features/threads/ComposerCommandPopover.tsx
@@ -3,6 +3,8 @@ import {
type ProviderSkillSourceKind,
} from "@t3tools/client-runtime/providerSkills";
import type {
+ PluginAction,
+ PluginActionTarget,
EnvironmentId,
EnvironmentMachineKind,
PullRequestContextMetadata,
@@ -71,6 +73,14 @@ export type ComposerCommandItem =
readonly skill: ServerProviderSkill;
readonly label: string;
readonly description: string;
+ }
+ | {
+ readonly id: string;
+ readonly type: "plugin-action";
+ readonly action: PluginAction;
+ readonly target: PluginActionTarget;
+ readonly label: string;
+ readonly description: string;
};
interface ComposerCommandPopoverProps {
@@ -121,6 +131,8 @@ function itemIcon(item: ComposerCommandItem): AppSymbolName | null {
return null;
case "thread":
return "text.bubble";
+ case "plugin-action":
+ return "cube";
case "environment":
return ENVIRONMENT_MACHINE_SYMBOLS[item.machine];
}
diff --git a/apps/mobile/src/features/threads/ThreadComposer.tsx b/apps/mobile/src/features/threads/ThreadComposer.tsx
index 52ef705e93b29..9dbabd768b3ed 100644
--- a/apps/mobile/src/features/threads/ThreadComposer.tsx
+++ b/apps/mobile/src/features/threads/ThreadComposer.tsx
@@ -544,7 +544,8 @@ export const ThreadComposer = function ThreadComposer(props: ThreadComposerProps
? mentionableEnvironments
: NO_MACHINES,
linkedEnvironments: useLinkedEnvironments(props.environmentId),
- currentThreadId: props.selectedThread.id,
+ currentThreadId: props.isDraft ? null : props.selectedThread.id,
+ projectId: props.selectedThread.projectId,
projectCwd: props.projectCwd,
pullRequestProjectId: props.serverConfig ? (project?.id ?? null) : null,
pullRequestRepository: project?.repositoryIdentity?.displayName ?? null,
diff --git a/apps/mobile/src/features/threads/ThreadContributionStatusStrip.tsx b/apps/mobile/src/features/threads/ThreadContributionStatusStrip.tsx
new file mode 100644
index 0000000000000..19d5296da92e1
--- /dev/null
+++ b/apps/mobile/src/features/threads/ThreadContributionStatusStrip.tsx
@@ -0,0 +1,114 @@
+import { useAtomValue } from "@effect/atom-react";
+import type {
+ ContributionStatusTone,
+ EnvironmentId,
+ ProviderDriverKind,
+ ThreadId,
+} from "@t3tools/contracts";
+import { useMemo } from "react";
+import { Alert, Platform, Pressable, ScrollView, View } from "react-native";
+
+import { AppText as Text } from "../../components/ui/AppText";
+import { ProviderIcon } from "../../components/ProviderIcon";
+import { cn } from "../../lib/cn";
+import { contributionStatusEnvironment } from "../../state/contribution-status";
+import {
+ reservesContributionStatusBand,
+ threadContributionStatusChips,
+ threadHasContributionStatus,
+} from "./thread-contribution-status-presentation";
+
+/** The strip's height: one row of chip touch targets (44pt iOS, 48dp Android). */
+const STRIP_HEIGHT = Platform.OS === "android" ? 48 : 44;
+
+// Neutral, the default, has no dot: Pi status text often brings its own glyph.
+const TONE_DOT_CLASS = {
+ neutral: null,
+ info: "bg-adaptive-sky-600-400",
+ success: "bg-adaptive-emerald-600-400",
+ warning: "bg-adaptive-amber-700-400",
+ error: "bg-adaptive-rose-600-400",
+} as const satisfies Record;
+
+/**
+ * The band the feed reserves above its first row for the status strip, passed
+ * to ThreadFeed's `topOverlayInset`. See `reservesContributionStatusBand`.
+ */
+export function useThreadContributionStatusStripInset(input: {
+ readonly environmentId: EnvironmentId;
+ readonly threadId: ThreadId;
+ readonly supported: boolean;
+ readonly driver: ProviderDriverKind | undefined;
+}): number {
+ const hasStatus = useAtomValue(
+ contributionStatusEnvironment.threadStatus(input.environmentId, input.threadId),
+ threadHasContributionStatus,
+ );
+ return reservesContributionStatusBand({ ...input, hasStatus }) ? STRIP_HEIGHT : 0;
+}
+
+// The strip overlays the feed; useThreadContributionStatusStripInset reserves its band.
+export function ThreadContributionStatusStrip(props: {
+ readonly environmentId: EnvironmentId;
+ readonly threadId: ThreadId;
+ /** Distance from the screen's top edge to the bottom of the navigation header. */
+ readonly top: number;
+ readonly contentMaxWidth: number | undefined;
+}) {
+ const entries = useAtomValue(
+ contributionStatusEnvironment.threadStatus(props.environmentId, props.threadId),
+ );
+ const chips = useMemo(() => threadContributionStatusChips(entries), [entries]);
+ if (chips.length === 0) return null;
+
+ return (
+
+
+ {/* Sized to its chips, so the feed under the empty rest of the row
+ still takes touches. */}
+
+ {chips.map((chip) => {
+ const dotClass = TONE_DOT_CLASS[chip.tone];
+ // The compact pill sits inside a full-size touch target (44pt
+ // iOS, 48dp Android); neighbours abut without overlapping.
+ return (
+ Alert.alert(chip.details.title, chip.details.message)}
+ >
+
+ {chip.leadsSource && chip.driver !== null ? (
+
+ ) : null}
+ {dotClass === null ? null : (
+
+ )}
+
+ {chip.text}
+
+
+
+ );
+ })}
+
+
+
+ );
+}
diff --git a/apps/mobile/src/features/threads/ThreadDetailScreen.tsx b/apps/mobile/src/features/threads/ThreadDetailScreen.tsx
index 870ab31f00003..219bfbbd31803 100644
--- a/apps/mobile/src/features/threads/ThreadDetailScreen.tsx
+++ b/apps/mobile/src/features/threads/ThreadDetailScreen.tsx
@@ -173,6 +173,10 @@ import { ComposerFeedback } from "./ComposerFeedback";
import { ComposerUsageLimits } from "./ComposerUsageLimits";
import { PendingUserInputCard } from "./PendingUserInputCard";
import { ProviderSubagentBar } from "./ProviderSubagentBar";
+import {
+ ThreadContributionStatusStrip,
+ useThreadContributionStatusStripInset,
+} from "./ThreadContributionStatusStrip";
import { ThreadCreationFailedCard } from "./ThreadCreationFailedCard";
import {
FLOATING_WORKING_CONTROL_COVERAGE,
@@ -1141,6 +1145,12 @@ function ThreadDetailBody(props: ThreadDetailScreenProps) {
providerSubagentProvider.models,
)
: null;
+ const statusStripInset = useThreadContributionStatusStripInset({
+ environmentId: props.environmentId,
+ threadId: props.selectedThread.id,
+ supported: props.serverConfig?.environment.capabilities.contributionStatus === true,
+ driver: providerSubagentProvider?.driver,
+ });
const providerSubagentCatalogModel = providerSubagentProvider?.models.find(
(model) => model.slug === providerSubagentModelSlug,
);
@@ -1407,6 +1417,7 @@ function ThreadDetailBody(props: ThreadDetailScreenProps) {
contentInsetEndAdjustment={combinedContentInsetEndAdjustment}
keyboardOffset={composerKeyboardOffset}
contentTopInset={0}
+ topOverlayInset={statusStripInset}
contentBottomInset={
estimatedOverlayHeight +
(showFloatingStatus ? FLOATING_WORKING_CONTROL_COVERAGE : 0)
@@ -1434,11 +1445,32 @@ function ThreadDetailBody(props: ThreadDetailScreenProps) {
threadId={props.selectedThread.id}
tabs={browserTabs.tabs}
loaded={browserTabs.loaded}
- top={navigationHeaderHeight + 8}
+ top={
+ navigationHeaderHeight +
+ (props.usesAutomaticContentInsets === true && Platform.OS === "ios"
+ ? statusStripInset
+ : 0) +
+ 8
+ }
onOpen={openBrowserPreview}
/>
) : null}
+ {showContent ? (
+
+ ) : null}
+
{showContent ? (
;
readonly keyboardOffset: number;
readonly contentTopInset?: number;
+ /** Height of UI floating over the feed's top edge below the header (the status strip). */
+ readonly topOverlayInset?: number;
readonly contentBottomInset?: number;
readonly historyControls?: ThreadFeedHistoryControls;
readonly contentMaxWidth?: number;
@@ -2750,6 +2753,11 @@ export const ThreadFeed = memo(function ThreadFeed({
const anchorTopInset = usesNativeAutomaticInsets
? (navigationHeaderHeight ?? insets.top + IOS_NAV_BAR_HEIGHT)
: topContentInset;
+ const feedTop = deriveThreadFeedTopGeometry({
+ usesNativeAutomaticInsets,
+ headerInset: anchorTopInset,
+ topOverlayInset: props.topOverlayInset ?? 0,
+ });
const theme = useUniwindTheme();
const iconSubtleColor = theme["--color-icon-subtle"];
@@ -3353,7 +3361,7 @@ export const ThreadFeed = memo(function ThreadFeed({
presentedFeed,
props.anchorMessageId,
(entry) => (entry.type === "message" ? entry.id : null),
- { anchorOffset: anchorTopInset + CHAT_LIST_ANCHOR_OFFSET },
+ { anchorOffset: feedTop.anchorTopInset + CHAT_LIST_ANCHOR_OFFSET },
);
const failedRunIds = failedFeedRunIds(props.feed, props.latestRun);
const terminalAssistantMessageIds = (() => {
@@ -3760,7 +3768,9 @@ export const ThreadFeed = memo(function ThreadFeed({
scrollEventThrottle={16}
ListHeaderComponent={
<>
- {usesNativeAutomaticInsets ? null : }
+ {feedTop.spacerHeight > 0 ? (
+
+ ) : null}
{setupAnchorIndex < 0 && props.worktreeSetup ? (
) : null}
diff --git a/apps/mobile/src/features/threads/thread-contribution-status-presentation.test.ts b/apps/mobile/src/features/threads/thread-contribution-status-presentation.test.ts
new file mode 100644
index 0000000000000..a590c116ec9c9
--- /dev/null
+++ b/apps/mobile/src/features/threads/thread-contribution-status-presentation.test.ts
@@ -0,0 +1,138 @@
+import {
+ type ContributionStatusEntry,
+ ProviderDriverKind,
+ ProviderInstanceId,
+ ProviderSessionId,
+ ThreadId,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+ reservesContributionStatusBand,
+ threadContributionStatusChips,
+ threadHasContributionStatus,
+} from "./thread-contribution-status-presentation";
+
+const entry = (
+ session: string,
+ items: ContributionStatusEntry["items"],
+ driver = "pi",
+): ContributionStatusEntry => ({
+ threadId: ThreadId.make("thread-1"),
+ source: {
+ kind: "provider-session",
+ providerSessionId: ProviderSessionId.make(session),
+ providerInstanceId: ProviderInstanceId.make(driver),
+ driver: ProviderDriverKind.make(driver),
+ },
+ items,
+});
+
+describe("threadContributionStatusChips", () => {
+ it("names a plugin as the source of its chips, without a provider icon", () => {
+ const [chip] = threadContributionStatusChips([
+ {
+ threadId: ThreadId.make("thread-1"),
+ source: { kind: "plugin", pluginId: "acme.ci", name: "CI watcher" },
+ items: [{ key: "ci", text: "passing", tone: "success" }],
+ },
+ ]);
+ expect(chip).toMatchObject({
+ driver: null,
+ text: "passing",
+ tone: "success",
+ accessibilityLabel: "CI watcher status: passing",
+ help: "Set by the CI watcher plugin.",
+ });
+ });
+
+ it("shows nothing for a thread without statuses", () => {
+ expect(threadContributionStatusChips([])).toEqual([]);
+ });
+
+ it("keys chips by source and item key, in the server's order", () => {
+ const chips = threadContributionStatusChips([
+ entry("session-a", [
+ { key: "mode", text: "● plan" },
+ { key: "tokens", text: "12k", tone: "warning", tooltip: "Context is filling up" },
+ ]),
+ entry("session-b", [{ key: "mode", text: "● plan" }], "codex"),
+ ]);
+
+ expect(chips.map((chip) => [chip.text, chip.leadsSource, chip.tone, chip.tooltip])).toEqual([
+ ["● plan", true, "neutral", null],
+ ["12k", false, "warning", "Context is filling up"],
+ ["● plan", true, "neutral", null],
+ ]);
+ // The same item key under two sources must stay two distinct rows.
+ expect(new Set(chips.map((chip) => chip.id)).size).toBe(3);
+ });
+
+ it("re-keys a chip when another provider session takes the thread over", () => {
+ const [before] = threadContributionStatusChips([entry("old", [{ key: "mode", text: "x" }])]);
+ const [after] = threadContributionStatusChips([entry("new", [{ key: "mode", text: "x" }])]);
+
+ expect(after?.id).not.toBe(before?.id);
+ });
+
+ it("attributes the status to its producer without claiming freshness", () => {
+ const [pi] = threadContributionStatusChips([entry("s", [{ key: "mode", text: "● startup" }])]);
+ const [codex] = threadContributionStatusChips([
+ entry("s", [{ key: "mode", text: "busy" }], "codex"),
+ ]);
+
+ expect(pi?.accessibilityLabel).toBe("Pi status: ● startup");
+ expect(pi?.help).toBe("Set by a Pi extension. It can lag a session change.");
+ expect(codex?.help).toBe("Set by Codex. It can lag a session change.");
+ });
+
+ it("puts the full status text in the details body, where it is never truncated", () => {
+ const text = "● build — indexing 1,284 files in packages/client-runtime before the next turn";
+ const [plain, withTooltip] = threadContributionStatusChips([
+ entry("s", [
+ { key: "mode", text },
+ { key: "tokens", text: "12k", tooltip: "Context is filling up" },
+ ]),
+ ]);
+
+ expect(plain?.details).toEqual({
+ title: "Pi status",
+ message: `${text}\n\nSet by a Pi extension. It can lag a session change.`,
+ });
+ expect(withTooltip?.details.message).toBe(
+ "12k\n\nContext is filling up\n\nSet by a Pi extension. It can lag a session change.",
+ );
+ });
+});
+
+describe("status strip band", () => {
+ it("counts a thread as having statuses only when an entry has items", () => {
+ expect(threadHasContributionStatus([])).toBe(false);
+ expect(threadHasContributionStatus([entry("s", [])])).toBe(false);
+ expect(threadHasContributionStatus([entry("s", [{ key: "mode", text: "x" }])])).toBe(true);
+ });
+
+ it("keeps a Pi thread's band through set, replace and clear", () => {
+ const pi = ProviderDriverKind.make("pi");
+ const band = [false, true, true, false].map((hasStatus) =>
+ reservesContributionStatusBand({ supported: true, driver: pi, hasStatus }),
+ );
+
+ expect(band).toEqual([true, true, true, true]);
+ });
+
+ it("reserves nothing for other providers without statuses or on servers without the stream", () => {
+ const codex = ProviderDriverKind.make("codex");
+ const pi = ProviderDriverKind.make("pi");
+
+ expect(
+ reservesContributionStatusBand({ supported: true, driver: codex, hasStatus: false }),
+ ).toBe(false);
+ expect(
+ reservesContributionStatusBand({ supported: true, driver: codex, hasStatus: true }),
+ ).toBe(true);
+ expect(reservesContributionStatusBand({ supported: false, driver: pi, hasStatus: false })).toBe(
+ false,
+ );
+ });
+});
diff --git a/apps/mobile/src/features/threads/thread-contribution-status-presentation.ts b/apps/mobile/src/features/threads/thread-contribution-status-presentation.ts
new file mode 100644
index 0000000000000..c98f2697e10dd
--- /dev/null
+++ b/apps/mobile/src/features/threads/thread-contribution-status-presentation.ts
@@ -0,0 +1,91 @@
+import {
+ type ContributionStatusEntry,
+ type ContributionStatusSource,
+ type ContributionStatusTone,
+ contributionStatusSourceKey,
+ PROVIDER_DISPLAY_NAMES,
+ type ProviderDriverKind,
+} from "@t3tools/contracts";
+
+export interface ThreadContributionStatusChip {
+ /** Source key plus item key, so a provider session taking over re-keys the chip. */
+ readonly id: string;
+ /** The provider that set it, or null for a plugin's status. */
+ readonly driver: ProviderDriverKind | null;
+ /** The first chip of each provider source carries that provider's icon. */
+ readonly leadsSource: boolean;
+ readonly text: string;
+ readonly tone: ContributionStatusTone;
+ readonly tooltip: string | null;
+ readonly accessibilityLabel: string;
+ /** Says where the status came from and that it can lag; never "current session". */
+ readonly help: string;
+ /** The details alert. The full text goes in the body: native alert titles truncate. */
+ readonly details: { readonly title: string; readonly message: string };
+}
+
+function providerLabel(driver: ProviderDriverKind): string {
+ return PROVIDER_DISPLAY_NAMES[driver] ?? driver;
+}
+
+function sourceLabel(source: ContributionStatusSource): string {
+ return source.kind === "plugin" ? source.name : providerLabel(source.driver);
+}
+
+function statusHelp(source: ContributionStatusSource): string {
+ if (source.kind === "plugin") return `Set by the ${source.name} plugin.`;
+ const origin = source.driver === "pi" ? "a Pi extension" : providerLabel(source.driver);
+ return `Set by ${origin}. It can lag a session change.`;
+}
+
+/** Flattens a thread's status entries into chips, in the server's order. */
+export function threadContributionStatusChips(
+ entries: ReadonlyArray,
+): ReadonlyArray {
+ return entries.flatMap((entry) => {
+ const { source } = entry;
+ const sourceKey = contributionStatusSourceKey(source);
+ const label = sourceLabel(source);
+ const help = statusHelp(source);
+ return entry.items.map((item, index) => ({
+ id: JSON.stringify([sourceKey, item.key]),
+ driver: source.kind === "plugin" ? null : source.driver,
+ leadsSource: index === 0,
+ text: item.text,
+ tone: item.tone ?? "neutral",
+ tooltip: item.tooltip ?? null,
+ accessibilityLabel: `${label} status: ${item.text}`,
+ help,
+ details: {
+ title: `${label} status`,
+ message: [item.text, item.tooltip, help].filter(Boolean).join("\n\n"),
+ },
+ }));
+ });
+}
+
+export function threadHasContributionStatus(
+ entries: ReadonlyArray,
+): boolean {
+ return entries.some((entry) => entry.items.length > 0);
+}
+
+/** Drivers whose sessions publish statuses (Pi's `setStatus`). */
+const STATUS_PUBLISHING_DRIVERS: ReadonlySet = new Set(["pi"]);
+
+/**
+ * Whether the feed reserves the status strip's band above its first row.
+ * Threads of a publishing provider keep it from the start, so a status
+ * appearing, changing or clearing never shifts the feed; other threads only
+ * get it while they have a status.
+ */
+export function reservesContributionStatusBand(input: {
+ readonly supported: boolean;
+ readonly driver: ProviderDriverKind | undefined;
+ readonly hasStatus: boolean;
+}): boolean {
+ if (!input.supported) return false;
+ return (
+ input.hasStatus || (input.driver !== undefined && STATUS_PUBLISHING_DRIVERS.has(input.driver))
+ );
+}
diff --git a/apps/mobile/src/features/threads/thread-list-v2-items.tsx b/apps/mobile/src/features/threads/thread-list-v2-items.tsx
index 74704ef116354..1aa0f231ee897 100644
--- a/apps/mobile/src/features/threads/thread-list-v2-items.tsx
+++ b/apps/mobile/src/features/threads/thread-list-v2-items.tsx
@@ -11,6 +11,8 @@ import {
import { RowPressable } from "../../components/ui/RowPressable";
import { CustomSnoozeSheet } from "./CustomSnoozeSheet";
import { appAtomRegistry } from "../../state/atom-registry";
+import { runPluginAction, usePluginActions } from "../../state/plugin-actions";
+import { pluginActionLabels, pluginActionsAt } from "@t3tools/client-runtime/state/pluginActions";
import { threadArrangementOpenAtom } from "../../state/thread-order";
import { threadEnvironment } from "../../state/threads";
import { useAtomCommand } from "../../state/use-atom-command";
@@ -867,6 +869,37 @@ export const ThreadListV2Row = memo(function ThreadListV2Row(props: {
],
[canTurnIntoProject, props.titleRegenerationSupported, thread.runtime, isRegeneratingTitle],
);
+ const pluginActions = usePluginActions(thread.environmentId);
+ const pluginMenuEntries = useMemo(() => {
+ const entries = pluginActionsAt(pluginActions, "thread-menu", {
+ threadId: thread.id,
+ projectId: thread.projectId,
+ });
+ const labels = pluginActionLabels(entries.map((entry) => entry.action));
+ return entries.map((entry, index) => ({
+ ...entry,
+ menuId: `plugin-action:${entry.action.id}`,
+ title: labels[index] ?? entry.action.title,
+ }));
+ }, [pluginActions, thread.id, thread.projectId]);
+ // One submenu keeps the long-press menu short however many plugins add actions.
+ const pluginMenuActions = useMemo(
+ () =>
+ pluginMenuEntries.length === 0
+ ? []
+ : [
+ {
+ id: "plugin-actions",
+ title: "Plugin actions",
+ image: "puzzlepiece.extension",
+ subactions: pluginMenuEntries.map((entry) => ({
+ id: entry.menuId,
+ title: entry.title,
+ })),
+ },
+ ],
+ [pluginMenuEntries],
+ );
const snoozableCardMenuActions = useMemo(
() => [
{ id: "settle", title: "Settle", image: "checkmark" },
@@ -929,6 +962,15 @@ export const ThreadListV2Row = memo(function ThreadListV2Row(props: {
);
const handleMenuAction = useCallback(
({ nativeEvent }: { readonly nativeEvent: { readonly event: string } }) => {
+ const pluginEntry = pluginMenuEntries.find((entry) => entry.menuId === nativeEvent.event);
+ if (pluginEntry) {
+ void runPluginAction({
+ environmentId: thread.environmentId,
+ action: pluginEntry.action,
+ target: pluginEntry.target,
+ });
+ return;
+ }
if (nativeEvent.event === "new-thread-on-branch") onNewThreadOnBranch(thread);
if (nativeEvent.event === "settle") handleSettle();
if (nativeEvent.event === "unsettle") handleUnsettle();
@@ -992,6 +1034,7 @@ export const ThreadListV2Row = memo(function ThreadListV2Row(props: {
handleUnpin,
handleUnsettle,
handleUnsnooze,
+ pluginMenuEntries,
setCustomSnoozeOpen,
snoozePresets,
props.snoozePresets,
@@ -1454,6 +1497,7 @@ export const ThreadListV2Row = memo(function ThreadListV2Row(props: {
: []),
{ id: "copy-thread", title: "Copy thread", image: "text.bubble" },
{ id: "copy-thread-id", title: "Copy thread ID", image: "doc.on.doc" },
+ ...pluginMenuActions,
...(snoozedRow
? snoozedMenuActions
: !props.settlementSupported
diff --git a/apps/mobile/src/features/threads/use-composer-command-menu.plugin-actions.test.tsx b/apps/mobile/src/features/threads/use-composer-command-menu.plugin-actions.test.tsx
new file mode 100644
index 0000000000000..333e2fe2140cc
--- /dev/null
+++ b/apps/mobile/src/features/threads/use-composer-command-menu.plugin-actions.test.tsx
@@ -0,0 +1,288 @@
+import {
+ EnvironmentId,
+ PluginActionId,
+ ProjectId,
+ ThreadId,
+ type PluginAction,
+} from "@t3tools/contracts";
+import { act, createElement, useLayoutEffect, useState } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+const fixture = vi.hoisted(() => ({
+ actions: [] as ReadonlyArray,
+ canOperate: true,
+ // The live operate grant, which can change after the menu was offered.
+ canRunNow: true,
+ runPluginAction: vi.fn(async (_input: unknown) => true),
+ onChangeDraftMessage: vi.fn((_draft: string) => {}),
+}));
+vi.mock("react-native", () => ({ Alert: { alert: vi.fn() } }));
+vi.mock("../../state/queries", () => ({
+ useThreadSearch: () => undefined,
+ useComposerPathSearch: () => ({ entries: [], isPending: false }),
+ useComposerPullRequestSearch: () => ({ entries: [], isPending: false, error: null }),
+}));
+vi.mock("../../state/use-composer-drafts", () => ({
+ getComposerDraftSnapshot: vi.fn(),
+ useComposerDraftSelection: () => null,
+ setComposerDraftContext: vi.fn(),
+}));
+vi.mock("../../lib/uuid", () => ({ uuidv4: () => "context-id" }));
+vi.mock("../../state/server", () => ({
+ serverEnvironment: { providersValueAtom: vi.fn(), refreshProviders: Symbol("refreshProviders") },
+}));
+vi.mock("../../state/session", () => ({
+ useEnvironmentScope: () => fixture.canOperate,
+}));
+vi.mock("../../state/plugin-actions", () => ({
+ usePluginActions: () => fixture.actions,
+ runPluginAction: fixture.runPluginAction,
+ canRunPluginActionsNow: () => fixture.canRunNow,
+}));
+
+import { useComposerCommandMenu } from "./use-composer-command-menu";
+
+const action = (name: string, title: string, target: PluginAction["target"]) =>
+ ({
+ id: PluginActionId.make(`installation-1:1:${name}`),
+ pluginId: "acme.deploy",
+ pluginName: "Deploy",
+ name,
+ title,
+ target,
+ placements: ["composer-slash"],
+ }) satisfies PluginAction;
+const deploy = action("deploy", "Deploy this branch", "thread");
+const dashboard = action("open-dashboard", "Open dashboard", "project");
+const environmentId = EnvironmentId.make("environment-1");
+const threadId = ThreadId.make("thread-1");
+const projectId = ProjectId.make("project-1");
+
+type Menu = ReturnType;
+const latest: { menu: Menu | null; draft: string } = { menu: null, draft: "" };
+const report = (menu: Menu, draft: string) => {
+ latest.menu = menu;
+ latest.draft = draft;
+};
+const onUpdateInteractionMode = vi.fn();
+const onUsageLimits = vi.fn();
+
+/** A composer: the draft lives in state and the menu edits it, as in ThreadComposer and New Task. */
+function Composer(props: {
+ initialDraft: string;
+ currentThreadId: ThreadId | null;
+ report: (menu: Menu, draft: string) => void;
+}) {
+ const [draft, setDraft] = useState(props.initialDraft);
+ const menu = useComposerCommandMenu({
+ draftMessage: draft,
+ ownerKey: "draft-1",
+ environmentId,
+ currentThreadId: props.currentThreadId,
+ projectId,
+ projectCwd: null,
+ selectedProviderStatus: null,
+ hasThread: props.currentThreadId !== null,
+ hasCompactableConversation: false,
+ onChangeDraftMessage: (next) => {
+ fixture.onChangeDraftMessage(next);
+ setDraft(next);
+ },
+ onUpdateInteractionMode,
+ onUsageLimits,
+ });
+ // Publish only committed callbacks to the test driver.
+ useLayoutEffect(() => {
+ editDraft = setDraft;
+ props.report(menu, draft);
+ });
+ return null;
+}
+
+let root: Root;
+let editDraft: (draft: string) => void = () => {};
+
+beforeEach(() => {
+ vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+ fixture.actions = [deploy, dashboard];
+ fixture.canOperate = true;
+ fixture.canRunNow = true;
+ fixture.runPluginAction.mockReset().mockResolvedValue(true);
+ fixture.onChangeDraftMessage.mockClear();
+ onUpdateInteractionMode.mockClear();
+ onUsageLimits.mockClear();
+ root = createRoot(document.createElement("div"));
+});
+
+afterEach(async () => {
+ await act(async () => root.unmount());
+ vi.unstubAllGlobals();
+});
+
+/** Types `draft` with the caret after `/`, then returns the plugin entries offered. */
+async function openMenu(draft: string, caret: number, currentThreadId: ThreadId | null) {
+ await act(async () =>
+ root.render(createElement(Composer, { initialDraft: draft, currentThreadId, report })),
+ );
+ await act(async () => latest.menu!.onSelectionChange({ start: caret, end: caret }));
+ return latest.menu!.items.filter((item) => item.type === "plugin-action");
+}
+
+function offered(label: string) {
+ const item = latest.menu!.items.find((candidate) => candidate.label === label);
+ if (!item) throw new Error(`Expected ${label} in the menu`);
+ return item;
+}
+
+async function pick(label: string) {
+ const item = offered(label);
+ await act(async () => latest.menu!.onSelect(item));
+}
+
+describe("picking a plugin action from the slash menu", () => {
+ it("runs it on the open thread and keeps the rest of the message", async () => {
+ const draft = "ship it\n/depl\nthen tell me";
+ const offered = await openMenu(draft, "ship it\n/depl".length, threadId);
+ expect(offered.map((item) => item.label)).toContain("/deploy");
+
+ await pick("/deploy");
+
+ expect(latest.draft).toBe("ship it\n\nthen tell me");
+ expect(fixture.runPluginAction).toHaveBeenCalledExactlyOnceWith({
+ environmentId,
+ action: deploy,
+ target: { _tag: "thread", threadId },
+ });
+ // The pick is the action itself: nothing else changes the message or the turn.
+ expect(onUpdateInteractionMode).not.toHaveBeenCalled();
+ expect(onUsageLimits).not.toHaveBeenCalled();
+ });
+
+ it("in a New Task draft offers project actions on the selected project, not thread actions", async () => {
+ const offered = await openMenu("check this\n/", "check this\n/".length, null);
+ expect(offered.map((item) => item.label)).toEqual(["/open-dashboard"]);
+
+ await pick("/open-dashboard");
+
+ expect(latest.draft).toBe("check this\n");
+ expect(fixture.runPluginAction).toHaveBeenCalledExactlyOnceWith({
+ environmentId,
+ action: dashboard,
+ target: { _tag: "project", projectId },
+ });
+ });
+
+ it("offers no plugin actions to a read-only connection and keeps the typed command", async () => {
+ fixture.canOperate = false;
+ const draft = "ship it\n/depl";
+ const offered = await openMenu(draft, draft.length, threadId);
+ expect(offered).toEqual([]);
+
+ // A stale entry picked after the grant changed is refused before the draft is touched.
+ await act(async () =>
+ latest.menu!.onSelect({
+ id: `plugin-action:${deploy.id}`,
+ type: "plugin-action",
+ action: deploy,
+ target: { _tag: "thread", threadId },
+ label: "/deploy",
+ description: deploy.title,
+ }),
+ );
+
+ expect(latest.draft).toBe(draft);
+ expect(fixture.runPluginAction).not.toHaveBeenCalled();
+ });
+
+ it("keeps the typed command when the grant is lost while the menu is open", async () => {
+ const draft = "ship it\n/depl";
+ await openMenu(draft, draft.length, threadId);
+ const stale = offered("/deploy");
+
+ fixture.canOperate = false;
+ await act(async () =>
+ root.render(
+ createElement(Composer, { initialDraft: draft, currentThreadId: threadId, report }),
+ ),
+ );
+ await act(async () => latest.menu!.onSelect(stale));
+
+ expect(fixture.runPluginAction).not.toHaveBeenCalled();
+ expect(latest.draft).toBe(draft);
+ });
+
+ it("reads the live grant when the action is picked and keeps the draft if it is gone", async () => {
+ const draft = "ship it\n/depl";
+ await openMenu(draft, draft.length, threadId);
+
+ // The cached grant still offers the action, but the connection lost it.
+ fixture.canRunNow = false;
+ await pick("/deploy");
+
+ expect(fixture.runPluginAction).not.toHaveBeenCalled();
+ expect(latest.draft).toBe(draft);
+ });
+
+ it.each(["different-token", "shifted-token", "removed-action"])(
+ "refuses a retained handler after %s",
+ async (change) => {
+ const draft = "ship it\n/depl";
+ await openMenu(draft, draft.length, threadId);
+ const stale = offered("/deploy");
+ const staleMenu = latest.menu!;
+ const changed =
+ change === "different-token"
+ ? "ship it\n/nope"
+ : change === "shifted-token"
+ ? "prefix " + draft
+ : draft;
+ if (change === "removed-action") fixture.actions = [];
+ await act(async () => {
+ editDraft(changed);
+ root.render(
+ createElement(Composer, { initialDraft: draft, currentThreadId: threadId, report }),
+ );
+ });
+ await act(async () =>
+ latest.menu!.onSelectionChange({ start: changed.length, end: changed.length }),
+ );
+ await act(async () => staleMenu.onSelect(stale));
+ expect(latest.draft).toBe(changed);
+ expect(fixture.onChangeDraftMessage).not.toHaveBeenCalled();
+ expect(fixture.runPluginAction).not.toHaveBeenCalled();
+ },
+ );
+
+ it("removes the command when it is picked, before the action settles, and runs it once", async () => {
+ let finish: (ran: boolean) => void = () => {};
+ fixture.runPluginAction.mockReturnValue(new Promise((resolve) => (finish = resolve)));
+ await openMenu("ship it\n/depl", "ship it\n/depl".length, threadId);
+ const stale = offered("/deploy");
+ const staleMenu = latest.menu!;
+
+ // Two taps land on the same render before the draft updates.
+ await act(async () => {
+ staleMenu.onSelect(stale);
+ staleMenu.onSelect(stale);
+ });
+ expect(latest.draft).toBe("ship it\n");
+ await act(async () => finish(true));
+
+ expect(fixture.runPluginAction).toHaveBeenCalledOnce();
+ });
+
+ it("writes no draft when the action settles after the composer is gone", async () => {
+ let finish: (ran: boolean) => void = () => {};
+ fixture.runPluginAction.mockReturnValue(new Promise((resolve) => (finish = resolve)));
+ await openMenu("ship it\n/depl", "ship it\n/depl".length, threadId);
+ await pick("/deploy");
+ expect(fixture.onChangeDraftMessage).toHaveBeenCalledExactlyOnceWith("ship it\n");
+
+ await act(async () => root.unmount());
+ await act(async () => finish(true));
+
+ expect(fixture.onChangeDraftMessage).toHaveBeenCalledOnce();
+ root = createRoot(document.createElement("div"));
+ });
+});
diff --git a/apps/mobile/src/features/threads/use-composer-command-menu.test.ts b/apps/mobile/src/features/threads/use-composer-command-menu.test.ts
index c0044a74f7944..f0b550b6ec7e3 100644
--- a/apps/mobile/src/features/threads/use-composer-command-menu.test.ts
+++ b/apps/mobile/src/features/threads/use-composer-command-menu.test.ts
@@ -1,5 +1,11 @@
import { describe, expect, it, vi } from "vite-plus/test";
-import { ProviderDriverKind } from "@t3tools/contracts";
+import {
+ PluginActionId,
+ ProjectId,
+ ProviderDriverKind,
+ ThreadId,
+ type PluginAction,
+} from "@t3tools/contracts";
vi.mock("react-native", () => ({ Alert: { alert: vi.fn() } }));
@@ -19,9 +25,15 @@ vi.mock("../../state/server", () => ({
refreshProviders: Symbol("refreshProviders"),
},
}));
+vi.mock("../../state/session", () => ({ useEnvironmentScope: () => true }));
+vi.mock("../../state/plugin-actions", () => ({
+ usePluginActions: () => [],
+ runPluginAction: vi.fn(),
+}));
import {
buildComposerSlashCommandItems,
+ buildPluginActionSlashItems,
resolveComposerCommandSelection,
resolveComposerMenuSelection,
} from "./use-composer-command-menu";
@@ -126,3 +138,42 @@ describe("mobile slash commands", () => {
).toEqual({ text: "/plan ", cursor: 6, interactionMode: null });
});
});
+describe("mobile plugin action slash entries", () => {
+ const action = (name: string, title: string, target: PluginAction["target"]) =>
+ ({
+ id: PluginActionId.make(`installation-1:1:${name}`),
+ pluginId: "acme.deploy",
+ pluginName: "Deploy",
+ name,
+ title,
+ target,
+ placements: ["composer-slash"],
+ }) satisfies PluginAction;
+ const actions = [
+ action("deploy", "Deploy this branch", "thread"),
+ action("open-dashboard", "Open dashboard", "project"),
+ ];
+ const threadId = ThreadId.make("thread-1");
+ const projectId = ProjectId.make("project-1");
+
+ it("match by name or title and run on the thread they were picked on", () => {
+ expect(
+ buildPluginActionSlashItems(actions, "branch", { threadId, projectId }).map((item) =>
+ item.type === "plugin-action" ? [item.label, item.target] : null,
+ ),
+ ).toEqual([["/deploy", { _tag: "thread", threadId }]]);
+ expect(
+ buildPluginActionSlashItems(actions, "dash", { threadId, projectId }).map(
+ (item) => item.label,
+ ),
+ ).toEqual(["/open-dashboard"]);
+ });
+
+ it("leave out actions whose target the composer cannot supply", () => {
+ expect(
+ buildPluginActionSlashItems(actions, "", { threadId: null, projectId }).map(
+ (item) => item.label,
+ ),
+ ).toEqual(["/open-dashboard"]);
+ });
+});
diff --git a/apps/mobile/src/features/threads/use-composer-command-menu.ts b/apps/mobile/src/features/threads/use-composer-command-menu.ts
index 72987599f48f6..10793b7bb86ee 100644
--- a/apps/mobile/src/features/threads/use-composer-command-menu.ts
+++ b/apps/mobile/src/features/threads/use-composer-command-menu.ts
@@ -1,11 +1,13 @@
import * as Dialog from "../../components/ui/Dialog";
-import type {
- EnvironmentId,
- ProjectId,
- ProviderInteractionMode,
- ServerProvider,
- ThreadId,
- ThreadPullRequestLink,
+import {
+ AuthOrchestrationOperateScope,
+ type EnvironmentId,
+ type PluginAction,
+ type ProjectId,
+ type ProviderInteractionMode,
+ type ServerProvider,
+ type ThreadId,
+ type ThreadPullRequestLink,
} from "@t3tools/contracts";
import {
type ComposerEnvironmentCandidate,
@@ -52,7 +54,7 @@ import {
} from "@t3tools/client-runtime/providerSkills";
import { useAtomRefresh } from "@effect/atom-react";
import { Atom } from "effect/reactivity";
-import { useEffect, useState } from "react";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
import type { ComposerEditorSelection } from "../../components/ComposerEditor";
import { serverEnvironment } from "../../state/server";
@@ -61,6 +63,16 @@ import {
useComposerPullRequestSearch,
useThreadSearch,
} from "../../state/queries";
+import { useEnvironmentScope } from "../../state/session";
+import {
+ canRunPluginActionsNow,
+ runPluginAction,
+ usePluginActions,
+} from "../../state/plugin-actions";
+import {
+ type PluginActionContext,
+ pluginActionsAt,
+} from "@t3tools/client-runtime/state/pluginActions";
import type { ComposerCommandItem } from "./ComposerCommandPopover";
import { matchesSlashSkillQuery } from "./composerSlashSkillSearch";
@@ -205,6 +217,32 @@ export function resolveComposerCommandSelection(input: {
};
}
+/**
+ * Slash entries for the plugin actions matching `query` (lowercase) by name or title.
+ * They run when picked, so they are offered anywhere in the message.
+ */
+export function buildPluginActionSlashItems(
+ actions: ReadonlyArray,
+ query: string,
+ context: PluginActionContext,
+): ComposerCommandItem[] {
+ return pluginActionsAt(actions, "composer-slash", context)
+ .filter(
+ // Names are lowercase today, but the wire accepts any string from a newer server.
+ ({ action }) =>
+ action.name.toLowerCase().includes(query) || action.title.toLowerCase().includes(query),
+ )
+ .map(({ action, target }) => ({
+ id: `plugin-action:${action.id}`,
+ type: "plugin-action" as const,
+ action,
+ target,
+ label: `/${action.name}`,
+ description: `${action.title} · ${action.pluginName}`,
+ }));
+}
+
+/** Shared autocomplete for thread composers and unsent new-task drafts. */
export function useComposerCommandMenu({
draftMessage,
ownerKey,
@@ -213,6 +251,7 @@ export function useComposerCommandMenu({
environments = EMPTY_ENVIRONMENTS,
linkedEnvironments = NO_LINKED_ENVIRONMENTS,
currentThreadId = null,
+ projectId,
projectCwd,
pullRequestProjectId = null,
pullRequestRepository = null,
@@ -234,6 +273,8 @@ export function useComposerCommandMenu({
/** The machines `environmentId` links to, by name, whose threads the picker also offers. */
readonly linkedEnvironments?: ReadonlyMap;
readonly currentThreadId?: ThreadId | null;
+ /** The project plugin actions with a project target run on; required so no composer drops them. */
+ readonly projectId: ProjectId | null;
readonly projectCwd: string | null;
readonly pullRequestProjectId?: ProjectId | null;
readonly pullRequestRepository?: string | null;
@@ -262,6 +303,7 @@ export function useComposerCommandMenu({
});
const setSelection = (next: ComposerEditorSelection) =>
setLocalSelection({ ownerKey, start: next.start, end: next.end });
+ const pluginActionRunningRef = useRef(false);
const skills = selectedProviderStatus
? resolveProviderSkillsForCwd(selectedProviderStatus, projectCwd)
@@ -315,6 +357,9 @@ export function useComposerCommandMenu({
query: trigger?.kind === "pull-request" ? trigger.query : null,
});
+ const pluginActions = usePluginActions(environmentId);
+ // Running a plugin action needs `orchestration:operate`.
+ const canRunPluginActions = useEnvironmentScope(environmentId, AuthOrchestrationOperateScope);
const items = ((): ComposerCommandItem[] => {
if (!trigger) return [];
@@ -371,7 +416,16 @@ export function useComposerCommandMenu({
description: skill.shortDescription ?? skill.description ?? "",
}));
- return [...commandItems, ...skillItems];
+ return [
+ ...commandItems,
+ ...skillItems,
+ ...(canRunPluginActions
+ ? buildPluginActionSlashItems(pluginActions, q, {
+ threadId: currentThreadId,
+ projectId,
+ })
+ : []),
+ ];
}
if (trigger.kind === "skill") {
@@ -491,6 +545,22 @@ export function useComposerCommandMenu({
return [];
})();
+ const liveSelection = {
+ draftMessage,
+ trigger,
+ items,
+ canRunPluginActions,
+ environmentId,
+ ownerKey,
+ currentThreadId,
+ projectId,
+ };
+ const liveSelectionRef = useRef(liveSelection);
+ // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- publishes committed composer ownership to asynchronous native menu callbacks
+ useLayoutEffect(() => {
+ liveSelectionRef.current = liveSelection;
+ });
+
const onSelect = (item: ComposerCommandItem) => {
if (!trigger) return;
if (item.type === "environment") {
@@ -582,6 +652,48 @@ export function useComposerCommandMenu({
return;
}
+ if (item.type === "plugin-action") {
+ const current = liveSelectionRef.current;
+ const liveTrigger = current.trigger;
+ const offered = current.items.find(
+ (candidate) => candidate.id === item.id && candidate.type === "plugin-action",
+ );
+ // An old menu may outlive its draft, target, permission, or plugin generation.
+ if (
+ current.environmentId === null ||
+ current.environmentId !== environmentId ||
+ current.ownerKey !== ownerKey ||
+ current.currentThreadId !== currentThreadId ||
+ current.projectId !== projectId ||
+ !current.canRunPluginActions ||
+ !canRunPluginActionsNow(current.environmentId) ||
+ trigger.kind !== "slash-command" ||
+ liveTrigger?.kind !== "slash-command" ||
+ liveTrigger.rangeStart !== trigger.rangeStart ||
+ liveTrigger.rangeEnd !== trigger.rangeEnd ||
+ liveTrigger.query !== trigger.query ||
+ offered?.type !== "plugin-action"
+ )
+ return;
+ if (pluginActionRunningRef.current) return;
+ pluginActionRunningRef.current = true;
+ const cleared = replaceTextRange(
+ current.draftMessage,
+ liveTrigger.rangeStart,
+ liveTrigger.rangeEnd,
+ "",
+ );
+ setSelection({ start: cleared.cursor, end: cleared.cursor });
+ onChangeDraftMessage(cleared.text);
+ void runPluginAction({
+ environmentId: current.environmentId,
+ action: offered.action,
+ target: offered.target,
+ }).finally(() => {
+ pluginActionRunningRef.current = false;
+ });
+ return;
+ }
if (
item.type === "provider-slash-command" &&
item.command.name === USAGE_LIMITS_COMMAND.name &&
diff --git a/apps/mobile/src/lib/layout.test.ts b/apps/mobile/src/lib/layout.test.ts
index 0eaed72c1979e..26b18d83ac08b 100644
--- a/apps/mobile/src/lib/layout.test.ts
+++ b/apps/mobile/src/lib/layout.test.ts
@@ -4,6 +4,7 @@ import {
alignListPaneToHinge,
deriveLayout,
deriveThreadFeedInitialContentInset,
+ deriveThreadFeedTopGeometry,
deriveThreadArrangementSizing,
deriveThreadWorkLogSizing,
deriveWorkspacePaneLayout,
@@ -200,3 +201,42 @@ describe("alignListPaneToHinge", () => {
expect(alignListPaneToHinge(narrowDetail)).toBe(layout);
});
});
+
+describe("deriveThreadFeedTopGeometry", () => {
+ it("keeps the first row and an anchored message below a strip under an opaque header", () => {
+ expect(
+ deriveThreadFeedTopGeometry({
+ usesNativeAutomaticInsets: false,
+ headerInset: 0,
+ topOverlayInset: 48,
+ }),
+ ).toEqual({ spacerHeight: 48, anchorTopInset: 48 });
+ });
+
+ it("adds only the strip to content under a glass header, whose inset UIKit applies", () => {
+ expect(
+ deriveThreadFeedTopGeometry({
+ usesNativeAutomaticInsets: true,
+ headerInset: 106,
+ topOverlayInset: 44,
+ }),
+ ).toEqual({ spacerHeight: 44, anchorTopInset: 150 });
+ });
+
+ it("leaves the feed where it was when nothing floats over it", () => {
+ expect(
+ deriveThreadFeedTopGeometry({
+ usesNativeAutomaticInsets: true,
+ headerInset: 106,
+ topOverlayInset: 0,
+ }),
+ ).toEqual({ spacerHeight: 0, anchorTopInset: 106 });
+ expect(
+ deriveThreadFeedTopGeometry({
+ usesNativeAutomaticInsets: false,
+ headerInset: 0,
+ topOverlayInset: 0,
+ }),
+ ).toEqual({ spacerHeight: 0, anchorTopInset: 0 });
+ });
+});
diff --git a/apps/mobile/src/lib/layout.ts b/apps/mobile/src/lib/layout.ts
index 4155d834ba24d..d0167ca845609 100644
--- a/apps/mobile/src/lib/layout.ts
+++ b/apps/mobile/src/lib/layout.ts
@@ -98,6 +98,18 @@ export function deriveThreadFeedInitialContentInset(input: {
return { bottom: Math.max(0, input.bottomContentInset) };
}
+// Overlay height offsets both the feed spacer and message anchor below the header.
+export function deriveThreadFeedTopGeometry(input: {
+ readonly usesNativeAutomaticInsets: boolean;
+ readonly headerInset: number;
+ readonly topOverlayInset: number;
+}): { readonly spacerHeight: number; readonly anchorTopInset: number } {
+ return {
+ spacerHeight: (input.usesNativeAutomaticInsets ? 0 : input.headerInset) + input.topOverlayInset,
+ anchorTopInset: input.headerInset + input.topOverlayInset,
+ };
+}
+
export type WorkspaceAuxiliaryPaneRole = "supplementary" | "inspector";
export function deriveLayout(input: {
diff --git a/apps/mobile/src/state/contribution-status.ts b/apps/mobile/src/state/contribution-status.ts
new file mode 100644
index 0000000000000..8a83addc96ab1
--- /dev/null
+++ b/apps/mobile/src/state/contribution-status.ts
@@ -0,0 +1,9 @@
+import { createContributionStatusEnvironmentAtoms } from "@t3tools/client-runtime/state/contribution-status";
+
+import { connectionAtomRuntime } from "../connection/runtime";
+import { serverEnvironment } from "./server";
+
+export const contributionStatusEnvironment = createContributionStatusEnvironmentAtoms(
+ connectionAtomRuntime,
+ { configValueAtom: serverEnvironment.configValueAtom },
+);
diff --git a/apps/mobile/src/state/plugin-actions.test.ts b/apps/mobile/src/state/plugin-actions.test.ts
new file mode 100644
index 0000000000000..542003f432e9a
--- /dev/null
+++ b/apps/mobile/src/state/plugin-actions.test.ts
@@ -0,0 +1,100 @@
+import {
+ AuthOrchestrationOperateScope,
+ EnvironmentId,
+ PluginActionId,
+ ProjectId,
+ ThreadId,
+ type PluginAction,
+} from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import { AsyncResult } from "effect/reactivity";
+import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+const state = vi.hoisted(() => ({
+ canOperate: true,
+ invoke: vi.fn(),
+ alert: vi.fn(),
+}));
+
+// The session grant, the invoke RPC and the alert are the boundaries.
+vi.mock("react-native", () => ({ Alert: { alert: state.alert } }));
+vi.mock("expo-haptics", () => ({
+ notificationAsync: async () => {},
+ NotificationFeedbackType: { Success: "success" },
+}));
+vi.mock("./session", () => ({
+ readEnvironmentScope: (_environmentId: string, scope: string) =>
+ scope === AuthOrchestrationOperateScope && state.canOperate,
+}));
+vi.mock("@t3tools/client-runtime/state/runtime", async (importOriginal) => ({
+ ...(await importOriginal()),
+ runAtomCommand: state.invoke,
+}));
+vi.mock("@t3tools/client-runtime/state/pluginActions", async (importOriginal) => ({
+ ...(await importOriginal()),
+ createPluginActionEnvironmentAtoms: () => ({ invoke: "invoke", snapshot: () => null }),
+}));
+vi.mock("../connection/runtime", () => ({ connectionAtomRuntime: {} }));
+vi.mock("./atom-registry", () => ({ appAtomRegistry: {} }));
+vi.mock("./query", () => ({ useEnvironmentQuery: () => ({ data: null }) }));
+
+import { buildPluginActionPaletteItems } from "../features/keyboard/commandPaletteItems";
+import { runPluginAction } from "./plugin-actions";
+
+const environmentId = EnvironmentId.make("environment-1");
+const threadId = ThreadId.make("thread-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 run = () =>
+ runPluginAction({ environmentId, action: deploy, target: { _tag: "thread", threadId } });
+
+beforeEach(() => {
+ state.canOperate = true;
+ state.invoke.mockReset().mockResolvedValue(AsyncResult.success({ message: "Deployed" }));
+ state.alert.mockReset();
+});
+
+describe("runPluginAction", () => {
+ it("reports that the plugin ran the action", async () => {
+ await expect(run()).resolves.toBe(true);
+ expect(state.invoke).toHaveBeenCalledOnce();
+ expect(state.alert).toHaveBeenCalledWith("Deploy this branch", "Deployed");
+ });
+
+ it("reports a refused action as not run", async () => {
+ state.invoke.mockResolvedValue(AsyncResult.failure(Cause.fail(new Error("Forbidden"))));
+ await expect(run()).resolves.toBe(false);
+ expect(state.alert).toHaveBeenCalledWith("Deploy this branch failed", "Forbidden");
+ });
+
+ it("does not invoke once the connection has lost its operate grant", async () => {
+ state.canOperate = false;
+ await expect(run()).resolves.toBe(false);
+ expect(state.invoke).not.toHaveBeenCalled();
+ });
+
+ it("rechecks the grant when a palette entry runs after the palette closes", async () => {
+ // The palette stores the picked entry and runs it once its modal is dismissed.
+ const [entry] = buildPluginActionPaletteItems({
+ actions: [deploy],
+ canOperate: true,
+ environmentId,
+ threadId,
+ projectId: ProjectId.make("project-1"),
+ runAction: (input) => void runPluginAction(input),
+ });
+ state.canOperate = false;
+
+ entry?.run();
+ await Promise.resolve();
+
+ expect(state.invoke).not.toHaveBeenCalled();
+ });
+});
diff --git a/apps/mobile/src/state/plugin-actions.ts b/apps/mobile/src/state/plugin-actions.ts
new file mode 100644
index 0000000000000..1ccc0e59a847e
--- /dev/null
+++ b/apps/mobile/src/state/plugin-actions.ts
@@ -0,0 +1,80 @@
+import { createPluginActionEnvironmentAtoms } from "@t3tools/client-runtime/state/pluginActions";
+import {
+ isAtomCommandInterrupted,
+ runAtomCommand,
+ squashAtomCommandFailure,
+} from "@t3tools/client-runtime/state/runtime";
+import {
+ AuthOrchestrationOperateScope,
+ type EnvironmentId,
+ type PluginAction,
+ type PluginActionTarget,
+} from "@t3tools/contracts";
+import * as Haptics from "expo-haptics";
+import { Alert } from "react-native";
+
+import { connectionAtomRuntime } from "../connection/runtime";
+import { appAtomRegistry } from "./atom-registry";
+import { useEnvironmentQuery } from "./query";
+import { readEnvironmentScope } from "./session";
+
+const pluginActionEnvironment = createPluginActionEnvironmentAtoms(connectionAtomRuntime);
+
+const NO_ACTIONS: ReadonlyArray = [];
+
+/** The environment's plugin actions; none on servers without them. */
+export function usePluginActions(environmentId: EnvironmentId | null): ReadonlyArray {
+ return (
+ useEnvironmentQuery(
+ environmentId === null
+ ? null
+ : pluginActionEnvironment.snapshot({ environmentId, input: {} }),
+ ).data?.actions ?? NO_ACTIONS
+ );
+}
+
+/** The environment's plugin actions snapshot, including what its limit left out; null until it arrives. */
+export function usePluginActionsSnapshot(environmentId: EnvironmentId | null) {
+ return useEnvironmentQuery(
+ environmentId === null ? null : pluginActionEnvironment.snapshot({ environmentId, input: {} }),
+ ).data;
+}
+
+/** Whether this connection may run plugin actions now, read from the live grant. */
+export function canRunPluginActionsNow(environmentId: EnvironmentId): boolean {
+ return readEnvironmentScope(environmentId, AuthOrchestrationOperateScope);
+}
+
+// Execution fixes the picked environment and target, then checks the live grant before running.
+export async function runPluginAction(input: {
+ readonly environmentId: EnvironmentId;
+ readonly action: PluginAction;
+ readonly target: PluginActionTarget;
+}): Promise {
+ const { action } = input;
+ if (!canRunPluginActionsNow(input.environmentId)) {
+ Alert.alert(`${action.title} unavailable`, "This connection cannot run plugin actions.");
+ return false;
+ }
+ const result = await runAtomCommand(
+ appAtomRegistry,
+ pluginActionEnvironment.invoke,
+ { environmentId: input.environmentId, input: { actionId: action.id, target: input.target } },
+ { reportFailure: false },
+ );
+ if (result._tag === "Success") {
+ if (result.value.message === null) {
+ void Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success).catch(() => {});
+ } else {
+ Alert.alert(action.title, result.value.message);
+ }
+ return true;
+ }
+ if (isAtomCommandInterrupted(result)) return false;
+ const error = squashAtomCommandFailure(result);
+ Alert.alert(
+ `${action.title} failed`,
+ error instanceof Error ? error.message : "The plugin action failed.",
+ );
+ return false;
+}
diff --git a/apps/mobile/src/state/plugin-notifications.ts b/apps/mobile/src/state/plugin-notifications.ts
new file mode 100644
index 0000000000000..11611914e0cb0
--- /dev/null
+++ b/apps/mobile/src/state/plugin-notifications.ts
@@ -0,0 +1,9 @@
+import { createPluginNotificationEnvironmentAtoms } from "@t3tools/client-runtime/state/plugin-notifications";
+
+import { connectionAtomRuntime } from "../connection/runtime";
+import { serverEnvironment } from "./server";
+
+export const pluginNotificationEnvironment = createPluginNotificationEnvironmentAtoms(
+ connectionAtomRuntime,
+ { configValueAtom: serverEnvironment.configValueAtom },
+);
diff --git a/apps/mobile/src/state/plugins.ts b/apps/mobile/src/state/plugins.ts
new file mode 100644
index 0000000000000..288261924ee74
--- /dev/null
+++ b/apps/mobile/src/state/plugins.ts
@@ -0,0 +1,13 @@
+import { createPluginEnvironmentAtoms } from "@t3tools/client-runtime/state/plugins";
+import { createPluginNpmEnvironmentAtoms } from "@t3tools/client-runtime/state/pluginNpm";
+import { createPluginSettingsEnvironmentAtoms } from "@t3tools/client-runtime/state/pluginSettings";
+import { createPluginViewEnvironmentAtoms } from "@t3tools/client-runtime/state/pluginViews";
+
+import { connectionAtomRuntime } from "../connection/runtime";
+
+export const pluginEnvironment = createPluginEnvironmentAtoms(connectionAtomRuntime);
+export const pluginSettingsEnvironment =
+ createPluginSettingsEnvironmentAtoms(connectionAtomRuntime);
+export const pluginNpmEnvironment = createPluginNpmEnvironmentAtoms(connectionAtomRuntime);
+/** Mobile shows no views; it reads which views a plugin offers for its details. */
+export const pluginViewEnvironment = createPluginViewEnvironmentAtoms(connectionAtomRuntime);
diff --git a/apps/mobile/vite.config.ts b/apps/mobile/vite.config.ts
index b64dc1c4e2a12..6358670d7c4ff 100644
--- a/apps/mobile/vite.config.ts
+++ b/apps/mobile/vite.config.ts
@@ -4,6 +4,7 @@ import { defineConfig, normalizePath } from "vite-plus";
import "vite-plus/test/config";
const reactTests = [
+ "src/features/threads/use-composer-command-menu.plugin-actions.test.tsx",
"src/features/threads/new-task-flow-provider.test.tsx",
"src/features/workspace/workspace-tabs-state.test.ts",
"src/state/use-thread-pr.demand.test.tsx",
diff --git a/apps/server/src/auth/RpcAuthorization.ts b/apps/server/src/auth/RpcAuthorization.ts
index 6049121b41a5d..424d26c9c25df 100644
--- a/apps/server/src/auth/RpcAuthorization.ts
+++ b/apps/server/src/auth/RpcAuthorization.ts
@@ -5,6 +5,7 @@ import {
authScopeRequiredResponse,
AssetCreateUrlInput,
AuthAccessReadScope,
+ AuthAccessWriteScope,
ServerSettingsPatch,
ProviderInstanceMutation,
requiredScopesForServerSettingsPatch,
@@ -115,6 +116,35 @@ export const RPC_REQUIRED_SCOPES = {
// Delivery logs hold request bodies, so they need the same scope as the URL.
[WS_METHODS.scheduledTasksListWebhookDeliveries]: AuthOrchestrationOperateScope,
[WS_METHODS.scheduledTasksGetWebhookDelivery]: AuthOrchestrationOperateScope,
+ // Plugins run as the server's OS user, so changing what runs requires access:write,
+ // which current standard pairings also receive for managing access.
+ [WS_METHODS.pluginsList]: AuthOrchestrationReadScope,
+ [WS_METHODS.pluginsSubscribe]: AuthOrchestrationReadScope,
+ [WS_METHODS.pluginsAdd]: AuthAccessWriteScope,
+ [WS_METHODS.pluginsRefresh]: AuthAccessWriteScope,
+ [WS_METHODS.pluginsConsent]: AuthAccessWriteScope,
+ [WS_METHODS.pluginsEnable]: AuthAccessWriteScope,
+ [WS_METHODS.pluginsDisable]: AuthAccessWriteScope,
+ [WS_METHODS.pluginsRemove]: AuthAccessWriteScope,
+ [WS_METHODS.pluginsResume]: AuthAccessWriteScope,
+ // Saved setting values are readable like the catalogue; secrets are never sent. Saving one
+ // configures code that runs as the server's OS user, so it takes the administrative scope.
+ [WS_METHODS.pluginsSettingsSubscribe]: AuthOrchestrationReadScope,
+ [WS_METHODS.pluginsSettingsUpdate]: AuthAccessWriteScope,
+ // Running an action the administrator already enabled is ordinary operation, like starting a
+ // turn; it cannot change what code runs.
+ [WS_METHODS.pluginActionsSubscribe]: AuthOrchestrationReadScope,
+ [WS_METHODS.pluginActionsInvoke]: AuthOrchestrationOperateScope,
+ // A view call runs the plugin's own `view:` handlers, like an action a client takes.
+ [WS_METHODS.pluginViewsSubscribe]: AuthOrchestrationReadScope,
+ [WS_METHODS.pluginViewsReadBundle]: AuthOrchestrationReadScope,
+ [WS_METHODS.pluginViewsCall]: AuthOrchestrationOperateScope,
+ // Installing or updating from npm changes which code the server runs, so it is administrative.
+ [WS_METHODS.pluginsNpmList]: AuthOrchestrationReadScope,
+ [WS_METHODS.pluginsNpmAdd]: AuthAccessWriteScope,
+ [WS_METHODS.pluginsNpmStageUpdate]: AuthAccessWriteScope,
+ [WS_METHODS.pluginsNpmApplyUpdate]: AuthAccessWriteScope,
+ [WS_METHODS.pluginsNpmDiscardUpdate]: AuthAccessWriteScope,
[WS_METHODS.cloudGetRelayClientStatus]: AuthRelayReadScope,
[WS_METHODS.cloudInstallRelayClient]: AuthRelayWriteScope,
[WS_METHODS.pullRequestsList]: AuthOrchestrationReadScope,
@@ -169,6 +199,8 @@ export const RPC_REQUIRED_SCOPES = {
[WS_METHODS.subscribeWorktreeSetup]: AuthOrchestrationReadScope,
[WS_METHODS.worktreeSetupCancel]: AuthOrchestrationOperateScope,
[WS_METHODS.subscribeResourceTelemetry]: AuthDiagnosticsReadScope,
+ [WS_METHODS.subscribeContributionStatus]: AuthOrchestrationReadScope,
+ [WS_METHODS.pluginsNotificationsSubscribe]: AuthOrchestrationReadScope,
[WS_METHODS.vcsRefreshStatus]: AuthOrchestrationReadScope,
[WS_METHODS.gitResolvePullRequest]: AuthOrchestrationReadScope,
[WS_METHODS.vcsListRefs]: AuthOrchestrationReadScope,
diff --git a/apps/server/src/auth/ServerSecretStore.test.ts b/apps/server/src/auth/ServerSecretStore.test.ts
index b3dd615c8d4d7..870f6ab892e67 100644
--- a/apps/server/src/auth/ServerSecretStore.test.ts
+++ b/apps/server/src/auth/ServerSecretStore.test.ts
@@ -1,9 +1,12 @@
+// @effect-diagnostics nodeBuiltinImport:off -- The child fixture proves writer liveness and crash cleanup across processes.
+import * as NodeChildProcess from "node:child_process";
import * as NodeServices from "@effect/platform-node/NodeServices";
import { assert, it } from "@effect/vitest";
import * as Cause from "effect/Cause";
import * as Deferred from "effect/Deferred";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
+import * as Fiber from "effect/Fiber";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Ref from "effect/Ref";
@@ -148,6 +151,204 @@ it.layer(NodeServices.layer)("ServerSecretStore.layer", (it) => {
}).pipe(Effect.provide(layerConcurrentCreateSecretStore())),
);
+ it.effect.each([false, true])(
+ "cleans crash temporaries at startup with a final secret: %s",
+ (hasFinal) =>
+ Effect.gen(function* () {
+ const config = yield* ServerConfig.ServerConfig;
+ const fs = yield* FileSystem.FileSystem;
+ yield* fs.makeDirectory(config.secretsDir, { recursive: true });
+ const final = `${config.secretsDir}/plugin-setting-test.bin`;
+ const temporary = `${final}.00000000-0000-4000-8000-000000000001.tmp`;
+ const reusedPidTemporary = `${final}.${process.pid}-00000000.00000000-0000-4000-8000-000000000002.tmp`;
+ const legacyPidTemporary = `${final}.${process.pid}.00000000-0000-4000-8000-000000000003.tmp`;
+ const unrelated = `${config.secretsDir}/notes.tmp`;
+ if (hasFinal) yield* fs.writeFileString(final, "old-secret");
+ yield* fs.writeFileString(temporary, "new-secret");
+ yield* fs.writeFileString(reusedPidTemporary, "old-instance-secret");
+ yield* fs.writeFileString(legacyPidTemporary, "legacy-instance-secret");
+ yield* fs.writeFileString(unrelated, "keep");
+ const store = yield* ServerSecretStore.make;
+ assert.isFalse(yield* fs.exists(temporary));
+ assert.isFalse(yield* fs.exists(reusedPidTemporary));
+ assert.isFalse(yield* fs.exists(legacyPidTemporary));
+ assert.isTrue(yield* fs.exists(unrelated));
+ assert.equal(Option.isSome(yield* store.get("plugin-setting-test")), hasFinal);
+ if (hasFinal) assert.equal(yield* fs.readFileString(final), "old-secret");
+ }).pipe(Effect.provide(layerServerConfig())),
+ );
+
+ it.effect("removes orphan temporaries when the final secret is missing", () =>
+ Effect.gen(function* () {
+ const store = yield* ServerSecretStore.ServerSecretStore;
+ const fs = yield* FileSystem.FileSystem;
+ const temporary = `${store.directory}/plugin-setting-test.bin.00000000-0000-4000-8000-000000000001.tmp`;
+ const other = `${store.directory}/other.bin.00000000-0000-4000-8000-000000000001.tmp`;
+ yield* fs.writeFileString(temporary, "secret");
+ yield* fs.writeFileString(other, "other-secret");
+ yield* store.remove("plugin-setting-test");
+ assert.isFalse(yield* fs.exists(temporary));
+ assert.isTrue(yield* fs.exists(other));
+ }).pipe(Effect.provide(layerServerSecretStore())),
+ );
+
+ it.effect("a second store preserves an active replacement during startup and removal", () =>
+ Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ const config = yield* ServerConfig.ServerConfig;
+ const written = yield* Deferred.make();
+ const finish = yield* Deferred.make();
+ const writer = yield* ServerSecretStore.make.pipe(
+ Effect.provideService(FileSystem.FileSystem, {
+ ...fs,
+ rename: (from, to) =>
+ Deferred.succeed(written, undefined).pipe(
+ Effect.andThen(Deferred.await(finish)),
+ Effect.andThen(fs.rename(from, to)),
+ ),
+ }),
+ );
+ yield* Effect.addFinalizer(() => Deferred.succeed(finish, undefined));
+ const writing = yield* writer
+ .set("shared-secret", Uint8Array.from([1, 2, 3]))
+ .pipe(Effect.forkChild);
+ yield* Deferred.await(written);
+ const replacement = (yield* fs.readDirectory(config.secretsDir)).find((name) =>
+ name.endsWith(".tmp"),
+ )!;
+ const second = yield* ServerSecretStore.make;
+ yield* second.remove("shared-secret");
+ assert.isTrue(yield* fs.exists(`${config.secretsDir}/${replacement}`));
+ yield* Deferred.succeed(finish, undefined);
+ yield* Fiber.join(writing);
+ assert.deepEqual(
+ Array.from(Option.getOrThrow(yield* second.get("shared-secret"))),
+ [1, 2, 3],
+ );
+ assert.isFalse(yield* fs.exists(`${config.secretsDir}/${replacement}`));
+ }).pipe(Effect.provide(layerServerConfig())),
+ );
+
+ it.effect("a second store preserves an active create during startup and removal", () =>
+ Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ const config = yield* ServerConfig.ServerConfig;
+ const written = yield* Deferred.make();
+ const finish = yield* Deferred.make();
+ const writer = yield* ServerSecretStore.make.pipe(
+ Effect.provideService(FileSystem.FileSystem, {
+ ...fs,
+ link: (from, to) =>
+ Deferred.succeed(written, undefined).pipe(
+ Effect.andThen(Deferred.await(finish)),
+ Effect.andThen(fs.link(from, to)),
+ ),
+ }),
+ );
+ yield* Effect.addFinalizer(() => Deferred.succeed(finish, undefined));
+ const writing = yield* writer
+ .create("shared-secret", Uint8Array.from([1, 2, 3]))
+ .pipe(Effect.forkChild);
+ yield* Deferred.await(written);
+ const replacement = (yield* fs.readDirectory(config.secretsDir)).find((name) =>
+ name.endsWith(".tmp"),
+ )!;
+ const second = yield* ServerSecretStore.make;
+ yield* second.remove("shared-secret");
+ assert.isTrue(yield* fs.exists(`${config.secretsDir}/${replacement}`));
+ yield* Deferred.succeed(finish, undefined);
+ yield* Fiber.join(writing);
+ assert.deepEqual(
+ Array.from(Option.getOrThrow(yield* second.get("shared-secret"))),
+ [1, 2, 3],
+ );
+ assert.isFalse(yield* fs.exists(`${config.secretsDir}/${replacement}`));
+ }).pipe(Effect.provide(layerServerConfig())),
+ );
+
+ it.effect("cleans its temporary when a replacement is interrupted", () =>
+ Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ const config = yield* ServerConfig.ServerConfig;
+ const written = yield* Deferred.make();
+ const writer = yield* ServerSecretStore.make.pipe(
+ Effect.provideService(FileSystem.FileSystem, {
+ ...fs,
+ rename: () => Deferred.succeed(written, undefined).pipe(Effect.andThen(Effect.never)),
+ }),
+ );
+ const writing = yield* writer
+ .set("interrupted-secret", Uint8Array.from([1]))
+ .pipe(Effect.forkChild);
+ yield* Deferred.await(written);
+ yield* Fiber.interrupt(writing);
+ assert.deepEqual(yield* fs.readDirectory(config.secretsDir), []);
+ }).pipe(Effect.provide(layerServerConfig())),
+ );
+
+ it.effect("retains a foreign live writer's temporary and sweeps it after exit", () =>
+ Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ const config = yield* ServerConfig.ServerConfig;
+ yield* fs.makeDirectory(config.secretsDir, { recursive: true });
+ const child = yield* Effect.acquireRelease(
+ Effect.sync(() =>
+ NodeChildProcess.spawn(
+ process.execPath,
+ [
+ "-e",
+ `
+ const fs = require('node:fs');
+ const path = require('node:path');
+ const temporary = path.join(process.argv[1], 'foreign.bin.' + process.pid + '.00000000-0000-4000-8000-000000000001.tmp');
+ fs.writeFileSync(temporary, 'crash-secret', { mode: 0o600 });
+ process.on('message', () => process.exit(0));
+ process.send(temporary);
+ `,
+ config.secretsDir,
+ ],
+ { stdio: ["ignore", "ignore", "ignore", "ipc"] },
+ ),
+ ),
+ (process) =>
+ Effect.promise(
+ () =>
+ new Promise((resolve) => {
+ if (process.exitCode !== null || process.signalCode !== null) return resolve();
+ process.once("exit", () => resolve());
+ process.kill();
+ }),
+ ),
+ );
+ const temporary = yield* Effect.tryPromise(
+ () =>
+ new Promise((resolve, reject) => {
+ child.once("message", (message) =>
+ typeof message === "string"
+ ? resolve(message)
+ : reject(new Error("Unexpected child fixture message")),
+ );
+ child.once("error", reject);
+ child.once("exit", () =>
+ reject(new Error("Child exited before publishing its temporary")),
+ );
+ }),
+ );
+ const second = yield* ServerSecretStore.make;
+ yield* second.remove("foreign");
+ assert.isTrue(yield* fs.exists(temporary));
+ yield* Effect.promise(
+ () =>
+ new Promise((resolve) => {
+ child.once("exit", () => resolve());
+ child.send("exit");
+ }),
+ );
+ yield* ServerSecretStore.make;
+ assert.isFalse(yield* fs.exists(temporary));
+ }).pipe(Effect.provide(layerServerConfig())),
+ );
+
it.effect("propagates read failures other than missing-file errors", () =>
Effect.gen(function* () {
const secretStore = yield* ServerSecretStore.ServerSecretStore;
diff --git a/apps/server/src/auth/ServerSecretStore.ts b/apps/server/src/auth/ServerSecretStore.ts
index 100e0e19ca2ae..50dea6adcfa63 100644
--- a/apps/server/src/auth/ServerSecretStore.ts
+++ b/apps/server/src/auth/ServerSecretStore.ts
@@ -150,9 +150,23 @@ export class ServerSecretStore extends Context.Service<
}
>()("t3/auth/ServerSecretStore") {}
+let processInstance: string | undefined;
+
+// A restarted container often reuses its own PID; its old temporaries belong to a different instance.
+const isWriterAlive = (pid: number, instance: string | undefined) => {
+ if (pid === process.pid) return instance === processInstance;
+ try {
+ process.kill(pid, 0);
+ return true;
+ } catch (error) {
+ return !(error instanceof Error && "code" in error && error.code === "ESRCH");
+ }
+};
+
/** @public */
export const make = Effect.gen(function* () {
const crypto = yield* Crypto.Crypto;
+ processInstance ??= (crypto.nextIntUnsafe() >>> 0).toString(16).padStart(8, "0");
const fileSystem = yield* FileSystem.FileSystem;
const path = yield* Path.Path;
const serverConfig = yield* ServerConfig.ServerConfig;
@@ -170,6 +184,30 @@ export const make = Effect.gen(function* () {
const resolveSecretPath = (name: string) => path.join(serverConfig.secretsDir, `${name}.bin`);
+ const removeTemporaryFiles = Effect.fnUntraced(function* (name?: string) {
+ for (const file of yield* fileSystem.readDirectory(serverConfig.secretsDir)) {
+ const match =
+ /^(.*\.bin)\.(?:(\d+)(?:-([0-9a-f]{8}))?\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.tmp$/i.exec(
+ file,
+ );
+ if (
+ match !== null &&
+ (name === undefined || match[1] === `${name}.bin`) &&
+ (match[2] === undefined || !isWriterAlive(Number(match[2]), match[3]))
+ ) {
+ yield* fileSystem.remove(path.join(serverConfig.secretsDir, file), { force: true });
+ }
+ }
+ });
+
+ // New temporaries name their writer so another process cannot sweep an active replacement.
+ // UUID-only files predate writer ownership and remain eligible for crash recovery.
+ yield* removeTemporaryFiles().pipe(
+ Effect.mapError(
+ (cause) => new SecretStoreRemoveError({ resource: "temporary secret files", cause }),
+ ),
+ );
+
const get: ServerSecretStore["Service"]["get"] = (name) =>
fileSystem.readFile(resolveSecretPath(name)).pipe(
Effect.map((bytes) => Option.some(Uint8Array.from(bytes))),
@@ -197,26 +235,17 @@ export const make = Effect.gen(function* () {
}),
),
Effect.flatMap((uuid) => {
- const tempPath = `${secretPath}.${uuid}.tmp`;
+ const tempPath = `${secretPath}.${process.pid}-${processInstance}.${uuid}.tmp`;
return Effect.gen(function* () {
yield* fileSystem.writeFile(tempPath, value);
yield* fileSystem.chmod(tempPath, 0o600);
yield* fileSystem.rename(tempPath, secretPath);
yield* fileSystem.chmod(secretPath, 0o600);
}).pipe(
- Effect.catch((cause) =>
- fileSystem.remove(tempPath).pipe(
- Effect.ignore,
- Effect.flatMap(() =>
- Effect.fail(
- new SecretStorePersistError({
- resource: `secret ${name}`,
- cause,
- }),
- ),
- ),
- ),
+ Effect.mapError(
+ (cause) => new SecretStorePersistError({ resource: `secret ${name}`, cause }),
),
+ Effect.ensuring(fileSystem.remove(tempPath, { force: true }).pipe(Effect.ignore)),
);
}),
Effect.withSpan("ServerSecretStore.set"),
@@ -236,7 +265,7 @@ export const make = Effect.gen(function* () {
}),
),
Effect.flatMap((uuid) => {
- const tempPath = `${secretPath}.${uuid}.tmp`;
+ const tempPath = `${secretPath}.${process.pid}-${processInstance}.${uuid}.tmp`;
return Effect.gen(function* () {
yield* Effect.scoped(
Effect.gen(function* () {
@@ -304,7 +333,8 @@ export const make = Effect.gen(function* () {
);
const remove: ServerSecretStore["Service"]["remove"] = (name) =>
- fileSystem.remove(resolveSecretPath(name)).pipe(
+ removeTemporaryFiles(name).pipe(
+ Effect.andThen(fileSystem.remove(resolveSecretPath(name))),
Effect.catch((cause) =>
cause.reason._tag === "NotFound"
? Effect.void
diff --git a/apps/server/src/bin.ts b/apps/server/src/bin.ts
index 936c79943fd74..93380095f2f50 100644
--- a/apps/server/src/bin.ts
+++ b/apps/server/src/bin.ts
@@ -1,7 +1,7 @@
/**
* Every ACP agent spawns `t3 acp-mcp-bridge` while opening its session, and terminal-fallback
* agents run `t3 acp-mcp-call` per tool call, so their startup sits on first-message latency.
- * They and Codex's managed-token helper dispatch before the full CLI module graph (seconds
+ * They, plugin children and Codex's managed-token helper dispatch before the full CLI module graph (seconds
* of evaluation) loads; everything else defers to the real CLI in ./binCli.ts.
*/
import { isEntrypoint } from "./entrypoint.ts";
@@ -35,6 +35,10 @@ if (
} else if (command === "acp-mcp-bridge" || command === "acp-mcp-call") {
const { runAcpMcpCliFastPath } = await import("./mcp/AcpMcpStdioBridge.ts");
await runAcpMcpCliFastPath(command, process.argv.slice(3));
+ } else if (command === "__plugin-host") {
+ // One process per enabled plugin: keep its footprint to the child runtime.
+ const { runPluginHostChild } = await import("./plugins/pluginHostChild.ts");
+ runPluginHostChild();
} else {
enableCliCompileCache();
// Windows desktop launches without stdin; attach before reading, except on fast paths using pipes.
diff --git a/apps/server/src/contributions/ContributionStatusRpc.test.ts b/apps/server/src/contributions/ContributionStatusRpc.test.ts
new file mode 100644
index 0000000000000..73a7ba435b35c
--- /dev/null
+++ b/apps/server/src/contributions/ContributionStatusRpc.test.ts
@@ -0,0 +1,208 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+import {
+ AuthOrchestrationReadScope,
+ AuthRelayReadScope,
+ type AuthEnvironmentScope,
+ ProviderDriverKind,
+ ProviderInstanceId,
+ ProviderSessionId,
+ ThreadId,
+ WS_METHODS,
+ WsRpcGroup,
+} from "@t3tools/contracts";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Queue from "effect/Queue";
+import * as TestClock from "effect/testing/TestClock";
+import { RpcMessage, RpcSerialization, RpcServer } from "effect/rpc";
+
+import * as PortScanner from "../preview/PortScanner.ts";
+import * as RpcAuthorization from "../auth/RpcAuthorization.ts";
+import { RPC_REQUIRED_SCOPES } from "../auth/RpcAuthorization.ts";
+import * as ProviderEventLoggers from "@t3tools/provider-core/server/ProviderEventLoggers";
+import * as ProviderOrchestrationAdapterInfrastructure from "../provider/ProviderOrchestrationAdapterInfrastructure.ts";
+import * as ContributionStatusStore from "@t3tools/provider-core/server/ContributionStatusStore";
+
+const TAG = WS_METHODS.subscribeContributionStatus;
+const THREAD = ThreadId.make("thread-1");
+const SOURCE = {
+ kind: "provider-session",
+ providerSessionId: ProviderSessionId.make("session-1"),
+ providerInstanceId: ProviderInstanceId.make("pi"),
+ driver: ProviderDriverKind.make("pi"),
+} as const;
+const encodedEntry = (texts: ReadonlyArray) => ({
+ threadId: THREAD,
+ source: SOURCE,
+ items: texts.map((text, index) => ({ key: `k${index}`, text })),
+});
+
+// The server group narrowed to this RPC; it keeps the group's scope middleware.
+const group = WsRpcGroup.omit(
+ ...[...WsRpcGroup.requests.keys()].filter(
+ (tag): tag is Exclude => tag !== TAG,
+ ),
+);
+
+/**
+ * Serves `subscribeContributionStatus` as ws.ts does (the store's subscription
+ * stream behind the connection's scope middleware) over an in-memory RPC protocol.
+ */
+const serveStatus = Effect.fn("serveStatus")(function* (
+ store: ContributionStatusStore.ContributionStatusStoreShape,
+ scopes: ReadonlyArray,
+) {
+ const responses = yield* Queue.unbounded();
+ const receive = yield* Deferred.make[0]>();
+ const protocol = yield* RpcServer.Protocol.make((write) =>
+ Effect.gen(function* () {
+ yield* Deferred.succeed(receive, write);
+ const serialization = yield* RpcSerialization.RpcSerialization;
+ return {
+ disconnects: yield* Queue.unbounded(),
+ send: (_clientId, response) => Queue.offer(responses, response),
+ end: () => Effect.void,
+ clientIds: Effect.succeed(new Set([0])),
+ initialMessage: Effect.succeedNone,
+ supportsAck: false,
+ supportsTransferables: false,
+ supportsSpanPropagation: false,
+ supportsNotifications: true,
+ codecFor: serialization.codecFor,
+ };
+ }),
+ );
+ yield* RpcServer.make(group).pipe(
+ Effect.provide(
+ Layer.merge(
+ group.toLayerHandler(TAG, () => ContributionStatusStore.subscriptionStream(store)),
+ RpcAuthorization.layer(scopes),
+ ),
+ ),
+ Effect.provideService(RpcServer.Protocol, protocol),
+ Effect.forkScoped,
+ );
+ const write = yield* Deferred.await(receive);
+ return {
+ subscribe: (id: string) =>
+ write(0, { _tag: "Request", id, tag: TAG, payload: {}, headers: [] }),
+ interrupt: (id: string) => write(0, { _tag: "Interrupt", requestId: id }),
+ /** The next frame the client receives; the store publishes one per visible change. */
+ next: Queue.take(responses),
+ /** Lets server fibers run so a frame that would be sent is in the queue. */
+ pending: TestClock.adjust(0).pipe(Effect.andThen(Queue.size(responses))),
+ };
+});
+
+const chunk = (
+ requestId: string,
+ entries: ReadonlyArray>,
+): RpcMessage.FromServerEncoded => ({ _tag: "Chunk", requestId, values: [{ entries }] });
+
+describe("subscribeContributionStatus", () => {
+ it.effect("streams the current snapshot, replacements, and a fresh snapshot on resubscribe", () =>
+ Effect.gen(function* () {
+ const store = yield* ContributionStatusStore.make();
+ const handle = yield* store.openSource(SOURCE);
+ yield* handle.bindThread(THREAD);
+ yield* handle.set({ key: "k0", text: "plan" });
+ const client = yield* serveStatus(store, [AuthOrchestrationReadScope]);
+
+ yield* client.subscribe("1");
+ assert.deepStrictEqual(yield* client.next, chunk("1", [encodedEntry(["plan"])]));
+
+ yield* handle.set({ key: "k0", text: "build" });
+ assert.deepStrictEqual(yield* client.next, chunk("1", [encodedEntry(["build"])]));
+ yield* handle.clear("k0");
+ assert.deepStrictEqual(yield* client.next, chunk("1", []));
+
+ // A reconnect is a new subscription whose first frame is the current state.
+ yield* handle.set({ key: "k0", text: "review" });
+ assert.deepStrictEqual(yield* client.next, chunk("1", [encodedEntry(["review"])]));
+ yield* client.subscribe("2");
+ assert.deepStrictEqual(yield* client.next, chunk("2", [encodedEntry(["review"])]));
+
+ // An interrupted subscription stops receiving frames; the other keeps going.
+ yield* client.interrupt("1");
+ assert.strictEqual((yield* client.next)._tag, "Exit");
+ yield* handle.set({ key: "k0", text: "done" });
+ assert.deepStrictEqual(yield* client.next, chunk("2", [encodedEntry(["done"])]));
+ assert.strictEqual(yield* client.pending, 0);
+ }).pipe(Effect.provide(RpcSerialization.layerJson), Effect.scoped),
+ );
+
+ it.effect("refuses a client without the orchestration read scope", () =>
+ Effect.gen(function* () {
+ const store = yield* ContributionStatusStore.make();
+ const handle = yield* store.openSource(SOURCE);
+ yield* handle.bindThread(THREAD);
+ yield* handle.set({ key: "k0", text: "plan" });
+ const client = yield* serveStatus(store, [AuthRelayReadScope]);
+
+ yield* client.subscribe("1");
+ assert.deepStrictEqual(yield* client.next, {
+ _tag: "Exit",
+ requestId: "1",
+ exit: {
+ _tag: "Failure",
+ cause: [
+ {
+ _tag: "Fail",
+ error: {
+ _tag: "EnvironmentAuthorizationError",
+ message: `The authenticated token is missing required scope: ${AuthOrchestrationReadScope}.`,
+ requiredPermission: AuthOrchestrationReadScope,
+ requiredScope: AuthOrchestrationReadScope,
+ },
+ },
+ ],
+ },
+ });
+ }).pipe(Effect.provide(RpcSerialization.layerJson), Effect.scoped),
+ );
+
+ it.effect("shares one store between provider adapters and the WebSocket stream", () =>
+ Effect.gen(function* () {
+ // Mirrors server.ts: adapters get the store through the provider
+ // infrastructure inside an unwrapped instance-registry layer, while the
+ // WebSocket layer reads it from the runtime's own reference.
+ const producer = Layer.unwrap(
+ Effect.succeed(
+ Layer.effectDiscard(
+ Effect.gen(function* () {
+ const store = yield* ContributionStatusStore.ContributionStatusStore;
+ const handle = yield* store.openSource(SOURCE);
+ yield* handle.bindThread(THREAD);
+ yield* handle.set({ key: "k0", text: "from adapter" });
+ }),
+ ).pipe(Layer.provide(ProviderOrchestrationAdapterInfrastructure.layer)),
+ ),
+ );
+ // As in server.ts, the registry layer sits below the store reference, so
+ // the producer only sees the store its own infrastructure provides.
+ const runtime = ContributionStatusStore.layer.pipe(
+ Layer.provideMerge(producer),
+ Layer.provide(
+ Layer.mergeAll(
+ NodeServices.layer,
+ PortScanner.layerTest,
+ Layer.succeed(
+ ProviderEventLoggers.ProviderEventLoggers,
+ ProviderEventLoggers.NoOpProviderEventLoggers,
+ ),
+ ),
+ ),
+ );
+
+ const snapshot = yield* Effect.gen(function* () {
+ const store = yield* ContributionStatusStore.ContributionStatusStore;
+ return yield* store.snapshot;
+ }).pipe(Effect.provide(runtime));
+ assert.deepStrictEqual(snapshot.entries, [
+ { threadId: THREAD, source: SOURCE, items: [{ key: "k0", text: "from adapter" }] },
+ ]);
+ }),
+ );
+});
diff --git a/apps/server/src/environment/ServerEnvironment.ts b/apps/server/src/environment/ServerEnvironment.ts
index d542b4ee55bb4..b6bd34ed11de1 100644
--- a/apps/server/src/environment/ServerEnvironment.ts
+++ b/apps/server/src/environment/ServerEnvironment.ts
@@ -264,6 +264,13 @@ export const make = Effect.gen(function* () {
...(hostPlatform === "win32" ? {} : { localServerStop: true }),
environmentIcon: true,
projectCloneTracking: true,
+ contributionStatus: true,
+ plugins: true,
+ pluginSettings: true,
+ pluginActions: true,
+ pluginViews: true,
+ pluginNpm: true,
+ pluginNotifications: true,
projectOrganization: true,
ignoredFileListing: true,
triage: true,
diff --git a/apps/server/src/mcp/McpHttpServer.ts b/apps/server/src/mcp/McpHttpServer.ts
index e684316f48d9a..0cf303ab4061c 100644
--- a/apps/server/src/mcp/McpHttpServer.ts
+++ b/apps/server/src/mcp/McpHttpServer.ts
@@ -69,6 +69,8 @@ import { WorktreeToolkit } from "./toolkits/worktree/tools.ts";
import * as WorktreeMcpService from "./WorktreeMcpService.ts";
import * as PullRequestsHandlers from "./toolkits/pullRequests/handlers.ts";
import { PullRequestsToolkit } from "./toolkits/pullRequests/tools.ts";
+import * as PluginToolsHandlers from "./toolkits/pluginTools/handlers.ts";
+import { PluginToolsToolkit } from "./toolkits/pluginTools/tools.ts";
import * as DeviceHandlers from "./toolkits/device/handlers.ts";
import {
DeviceScreenshotTool,
@@ -1125,6 +1127,11 @@ export const layerPullRequestsToolkit = toolkitRegistration(
PullRequestsHandlers.layer,
);
+export const layerPluginToolsToolkit = toolkitRegistration(
+ PluginToolsToolkit,
+ PluginToolsHandlers.layer,
+);
+
const layerDeviceStandardToolkitRegistration = toolkitRegistration(
DeviceStandardToolkit,
DeviceHandlers.layerStandard,
@@ -1161,6 +1168,7 @@ export const layerTools = Layer.mergeAll(
layerPullRequestsToolkit,
layerDeviceToolkit,
layerHtmlToolkit,
+ layerPluginToolsToolkit,
);
export const layer = layerTools.pipe(Layer.provideMerge(layerMcpTransport));
diff --git a/apps/server/src/mcp/McpInvocationContext.ts b/apps/server/src/mcp/McpInvocationContext.ts
index 5ce9669bc4d83..706e321ca05c9 100644
--- a/apps/server/src/mcp/McpInvocationContext.ts
+++ b/apps/server/src/mcp/McpInvocationContext.ts
@@ -14,6 +14,8 @@ import * as Effect from "effect/Effect";
import * as Fiber from "effect/Fiber";
import { formatThreadLink } from "@t3tools/shared/threadLinks";
+import type { PluginToolGrant } from "../plugins/PluginTools.ts";
+
const ALL_MCP_CAPABILITIES = [
"preview",
"orchestration",
@@ -104,6 +106,8 @@ export interface McpInvocationScope {
readonly requestNamespace: string;
readonly thread: McpThreadCaller | undefined;
readonly client: McpClientCaller | undefined;
+ /** Tool plugins enabled when the session was prepared; see PluginTools.ts. */
+ readonly pluginToolGrants?: ReadonlyArray;
/** False while the Linked environments beta is off here; `/mcp` reads it per request. */
readonly linkedEnvironments?: boolean;
}
diff --git a/apps/server/src/mcp/McpSessionRegistry.test.ts b/apps/server/src/mcp/McpSessionRegistry.test.ts
index 282c3dffd6d64..998e58ccf8c89 100644
--- a/apps/server/src/mcp/McpSessionRegistry.test.ts
+++ b/apps/server/src/mcp/McpSessionRegistry.test.ts
@@ -1,6 +1,11 @@
import * as NodeServices from "@effect/platform-node/NodeServices";
import { expect, it } from "@effect/vitest";
-import { EnvironmentId, ProviderInstanceId, ThreadId } from "@t3tools/contracts";
+import {
+ EnvironmentId,
+ PluginInstallationId,
+ ProviderInstanceId,
+ ThreadId,
+} from "@t3tools/contracts";
import * as Effect from "effect/Effect";
import { HttpServer } from "effect/http";
import * as NetAddress from "effect/net/NetAddress";
@@ -159,6 +164,32 @@ it.effect("does not keep credentials of other threads alive", () =>
}),
);
+it.effect("keeps a credential's plugin tool grants and replaces them without rotating it", () =>
+ Effect.gen(function* () {
+ const registry = yield* makeRegistry(() => 1_000);
+ const grant = (generation: number) => ({
+ installationId: PluginInstallationId.make("installation-1"),
+ generation,
+ });
+ const issued = yield* registry.issue({
+ threadId: ThreadId.make("thread-plugin-tools"),
+ providerInstanceId: ProviderInstanceId.make("codex"),
+ pluginToolGrants: [grant(1)],
+ });
+ const other = yield* registry.issue({
+ threadId: ThreadId.make("thread-other"),
+ providerInstanceId: ProviderInstanceId.make("codex"),
+ });
+ const tokenOf = (credential: typeof issued) =>
+ credential.config.authorizationHeader.replace(/^Bearer\s+/, "");
+ expect((yield* registry.resolve(tokenOf(issued)))?.pluginToolGrants).toEqual([grant(1)]);
+ expect((yield* registry.resolve(tokenOf(other)))?.pluginToolGrants).toBeUndefined();
+
+ yield* registry.setPluginToolGrants(issued.config.providerSessionId, [grant(2)]);
+ expect((yield* registry.resolve(tokenOf(issued)))?.pluginToolGrants).toEqual([grant(2)]);
+ expect((yield* registry.resolve(tokenOf(other)))?.pluginToolGrants).toBeUndefined();
+ }),
+);
it.effect("only a trusted touch restores an expired token with its original scope", () =>
Effect.gen(function* () {
let timestamp = 1_000;
diff --git a/apps/server/src/mcp/McpSessionRegistry.testkit.ts b/apps/server/src/mcp/McpSessionRegistry.testkit.ts
index 84676e7ccb1b4..61a271c5b52e0 100644
--- a/apps/server/src/mcp/McpSessionRegistry.testkit.ts
+++ b/apps/server/src/mcp/McpSessionRegistry.testkit.ts
@@ -22,6 +22,7 @@ export const layer = Layer.succeed(
// @effect-diagnostics-next-line effectSucceedWithVoid:off - This optional result requires undefined, not the wider void type.
resolve: () => Effect.succeed(undefined),
touch: () => Effect.void,
+ setPluginToolGrants: () => Effect.void,
revokeProviderSession: () => Effect.void,
revokeThread: () => Effect.void,
revokeAll: Effect.void,
diff --git a/apps/server/src/mcp/McpSessionRegistry.ts b/apps/server/src/mcp/McpSessionRegistry.ts
index 962beb1aed6c7..8f354e31ad4ee 100644
--- a/apps/server/src/mcp/McpSessionRegistry.ts
+++ b/apps/server/src/mcp/McpSessionRegistry.ts
@@ -9,6 +9,7 @@ import { HttpServer } from "effect/http";
import * as NetAddress from "effect/net/NetAddress";
import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
+import type { PluginToolGrant } from "../plugins/PluginTools.ts";
import * as McpInvocationContext from "./McpInvocationContext.ts";
import * as McpProviderSession from "@t3tools/provider-core/server/mcpSession";
@@ -18,6 +19,8 @@ export interface McpCredentialRequest {
/** False omits the preview capability wherever the token is honored. Defaults to full access. */
readonly browserToolsAvailable?: boolean;
readonly capabilities?: ReadonlySet;
+ /** Tool plugins the session may use; none when omitted. */
+ readonly pluginToolGrants?: ReadonlyArray;
readonly subagent?: boolean;
}
@@ -31,6 +34,14 @@ export interface McpSessionRegistryShape {
rawToken: string,
) => Effect.Effect;
readonly touch: (threadId: ThreadId) => Effect.Effect;
+ /**
+ * Replaces the tool plugin grants of a live credential without rotating it,
+ * for a session prepared again on a credential its provider still holds.
+ */
+ readonly setPluginToolGrants: (
+ providerSessionId: string,
+ grants: ReadonlyArray,
+ ) => Effect.Effect;
readonly revokeProviderSession: (providerSessionId: string) => Effect.Effect;
readonly revokeThread: (threadId: ThreadId) => Effect.Effect;
readonly revokeAll: Effect.Effect;
@@ -116,6 +127,9 @@ const makeWithOptions = Effect.fn("McpSessionRegistry.make")(function* (
...(request.capabilities ?? (browserToolsAvailable ? (["preview"] as const) : [])),
]),
issuedAt,
+ ...(request.pluginToolGrants === undefined
+ ? {}
+ : { pluginToolGrants: request.pluginToolGrants }),
};
yield* SynchronizedRef.update(state, ({ records }) => {
const next = new Map(records);
@@ -178,6 +192,22 @@ const makeWithOptions = Effect.fn("McpSessionRegistry.make")(function* (
issue,
resolve,
touch,
+ setPluginToolGrants: Effect.fn("McpSessionRegistry.setPluginToolGrants")(
+ function* (providerSessionId, grants) {
+ yield* SynchronizedRef.update(state, ({ records }) => {
+ const next = new Map(records);
+ for (const [tokenHash, record] of records) {
+ if (record.scope.thread.providerSessionId === providerSessionId) {
+ next.set(tokenHash, {
+ ...record,
+ scope: { ...record.scope, pluginToolGrants: grants },
+ });
+ }
+ }
+ return { records: next };
+ });
+ },
+ ),
revokeProviderSession: Effect.fn("McpSessionRegistry.revokeProviderSession")(
function* (providerSessionId) {
yield* revokeWhere((record) => record.scope.thread.providerSessionId === providerSessionId);
diff --git a/apps/server/src/mcp/McpToolAccess.ts b/apps/server/src/mcp/McpToolAccess.ts
index b82d9bb5ae59c..29ac5a8b1491c 100644
--- a/apps/server/src/mcp/McpToolAccess.ts
+++ b/apps/server/src/mcp/McpToolAccess.ts
@@ -127,12 +127,14 @@ export const reads = (handle: (params: P) => Effect.Effect)
export const readsAsCaller = (handle: (params: P) => Effect.Effect) =>
declare((params: P) => requireThreadCaller.pipe(Effect.flatMap(() => handle(params))), undefined);
-export const actsAsCaller = (handle: (params: P) => Effect.Effect) =>
+export const actsAsCaller = (
+ handle: (params: P, caller: Caller) => Effect.Effect,
+) =>
declare(
(params: P) =>
requireThreadCaller.pipe(
Effect.andThen(writingCaller),
- Effect.flatMap(() => handle(params)),
+ Effect.flatMap((caller) => handle(params, caller)),
),
undefined,
);
diff --git a/apps/server/src/mcp/toolkits/pluginTools/handlers.test.ts b/apps/server/src/mcp/toolkits/pluginTools/handlers.test.ts
new file mode 100644
index 0000000000000..42d5b60e9cf92
--- /dev/null
+++ b/apps/server/src/mcp/toolkits/pluginTools/handlers.test.ts
@@ -0,0 +1,187 @@
+import { expect, it } from "@effect/vitest";
+import {
+ EnvironmentId,
+ PluginInstallationId,
+ PluginToolError,
+ ProviderInstanceId,
+ ThreadId,
+} from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { McpSchema, McpServer } from "effect/ai";
+
+import * as PluginTools from "../../../plugins/PluginTools.ts";
+import * as McpHttpServer from "../../McpHttpServer.ts";
+import * as McpInvocationContext from "../../McpInvocationContext.ts";
+import { liveThreadShell } from "../../McpToolAccess.testkit.ts";
+import * as ThreadManagement from "../../../orchestration-v2/ThreadManagementService.ts";
+
+const grants = [{ installationId: PluginInstallationId.make("installation-1"), generation: 3 }];
+const invocation = {
+ environmentId: EnvironmentId.make("environment-plugin-tools"),
+ capabilities: new Set(),
+ issuedAt: 1,
+ requestNamespace: "thread:thread-plugin-tools",
+ thread: {
+ threadId: ThreadId.make("thread-plugin-tools"),
+ providerSessionId: "provider-session-plugin-tools",
+ providerInstanceId: ProviderInstanceId.make("codex"),
+ },
+ client: undefined,
+ pluginToolGrants: grants,
+} satisfies McpInvocationContext.McpInvocationScope;
+// An MCP OAuth client signed in from outside T3 Code: no thread and no grants.
+const outsideClient = {
+ environmentId: invocation.environmentId,
+ capabilities: new Set(),
+ issuedAt: 1,
+ requestNamespace: "client:session-outside",
+ thread: undefined,
+ client: { sessionId: "session-outside", label: "outside", access: "full-access" },
+} satisfies McpInvocationContext.McpInvocationScope;
+const client = McpSchema.McpServerClient.of({
+ clientId: 1,
+ clientCapabilities: {},
+ clientInfo: { name: "mcp-test", version: "1.0.0" },
+ protocolVersion: "2025-06-18",
+ initializePayload: {
+ protocolVersion: "2025-06-18",
+ capabilities: {},
+ clientInfo: { name: "mcp-test", version: "1.0.0" },
+ },
+ getClient: Effect.die("unused"),
+});
+
+it.effect(
+ "takes grants and thread from the credential and marks the call tool conservatively",
+ () => {
+ const seen: Array = [];
+ let shell = liveThreadShell(invocation.thread.threadId);
+ const threads = Layer.mock(ThreadManagement.ThreadManagementService)({
+ getThreadShell: () => Effect.sync(() => shell),
+ });
+ const tools = Layer.mock(PluginTools.PluginTools)({
+ list: (granted, options) =>
+ Effect.sync(() => {
+ seen.push({ granted, options });
+ return { tools: [], notInThisSession: [] };
+ }),
+ call: (granted, request) =>
+ Effect.suspend(() => {
+ seen.push({ granted, request });
+ return request.tool === "acme.search/lookup"
+ ? Effect.succeed({ hits: 1 })
+ : Effect.fail(
+ new PluginToolError({ reason: "unknown-tool", message: "No such tool." }),
+ );
+ }),
+ });
+ return Effect.gen(function* () {
+ const server = yield* McpServer.McpServer;
+ const registered = Object.fromEntries(server.tools.map(({ tool }) => [tool.name, tool]));
+ expect(registered.plugin_tools_list?.annotations).toMatchObject({
+ readOnlyHint: true,
+ destructiveHint: false,
+ });
+ expect(registered.plugin_tool_call?.annotations).toMatchObject({
+ readOnlyHint: false,
+ destructiveHint: true,
+ openWorldHint: true,
+ });
+ const callTool = (
+ name: string,
+ args: Record,
+ scope: McpInvocationContext.McpInvocationScope = invocation,
+ ) =>
+ server
+ .callTool({ name, arguments: args })
+ .pipe(
+ Effect.provideService(McpInvocationContext.McpInvocationContext, scope),
+ Effect.provideService(McpSchema.McpServerClient, client),
+ );
+
+ const listed = yield* callTool("plugin_tools_list", { plugin: "acme.search", cursor: "a" });
+ expect(listed.isError).toBe(false);
+ // A context the agent passes is only input; the plugin gets the credential's.
+ const called = yield* callTool("plugin_tool_call", {
+ tool: "acme.search/lookup",
+ input: { q: "x", context: { threadId: "spoofed" } },
+ });
+ expect(called).toMatchObject({ isError: false, structuredContent: { result: { hits: 1 } } });
+ const failed = yield* callTool("plugin_tool_call", { tool: "acme.search/nope" });
+ expect(failed.isError).toBe(true);
+ expect(failed.content).toEqual([{ type: "text", text: "No such tool." }]);
+
+ expect(seen).toEqual([
+ { granted: grants, options: { plugin: "acme.search", cursor: "a" } },
+ {
+ granted: grants,
+ request: {
+ tool: "acme.search/lookup",
+ input: { q: "x", context: { threadId: "spoofed" } },
+ context: {
+ environmentId: invocation.environmentId,
+ threadId: invocation.thread.threadId,
+ },
+ },
+ },
+ {
+ granted: grants,
+ request: {
+ tool: "acme.search/nope",
+ input: {},
+ context: {
+ environmentId: invocation.environmentId,
+ threadId: invocation.thread.threadId,
+ },
+ },
+ },
+ ]);
+
+ // Outside clients see no plugin tools and cannot call one; the plugin is never reached.
+ seen.length = 0;
+ const outsideList = yield* callTool("plugin_tools_list", {}, outsideClient);
+ expect(outsideList.isError).toBe(false);
+ const outsideCall = yield* callTool(
+ "plugin_tool_call",
+ { tool: "acme.search/lookup" },
+ outsideClient,
+ );
+ expect(outsideCall.isError).toBe(true);
+ expect(outsideCall.content).toEqual([
+ {
+ type: "text",
+ text: "This tool acts as the calling T3 thread, so it needs an agent running inside T3 Code. This MCP client signed in from outside a thread.",
+ },
+ ]);
+ expect(outsideList.structuredContent).toEqual({ tools: [], notInThisSession: [] });
+ expect(seen).toEqual([]);
+ for (const modes of [
+ { runtimeMode: "approval-required", interactionMode: "default" },
+ { runtimeMode: "auto-accept-edits", interactionMode: "default" },
+ { runtimeMode: "auto", interactionMode: "default" },
+ { runtimeMode: "full-access", interactionMode: "plan" },
+ ] as const) {
+ shell = liveThreadShell(invocation.thread.threadId, modes);
+ const refused = yield* callTool("plugin_tool_call", { tool: "acme.search/lookup" });
+ expect(refused.isError).toBe(true);
+ expect(refused.content).toEqual([
+ {
+ type: "text",
+ text: "Calling a trusted plugin needs a full-access thread in default mode.",
+ },
+ ]);
+ expect(seen).toEqual([]);
+ }
+ }).pipe(
+ Effect.scoped,
+ Effect.provide(
+ McpHttpServer.layerPluginToolsToolkit.pipe(
+ Layer.provideMerge(McpServer.McpServer.layer),
+ Layer.provide(tools),
+ Layer.provide(threads),
+ ),
+ ),
+ );
+ },
+);
diff --git a/apps/server/src/mcp/toolkits/pluginTools/handlers.ts b/apps/server/src/mcp/toolkits/pluginTools/handlers.ts
new file mode 100644
index 0000000000000..c512ef8802770
--- /dev/null
+++ b/apps/server/src/mcp/toolkits/pluginTools/handlers.ts
@@ -0,0 +1,50 @@
+import * as Effect from "effect/Effect";
+
+import * as PluginTools from "../../../plugins/PluginTools.ts";
+import * as McpInvocationContext from "../../McpInvocationContext.ts";
+import * as McpToolAccess from "../../McpToolAccess.ts";
+import { PluginToolsToolkit } from "./tools.ts";
+import { assertFullAccess } from "../../threadAccess.ts";
+
+const make = Effect.gen(function* () {
+ const tools = yield* PluginTools.PluginTools;
+ return {
+ // Scope and grants come from the session's credential, never from the agent.
+ // A caller without a thread can call no plugin tool, so it learns of no plugins either.
+ plugin_tools_list: McpToolAccess.reads((input) =>
+ McpInvocationContext.McpInvocationContext.pipe(
+ Effect.flatMap((scope) =>
+ scope.thread === undefined
+ ? Effect.succeed({ tools: [], notInThisSession: [] })
+ : tools.list(scope.pluginToolGrants ?? [], {
+ ...(input.plugin === undefined ? {} : { plugin: input.plugin }),
+ ...(input.cursor === undefined ? {} : { cursor: input.cursor }),
+ }),
+ ),
+ ),
+ ),
+ // A plugin tool runs on behalf of the calling thread while its run is live, so a client
+ // signed in from outside T3 Code (no thread, no grants) cannot call one.
+ plugin_tool_call: McpToolAccess.actsAsCaller((input, caller) =>
+ assertFullAccess(
+ caller,
+ "Calling a trusted plugin needs a full-access thread in default mode.",
+ ).pipe(
+ Effect.andThen(McpInvocationContext.McpInvocationContext),
+ Effect.flatMap((scope) =>
+ McpInvocationContext.requireThreadScope(scope, "plugin_tool_call"),
+ ),
+ Effect.flatMap((scope) =>
+ tools.call(scope.pluginToolGrants ?? [], {
+ tool: input.tool,
+ input: input.input ?? {},
+ context: { environmentId: scope.environmentId, threadId: scope.thread.threadId },
+ }),
+ ),
+ Effect.map((result) => ({ result })),
+ ),
+ ),
+ } satisfies McpToolAccess.Handlers;
+});
+
+export const layer = McpToolAccess.toLayer(PluginToolsToolkit, make);
diff --git a/apps/server/src/mcp/toolkits/pluginTools/tools.ts b/apps/server/src/mcp/toolkits/pluginTools/tools.ts
new file mode 100644
index 0000000000000..8cfbdc395c09c
--- /dev/null
+++ b/apps/server/src/mcp/toolkits/pluginTools/tools.ts
@@ -0,0 +1,64 @@
+import { OrchestratorMcpFailure, PluginToolError, PluginToolsListResult } from "@t3tools/contracts";
+import * as Schema from "effect/Schema";
+import * as Tool from "effect/ai/Tool";
+import * as Toolkit from "effect/ai/Toolkit";
+
+import * as ThreadManagementService from "../../../orchestration-v2/ThreadManagementService.ts";
+import * as McpInvocationContext from "../../McpInvocationContext.ts";
+
+const dependencies = [McpInvocationContext.McpInvocationContext];
+
+const PluginToolsListTool = Tool.make("plugin_tools_list", {
+ description:
+ "List the tools offered by the user's trusted local T3 Code plugins that this session may use. Each entry has the tool name to pass to plugin_tool_call, its inputSchema, and its sideEffect (read, write or destructive). Listing starts no plugin. Results come in pages ordered by plugin id: when nextCursor is present, pass it as cursor for more. Pass plugin to list one plugin's tools. Plugins enabled after this session started appear under notInThisSession and need a new session.",
+ parameters: Schema.Struct({
+ plugin: Schema.optionalKey(
+ Schema.String.check(Schema.isMaxLength(128)).annotate({
+ description: "A plugin id, such as acme.search, to list only that plugin's tools.",
+ }),
+ ),
+ cursor: Schema.optionalKey(
+ Schema.String.check(Schema.isMaxLength(128)).annotate({
+ description: "The nextCursor of the previous page.",
+ }),
+ ),
+ }),
+ success: PluginToolsListResult,
+ failure: PluginToolError,
+ dependencies,
+})
+ .annotate(Tool.Title, "List plugin tools")
+ .annotate(Tool.Readonly, true)
+ .annotate(Tool.Destructive, false)
+ .annotate(Tool.Idempotent, true)
+ .annotate(Tool.OpenWorld, false);
+
+/**
+ * One fixed tool calls every plugin tool, so its hints describe the most a
+ * plugin tool may do. Each tool's own sideEffect is in plugin_tools_list.
+ */
+const PluginToolCallTool = Tool.make("plugin_tool_call", {
+ description:
+ "Call a tool from plugin_tools_list. Pass its tool name and an input object that matches its inputSchema. Check the tool's sideEffect first: write and destructive tools change things, so follow the user's instructions about such changes.",
+ parameters: Schema.Struct({
+ tool: Schema.String.check(Schema.isMaxLength(200)).annotate({
+ description: "The tool value from plugin_tools_list, such as acme.search/lookup.",
+ }),
+ input: Schema.optionalKey(
+ Schema.Record(Schema.String, Schema.Unknown).annotate({
+ description: "Arguments matching the tool's inputSchema. Defaults to {}.",
+ }),
+ ),
+ }),
+ success: Schema.Struct({ result: Schema.Unknown }),
+ // The caller check refuses an outside client or a thread whose run has ended.
+ failure: Schema.Union([PluginToolError, OrchestratorMcpFailure]),
+ dependencies: [...dependencies, ThreadManagementService.ThreadManagementService],
+})
+ .annotate(Tool.Title, "Call plugin tool")
+ .annotate(Tool.Readonly, false)
+ .annotate(Tool.Destructive, true)
+ .annotate(Tool.Idempotent, false)
+ .annotate(Tool.OpenWorld, true);
+
+export const PluginToolsToolkit = Toolkit.make(PluginToolsListTool, PluginToolCallTool);
diff --git a/apps/server/src/observability/RpcInstrumentation.ts b/apps/server/src/observability/RpcInstrumentation.ts
index 1e3388e4136ad..223078de04242 100644
--- a/apps/server/src/observability/RpcInstrumentation.ts
+++ b/apps/server/src/observability/RpcInstrumentation.ts
@@ -92,6 +92,28 @@ const RPC_AGGREGATES = {
[WS_METHODS.scheduledTasksSetEnabled]: "scheduledTasks",
[WS_METHODS.scheduledTasksDelete]: "scheduledTasks",
[WS_METHODS.scheduledTasksRunNow]: "scheduledTasks",
+ [WS_METHODS.pluginsList]: "plugins",
+ [WS_METHODS.pluginsSubscribe]: "plugins",
+ [WS_METHODS.pluginsAdd]: "plugins",
+ [WS_METHODS.pluginsRefresh]: "plugins",
+ [WS_METHODS.pluginsConsent]: "plugins",
+ [WS_METHODS.pluginsEnable]: "plugins",
+ [WS_METHODS.pluginsDisable]: "plugins",
+ [WS_METHODS.pluginsRemove]: "plugins",
+ [WS_METHODS.pluginsResume]: "plugins",
+ [WS_METHODS.pluginsSettingsSubscribe]: "plugins",
+ [WS_METHODS.pluginsSettingsUpdate]: "plugins",
+ [WS_METHODS.pluginActionsSubscribe]: "plugins",
+ [WS_METHODS.pluginActionsInvoke]: "plugins",
+ [WS_METHODS.pluginsNpmList]: "plugins",
+ [WS_METHODS.pluginsNpmAdd]: "plugins",
+ [WS_METHODS.pluginsNpmStageUpdate]: "plugins",
+ [WS_METHODS.pluginsNpmApplyUpdate]: "plugins",
+ [WS_METHODS.pluginsNpmDiscardUpdate]: "plugins",
+ [WS_METHODS.pluginsNotificationsSubscribe]: "plugins",
+ [WS_METHODS.pluginViewsSubscribe]: "pluginViews",
+ [WS_METHODS.pluginViewsReadBundle]: "pluginViews",
+ [WS_METHODS.pluginViewsCall]: "pluginViews",
[WS_METHODS.scheduledTasksRotateWebhookToken]: "scheduledTasks",
[WS_METHODS.scheduledTasksListWebhookDeliveries]: "scheduledTasks",
[WS_METHODS.scheduledTasksGetWebhookDelivery]: "scheduledTasks",
@@ -172,6 +194,7 @@ const RPC_AGGREGATES = {
[WS_METHODS.subscribeWorktreeSetup]: "vcs",
[WS_METHODS.worktreeSetupCancel]: "vcs",
[WS_METHODS.subscribeResourceTelemetry]: "server",
+ [WS_METHODS.subscribeContributionStatus]: "server",
[WS_METHODS.vcsRefreshStatus]: "vcs",
[WS_METHODS.vcsPull]: "git",
[WS_METHODS.gitRunStackedAction]: "vcs",
diff --git a/apps/server/src/orchestration-v2/EffectOutbox.ts b/apps/server/src/orchestration-v2/EffectOutbox.ts
index 92e1e01ad43f2..f353c7ccf8730 100644
--- a/apps/server/src/orchestration-v2/EffectOutbox.ts
+++ b/apps/server/src/orchestration-v2/EffectOutbox.ts
@@ -207,6 +207,10 @@ export interface EffectOutboxV2Shape {
readonly listByCommandId: (
commandId: CommandId,
) => Effect.Effect, EffectOutboxError>;
+ /**
+ * Cancelling a checkpoint capture abandons its run's finalization. Do that
+ * through `EventSink.commitCommand`, which records the failure.
+ */
readonly cancelUnsettled: (input: {
readonly threadId: ThreadId;
readonly effectTypes: ReadonlyArray;
diff --git a/apps/server/src/orchestration-v2/EffectWorker.test.ts b/apps/server/src/orchestration-v2/EffectWorker.test.ts
index 2329f2aa20cf0..7ed64568f0e06 100644
--- a/apps/server/src/orchestration-v2/EffectWorker.test.ts
+++ b/apps/server/src/orchestration-v2/EffectWorker.test.ts
@@ -135,7 +135,10 @@ function layerExecutorFor(input: {
),
Layer.succeed(
RunFinalizationService.RunFinalizationService,
- RunFinalizationService.RunFinalizationService.of({ finalize: () => Effect.void }),
+ RunFinalizationService.RunFinalizationService.of({
+ finalize: () => Effect.void,
+ abandon: () => Effect.succeed(true),
+ }),
),
Layer.succeed(
CheckpointRollbackService.CheckpointRollbackServiceV2,
diff --git a/apps/server/src/orchestration-v2/EffectWorker.ts b/apps/server/src/orchestration-v2/EffectWorker.ts
index 534043aeb4eb8..2cb554d15e04c 100644
--- a/apps/server/src/orchestration-v2/EffectWorker.ts
+++ b/apps/server/src/orchestration-v2/EffectWorker.ts
@@ -61,6 +61,18 @@ export interface OrchestrationEffectExecutorV2Shape {
effect: EffectOutbox.OrchestrationEffectV2,
options?: { readonly willRetry: boolean },
) => Effect.Effect;
+ /**
+ * Settles an effect whose last attempt failed, in place of `outbox.fail`, so
+ * its failure record commits with the terminal status. Returns undefined
+ * for effects that keep no record, and false when the worker no longer
+ * owns the lease.
+ */
+ readonly fail?: (input: {
+ readonly effect: EffectOutbox.OrchestrationEffectV2;
+ readonly workerId: string;
+ readonly error: string;
+ readonly cause: Cause.Cause;
+ }) => Effect.Effect | undefined;
}
export class OrchestrationEffectExecutorV2 extends Context.Service<
@@ -573,6 +585,36 @@ export const layerExecutor: Layer.Layer<
);
}
}),
+ fail: ({ effect, workerId, error, cause }) => {
+ if (effect.request.type !== "checkpoint.capture") return undefined;
+ const failure = Cause.findErrorOption(cause).pipe(
+ Option.map((executionError) => executionError.cause),
+ Option.filter(RunFinalizationService.isRunFinalizationError),
+ );
+ return runFinalization
+ .abandon({
+ threadId: effect.threadId,
+ runId: effect.request.runId,
+ scopeId: effect.request.scopeId,
+ operation: Option.match(failure, {
+ onNone: () => "capture-checkpoint" as const,
+ onSome: (finalizationError) => finalizationError.operation,
+ }),
+ effectId: effect.id,
+ workerId,
+ error,
+ })
+ .pipe(
+ Effect.mapError(
+ (abandonCause) =>
+ new OrchestrationEffectExecutionError({
+ effectId: effect.id,
+ effectType: effect.request.type,
+ cause: abandonCause,
+ }),
+ ),
+ );
+ },
});
}),
);
@@ -655,9 +697,12 @@ export const layerWithOptions = (
}),
),
);
+ const retryDelayMs = (effect: EffectOutbox.OrchestrationEffectV2) =>
+ Math.min(30_000, 100 * 2 ** Math.max(0, effect.attemptCount - 1));
const requeueClaim = (
effect: EffectOutbox.OrchestrationEffectV2,
cause: Cause.Cause,
+ delayMs = 0,
) =>
Cause.hasInterruptsOnly(cause)
? Effect.void
@@ -666,7 +711,7 @@ export const layerWithOptions = (
effectId: effect.id,
workerId,
error: `Worker failed before settling the claimed effect: ${Cause.pretty(cause)}`,
- delayMs: 0,
+ delayMs,
})
.pipe(
Effect.flatMap((requeued) =>
@@ -814,22 +859,32 @@ export const layerWithOptions = (
nonRetryable,
error,
});
+ const retry = outbox
+ .retry({
+ effectId: effect.id,
+ workerId,
+ error,
+ delayMs: retryDelayMs(effect),
+ })
+ .pipe(Effect.onError((cause) => requeueClaim(effect, cause)));
+ const recordedFailure = executor.fail?.({ effect, workerId, error, cause: exit.cause });
+ // Terminal interrupt races succeed; recorded failures remain recoverable until their write commits.
+ // Backoff avoids repeating a failed recording immediately; interruption replays the effect.
const updated = nonRetryable
? yield* outbox
.succeed({ effectId: effect.id, workerId })
.pipe(Effect.onError((cause) => terminalizeClaim(effect, cause)))
- : effect.attemptCount >= maxAttempts
- ? yield* outbox
- .fail({ effectId: effect.id, workerId, error })
- .pipe(Effect.onError((cause) => terminalizeClaim(effect, cause)))
- : yield* outbox
- .retry({
- effectId: effect.id,
- workerId,
- error,
- delayMs: Math.min(30_000, 100 * 2 ** Math.max(0, effect.attemptCount - 1)),
- })
- .pipe(Effect.onError((cause) => requeueClaim(effect, cause)));
+ : effect.attemptCount < maxAttempts
+ ? yield* retry
+ : recordedFailure === undefined
+ ? yield* outbox
+ .fail({ effectId: effect.id, workerId, error })
+ .pipe(Effect.onError((cause) => terminalizeClaim(effect, cause)))
+ : Cause.hasInterruptsOnly(exit.cause)
+ ? yield* retry
+ : yield* recordedFailure.pipe(
+ Effect.onError((cause) => requeueClaim(effect, cause, retryDelayMs(effect))),
+ );
if (!updated) {
if (yield* wasCancelled(effect.id)) return true;
return yield* new OrchestrationEffectWorkerError({
diff --git a/apps/server/src/orchestration-v2/EventSink.ts b/apps/server/src/orchestration-v2/EventSink.ts
index b210d3c9840ae..603c79f8620bd 100644
--- a/apps/server/src/orchestration-v2/EventSink.ts
+++ b/apps/server/src/orchestration-v2/EventSink.ts
@@ -33,6 +33,7 @@ import * as EffectOutbox from "./EffectOutbox.ts";
import * as EventStore from "./EventStore.ts";
import * as ProjectionStore from "./ProjectionStore.ts";
import * as ProjectStore from "./ProjectStore.ts";
+import * as RunFinalized from "./RunFinalized.ts";
import * as TurnItemPositionStore from "./TurnItemPositionStore.ts";
export class EventSinkWriteError extends Schema.TaggedError()(
@@ -157,6 +158,25 @@ export interface EventSinkV2Shape {
},
EventSinkV2Error
>;
+ /**
+ * Fails a claimed effect and records `events` in one transaction. Commits
+ * nothing when `workerId` no longer holds the effect's lease.
+ */
+ readonly failEffect: (input: {
+ readonly commandId: CommandId;
+ readonly effectId: string;
+ readonly workerId: string;
+ readonly error: string;
+ readonly events: ReadonlyArray;
+ }) => Effect.Effect<
+ {
+ readonly committed: boolean;
+ readonly storedEvents: ReadonlyArray;
+ },
+ EventSinkV2Error
+ >;
+ /** Whether the run recorded `run.finalized` or `run.finalization-failed`. */
+ readonly hasRunFinalization: (runId: RunId) => Effect.Effect;
readonly commitRejectedCommand: (input: {
readonly commandId: CommandId;
readonly threadId: ThreadId;
@@ -329,7 +349,105 @@ const layerBase: Layer.Layer<
});
});
- const normalizeEvents = (events: ReadonlyArray) => {
+ const isRunFinalizationRecorded = (runId: RunId) =>
+ sql<{ readonly found: number }>`
+ SELECT 1 AS found
+ FROM orchestration_events
+ WHERE event_id = ${RunFinalized.runFinalizedEventId(runId)}
+ LIMIT 1
+ `.pipe(Effect.map((rows) => rows.length > 0));
+
+ // Capture runs finalize through RunFinalizationService; uncaptured or abandoned runs finalize with their terminal write.
+ // Stored state prevents duplicate milestones; the enclosing EventSink operation owns tracing.
+ const withRunFinalizedEvents = Effect.fnUntraced(function* (
+ events: ReadonlyArray,
+ effects: ReadonlyArray,
+ ) {
+ const isFinalizationRecord = (event: OrchestrationV2DomainEvent) =>
+ event.type === "run.finalized" || event.type === "run.finalization-failed";
+ if (!events.some((event) => event.type === "run.updated" || isFinalizationRecord(event))) {
+ return events;
+ }
+ const captureStatus = (runId: RunId) =>
+ effects.some(
+ (effect) =>
+ effect.request.type === "checkpoint.capture" && effect.request.runId === runId,
+ )
+ ? Effect.succeedSome("pending")
+ : effectOutbox
+ .get(RunFinalized.checkpointCaptureEffectId(runId))
+ .pipe(Effect.map(Option.map((effect) => effect.status)));
+ const statuses = new Map();
+ const previousStatus = (runId: RunId) =>
+ statuses.has(runId)
+ ? Effect.succeed(statuses.get(runId))
+ : sql<{ readonly status: string }>`
+ SELECT status
+ FROM orchestration_v2_projection_runs
+ WHERE run_id = ${runId}
+ LIMIT 1
+ `.pipe(Effect.map((rows) => rows[0]?.status));
+ const finalized = new Set();
+ const result: Array = [];
+ // Appended last so the milestone follows every write in its commit.
+ const milestones: Array = [];
+ for (const event of events) {
+ if (event.type === "run.finalized" || event.type === "run.finalization-failed") {
+ const runId = event.payload.runId;
+ if (!finalized.has(runId) && !(yield* isRunFinalizationRecorded(runId))) {
+ finalized.add(runId);
+ result.push(event);
+ }
+ continue;
+ }
+ result.push(event);
+ if (event.type === "run.created") {
+ statuses.set(event.payload.id, event.payload.status);
+ continue;
+ }
+ if (event.type !== "run.updated") continue;
+ const run = event.payload;
+ const previous = yield* previousStatus(run.id);
+ statuses.set(run.id, run.status);
+ const outcome = RunFinalized.runFinalizedOutcome(run.status);
+ // Only the transition into a final status finalizes, so later
+ // updates to old runs never produce a late milestone.
+ if (
+ outcome === null ||
+ finalized.has(run.id) ||
+ (previous !== undefined && RunFinalized.isSettledRunStatus(previous)) ||
+ (yield* isRunFinalizationRecorded(run.id))
+ ) {
+ continue;
+ }
+ const capture = yield* captureStatus(run.id);
+ const abandoned =
+ Option.isSome(capture) && (capture.value === "failed" || capture.value === "cancelled");
+ if (Option.isSome(capture) && !abandoned) continue;
+ finalized.add(run.id);
+ milestones.push(
+ abandoned
+ ? RunFinalized.makeRunFinalizationFailedEvent({
+ run,
+ operation: RunFinalized.abandonedOperation(run),
+ occurredAt: event.occurredAt,
+ })
+ : RunFinalized.makeRunFinalizedEvent({ run, outcome, occurredAt: event.occurredAt }),
+ );
+ }
+ return [...result, ...milestones];
+ });
+
+ // The enclosing EventSink operation already traces this persistence work.
+ const normalizeEvents = Effect.fnUntraced(function* (
+ input: ReadonlyArray,
+ effects: ReadonlyArray = [],
+ ) {
+ const events = yield* withRunFinalizedEvents(input, effects);
+ return yield* normalizeTurnItemPositions(events);
+ });
+
+ const normalizeTurnItemPositions = (events: ReadonlyArray) => {
const runOrdinals = new Map(
events.flatMap((event) =>
event.type === "run.created" || event.type === "run.updated"
@@ -441,6 +559,7 @@ const layerBase: Layer.Layer<
input.guardPendingUserInputCancellations === true
? yield* guardUserInputCancellations(events)
: events,
+ input.effects,
);
const committed = yield* eventStore.append({
...(input.commandId === undefined ? {} : { commandId: input.commandId }),
@@ -496,10 +615,13 @@ const layerBase: Layer.Layer<
};
}
+ // The checkpoint capture enqueued below decides how a run that
+ // settles here finalizes, so it must be visible to normalization.
const normalized = yield* normalizeEvents(
input.guardPendingUserInputCancellations === true
? yield* guardUserInputCancellations(input.events)
: input.events,
+ input.effects,
);
const storedEvents = yield* eventStore.append({
...(input.commandId === undefined ? {} : { commandId: input.commandId }),
@@ -632,6 +754,79 @@ const layerBase: Layer.Layer<
return { receipt: existing.value, storedEvents };
});
+ // Cancelling a checkpoint capture abandons its run's finalization, so the
+ // cancelling commit records `run.finalization-failed` for that run.
+ // The enclosing EventSink operation already traces this persistence work.
+ const recordAbandonedCaptures = Effect.fnUntraced(function* (
+ commandId: CommandId,
+ cancelledEffectIds: ReadonlyArray,
+ occurredAt: DateTime.Utc,
+ ) {
+ const events: Array = [];
+ for (const effectId of cancelledEffectIds) {
+ const effect = yield* effectOutbox.get(effectId);
+ if (Option.isNone(effect) || effect.value.request.type !== "checkpoint.capture") continue;
+ const { run } = yield* projectionStore.getCheckpointCaptureContext(
+ effect.value.threadId,
+ effect.value.request,
+ );
+ if (run === undefined || run.status === "rolled_back") continue;
+ events.push(
+ RunFinalized.makeRunFinalizationFailedEvent({
+ run,
+ operation: RunFinalized.abandonedOperation(run),
+ occurredAt,
+ }),
+ );
+ }
+ if (events.length === 0) return [];
+ const storedEvents = yield* eventStore.append({
+ commandId,
+ events: yield* normalizeEvents(events),
+ });
+ yield* applyStoredEvents(storedEvents);
+ return storedEvents;
+ });
+
+ const failEffectEffect = Effect.fn("orchestrationV2.EventSink.failEffect")(function* (
+ input: Parameters[0],
+ ) {
+ yield* Effect.annotateCurrentSpan({
+ "orchestration_v2.command_id": input.commandId,
+ "orchestration_v2.effect_id": input.effectId,
+ "orchestration_v2.event_count": input.events.length,
+ });
+
+ return yield* commitThenPublish(
+ Effect.gen(function* () {
+ const failed = yield* effectOutbox.fail({
+ effectId: input.effectId,
+ workerId: input.workerId,
+ error: input.error,
+ });
+ if (!failed) {
+ return {
+ committed: false as const,
+ storedEvents: [] as ReadonlyArray,
+ };
+ }
+ const normalized = yield* normalizeEvents(input.events);
+ const storedEvents =
+ normalized.length === 0
+ ? []
+ : yield* eventStore.append({ commandId: input.commandId, events: normalized });
+ const outcomes = yield* applyStoredEvents(storedEvents);
+ return { committed: true as const, storedEvents, outcomes };
+ }),
+ (result) =>
+ result.committed
+ ? effectOutbox
+ .notifyAvailable()
+ .pipe(Effect.andThen(publishStoredEvents(result.storedEvents, result.outcomes)))
+ : Effect.void,
+ );
+ });
+
const commitCommandEffect = Effect.fn("orchestrationV2.EventSink.commitCommand")(function* (
input: Parameters[0],
) {
@@ -656,14 +851,15 @@ const layerBase: Layer.Layer<
runId === undefined
? input.events
: yield* updateDelegatedCompletionOnly(input.events, (id) => id === runId),
+ input.effects,
);
- const storedEvents = yield* eventStore.append({
+ const appended = yield* eventStore.append({
commandId: input.commandId,
events: normalized,
});
// A Stop that changes nothing can still queue the stop of its delegated tasks.
const sequence =
- storedEvents.at(-1)?.sequence ??
+ appended.at(-1)?.sequence ??
(input.effects.length === 0
? undefined
: yield* eventStore.latestSequence({ threadId: input.threadId }));
@@ -672,25 +868,37 @@ const layerBase: Layer.Layer<
new Error(`Command ${input.commandId} produced no orchestration events.`),
);
}
- const outcomes = yield* applyStoredEvents(storedEvents);
+ const outcomes = yield* applyStoredEvents(appended);
yield* effectOutbox.enqueue(input.effects);
+ const cancelledEffectIds =
+ input.cancelUnsettledEffects === undefined
+ ? []
+ : yield* effectOutbox.cancelUnsettled({
+ threadId: input.threadId,
+ ...input.cancelUnsettledEffects,
+ });
+ const storedEvents = input.cancelUnsettledEffects?.effectTypes.includes(
+ "checkpoint.capture",
+ )
+ ? [
+ ...appended,
+ ...(yield* recordAbandonedCaptures(
+ input.commandId,
+ cancelledEffectIds,
+ input.acceptedAt,
+ )),
+ ]
+ : appended;
const receipt: CommandReceiptStore.CommandReceiptV2 = {
commandId: input.commandId,
threadId: input.threadId,
commandType: input.commandType,
acceptedAt: input.acceptedAt,
- resultSequence: sequence,
+ resultSequence: storedEvents.at(-1)?.sequence ?? sequence,
status: "accepted",
error: null,
};
yield* commandReceipts.upsert(receipt);
- const cancelledEffectIds =
- input.cancelUnsettledEffects === undefined
- ? []
- : yield* effectOutbox.cancelUnsettled({
- threadId: input.threadId,
- ...input.cancelUnsettledEffects,
- });
return { receipt, storedEvents, outcomes, committed: true as const, cancelledEffectIds };
}),
(result) =>
@@ -939,6 +1147,21 @@ const layerBase: Layer.Layer<
}),
),
),
+ failEffect: (input) =>
+ failEffectEffect(input).pipe(
+ Effect.mapError(
+ (cause) =>
+ new EventSinkWriteError({
+ commandId: input.commandId,
+ eventCount: input.events.length,
+ cause,
+ }),
+ ),
+ ),
+ hasRunFinalization: (runId) =>
+ isRunFinalizationRecorded(runId).pipe(
+ Effect.mapError((cause) => new EventSinkStreamError({ cause })),
+ ),
commitRejectedCommand: (input) =>
commitRejectedCommandEffect(input).pipe(
Effect.mapError(
diff --git a/apps/server/src/orchestration-v2/ProjectionStore.ts b/apps/server/src/orchestration-v2/ProjectionStore.ts
index 95c0f7a4bae53..55ceb83c029f3 100644
--- a/apps/server/src/orchestration-v2/ProjectionStore.ts
+++ b/apps/server/src/orchestration-v2/ProjectionStore.ts
@@ -832,6 +832,10 @@ export function applyToProjection(
),
),
});
+ // Milestones over state the run rows already hold.
+ case "run.finalized":
+ case "run.finalization-failed":
+ return projection;
case "run.background-work-cancelled":
return {
...base,
@@ -2001,6 +2005,9 @@ export const layer: Layer.Layer =
`;
break;
}
+ case "run.finalized":
+ case "run.finalization-failed":
+ break;
case "run.background-work-cancelled": {
// Only this field changes, so a concurrent lifecycle write is never regressed.
const workJson = yield* encodeRestartCancelledBackgroundWork(
@@ -2717,6 +2724,8 @@ export const layer: Layer.Layer =
event.type !== "thread.interaction-mode-updated" &&
event.type !== "thread.model-selection-updated" &&
event.type !== "thread.provider-switched" &&
+ event.type !== "run.finalized" &&
+ event.type !== "run.finalization-failed" &&
event.type !== "thread.guest-share-updated"
) {
const updatedAt = yield* encodeThreadUpdatedAt(event.occurredAt);
diff --git a/apps/server/src/orchestration-v2/ProviderSessionManager.test.ts b/apps/server/src/orchestration-v2/ProviderSessionManager.test.ts
index 5bbb3926e2b66..fdd1beed5b2b2 100644
--- a/apps/server/src/orchestration-v2/ProviderSessionManager.test.ts
+++ b/apps/server/src/orchestration-v2/ProviderSessionManager.test.ts
@@ -10,6 +10,7 @@ import {
type OrchestrationV2ProviderCapabilities,
type OrchestrationV2ProviderSession,
type OrchestrationV2ProviderThread,
+ PluginInstallationId,
type Project,
ProjectId,
ProviderDriverKind,
@@ -34,6 +35,7 @@ import { HttpServer } from "effect/http";
import { ProviderWorkspaceMissingError } from "../provider/Errors.ts";
import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
+import * as PluginTools from "../plugins/PluginTools.ts";
import * as ProjectService from "../project/ProjectService.ts";
import * as McpProviderSession from "@t3tools/provider-core/server/mcpSession";
import * as McpProviderSessions from "@t3tools/provider-core/server/McpProviderSessions";
@@ -476,11 +478,9 @@ function layerTest(input: {
readonly failReleaseEventWrites?: boolean;
readonly flakyReleaseWrites?: FlakyReleaseWrites;
readonly pauseAttachWrite?: Parameters[0];
+ /** Once armed, the next call of that registry step hangs until interrupted or crashes. */
+ readonly pauseMcpRegistry?: PauseMcpRegistry;
readonly beforeUnchangedWrite?: Ref.Ref>;
- readonly pauseResolve?: {
- readonly armed: Ref.Ref;
- readonly paused: Deferred.Deferred;
- };
readonly hasPendingBackgroundWork?: Effect.Effect;
readonly hasPendingBackgroundWorkForThread?: Effect.Effect;
readonly backgroundTasksEndWithProcess?: boolean;
@@ -492,6 +492,7 @@ function layerTest(input: {
readonly scopeCloseReached?: Deferred.Deferred;
readonly serverSettingsLayer?: ReturnType;
readonly projectServiceLayer?: Layer.Layer;
+ readonly pluginToolsLayer?: Layer.Layer;
}) {
const layerConfiguredEventSink =
input.flakyReleaseWrites !== undefined
@@ -531,9 +532,9 @@ function layerTest(input: {
}).pipe(Effect.map(ProviderAdapterRegistry.layerSingle)),
);
const layerConfiguredMcpRegistry =
- input.pauseResolve === undefined
+ input.pauseMcpRegistry === undefined
? layerTestMcpRegistry
- : layerPausingMcpRegistry(input.pauseResolve);
+ : layerPausingMcpRegistry(input.pauseMcpRegistry);
const layerProviderEventIngestorTest = ProviderEventIngestor.layer.pipe(
Layer.provide(
Layer.mergeAll(
@@ -574,6 +575,7 @@ function layerTest(input: {
layerTestStores,
...(input.serverSettingsLayer === undefined ? [] : [input.serverSettingsLayer]),
...(input.projectServiceLayer === undefined ? [] : [input.projectServiceLayer]),
+ ...(input.pluginToolsLayer === undefined ? [] : [input.pluginToolsLayer]),
),
),
),
@@ -599,23 +601,41 @@ const layerTestMcpRegistry = Layer.effect(
Layer.provide(NodeServices.layer),
);
-const layerPausingMcpRegistry = (pause: {
+interface PauseMcpRegistry {
+ readonly step: "resolve" | "setPluginToolGrants";
+ readonly outcome: "hang" | "crash";
readonly armed: Ref.Ref;
readonly paused: Deferred.Deferred;
-}) =>
+}
+
+const layerPausingMcpRegistry = (pause: PauseMcpRegistry) =>
Layer.effect(
McpSessionRegistry.McpSessionRegistry,
Effect.gen(function* () {
const delegate = yield* McpSessionRegistry.McpSessionRegistry;
+ const holdIfArmed = (step: PauseMcpRegistry["step"], run: Effect.Effect) =>
+ step !== pause.step
+ ? run
+ : Ref.getAndSet(pause.armed, false).pipe(
+ Effect.flatMap((armed) =>
+ armed
+ ? Deferred.succeed(pause.paused, undefined).pipe(
+ Effect.andThen(
+ pause.outcome === "hang"
+ ? Effect.never
+ : Effect.die(new Error(`${step} crashed`)),
+ ),
+ )
+ : run,
+ ),
+ );
return McpSessionRegistry.McpSessionRegistry.of({
...delegate,
- resolve: (rawToken) =>
- Ref.getAndSet(pause.armed, false).pipe(
- Effect.flatMap((armed) =>
- armed
- ? Deferred.succeed(pause.paused, undefined).pipe(Effect.andThen(Effect.never))
- : delegate.resolve(rawToken),
- ),
+ resolve: (rawToken) => holdIfArmed("resolve", delegate.resolve(rawToken)),
+ setPluginToolGrants: (providerSessionId, grants) =>
+ holdIfArmed(
+ "setPluginToolGrants",
+ delegate.setPluginToolGrants(providerSessionId, grants),
),
});
}),
@@ -1845,6 +1865,49 @@ it.effect(
}),
);
+it.effect("ProviderSessionManagerV2 snapshots the enabled tool plugins into the credential", () =>
+ Effect.gen(function* () {
+ const state = yield* Ref.make(emptyState);
+ const mcpConfigs = yield* Ref.make<
+ ReadonlyArray
+ >([]);
+ const enabled = yield* Ref.make([
+ { installationId: PluginInstallationId.make("installation-1"), generation: 1 },
+ ]);
+ const pluginToolsLayer = Layer.mock(PluginTools.PluginTools)({ grants: Ref.get(enabled) });
+ yield* Effect.gen(function* () {
+ const eventSink = yield* EventSink.EventSinkV2;
+ const idAllocator = yield* IdAllocator.IdAllocatorV2;
+ const manager = yield* ProviderSessionManager.ProviderSessionManagerV2;
+ const registry = yield* McpSessionRegistry.McpSessionRegistry;
+ const now = yield* DateTime.now;
+ const threadId = ThreadId.make("thread-provider-session-manager-plugin-tools");
+ yield* eventSink.write({
+ events: [yield* makeThreadCreatedEvent({ idAllocator, threadId, now })],
+ });
+ const openAndResolve = Effect.gen(function* () {
+ const providerSessionId = yield* idAllocator.allocate.providerSession({
+ providerInstanceId: modelSelection.instanceId,
+ threadId,
+ });
+ yield* manager.open({ threadId, providerSessionId, modelSelection, runtimePolicy });
+ const config = (yield* Ref.get(mcpConfigs)).at(-1);
+ const token = config!.authorizationHeader.replace(/^Bearer\s+/, "");
+ const resolved = yield* registry.resolve(token);
+ yield* manager.close(providerSessionId);
+ return resolved?.pluginToolGrants;
+ });
+
+ assert.deepEqual(yield* openAndResolve, yield* Ref.get(enabled));
+ // A plugin enabled later reaches the next session, not the one already prepared.
+ yield* Ref.set(enabled, []);
+ assert.deepEqual(yield* openAndResolve, []);
+ }).pipe(
+ Effect.provide(layerTest({ state, idleTimeoutMs: 1_000, mcpConfigs, pluginToolsLayer })),
+ );
+ }),
+);
+
it.effect("ProviderSessionManagerV2 honors a project browser-access opt-out", () =>
Effect.gen(function* () {
const captured = yield* runBrowserAccessScenario({
@@ -2075,10 +2138,14 @@ it.effect(
}),
);
-// regression: #15571 an interrupted session start did not clean up
-it.effect(
- "ProviderSessionManagerV2 revokes a reused credential after a resume stopped while checking it",
- () =>
+it.effect.each([
+ ["stopped while checking it", "resolve", "hang"],
+ ["stopped while updating its plugin tool grants", "setPluginToolGrants", "hang"],
+ ["crashed while checking it", "resolve", "crash"],
+ ["crashed while updating its plugin tool grants", "setPluginToolGrants", "crash"],
+] as const)(
+ "ProviderSessionManagerV2 revokes a reused credential after a resume %s",
+ ([, step, outcome]) =>
Effect.gen(function* () {
const state = yield* Ref.make(emptyState);
const armed = yield* Ref.make(false);
@@ -2090,8 +2157,8 @@ it.effect(
const registry = yield* McpSessionRegistry.McpSessionRegistry;
const mcpSessions = yield* McpProviderSessions.McpProviderSessions;
const now = yield* DateTime.now;
- const owner = ThreadId.make("thread-provider-session-manager-resolve-stop-owner");
- const threadId = ThreadId.make("thread-provider-session-manager-resolve-stop");
+ const owner = ThreadId.make(`thread-provider-session-manager-${step}-${outcome}-owner`);
+ const threadId = ThreadId.make(`thread-provider-session-manager-${step}-${outcome}`);
const providerSessionId = idAllocator.derive.providerSession({
providerInstanceId: modelSelection.instanceId,
});
@@ -2114,7 +2181,7 @@ it.effect(
threadId,
providerSessionId,
now,
- nativeThreadId: "native-resolve-stop",
+ nativeThreadId: `native-${step}-${outcome}`,
}),
});
yield* resume;
@@ -2123,16 +2190,22 @@ it.effect(
assert.isDefined(config);
const token = config!.authorizationHeader.replace(/^Bearer\s+/, "");
+ // A re-attach is stopped, or crashes, while it reuses that credential.
yield* Ref.set(armed, true);
const stopped = yield* resume.pipe(Effect.forkChild({ startImmediately: true }));
yield* Deferred.await(paused);
- yield* Fiber.interrupt(stopped);
+ // A crashed attach is logged and rolled back rather than failing the resume.
+ yield* outcome === "hang" ? Fiber.interrupt(stopped) : Fiber.await(stopped);
yield* manager.release({ providerSessionId, reason: "manual_shutdown" });
assert.isUndefined(yield* registry.resolve(token));
}).pipe(
Effect.provide(
- layerTest({ state, idleTimeoutMs: 60_000, pauseResolve: { armed, paused } }),
+ layerTest({
+ state,
+ idleTimeoutMs: 60_000,
+ pauseMcpRegistry: { step, outcome, armed, paused },
+ }),
),
);
}),
diff --git a/apps/server/src/orchestration-v2/ProviderSessionManager.ts b/apps/server/src/orchestration-v2/ProviderSessionManager.ts
index 03a7278774a64..d029d7df2079a 100644
--- a/apps/server/src/orchestration-v2/ProviderSessionManager.ts
+++ b/apps/server/src/orchestration-v2/ProviderSessionManager.ts
@@ -45,6 +45,7 @@ import * as ProjectService from "../project/ProjectService.ts";
import * as McpProviderSessions from "@t3tools/provider-core/server/McpProviderSessions";
import * as ServerSettings from "../serverSettings.ts";
import * as McpSessionRegistry from "../mcp/McpSessionRegistry.ts";
+import * as PluginTools from "../plugins/PluginTools.ts";
import * as EventSink from "./EventSink.ts";
import * as CommandOutputHub from "./CommandOutputHub.ts";
import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator";
@@ -340,6 +341,8 @@ export const layerWithOptions = (
/** Unreadable settings must preserve explicit browser-access opt-outs. */
const serverSettings = yield* Effect.serviceOption(ServerSettings.ServerSettingsService);
const projectService = yield* Effect.serviceOption(ProjectService.ProjectService);
+ // Optional for the same reason; without it a session gets no plugin tools.
+ const pluginTools = yield* Effect.serviceOption(PluginTools.PluginTools);
const eventSink = yield* EventSink.EventSinkV2;
const commandOutput = yield* CommandOutputHub.CommandOutputHub;
const idAllocator = yield* IdAllocator.IdAllocatorV2;
@@ -457,6 +460,10 @@ export const layerWithOptions = (
>(["orchestration", "worktree", "pull-requests"]);
if (browserToolsAvailable) capabilities.add("preview");
if (deviceToolsAvailable) capabilities.add("device");
+ // Taken at every preparation; each call still checks the plugin is enabled now.
+ const pluginToolGrants = Option.isSome(pluginTools)
+ ? yield* pluginTools.value.grants
+ : [];
const subagent = yield* projectionStore.getThread(threadId).pipe(
Effect.map((thread) => thread.lineage.relationshipToParent === "subagent"),
Effect.orElseSucceed(() => false),
@@ -466,25 +473,37 @@ export const layerWithOptions = (
// Reserve before async validation so release cannot revoke between validation and reservation.
reserveMcpCredential(threadId, existing.providerSessionId);
const rawToken = existing.authorizationHeader.replace(/^Bearer\s+/, "");
- // Interrupted resolution must release the reservation before the caller learns of it.
- const resolved = yield* mcpSessionRegistry
- .resolve(rawToken)
- .pipe(
- Effect.onInterrupt(() =>
- Effect.sync(() =>
- dropMcpCredentialReservation(threadId, existing.providerSessionId),
- ),
- ),
+ // The caller only learns of the reservation once this returns,
+ // so a stop or crash while resolving or updating grants must drop it here.
+ const reused = yield* Effect.gen(function* () {
+ const resolved = yield* mcpSessionRegistry.resolve(rawToken);
+ if (
+ resolved === undefined ||
+ resolved.thread.threadId !== threadId ||
+ resolved.thread.providerInstanceId !== providerInstanceId ||
+ // A flipped browser-access setting must not survive through
+ // credential reuse: rotate so the new scope reflects it.
+ resolved.capabilities.has("preview") !== browserToolsAvailable ||
+ resolved.capabilities.has("device") !== deviceToolsAvailable ||
+ (resolved.thread.subagent === true) !== subagent
+ ) {
+ return false;
+ }
+ // The provider keeps this credential, and the plugin tools are fixed meta-tools,
+ // so new grants apply to it without rotating the token.
+ yield* mcpSessionRegistry.setPluginToolGrants(
+ existing.providerSessionId,
+ pluginToolGrants,
);
- if (
- resolved !== undefined &&
- resolved.thread.threadId === threadId &&
- resolved.thread.providerInstanceId === providerInstanceId &&
- resolved.capabilities.has("preview") === browserToolsAvailable &&
- resolved.capabilities.has("device") === deviceToolsAvailable &&
- // A credential issued while the lineage read failed is replaced once it works.
- (resolved.thread.subagent === true) === subagent
- ) {
+ return true;
+ }).pipe(
+ Effect.onError(() =>
+ Effect.sync(() =>
+ dropMcpCredentialReservation(threadId, existing.providerSessionId),
+ ),
+ ),
+ );
+ if (reused) {
return { mcpCredentialId: existing.providerSessionId, issued: false };
}
dropMcpCredentialReservation(threadId, existing.providerSessionId);
@@ -495,6 +514,7 @@ export const layerWithOptions = (
providerInstanceId,
browserToolsAvailable,
capabilities,
+ pluginToolGrants,
subagent,
});
yield* mcpSessions.set(credential.config);
diff --git a/apps/server/src/orchestration-v2/RunExecutionService.ts b/apps/server/src/orchestration-v2/RunExecutionService.ts
index b9b2b09bd227e..f690bfea04678 100644
--- a/apps/server/src/orchestration-v2/RunExecutionService.ts
+++ b/apps/server/src/orchestration-v2/RunExecutionService.ts
@@ -53,6 +53,7 @@ import {
makeProviderFailureTurnItem,
} from "@t3tools/provider-core/server/failure";
import * as RunFinalizationService from "./RunFinalizationService.ts";
+import { checkpointCaptureEffectId } from "./RunFinalized.ts";
import * as TurnItemPositionStore from "./TurnItemPositionStore.ts";
import { userFacingDatabaseErrorMessage } from "./UserFacingErrors.ts";
@@ -742,7 +743,7 @@ export const layer: Layer.Layer<
input.terminal.status === "cancelled"
? [
{
- id: `effect:checkpoint.capture:${input.run.id}`,
+ id: checkpointCaptureEffectId(input.run.id),
commandId: checkpointCaptureCommandId,
threadId: input.run.threadId,
request: {
diff --git a/apps/server/src/orchestration-v2/RunFinalizationQueue.test.ts b/apps/server/src/orchestration-v2/RunFinalizationQueue.test.ts
index c2b9e0aabcd5b..fa1589c9c52a3 100644
--- a/apps/server/src/orchestration-v2/RunFinalizationQueue.test.ts
+++ b/apps/server/src/orchestration-v2/RunFinalizationQueue.test.ts
@@ -11,6 +11,7 @@ import * as VcsStatusBroadcaster from "../vcs/VcsStatusBroadcaster.ts";
import * as WorkspaceEntries from "../workspace/WorkspaceEntries.ts";
import * as CheckpointCapture from "./CheckpointCaptureService.ts";
import * as CheckpointRollback from "./CheckpointRollbackService.ts";
+import * as EventSink from "./EventSink.ts";
import * as EffectOutbox from "./EffectOutbox.ts";
import * as EffectWorker from "./EffectWorker.ts";
import * as ProjectionStore from "./ProjectionStore.ts";
@@ -37,6 +38,15 @@ it.effect.each([
cause: "checkpoint storage unavailable",
});
const projections = Layer.mock(ProjectionStore.ProjectionStoreV2)({
+ getCheckpointCaptureContext: () =>
+ Effect.succeed({
+ run: undefined,
+ rootNode: undefined,
+ scope: undefined,
+ providerThread: undefined,
+ readyCheckpointOrdinals: [],
+ sideChat: false,
+ }),
getCheckpointContext: () =>
Effect.succeed({
runs: [],
@@ -70,6 +80,9 @@ it.effect.each([
Layer.mergeAll(
projections,
observer,
+ Layer.mock(EventSink.EventSinkV2)({
+ hasRunFinalization: () => Effect.succeed(false),
+ }),
Layer.mock(CheckpointCapture.CheckpointCaptureServiceV2)({
execute: () =>
Effect.gen(function* () {
diff --git a/apps/server/src/orchestration-v2/RunFinalizationService.test.ts b/apps/server/src/orchestration-v2/RunFinalizationService.test.ts
index 38a18192531a5..286b09ae26f81 100644
--- a/apps/server/src/orchestration-v2/RunFinalizationService.test.ts
+++ b/apps/server/src/orchestration-v2/RunFinalizationService.test.ts
@@ -1,8 +1,10 @@
-import { assert, it } from "@effect/vitest";
+import { assert, it, vi } from "@effect/vitest";
import {
CheckpointScopeId,
+ ProviderInstanceId,
RunId,
ThreadId,
+ type OrchestrationV2Run,
type OrchestrationV2ThreadShell,
} from "@t3tools/contracts";
import * as Effect from "effect/Effect";
@@ -12,9 +14,68 @@ import * as PullRequestService from "../pullRequest/PullRequestService.ts";
import * as VcsStatusBroadcaster from "../vcs/VcsStatusBroadcaster.ts";
import * as WorkspaceEntries from "../workspace/WorkspaceEntries.ts";
import * as CheckpointCapture from "./CheckpointCaptureService.ts";
+import * as EventSink from "./EventSink.ts";
import * as ProjectionStore from "./ProjectionStore.ts";
import * as RunFinalization from "./RunFinalizationService.ts";
+it.effect("refreshes workspace after checkpoint capture, then records finalization", () => {
+ const threadId = ThreadId.make("thread_finalize");
+ const runId = RunId.make("run_finalize");
+ const scopeId = CheckpointScopeId.make("scope_finalize");
+ const steps: Array = [];
+ const capture = vi.fn(() => Effect.sync(() => steps.push("capture")));
+ const refresh = vi.fn(() => Effect.sync(() => steps.push("refresh")));
+ const write = vi.fn(() => Effect.sync(() => (steps.push("record"), [])));
+ const checkpointContext = {
+ runs: [],
+ checkpointScopes: [{ id: scopeId, runId, kind: "root_run" as const, cwd: "/repo" }],
+ checkpoints: [],
+ };
+ const layer = RunFinalization.layer.pipe(
+ Layer.provide(
+ Layer.mergeAll(
+ Layer.mock(CheckpointCapture.CheckpointCaptureServiceV2)({ execute: capture }),
+ Layer.mock(ProjectionStore.ProjectionStoreV2)({
+ getThreadProjection: () =>
+ Effect.die("workspace refresh must not load transcript history"),
+ getCheckpointContext: () => Effect.succeed(checkpointContext),
+ getCheckpointCaptureContext: () =>
+ Effect.succeed({
+ run: {
+ id: runId,
+ threadId,
+ rootNodeId: null,
+ providerInstanceId: ProviderInstanceId.make("codex"),
+ status: "completed",
+ checkpointId: null,
+ } as OrchestrationV2Run,
+ rootNode: undefined,
+ scope: undefined,
+ providerThread: undefined,
+ readyCheckpointOrdinals: [],
+ sideChat: false,
+ }),
+ }),
+ Layer.mock(EventSink.EventSinkV2)({
+ write,
+ hasRunFinalization: () => Effect.succeed(false),
+ }),
+ Layer.succeed(RunFinalization.RunFinalizationObserver, {
+ refresh,
+ refreshAfterTurn: () => Effect.void,
+ }),
+ ),
+ ),
+ );
+ return Effect.gen(function* () {
+ const service = yield* RunFinalization.RunFinalizationService;
+ yield* service.finalize({ threadId, runId, scopeId });
+ assert.equal(capture.mock.calls.length, 1);
+ assert.deepEqual(refresh.mock.calls[0], [{ cwd: "/repo", threadId, runId }]);
+ assert.deepEqual(steps, ["capture", "refresh", "record"]);
+ }).pipe(Effect.provide(layer));
+});
+
it.effect("completes finalization when the post-checkpoint workspace refresh fails", () => {
const threadId = ThreadId.make("thread_refresh_failure");
const runId = RunId.make("run_refresh_failure");
@@ -23,6 +84,10 @@ it.effect("completes finalization when the post-checkpoint workspace refresh fai
const layer = RunFinalization.layer.pipe(
Layer.provide(
Layer.mergeAll(
+ Layer.mock(EventSink.EventSinkV2)({
+ hasRunFinalization: () => Effect.succeed(false),
+ write: () => Effect.sync(() => (captured.push("finalized"), [])),
+ }),
Layer.mock(CheckpointCapture.CheckpointCaptureServiceV2)({
execute: () =>
Effect.sync(() => {
@@ -36,6 +101,22 @@ it.effect("completes finalization when the post-checkpoint workspace refresh fai
checkpointScopes: [{ id: scopeId, runId, kind: "root_run" as const, cwd: "/repo" }],
checkpoints: [],
}),
+ getCheckpointCaptureContext: () =>
+ Effect.succeed({
+ run: {
+ id: runId,
+ threadId,
+ rootNodeId: null,
+ providerInstanceId: ProviderInstanceId.make("codex"),
+ status: "completed",
+ checkpointId: null,
+ } as OrchestrationV2Run,
+ rootNode: undefined,
+ scope: undefined,
+ providerThread: undefined,
+ readyCheckpointOrdinals: [],
+ sideChat: false,
+ }),
}),
Layer.succeed(RunFinalization.RunFinalizationObserver, {
refresh: () =>
@@ -54,7 +135,81 @@ it.effect("completes finalization when the post-checkpoint workspace refresh fai
return Effect.gen(function* () {
const service = yield* RunFinalization.RunFinalizationService;
yield* service.finalize({ threadId, runId, scopeId });
- assert.deepEqual(captured, ["checkpoint", "refresh"]);
+ assert.deepEqual(captured, ["checkpoint", "refresh", "finalized"]);
+ }).pipe(Effect.provide(layer));
+});
+
+it.effect("preserves checkpoint failures without refreshing the workspace", () => {
+ const threadId = ThreadId.make("thread_capture_failure");
+ const runId = RunId.make("run_capture_failure");
+ const scopeId = CheckpointScopeId.make("scope_capture_failure");
+ const captureError = new CheckpointCapture.CheckpointCaptureExecutionError({
+ threadId,
+ runId,
+ scopeId,
+ cause: new Error("Checkpoint capture failed"),
+ });
+ const refresh = vi.fn(() => Effect.void);
+ const layer = RunFinalization.layer.pipe(
+ Layer.provide(
+ Layer.mergeAll(
+ Layer.mock(EventSink.EventSinkV2)({
+ hasRunFinalization: () => Effect.succeed(false),
+ }),
+ Layer.mock(CheckpointCapture.CheckpointCaptureServiceV2)({
+ execute: () => Effect.fail(captureError),
+ }),
+ Layer.mock(ProjectionStore.ProjectionStoreV2)({
+ getCheckpointContext: () => Effect.die("capture failed before context lookup"),
+ }),
+ Layer.succeed(RunFinalization.RunFinalizationObserver, {
+ refresh,
+ refreshAfterTurn: () => Effect.void,
+ }),
+ ),
+ ),
+ );
+ return Effect.gen(function* () {
+ const service = yield* RunFinalization.RunFinalizationService;
+ const error = yield* service.finalize({ threadId, runId, scopeId }).pipe(Effect.flip);
+ assert.equal(error.operation, "capture-checkpoint");
+ assert.strictEqual(error.cause, captureError);
+ assert.equal(refresh.mock.calls.length, 0);
+ }).pipe(Effect.provide(layer));
+});
+
+it.effect("preserves checkpoint context read failures without refreshing the workspace", () => {
+ const threadId = ThreadId.make("thread_context_failure");
+ const runId = RunId.make("run_context_failure");
+ const scopeId = CheckpointScopeId.make("scope_context_failure");
+ const contextError = new ProjectionStore.ProjectionStoreReadError({
+ threadId,
+ cause: new Error("Checkpoint context read failed"),
+ });
+ const refresh = vi.fn(() => Effect.void);
+ const layer = RunFinalization.layer.pipe(
+ Layer.provide(
+ Layer.mergeAll(
+ Layer.mock(EventSink.EventSinkV2)({
+ hasRunFinalization: () => Effect.succeed(false),
+ }),
+ Layer.mock(CheckpointCapture.CheckpointCaptureServiceV2)({ execute: () => Effect.void }),
+ Layer.mock(ProjectionStore.ProjectionStoreV2)({
+ getCheckpointContext: () => Effect.fail(contextError),
+ }),
+ Layer.succeed(RunFinalization.RunFinalizationObserver, {
+ refresh,
+ refreshAfterTurn: () => Effect.void,
+ }),
+ ),
+ ),
+ );
+ return Effect.gen(function* () {
+ const service = yield* RunFinalization.RunFinalizationService;
+ const error = yield* service.finalize({ threadId, runId, scopeId }).pipe(Effect.flip);
+ assert.equal(error.operation, "refresh-workspace");
+ assert.strictEqual(error.cause, contextError);
+ assert.equal(refresh.mock.calls.length, 0);
}).pipe(Effect.provide(layer));
});
diff --git a/apps/server/src/orchestration-v2/RunFinalizationService.ts b/apps/server/src/orchestration-v2/RunFinalizationService.ts
index 40882033ba527..34cde32358965 100644
--- a/apps/server/src/orchestration-v2/RunFinalizationService.ts
+++ b/apps/server/src/orchestration-v2/RunFinalizationService.ts
@@ -1,5 +1,14 @@
-import { CheckpointScopeId, ProjectId, RunId, ThreadId } from "@t3tools/contracts";
+import {
+ CheckpointScopeId,
+ CommandId,
+ OrchestrationV2RunFinalizationOperation,
+ ProjectId,
+ RunId,
+ ThreadId,
+} from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
import * as Context from "effect/Context";
+import * as DateTime from "effect/DateTime";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Schema from "effect/Schema";
@@ -8,7 +17,9 @@ import * as PullRequestService from "../pullRequest/PullRequestService.ts";
import * as VcsStatusBroadcaster from "../vcs/VcsStatusBroadcaster.ts";
import * as WorkspaceEntries from "../workspace/WorkspaceEntries.ts";
import * as CheckpointCapture from "./CheckpointCaptureService.ts";
+import * as EventSink from "./EventSink.ts";
import * as ProjectionStore from "./ProjectionStore.ts";
+import * as RunFinalized from "./RunFinalized.ts";
export class RunFinalizationError extends Schema.TaggedError()(
"RunFinalizationError",
@@ -16,11 +27,13 @@ export class RunFinalizationError extends Schema.TaggedError()(
"RunFinalizationRefreshError",
{ cwd: Schema.String, cause: Schema.Defect() },
@@ -40,51 +53,134 @@ export class RunFinalizationObserver extends Context.Reference<{
export class RunFinalizationService extends Context.Service<
RunFinalizationService,
{
+ /**
+ * Captures the run's checkpoint, refreshes its workspace, then records
+ * `run.finalized`. At-least-once: every step is safe to repeat, and a run
+ * that already recorded its finalization is left as recorded. Every
+ * failure outside the best-effort display refresh names the step that failed.
+ */
readonly finalize: (input: {
readonly threadId: ThreadId;
readonly runId: RunId;
readonly scopeId: CheckpointScopeId;
}) => Effect.Effect;
+ /**
+ * Gives up on a run's finalization after the worker's last attempt failed
+ * at `operation`: fails the claimed capture effect and records
+ * `run.finalization-failed` in one transaction. Returns false, recording
+ * nothing, when `workerId` no longer holds the effect's lease.
+ */
+ readonly abandon: (input: {
+ readonly threadId: ThreadId;
+ readonly runId: RunId;
+ readonly scopeId: CheckpointScopeId;
+ readonly operation: OrchestrationV2RunFinalizationOperation;
+ readonly effectId: string;
+ readonly workerId: string;
+ readonly error: string;
+ }) => Effect.Effect;
}
>()("t3/orchestration-v2/RunFinalizationService") {}
const make = Effect.gen(function* () {
const checkpointCapture = yield* CheckpointCapture.CheckpointCaptureServiceV2;
const projections = yield* ProjectionStore.ProjectionStoreV2;
+ const eventSink = yield* EventSink.EventSinkV2;
const observer = yield* RunFinalizationObserver;
- const finalize: RunFinalizationService["Service"]["finalize"] = Effect.fn(
- "RunFinalizationService.finalize",
- )(function* (input) {
- yield* checkpointCapture
- .execute(input)
- .pipe(
- Effect.mapError(
- (cause) => new RunFinalizationError({ ...input, operation: "capture-checkpoint", cause }),
- ),
- );
- const projection = yield* projections
- .getCheckpointContext(input.threadId)
- .pipe(
+ const finalize = Effect.fn("RunFinalizationService.finalize")(function* (input: {
+ readonly threadId: ThreadId;
+ readonly runId: RunId;
+ readonly scopeId: CheckpointScopeId;
+ }) {
+ // Unexpected defects fail the step too; an interruption is replayed.
+ const failStep =
+ (operation: OrchestrationV2RunFinalizationOperation) => (cause: Cause.Cause) =>
+ Cause.hasInterruptsOnly(cause)
+ ? Effect.interrupt
+ : Effect.fail(
+ new RunFinalizationError({ ...input, operation, cause: Cause.squash(cause) }),
+ );
+
+ // A replay after a crash honours the disposition already recorded.
+ if (
+ yield* eventSink
+ .hasRunFinalization(input.runId)
+ .pipe(Effect.catchCause(failStep("capture-checkpoint")))
+ )
+ return;
+ yield* checkpointCapture.execute(input).pipe(Effect.catchCause(failStep("capture-checkpoint")));
+ yield* Effect.gen(function* () {
+ const projection = yield* projections.getCheckpointContext(input.threadId);
+ const cwd = projection.checkpointScopes.find((scope) => scope.id === input.scopeId)?.cwd;
+ if (cwd !== undefined) {
+ // A display refresh failure must not retry an already durable checkpoint.
+ yield* observer.refresh({ cwd, threadId: input.threadId, runId: input.runId }).pipe(
+ Effect.catchTags({
+ RunFinalizationRefreshError: (cause) =>
+ Effect.logWarning("Failed to refresh workspace after checkpoint capture", {
+ ...input,
+ cause,
+ }),
+ }),
+ );
+ }
+ }).pipe(Effect.catchCause(failStep("refresh-workspace")));
+ yield* Effect.gen(function* () {
+ const { run } = yield* projections.getCheckpointCaptureContext(input.threadId, input);
+ // A rolled-back run was discarded before its capture ran.
+ const outcome = run === undefined ? null : RunFinalized.runFinalizedOutcome(run.status);
+ if (run === undefined || outcome === null) return;
+ // EventSink drops the event when this run already recorded its finalization.
+ yield* eventSink.write({
+ commandId: CommandId.make(`command:effect:run.finalized:${run.id}`),
+ events: [
+ RunFinalized.makeRunFinalizedEvent({ run, outcome, occurredAt: yield* DateTime.now }),
+ ],
+ });
+ }).pipe(Effect.catchCause(failStep("record-finalized")));
+ });
+
+ const abandon: RunFinalizationService["Service"]["abandon"] = Effect.fn(
+ "RunFinalizationService.abandon",
+ )(
+ function* (input) {
+ const { run } = yield* projections.getCheckpointCaptureContext(input.threadId, input);
+ const { committed } = yield* eventSink.failEffect({
+ commandId: CommandId.make(`command:effect:run.finalization-failed:${input.runId}`),
+ effectId: input.effectId,
+ workerId: input.workerId,
+ error: input.error,
+ // A rolled-back run was discarded; there is nothing to report.
+ events:
+ run === undefined || run.status === "rolled_back"
+ ? []
+ : [
+ RunFinalized.makeRunFinalizationFailedEvent({
+ run,
+ operation: input.operation,
+ occurredAt: yield* DateTime.now,
+ }),
+ ],
+ });
+ return committed;
+ },
+ (effect, input) =>
+ effect.pipe(
Effect.mapError(
- (cause) => new RunFinalizationError({ ...input, operation: "refresh-workspace", cause }),
- ),
- );
- const cwd = projection.checkpointScopes.find((scope) => scope.id === input.scopeId)?.cwd;
- if (cwd !== undefined) {
- // Retrying a display refresh after the checkpoint is durable blocks the next turn.
- yield* observer.refresh({ cwd, threadId: input.threadId, runId: input.runId }).pipe(
- Effect.catchTags({
- RunFinalizationRefreshError: (cause) =>
- Effect.logWarning("Failed to refresh workspace after checkpoint capture", {
- ...input,
+ (cause) =>
+ new RunFinalizationError({
+ threadId: input.threadId,
+ runId: input.runId,
+ scopeId: input.scopeId,
+ operation: input.operation,
cause,
}),
- }),
- );
- }
- });
- return RunFinalizationService.of({ finalize });
+ ),
+ ),
+ );
+
+ return RunFinalizationService.of({ finalize, abandon });
});
export const layer = Layer.effect(RunFinalizationService, make);
diff --git a/apps/server/src/orchestration-v2/RunFinalized.test.ts b/apps/server/src/orchestration-v2/RunFinalized.test.ts
new file mode 100644
index 0000000000000..40b352ff625a5
--- /dev/null
+++ b/apps/server/src/orchestration-v2/RunFinalized.test.ts
@@ -0,0 +1,924 @@
+import { assert, it } from "@effect/vitest";
+import {
+ CheckpointId,
+ CheckpointScopeId,
+ CommandId,
+ EventId,
+ MessageId,
+ NodeId,
+ type OrchestrationV2DomainEvent,
+ type OrchestrationV2Run,
+ type OrchestrationV2StoredEvent,
+ ProjectId,
+ ProviderInstanceId,
+ ProviderThreadId,
+ RunAttemptId,
+ RunId,
+ ThreadId,
+} from "@t3tools/contracts";
+import * as DateTime from "effect/DateTime";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Stream from "effect/Stream";
+import * as TestClock from "effect/testing/TestClock";
+
+import * as SqlitePersistence from "../persistence/Sqlite.ts";
+import * as ServerSettings from "../serverSettings.ts";
+import * as CheckpointCapture from "./CheckpointCaptureService.ts";
+import * as CheckpointRollbackService from "./CheckpointRollbackService.ts";
+import * as EffectOutbox from "./EffectOutbox.ts";
+import * as EffectWorker from "./EffectWorker.ts";
+import * as EventSink from "./EventSink.ts";
+import * as EventStore from "./EventStore.ts";
+import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator";
+import * as ProjectionStore from "./ProjectionStore.ts";
+import * as ProviderRuntimeRecovery from "./ProviderRuntimeRecoveryService.ts";
+import * as ProviderSessionManager from "./ProviderSessionManager.ts";
+import * as ProviderTurnControlService from "./ProviderTurnControlService.ts";
+import * as ProviderTurnStartService from "./ProviderTurnStartService.ts";
+import * as RunFinalization from "./RunFinalizationService.ts";
+import { checkpointCaptureEffectId, makeRunFinalizationFailedEvent } from "./RunFinalized.ts";
+import * as RuntimeRequestService from "./RuntimeRequestService.ts";
+import * as ThreadManagementService from "./ThreadManagementService.ts";
+import * as ThreadTitleRegenerationService from "./ThreadTitleRegenerationService.ts";
+
+const threadId = ThreadId.make("thread:run-finalized");
+const runId = RunId.make("run:run-finalized");
+const scopeId = CheckpointScopeId.make("scope:run-finalized");
+const rootNodeId = NodeId.make("node:run-finalized-root");
+const providerThreadId = ProviderThreadId.make("provider-thread:run-finalized");
+const providerInstanceId = ProviderInstanceId.make("codex");
+const checkpointId = CheckpointId.make("checkpoint:run-finalized");
+const attemptId = RunAttemptId.make("attempt:run-finalized");
+
+const maxAttempts = 2;
+/** The worker's backoff after a capture's first failed attempt. */
+const firstRetryDelay = "100 millis";
+/** The worker's backoff after a capture's last attempt, when its failure record cannot commit. */
+const lastRetryDelay = "200 millis";
+
+/**
+ * Real stores, outbox, worker, finalization and restart recovery. Checkpoint
+ * capture and workspace refresh are stubs. `finalizationSink` can inject
+ * faults into the event sink the finalization service writes through.
+ */
+const makeLayer = (
+ capture: Effect.Effect<
+ void,
+ CheckpointCapture.CheckpointCaptureExecutionError,
+ EventSink.EventSinkV2
+ >,
+ refresh: () => Effect.Effect = () =>
+ Effect.void,
+ finalizationSink: (sink: EventSink.EventSinkV2Shape) => EventSink.EventSinkV2Shape = (sink) =>
+ sink,
+) => {
+ const stores = Layer.mergeAll(
+ SqlitePersistence.layerMemory,
+ EventStore.layer.pipe(Layer.provideMerge(SqlitePersistence.layerMemory)),
+ ProjectionStore.layer.pipe(Layer.provideMerge(SqlitePersistence.layerMemory)),
+ );
+ const eventSink = EventSink.layer.pipe(Layer.provide(stores));
+ const outbox = EffectOutbox.layer.pipe(Layer.provide(SqlitePersistence.layerMemory));
+ const finalization = RunFinalization.layer.pipe(
+ Layer.provide(
+ Layer.mergeAll(
+ stores,
+ Layer.effect(
+ EventSink.EventSinkV2,
+ EventSink.EventSinkV2.pipe(Effect.map(finalizationSink)),
+ ).pipe(Layer.provide(eventSink)),
+ Layer.effect(
+ CheckpointCapture.CheckpointCaptureServiceV2,
+ Effect.gen(function* () {
+ const sink = yield* EventSink.EventSinkV2;
+ return { execute: () => Effect.provideService(capture, EventSink.EventSinkV2, sink) };
+ }),
+ ).pipe(Layer.provide(eventSink)),
+ Layer.succeed(RunFinalization.RunFinalizationObserver, {
+ refresh,
+ refreshAfterTurn: () => Effect.void,
+ }),
+ ),
+ ),
+ );
+ const executor = EffectWorker.layerExecutor.pipe(
+ Layer.provide(
+ Layer.mergeAll(
+ finalization,
+ Layer.mock(ProviderSessionManager.ProviderSessionManagerV2)({}),
+ Layer.mock(CheckpointRollbackService.CheckpointRollbackServiceV2)({}),
+ Layer.mock(ProviderTurnControlService.ProviderTurnControlServiceV2)({}),
+ Layer.mock(ProviderTurnStartService.ProviderTurnStartServiceV2)({}),
+ Layer.mock(RuntimeRequestService.RuntimeRequestServiceV2)({}),
+ Layer.mock(ThreadTitleRegenerationService.ThreadTitleRegenerationService)({}),
+ Layer.mock(ThreadManagementService.ThreadManagementService)({}),
+ ServerSettings.layerTest(),
+ ),
+ ),
+ );
+ const worker = EffectWorker.layerWithOptions({
+ workerId: "worker:run-finalized",
+ maxAttempts,
+ }).pipe(Layer.provide(Layer.merge(outbox, executor)));
+ const recovery = ProviderRuntimeRecovery.layer.pipe(
+ Layer.provide(
+ Layer.mergeAll(
+ stores,
+ eventSink,
+ outbox,
+ worker,
+ IdAllocator.layer,
+ ServerSettings.layerTest(),
+ ),
+ ),
+ );
+ return Layer.mergeAll(stores, eventSink, outbox, finalization, worker, recovery);
+};
+
+const makeRun = (
+ now: DateTime.Utc,
+ status: OrchestrationV2Run["status"],
+ overrides: Partial = {},
+): OrchestrationV2Run => ({
+ id: runId,
+ threadId,
+ ordinal: 1,
+ providerInstanceId,
+ modelSelection: { instanceId: providerInstanceId, model: "gpt-5.4" },
+ providerThreadId,
+ userMessageId: MessageId.make("message:run-finalized"),
+ rootNodeId,
+ activeAttemptId: null,
+ status,
+ requestedAt: now,
+ startedAt: now,
+ completedAt: null,
+ checkpointId: null,
+ contextHandoffId: null,
+ ...overrides,
+});
+
+let eventCounter = 0;
+const runEvent = (
+ type: "run.created" | "run.updated",
+ run: OrchestrationV2Run,
+ occurredAt: DateTime.Utc,
+): OrchestrationV2DomainEvent => ({
+ id: EventId.make(`event:run-finalized-test:${(eventCounter += 1)}`),
+ type,
+ threadId,
+ runId: run.id,
+ providerInstanceId,
+ occurredAt,
+ payload: run,
+});
+
+const captureEffect = {
+ id: checkpointCaptureEffectId(runId),
+ commandId: CommandId.make(`command:effect:checkpoint.capture:${runId}`),
+ threadId,
+ request: { type: "checkpoint.capture" as const, runId, scopeId },
+};
+
+const seedThread = Effect.gen(function* () {
+ const eventSink = yield* EventSink.EventSinkV2;
+ const now = yield* DateTime.now;
+ yield* eventSink.write({
+ events: [
+ {
+ id: EventId.make("event:run-finalized-test:thread"),
+ type: "thread.created",
+ threadId,
+ providerInstanceId,
+ occurredAt: now,
+ payload: {
+ createdBy: "user",
+ creationSource: "web",
+ id: threadId,
+ projectId: ProjectId.make("project:run-finalized"),
+ title: "Run finalized",
+ providerInstanceId,
+ modelSelection: { instanceId: providerInstanceId, model: "gpt-5.4" },
+ runtimeMode: "full-access",
+ interactionMode: "default",
+ branch: null,
+ worktreePath: null,
+ activeProviderThreadId: null,
+ lineage: { parentThreadId: null, relationshipToParent: null, rootThreadId: threadId },
+ forkedFrom: null,
+ createdAt: now,
+ updatedAt: now,
+ archivedAt: null,
+ settledOverride: null,
+ settledAt: null,
+ lastVisitedAt: null,
+ deletedAt: null,
+ },
+ },
+ {
+ id: EventId.make("event:run-finalized-test:scope"),
+ type: "checkpoint-scope.created",
+ threadId,
+ occurredAt: now,
+ payload: {
+ id: scopeId,
+ threadId,
+ runId,
+ nodeId: rootNodeId,
+ parentScopeId: null,
+ providerThreadId,
+ kind: "root_run",
+ ordinalWithinParent: 0,
+ advancesAppRunCount: true,
+ cwd: "/repo",
+ createdAt: now,
+ },
+ },
+ runEvent("run.created", makeRun(now, "running"), now),
+ ],
+ });
+});
+
+const storedEvents = Effect.gen(function* () {
+ const eventStore = yield* EventStore.EventStoreV2;
+ return Array.from(yield* eventStore.read({ threadId }).pipe(Stream.runCollect));
+});
+
+const finalizedEvents = (events: ReadonlyArray) =>
+ events.flatMap((stored) => (stored.event.type === "run.finalized" ? [stored] : []));
+
+/** Every finalization record for the thread, success or failure. */
+const finalizationRecords = storedEvents.pipe(
+ Effect.map((events) =>
+ events.flatMap((stored) =>
+ stored.event.type === "run.finalized" || stored.event.type === "run.finalization-failed"
+ ? [{ type: stored.event.type, payload: stored.event.payload }]
+ : [],
+ ),
+ ),
+);
+
+/** Runs every claimable effect on the real worker. */
+const drainWorker = EffectWorker.OrchestrationEffectWorkerV2.pipe(
+ Effect.flatMap((worker) => worker.drain()),
+);
+
+const captureStatus = EffectOutbox.EffectOutboxV2.pipe(
+ Effect.flatMap((outbox) => outbox.get(captureEffect.id)),
+ Effect.map(Option.map((effect) => effect.status)),
+);
+
+const runStatus = ProjectionStore.ProjectionStoreV2.pipe(
+ Effect.flatMap((projections) =>
+ projections.getCheckpointCaptureContext(threadId, { runId, scopeId }),
+ ),
+ Effect.map(({ run }) => run?.status),
+);
+
+/** The startup recovery a restarted server runs before its worker resumes. */
+const restartServer = ProviderRuntimeRecovery.ProviderRuntimeRecoveryService.pipe(
+ Effect.flatMap((recovery) => recovery.recover),
+);
+
+/** Stands in for CheckpointCaptureService: commits the checkpoint once, like the real one. */
+const commitCapture = (status: "completed" | "interrupted" | "cancelled") =>
+ Effect.gen(function* () {
+ const eventSink = yield* EventSink.EventSinkV2;
+ const now = yield* DateTime.now;
+ yield* eventSink.commitCommand({
+ commandId: captureEffect.commandId,
+ threadId,
+ commandType: "checkpoint.capture",
+ acceptedAt: now,
+ effects: [],
+ events: [
+ runEvent("run.updated", makeRun(now, status, { checkpointId, completedAt: now }), now),
+ ],
+ });
+ }).pipe(Effect.orDie);
+
+const failCapture = Effect.fail(
+ new CheckpointCapture.CheckpointCaptureExecutionError({
+ threadId,
+ runId,
+ scopeId,
+ cause: "simulated capture failure",
+ }),
+);
+
+const failRefresh = () =>
+ Effect.fail(
+ new RunFinalization.RunFinalizationRefreshError({
+ cwd: "/repo",
+ cause: "simulated refresh failure",
+ }),
+ );
+
+/** Ends the run waiting on its capture, as RunExecutionService does. */
+const finishProviderTurn = (status: "waiting" | "interrupted" | "cancelled") =>
+ Effect.gen(function* () {
+ const eventSink = yield* EventSink.EventSinkV2;
+ const now = yield* DateTime.now;
+ yield* eventSink.writeWithEffects({
+ events: [
+ runEvent(
+ "run.updated",
+ makeRun(now, status, status === "waiting" ? {} : { completedAt: now }),
+ now,
+ ),
+ ],
+ effects: [captureEffect],
+ });
+ });
+
+it.effect("finalizes a completed run once, after its checkpoint and workspace refresh", () => {
+ const refreshedAtSequence: Array = [];
+ let probe: Effect.Effect = Effect.void;
+ return Effect.gen(function* () {
+ const eventSink = yield* EventSink.EventSinkV2;
+ yield* seedThread;
+ yield* finishProviderTurn("waiting");
+ assert.lengthOf(yield* finalizationRecords, 0);
+
+ probe = eventSink.latestSequence({ threadId }).pipe(
+ Effect.map((sequence) => {
+ refreshedAtSequence.push(sequence);
+ }),
+ Effect.orDie,
+ );
+ yield* drainWorker;
+
+ const events = yield* storedEvents;
+ const finalized = finalizedEvents(events);
+ assert.lengthOf(finalized, 1);
+ const [stored] = finalized;
+ assert.deepEqual(stored?.event.payload, { runId, outcome: "completed", checkpointId });
+ assert.equal(stored?.event.id, EventId.make(`event:run-finalized:${runId}`));
+ const completedAt = events.find(
+ (event) => event.event.type === "run.updated" && event.event.payload.status === "completed",
+ )?.sequence;
+ assert.isDefined(completedAt);
+ assert.deepEqual(refreshedAtSequence, [completedAt!]);
+ assert.isTrue(stored!.sequence > completedAt!);
+ assert.deepEqual(yield* captureStatus, Option.some("succeeded"));
+ }).pipe(Effect.provide(makeLayer(commitCapture("completed"), () => probe)));
+});
+
+it.effect("recording the milestone leaves thread activity where the run left it", () =>
+ Effect.gen(function* () {
+ const projections = yield* ProjectionStore.ProjectionStoreV2;
+ yield* seedThread;
+ yield* finishProviderTurn("waiting");
+ yield* drainWorker;
+
+ const events = yield* storedEvents;
+ const completed = events.find(
+ (event) => event.event.type === "run.updated" && event.event.payload.status === "completed",
+ );
+ const [milestone] = finalizedEvents(events);
+ assert.isDefined(completed);
+ assert.isDefined(milestone);
+ // The slow refresh put the milestone a minute after the run's last write.
+ assert.isTrue(DateTime.isGreaterThan(milestone.event.occurredAt, completed.event.occurredAt));
+ const shell = yield* projections.getThreadShell(threadId);
+ assert.deepEqual(shell?.updatedAt, completed.event.occurredAt);
+ }).pipe(
+ Effect.provide(makeLayer(commitCapture("completed"), () => TestClock.adjust("60 seconds"))),
+ ),
+);
+
+it.effect("a restart after finalizing but before settling records one milestone", () => {
+ let captures = 0;
+ return Effect.gen(function* () {
+ const eventSink = yield* EventSink.EventSinkV2;
+ const outbox = yield* EffectOutbox.EffectOutboxV2;
+ const finalization = yield* RunFinalization.RunFinalizationService;
+ yield* seedThread;
+ yield* finishProviderTurn("waiting");
+ // A worker finalized, then its process died before settling the effect.
+ yield* outbox.claimNext({ workerId: "worker:crashed" });
+ yield* finalization.finalize({ threadId, runId, scopeId });
+ assert.lengthOf(finalizedEvents(yield* storedEvents), 1);
+
+ // Restart requeues the capture; the worker settles it without capturing again.
+ const summary = yield* restartServer;
+ assert.equal(summary.requeuedEffects, 1);
+ yield* drainWorker;
+ assert.deepEqual(yield* captureStatus, Option.some("succeeded"));
+ assert.equal(captures, 1);
+ // A later write of the finished run adds nothing either.
+ const now = yield* DateTime.now;
+ yield* eventSink.write({
+ events: [
+ runEvent("run.updated", makeRun(now, "completed", { checkpointId, completedAt: now }), now),
+ ],
+ });
+ assert.deepEqual(yield* finalizationRecords, [
+ { type: "run.finalized", payload: { runId, outcome: "completed", checkpointId } },
+ ]);
+ }).pipe(
+ Effect.provide(
+ makeLayer(
+ Effect.suspend(() => {
+ captures += 1;
+ return commitCapture("completed");
+ }),
+ ),
+ ),
+ );
+});
+
+it.effect.each(["interrupted", "cancelled"] as const)(
+ "a stopped run with a capture finalizes as %s after the capture",
+ (status) =>
+ Effect.gen(function* () {
+ yield* seedThread;
+ yield* finishProviderTurn(status);
+ assert.lengthOf(yield* finalizationRecords, 0);
+ yield* drainWorker;
+ assert.deepEqual(yield* finalizationRecords, [
+ { type: "run.finalized", payload: { runId, outcome: status, checkpointId } },
+ ]);
+ }).pipe(Effect.provide(makeLayer(commitCapture(status)))),
+);
+
+/** Ends a running attempt through the ownership guard, as RunExecutionService does. */
+const finishGuardedTurn = (
+ status: "interrupted" | "cancelled",
+ guard: { readonly activeAttemptId: RunAttemptId; readonly expectedStatus: "running" | "waiting" },
+) =>
+ Effect.gen(function* () {
+ const eventSink = yield* EventSink.EventSinkV2;
+ const now = yield* DateTime.now;
+ yield* eventSink.write({
+ events: [
+ runEvent("run.updated", makeRun(now, "running", { activeAttemptId: attemptId }), now),
+ ],
+ });
+ return yield* eventSink.writeIfRunCurrent({
+ threadId,
+ runId,
+ ...guard,
+ events: [
+ runEvent(
+ "run.updated",
+ makeRun(now, status, { activeAttemptId: attemptId, completedAt: now }),
+ now,
+ ),
+ ],
+ effects: [captureEffect],
+ });
+ });
+
+it.effect.each(["interrupted", "cancelled"] as const)(
+ "a guarded stop that queues a capture finalizes as %s after the capture",
+ (status) =>
+ Effect.gen(function* () {
+ yield* seedThread;
+ const result = yield* finishGuardedTurn(status, {
+ activeAttemptId: attemptId,
+ expectedStatus: "running",
+ });
+ assert.isTrue(result.committed);
+ assert.lengthOf(yield* finalizationRecords, 0);
+ yield* drainWorker;
+ assert.deepEqual(yield* finalizationRecords, [
+ { type: "run.finalized", payload: { runId, outcome: status, checkpointId } },
+ ]);
+ }).pipe(Effect.provide(makeLayer(commitCapture(status)))),
+);
+
+it.effect("a guarded stop that no longer owns the run commits and queues nothing", () =>
+ Effect.gen(function* () {
+ yield* seedThread;
+ const result = yield* finishGuardedTurn("interrupted", {
+ activeAttemptId: RunAttemptId.make("attempt:run-finalized-stale"),
+ expectedStatus: "running",
+ });
+ assert.isFalse(result.committed);
+ assert.deepEqual(yield* captureStatus, Option.none());
+ assert.equal(yield* drainWorker, 0);
+ assert.equal(yield* runStatus, "running");
+ assert.lengthOf(yield* finalizationRecords, 0);
+ }).pipe(Effect.provide(makeLayer(commitCapture("interrupted")))),
+);
+
+it.effect("a run that ends without a capture finalizes in its terminal commit", () =>
+ Effect.gen(function* () {
+ const eventSink = yield* EventSink.EventSinkV2;
+ yield* seedThread;
+ const now = yield* DateTime.now;
+ const failed = makeRun(now, "failed", { completedAt: now });
+ const [terminal, milestone] = yield* eventSink.write({
+ events: [runEvent("run.updated", failed, now)],
+ });
+ assert.equal(terminal?.event.type, "run.updated");
+ assert.equal(milestone?.event.type, "run.finalized");
+ assert.equal(milestone?.commandId, terminal?.commandId);
+ // A repeated terminal write and a later update to the finished run add nothing.
+ yield* eventSink.write({ events: [runEvent("run.updated", failed, now)] });
+ yield* eventSink.write({
+ events: [runEvent("run.updated", { ...failed, status: "cancelled" }, now)],
+ });
+ assert.deepEqual(
+ finalizedEvents(yield* storedEvents).map((stored) => stored.event.payload),
+ [{ runId, outcome: "failed", checkpointId: null }],
+ );
+ }).pipe(Effect.provide(makeLayer(Effect.void))),
+);
+
+it.effect("unfinished, discarded, and previously finished runs never finalize", () =>
+ Effect.gen(function* () {
+ const eventSink = yield* EventSink.EventSinkV2;
+ const finalization = yield* RunFinalization.RunFinalizationService;
+ yield* seedThread;
+ const now = yield* DateTime.now;
+ // Waiting on a capture that never ran.
+ yield* finishProviderTurn("waiting");
+ assert.lengthOf(yield* finalizationRecords, 0);
+ // Rolled back before the capture ran: discarded, and the capture skips it.
+ yield* eventSink.write({
+ events: [runEvent("run.updated", makeRun(now, "rolled_back", { completedAt: now }), now)],
+ });
+ yield* finalization.finalize({ threadId, runId, scopeId });
+ assert.lengthOf(yield* finalizationRecords, 0);
+
+ // A run that finished before this milestone existed has no event. A later
+ // update to it must not invent one.
+ const historical = makeRun(now, "completed", {
+ id: RunId.make("run:run-finalized-historical"),
+ ordinal: 2,
+ completedAt: now,
+ });
+ yield* eventSink.write({ events: [runEvent("run.created", historical, now)] });
+ yield* eventSink.write({ events: [runEvent("run.updated", historical, now)] });
+ assert.lengthOf(yield* finalizationRecords, 0);
+ }).pipe(Effect.provide(makeLayer(Effect.void))),
+);
+
+it.effect.each(["waiting", "interrupted"] as const)(
+ "a capture that gives up after a %s turn records the failure, never run.finalized",
+ (status) =>
+ Effect.gen(function* () {
+ yield* seedThread;
+ yield* finishProviderTurn(status);
+ // The first failure will be retried, so nothing is recorded yet.
+ yield* drainWorker;
+ assert.deepEqual(yield* captureStatus, Option.some("pending"));
+ assert.lengthOf(yield* finalizationRecords, 0);
+
+ yield* TestClock.adjust(firstRetryDelay);
+ yield* drainWorker;
+ assert.deepEqual(yield* captureStatus, Option.some("failed"));
+ const failure = [
+ {
+ type: "run.finalization-failed" as const,
+ payload: { runId, operation: "capture-checkpoint" as const },
+ },
+ ];
+ assert.deepEqual(yield* finalizationRecords, failure);
+
+ // A restart cancels a run still waiting on the failed capture. That is
+ // not a finalization either.
+ yield* restartServer;
+ assert.equal(yield* runStatus, status === "waiting" ? "cancelled" : "interrupted");
+ assert.deepEqual(yield* finalizationRecords, failure);
+ }).pipe(Effect.provide(makeLayer(failCapture))),
+);
+
+it.effect("a failed display refresh finalizes the durable checkpoint across restart", () =>
+ Effect.gen(function* () {
+ const eventSink = yield* EventSink.EventSinkV2;
+ yield* seedThread;
+ yield* finishProviderTurn("waiting");
+ yield* drainWorker;
+ yield* TestClock.adjust(firstRetryDelay);
+ yield* drainWorker;
+
+ assert.deepEqual(yield* captureStatus, Option.some("succeeded"));
+ assert.equal(yield* runStatus, "completed");
+ const finalized = [
+ {
+ type: "run.finalized" as const,
+ payload: { runId, outcome: "completed" as const, checkpointId },
+ },
+ ];
+ assert.deepEqual(yield* finalizationRecords, finalized);
+ // Neither a restart nor a later write duplicates the recorded finalization.
+ yield* restartServer;
+ const now = yield* DateTime.now;
+ yield* eventSink.write({
+ events: [
+ runEvent("run.updated", makeRun(now, "completed", { checkpointId, completedAt: now }), now),
+ ],
+ });
+ assert.deepEqual(yield* finalizationRecords, finalized);
+ }).pipe(Effect.provide(makeLayer(commitCapture("completed"), failRefresh))),
+);
+
+it.effect("a failed display refresh is not retried after run.finalized", () => {
+ let refreshes = 0;
+ return Effect.gen(function* () {
+ yield* seedThread;
+ yield* finishProviderTurn("waiting");
+ yield* drainWorker;
+ yield* TestClock.adjust(firstRetryDelay);
+ yield* drainWorker;
+ assert.equal(refreshes, 1);
+ assert.deepEqual(yield* finalizationRecords, [
+ { type: "run.finalized", payload: { runId, outcome: "completed", checkpointId } },
+ ]);
+ }).pipe(
+ Effect.provide(
+ makeLayer(commitCapture("completed"), () =>
+ Effect.suspend(() => ((refreshes += 1) === 1 ? failRefresh() : Effect.void)),
+ ),
+ ),
+ );
+});
+
+it.effect(
+ "a capture cancelled outside a command records the failure when restart ends the run",
+ () =>
+ Effect.gen(function* () {
+ const outbox = yield* EffectOutbox.EffectOutboxV2;
+ yield* seedThread;
+ yield* finishProviderTurn("waiting");
+ yield* outbox.cancelUnsettled({
+ threadId,
+ effectTypes: ["checkpoint.capture"],
+ reason: "test",
+ });
+ assert.deepEqual(yield* captureStatus, Option.some("cancelled"));
+ assert.lengthOf(yield* finalizationRecords, 0);
+ yield* restartServer;
+ assert.equal(yield* runStatus, "cancelled");
+ assert.deepEqual(yield* finalizationRecords, [
+ {
+ type: "run.finalization-failed",
+ payload: { runId, operation: "capture-checkpoint" },
+ },
+ ]);
+ }).pipe(Effect.provide(makeLayer(Effect.void))),
+);
+
+it.effect("a command that cancels a capture records the failure in its commit", () =>
+ Effect.gen(function* () {
+ const eventSink = yield* EventSink.EventSinkV2;
+ yield* seedThread;
+ yield* finishProviderTurn("interrupted");
+ const now = yield* DateTime.now;
+ const commandId = CommandId.make("command:run-finalized-test:cancel-capture");
+ const { storedEvents, receipt } = yield* eventSink.commitCommand({
+ commandId,
+ threadId,
+ commandType: "test.cancel-capture",
+ acceptedAt: now,
+ events: [runEvent("run.updated", makeRun(now, "interrupted", { completedAt: now }), now)],
+ effects: [],
+ cancelUnsettledEffects: { effectTypes: ["checkpoint.capture"], reason: "test" },
+ });
+ const failure = [
+ {
+ type: "run.finalization-failed" as const,
+ payload: { runId, operation: "capture-checkpoint" as const },
+ },
+ ];
+ assert.deepEqual(yield* captureStatus, Option.some("cancelled"));
+ assert.deepEqual(yield* finalizationRecords, failure);
+ const recorded = storedEvents.at(-1);
+ assert.equal(recorded?.event.type, "run.finalization-failed");
+ assert.equal(recorded?.commandId, commandId);
+ assert.equal(receipt.resultSequence, recorded?.sequence);
+
+ // Nothing runs the cancelled capture, and a restart adds nothing.
+ assert.equal(yield* drainWorker, 0);
+ yield* restartServer;
+ assert.deepEqual(yield* finalizationRecords, failure);
+ }).pipe(Effect.provide(makeLayer(Effect.die("a cancelled capture must not run")))),
+);
+
+const captureDefect = Effect.die("simulated unexpected checkpoint defect");
+const refreshDefect = () => Effect.die("simulated unexpected refresh defect");
+
+it.effect.each([
+ {
+ label: "a capture defect after a waiting turn",
+ turn: "waiting" as const,
+ capture: captureDefect,
+ refresh: undefined,
+ operation: "capture-checkpoint" as const,
+ runAfterRestart: "cancelled",
+ },
+ {
+ label: "a capture defect after an interrupted turn",
+ turn: "interrupted" as const,
+ capture: captureDefect,
+ refresh: undefined,
+ operation: "capture-checkpoint" as const,
+ runAfterRestart: "interrupted",
+ },
+ {
+ label: "a refresh defect after a completed run's checkpoint",
+ turn: "waiting" as const,
+ capture: commitCapture("completed"),
+ refresh: refreshDefect,
+ operation: "refresh-workspace" as const,
+ runAfterRestart: "completed",
+ },
+ {
+ label: "a refresh defect after an interrupted run's checkpoint",
+ turn: "interrupted" as const,
+ capture: commitCapture("interrupted"),
+ refresh: refreshDefect,
+ operation: "refresh-workspace" as const,
+ runAfterRestart: "interrupted",
+ },
+])("$label records the failure when retries run out", (testCase) =>
+ Effect.gen(function* () {
+ yield* seedThread;
+ yield* finishProviderTurn(testCase.turn);
+ yield* drainWorker;
+ assert.deepEqual(yield* captureStatus, Option.some("pending"));
+ assert.lengthOf(yield* finalizationRecords, 0);
+
+ yield* TestClock.adjust(firstRetryDelay);
+ yield* drainWorker;
+ assert.deepEqual(yield* captureStatus, Option.some("failed"));
+ const failure = [
+ {
+ type: "run.finalization-failed" as const,
+ payload: { runId, operation: testCase.operation },
+ },
+ ];
+ assert.deepEqual(yield* finalizationRecords, failure);
+
+ yield* restartServer;
+ yield* drainWorker;
+ assert.equal(yield* runStatus, testCase.runAfterRestart);
+ assert.deepEqual(yield* captureStatus, Option.some("failed"));
+ assert.deepEqual(yield* finalizationRecords, failure);
+ }).pipe(Effect.provide(makeLayer(testCase.capture, testCase.refresh))),
+);
+
+it.effect("a failure record that cannot commit keeps the capture recoverable", () => {
+ let faults = 1;
+ let captures = 0;
+ return Effect.gen(function* () {
+ yield* seedThread;
+ yield* finishProviderTurn("waiting");
+ yield* drainWorker;
+ yield* TestClock.adjust(firstRetryDelay);
+ // The last attempt fails and its failure record cannot commit.
+ const exit = yield* Effect.exit(drainWorker);
+ assert.isTrue(Exit.isFailure(exit));
+ assert.equal(faults, 0);
+ // The rolled-back commit neither failed the capture nor recorded anything.
+ assert.deepEqual(yield* captureStatus, Option.some("pending"));
+ assert.lengthOf(yield* finalizationRecords, 0);
+ // The capture waits out the backoff instead of running again at once.
+ yield* drainWorker;
+ assert.equal(captures, 2);
+ assert.deepEqual(yield* captureStatus, Option.some("pending"));
+
+ // A restart keeps the work; the next attempt gives up and records it.
+ yield* restartServer;
+ yield* TestClock.adjust(lastRetryDelay);
+ yield* drainWorker;
+ assert.deepEqual(yield* captureStatus, Option.some("failed"));
+ assert.deepEqual(yield* finalizationRecords, [
+ {
+ type: "run.finalization-failed",
+ payload: { runId, operation: "capture-checkpoint" },
+ },
+ ]);
+ }).pipe(
+ Effect.provide(
+ makeLayer(
+ Effect.suspend(() => {
+ captures += 1;
+ return failCapture;
+ }),
+ undefined,
+ (sink) => ({
+ ...sink,
+ // Also append an event whose id is taken, so the commit fails after
+ // the capture's terminal status was written inside it.
+ failEffect: (input) =>
+ Effect.suspend(() => {
+ if (faults === 0) return sink.failEffect(input);
+ faults -= 1;
+ const at = input.events[0]!.occurredAt;
+ return sink.failEffect({
+ ...input,
+ events: [
+ ...input.events,
+ {
+ ...runEvent("run.updated", makeRun(at, "waiting"), at),
+ id: EventId.make("event:run-finalized-test:thread"),
+ },
+ ],
+ });
+ }),
+ }),
+ ),
+ ),
+ );
+});
+
+it.effect("a restart after a failure record but before settling never finalizes again", () => {
+ let captures = 0;
+ return Effect.gen(function* () {
+ const eventSink = yield* EventSink.EventSinkV2;
+ const outbox = yield* EffectOutbox.EffectOutboxV2;
+ yield* seedThread;
+ yield* finishProviderTurn("waiting");
+ // A worker recorded the failure, then its process died before settling
+ // the capture (the state a non-atomic writer could leave).
+ yield* outbox.claimNext({ workerId: "worker:crashed" });
+ const context = yield* ProjectionStore.ProjectionStoreV2.pipe(
+ Effect.flatMap((projections) =>
+ projections.getCheckpointCaptureContext(threadId, { runId, scopeId }),
+ ),
+ );
+ yield* eventSink.write({
+ events: [
+ makeRunFinalizationFailedEvent({
+ run: context.run!,
+ operation: "capture-checkpoint",
+ occurredAt: yield* DateTime.now,
+ }),
+ ],
+ });
+
+ const summary = yield* restartServer;
+ assert.equal(summary.requeuedEffects, 1);
+ yield* drainWorker;
+ assert.equal(captures, 0);
+ assert.deepEqual(yield* captureStatus, Option.some("succeeded"));
+ assert.deepEqual(yield* finalizationRecords, [
+ {
+ type: "run.finalization-failed",
+ payload: { runId, operation: "capture-checkpoint" },
+ },
+ ]);
+ }).pipe(
+ Effect.provide(
+ makeLayer(
+ Effect.suspend(() => {
+ captures += 1;
+ return commitCapture("completed");
+ }),
+ ),
+ ),
+ );
+});
+
+it.effect("an interrupted capture is replayed, never recorded as a failure", () => {
+ let captures = 0;
+ const started = Deferred.makeUnsafe();
+ return Effect.gen(function* () {
+ yield* seedThread;
+ yield* finishProviderTurn("waiting");
+ // Interrupted on every attempt in a live worker: retried, not given up.
+ yield* drainWorker;
+ yield* TestClock.adjust(firstRetryDelay);
+ yield* drainWorker;
+ yield* TestClock.adjust("30 seconds");
+ assert.deepEqual(yield* captureStatus, Option.some("pending"));
+ assert.lengthOf(yield* finalizationRecords, 0);
+
+ // A shutdown interrupts the worker mid-capture and leaves the claim running.
+ const shuttingDown = yield* Effect.forkChild(drainWorker);
+ yield* Deferred.await(started);
+ yield* Fiber.interrupt(shuttingDown);
+ assert.deepEqual(yield* captureStatus, Option.some("running"));
+ assert.lengthOf(yield* finalizationRecords, 0);
+
+ // Restart replays it and the capture now succeeds.
+ yield* restartServer;
+ yield* drainWorker;
+ assert.equal(captures, 4);
+ assert.deepEqual(yield* finalizationRecords, [
+ { type: "run.finalized", payload: { runId, outcome: "completed", checkpointId } },
+ ]);
+ }).pipe(
+ Effect.provide(
+ makeLayer(
+ Effect.suspend(() => {
+ captures += 1;
+ return captures <= 2
+ ? Effect.interrupt
+ : captures === 3
+ ? Deferred.succeed(started, undefined).pipe(Effect.andThen(Effect.never))
+ : commitCapture("completed");
+ }),
+ ),
+ ),
+ );
+});
diff --git a/apps/server/src/orchestration-v2/RunFinalized.ts b/apps/server/src/orchestration-v2/RunFinalized.ts
new file mode 100644
index 0000000000000..c63292032030b
--- /dev/null
+++ b/apps/server/src/orchestration-v2/RunFinalized.ts
@@ -0,0 +1,88 @@
+import {
+ EventId,
+ type OrchestrationV2DomainEvent,
+ type OrchestrationV2Run,
+ type OrchestrationV2RunFinalizationOperation,
+ type OrchestrationV2RunFinalizedOutcome,
+ type RunId,
+} from "@t3tools/contracts";
+import type * as DateTime from "effect/DateTime";
+
+/**
+ * The id of a run's one finalization record, `run.finalized` or
+ * `run.finalization-failed`. The event log's unique event id keeps a run to
+ * one of them, and consumers can deduplicate deliveries by it.
+ */
+export const runFinalizedEventId = (runId: RunId) => EventId.make(`event:run-finalized:${runId}`);
+
+/**
+ * The checkpoint capture a finished run enqueues. RunFinalizationService
+ * records `run.finalized` once capture and refresh succeed, or
+ * `run.finalization-failed` in the same commit that gives up on the capture.
+ * Cancelling the capture records that failure too.
+ */
+export const checkpointCaptureEffectId = (runId: RunId) => `effect:checkpoint.capture:${runId}`;
+
+const SETTLED_RUN_STATUSES: ReadonlySet = new Set([
+ "completed",
+ "failed",
+ "interrupted",
+ "cancelled",
+ "rolled_back",
+]);
+
+/** Whether a persisted run status is final, including a discarded (rolled-back) run. */
+export const isSettledRunStatus = (status: string) => SETTLED_RUN_STATUSES.has(status);
+
+/** The finalized outcome for a run status, or null when the run is not finished or was discarded. */
+export const runFinalizedOutcome = (
+ status: OrchestrationV2Run["status"],
+): OrchestrationV2RunFinalizedOutcome | null =>
+ status === "completed" ||
+ status === "failed" ||
+ status === "interrupted" ||
+ status === "cancelled"
+ ? status
+ : null;
+
+/**
+ * The step a run's finalization stopped at when its capture was abandoned
+ * without reporting one: before the checkpoint commit or after it.
+ */
+export const abandonedOperation = (
+ run: OrchestrationV2Run,
+): OrchestrationV2RunFinalizationOperation =>
+ run.checkpointId === null ? "capture-checkpoint" : "refresh-workspace";
+
+const recordEnvelope = (run: OrchestrationV2Run, occurredAt: DateTime.Utc) => ({
+ id: runFinalizedEventId(run.id),
+ threadId: run.threadId,
+ runId: run.id,
+ ...(run.rootNodeId === null ? {} : { nodeId: run.rootNodeId }),
+ providerInstanceId: run.providerInstanceId,
+ occurredAt,
+});
+
+export const makeRunFinalizedEvent = (input: {
+ readonly run: OrchestrationV2Run;
+ readonly outcome: OrchestrationV2RunFinalizedOutcome;
+ readonly occurredAt: DateTime.Utc;
+}): Extract => ({
+ ...recordEnvelope(input.run, input.occurredAt),
+ type: "run.finalized",
+ payload: {
+ runId: input.run.id,
+ outcome: input.outcome,
+ checkpointId: input.run.checkpointId,
+ },
+});
+
+export const makeRunFinalizationFailedEvent = (input: {
+ readonly run: OrchestrationV2Run;
+ readonly operation: OrchestrationV2RunFinalizationOperation;
+ readonly occurredAt: DateTime.Utc;
+}): Extract => ({
+ ...recordEnvelope(input.run, input.occurredAt),
+ type: "run.finalization-failed",
+ payload: { runId: input.run.id, operation: input.operation },
+});
diff --git a/apps/server/src/orchestration-v2/RunMetrics.test.ts b/apps/server/src/orchestration-v2/RunMetrics.test.ts
index fead1c29a969e..aa07165f7c5bf 100644
--- a/apps/server/src/orchestration-v2/RunMetrics.test.ts
+++ b/apps/server/src/orchestration-v2/RunMetrics.test.ts
@@ -271,8 +271,20 @@ describe("EventSink run outcomes", () => {
yield* Fiber.join(terminal),
yield* Fiber.join(unrelated),
];
- assert.strictEqual(terminalEvents.length, 1);
- assert.strictEqual(unrelatedEvents.length, 1);
+ assert.deepEqual(
+ terminalEvents.map((stored) => stored.event.type),
+ ["run.updated", "run.finalized"],
+ );
+ assert.deepEqual(terminalEvents[0]?.event, runEvent("run.updated", "completed"));
+ assert.deepEqual(terminalEvents[1]?.event.payload, {
+ runId,
+ outcome: "completed",
+ checkpointId: null,
+ });
+ assert.deepEqual(
+ unrelatedEvents.map((stored) => stored.event.type),
+ ["thread.created"],
+ );
const counter = (yield* runSnapshots("p-sink")).find(
(snapshot) => snapshot.id === "t3_runs_total",
);
diff --git a/apps/server/src/orchestration-v2/runtimeLayer.test.ts b/apps/server/src/orchestration-v2/runtimeLayer.test.ts
index 8e1ca75fcac98..da5ebe62ff3d9 100644
--- a/apps/server/src/orchestration-v2/runtimeLayer.test.ts
+++ b/apps/server/src/orchestration-v2/runtimeLayer.test.ts
@@ -20,6 +20,7 @@ import {
type OrchestrationV2Run,
type OrchestrationV2RuntimeRequest,
ProjectId,
+ PluginInstallationId,
type PullRequestDetail,
type PullRequestComment,
PullRequestOperationError,
@@ -40,6 +41,8 @@ import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Path from "effect/Path";
import * as Queue from "effect/Queue";
+import * as Ref from "effect/Ref";
+import * as Exit from "effect/Exit";
import * as Stream from "effect/Stream";
import * as TestClock from "effect/testing/TestClock";
import * as SqlClient from "effect/sql/SqlClient";
@@ -53,6 +56,8 @@ import * as ProjectEnrichmentService from "../project/ProjectEnrichmentService.t
import * as ProjectService from "../project/ProjectService.ts";
import * as ServerSettings from "../serverSettings.ts";
import * as McpSessionRegistryTestkit from "../mcp/McpSessionRegistry.testkit.ts";
+import * as McpSessionRegistry from "../mcp/McpSessionRegistry.ts";
+import * as PluginTools from "../plugins/PluginTools.ts";
import * as ProviderInstanceRegistry from "../provider/ProviderInstanceRegistry.ts";
import type { ProviderInstance } from "@t3tools/provider-core/server/driver";
import * as VcsDriverRegistry from "../vcs/VcsDriverRegistry.ts";
@@ -273,25 +278,30 @@ const moveProject = (projectId: ProjectId, workspaceRoot: string, updatedAt: str
}),
);
-const layerTest = Layer.mergeAll(
- RuntimeLayer.layer,
- RuntimeLayer.layerEventSink,
- ProjectStore.layer,
- ProjectionStore.layer,
- EffectOutbox.layer,
- ThreadCommandExecutor.layer,
-).pipe(
- Layer.provide(McpSessionRegistryTestkit.layer),
- Layer.provide(McpProviderSessions.layer),
- Layer.provide(SqlitePersistence.layerMemory),
- Layer.provide(layerCheckpointStoreTest),
- Layer.provide(layerServerConfig),
- Layer.provide(ServerSettings.layerTest()),
- Layer.provide(layerTestProviderInstanceRegistry),
- Layer.provide(layerGitWorkflowTest),
- Layer.provide(layerProjectServiceTest),
- Layer.provide(layerPlatformTest),
-);
+const layerTestWithMcpRegistry = (
+ registryLayer: Layer.Layer,
+) =>
+ Layer.mergeAll(
+ RuntimeLayer.layer,
+ RuntimeLayer.layerEventSink,
+ ProjectStore.layer,
+ ProjectionStore.layer,
+ EffectOutbox.layer,
+ ThreadCommandExecutor.layer,
+ ).pipe(
+ Layer.provide(registryLayer),
+ Layer.provide(McpProviderSessions.layer),
+ Layer.provide(SqlitePersistence.layerMemory),
+ Layer.provide(layerCheckpointStoreTest),
+ Layer.provide(layerServerConfig),
+ Layer.provide(ServerSettings.layerTest()),
+ Layer.provide(layerTestProviderInstanceRegistry),
+ Layer.provide(layerGitWorkflowTest),
+ Layer.provide(layerProjectServiceTest),
+ Layer.provide(layerPlatformTest),
+ );
+
+const layerTest = layerTestWithMcpRegistry(McpSessionRegistryTestkit.layer);
const layerLegacyImportTest = RuntimeLayer.layer.pipe(
Layer.provide(McpSessionRegistryTestkit.layer),
@@ -8501,3 +8511,70 @@ it.layer(layerQueueResumeDisabledInstanceTest)(
);
},
);
+
+it.effect("runtime layers snapshot outer plugin tool grants into session credentials", () =>
+ Effect.gen(function* () {
+ const requests = yield* Ref.make>([]);
+ const grants = [
+ { installationId: PluginInstallationId.make("runtime-tool-plugin"), generation: 3 },
+ ];
+ const registryLayer = Layer.effect(
+ McpSessionRegistry.McpSessionRegistry,
+ Effect.gen(function* () {
+ const delegate = yield* McpSessionRegistry.McpSessionRegistry;
+ return McpSessionRegistry.McpSessionRegistry.of({
+ ...delegate,
+ issue: (request) =>
+ delegate
+ .issue(request)
+ .pipe(Effect.tap(() => Ref.update(requests, (current) => [...current, request]))),
+ });
+ }),
+ ).pipe(Layer.provide(McpSessionRegistryTestkit.layer));
+ yield* Effect.gen(function* () {
+ const orchestrator = yield* Orchestrator.OrchestratorV2;
+ const manager = yield* ProviderSessionManager.ProviderSessionManagerV2;
+ const threadId = ThreadId.make("runtime-plugin-grants-thread");
+ yield* orchestrator.dispatch({
+ type: "thread.create",
+ createdBy: "user",
+ creationSource: "web",
+ commandId: CommandId.make("runtime-plugin-grants-create"),
+ threadId,
+ projectId: ProjectId.make("runtime-plugin-grants-project"),
+ title: "Plugin grants",
+ modelSelection,
+ runtimeMode: "full-access",
+ interactionMode: "default",
+ branch: null,
+ worktreePath: process.cwd(),
+ });
+ // The lifecycle adapter deliberately refuses to open; credentials are issued before that boundary.
+ const opened = yield* manager
+ .open({
+ threadId,
+ providerSessionId: ProviderSessionId.make("runtime-plugin-grants-session"),
+ modelSelection,
+ runtimePolicy: {
+ runtimeMode: "full-access",
+ interactionMode: "default",
+ cwd: process.cwd(),
+ },
+ })
+ .pipe(Effect.exit);
+ assert.isTrue(Exit.isFailure(opened));
+ assert.deepEqual(
+ (yield* Ref.get(requests)).map((request) => request.pluginToolGrants),
+ [grants],
+ );
+ }).pipe(
+ Effect.provide(
+ layerTestWithMcpRegistry(registryLayer).pipe(
+ Layer.provideMerge(
+ Layer.mock(PluginTools.PluginTools)({ grants: Effect.succeed(grants) }),
+ ),
+ ),
+ ),
+ );
+ }),
+);
diff --git a/apps/server/src/orchestration-v2/runtimeLayer.ts b/apps/server/src/orchestration-v2/runtimeLayer.ts
index 1b54627595372..803d8b13aa674 100644
--- a/apps/server/src/orchestration-v2/runtimeLayer.ts
+++ b/apps/server/src/orchestration-v2/runtimeLayer.ts
@@ -207,7 +207,9 @@ const layerCheckpointCaptureServiceProvided = CheckpointCaptureService.layer.pip
),
);
const layerRunFinalizationServiceProvided = RunFinalizationService.layer.pipe(
- Layer.provide(Layer.merge(layerCheckpointCaptureServiceProvided, ProjectionStore.layer)),
+ Layer.provide(
+ Layer.mergeAll(layerCheckpointCaptureServiceProvided, layerEventSink, ProjectionStore.layer),
+ ),
);
const layerOrchestratorProvided = Orchestrator.layer.pipe(
diff --git a/apps/server/src/orchestration-v2/testkit/OrchestratorScenario.ts b/apps/server/src/orchestration-v2/testkit/OrchestratorScenario.ts
index 77e8bae8f085f..8a3b6a7f08df4 100644
--- a/apps/server/src/orchestration-v2/testkit/OrchestratorScenario.ts
+++ b/apps/server/src/orchestration-v2/testkit/OrchestratorScenario.ts
@@ -210,8 +210,18 @@ function scenarioCommands(scenario: OrchestratorV2Scenario): ReadonlyArray
- projection.runtimeRequests.find((request) => request.status === "pending");
+ projection.runtimeRequests.find(
+ (request) =>
+ request.status === "pending" &&
+ projection.turnItems.some(
+ (item) =>
+ (item.type === "approval_request" || item.type === "user_input_request") &&
+ item.requestId === request.id,
+ ),
+ );
const hasActiveRun = (projection: OrchestrationV2ThreadProjection) =>
projection.runs.some((run) =>
diff --git a/apps/server/src/orchestration-v2/testkit/ProviderReplayHarness.ts b/apps/server/src/orchestration-v2/testkit/ProviderReplayHarness.ts
index afd11a9ab7ecb..6402c10d4a983 100644
--- a/apps/server/src/orchestration-v2/testkit/ProviderReplayHarness.ts
+++ b/apps/server/src/orchestration-v2/testkit/ProviderReplayHarness.ts
@@ -444,7 +444,9 @@ export function layerWithRegistry(
),
);
const layerRunFinalizationServiceProvided = RunFinalizationService.layer.pipe(
- Layer.provide(Layer.merge(layerCheckpointCaptureServiceProvided, layerStores)),
+ Layer.provide(
+ Layer.mergeAll(layerCheckpointCaptureServiceProvided, layerEventSinkProvided, layerStores),
+ ),
);
const layerThreadTitleRegenerationTest = Layer.succeed(
ThreadTitleRegenerationService.ThreadTitleRegenerationService,
diff --git a/apps/server/src/persistence/Migrations.ts b/apps/server/src/persistence/Migrations.ts
index e13c2b449d9e7..a16b2973b8fa3 100644
--- a/apps/server/src/persistence/Migrations.ts
+++ b/apps/server/src/persistence/Migrations.ts
@@ -1,6 +1,7 @@
import * as Migrator from "effect/sql/Migrator";
import * as Effect from "effect/Effect";
import * as SqlClient from "effect/sql/SqlClient";
+import { reconcilePluginPreviewMigrations } from "./reconcilePluginPreviewMigrations.ts";
import { reconcileV2PreviewMigration } from "./reconcileV2PreviewMigration.ts";
import Migration0001 from "./Migrations/001_OrchestrationEvents.ts";
@@ -79,6 +80,9 @@ import Migration0073 from "./Migrations/073_ActiveTurnItemIndexes.ts";
import Migration0074 from "./Migrations/074_ExcludeAttachmentPlaceholdersFromSearch.ts";
import Migration0075 from "./Migrations/075_SubagentDeliveryState.ts";
import Migration0076 from "./Migrations/076_ProjectionProjectsPinArchive.ts";
+import Migration0077 from "./Migrations/077_PluginInstallations.ts";
+import Migration0078 from "./Migrations/078_PluginEventCursors.ts";
+import Migration0079 from "./Migrations/079_PluginSettings.ts";
const migrationEntries = [
[1, "OrchestrationEvents", Migration0001],
@@ -158,6 +162,9 @@ const migrationEntries = [
[74, "ExcludeAttachmentPlaceholdersFromSearch", Migration0074],
[75, "SubagentDeliveryState", Migration0075],
[76, "ProjectionProjectsPinArchive", Migration0076],
+ [77, "PluginInstallations", Migration0077],
+ [78, "PluginEventCursors", Migration0078],
+ [79, "PluginSettings", Migration0079],
] as const;
export const migrationManifest = migrationEntries.map(([id, name]) => [id, name] as const);
@@ -218,11 +225,15 @@ export const runMigrations = Effect.fn("runMigrations")(function* ({
const includesV2 =
toMigrationInclusive === undefined || toMigrationInclusive >= FIRST_V2_MIGRATION_ID;
const previewMigrations = includesV2 ? yield* reconcileV2PreviewMigration() : [];
+ const pluginMigrations = includesV2
+ ? yield* reconcilePluginPreviewMigrations(migrationManifest, toMigrationInclusive)
+ : [];
if (includesV2) {
yield* assertV2MigrationsCanRun(toMigrationInclusive);
}
const executedMigrations = [
...previewMigrations,
+ ...pluginMigrations,
...(yield* run({ loader: makeMigrationLoader(toMigrationInclusive) })),
];
const migrations = executedMigrations.map(([id, name]) => `${id}_${name}`);
diff --git a/apps/server/src/persistence/Migrations/077_PluginInstallations.ts b/apps/server/src/persistence/Migrations/077_PluginInstallations.ts
new file mode 100644
index 0000000000000..fc8e31c2cd87e
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/077_PluginInstallations.ts
@@ -0,0 +1,16 @@
+import * as Effect from "effect/Effect";
+import * as SqlClient from "effect/sql/SqlClient";
+
+export default Effect.gen(function* () {
+ const sql = yield* SqlClient.SqlClient;
+
+ // One row per plugin directory added to this environment. `record_json` holds the last
+ // inspection and the consent; the directory is unique so one folder is one installation.
+ yield* sql`
+ CREATE TABLE IF NOT EXISTS plugin_installations (
+ installation_id TEXT PRIMARY KEY,
+ directory TEXT NOT NULL UNIQUE,
+ record_json TEXT NOT NULL
+ )
+ `;
+});
diff --git a/apps/server/src/persistence/Migrations/078_PluginEventCursors.ts b/apps/server/src/persistence/Migrations/078_PluginEventCursors.ts
new file mode 100644
index 0000000000000..cf24e4b054559
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/078_PluginEventCursors.ts
@@ -0,0 +1,16 @@
+import * as Effect from "effect/Effect";
+import * as SqlClient from "effect/sql/SqlClient";
+
+export default Effect.gen(function* () {
+ const sql = yield* SqlClient.SqlClient;
+
+ // One row per plugin installation that receives events: the event log sequence it has
+ // acknowledged through. Removing the installation removes its row.
+ yield* sql`
+ CREATE TABLE IF NOT EXISTS plugin_event_cursors (
+ installation_id TEXT PRIMARY KEY,
+ acknowledged_sequence INTEGER NOT NULL,
+ updated_at TEXT NOT NULL
+ )
+ `;
+});
diff --git a/apps/server/src/persistence/Migrations/079_PluginSettings.ts b/apps/server/src/persistence/Migrations/079_PluginSettings.ts
new file mode 100644
index 0000000000000..0dde99c4fb122
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/079_PluginSettings.ts
@@ -0,0 +1,37 @@
+import * as Effect from "effect/Effect";
+import * as SqlClient from "effect/sql/SqlClient";
+
+export default Effect.gen(function* () {
+ const sql = yield* SqlClient.SqlClient;
+
+ // Saved plugin setting values per installation, secrets excepted.
+ yield* sql`
+ CREATE TABLE IF NOT EXISTS plugin_settings (
+ installation_id TEXT NOT NULL,
+ key TEXT NOT NULL,
+ value_json TEXT NOT NULL,
+ PRIMARY KEY (installation_id, key)
+ )
+ `;
+ // Secrets whose value may be in the server secret store. A row is written before its file and
+ // deleted after it, so cleanup can always find the file; `saved` is 1 once the value is complete
+ // and 0 while it is written or deleted.
+ yield* sql`
+ CREATE TABLE IF NOT EXISTS plugin_setting_secrets (
+ installation_id TEXT NOT NULL,
+ key TEXT NOT NULL,
+ saved INTEGER NOT NULL,
+ PRIMARY KEY (installation_id, key)
+ )
+ `;
+ // Each installation's private key-value storage; `bytes` is the value's encoded size for quotas.
+ yield* sql`
+ CREATE TABLE IF NOT EXISTS plugin_storage (
+ installation_id TEXT NOT NULL,
+ key TEXT NOT NULL,
+ value_json TEXT NOT NULL,
+ bytes INTEGER NOT NULL,
+ PRIMARY KEY (installation_id, key)
+ )
+ `;
+});
diff --git a/apps/server/src/persistence/reconcilePluginPreviewMigrations.test.ts b/apps/server/src/persistence/reconcilePluginPreviewMigrations.test.ts
new file mode 100644
index 0000000000000..c2544749db0b5
--- /dev/null
+++ b/apps/server/src/persistence/reconcilePluginPreviewMigrations.test.ts
@@ -0,0 +1,182 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as NodeSqliteClient from "@t3tools/shared/nodeSqliteClient";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Migrator from "effect/sql/Migrator";
+import * as SqlClient from "effect/sql/SqlClient";
+
+import { migrationManifest, runMigrations } from "./Migrations.ts";
+import PluginInstallations from "./Migrations/077_PluginInstallations.ts";
+import PluginEventCursors from "./Migrations/078_PluginEventCursors.ts";
+import PluginSettings from "./Migrations/079_PluginSettings.ts";
+
+const previews = [
+ [67, "PluginInstallations", PluginInstallations],
+ [68, "PluginEventCursors", PluginEventCursors],
+ [69, "PluginSettings", PluginSettings],
+] as const;
+const seed = (through: number, start = 67) =>
+ Effect.gen(function* () {
+ const sql = yield* SqlClient.SqlClient;
+ yield* runMigrations({ toMigrationInclusive: start - 1 });
+ yield* Migrator.make({})({
+ loader: Migrator.fromRecord(
+ Object.fromEntries(
+ previews
+ .filter(([id]) => start + id - 67 <= through)
+ .map(([id, name, migration]) => [`${start + id - 67}_${name}`, migration]),
+ ),
+ ),
+ });
+ yield* sql`INSERT INTO plugin_installations VALUES ('sentinel', '/plugins/sentinel', '{"consent":"retained"}')`;
+ if (through >= start + 1)
+ yield* sql`INSERT INTO plugin_event_cursors VALUES ('sentinel', 321, 'retained-time')`;
+ if (through >= start + 2) {
+ yield* sql`INSERT INTO plugin_settings VALUES ('sentinel', 'setting', '{"retained":true}')`;
+ yield* sql`INSERT INTO plugin_setting_secrets VALUES ('sentinel', 'secret', 1)`;
+ yield* sql`INSERT INTO plugin_storage VALUES ('sentinel', 'key', '{"retained":true}', 17)`;
+ }
+ yield* sql`UPDATE effect_sql_migrations SET created_at = '2026-10-01 00:00:00' WHERE migration_id >= ${start}`;
+ });
+const snapshot = Effect.gen(function* () {
+ const sql = yield* SqlClient.SqlClient;
+ const schema = yield* sql<{
+ readonly name: string;
+ readonly type: string;
+ readonly sql: string | null;
+ }>`SELECT name, type, sql FROM sqlite_master ORDER BY name`;
+ const data = [];
+ for (const row of schema) {
+ if (
+ row.type === "table" &&
+ (row.name.startsWith("plugin_") || row.name === "effect_sql_migrations")
+ )
+ data.push([row.name, yield* sql.unsafe(`SELECT * FROM "${row.name}" ORDER BY 1`)]);
+ }
+ return { schema, data };
+});
+const assertCurrent = Effect.gen(function* () {
+ const sql = yield* SqlClient.SqlClient;
+ assert.deepStrictEqual(
+ (yield* sql<{
+ readonly migration_id: number;
+ readonly name: string;
+ }>`SELECT migration_id, name FROM effect_sql_migrations ORDER BY migration_id`).map(
+ (row) => [row.migration_id, row.name] as const,
+ ),
+ migrationManifest,
+ );
+ assert.strictEqual(
+ (yield* sql`PRAGMA table_info(scheduled_tasks)`).some(
+ (row) => row.name === "last_run_webhook_delivery_id",
+ ),
+ true,
+ );
+ assert.strictEqual(
+ (yield* sql`SELECT name FROM sqlite_master WHERE name = 'orchestration_v2_projection_turn_items_stop_request_idx'`)
+ .length,
+ 1,
+ );
+});
+const memory = (test: Effect.Effect) =>
+ test.pipe(Effect.provide(NodeSqliteClient.layer({ filename: ":memory:" })));
+
+describe("plugin preview upgrade", () => {
+ it.effect.each([0, 68, 75, 76])("upgrades fresh/main %s with canonical migration ids", (main) =>
+ memory(
+ Effect.gen(function* () {
+ if (main) yield* runMigrations({ toMigrationInclusive: main });
+ yield* runMigrations();
+ yield* assertCurrent;
+ const before = yield* snapshot;
+ assert.deepStrictEqual(yield* runMigrations(), []);
+ assert.deepStrictEqual(yield* snapshot, before);
+ }),
+ ),
+ );
+ it.effect.each([
+ [67, 67],
+ [68, 67],
+ [69, 69],
+ [70, 69],
+ [69, 67],
+ [71, 69],
+ [76, 76],
+ [77, 76],
+ [78, 76],
+ ] as const)("preserves preview %s data and timestamps and is reentrant", ([through, start]) =>
+ memory(
+ Effect.gen(function* () {
+ const sql = yield* SqlClient.SqlClient;
+ yield* seed(through, start);
+ const before = (yield* snapshot).data.filter(([name]) => name !== "effect_sql_migrations");
+ yield* runMigrations();
+ yield* assertCurrent;
+ const after = yield* snapshot;
+ // A later canonical build can add tables, but existing rows stay byte-for-byte identical.
+ for (const table of before)
+ assert.deepStrictEqual(
+ after.data.find(([name]) => name === table[0]),
+ table,
+ );
+ assert.deepStrictEqual(
+ yield* sql`SELECT created_at FROM effect_sql_migrations WHERE migration_id BETWEEN 77 AND ${77 + through - start}`,
+ Array.from({ length: through - start + 1 }, () => ({
+ created_at: "2026-10-01 00:00:00",
+ })),
+ );
+ assert.deepStrictEqual(yield* runMigrations(), []);
+ assert.deepStrictEqual(yield* snapshot, after);
+ }),
+ ),
+ );
+ it.effect.each([
+ "unknown-history",
+ "unknown-schema",
+ "partial-upstream",
+ "partial-search",
+ "partial-project",
+ "partial-target",
+ ])("rejects %s unchanged", (variant) =>
+ memory(
+ Effect.gen(function* () {
+ const sql = yield* SqlClient.SqlClient;
+ yield* seed(67);
+ if (variant === "unknown-history")
+ yield* sql`INSERT INTO effect_sql_migrations (migration_id, name) VALUES (68, 'UnknownFork')`;
+ if (variant === "unknown-schema")
+ yield* sql`ALTER TABLE plugin_installations ADD COLUMN unknown TEXT`;
+ if (variant === "partial-upstream")
+ yield* sql`ALTER TABLE scheduled_tasks ADD COLUMN last_run_webhook_delivery_id TEXT`;
+ if (variant === "partial-search")
+ yield* sql`CREATE TABLE orchestration_v2_message_search (text TEXT)`;
+ if (variant === "partial-project")
+ yield* sql`ALTER TABLE projection_projects ADD COLUMN pinned_at TEXT`;
+ const before = yield* snapshot;
+ assert.ok(
+ Exit.isFailure(
+ yield* Effect.exit(
+ runMigrations(variant === "partial-target" ? { toMigrationInclusive: 75 } : {}),
+ ),
+ ),
+ );
+ assert.deepStrictEqual(yield* snapshot, before);
+ }),
+ ),
+ );
+ it.effect("rolls back ledger moves and upstream schema on SQL failure, then retries", () =>
+ memory(
+ Effect.gen(function* () {
+ const sql = yield* SqlClient.SqlClient;
+ yield* seed(67);
+ yield* sql`CREATE TRIGGER refuse_plugin_upgrade BEFORE INSERT ON effect_sql_migrations WHEN NEW.name = 'ShellStopRequestIndex' BEGIN SELECT RAISE(ABORT, 'injected failure'); END`;
+ const before = yield* snapshot;
+ assert.ok(Exit.isFailure(yield* Effect.exit(runMigrations())));
+ assert.deepStrictEqual(yield* snapshot, before);
+ yield* sql`DROP TRIGGER refuse_plugin_upgrade`;
+ yield* runMigrations();
+ yield* assertCurrent;
+ }),
+ ),
+ );
+});
diff --git a/apps/server/src/persistence/reconcilePluginPreviewMigrations.ts b/apps/server/src/persistence/reconcilePluginPreviewMigrations.ts
new file mode 100644
index 0000000000000..9c0cfe1ff08de
--- /dev/null
+++ b/apps/server/src/persistence/reconcilePluginPreviewMigrations.ts
@@ -0,0 +1,179 @@
+import * as Effect from "effect/Effect";
+import * as Migrator from "effect/sql/Migrator";
+import * as SqlClient from "effect/sql/SqlClient";
+
+import WebhookDedupe from "./Migrations/067_WebhookDedupe.ts";
+import ShellStopRequestIndex from "./Migrations/068_ShellStopRequestIndex.ts";
+import Migration69 from "./Migrations/069_ThreadMessageSearch.ts";
+import Migration70 from "./Migrations/070_PeerLinks.ts";
+import Migration71 from "./Migrations/071_PeerLinkFence.ts";
+import Migration72 from "./Migrations/072_WaitingLinkRequestIndex.ts";
+import Migration73 from "./Migrations/073_ActiveTurnItemIndexes.ts";
+import Migration74 from "./Migrations/074_ExcludeAttachmentPlaceholdersFromSearch.ts";
+import Migration75 from "./Migrations/075_SubagentDeliveryState.ts";
+import Migration76 from "./Migrations/076_ProjectionProjectsPinArchive.ts";
+
+// These unmerged preview builds used main's next slots. Recognize their exact
+// histories and schemas; never reinterpret an unknown build's migration ledger.
+const legacyNames = ["PluginInstallations", "PluginEventCursors", "PluginSettings"] as const;
+const legacySchemas = [
+ [
+ [
+ "plugin_installations",
+ "CREATE TABLE plugin_installations ( installation_id TEXT PRIMARY KEY, directory TEXT NOT NULL UNIQUE, record_json TEXT NOT NULL )",
+ ],
+ ],
+ [
+ [
+ "plugin_event_cursors",
+ "CREATE TABLE plugin_event_cursors ( installation_id TEXT PRIMARY KEY, acknowledged_sequence INTEGER NOT NULL, updated_at TEXT NOT NULL )",
+ ],
+ ],
+ [
+ [
+ "plugin_settings",
+ "CREATE TABLE plugin_settings ( installation_id TEXT NOT NULL, key TEXT NOT NULL, value_json TEXT NOT NULL, PRIMARY KEY (installation_id, key) )",
+ ],
+ [
+ "plugin_setting_secrets",
+ "CREATE TABLE plugin_setting_secrets ( installation_id TEXT NOT NULL, key TEXT NOT NULL, saved INTEGER NOT NULL, PRIMARY KEY (installation_id, key) )",
+ ],
+ [
+ "plugin_storage",
+ "CREATE TABLE plugin_storage ( installation_id TEXT NOT NULL, key TEXT NOT NULL, value_json TEXT NOT NULL, bytes INTEGER NOT NULL, PRIMARY KEY (installation_id, key) )",
+ ],
+ ],
+] as const;
+const upstream = [
+ [67, "WebhookDedupe", WebhookDedupe],
+ [68, "ShellStopRequestIndex", ShellStopRequestIndex],
+ [69, "ThreadMessageSearch", Migration69],
+ [70, "PeerLinks", Migration70],
+ [71, "PeerLinkFence", Migration71],
+ [72, "WaitingLinkRequestIndex", Migration72],
+ [73, "ActiveTurnItemIndexes", Migration73],
+ [74, "ExcludeAttachmentPlaceholdersFromSearch", Migration74],
+ [75, "SubagentDeliveryState", Migration75],
+ [76, "ProjectionProjectsPinArchive", Migration76],
+] as const;
+const normalize = (sql: string) => sql.trim().replace(/\s+/g, " ").toLowerCase();
+const badState = () =>
+ new Migrator.MigrationError({
+ kind: "BadState",
+ message: "Cannot upgrade an unknown or ambiguous plugin preview migration history/schema.",
+ });
+
+export const reconcilePluginPreviewMigrations = Effect.fn("reconcilePluginPreviewMigrations")(
+ function* (manifest: ReadonlyArray, throughId?: number) {
+ const sql = yield* SqlClient.SqlClient;
+ return yield* sql.withTransaction(
+ Effect.gen(function* () {
+ const exists =
+ yield* sql`SELECT name FROM sqlite_master WHERE name = 'effect_sql_migrations'`;
+ if (exists.length === 0) return [];
+ const history = yield* sql<{ readonly migration_id: number; readonly name: string }>`
+ SELECT migration_id, name FROM effect_sql_migrations ORDER BY migration_id
+ `;
+ const preview = history.find(
+ (row) => row.name === legacyNames[0] && [67, 69, 76].includes(row.migration_id),
+ );
+ if (!preview) return [];
+ const start = preview.migration_id;
+ const canonical = manifest.find(([, name]) => name === legacyNames[0])?.[0];
+ if (canonical === undefined) return yield* badState();
+ const tail = history.filter((row) => row.migration_id >= start);
+ const available = legacyNames.filter((name, offset) =>
+ manifest.some(([id, found]) => id === canonical + offset && found === name),
+ );
+ if (
+ tail.length === 0 ||
+ tail.length > available.length ||
+ tail.some(
+ (row, offset) => row.migration_id !== start + offset || row.name !== available[offset],
+ ) ||
+ (throughId !== undefined && throughId < canonical + tail.length - 1)
+ )
+ return yield* badState();
+ const earlier = history.filter((row) => row.migration_id < start);
+ const expected = manifest.filter(([id]) => id < start);
+ if (
+ earlier.length !== expected.length ||
+ earlier.some(
+ (row, offset) =>
+ row.migration_id !== expected[offset]?.[0] || row.name !== expected[offset]?.[1],
+ )
+ )
+ return yield* badState();
+ const schema = yield* sql<{
+ readonly name: string;
+ readonly tbl_name: string;
+ readonly sql: string | null;
+ }>`SELECT name, tbl_name, sql FROM sqlite_master`;
+ for (const [offset, tables] of legacySchemas.entries()) {
+ for (const [name, definition] of tables) {
+ const objects = schema.filter((row) => row.tbl_name === name && row.sql !== null);
+ if (offset < tail.length) {
+ if (
+ objects.length !== 1 ||
+ objects[0]?.name !== name ||
+ normalize(objects[0].sql!) !== normalize(definition)
+ )
+ return yield* badState();
+ } else if (objects.length !== 0) return yield* badState();
+ }
+ }
+ if (
+ start < 76 &&
+ schema.some((row) =>
+ [
+ "orchestration_v2_message_search",
+ "peer_environment_links",
+ "orchestration_v2_projection_turn_items_waiting_link_idx",
+ "orchestration_v2_projection_turn_items_active_ordinal_idx",
+ "orchestration_v2_projection_turn_items_active_run_idx",
+ "orchestration_v2_projection_subagents_settled_idx",
+ ].includes(row.name),
+ )
+ )
+ return yield* badState();
+ const subagentColumns = yield* sql<{
+ readonly name: string;
+ }>`PRAGMA table_info(orchestration_v2_projection_subagents)`;
+ if (start < 76 && subagentColumns.some((row) => row.name === "completion_delivery_state"))
+ return yield* badState();
+ const projectColumns = yield* sql<{
+ readonly name: string;
+ }>`PRAGMA table_info(projection_projects)`;
+ if (projectColumns.some((row) => row.name === "pinned_at" || row.name === "archived_at"))
+ return yield* badState();
+ const taskColumns = yield* sql<{
+ readonly name: string;
+ }>`PRAGMA table_info(scheduled_tasks)`;
+ if (
+ start === 67 &&
+ (taskColumns.some((row) => row.name === "last_run_webhook_delivery_id") ||
+ schema.some((row) =>
+ [
+ "scheduled_task_webhook_replay_keys",
+ "scheduled_task_webhook_pending",
+ "orchestration_v2_projection_turn_items_stop_request_idx",
+ ].includes(row.name),
+ ))
+ )
+ return yield* badState();
+ // Move the preview ledger before filling main's slots; the transaction preserves both on failure.
+ for (let offset = tail.length - 1; offset >= 0; offset--) {
+ yield* sql`UPDATE effect_sql_migrations SET migration_id = ${canonical + offset} WHERE migration_id = ${start + offset} AND name = ${legacyNames[offset]}`;
+ }
+ const executed: Array = [];
+ for (const [id, name, migration] of upstream) {
+ if (id < start) continue;
+ yield* migration;
+ yield* sql`INSERT INTO effect_sql_migrations (migration_id, name) VALUES (${id}, ${name})`;
+ executed.push([id, name]);
+ }
+ return executed;
+ }),
+ );
+ },
+);
diff --git a/apps/server/src/persistence/reconcileV2PreviewMigration.test.ts b/apps/server/src/persistence/reconcileV2PreviewMigration.test.ts
index 08c5094bf49c8..95c1b1059e9b0 100644
--- a/apps/server/src/persistence/reconcileV2PreviewMigration.test.ts
+++ b/apps/server/src/persistence/reconcileV2PreviewMigration.test.ts
@@ -56,6 +56,9 @@ describe("V2 preview upgrade", () => {
[74, "ExcludeAttachmentPlaceholdersFromSearch"],
[75, "SubagentDeliveryState"],
[76, "ProjectionProjectsPinArchive"],
+ [77, "PluginInstallations"],
+ [78, "PluginEventCursors"],
+ [79, "PluginSettings"],
]);
assert.deepStrictEqual(yield* runMigrations(), []);
assert.deepStrictEqual(yield* sql`SELECT * FROM orchestration_v2_legacy_imports`, imports);
@@ -155,6 +158,9 @@ describe("V2 preview upgrade", () => {
[74, "ExcludeAttachmentPlaceholdersFromSearch"],
[75, "SubagentDeliveryState"],
[76, "ProjectionProjectsPinArchive"],
+ [77, "PluginInstallations"],
+ [78, "PluginEventCursors"],
+ [79, "PluginSettings"],
]);
}).pipe(Effect.provide(NodeSqliteClient.layer({ filename: ":memory:" }))),
);
diff --git a/apps/server/src/plugins/PluginActions.test.ts b/apps/server/src/plugins/PluginActions.test.ts
new file mode 100644
index 0000000000000..94693dec3fa1c
--- /dev/null
+++ b/apps/server/src/plugins/PluginActions.test.ts
@@ -0,0 +1,489 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { describe, expect, it } from "@effect/vitest";
+import {
+ PLUGIN_ACTIONS_MAX_PER_ENVIRONMENT,
+ PLUGIN_ACTIONS_MAX_PER_PLUGIN,
+ PLUGIN_ACTIONS_SNAPSHOT_MAX_BYTES,
+ PluginActionId,
+ PluginActionInvokeInput,
+ PluginId,
+ PluginInstallationId,
+ ProjectId,
+ ThreadId,
+ type OrchestrationProjectShell,
+ type OrchestrationV2ThreadShell,
+ type PluginActionsSnapshot,
+ type PluginInstallation,
+} from "@t3tools/contracts";
+import * as HostProcess from "@t3tools/shared/HostProcess";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+
+import { ProjectStoreV2 } from "../orchestration-v2/ProjectStore.ts";
+import { ThreadManagementService } from "../orchestration-v2/ThreadManagementService.ts";
+import * as SqlitePersistence from "../persistence/Sqlite.ts";
+import * as PluginActions from "./PluginActions.ts";
+import * as PluginCatalog from "./PluginCatalog.ts";
+import { loadPluginDirectory } from "./PluginManifestLoader.ts";
+import * as PluginSupervisor from "./PluginSupervisor.ts";
+
+// Children run the real CLI entry, which routes `__plugin-host` to the child runtime.
+const BIN_PATH = `${import.meta.dirname}/../bin.ts`;
+const FIXTURE = `${import.meta.dirname}/testFixtures/actions`;
+
+const toJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown));
+const fromJson = Schema.decodeSync(
+ Schema.fromJsonString(Schema.Record(Schema.String, Schema.Unknown)),
+);
+
+const THREAD = ThreadId.make("thread-1");
+const PROJECT = ProjectId.make("project-1");
+
+/** One thread in one project; every other target does not exist. */
+const threadsAndProjects = Layer.merge(
+ Layer.mock(ThreadManagementService)({
+ getThreadShell: (threadId) =>
+ Effect.succeed(
+ threadId === THREAD
+ ? ({
+ projectId: PROJECT,
+ worktreePath: null,
+ branch: "main",
+ } as OrchestrationV2ThreadShell)
+ : null,
+ ),
+ }),
+ Layer.mock(ProjectStoreV2)({
+ getShell: (projectId) =>
+ Effect.succeed(
+ projectId === PROJECT
+ ? Option.some({ workspaceRoot: "/work/project" } as OrchestrationProjectShell)
+ : Option.none(),
+ ),
+ }),
+);
+
+const startActions = Effect.fn("startActions")(function* (scope: Scope.Scope) {
+ const supervisor = yield* PluginSupervisor.make({
+ heapLimitMb: 64,
+ activationTimeout: "10 seconds",
+ stopGrace: "1 second",
+ }).pipe(
+ Effect.provideService(HostProcess.Arguments, [process.execPath, BIN_PATH]),
+ Effect.provideService(Scope.Scope, scope),
+ );
+ const catalog = yield* PluginCatalog.make().pipe(
+ Effect.provideService(PluginSupervisor.PluginSupervisor, supervisor),
+ Effect.provideService(Scope.Scope, scope),
+ );
+ const actions = yield* PluginActions.make().pipe(
+ Effect.provideService(PluginCatalog.PluginCatalog, catalog),
+ Effect.provide(threadsAndProjects),
+ );
+ return { catalog, actions };
+});
+
+/** Copies the fixture (or a variant of its manifest) into a fresh directory. */
+const preparePlugin = Effect.fn("preparePlugin")(function* (
+ manifest?: (manifest: Record) => Record,
+) {
+ const fs = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const directory = path.join(
+ yield* fs.makeTempDirectoryScoped({ prefix: "t3-plugin-actions-" }),
+ "plugin",
+ );
+ yield* fs.makeDirectory(directory);
+ yield* fs.writeFileString(
+ path.join(directory, "main.mjs"),
+ yield* fs.readFileString(path.join(FIXTURE, "main.mjs")),
+ );
+ const original = fromJson(yield* fs.readFileString(path.join(FIXTURE, "t3-plugin.json")));
+ yield* fs.writeFileString(
+ path.join(directory, "t3-plugin.json"),
+ toJson(manifest ? manifest(original) : original),
+ );
+ return directory;
+});
+
+const enablePlugin = Effect.fn("enablePlugin")(function* (
+ catalog: PluginCatalog.PluginCatalog["Service"],
+ directory: string,
+) {
+ const { installation } = yield* catalog.add({ directory });
+ yield* catalog.consent({
+ installationId: installation.installationId,
+ digest: installation.source!.digest,
+ });
+ return (yield* catalog.enable({ installationId: installation.installationId })).installation;
+});
+
+const awaitActions = (
+ actions: PluginActions.PluginActions["Service"],
+ predicate: (snapshot: PluginActionsSnapshot) => boolean,
+) =>
+ actions.subscribe.pipe(
+ Stream.filter(predicate),
+ Stream.runHead,
+ Effect.map((snapshot) => Option.getOrThrow(snapshot).actions),
+ );
+
+const awaitHostState = (
+ catalog: PluginCatalog.PluginCatalog["Service"],
+ installationId: PluginInstallationId,
+ tags: ReadonlyArray,
+) =>
+ catalog.subscribe.pipe(
+ Stream.filter((snapshot) =>
+ snapshot.installations.some(
+ (installation) =>
+ installation.installationId === installationId &&
+ tags.includes(installation.hostState?._tag ?? ""),
+ ),
+ ),
+ Stream.runHead,
+ );
+
+const withDatabase = (effect: Effect.Effect) =>
+ effect.pipe(Effect.provide(SqlitePersistence.layerMemory));
+
+it.layer(NodeServices.layer)("PluginActions", (it) => {
+ it.effect(
+ "lists an enabled plugin's actions without starting it, and drops them on disable",
+ () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const { catalog, actions } = yield* startActions(yield* Scope.Scope);
+ const directory = yield* preparePlugin();
+ const installation = yield* enablePlugin(catalog, directory);
+ const { installationId } = installation;
+
+ const listed = yield* awaitActions(actions, (snapshot) => snapshot.actions.length > 0);
+ expect(listed.map((action) => [action.name, action.target, action.placements])).toEqual([
+ ["echo-target", "thread", ["command-palette", "thread-menu", "composer-slash"]],
+ ["say-hello", "environment", ["command-palette"]],
+ ["fail", "environment", ["command-palette"]],
+ ["wait", "environment", ["command-palette"]],
+ ]);
+ expect(listed[0]).toMatchObject({
+ pluginId: "test.actions",
+ pluginName: "Actions fixture",
+ title: "Echo target",
+ description: "Says which thread it ran on.",
+ });
+ // Listing read the manifest only: no process was started.
+ const [row] = (yield* catalog.list).installations;
+ expect(row?.hostState).toEqual({ _tag: "idle" });
+
+ const hello = listed.find((action) => action.name === "say-hello")!;
+ expect(
+ yield* actions.invoke({ actionId: hello.id, target: { _tag: "environment" } }),
+ ).toEqual({ message: "Hello from test.actions" });
+
+ yield* catalog.disable({ installationId });
+ expect(yield* awaitActions(actions, () => true)).toEqual([]);
+ const disabled = yield* actions
+ .invoke({ actionId: hello.id, target: { _tag: "environment" } })
+ .pipe(Effect.flip);
+ expect(disabled.reason).toBe("not-found");
+
+ // Enabled again: new ids, and the old one can never reach the new registration.
+ yield* catalog.enable({ installationId });
+ const relisted = yield* awaitActions(actions, (snapshot) => snapshot.actions.length > 0);
+ expect(relisted.find((action) => action.name === "say-hello")!.id).not.toBe(hello.id);
+ const stale = yield* actions
+ .invoke({ actionId: hello.id, target: { _tag: "environment" } })
+ .pipe(Effect.flip);
+ expect(stale.reason).toBe("stale");
+
+ yield* catalog.remove({ installationId });
+ expect(yield* awaitActions(actions, () => true)).toEqual([]);
+ }),
+ ),
+ );
+
+ it.effect("runs an action on its resolved target and reports typed failures", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const { catalog, actions } = yield* startActions(yield* Scope.Scope);
+ const { installationId } = yield* enablePlugin(catalog, yield* preparePlugin());
+ const listed = yield* awaitActions(actions, (snapshot) => snapshot.actions.length > 0);
+ const byName = (name: string) => listed.find((action) => action.name === name)!.id;
+
+ expect(
+ yield* actions.invoke({
+ actionId: byName("echo-target"),
+ target: { _tag: "thread", threadId: THREAD },
+ }),
+ ).toEqual({ message: "thread thread-1 in /work/project" });
+
+ const failures = yield* Effect.forEach(
+ [
+ { actionId: byName("echo-target"), target: { _tag: "environment" as const } },
+ {
+ actionId: byName("echo-target"),
+ target: { _tag: "thread" as const, threadId: ThreadId.make("elsewhere") },
+ },
+ { actionId: byName("fail"), target: { _tag: "environment" as const } },
+ {
+ actionId: PluginActionId.make(`${installationId}:1:missing`),
+ target: { _tag: "environment" as const },
+ },
+ {
+ actionId: PluginActionId.make("not-an-action"),
+ target: { _tag: "environment" as const },
+ },
+ ],
+ (input) => actions.invoke(input).pipe(Effect.flip),
+ );
+ expect(failures.map((error) => [error.reason, error.message])).toEqual([
+ ["target-mismatch", "Echo target runs on a thread."],
+ ["target-not-found", "That thread does not exist here."],
+ ["failed", "The fixture failed on purpose."],
+ ["not-found", "That action is not available now."],
+ ["not-found", "That action is not available here."],
+ ]);
+
+ // A disable while the action runs revokes it at once.
+ const running = yield* actions
+ .invoke({ actionId: byName("wait"), target: { _tag: "environment" } })
+ .pipe(Effect.flip, Effect.forkChild({ startImmediately: true }));
+ yield* awaitHostState(catalog, installationId, ["starting", "running"]);
+ yield* catalog.disable({ installationId });
+ expect((yield* Fiber.join(running)).reason).toBe("stopped");
+ }),
+ ),
+ );
+
+ it.effect("refuses malformed ids the wire accepts with a typed error, never a defect", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const { catalog, actions } = yield* startActions(yield* Scope.Scope);
+ const { installationId } = yield* enablePlugin(catalog, yield* preparePlugin());
+ const decode = Schema.decodeUnknownEffect(PluginActionInvokeInput);
+ const exits = yield* Effect.forEach(
+ [
+ ":1:go",
+ `${"x".repeat(65)}:1:go`,
+ "::",
+ `${installationId}::say-hello`,
+ `${installationId}:1.0:say-hello`,
+ `${installationId}:99999999999999999999:say-hello`,
+ `${installationId} :1:say-hello`,
+ ],
+ (actionId) =>
+ decode({ actionId, target: { _tag: "environment" } }).pipe(
+ Effect.flatMap((input) => actions.invoke(input).pipe(Effect.exit)),
+ ),
+ );
+ for (const exit of exits) {
+ expect(Exit.isFailure(exit) && !Cause.hasDies(exit.cause)).toBe(true);
+ if (Exit.isFailure(exit)) {
+ expect(Cause.squash(exit.cause)).toMatchObject({
+ _tag: "PluginActionError",
+ reason: "not-found",
+ });
+ }
+ }
+ }),
+ ),
+ );
+
+ it.effect("offers plugins whole up to the environment bound and runs only those", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const { catalog, actions } = yield* startActions(yield* Scope.Scope);
+ const pluginCount = PLUGIN_ACTIONS_MAX_PER_ENVIRONMENT / PLUGIN_ACTIONS_MAX_PER_PLUGIN + 1;
+ const installations = yield* Effect.forEach(
+ Array.from({ length: pluginCount }, (_, index) => index),
+ (index) =>
+ preparePlugin((manifest) => ({
+ ...manifest,
+ id: `test.actions-${index}`,
+ actions: Array.from({ length: PLUGIN_ACTIONS_MAX_PER_PLUGIN }, (_, action) => ({
+ name: `go-${action}`,
+ title: `Go ${action}`,
+ target: "environment",
+ placements: ["command-palette"],
+ })),
+ })).pipe(Effect.flatMap((directory) => enablePlugin(catalog, directory))),
+ );
+ const full = yield* actions.subscribe.pipe(
+ Stream.filter((snapshot) => snapshot.omitted !== undefined),
+ Stream.runHead,
+ Effect.map(Option.getOrThrow),
+ );
+ expect(full.actions).toHaveLength(PLUGIN_ACTIONS_MAX_PER_ENVIRONMENT);
+ expect(full.omitted).toEqual({ plugins: 1, actions: PLUGIN_ACTIONS_MAX_PER_PLUGIN });
+ const listedIds = new Set(full.actions.map((action) => action.id.split(":")[0]));
+ const left = installations.find(
+ (installation) => !listedIds.has(installation.installationId),
+ )!;
+
+ const refused = yield* actions
+ .invoke({
+ actionId: PluginActionId.make(`${left.installationId}:${left.generation}:go-0`),
+ target: { _tag: "environment" },
+ })
+ .pipe(Effect.flip);
+ expect(refused.reason).toBe("not-found");
+ expect(refused.message).toContain("more actions than it shows");
+
+ // Disabling a listed plugin makes room, and the left-out one is offered whole.
+ const listed = installations.find((installation) => installation !== left)!;
+ yield* catalog.disable({ installationId: listed.installationId });
+ const after = yield* awaitActions(actions, (snapshot) => snapshot.omitted === undefined);
+ expect(after).toHaveLength(PLUGIN_ACTIONS_MAX_PER_ENVIRONMENT);
+ expect(
+ after.filter((action) => action.id.startsWith(`${left.installationId}:`)),
+ ).toHaveLength(PLUGIN_ACTIONS_MAX_PER_PLUGIN);
+ }),
+ ),
+ );
+
+ it.effect("refuses declarations the host cannot honour", () =>
+ Effect.gen(function* () {
+ const reasons = yield* Effect.forEach(
+ [
+ (manifest: Record) => ({ ...manifest, capabilities: [] }),
+ (manifest: Record) => ({ ...manifest, proposedApi: false }),
+ (manifest: Record) => ({
+ ...manifest,
+ actions: [
+ { name: "same", title: "One", target: "environment", placements: ["thread-menu"] },
+ { name: "same", title: "Two", target: "environment", placements: ["thread-menu"] },
+ ],
+ }),
+ (manifest: Record) => ({
+ ...manifest,
+ actions: [
+ {
+ name: "twice",
+ title: "Twice",
+ target: "environment",
+ placements: ["thread-menu", "thread-menu"],
+ },
+ ],
+ }),
+ ],
+ (variant) =>
+ preparePlugin(variant).pipe(
+ Effect.flatMap(loadPluginDirectory),
+ Effect.flip,
+ Effect.map((error) => error.reason),
+ ),
+ );
+ expect(reasons).toEqual([
+ "it declares actions without the actions capability.",
+ "it declares actions, which need proposedApi: true.",
+ "it declares the action same twice.",
+ "the action twice repeats a placement.",
+ ]);
+ }),
+ );
+});
+
+describe("pluginActionsFromCatalog", () => {
+ const digest = `sha256:${"a".repeat(64)}`;
+ const installation: PluginInstallation = {
+ installationId: PluginInstallationId.make("installation-1"),
+ generation: 3,
+ directory: "/srv/plugins/actions",
+ manifest: {
+ id: PluginId.make("test.actions"),
+ name: "Actions",
+ version: "1.0.0",
+ capabilities: ["actions"],
+ proposedApi: true,
+ actions: [{ name: "go", title: "Go", target: "environment", placements: ["thread-menu"] }],
+ },
+ source: { digest, files: 2, bytes: 10 },
+ problem: null,
+ inspectedAt: "2026-10-04T00:00:00.000Z",
+ consent: { digest, capabilities: ["actions"], grantedAt: "2026-10-04T00:00:00.000Z" },
+ enabled: true,
+ hostState: { _tag: "running" },
+ addedAt: "2026-10-04T00:00:00.000Z",
+ };
+ const names = (installations: ReadonlyArray) =>
+ PluginActions.pluginActionsFromCatalog({ installations }).actions.map((action) => action.id);
+
+ const many = (count: number, description?: string) =>
+ Array.from({ length: count }, (_, index): PluginInstallation => {
+ const installationId = PluginInstallationId.make(`installation-${index}`);
+ return {
+ ...installation,
+ installationId,
+ manifest: {
+ ...installation.manifest!,
+ id: PluginId.make(`test.actions-${index}`),
+ actions: Array.from({ length: PLUGIN_ACTIONS_MAX_PER_PLUGIN }, (_, action) => ({
+ name: `go-${action}`,
+ title: `Go ${action}`,
+ ...(description === undefined ? {} : { description }),
+ target: "environment" as const,
+ placements: ["command-palette" as const],
+ })),
+ },
+ };
+ });
+ const frameBytes = (snapshot: PluginActionsSnapshot) =>
+ Buffer.byteLength(JSON.stringify(snapshot));
+
+ it("bounds the actions and bytes one environment offers, counting what it leaves out", () => {
+ const byCount = PluginActions.pluginActionsFromCatalog({ installations: many(1000) });
+ expect(byCount.actions).toHaveLength(PLUGIN_ACTIONS_MAX_PER_ENVIRONMENT);
+ const keptPlugins = PLUGIN_ACTIONS_MAX_PER_ENVIRONMENT / PLUGIN_ACTIONS_MAX_PER_PLUGIN;
+ expect(byCount.omitted).toEqual({
+ plugins: 1000 - keptPlugins,
+ actions: (1000 - keptPlugins) * PLUGIN_ACTIONS_MAX_PER_PLUGIN,
+ });
+ // The first plugins in catalogue order are the ones kept.
+ expect(new Set(byCount.actions.map((action) => action.id.split(":")[0]))).toEqual(
+ new Set(Array.from({ length: keptPlugins }, (_, index) => `installation-${index}`)),
+ );
+ expect(frameBytes(byCount)).toBeLessThanOrEqual(PLUGIN_ACTIONS_SNAPSHOT_MAX_BYTES);
+
+ // Escaped control characters make each description six times its length on the wire.
+ const byBytes = PluginActions.pluginActionsFromCatalog({
+ installations: many(1000, "\u0001".repeat(240)),
+ });
+ expect(byBytes.actions.length).toBeLessThan(PLUGIN_ACTIONS_MAX_PER_ENVIRONMENT);
+ expect(byBytes.actions.length % PLUGIN_ACTIONS_MAX_PER_PLUGIN).toBe(0);
+ expect(byBytes.omitted?.actions).toBe(
+ 1000 * PLUGIN_ACTIONS_MAX_PER_PLUGIN - byBytes.actions.length,
+ );
+ expect(frameBytes(byBytes)).toBeLessThanOrEqual(PLUGIN_ACTIONS_SNAPSHOT_MAX_BYTES);
+
+ // Within the bounds nothing is left out and `omitted` is absent.
+ expect(
+ PluginActions.pluginActionsFromCatalog({ installations: many(keptPlugins) }),
+ ).not.toHaveProperty("omitted");
+ });
+
+ it("offers only actions that can run now", () => {
+ expect(names([installation])).toEqual(["installation-1:3:go"]);
+ // A state this server version does not know is unknown, not a reason to hide the action.
+ const { hostState: _hostState, ...unknownState } = installation;
+ expect(names([unknownState])).toEqual(["installation-1:3:go"]);
+ for (const hidden of [
+ { ...installation, enabled: false },
+ { ...installation, consent: null },
+ { ...installation, source: null, problem: "gone" },
+ { ...installation, hostState: { _tag: "quarantined" as const, failures: 3, reason: "x" } },
+ { ...installation, hostState: { _tag: "incompatible" as const, reason: "x" } },
+ { ...installation, manifest: { ...installation.manifest!, capabilities: [] } },
+ ]) {
+ expect(names([hidden])).toEqual([]);
+ }
+ });
+});
diff --git a/apps/server/src/plugins/PluginActions.ts b/apps/server/src/plugins/PluginActions.ts
new file mode 100644
index 0000000000000..c96befa8311e5
--- /dev/null
+++ b/apps/server/src/plugins/PluginActions.ts
@@ -0,0 +1,294 @@
+// Ids pin registration generations; stale or omitted actions must never reach a replacement.
+// Listing starts no plugin, and caller interruption cancels the invoked handler.
+import {
+ PLUGIN_ACTION_MESSAGE_MAX_LENGTH,
+ PLUGIN_ACTIONS_MAX_PER_ENVIRONMENT,
+ PLUGIN_ACTIONS_MAX_PER_PLUGIN,
+ PLUGIN_ACTIONS_SNAPSHOT_MAX_BYTES,
+ PluginActionError,
+ PluginActionId,
+ PluginInstallationId,
+ pluginInstallationStatus,
+ type PluginAction,
+ type PluginActionInvokeInput,
+ type PluginActionInvokeResult,
+ type PluginActionsSnapshot,
+ type PluginActionTarget,
+ type PluginCatalogError,
+ type PluginCatalogSnapshot,
+ type PluginInstallation,
+ type ProjectId,
+ type ThreadId,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import type * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+
+import { ProjectStoreV2 } from "../orchestration-v2/ProjectStore.ts";
+import { ThreadManagementService } from "../orchestration-v2/ThreadManagementService.ts";
+import { PluginCatalog } from "./PluginCatalog.ts";
+import type { PluginInvokeError } from "./PluginSupervisor.ts";
+
+const PLUGIN_ACTION_TIMEOUT: Duration.Input = "30 seconds";
+
+/** What an action handler receives as `input.target`: the target the user picked, resolved. */
+type PluginActionTargetContext =
+ | { readonly kind: "environment" }
+ | { readonly kind: "project"; readonly projectId: string; readonly workspaceRoot: string }
+ | {
+ readonly kind: "thread";
+ readonly threadId: string;
+ readonly projectId: string;
+ /** The thread's worktree, or its project's workspace root. */
+ readonly cwd: string;
+ readonly branch: string | null;
+ };
+
+/** Looks a target up in this environment's projects and threads; none when it does not exist here. */
+const resolvePluginActionTargetFrom =
+ (lookups: {
+ readonly getThreadShell: (threadId: ThreadId) => Effect.Effect<
+ {
+ readonly projectId: ProjectId;
+ readonly worktreePath: string | null;
+ readonly branch: string | null;
+ } | null,
+ ThreadError
+ >;
+ readonly getProjectShell: (
+ projectId: ProjectId,
+ ) => Effect.Effect, ProjectError>;
+ }) =>
+ (
+ target: PluginActionTarget,
+ ): Effect.Effect, PluginActionError> =>
+ Effect.gen(function* () {
+ switch (target._tag) {
+ case "environment":
+ return Option.some({ kind: "environment" as const });
+ case "project": {
+ const project = yield* lookups.getProjectShell(target.projectId);
+ return Option.map(project, (shell) => ({
+ kind: "project" as const,
+ projectId: target.projectId,
+ workspaceRoot: shell.workspaceRoot,
+ }));
+ }
+ case "thread": {
+ const thread = yield* lookups.getThreadShell(target.threadId);
+ if (thread === null) return Option.none();
+ const project = yield* lookups.getProjectShell(thread.projectId);
+ if (Option.isNone(project)) return Option.none();
+ return Option.some({
+ kind: "thread" as const,
+ threadId: target.threadId,
+ projectId: thread.projectId,
+ cwd: thread.worktreePath ?? project.value.workspaceRoot,
+ branch: thread.branch,
+ });
+ }
+ }
+ }).pipe(
+ Effect.mapError(() => actionError("unavailable", "Could not look up the action's target.")),
+ );
+
+export class PluginActions extends Context.Service<
+ PluginActions,
+ {
+ /** The current actions now, then a new list whenever it changes. */
+ readonly subscribe: Stream.Stream;
+ readonly invoke: (
+ input: PluginActionInvokeInput,
+ ) => Effect.Effect;
+ }
+>()("t3/plugins/PluginActions") {}
+
+const pluginActionHandlerName = (name: string) => `action:${name}`;
+
+const actionId = (installationId: string, generation: number, name: string) =>
+ PluginActionId.make(`${installationId}:${generation}:${name}`);
+
+const decodeInstallationId = Schema.decodeUnknownOption(PluginInstallationId);
+
+/** The parts of an id this server issued; undefined for anything else. */
+const parseActionId = (id: PluginActionId) => {
+ const parts = id.split(":");
+ const name = parts.pop();
+ const generationText = parts.pop();
+ if (name === undefined || generationText === undefined || !/^[0-9]+$/.test(generationText))
+ return undefined;
+ const generation = Number(generationText);
+ if (!Number.isSafeInteger(generation)) return undefined;
+ const segment = parts.join(":");
+ const installationId = decodeInstallationId(segment);
+ if (Option.isNone(installationId) || installationId.value !== segment) return undefined;
+ return { installationId: installationId.value, generation, name };
+};
+
+/** The actions one installation offers on its own: enabled and able to run now. */
+const installationActions = (installation: PluginInstallation): ReadonlyArray => {
+ const { manifest } = installation;
+ if (manifest === null || pluginInstallationStatus(installation) !== "enabled") return [];
+ if (!manifest.capabilities.includes("actions")) return [];
+ // These wait for someone to resume them; an action could only fail.
+ const state = installation.hostState?._tag;
+ if (state === "quarantined" || state === "incompatible") return [];
+ return (manifest.actions ?? []).slice(0, PLUGIN_ACTIONS_MAX_PER_PLUGIN).map((declaration) => ({
+ id: actionId(installation.installationId, installation.generation, declaration.name),
+ pluginId: manifest.id,
+ pluginName: manifest.name,
+ name: declaration.name,
+ title: declaration.title,
+ ...(declaration.description === undefined ? {} : { description: declaration.description }),
+ target: declaration.target,
+ placements: declaration.placements,
+ }));
+};
+
+// Room for the frame around the actions: `{"actions":[`, `]`, and `omitted`.
+const SNAPSHOT_ENVELOPE_BYTES = 128;
+const ACTIONS_MAX_BYTES = PLUGIN_ACTIONS_SNAPSHOT_MAX_BYTES - SNAPSHOT_ENVELOPE_BYTES;
+
+/** Each action's JSON plus its separator. */
+const encodedBytes = (actions: ReadonlyArray) =>
+ actions.reduce((total, action) => total + Buffer.byteLength(JSON.stringify(action)) + 1, 0);
+
+/**
+ * The actions a catalogue snapshot offers. Plugins are taken whole, in
+ * catalogue order, until one would pass the environment's action or byte
+ * bound; it and every later plugin are counted in `omitted` instead.
+ */
+export const pluginActionsFromCatalog = (
+ snapshot: PluginCatalogSnapshot,
+): PluginActionsSnapshot => {
+ const actions: Array = [];
+ let bytes = 0;
+ const omitted = { plugins: 0, actions: 0 };
+ for (const installation of snapshot.installations) {
+ const offered = installationActions(installation);
+ if (offered.length === 0) continue;
+ if (omitted.plugins === 0) {
+ const size = encodedBytes(offered);
+ if (
+ actions.length + offered.length <= PLUGIN_ACTIONS_MAX_PER_ENVIRONMENT &&
+ bytes + size <= ACTIONS_MAX_BYTES
+ ) {
+ actions.push(...offered);
+ bytes += size;
+ continue;
+ }
+ }
+ omitted.plugins += 1;
+ omitted.actions += offered.length;
+ }
+ return omitted.plugins === 0 ? { actions } : { actions, omitted };
+};
+
+const actionError = (reason: string, message: string) =>
+ new PluginActionError({ reason, message: bound(message) });
+
+/** At most the message bound, without splitting a surrogate pair. */
+const bound = (text: string) => {
+ const characters = Array.from(text);
+ return characters.length <= PLUGIN_ACTION_MESSAGE_MAX_LENGTH
+ ? text
+ : `${characters.slice(0, PLUGIN_ACTION_MESSAGE_MAX_LENGTH - 1).join("")}…`;
+};
+
+/** A plugin's `{ message }`, if it returned one. */
+const resultMessage = (value: Schema.Json): string | null => {
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+ const message = (value as { readonly [key: string]: Schema.Json })["message"];
+ if (typeof message !== "string" || message.trim() === "") return null;
+ return bound(message.trim());
+};
+
+const fromInvokeError = (
+ error: PluginCatalogError | PluginInvokeError,
+ title: string,
+): PluginActionError => {
+ switch (error._tag) {
+ case "PluginCatalogError":
+ return error.reason === "generation-changed"
+ ? actionError("stale", "The plugin was enabled again since this action was listed.")
+ : error.reason === "not-found"
+ ? actionError("not-found", "That plugin is no longer installed.")
+ : actionError("unavailable", error.message);
+ case "PluginTimeoutError":
+ return actionError("timeout", `${title} did not finish in time.`);
+ case "PluginBusyError":
+ return actionError("busy", `${title} could not start: the plugin is busy.`);
+ case "PluginStoppedError":
+ return actionError("stopped", "The plugin was disabled while the action ran.");
+ case "PluginCallFailedError":
+ return actionError("failed", error.reason);
+ default:
+ return actionError("unavailable", error.message);
+ }
+};
+
+export const make = Effect.fn("PluginActions.make")(function* () {
+ const catalog = yield* PluginCatalog;
+ const threads = yield* ThreadManagementService;
+ const projects = yield* ProjectStoreV2;
+ const resolveTarget = resolvePluginActionTargetFrom({
+ getThreadShell: threads.getThreadShell,
+ getProjectShell: projects.getShell,
+ });
+
+ const invoke = Effect.fn("PluginActions.invoke")(function* (input: PluginActionInvokeInput) {
+ const parsed = parseActionId(input.actionId);
+ if (parsed === undefined)
+ return yield* actionError("not-found", "That action is not available here.");
+ const snapshot = yield* catalog.list;
+ const installation = snapshot.installations.find(
+ (candidate) => candidate.installationId === parsed.installationId,
+ );
+ if (installation === undefined)
+ return yield* actionError("not-found", "That plugin is no longer installed.");
+ if (installation.generation !== parsed.generation)
+ return yield* actionError(
+ "stale",
+ "The plugin was enabled again since this action was listed.",
+ );
+ // Only what the list offers runs, so an action left out by the bounds cannot.
+ const action = pluginActionsFromCatalog(snapshot).actions.find(
+ (candidate) => candidate.id === input.actionId,
+ );
+ if (action === undefined)
+ return yield* installationActions(installation).some(
+ (candidate) => candidate.name === parsed.name,
+ )
+ ? actionError(
+ "not-found",
+ "That action is not offered: this environment's plugins declare more actions than it shows.",
+ )
+ : actionError("not-found", "That action is not available now.");
+ if (action.target !== input.target._tag)
+ return yield* actionError("target-mismatch", `${action.title} runs on a ${action.target}.`);
+ const target = yield* resolveTarget(input.target);
+ if (Option.isNone(target))
+ return yield* actionError("target-not-found", `That ${action.target} does not exist here.`);
+ const value = yield* catalog
+ .invoke(
+ installation.installationId,
+ pluginActionHandlerName(action.name),
+ { action: action.name, target: target.value },
+ { generation: parsed.generation, timeout: PLUGIN_ACTION_TIMEOUT },
+ )
+ .pipe(Effect.mapError((error) => fromInvokeError(error, action.title)));
+ return { message: resultMessage(value) };
+ });
+
+ return PluginActions.of({
+ // Process state changes reach the catalogue too; most leave the list as it was.
+ subscribe: catalog.subscribe.pipe(Stream.map(pluginActionsFromCatalog), Stream.changes),
+ invoke,
+ });
+});
+
+export const layer = Layer.effect(PluginActions, make());
diff --git a/apps/server/src/plugins/PluginActionsRpc.test.ts b/apps/server/src/plugins/PluginActionsRpc.test.ts
new file mode 100644
index 0000000000000..335d9a3eb5c54
--- /dev/null
+++ b/apps/server/src/plugins/PluginActionsRpc.test.ts
@@ -0,0 +1,120 @@
+import {
+ type AuthEnvironmentScope,
+ AuthOrchestrationOperateScope,
+ AuthOrchestrationReadScope,
+ AuthRelayReadScope,
+ AuthStandardClientScopes,
+ PluginActionId,
+ type PluginActionsSnapshot,
+ WS_METHODS,
+ WsRpcGroup,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Stream from "effect/Stream";
+import * as RpcTest from "effect/rpc/RpcTest";
+
+import { RPC_REQUIRED_SCOPES } from "../auth/RpcAuthorization.ts";
+import * as RpcAuthorization from "../auth/RpcAuthorization.ts";
+
+type ActionMethod =
+ | typeof WS_METHODS.pluginActionsSubscribe
+ | typeof WS_METHODS.pluginActionsInvoke;
+const actionMethods: ReadonlySet = new Set([
+ WS_METHODS.pluginActionsSubscribe,
+ WS_METHODS.pluginActionsInvoke,
+]);
+
+const group = WsRpcGroup.omit(
+ ...[...WsRpcGroup.requests.keys()].filter(
+ (tag): tag is Exclude =>
+ !actionMethods.has(tag),
+ ),
+);
+
+const actionId = PluginActionId.make("installation-1:1:say-hello");
+const snapshot: PluginActionsSnapshot = {
+ actions: [
+ {
+ id: actionId,
+ pluginId: "test.actions",
+ pluginName: "Actions fixture",
+ name: "say-hello",
+ title: "Say hello",
+ target: "environment",
+ placements: ["command-palette"],
+ },
+ ],
+};
+const invoke = { actionId, target: { _tag: "environment" as const } };
+
+/** Serves the action RPCs through the real scope middleware; handlers record that they ran. */
+const makeClient = (scopes: ReadonlyArray, handled: Array) =>
+ RpcTest.makeClient(group).pipe(
+ Effect.provide(
+ Layer.mergeAll(
+ group.toLayerHandler(WS_METHODS.pluginActionsSubscribe, () =>
+ Stream.fromEffect(
+ Effect.sync(() => handled.push(WS_METHODS.pluginActionsSubscribe)).pipe(
+ Effect.as(snapshot),
+ ),
+ ),
+ ),
+ group.toLayerHandler(WS_METHODS.pluginActionsInvoke, () =>
+ Effect.sync(() => handled.push(WS_METHODS.pluginActionsInvoke)).pipe(
+ Effect.as({ message: "Hello" }),
+ ),
+ ),
+ RpcAuthorization.layer(scopes),
+ ),
+ ),
+ );
+
+describe("plugin action RPC scopes", () => {
+ it.effect("lets a standard pairing list and run the actions an administrator enabled", () =>
+ Effect.gen(function* () {
+ const handled: Array = [];
+ const client = yield* makeClient(AuthStandardClientScopes, handled);
+
+ expect(
+ yield* client[WS_METHODS.pluginActionsSubscribe]({}).pipe(
+ Stream.take(1),
+ Stream.runCollect,
+ ),
+ ).toEqual([snapshot]);
+ expect(yield* client[WS_METHODS.pluginActionsInvoke](invoke)).toEqual({ message: "Hello" });
+ expect(handled).toEqual([WS_METHODS.pluginActionsSubscribe, WS_METHODS.pluginActionsInvoke]);
+ }).pipe(Effect.scoped),
+ );
+
+ it.effect("refuses to run an action for a read-only session", () =>
+ Effect.gen(function* () {
+ const handled: Array = [];
+ const client = yield* makeClient([AuthOrchestrationReadScope], handled);
+
+ expect(yield* client[WS_METHODS.pluginActionsInvoke](invoke).pipe(Effect.flip)).toMatchObject(
+ {
+ _tag: "EnvironmentAuthorizationError",
+ requiredScope: AuthOrchestrationOperateScope,
+ },
+ );
+ expect(handled).toEqual([]);
+ }).pipe(Effect.scoped),
+ );
+
+ it.effect("refuses the list without the orchestration read scope", () =>
+ Effect.gen(function* () {
+ const handled: Array = [];
+ const client = yield* makeClient([AuthRelayReadScope], handled);
+
+ expect(
+ yield* client[WS_METHODS.pluginActionsSubscribe]({}).pipe(Stream.runCollect, Effect.flip),
+ ).toMatchObject({
+ _tag: "EnvironmentAuthorizationError",
+ requiredScope: AuthOrchestrationReadScope,
+ });
+ expect(handled).toEqual([]);
+ }).pipe(Effect.scoped),
+ );
+});
diff --git a/apps/server/src/plugins/PluginCatalog.test.ts b/apps/server/src/plugins/PluginCatalog.test.ts
new file mode 100644
index 0000000000000..5a1fee181e166
--- /dev/null
+++ b/apps/server/src/plugins/PluginCatalog.test.ts
@@ -0,0 +1,958 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { describe, expect, it } from "@effect/vitest";
+import {
+ EnvironmentId,
+ ThreadId,
+ PluginInstallationId,
+ pluginInstallationStatus,
+ type PluginId,
+ type PluginInstallation,
+} from "@t3tools/contracts";
+import * as HostProcess from "@t3tools/shared/HostProcess";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as PubSub from "effect/PubSub";
+import * as Queue from "effect/Queue";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import * as SqlClient from "effect/sql/SqlClient";
+
+import * as SqlitePersistence from "../persistence/Sqlite.ts";
+import * as PluginCatalog from "./PluginCatalog.ts";
+import type { PluginRegistration } from "./PluginManifestLoader.ts";
+import * as PluginSupervisor from "./PluginSupervisor.ts";
+import * as PluginTools from "./PluginTools.ts";
+
+// Children run the real CLI entry, which routes `__plugin-host` to the child runtime.
+const BIN_PATH = `${import.meta.dirname}/../bin.ts`;
+
+type Catalog = PluginCatalog.PluginCatalog["Service"];
+
+const toJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown));
+
+/** Starts a catalogue and its supervisor in `scope`, as one server start would. */
+const startCatalog = Effect.fn("startCatalog")(function* (scope: Scope.Scope) {
+ const supervisor = yield* PluginSupervisor.make({
+ heapLimitMb: 64,
+ activationTimeout: "10 seconds",
+ stopGrace: "1 second",
+ }).pipe(
+ Effect.provideService(HostProcess.Arguments, [process.execPath, BIN_PATH]),
+ Effect.provideService(Scope.Scope, scope),
+ );
+ return yield* PluginCatalog.make().pipe(
+ Effect.provideService(PluginSupervisor.PluginSupervisor, supervisor),
+ Effect.provideService(Scope.Scope, scope),
+ );
+});
+
+/**
+ * Writes a plugin whose activation leaves a marker outside its own directory:
+ * a plugin writing into its directory changes its own digest.
+ */
+const preparePlugin = Effect.fn("preparePlugin")(function* (id: string) {
+ const fs = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-plugin-catalog-" });
+ const directory = path.join(root, "plugin");
+ yield* fs.makeDirectory(directory);
+ const marker = path.join(root, "activated");
+ const entry = path.join(directory, "main.mjs");
+ yield* fs.writeFileString(
+ entry,
+ [
+ `import * as NodeFS from "node:fs";`,
+ `export function activate(context) {`,
+ ` NodeFS.writeFileSync(${toJson(marker)}, String(process.pid));`,
+ ` context.proposed.handle("ping", (input) => ({ pid: process.pid, input }));`,
+ `}`,
+ ``,
+ ].join("\n"),
+ );
+ yield* fs.writeFileString(
+ path.join(directory, "t3-plugin.json"),
+ toJson({
+ id,
+ name: id,
+ version: "1.0.0",
+ apiVersion: 1,
+ entry: "main.mjs",
+ proposedApi: true,
+ }),
+ );
+ const edit = (line: string) =>
+ fs
+ .readFileString(entry)
+ .pipe(Effect.flatMap((content) => fs.writeFileString(entry, `${content}// ${line}\n`)));
+ return { directory, marker, edit };
+});
+
+/** Waits, through the subscription, for a snapshot that satisfies `predicate`. */
+const awaitSnapshot = (
+ catalog: Catalog,
+ predicate: (installations: ReadonlyArray) => boolean,
+) =>
+ catalog.subscribe.pipe(
+ Stream.filter((snapshot) => predicate(snapshot.installations)),
+ Stream.runHead,
+ Effect.map((snapshot) => Option.getOrThrow(snapshot).installations),
+ );
+
+/** A step a test can stop at: `reached` completes when it is entered, `release` lets it go on. */
+interface Hold {
+ readonly reached: Deferred.Deferred;
+ readonly release: Deferred.Deferred;
+}
+
+const makeHold = Effect.gen(function* () {
+ const hold: Hold = {
+ reached: yield* Deferred.make(),
+ release: yield* Deferred.make(),
+ };
+ return hold;
+});
+
+const passHold = (hold: Hold | undefined) =>
+ hold === undefined
+ ? Effect.void
+ : Deferred.succeed(hold.reached, undefined).pipe(Effect.andThen(Deferred.await(hold.release)));
+
+/**
+ * A supervisor without processes that behaves like the real one at its
+ * boundary: registration by plugin id, revocation at the start of `disable`,
+ * and `invoke` answering with the registered directory. Tests can hold
+ * `enable` and `disable` open.
+ */
+const makeStubSupervisor = Effect.gen(function* () {
+ const registrations = new Map();
+ const invoked: Array = [];
+ const holds: { enable?: Hold; disable?: Hold } = {};
+ const events = yield* PubSub.unbounded();
+ const service = PluginSupervisor.PluginSupervisor.of({
+ enable: (registration) =>
+ Effect.suspend(() => {
+ const pluginId = registration.manifest.id;
+ if (registrations.has(pluginId))
+ return Effect.fail(new PluginSupervisor.PluginAlreadyEnabledError({ pluginId }));
+ registrations.set(pluginId, registration);
+ return passHold(holds.enable);
+ }),
+ disable: (pluginId) =>
+ Effect.suspend(() => {
+ registrations.delete(pluginId);
+ return passHold(holds.disable);
+ }),
+ resume: () => Effect.void,
+ invoke: (pluginId) =>
+ Effect.suspend(() => {
+ const registration = registrations.get(pluginId);
+ if (registration === undefined)
+ return Effect.fail(new PluginSupervisor.PluginNotEnabledError({ pluginId }));
+ invoked.push(registration.directory);
+ return Effect.succeed(registration.directory);
+ }),
+ state: (pluginId) =>
+ Effect.sync(() =>
+ registrations.has(pluginId) ? Option.some({ _tag: "idle" as const }) : Option.none(),
+ ),
+ subscribe: PubSub.subscribe(events),
+ serveHostMethod: () => Effect.void,
+ });
+ return { service, registrations, invoked, holds };
+});
+
+/** The real file system, except that the next read of a held directory waits for its hold. */
+const makeHoldingFileSystem = Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ let held: { readonly directory: string; readonly hold: Hold } | undefined;
+ const fileSystem: FileSystem.FileSystem = {
+ ...fs,
+ realPath: (target) =>
+ Effect.suspend(() => {
+ if (held === undefined || !target.startsWith(held.directory)) return fs.realPath(target);
+ const { hold } = held;
+ held = undefined;
+ return passHold(hold).pipe(Effect.andThen(fs.realPath(target)));
+ }),
+ };
+ const holdDirectory = Effect.fn("holdDirectory")(function* (directory: string) {
+ const hold = yield* makeHold;
+ held = { directory, hold };
+ return hold;
+ });
+ return { fileSystem, holdDirectory };
+});
+
+/** A catalogue over the stub supervisor, reading files through `fileSystem`. */
+const startStubCatalog = Effect.fn("startStubCatalog")(function* (
+ scope: Scope.Scope,
+ supervisor: PluginSupervisor.PluginSupervisor["Service"],
+ fileSystem?: FileSystem.FileSystem,
+) {
+ return yield* PluginCatalog.make().pipe(
+ Effect.provideService(PluginSupervisor.PluginSupervisor, supervisor),
+ Effect.provideService(FileSystem.FileSystem, fileSystem ?? (yield* FileSystem.FileSystem)),
+ Effect.provideService(Scope.Scope, scope),
+ );
+});
+
+const pidOf = (value: unknown) => (value as { readonly pid: number }).pid;
+
+const isProcessAlive = (pid: number) => {
+ try {
+ process.kill(pid, 0);
+ return true;
+ } catch {
+ return false;
+ }
+};
+
+// Each test gets its own database; the restart test shares one between two starts.
+const withDatabase = (effect: Effect.Effect) =>
+ effect.pipe(Effect.provide(SqlitePersistence.layerMemory));
+
+it.layer(NodeServices.layer)("PluginCatalog", (it) => {
+ it.effect("revokes changed code even when persisting its disabled record fails", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const sql = yield* SqlClient.SqlClient;
+ const stub = yield* makeStubSupervisor;
+ const catalog = yield* startStubCatalog(yield* Scope.Scope, stub.service);
+ const plugin = yield* preparePlugin("test.failed-revocation");
+ const { installation } = yield* catalog.add({ directory: plugin.directory });
+ const installationId = installation.installationId;
+ yield* catalog.consent({ installationId, digest: installation.source!.digest });
+ yield* catalog.enable({ installationId });
+ yield* plugin.edit("changed after consent");
+ yield* sql`CREATE TRIGGER refuse_plugin_save BEFORE UPDATE ON plugin_installations BEGIN SELECT RAISE(FAIL, 'test write failure'); END`;
+ const failed = yield* catalog.refresh({ installationId }).pipe(Effect.flip);
+ expect(failed.reason).toBe("storage");
+ expect(stub.registrations.size).toBe(0);
+ const listed = (yield* catalog.list).installations[0]!;
+ expect(listed.enabled).toBe(false);
+ const published = yield* awaitSnapshot(catalog, ([row]) => row?.enabled === false);
+ expect(published[0]?.enabled).toBe(false);
+ const invoked = yield* catalog.invoke(installationId, "ping", null).pipe(Effect.flip);
+ expect(invoked._tag).toBe("PluginCatalogError");
+ expect(stub.invoked).toEqual([]);
+ yield* sql`DROP TRIGGER refuse_plugin_save`;
+ yield* catalog.refresh({ installationId });
+ expect((yield* catalog.list).installations[0]?.enabled).toBe(false);
+ const saved = yield* sql<{
+ readonly record_json: string;
+ }>`SELECT record_json FROM plugin_installations WHERE installation_id = ${installationId}`;
+ expect(JSON.parse(saved[0]!.record_json).enabled).toBe(false);
+ }),
+ ),
+ );
+
+ it.effect("persists a replacement's committed outcome independently of later consent", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const scope = yield* Scope.Scope;
+ const stub = yield* makeStubSupervisor;
+ const catalog = yield* startStubCatalog(scope, stub.service);
+ const plugin = yield* preparePlugin("test.committed-replacement");
+ const { installation } = yield* catalog.add({ directory: plugin.directory });
+ const installationId = installation.installationId;
+ yield* catalog.consent({ installationId, digest: installation.source!.digest });
+ yield* plugin.edit("approved replacement");
+ const refreshed = yield* catalog.refresh({ installationId });
+ const digest = refreshed.installations[0]!.source!.digest;
+ yield* catalog.replace(
+ { installationId, digest },
+ { paths: [], swap: Effect.void, restore: Effect.die("unexpected rollback") },
+ );
+ yield* plugin.edit("later consent");
+ const later = yield* catalog.refresh({ installationId });
+ yield* catalog.consent({ installationId, digest: later.installations[0]!.source!.digest });
+ for (const current of [catalog, yield* startStubCatalog(scope, stub.service)]) {
+ let restored = false;
+ expect(
+ yield* current.settleReplace(
+ { installationId, digest },
+ {
+ paths: [],
+ restore: Effect.sync(() => {
+ restored = true;
+ }),
+ },
+ ),
+ ).toBe("committed");
+ expect(restored).toBe(false);
+ }
+ }),
+ ),
+ );
+
+ describe("consent", () => {
+ it.effect("runs nothing until the exact bytes are approved, then starts on first use", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ const sql = yield* SqlClient.SqlClient;
+ const catalog = yield* startCatalog(yield* Scope.Scope);
+ const plugin = yield* preparePlugin("test.lazy");
+
+ const relative = yield* catalog.add({ directory: "plugins/lazy" }).pipe(Effect.flip);
+ expect(relative.reason).toBe("invalid-directory");
+
+ const { installation: added } = yield* catalog.add({ directory: plugin.directory });
+ const installationId = added.installationId;
+ expect(pluginInstallationStatus(added)).toBe("needs-consent");
+ expect(added).toMatchObject({ enabled: false, consent: null, generation: 0 });
+ expect(added.manifest?.id).toBe("test.lazy");
+ expect(added.hostState).toBeUndefined();
+ const again = yield* catalog.add({ directory: plugin.directory }).pipe(Effect.flip);
+ expect(again.reason).toBe("already-added");
+
+ const unapproved = yield* catalog.enable({ installationId }).pipe(Effect.flip);
+ expect(unapproved.reason).toBe("consent-required");
+ const wrongDigest = yield* catalog
+ .consent({ installationId, digest: `sha256:${"0".repeat(64)}` })
+ .pipe(Effect.flip);
+ expect(wrongDigest.reason).toBe("source-changed");
+
+ const digest = added.source!.digest;
+ const { installation: approved } = yield* catalog.consent({ installationId, digest });
+ expect(pluginInstallationStatus(approved)).toBe("disabled");
+ expect(approved.consent).toMatchObject({ digest, capabilities: [] });
+
+ const { installation: enabled } = yield* catalog.enable({ installationId });
+ expect(pluginInstallationStatus(enabled)).toBe("enabled");
+ expect(enabled).toMatchObject({ generation: 1, hostState: { _tag: "idle" } });
+ expect(yield* fs.exists(plugin.marker)).toBe(false);
+
+ const pid = pidOf(yield* catalog.invoke(installationId, "ping", null));
+ expect(isProcessAlive(pid)).toBe(true);
+ yield* awaitSnapshot(catalog, ([row]) => row?.hostState?._tag === "running");
+
+ const { installation: disabled } = yield* catalog.disable({ installationId });
+ expect(isProcessAlive(pid)).toBe(false);
+ expect(pluginInstallationStatus(disabled)).toBe("disabled");
+ expect(disabled.hostState).toBeUndefined();
+ const stopped = yield* catalog.invoke(installationId, "ping", null).pipe(Effect.flip);
+ expect(stopped._tag).toBe("PluginCatalogError");
+
+ expect((yield* catalog.enable({ installationId })).installation.generation).toBe(2);
+ expect(yield* catalog.remove({ installationId })).toEqual({ installationId });
+ expect((yield* catalog.list).installations).toEqual([]);
+ // Settings promises that removing an added directory leaves it in place.
+ expect(yield* fs.exists(plugin.directory)).toBe(true);
+ expect(yield* sql`SELECT installation_id FROM plugin_installations`).toEqual([]);
+ }),
+ ),
+ );
+
+ it.effect("stops a plugin and asks again when its bytes change", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ const catalog = yield* startCatalog(yield* Scope.Scope);
+ const plugin = yield* preparePlugin("test.changed");
+ const { installation } = yield* catalog.add({ directory: plugin.directory });
+ const installationId = installation.installationId;
+ const firstDigest = installation.source!.digest;
+ yield* catalog.consent({ installationId, digest: firstDigest });
+ yield* catalog.enable({ installationId });
+ const pid = pidOf(yield* catalog.invoke(installationId, "ping", null));
+
+ yield* plugin.edit("changed while running");
+ const [refreshed] = (yield* catalog.refresh({ installationId })).installations;
+ expect(pluginInstallationStatus(refreshed!)).toBe("needs-consent");
+ expect(refreshed!.enabled).toBe(false);
+ expect(isProcessAlive(pid)).toBe(false);
+ const changed = yield* catalog.enable({ installationId }).pipe(Effect.flip);
+ expect(changed.reason).toBe("consent-required");
+ const stale = yield* catalog
+ .consent({ installationId, digest: firstDigest })
+ .pipe(Effect.flip);
+ expect(stale.reason).toBe("source-changed");
+
+ yield* catalog.consent({ installationId, digest: refreshed!.source!.digest });
+ yield* catalog.enable({ installationId });
+ // Changed again with no refresh: the check before a fresh process catches it.
+ yield* plugin.edit("changed before first use");
+ yield* fs.remove(plugin.marker);
+ const beforeStart = yield* catalog.invoke(installationId, "ping", null).pipe(Effect.flip);
+ expect(beforeStart).toMatchObject({ reason: "source-changed" });
+ expect(yield* fs.exists(plugin.marker)).toBe(false);
+ const [revoked] = (yield* catalog.list).installations;
+ expect(pluginInstallationStatus(revoked!)).toBe("needs-consent");
+ }),
+ ),
+ );
+
+ it.effect("checks the bytes when enabling an installation that is already enabled", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const catalog = yield* startCatalog(yield* Scope.Scope);
+ const plugin = yield* preparePlugin("test.enable-again");
+ const { installation } = yield* catalog.add({ directory: plugin.directory });
+ const installationId = installation.installationId;
+ const approve = (digest: string) =>
+ catalog
+ .consent({ installationId, digest })
+ .pipe(Effect.andThen(catalog.enable({ installationId })));
+ const { installation: enabled } = yield* approve(installation.source!.digest);
+
+ // Unchanged: the same registration, not a new generation.
+ const { installation: same } = yield* catalog.enable({ installationId });
+ expect(same).toMatchObject({ enabled: true, generation: enabled.generation });
+
+ // Changed while registered but idle.
+ yield* plugin.edit("changed while idle");
+ const idle = yield* catalog.enable({ installationId }).pipe(Effect.flip);
+ expect(idle.reason).toBe("consent-required");
+ const [afterIdle] = (yield* catalog.list).installations;
+ expect(pluginInstallationStatus(afterIdle!)).toBe("needs-consent");
+ expect(afterIdle!.enabled).toBe(false);
+
+ // Changed while its process runs: enabling again stops it.
+ yield* approve(afterIdle!.source!.digest);
+ const pid = pidOf(yield* catalog.invoke(installationId, "ping", null));
+ yield* plugin.edit("changed while running");
+ const running = yield* catalog.enable({ installationId }).pipe(Effect.flip);
+ expect(running.reason).toBe("consent-required");
+ expect(isProcessAlive(pid)).toBe(false);
+ const [afterRunning] = (yield* catalog.list).installations;
+ expect(pluginInstallationStatus(afterRunning!)).toBe("needs-consent");
+ expect(afterRunning!.hostState).toBeUndefined();
+ }),
+ ),
+ );
+
+ it.effect("runs one directory per plugin id at a time", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const catalog = yield* startCatalog(yield* Scope.Scope);
+ const approve = Effect.fn(function* (directory: string) {
+ const { installation } = yield* catalog.add({ directory });
+ const installationId = installation.installationId;
+ yield* catalog.consent({ installationId, digest: installation.source!.digest });
+ return installationId;
+ });
+ const first = yield* approve((yield* preparePlugin("test.same")).directory);
+ const second = yield* approve((yield* preparePlugin("test.same")).directory);
+
+ yield* catalog.enable({ installationId: first });
+ const conflict = yield* catalog.enable({ installationId: second }).pipe(Effect.flip);
+ expect(conflict.reason).toBe("plugin-id-conflict");
+ yield* catalog.disable({ installationId: first });
+ const { installation } = yield* catalog.enable({ installationId: second });
+ expect(installation.enabled).toBe(true);
+ }),
+ ),
+ );
+
+ it.effect("keeps disable and remove available when the directory is gone", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ const catalog = yield* startCatalog(yield* Scope.Scope);
+ const plugin = yield* preparePlugin("test.gone");
+ const { installation } = yield* catalog.add({ directory: plugin.directory });
+ const installationId = installation.installationId;
+ yield* catalog.consent({ installationId, digest: installation.source!.digest });
+ yield* catalog.enable({ installationId });
+
+ yield* fs.remove(plugin.directory, { recursive: true });
+ const [missing] = (yield* catalog.refresh({})).installations;
+ expect(pluginInstallationStatus(missing!)).toBe("unavailable");
+ expect(missing).toMatchObject({ enabled: false, source: null });
+ expect(missing!.problem).toContain("does not exist");
+ expect(missing!.manifest?.id).toBe("test.gone");
+ expect((yield* catalog.enable({ installationId }).pipe(Effect.flip)).reason).toBe(
+ "unavailable",
+ );
+ expect((yield* catalog.disable({ installationId })).installation.enabled).toBe(false);
+ yield* catalog.remove({ installationId });
+ const unknown = yield* catalog
+ .disable({ installationId: PluginInstallationId.make("missing") })
+ .pipe(Effect.flip);
+ expect(unknown.reason).toBe("not-found");
+ }),
+ ),
+ );
+ });
+
+ describe("calls racing management", () => {
+ it.effect("fails a call whose installation is replaced while its bytes are checked", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const stub = yield* makeStubSupervisor;
+ const files = yield* makeHoldingFileSystem;
+ const catalog = yield* startStubCatalog(
+ yield* Scope.Scope,
+ stub.service,
+ files.fileSystem,
+ );
+ const approve = Effect.fn(function* (directory: string) {
+ const { installation } = yield* catalog.add({ directory });
+ yield* catalog.consent({
+ installationId: installation.installationId,
+ digest: installation.source!.digest,
+ });
+ return installation;
+ });
+ const first = yield* approve((yield* preparePlugin("test.same")).directory);
+ const second = yield* approve((yield* preparePlugin("test.same")).directory);
+ yield* catalog.enable({ installationId: first.installationId });
+
+ // The call stops in its byte check, before a fresh process would start.
+ const hold = yield* files.holdDirectory(first.directory);
+ const call = yield* catalog
+ .invoke(first.installationId, "ping", null)
+ .pipe(Effect.forkChild({ startImmediately: true }));
+ yield* Deferred.await(hold.reached);
+ yield* catalog.disable({ installationId: first.installationId });
+ yield* catalog.enable({ installationId: second.installationId });
+ yield* Deferred.succeed(hold.release, undefined);
+
+ const refused = yield* Fiber.join(call).pipe(Effect.flip);
+ expect(refused).toMatchObject({ _tag: "PluginCatalogError", reason: "unavailable" });
+ expect(stub.invoked).toEqual([]);
+ expect(yield* catalog.invoke(second.installationId, "ping", null)).toBe(second.directory);
+ }),
+ ),
+ );
+
+ it.effect(
+ "fails a call when its installation is enabled again or names an old generation",
+ () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const stub = yield* makeStubSupervisor;
+ const files = yield* makeHoldingFileSystem;
+ const catalog = yield* startStubCatalog(
+ yield* Scope.Scope,
+ stub.service,
+ files.fileSystem,
+ );
+ const plugin = yield* preparePlugin("test.generation");
+ const { installation } = yield* catalog.add({ directory: plugin.directory });
+ const installationId = installation.installationId;
+ yield* catalog.consent({ installationId, digest: installation.source!.digest });
+ const { installation: enabled } = yield* catalog.enable({ installationId });
+
+ const hold = yield* files.holdDirectory(installation.directory);
+ const call = yield* catalog
+ .invoke(installationId, "ping", null)
+ .pipe(Effect.forkChild({ startImmediately: true }));
+ yield* Deferred.await(hold.reached);
+ yield* catalog.disable({ installationId });
+ const { installation: again } = yield* catalog.enable({ installationId });
+ yield* Deferred.succeed(hold.release, undefined);
+ expect(yield* Fiber.join(call).pipe(Effect.flip)).toMatchObject({
+ reason: "unavailable",
+ });
+ expect(stub.invoked).toEqual([]);
+
+ expect(again.generation).toBe(enabled.generation + 1);
+ const stale = yield* catalog
+ .invoke(installationId, "ping", null, { generation: enabled.generation })
+ .pipe(Effect.flip);
+ expect(stale).toMatchObject({ reason: "generation-changed" });
+ expect(stub.invoked).toEqual([]);
+ expect(
+ yield* catalog.invoke(installationId, "ping", null, { generation: again.generation }),
+ ).toBe(installation.directory);
+ }),
+ ),
+ );
+ });
+
+ describe("subscription", () => {
+ it.effect("sends a snapshot only when a step changed what it shows", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const stub = yield* makeStubSupervisor;
+ const catalog = yield* startStubCatalog(yield* Scope.Scope, stub.service);
+ const plugin = yield* preparePlugin("test.quiet");
+ const { installation } = yield* catalog.add({ directory: plugin.directory });
+ const installationId = installation.installationId;
+ const digest = installation.source!.digest;
+ yield* catalog.consent({ installationId, digest });
+
+ const snapshots = yield* Queue.unbounded>();
+ yield* catalog.subscribe.pipe(
+ Stream.runForEach((snapshot) => Queue.offer(snapshots, snapshot.installations)),
+ Effect.forkScoped,
+ );
+ const [initial] = yield* Queue.take(snapshots);
+ expect(initial).toMatchObject({ enabled: false });
+
+ // Failures and steps that find nothing new.
+ yield* catalog.add({ directory: "relative" }).pipe(Effect.flip);
+ yield* catalog.add({ directory: plugin.directory }).pipe(Effect.flip);
+ yield* catalog
+ .consent({ installationId, digest: `sha256:${"0".repeat(64)}` })
+ .pipe(Effect.flip);
+ yield* catalog.resume({ installationId }).pipe(Effect.flip);
+ yield* catalog.refresh({});
+ yield* catalog.disable({ installationId });
+
+ yield* catalog.enable({ installationId });
+ const [enabled] = yield* Queue.take(snapshots);
+ expect(enabled).toMatchObject({ enabled: true, inspectedAt: initial!.inspectedAt });
+
+ yield* catalog.enable({ installationId });
+ yield* catalog.resume({ installationId });
+ yield* catalog.disable({ installationId });
+ const [disabled] = yield* Queue.take(snapshots);
+ expect(disabled).toMatchObject({ enabled: false });
+ }),
+ ),
+ );
+ });
+
+ describe("interrupted management", () => {
+ /** An approved, enabled installation in a catalogue that can be restarted on the same database. */
+ const enabledInStub = Effect.fn("enabledInStub")(function* (
+ fileSystem?: FileSystem.FileSystem,
+ ) {
+ const stub = yield* makeStubSupervisor;
+ const before = yield* Scope.make();
+ const catalog = yield* startStubCatalog(before, stub.service, fileSystem);
+ const plugin = yield* preparePlugin("test.interrupted");
+ const { installation } = yield* catalog.add({ directory: plugin.directory });
+ const installationId = installation.installationId;
+ yield* catalog.consent({ installationId, digest: installation.source!.digest });
+ yield* catalog.enable({ installationId });
+ return { stub, before, catalog, installationId, directory: installation.directory };
+ });
+
+ /** Starts the catalogue again and waits until its startup re-registration has run. */
+ const restart = Effect.fn("restart")(function* () {
+ const stub = yield* makeStubSupervisor;
+ const catalog = yield* startStubCatalog(yield* Scope.Scope, stub.service);
+ // Management steps queue behind startup, so this returns after it.
+ const { installations } = yield* catalog.refresh({});
+ return { stub, installations };
+ });
+
+ const storedRows = Effect.gen(function* () {
+ const sql = yield* SqlClient.SqlClient;
+ const rows = yield* sql<{ readonly record_json: string }>`
+ SELECT record_json FROM plugin_installations
+ `;
+ return rows.map((row) => JSON.parse(row.record_json) as { readonly enabled: boolean });
+ });
+
+ it.effect("keeps a disable whose caller left while the process stopped", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const { stub, before, catalog, installationId } = yield* enabledInStub();
+ const stopping = yield* makeHold;
+ stub.holds.disable = stopping;
+ const disabling = yield* catalog
+ .disable({ installationId })
+ .pipe(Effect.forkChild({ startImmediately: true }));
+ yield* Deferred.await(stopping.reached);
+ yield* Fiber.interrupt(disabling);
+
+ const [row] = (yield* catalog.list).installations;
+ expect(row).toMatchObject({ enabled: false });
+ expect(row!.hostState).toBeUndefined();
+ expect(yield* storedRows).toMatchObject([{ enabled: false }]);
+ expect(stub.registrations.size).toBe(0);
+ yield* Deferred.succeed(stopping.release, undefined);
+ yield* Scope.close(before, Exit.void);
+
+ const after = yield* restart();
+ expect(after.installations).toMatchObject([{ installationId, enabled: false }]);
+ expect(after.stub.registrations.size).toBe(0);
+ }),
+ ),
+ );
+
+ it.effect("makes a repeated disable wait for the interrupted stop", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const { stub, catalog, installationId } = yield* enabledInStub();
+ const stopping = yield* makeHold;
+ stub.holds.disable = stopping;
+ const disabling = yield* catalog
+ .disable({ installationId })
+ .pipe(Effect.forkChild({ startImmediately: true }));
+ yield* Deferred.await(stopping.reached);
+ yield* Fiber.interrupt(disabling);
+
+ const retry = yield* catalog
+ .disable({ installationId })
+ .pipe(Effect.forkChild({ startImmediately: true }));
+ yield* Effect.yieldNow;
+ expect(retry.pollUnsafe()).toBeUndefined();
+ expect(stub.registrations.size).toBe(0);
+
+ yield* Deferred.succeed(stopping.release, undefined);
+ const { installation } = yield* Fiber.join(retry);
+ expect(installation).toMatchObject({ enabled: false });
+ expect(installation.hostState).toBeUndefined();
+ expect(stub.registrations.size).toBe(0);
+ }),
+ ),
+ );
+
+ it.effect("waits for an interrupted stop before inspecting and enabling again", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const fs = yield* makeHoldingFileSystem;
+ const { stub, catalog, installationId, directory } = yield* enabledInStub(fs.fileSystem);
+ const stopping = yield* makeHold;
+ stub.holds.disable = stopping;
+ const disabling = yield* catalog
+ .disable({ installationId })
+ .pipe(Effect.forkChild({ startImmediately: true }));
+ yield* Deferred.await(stopping.reached);
+ yield* Fiber.interrupt(disabling);
+
+ const inspection = yield* fs.holdDirectory(directory);
+ const enabling = yield* catalog
+ .enable({ installationId })
+ .pipe(Effect.forkChild({ startImmediately: true }));
+ const inspectedBeforeStop = yield* Deferred.isDone(inspection.reached);
+ expect(stub.registrations.size).toBe(0);
+
+ yield* Deferred.succeed(stopping.release, undefined);
+ yield* Deferred.await(inspection.reached);
+ yield* Deferred.succeed(inspection.release, undefined);
+ const { installation } = yield* Fiber.join(enabling);
+ expect(inspectedBeforeStop).toBe(false);
+ expect(installation).toMatchObject({ enabled: true, generation: 2 });
+ expect(stub.registrations.size).toBe(1);
+ }),
+ ),
+ );
+
+ it.effect("keeps a remove whose caller left while the process stopped", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const { stub, before, catalog, installationId } = yield* enabledInStub();
+ const stopping = yield* makeHold;
+ stub.holds.disable = stopping;
+ const removing = yield* catalog
+ .remove({ installationId })
+ .pipe(Effect.forkChild({ startImmediately: true }));
+ yield* Deferred.await(stopping.reached);
+ yield* Fiber.interrupt(removing);
+
+ expect((yield* catalog.list).installations).toEqual([]);
+ expect(yield* storedRows).toEqual([]);
+ expect(stub.registrations.size).toBe(0);
+ yield* Deferred.succeed(stopping.release, undefined);
+ yield* Scope.close(before, Exit.void);
+
+ const after = yield* restart();
+ expect(after.installations).toEqual([]);
+ expect(after.stub.registrations.size).toBe(0);
+ }),
+ ),
+ );
+
+ it.effect("finishes an enable whose caller left during registration", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const { stub, before, catalog, installationId } = yield* enabledInStub();
+ yield* catalog.disable({ installationId });
+ const registering = yield* makeHold;
+ stub.holds.enable = registering;
+ const enabling = yield* catalog
+ .enable({ installationId })
+ .pipe(Effect.forkChild({ startImmediately: true }));
+ yield* Deferred.await(registering.reached);
+ const interrupting = yield* Fiber.interrupt(enabling).pipe(
+ Effect.forkChild({ startImmediately: true }),
+ );
+ yield* Deferred.succeed(registering.release, undefined);
+ yield* Fiber.join(interrupting);
+
+ // Registered, saved, and shown together: never one without the others.
+ const [row] = (yield* catalog.list).installations;
+ expect(row).toMatchObject({ enabled: true, generation: 2 });
+ expect(yield* storedRows).toMatchObject([{ enabled: true }]);
+ expect(stub.registrations.size).toBe(1);
+ yield* Scope.close(before, Exit.void);
+ }),
+ ),
+ );
+
+ it.effect("prepares tool grants after startup restores registration generations", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const before = yield* Scope.make();
+ const first = yield* startStubCatalog(before, (yield* makeStubSupervisor).service);
+ const { directory } = yield* preparePlugin("test.startup-tools");
+ yield* fs.writeFileString(
+ path.join(directory, "t3-plugin.json"),
+ toJson({
+ id: "test.startup-tools",
+ name: "Startup tools",
+ version: "1.0.0",
+ apiVersion: 1,
+ entry: "main.mjs",
+ proposedApi: true,
+ capabilities: ["tools"],
+ tools: [
+ {
+ name: "ping",
+ description: "Ping",
+ inputSchema: { type: "object" },
+ sideEffect: "read",
+ },
+ ],
+ }),
+ );
+ const { installation } = yield* first.add({ directory });
+ const installationId = installation.installationId;
+ yield* first.consent({ installationId, digest: installation.source!.digest });
+ yield* first.enable({ installationId });
+ yield* Scope.close(before, Exit.void);
+
+ const stub = yield* makeStubSupervisor;
+ const registering = yield* makeHold;
+ stub.holds.enable = registering;
+ const catalog = yield* startStubCatalog(yield* Scope.Scope, stub.service);
+ yield* Effect.addFinalizer(() => Deferred.succeed(registering.release, undefined));
+ yield* Deferred.await(registering.reached);
+ const tools = yield* PluginTools.make.pipe(
+ Effect.provideService(PluginCatalog.PluginCatalog, catalog),
+ );
+ const preparing = yield* tools.grants.pipe(Effect.forkChild({ startImmediately: true }));
+ expect(preparing.pollUnsafe()).toBeUndefined();
+ yield* Deferred.succeed(registering.release, undefined);
+ const grants = yield* Fiber.join(preparing);
+ expect(grants).toEqual([{ installationId, generation: 2 }]);
+ expect((yield* tools.list(grants)).tools).toHaveLength(1);
+ expect(
+ yield* tools.call(grants, {
+ tool: "test.startup-tools/ping",
+ input: {},
+ context: {
+ environmentId: EnvironmentId.make("test"),
+ threadId: ThreadId.make("test"),
+ },
+ }),
+ ).toBe(directory);
+ }),
+ ),
+ );
+
+ it.effect("holds a call made during startup until the plugin is registered again", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const { before, installationId } = yield* enabledInStub();
+ yield* Scope.close(before, Exit.void);
+
+ const stub = yield* makeStubSupervisor;
+ const registering = yield* makeHold;
+ stub.holds.enable = registering;
+ const after = yield* startStubCatalog(yield* Scope.Scope, stub.service);
+ // Runs before the catalogue's finalizers, so a failing test can still close its scope.
+ yield* Effect.addFinalizer(() => Deferred.succeed(registering.release, undefined));
+ yield* Deferred.await(registering.reached);
+ const calling = yield* after
+ .invoke(installationId, "ping", null)
+ .pipe(Effect.forkChild({ startImmediately: true }));
+ yield* Effect.yieldNow;
+ expect(calling.pollUnsafe()).toBeUndefined();
+
+ yield* Deferred.succeed(registering.release, undefined);
+ const [directory] = [...stub.registrations.values()].map((r) => r.directory);
+ expect(yield* Fiber.join(calling)).toBe(directory);
+ expect(stub.invoked).toEqual([directory]);
+ }),
+ ),
+ );
+
+ it.effect("keeps a remove made as the catalogue starts", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const { before, installationId } = yield* enabledInStub();
+ yield* Scope.close(before, Exit.void);
+
+ const stub = yield* makeStubSupervisor;
+ const after = yield* startStubCatalog(yield* Scope.Scope, stub.service);
+ yield* after.remove({ installationId });
+ // A call waits for startup to finish restoring.
+ yield* after.invoke(installationId, "ping", null).pipe(Effect.flip);
+
+ expect((yield* after.list).installations).toEqual([]);
+ expect(yield* storedRows).toEqual([]);
+ expect(stub.registrations.size).toBe(0);
+ }),
+ ),
+ );
+
+ it.effect("keeps an enable made as the catalogue starts", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const { before, installationId } = yield* enabledInStub();
+ yield* Scope.close(before, Exit.void);
+
+ const stub = yield* makeStubSupervisor;
+ const after = yield* startStubCatalog(yield* Scope.Scope, stub.service);
+ yield* after.enable({ installationId });
+ const [directory] = [...stub.registrations.values()].map((r) => r.directory);
+ expect(yield* after.invoke(installationId, "ping", null)).toBe(directory);
+
+ const [row] = (yield* after.list).installations;
+ expect(row).toMatchObject({ enabled: true, generation: 2 });
+ expect(stub.registrations.size).toBe(1);
+ }),
+ ),
+ );
+ });
+
+ describe("server restart", () => {
+ it.effect("re-enables approved plugins without starting them and drops changed ones", () =>
+ withDatabase(
+ Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ const kept = yield* preparePlugin("test.kept");
+ const changed = yield* preparePlugin("test.restart-changed");
+
+ const before = yield* Scope.make();
+ const first = yield* startCatalog(before);
+ const ids = yield* Effect.forEach([kept, changed], (plugin) =>
+ Effect.gen(function* () {
+ const { installation } = yield* first.add({ directory: plugin.directory });
+ const installationId = installation.installationId;
+ yield* first.consent({ installationId, digest: installation.source!.digest });
+ yield* first.enable({ installationId });
+ return installationId;
+ }),
+ );
+ const pid = pidOf(yield* first.invoke(ids[0]!, "ping", null));
+ yield* Scope.close(before, Exit.void);
+ expect(isProcessAlive(pid)).toBe(false);
+
+ yield* fs.remove(kept.marker);
+ yield* changed.edit("changed while the server was down");
+ const after = yield* startCatalog(yield* Scope.Scope);
+ const restarted = yield* awaitSnapshot(after, (rows) =>
+ rows.every((row) => row.hostState?._tag === "idle" || !row.enabled),
+ );
+ const keptRow = restarted.find((row) => row.installationId === ids[0]);
+ const changedRow = restarted.find((row) => row.installationId === ids[1]);
+ expect(keptRow).toMatchObject({ enabled: true, generation: 2 });
+ expect(pluginInstallationStatus(changedRow!)).toBe("needs-consent");
+ expect(changedRow!.enabled).toBe(false);
+ expect(yield* fs.exists(kept.marker)).toBe(false);
+
+ const restartedPid = pidOf(yield* after.invoke(ids[0]!, "ping", null));
+ expect(restartedPid).not.toBe(pid);
+ expect(yield* fs.exists(kept.marker)).toBe(true);
+ }),
+ ),
+ );
+ });
+});
diff --git a/apps/server/src/plugins/PluginCatalog.ts b/apps/server/src/plugins/PluginCatalog.ts
new file mode 100644
index 0000000000000..613c7d534cfeb
--- /dev/null
+++ b/apps/server/src/plugins/PluginCatalog.ts
@@ -0,0 +1,939 @@
+// Consent binds to exact directory bytes; edits revoke registration and require fresh consent.
+// The digest cannot constrain its OS-user owner between checks or turn trusted plugins into a sandbox.
+import {
+ PluginCatalogError,
+ PluginInstallation,
+ pluginInstallationStatus,
+ type PluginAddInput,
+ type PluginCatalogSnapshot,
+ type PluginConsentInput,
+ type PluginId,
+ type PluginInstallationInput,
+ type PluginInstallationManifest,
+ type PluginInstallationResult,
+ type PluginManifest,
+ type PluginRefreshInput,
+ type PluginRemoveResult,
+ type PluginSource,
+ PluginInstallationId,
+ PluginSourceDigest,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as DateTime from "effect/DateTime";
+import * as Equal from "effect/Equal";
+import * as Deferred from "effect/Deferred";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as PubSub from "effect/PubSub";
+import * as Schema from "effect/Schema";
+import * as Semaphore from "effect/Semaphore";
+import * as Stream from "effect/Stream";
+import * as SqlClient from "effect/sql/SqlClient";
+
+import { PluginEventDelivery } from "./PluginEventDelivery.ts";
+import { loadPluginDirectory, type PluginRegistration } from "./PluginManifestLoader.ts";
+import {
+ defaultPluginSourceLimits,
+ digestPluginSource,
+ type PluginSourceLimits,
+} from "./pluginSource.ts";
+import { PluginSupervisor, type PluginInvokeError } from "./PluginSupervisor.ts";
+
+/** What is persisted: the wire record without the live process and delivery states. */
+const PluginInstallationRecord = PluginInstallation.mapFields(
+ ({ hostState: _hostState, eventDelivery: _eventDelivery, ...fields }) => ({
+ ...fields,
+ // A successful file swap stays committed when a later consent changes.
+ replacement: Schema.optionalKey(
+ Schema.Struct({
+ digest: PluginSourceDigest,
+ committed: Schema.Boolean,
+ attemptId: Schema.optionalKey(Schema.String),
+ }),
+ ),
+ }),
+);
+type PluginInstallationRecord = typeof PluginInstallationRecord.Type;
+
+const decodeRecord = Schema.decodeUnknownEffect(Schema.fromJsonString(PluginInstallationRecord));
+const encodeRecord = Schema.encodeEffect(Schema.fromJsonString(PluginInstallationRecord));
+
+/** One registration with the supervisor. A re-enable makes a new one; it is never mutated. */
+interface Registration {
+ readonly pluginId: PluginId;
+ readonly generation: number;
+}
+
+interface Installation {
+ record: PluginInstallationRecord;
+ /** Revocation is visible even when storage fails; retry that write on refresh. */
+ unsaved?: boolean;
+ /** The registration this installation runs under, while enabled. */
+ registered: Registration | undefined;
+ /** Waits for the process of the last registration revoked here to exit. */
+ stopping: Fiber.Fiber | undefined;
+}
+
+type Inspection =
+ | {
+ readonly _tag: "ok";
+ readonly registration: PluginRegistration;
+ readonly source: PluginSource;
+ }
+ | { readonly _tag: "failed"; readonly reason: string };
+
+/**
+ * How long a call waits for startup to re-register enabled plugins before it
+ * proceeds without them, matching the supervisor's default activation timeout.
+ */
+const STARTUP_RESTORE_WAIT = Duration.seconds(10);
+
+/** What one admission attempt of `invoke` found. */
+type Admission =
+ | { readonly _tag: "called"; readonly value: Schema.Json }
+ | { readonly _tag: "revoked" }
+ /** A fresh process would start: the bytes must be checked against `consented` first. */
+ | { readonly _tag: "check"; readonly consented: string };
+
+/** What clients see of a manifest; also the summary of a downloaded npm update under review. */
+export const summarizePluginManifest = (manifest: PluginManifest): PluginInstallationManifest => ({
+ id: manifest.id,
+ name: manifest.name,
+ version: manifest.version,
+ ...(manifest.description === undefined ? {} : { description: manifest.description }),
+ capabilities: manifest.capabilities,
+ proposedApi: manifest.proposedApi,
+ ...(manifest.tools === undefined || manifest.tools.length === 0 ? {} : { tools: manifest.tools }),
+ ...(manifest.settings === undefined ? {} : { settings: manifest.settings }),
+ ...(manifest.actions === undefined || manifest.actions.length === 0
+ ? {}
+ : { actions: manifest.actions }),
+});
+
+const catalogError = (
+ reason: string,
+ message: string,
+ installationId?: PluginInstallationId,
+): PluginCatalogError =>
+ new PluginCatalogError({
+ reason,
+ message,
+ ...(installationId === undefined ? {} : { installationId }),
+ });
+
+const storageError = (cause: unknown) =>
+ Effect.logWarning("Plugin catalogue storage failed", { cause }).pipe(
+ Effect.andThen(Effect.fail(catalogError("storage", "Could not save the plugin catalogue."))),
+ );
+
+export class PluginCatalog extends Context.Service<
+ PluginCatalog,
+ {
+ readonly list: Effect.Effect;
+ /** Completes after enabled installations have their startup registration generations. */
+ readonly ready: Effect.Effect;
+ /** Changes whenever `list` could show different installation records, so a reader can cache what it derives from them. */
+ readonly revision: Effect.Effect;
+ /** One snapshot now, then a fresh one after every catalogue or plugin state change. */
+ readonly subscribe: Stream.Stream;
+ readonly add: (
+ input: PluginAddInput,
+ ) => Effect.Effect;
+ readonly refresh: (
+ input: PluginRefreshInput,
+ ) => Effect.Effect;
+ readonly consent: (
+ input: PluginConsentInput,
+ ) => Effect.Effect;
+ readonly enable: (
+ input: PluginInstallationInput,
+ ) => Effect.Effect;
+ readonly disable: (
+ input: PluginInstallationInput,
+ ) => Effect.Effect;
+ readonly remove: (
+ input: PluginInstallationInput,
+ ) => Effect.Effect;
+ /** Clears the process's backoff, quarantine, or incompatibility, and restarts stopped event delivery. */
+ readonly resume: (
+ input: PluginInstallationInput,
+ ) => Effect.Effect;
+ // Claim all move paths and keep registration revoked throughout the locked swap and consent commit.
+ // Restore on precommit failure; re-enable only if previously enabled and the final bytes have consent.
+ readonly replace: (
+ input: PluginConsentInput & { readonly attemptId?: string },
+ files: {
+ readonly paths: ReadonlyArray;
+ readonly swap: Effect.Effect;
+ readonly restore: Effect.Effect;
+ },
+ ) => Effect.Effect;
+ // The persisted attempt outcome decides commit versus rollback independently of later consent.
+ // Recovery claims paths, waits for stop, and never grants consent or enables the installation.
+ readonly settleReplace: (
+ input: PluginConsentInput & { readonly attemptId?: string },
+ files?: {
+ readonly paths: ReadonlyArray;
+ readonly restore: Effect.Effect;
+ },
+ ) => Effect.Effect<"committed" | "rolled-back", PluginCatalogError>;
+ // Claim paths before mutation; reject overlapping installations and await every process that used those files.
+ readonly changeFiles: (
+ paths: ReadonlyArray,
+ effect: Effect.Effect,
+ ) => Effect.Effect;
+ // Checks consent before cold starts; generation pins the registration so revocation or replacement never redirects a call.
+ readonly invoke: (
+ installationId: PluginInstallationId,
+ handler: string,
+ input: Schema.Json,
+ options?: { readonly timeout?: Duration.Input; readonly generation?: number },
+ ) => Effect.Effect;
+ }
+>()("t3/plugins/PluginCatalog") {}
+
+export const make = Effect.fn("PluginCatalog.make")(function* (
+ sourceLimits: PluginSourceLimits = defaultPluginSourceLimits,
+) {
+ const sql = yield* SqlClient.SqlClient;
+ const supervisor = yield* PluginSupervisor;
+ const crypto = yield* Crypto.Crypto;
+ const path = yield* Path.Path;
+ const fileSystem = yield* FileSystem.FileSystem;
+ const scope = yield* Effect.scope;
+ const eventDeliveries = yield* Effect.serviceOption(PluginEventDelivery);
+
+ const installations = new Map();
+ // Management is rare and each step may wait for a process to exit; one at a time keeps the
+ // catalogue, the table, and the supervisor in step.
+ const lock = yield* Semaphore.make(1);
+ /**
+ * Processes still exiting after their registration was revoked, by the
+ * directory they ran from. Kept apart from `registered`, since a disable
+ * or remove whose caller went away no longer waits for its process.
+ */
+ const exiting = new Map, string>();
+ const changes = yield* PubSub.sliding(1);
+ const notify = PubSub.publish(changes, undefined).pipe(Effect.asVoid);
+ // Counts changes a snapshot can show, so a step that changed nothing tells no one.
+ let revision = 0;
+ // Completes when startup has tried to re-register every enabled installation.
+ const restored = yield* Deferred.make();
+
+ const now = DateTime.now.pipe(Effect.map(DateTime.formatIso));
+
+ const save = (record: PluginInstallationRecord) =>
+ encodeRecord(record).pipe(
+ Effect.flatMap(
+ (json) => sql`
+ INSERT INTO plugin_installations (installation_id, directory, record_json)
+ VALUES (${record.installationId}, ${record.directory}, ${json})
+ ON CONFLICT (installation_id) DO UPDATE SET
+ directory = excluded.directory,
+ record_json = excluded.record_json
+ `,
+ ),
+ Effect.asVoid,
+ Effect.catch(storageError),
+ );
+
+ /** Saves `record` as enabled, with the event cursor its capabilities need, or neither. */
+ const saveEnabled = (record: PluginInstallationRecord, capabilities: ReadonlyArray) =>
+ Option.match(eventDeliveries, {
+ onNone: () => save(record),
+ onSome: (delivery) =>
+ sql
+ .withTransaction(
+ delivery
+ .begin(record.installationId, capabilities)
+ .pipe(Effect.catch(storageError), Effect.andThen(save(record))),
+ )
+ .pipe(Effect.catchTags({ SqlError: storageError })),
+ });
+
+ /** Saves `record` and then shows it, or neither. */
+ const commit = (installation: Installation, record: PluginInstallationRecord) =>
+ save(record).pipe(
+ Effect.andThen(
+ Effect.sync(() => {
+ installation.record = record;
+ installation.unsaved = false;
+ revision++;
+ }),
+ ),
+ Effect.uninterruptible,
+ );
+
+ const inspect = (directory: string): Effect.Effect =>
+ loadPluginDirectory(directory).pipe(
+ Effect.flatMap((registration) =>
+ digestPluginSource(registration.directory, sourceLimits).pipe(
+ Effect.map((source) => ({ _tag: "ok" as const, registration, source })),
+ ),
+ ),
+ Effect.catch((error) => Effect.succeed({ _tag: "failed" as const, reason: error.reason })),
+ Effect.provideService(FileSystem.FileSystem, fileSystem),
+ Effect.provideService(Path.Path, path),
+ );
+
+ const isReady = (record: PluginInstallationRecord) =>
+ pluginInstallationStatus({ ...record, enabled: true }) === "enabled";
+
+ // Revocation starts immediately; retries share the original stop fiber and cannot stop a replacement registration.
+ const unregister = Effect.fnUntraced(function* (installation: Installation) {
+ const registered = installation.registered;
+ if (registered === undefined) return installation.stopping;
+ installation.registered = undefined;
+ revision++;
+ const stopping = yield* supervisor
+ .disable(registered.pluginId)
+ .pipe(Effect.forkIn(scope, { startImmediately: true }));
+ installation.stopping = stopping;
+ exiting.set(stopping, installation.record.directory);
+ stopping.addObserver(() => exiting.delete(stopping));
+ return stopping;
+ });
+
+ /**
+ * Revokes the registration, saves `record` (normally with `enabled: false`),
+ * and waits for the process to exit. Everything but the wait finishes even
+ * if the caller goes away, so a disable that was cut short never comes
+ * back enabled at the next start. A failed save leaves the registration revoked, so changed bytes cannot run.
+ */
+ const revoke = (installation: Installation, record: PluginInstallationRecord) =>
+ Effect.uninterruptibleMask((restore) =>
+ Effect.gen(function* () {
+ const stopping = yield* unregister(installation);
+ if (record !== installation.record || installation.unsaved)
+ yield* commit(installation, record).pipe(
+ Effect.tapError(() =>
+ Effect.sync(() => {
+ installation.record = record;
+ installation.unsaved = true;
+ revision++;
+ }),
+ ),
+ );
+ if (stopping) yield* restore(Fiber.join(stopping));
+ }),
+ );
+
+ /**
+ * Inspects the directory again and records the result. An enabled
+ * installation whose bytes no longer match its consent is stopped and
+ * disabled.
+ */
+ const reinspect = Effect.fnUntraced(function* (installation: Installation) {
+ const inspection = yield* inspect(installation.record.directory);
+ const current = installation.record;
+ const found =
+ inspection._tag === "ok"
+ ? {
+ manifest: summarizePluginManifest(inspection.registration.manifest),
+ source: inspection.source,
+ problem: null,
+ }
+ : { manifest: current.manifest, source: null, problem: inspection.reason };
+ // The same result keeps the record as it was, `inspectedAt` included.
+ if (
+ Equal.equals(found, {
+ manifest: current.manifest,
+ source: current.source,
+ problem: current.problem,
+ })
+ ) {
+ if (installation.unsaved) yield* commit(installation, current);
+ return inspection;
+ }
+ const record: PluginInstallationRecord = { ...current, ...found, inspectedAt: yield* now };
+ if (record.enabled && !isReady(record)) {
+ yield* Effect.logWarning("Plugin source changed; disabling until consent is renewed", {
+ installationId: record.installationId,
+ directory: record.directory,
+ });
+ yield* revoke(installation, { ...record, enabled: false });
+ } else {
+ yield* commit(installation, record);
+ }
+ return inspection;
+ });
+
+ /**
+ * Registers a ready installation with the supervisor under a new generation
+ * and saves it as enabled. Both happen or neither, even if the caller is
+ * interrupted.
+ */
+ const register = Effect.fnUntraced(function* (
+ installation: Installation,
+ registration: PluginRegistration,
+ ) {
+ const pluginId = registration.manifest.id;
+ const holder = [...installations.values()].find(
+ (other) => other !== installation && other.registered?.pluginId === pluginId,
+ );
+ if (holder)
+ return yield* catalogError(
+ "plugin-id-conflict",
+ `Another enabled plugin already uses the id ${pluginId} (${holder.record.directory}). Disable it first.`,
+ installation.record.installationId,
+ );
+ yield* supervisor
+ .enable({ ...registration, installationId: installation.record.installationId })
+ .pipe(
+ Effect.mapError(() =>
+ catalogError(
+ "plugin-id-conflict",
+ `A plugin with the id ${pluginId} is already running.`,
+ installation.record.installationId,
+ ),
+ ),
+ );
+ const record = {
+ ...installation.record,
+ enabled: true,
+ generation: installation.record.generation + 1,
+ };
+ yield* saveEnabled(record, registration.manifest.capabilities).pipe(
+ Effect.tapError(() => supervisor.disable(pluginId)),
+ );
+ // Together, so an invoke never sees the new registration with the old generation.
+ installation.record = record;
+ installation.registered = { pluginId, generation: record.generation };
+ revision++;
+ }, Effect.uninterruptible);
+
+ const find = (installationId: PluginInstallationId) =>
+ Effect.suspend(() => {
+ const installation = installations.get(installationId);
+ return installation
+ ? Effect.succeed(installation)
+ : Effect.fail(
+ catalogError("not-found", "That plugin is not installed here.", installationId),
+ );
+ });
+
+ const toWire = Effect.fnUntraced(function* (installation: Installation) {
+ const { replacement: _replacement, ...record } = installation.record;
+ const registered = installation.registered;
+ if (registered === undefined) return record;
+ const hostState = yield* supervisor.state(registered.pluginId);
+ const eventDelivery = Option.isSome(eventDeliveries)
+ ? yield* eventDeliveries.value.state(
+ installation.record.installationId,
+ registered.generation,
+ )
+ : Option.none();
+ const wire: PluginInstallation = {
+ ...record,
+ ...(Option.isSome(hostState) ? { hostState: hostState.value } : {}),
+ ...(Option.isSome(eventDelivery) ? { eventDelivery: eventDelivery.value } : {}),
+ };
+ return wire;
+ });
+
+ const list = Effect.suspend(() =>
+ Effect.forEach(
+ [...installations.values()].sort(
+ (a, b) =>
+ a.record.addedAt.localeCompare(b.record.addedAt) ||
+ a.record.installationId.localeCompare(b.record.installationId),
+ ),
+ toWire,
+ ),
+ ).pipe(Effect.map((installations) => ({ installations })));
+
+ const result = (installation: Installation) =>
+ toWire(installation).pipe(Effect.map((wire) => ({ installation: wire })));
+
+ /** Runs a management step under the lock and tells subscribers if it changed anything, even when it then failed. */
+ const managed = (effect: Effect.Effect) =>
+ lock.withPermit(
+ Effect.suspend(() => {
+ const before = revision;
+ return effect.pipe(
+ Effect.ensuring(Effect.suspend(() => (revision === before ? Effect.void : notify))),
+ );
+ }),
+ );
+
+ const add = Effect.fn("PluginCatalog.add")(function* (input: PluginAddInput) {
+ if (!path.isAbsolute(input.directory))
+ return yield* catalogError(
+ "invalid-directory",
+ "Enter the plugin directory's absolute path on the server's machine.",
+ );
+ const inspection = yield* inspect(input.directory);
+ if (inspection._tag === "failed")
+ return yield* catalogError("invalid-directory", inspection.reason);
+ const directory = inspection.registration.directory;
+ const existing = [...installations.values()].find(
+ (installation) => installation.record.directory === directory,
+ );
+ if (existing)
+ return yield* catalogError(
+ "already-added",
+ `${directory} is already installed.`,
+ existing.record.installationId,
+ );
+ const installationId = PluginInstallationId.make(
+ yield* crypto.randomUUIDv4().pipe(Effect.orDie),
+ );
+ const at = yield* now;
+ const record: PluginInstallationRecord = {
+ installationId,
+ generation: 0,
+ directory,
+ manifest: summarizePluginManifest(inspection.registration.manifest),
+ source: inspection.source,
+ problem: null,
+ inspectedAt: at,
+ consent: null,
+ enabled: false,
+ addedAt: at,
+ };
+ const installation: Installation = { record, registered: undefined, stopping: undefined };
+ yield* save(record).pipe(
+ Effect.andThen(
+ Effect.sync(() => {
+ installations.set(installationId, installation);
+ revision++;
+ }),
+ ),
+ Effect.uninterruptible,
+ );
+ return yield* result(installation);
+ }, managed);
+
+ const refresh = Effect.fn("PluginCatalog.refresh")(function* (input: PluginRefreshInput) {
+ const targets =
+ input.installationId === undefined
+ ? [...installations.values()]
+ : [yield* find(input.installationId)];
+ yield* Effect.forEach(targets, reinspect, { discard: true });
+ return yield* list;
+ }, managed);
+
+ const consent = Effect.fn("PluginCatalog.consent")(function* (input: PluginConsentInput) {
+ const installation = yield* find(input.installationId);
+ const inspection = yield* reinspect(installation);
+ if (inspection._tag === "failed")
+ return yield* catalogError("unavailable", inspection.reason, input.installationId);
+ if (inspection.source.digest !== input.digest)
+ return yield* catalogError(
+ "source-changed",
+ "The plugin's files changed after they were reviewed. Review the current version.",
+ input.installationId,
+ );
+ yield* commit(installation, {
+ ...installation.record,
+ ...(installation.record.replacement?.digest === input.digest
+ ? { replacement: { ...installation.record.replacement, committed: true } }
+ : {}),
+ consent: {
+ digest: inspection.source.digest,
+ capabilities: inspection.registration.manifest.capabilities,
+ grantedAt: yield* now,
+ },
+ });
+ return yield* result(installation);
+ }, managed);
+
+ const enable = Effect.fn("PluginCatalog.enable")(function* (input: PluginInstallationInput) {
+ const installation = yield* find(input.installationId);
+ // A caller may have left disable while its process was still exiting.
+ if (installation.stopping) yield* Fiber.join(installation.stopping);
+ // Checked even when already enabled: changed bytes stop it and need consent again.
+ const inspection = yield* reinspect(installation);
+ if (inspection._tag === "failed")
+ return yield* catalogError("unavailable", inspection.reason, input.installationId);
+ if (!isReady(installation.record))
+ return yield* catalogError(
+ "consent-required",
+ installation.record.consent === null
+ ? "Review and approve the plugin before enabling it."
+ : "The plugin's files changed since they were approved. Review the current version.",
+ input.installationId,
+ );
+ // Already enabled with these bytes: keep the registration and its generation.
+ if (installation.registered !== undefined) return yield* result(installation);
+ yield* register(installation, inspection.registration);
+ return yield* result(installation);
+ }, managed);
+
+ const disableInstallation = (installation: Installation) =>
+ revoke(
+ installation,
+ installation.record.enabled
+ ? { ...installation.record, enabled: false }
+ : installation.record,
+ );
+
+ const overlaps = (a: string, b: string) =>
+ a === b || a.startsWith(`${b}${path.sep}`) || b.startsWith(`${a}${path.sep}`);
+
+ /**
+ * The one rule for moving or deleting files under `paths`, run inside a
+ * management step: no installation but `owner` may be rooted in or around
+ * them, `owner` is disabled, and every process that ran from files there
+ * has exited before this returns.
+ */
+ const claimFiles = Effect.fnUntraced(function* (
+ paths: ReadonlyArray,
+ owner?: Installation,
+ ) {
+ const other = [...installations.values()].find(
+ (installation) =>
+ installation !== owner &&
+ paths.some((target) => overlaps(target, installation.record.directory)),
+ );
+ if (other)
+ return yield* catalogError(
+ "already-added",
+ `${other.record.directory} is installed as a plugin, so its files were left in place.`,
+ other.record.installationId,
+ );
+ if (owner) yield* disableInstallation(owner);
+ yield* Effect.forEach(
+ [...exiting].filter(([, directory]) => paths.some((target) => overlaps(target, directory))),
+ ([stopping]) => Fiber.await(stopping),
+ { discard: true },
+ );
+ });
+
+ const disable = Effect.fn("PluginCatalog.disable")(function* (input: PluginInstallationInput) {
+ const installation = yield* find(input.installationId);
+ yield* disableInstallation(installation);
+ return yield* result(installation);
+ }, managed);
+
+ const remove = Effect.fn("PluginCatalog.remove")(function* (input: PluginInstallationInput) {
+ const installation = yield* find(input.installationId);
+ // Forgotten durably first, like disable, so an interrupted remove does not come back.
+ yield* Effect.uninterruptibleMask((restore) =>
+ Effect.gen(function* () {
+ yield* sql`DELETE FROM plugin_installations WHERE installation_id = ${input.installationId}`.pipe(
+ Effect.catch(storageError),
+ );
+ installations.delete(input.installationId);
+ revision++;
+ const stopping = yield* unregister(installation);
+ if (stopping) yield* restore(Fiber.join(stopping));
+ }),
+ );
+ return { installationId: input.installationId };
+ }, managed);
+
+ const replace = Effect.fn("PluginCatalog.replace")(
+ function* (
+ input: PluginConsentInput & { readonly attemptId?: string },
+ files: Parameters[1],
+ ) {
+ const installation = yield* find(input.installationId);
+ const wasEnabled = installation.record.enabled;
+ yield* claimFiles([installation.record.directory, ...files.paths], installation);
+ yield* commit(installation, {
+ ...installation.record,
+ replacement: {
+ digest: input.digest,
+ committed: false,
+ ...(input.attemptId === undefined ? {} : { attemptId: input.attemptId }),
+ },
+ });
+ const enableAgain = (inspection: Inspection) =>
+ wasEnabled && inspection._tag === "ok" && isReady(installation.record)
+ ? register(installation, inspection.registration)
+ : Effect.void;
+ const inspection = yield* files.swap.pipe(
+ Effect.andThen(reinspect(installation)),
+ Effect.filterOrFail(
+ (inspection): inspection is Extract =>
+ inspection._tag === "ok" && inspection.source.digest === input.digest,
+ () =>
+ catalogError(
+ "source-changed",
+ "The new files changed after they were reviewed, so the old ones were put back.",
+ input.installationId,
+ ),
+ ),
+ Effect.tap((inspection) =>
+ Effect.gen(function* () {
+ yield* commit(installation, {
+ ...installation.record,
+ replacement: {
+ digest: inspection.source.digest,
+ committed: true,
+ ...(input.attemptId === undefined ? {} : { attemptId: input.attemptId }),
+ },
+ consent: {
+ digest: inspection.source.digest,
+ capabilities: inspection.registration.manifest.capabilities,
+ grantedAt: yield* now,
+ },
+ });
+ }),
+ ),
+ Effect.tapError(() =>
+ files.restore.pipe(
+ Effect.andThen(reinspect(installation)),
+ Effect.flatMap(enableAgain),
+ Effect.catch((error) =>
+ Effect.logWarning("Could not put a plugin's old files back", {
+ installationId: input.installationId,
+ detail: error.message,
+ }),
+ ),
+ ),
+ ),
+ );
+ yield* enableAgain(inspection);
+ return yield* result(installation);
+ },
+ Effect.uninterruptible,
+ managed,
+ );
+
+ const settleReplace = Effect.fn("PluginCatalog.settleReplace")(
+ function* (
+ input: PluginConsentInput & { readonly attemptId?: string },
+ files: Parameters[1],
+ ) {
+ const installation = yield* find(input.installationId);
+ // New journals must match this attempt; only legacy journals use digest/consent recovery.
+ const replacement = installation.record.replacement;
+ const committed =
+ input.attemptId !== undefined
+ ? replacement?.attemptId === input.attemptId &&
+ replacement.digest === input.digest &&
+ replacement.committed
+ : replacement?.digest === input.digest
+ ? replacement.committed
+ : installation.record.consent?.digest === input.digest;
+ if (committed) return "committed" as const;
+ if (files !== undefined) {
+ yield* claimFiles([installation.record.directory, ...files.paths], installation);
+ yield* files.restore;
+ yield* reinspect(installation);
+ }
+ return "rolled-back" as const;
+ },
+ Effect.uninterruptible,
+ managed,
+ );
+
+ const changeFiles: PluginCatalog["Service"]["changeFiles"] = Effect.fn(
+ "PluginCatalog.changeFiles",
+ )(
+ function* (paths: ReadonlyArray, effect: Effect.Effect) {
+ yield* claimFiles(paths);
+ return yield* effect;
+ },
+ Effect.uninterruptible,
+ managed,
+ );
+
+ const resume = Effect.fn("PluginCatalog.resume")(function* (input: PluginInstallationInput) {
+ const installation = yield* find(input.installationId);
+ if (installation.registered === undefined)
+ return yield* catalogError("unavailable", "The plugin is not enabled.", input.installationId);
+ yield* supervisor.resume(installation.registered.pluginId).pipe(Effect.ignore);
+ if (Option.isSome(eventDeliveries)) yield* eventDeliveries.value.resume(input.installationId);
+ return yield* result(installation);
+ }, managed);
+
+ /**
+ * Re-checks that `registered` is still this installation's registration and, unless the call
+ * would start a fresh process with unchecked bytes, hands the call to the supervisor. It runs
+ * in a fiber that starts synchronously, so no management step can revoke or replace the
+ * registration between the check and the supervisor admitting the call.
+ */
+ const admit = (
+ installation: Installation,
+ registered: Registration,
+ verified: string | undefined,
+ call: (pluginId: PluginId) => Effect.Effect,
+ ) =>
+ Effect.uninterruptibleMask((restore) =>
+ Effect.forkChild(
+ Effect.suspend((): Effect.Effect => {
+ if (
+ installations.get(installation.record.installationId) !== installation ||
+ installation.registered !== registered ||
+ installation.record.consent === null
+ )
+ return Effect.succeed({ _tag: "revoked" });
+ const consented = installation.record.consent.digest;
+ return supervisor
+ .state(registered.pluginId)
+ .pipe(
+ Effect.flatMap((state): Effect.Effect =>
+ Option.isSome(state) && state.value._tag === "idle" && verified !== consented
+ ? Effect.succeed({ _tag: "check", consented })
+ : call(registered.pluginId).pipe(
+ Effect.map((value) => ({ _tag: "called", value })),
+ ),
+ ),
+ );
+ }),
+ { startImmediately: true },
+ ).pipe(
+ Effect.flatMap((fiber) =>
+ restore(Fiber.join(fiber)).pipe(Effect.onInterrupt(() => Fiber.interrupt(fiber))),
+ ),
+ ),
+ );
+
+ const invoke: PluginCatalog["Service"]["invoke"] = Effect.fn("PluginCatalog.invoke")(
+ function* (installationId, handler, input, options) {
+ // A call right after a restart waits for its installation to be registered again.
+ yield* Deferred.await(restored).pipe(Effect.timeoutOption(STARTUP_RESTORE_WAIT));
+ const installation = yield* find(installationId);
+ const registered = installation.registered;
+ if (registered === undefined)
+ return yield* catalogError("unavailable", "The plugin is not enabled.", installationId);
+ if (options?.generation !== undefined && options.generation !== registered.generation)
+ return yield* catalogError(
+ "generation-changed",
+ "The plugin was enabled again since this call was prepared.",
+ installationId,
+ );
+ const call = (pluginId: PluginId) =>
+ supervisor.invoke(
+ pluginId,
+ handler,
+ input,
+ options?.timeout === undefined ? undefined : { timeout: options.timeout },
+ );
+ let verified: string | undefined;
+ while (true) {
+ const admission = yield* admit(installation, registered, verified, call);
+ if (admission._tag === "called") return admission.value;
+ if (admission._tag === "revoked")
+ return yield* catalogError(
+ "unavailable",
+ "The plugin was disabled or replaced before the call started.",
+ installationId,
+ );
+ const inspection = yield* inspect(installation.record.directory);
+ if (inspection._tag === "ok" && inspection.source.digest === admission.consented) {
+ verified = admission.consented;
+ continue;
+ }
+ // Skip the record if it was disabled or removed meanwhile, so it is not written back.
+ yield* managed(
+ Effect.suspend(() =>
+ installations.get(installationId) === installation &&
+ installation.registered === registered
+ ? reinspect(installation)
+ : Effect.void,
+ ),
+ );
+ return yield* catalogError(
+ "source-changed",
+ "The plugin's files changed since they were approved, so it was disabled.",
+ installationId,
+ );
+ }
+ },
+ );
+
+ // Load what was installed before this start.
+ const rows = yield* sql<{ readonly record_json: string }>`
+ SELECT record_json FROM plugin_installations
+ `.pipe(Effect.orDie);
+ for (const row of rows) {
+ const decoded = yield* decodeRecord(row.record_json).pipe(Effect.option);
+ if (Option.isNone(decoded)) {
+ yield* Effect.logWarning("Skipping an unreadable plugin installation row");
+ continue;
+ }
+ installations.set(decoded.value.installationId, {
+ record: decoded.value,
+ registered: undefined,
+ stopping: undefined,
+ });
+ }
+
+ // Plugin state changes reach subscribers as fresh snapshots.
+ const supervisorEvents = yield* supervisor.subscribe;
+ yield* Stream.fromSubscription(supervisorEvents).pipe(
+ Stream.filter((event) => event._tag === "StateChanged"),
+ Stream.runForEach(() => notify),
+ Effect.forkScoped,
+ );
+
+ // So do changes of event delivery state.
+ if (Option.isSome(eventDeliveries)) {
+ const deliveryChanges = yield* eventDeliveries.value.changes;
+ yield* Stream.fromSubscription(deliveryChanges).pipe(
+ Stream.runForEach(() => notify),
+ Effect.forkScoped,
+ );
+ }
+
+ // Re-register what was enabled, off the startup path. Changed bytes are disabled here;
+ // nothing starts a process until it is used. Starting at once takes the lock before this
+ // returns, so no management step can act on an installation still waiting to be restored.
+ yield* managed(
+ Effect.forEach(
+ [...installations.values()].filter((installation) => installation.record.enabled),
+ (installation) =>
+ reinspect(installation).pipe(
+ Effect.flatMap((inspection) =>
+ inspection._tag === "ok" && installation.record.enabled
+ ? register(installation, inspection.registration)
+ : Effect.void,
+ ),
+ Effect.catch((error) =>
+ Effect.logWarning("Could not re-enable a plugin at startup", {
+ installationId: installation.record.installationId,
+ detail: error.message,
+ }).pipe(Effect.andThen(disableInstallation(installation).pipe(Effect.ignore))),
+ ),
+ ),
+ { discard: true },
+ ),
+ ).pipe(
+ Effect.ensuring(Deferred.succeed(restored, undefined)),
+ Effect.forkIn(scope, { startImmediately: true }),
+ );
+
+ return PluginCatalog.of({
+ list,
+ ready: Deferred.await(restored),
+ revision: Effect.sync(() => revision),
+ subscribe: Stream.unwrap(
+ // Subscribe before the first snapshot so a change in between is not lost.
+ PubSub.subscribe(changes).pipe(
+ Effect.map((subscription) =>
+ Stream.concat(
+ Stream.fromEffect(list),
+ Stream.fromSubscription(subscription).pipe(Stream.mapEffect(() => list)),
+ ).pipe(
+ // A plugin state event and the step that caused it can describe the same snapshot.
+ Stream.changes,
+ ),
+ ),
+ ),
+ ),
+ add,
+ refresh,
+ consent,
+ enable,
+ disable,
+ remove,
+ resume,
+ replace,
+ settleReplace,
+ changeFiles,
+ invoke,
+ });
+});
+
+export const layer = (sourceLimits?: PluginSourceLimits) =>
+ Layer.effect(PluginCatalog, make(sourceLimits));
diff --git a/apps/server/src/plugins/PluginCatalogRpc.test.ts b/apps/server/src/plugins/PluginCatalogRpc.test.ts
new file mode 100644
index 0000000000000..9cd64fc3d4301
--- /dev/null
+++ b/apps/server/src/plugins/PluginCatalogRpc.test.ts
@@ -0,0 +1,147 @@
+import {
+ AuthAccessWriteScope,
+ type AuthEnvironmentScope,
+ AuthOrchestrationReadScope,
+ AuthRelayReadScope,
+ AuthStandardClientScopes,
+ PluginCatalogError,
+ PluginInstallationId,
+ WS_METHODS,
+ WsRpcGroup,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Stream from "effect/Stream";
+import * as RpcTest from "effect/rpc/RpcTest";
+
+import { RPC_REQUIRED_SCOPES } from "../auth/RpcAuthorization.ts";
+import * as RpcAuthorization from "../auth/RpcAuthorization.ts";
+
+const reads = [WS_METHODS.pluginsList, WS_METHODS.pluginsSubscribe] as const;
+const writes = [
+ WS_METHODS.pluginsAdd,
+ WS_METHODS.pluginsRefresh,
+ WS_METHODS.pluginsConsent,
+ WS_METHODS.pluginsEnable,
+ WS_METHODS.pluginsDisable,
+ WS_METHODS.pluginsRemove,
+ WS_METHODS.pluginsResume,
+] as const;
+type PluginMethod = (typeof reads)[number] | (typeof writes)[number];
+const pluginMethods: ReadonlySet = new Set([...reads, ...writes]);
+
+const group = WsRpcGroup.omit(
+ ...[...WsRpcGroup.requests.keys()].filter(
+ (tag): tag is Exclude =>
+ !pluginMethods.has(tag),
+ ),
+);
+
+const installationId = PluginInstallationId.make("fixture");
+const digest = `sha256:${"0".repeat(64)}`;
+
+/** Serves the plugin RPCs through the real scope middleware; handlers record that they ran. */
+const makeClient = (scopes: ReadonlyArray, handled: Array) => {
+ // Mutations answer with a catalogue error: reaching it proves the middleware let the call in.
+ const mutation = (method: string) => () =>
+ Effect.sync(() => handled.push(method)).pipe(
+ Effect.andThen(
+ Effect.fail(new PluginCatalogError({ reason: "not-found", message: "fixture" })),
+ ),
+ );
+ return RpcTest.makeClient(group).pipe(
+ Effect.provide(
+ Layer.mergeAll(
+ group.toLayerHandler(WS_METHODS.pluginsList, () =>
+ Effect.sync(() => handled.push(WS_METHODS.pluginsList)).pipe(
+ Effect.as({ installations: [] }),
+ ),
+ ),
+ group.toLayerHandler(WS_METHODS.pluginsSubscribe, () =>
+ Stream.fromEffect(
+ Effect.sync(() => handled.push(WS_METHODS.pluginsSubscribe)).pipe(
+ Effect.as({ installations: [] }),
+ ),
+ ),
+ ),
+ group.toLayerHandler(WS_METHODS.pluginsAdd, mutation(WS_METHODS.pluginsAdd)),
+ group.toLayerHandler(WS_METHODS.pluginsRefresh, mutation(WS_METHODS.pluginsRefresh)),
+ group.toLayerHandler(WS_METHODS.pluginsConsent, mutation(WS_METHODS.pluginsConsent)),
+ group.toLayerHandler(WS_METHODS.pluginsEnable, mutation(WS_METHODS.pluginsEnable)),
+ group.toLayerHandler(WS_METHODS.pluginsDisable, mutation(WS_METHODS.pluginsDisable)),
+ group.toLayerHandler(WS_METHODS.pluginsRemove, mutation(WS_METHODS.pluginsRemove)),
+ group.toLayerHandler(WS_METHODS.pluginsResume, mutation(WS_METHODS.pluginsResume)),
+ RpcAuthorization.layer(scopes),
+ ),
+ ),
+ );
+};
+
+/** Calls every management RPC and returns the tag each one failed with. */
+const callWrites = (client: Effect.Success>) =>
+ Effect.all([
+ client[WS_METHODS.pluginsAdd]({ directory: "/plugins/fixture" }).pipe(Effect.flip),
+ client[WS_METHODS.pluginsRefresh]({}).pipe(Effect.flip),
+ client[WS_METHODS.pluginsConsent]({ installationId, digest }).pipe(Effect.flip),
+ client[WS_METHODS.pluginsEnable]({ installationId }).pipe(Effect.flip),
+ client[WS_METHODS.pluginsDisable]({ installationId }).pipe(Effect.flip),
+ client[WS_METHODS.pluginsRemove]({ installationId }).pipe(Effect.flip),
+ client[WS_METHODS.pluginsResume]({ installationId }).pipe(Effect.flip),
+ ]);
+
+describe("plugin RPC scopes", () => {
+ it.effect("lets a read-only pairing read the catalogue but not change what runs", () =>
+ Effect.gen(function* () {
+ const handled: Array = [];
+ const client = yield* makeClient([AuthOrchestrationReadScope], handled);
+
+ expect(yield* client[WS_METHODS.pluginsList]({})).toEqual({ installations: [] });
+ expect(
+ yield* client[WS_METHODS.pluginsSubscribe]({}).pipe(Stream.take(1), Stream.runCollect),
+ ).toEqual([{ installations: [] }]);
+
+ const failures = yield* callWrites(client);
+ for (const failure of failures) {
+ expect(failure).toMatchObject({
+ _tag: "EnvironmentAuthorizationError",
+ requiredScope: AuthAccessWriteScope,
+ requiredPermission: AuthAccessWriteScope,
+ });
+ }
+ expect(handled).toEqual([WS_METHODS.pluginsList, WS_METHODS.pluginsSubscribe]);
+ }).pipe(Effect.scoped),
+ );
+
+ it.effect("lets a standard pairing manage plugins", () =>
+ Effect.gen(function* () {
+ const handled: Array = [];
+ const client = yield* makeClient(AuthStandardClientScopes, handled);
+
+ const failures = yield* callWrites(client);
+ for (const failure of failures) expect(failure._tag).toBe("PluginCatalogError");
+ expect(handled).toEqual([...writes]);
+ }).pipe(Effect.scoped),
+ );
+
+ it.effect("refuses catalogue reads without the orchestration read scope", () =>
+ Effect.gen(function* () {
+ const handled: Array = [];
+ const client = yield* makeClient([AuthRelayReadScope], handled);
+
+ expect(yield* client[WS_METHODS.pluginsList]({}).pipe(Effect.flip)).toMatchObject({
+ _tag: "EnvironmentAuthorizationError",
+ requiredScope: AuthOrchestrationReadScope,
+ requiredPermission: AuthOrchestrationReadScope,
+ });
+ expect(
+ yield* client[WS_METHODS.pluginsSubscribe]({}).pipe(Stream.runCollect, Effect.flip),
+ ).toMatchObject({
+ _tag: "EnvironmentAuthorizationError",
+ requiredScope: AuthOrchestrationReadScope,
+ requiredPermission: AuthOrchestrationReadScope,
+ });
+ expect(handled).toEqual([]);
+ }).pipe(Effect.scoped),
+ );
+});
diff --git a/apps/server/src/plugins/PluginEventDelivery.ts b/apps/server/src/plugins/PluginEventDelivery.ts
new file mode 100644
index 0000000000000..b5f6a580b4f02
--- /dev/null
+++ b/apps/server/src/plugins/PluginEventDelivery.ts
@@ -0,0 +1,116 @@
+/**
+ * The part of plugin event delivery that the plugin catalogue calls into. It
+ * lets the catalogue start a plugin's event cursor, show how delivery is
+ * going, and resume it, without depending on the event feed, which itself
+ * depends on the catalogue.
+ */
+import {
+ PLUGIN_EVENTS_CAPABILITY,
+ type PluginEventDeliveryState,
+ type PluginInstallationId,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Equal from "effect/Equal";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as PubSub from "effect/PubSub";
+import type * as Scope from "effect/Scope";
+import * as SqlClient from "effect/sql/SqlClient";
+import type * as SqlError from "effect/sql/SqlError";
+
+export class PluginEventDelivery extends Context.Service<
+ PluginEventDelivery,
+ {
+ // Starts at the event-log end in the enabling transaction; re-enables and restarts retain the cursor.
+ readonly begin: (
+ installationId: PluginInstallationId,
+ capabilities: ReadonlyArray,
+ ) => Effect.Effect;
+ /** The delivery state of one registration, if the feed reported one. */
+ readonly state: (
+ installationId: PluginInstallationId,
+ generation: number,
+ ) => Effect.Effect>;
+ /** Reports a registration's state; `undefined` when it no longer delivers. */
+ readonly report: (
+ installationId: PluginInstallationId,
+ generation: number,
+ state: PluginEventDeliveryState | undefined,
+ ) => Effect.Effect;
+ /** Signals each reported change of a state (never a cursor move). Sliding, 1. */
+ readonly changes: Effect.Effect, never, Scope.Scope>;
+ /** Restarts quarantined or retrying delivery from its cursor. Nothing else changes. */
+ readonly resume: (installationId: PluginInstallationId) => Effect.Effect;
+ /** Installs what `resume` runs, for as long as the scope is open. */
+ readonly handleResume: (
+ resume: (installationId: PluginInstallationId) => Effect.Effect,
+ ) => Effect.Effect;
+ }
+>()("t3/plugins/PluginEventDelivery") {}
+
+export const make = Effect.gen(function* () {
+ const sql = yield* SqlClient.SqlClient;
+ const states = new Map<
+ PluginInstallationId,
+ { readonly generation: number; readonly state: PluginEventDeliveryState }
+ >();
+ const changes = yield* PubSub.sliding(1);
+ let resume: ((installationId: PluginInstallationId) => Effect.Effect) | undefined;
+
+ return PluginEventDelivery.of({
+ begin: Effect.fn("PluginEventDelivery.begin")((installationId, capabilities) =>
+ capabilities.includes(PLUGIN_EVENTS_CAPABILITY)
+ ? Effect.gen(function* () {
+ // One statement, so the end it reads is the end when the row is written.
+ yield* sql`
+ INSERT INTO plugin_event_cursors (installation_id, acknowledged_sequence, updated_at)
+ SELECT ${installationId}, COALESCE(MAX(sequence), 0), ${DateTime.formatIso(yield* DateTime.now)}
+ FROM orchestration_events
+ WHERE application_event_version = 2
+ AND aggregate_kind = 'thread'
+ ON CONFLICT (installation_id) DO NOTHING
+ `;
+ })
+ : Effect.void,
+ ),
+ state: Effect.fn("PluginEventDelivery.state")((installationId, generation) =>
+ Effect.sync(() => {
+ const current = states.get(installationId);
+ return current?.generation === generation ? Option.some(current.state) : Option.none();
+ }),
+ ),
+ report: Effect.fn("PluginEventDelivery.report")((installationId, generation, state) =>
+ Effect.suspend(() => {
+ const current = states.get(installationId);
+ if (state === undefined) {
+ if (current?.generation !== generation) return Effect.void;
+ states.delete(installationId);
+ } else {
+ if (current?.generation === generation && Equal.equals(current.state, state))
+ return Effect.void;
+ states.set(installationId, { generation, state });
+ }
+ return PubSub.publish(changes, undefined).pipe(Effect.asVoid);
+ }),
+ ),
+ changes: PubSub.subscribe(changes),
+ resume: Effect.fn("PluginEventDelivery.resume")((installationId) =>
+ Effect.suspend(() => resume?.(installationId) ?? Effect.void),
+ ),
+ handleResume: Effect.fn("PluginEventDelivery.handleResume")((handler) =>
+ Effect.acquireRelease(
+ Effect.sync(() => {
+ resume = handler;
+ }),
+ () =>
+ Effect.sync(() => {
+ if (resume === handler) resume = undefined;
+ }),
+ ),
+ ),
+ });
+});
+
+export const layer = Layer.effect(PluginEventDelivery, make);
diff --git a/apps/server/src/plugins/PluginEventFeed.test.ts b/apps/server/src/plugins/PluginEventFeed.test.ts
new file mode 100644
index 0000000000000..0e723eb110957
--- /dev/null
+++ b/apps/server/src/plugins/PluginEventFeed.test.ts
@@ -0,0 +1,965 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { describe, expect, it } from "@effect/vitest";
+import {
+ EnvironmentId,
+ EventId,
+ PluginCatalogError,
+ type PluginCatalogSnapshot,
+ type PluginEventDeliveryState,
+ PluginInstallationId,
+ ProjectId,
+ ProviderInstanceId,
+ RunId,
+ ThreadId,
+} from "@t3tools/contracts";
+import * as HostProcess from "@t3tools/shared/HostProcess";
+import * as DateTime from "effect/DateTime";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as PubSub from "effect/PubSub";
+import * as Queue from "effect/Queue";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import * as SqlClient from "effect/sql/SqlClient";
+import * as TestClock from "effect/testing/TestClock";
+
+import { ServerEnvironment } from "../environment/ServerEnvironment.ts";
+import * as EventSink from "../orchestration-v2/EventSink.ts";
+import * as EventStore from "../orchestration-v2/EventStore.ts";
+import { LiveStreamBufferError } from "../orchestration-v2/LiveStreamBudget.ts";
+import * as ProjectionStore from "../orchestration-v2/ProjectionStore.ts";
+import * as SqlitePersistence from "../persistence/Sqlite.ts";
+import * as PluginCatalog from "./PluginCatalog.ts";
+import * as PluginEventDelivery from "./PluginEventDelivery.ts";
+import * as PluginEventFeed from "./PluginEventFeed.ts";
+import * as PluginManifestLoader from "./PluginManifestLoader.ts";
+import * as PluginSupervisor from "./PluginSupervisor.ts";
+
+// Children run the real CLI entry, which routes `__plugin-host` to the child runtime.
+const BIN_PATH = `${import.meta.dirname}/../bin.ts`;
+
+const environmentId = EnvironmentId.make("environment:plugin-events");
+const threadId = ThreadId.make("thread:plugin-events");
+const projectId = ProjectId.make("project:plugin-events");
+const providerInstanceId = ProviderInstanceId.make("codex");
+
+const toJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown));
+
+type Receipts = PubSub.Subscription;
+
+type Catalog = PluginCatalog.PluginCatalog["Service"];
+
+/** A catalogue whose snapshots the feed sees only once `observed` completes. */
+const observedAfter =
+ (observed: Deferred.Deferred) =>
+ (catalog: Catalog): Catalog => ({
+ ...catalog,
+ subscribe: Stream.unwrap(Deferred.await(observed).pipe(Effect.as(catalog.subscribe))),
+ });
+
+type Sink = EventSink.EventSinkV2["Service"];
+
+/**
+ * Starts a supervisor, catalogue and event feed in `scope`, as one server start
+ * would. `feedSees` changes the catalogue or event sink the feed sees.
+ */
+const startServer = Effect.fn("startServer")(function* (
+ scope: Scope.Scope,
+ options: Partial = {},
+ feedSees: {
+ readonly catalog?: (catalog: Catalog) => Catalog;
+ readonly eventSink?: (eventSink: Sink) => Sink;
+ readonly sql?: (sql: SqlClient.SqlClient) => SqlClient.SqlClient;
+ } = {},
+) {
+ const delivery = yield* PluginEventDelivery.make;
+ const supervisor = yield* PluginSupervisor.make({
+ heapLimitMb: 64,
+ activationTimeout: "10 seconds",
+ stopGrace: "1 second",
+ }).pipe(
+ Effect.provideService(HostProcess.Arguments, [process.execPath, BIN_PATH]),
+ Effect.provideService(Scope.Scope, scope),
+ );
+ const catalog = yield* PluginCatalog.make().pipe(
+ Effect.provideService(PluginSupervisor.PluginSupervisor, supervisor),
+ Effect.provideService(PluginEventDelivery.PluginEventDelivery, delivery),
+ Effect.provideService(Scope.Scope, scope),
+ );
+ const feed = yield* PluginEventFeed.make(options).pipe(
+ Effect.provideService(
+ SqlClient.SqlClient,
+ feedSees.sql?.(yield* SqlClient.SqlClient) ?? (yield* SqlClient.SqlClient),
+ ),
+ Effect.provideService(PluginCatalog.PluginCatalog, feedSees.catalog?.(catalog) ?? catalog),
+ Effect.provideService(
+ EventSink.EventSinkV2,
+ feedSees.eventSink?.(yield* EventSink.EventSinkV2) ?? (yield* EventSink.EventSinkV2),
+ ),
+ Effect.provideService(PluginEventDelivery.PluginEventDelivery, delivery),
+ Effect.provideService(
+ ServerEnvironment,
+ ServerEnvironment.of({
+ getEnvironmentId: Effect.succeed(environmentId),
+ getDescriptor: Effect.die("unused"),
+ }),
+ ),
+ Effect.provideService(Scope.Scope, scope),
+ );
+ const receipts: Receipts = yield* feed.subscribe.pipe(Effect.provideService(Scope.Scope, scope));
+ return { catalog, feed, receipts };
+});
+
+/**
+ * Writes a plugin that appends each event it handles to `events.log` next to
+ * its directory, and fails every event while a `fail` file exists there.
+ */
+const preparePlugin = Effect.fn("preparePlugin")(function* (id: string, onEvent = true) {
+ const fs = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-plugin-events-" });
+ const directory = path.join(root, "plugin");
+ yield* fs.makeDirectory(directory);
+ const log = path.join(root, "events.log");
+ const fail = path.join(root, "fail");
+ yield* fs.writeFileString(
+ path.join(directory, "main.mjs"),
+ [
+ `import * as NodeFS from "node:fs";`,
+ `export function activate(context) {`,
+ ` if (!${onEvent}) return;`,
+ ` context.proposed.onEvent((event) => {`,
+ ` if (NodeFS.existsSync(${toJson(fail)})) throw new Error("told to fail");`,
+ ` NodeFS.appendFileSync(${toJson(log)}, JSON.stringify(event) + "\\n");`,
+ ` });`,
+ `}`,
+ ``,
+ ].join("\n"),
+ );
+ yield* fs.writeFileString(
+ path.join(directory, "t3-plugin.json"),
+ toJson({
+ id,
+ name: id,
+ version: "1.0.0",
+ apiVersion: 1,
+ entry: "main.mjs",
+ capabilities: ["events"],
+ proposedApi: true,
+ }),
+ );
+ const handled = fs.exists(log).pipe(
+ Effect.flatMap((exists) => (exists ? fs.readFileString(log) : Effect.succeed(""))),
+ Effect.map((content) =>
+ content
+ .split("\n")
+ .filter((line) => line !== "")
+ .map((line) => JSON.parse(line) as Record),
+ ),
+ );
+ return {
+ directory,
+ handled,
+ failing: (on: boolean) => (on ? fs.writeFileString(fail, "") : fs.remove(fail)),
+ };
+});
+
+const install = Effect.fn("install")(function* (catalog: Catalog, directory: string) {
+ const { installation } = yield* catalog.add({ directory });
+ const installationId = installation.installationId;
+ yield* catalog.consent({ installationId, digest: installation.source!.digest });
+ yield* catalog.enable({ installationId });
+ return installationId;
+});
+
+/** Follows the event delivery states that catalogue subscribers see. */
+const deliveryStates = Effect.fn("deliveryStates")(function* (catalog: Catalog) {
+ const snapshots = yield* Queue.unbounded();
+ yield* catalog.subscribe.pipe(
+ Stream.runForEach((snapshot) => Queue.offer(snapshots, snapshot)),
+ Effect.forkScoped,
+ );
+ const stateOf = (snapshot: PluginCatalogSnapshot, installationId: PluginInstallationId) =>
+ snapshot.installations.find((installation) => installation.installationId === installationId)
+ ?.eventDelivery;
+ return {
+ /** Takes snapshots through the first that shows `tag`; returns each state that changed on the way. */
+ untilTag: (installationId: PluginInstallationId, tag: PluginEventDeliveryState["_tag"]) =>
+ Effect.gen(function* () {
+ const states: Array = [];
+ while (true) {
+ const state = stateOf(yield* Queue.take(snapshots), installationId);
+ if (state?._tag !== states.at(-1)?._tag) states.push(state);
+ if (state?._tag === tag) return states;
+ }
+ }),
+ /** Takes snapshots until one shows `tag` for the installation; earlier ones are dropped. */
+ next: (installationId: PluginInstallationId, tag: PluginEventDeliveryState["_tag"]) =>
+ Effect.gen(function* () {
+ while (true) {
+ const snapshot = yield* Queue.take(snapshots);
+ const state = snapshot.installations.find(
+ (installation) => installation.installationId === installationId,
+ )?.eventDelivery;
+ if (state?._tag === tag) return state;
+ }
+ }),
+ };
+});
+
+/** Takes receipts until one matches; earlier ones are dropped. */
+const next = (
+ receipts: Receipts,
+ tag: Tag,
+ installationId: PluginInstallationId,
+) =>
+ Effect.gen(function* () {
+ while (true) {
+ const receipt = yield* PubSub.take(receipts);
+ if (receipt._tag === tag && receipt.installationId === installationId)
+ return receipt as Extract