Skip to content

Commit f1e4ee0

Browse files
feat(server,web,mobile): let plugins send notifications
A plugin with the `notifications` capability (proposed API) can send short notifications. Web and desktop show them as toasts and mobile as a banner, with an "Open thread" action when the notification names a thread. The server keeps the newest 20 for 2 minutes in memory and sends that whole set on subscribe and after every change, so a client that reconnects shows what it missed exactly once and closes what was withdrawn meanwhile. A plugin's notifications are withdrawn when its process stops. Each process may send 5 at once, then one every 5 seconds. Subscribing needs orchestration:read. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent 441de4a commit f1e4ee0

33 files changed

Lines changed: 1888 additions & 5 deletions

‎apps/mobile/src/Stack.tsx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ import {
2929
type RenderFailureProps,
3030
} from "./components/RenderErrorBoundary";
3131
import { ArchivedThreadsRouteScreen } from "./features/archive/ArchivedThreadsRouteScreen";
32+
import { PluginNotificationBannerHost } from "./features/plugins/PluginNotificationBannerHost";
3233
import { useAgentNotificationNavigation } from "./features/agent-awareness/notificationNavigation";
3334
import { ConnectOnboardingRouteScreen } from "./features/cloud/ConnectOnboardingRouteScreen";
3435
import { useConnectOnboardingNavigation } from "./features/cloud/connectOnboardingNavigation";
@@ -636,6 +637,7 @@ function RootStackLayout(props: {
636637
{props.children}
637638
<HardwareKeyboardCommandOverlay />
638639
</AdaptiveWorkspaceLayout>
640+
<PluginNotificationBannerHost />
639641
</ExistingThreadSettingsRouteProvider>
640642
</HardwareKeyboardCommandProvider>
641643
);
Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
import { useAtomValue } from "@effect/atom-react";
2+
import { useLinkTo } from "@react-navigation/native";
3+
import {
4+
pluginNotificationChanges,
5+
pluginNotificationDescription,
6+
type PluginNotificationMark,
7+
type ReceivedPluginNotification,
8+
} from "@t3tools/client-runtime/state/plugin-notifications";
9+
import type { ContributionStatusTone, EnvironmentId } from "@t3tools/contracts";
10+
import { useCallback, useEffect, useRef, useState } from "react";
11+
import { Pressable, View } from "react-native";
12+
import { useSafeAreaInsets } from "react-native-safe-area-context";
13+
14+
import { AppText as Text } from "../../components/AppText";
15+
import { cn } from "../../lib/cn";
16+
import { useEnvironments } from "../../state/environments";
17+
import { pluginNotificationEnvironment } from "../../state/plugin-notifications";
18+
import {
19+
type Banner,
20+
queueBannerChanges,
21+
removeEnvironmentBanners,
22+
} from "./plugin-notification-banners";
23+
24+
const SHOWN_MS = 5_000;
25+
26+
const TONE_DOT_CLASS = {
27+
neutral: "bg-foreground-muted",
28+
info: "bg-adaptive-sky-600-400",
29+
success: "bg-adaptive-emerald-600-400",
30+
warning: "bg-adaptive-amber-700-400",
31+
error: "bg-adaptive-rose-600-400",
32+
} as const satisfies Record<ContributionStatusTone, string>;
33+
34+
/**
35+
* Plugin notifications as an in-app banner under the status bar, one at a
36+
* time for a few seconds each. Only notifications that arrive while the app
37+
* is open are shown; tapping one about a thread opens it, and a banner goes
38+
* away once the server no longer retains its notification (its plugin
39+
* stopped, it expired or was evicted, or the server restarted) or its
40+
* environment is removed.
41+
*/
42+
export function PluginNotificationBannerHost() {
43+
const { environments } = useEnvironments();
44+
const [queue, setQueue] = useState<ReadonlyArray<Banner>>([]);
45+
const onChanges = useCallback(
46+
(
47+
environmentId: EnvironmentId,
48+
show: ReadonlyArray<ReceivedPluginNotification>,
49+
keep: ReadonlySet<string>,
50+
) => setQueue((current) => queueBannerChanges(current, environmentId, show, keep)),
51+
[],
52+
);
53+
const onRemoved = useCallback(
54+
(environmentId: EnvironmentId) =>
55+
setQueue((current) => removeEnvironmentBanners(current, environmentId)),
56+
[],
57+
);
58+
const dismiss = useCallback(
59+
(banner: Banner) => setQueue((current) => current.filter((each) => each !== banner)),
60+
[],
61+
);
62+
const head = queue[0];
63+
64+
useEffect(() => {
65+
if (head === undefined) return;
66+
const timer = setTimeout(() => dismiss(head), SHOWN_MS);
67+
return () => clearTimeout(timer);
68+
}, [dismiss, head]);
69+
70+
return (
71+
<>
72+
{environments.map((environment) => (
73+
<EnvironmentPluginNotifications
74+
key={environment.environmentId}
75+
environmentId={environment.environmentId}
76+
onChanges={onChanges}
77+
onRemoved={onRemoved}
78+
/>
79+
))}
80+
{head === undefined ? null : <PluginNotificationBanner banner={head} onDone={dismiss} />}
81+
</>
82+
);
83+
}
84+
85+
function EnvironmentPluginNotifications(props: {
86+
readonly environmentId: EnvironmentId;
87+
readonly onChanges: (
88+
environmentId: EnvironmentId,
89+
show: ReadonlyArray<ReceivedPluginNotification>,
90+
keep: ReadonlySet<string>,
91+
) => void;
92+
readonly onRemoved: (environmentId: EnvironmentId) => void;
93+
}) {
94+
const { environmentId, onChanges, onRemoved } = props;
95+
const frame = useAtomValue(pluginNotificationEnvironment.frame(environmentId));
96+
// The newest notification seen; banners themselves live in the host's queue.
97+
const mark = useRef<PluginNotificationMark | undefined>(undefined);
98+
99+
// Unmounting means the environment was removed, so no later frame will drop its banners.
100+
useEffect(() => () => onRemoved(environmentId), [environmentId, onRemoved]);
101+
102+
useEffect(() => {
103+
const changes = pluginNotificationChanges(mark.current, frame);
104+
mark.current = changes.mark;
105+
onChanges(environmentId, changes.show, changes.keep);
106+
}, [environmentId, frame, onChanges]);
107+
108+
return null;
109+
}
110+
111+
function PluginNotificationBanner(props: {
112+
readonly banner: Banner;
113+
readonly onDone: (banner: Banner) => void;
114+
}) {
115+
const { banner, onDone } = props;
116+
const insets = useSafeAreaInsets();
117+
const linkTo = useLinkTo();
118+
const { threadId, title, tone } = banner.entry.notification;
119+
const description = pluginNotificationDescription(banner.entry);
120+
121+
return (
122+
<View
123+
pointerEvents="box-none"
124+
className="absolute inset-x-0 items-center px-3"
125+
style={{ top: insets.top + 4 }}
126+
>
127+
<Pressable
128+
accessibilityRole={threadId === undefined ? "button" : "link"}
129+
accessibilityLabel={`${title}. ${description}`}
130+
accessibilityHint={
131+
threadId === undefined ? "Dismisses the notification" : "Opens the thread"
132+
}
133+
className="w-full max-w-[480px] flex-row items-start gap-2.5 rounded-2xl border border-border-subtle bg-card-alt px-3.5 py-3 active:opacity-70"
134+
onPress={() => {
135+
onDone(banner);
136+
if (threadId !== undefined)
137+
linkTo(
138+
`/threads/${encodeURIComponent(banner.environmentId)}/${encodeURIComponent(threadId)}`,
139+
);
140+
}}
141+
>
142+
<View
143+
className={cn("mt-1.5 h-2 w-2 shrink-0 rounded-full", TONE_DOT_CLASS[tone ?? "neutral"])}
144+
/>
145+
<View className="min-w-0 flex-1">
146+
<Text numberOfLines={1} className="text-sm font-semibold text-foreground">
147+
{title}
148+
</Text>
149+
<Text numberOfLines={2} className="text-xs text-foreground-secondary">
150+
{description}
151+
</Text>
152+
</View>
153+
</Pressable>
154+
</View>
155+
);
156+
}
Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
import {
2+
pluginNotificationChanges,
3+
type PluginNotificationMark,
4+
} from "@t3tools/client-runtime/state/plugin-notifications";
5+
import { EnvironmentId, type PluginNotificationFrame } from "@t3tools/contracts";
6+
import { expect, it } from "vite-plus/test";
7+
8+
import {
9+
type Banner,
10+
queueBannerChanges,
11+
removeEnvironmentBanners,
12+
} from "./plugin-notification-banners";
13+
14+
const A = EnvironmentId.make("env-a");
15+
const B = EnvironmentId.make("env-b");
16+
17+
/** The same epoch and sequences in each environment, so only the environment differs. */
18+
const frame = (titles: ReadonlyArray<string>): PluginNotificationFrame => ({
19+
epoch: "epoch-1",
20+
notifications: titles.map((title, index) => ({
21+
sequence: index + 1,
22+
pluginId: "acme.notifier",
23+
pluginName: "Notifier",
24+
title,
25+
createdAt: "2026-10-04T00:00:00.000Z",
26+
})),
27+
});
28+
29+
/** Feeds frames through the shared helper as each environment's host component does. */
30+
function receive(
31+
queue: ReadonlyArray<Banner>,
32+
marks: Map<EnvironmentId, PluginNotificationMark | undefined>,
33+
environmentId: EnvironmentId,
34+
next: PluginNotificationFrame,
35+
) {
36+
const changes = pluginNotificationChanges(marks.get(environmentId), next);
37+
marks.set(environmentId, changes.mark);
38+
return queueBannerChanges(queue, environmentId, changes.show, changes.keep);
39+
}
40+
41+
const shown = (queue: ReadonlyArray<Banner>) =>
42+
queue.map((banner) => `${banner.environmentId}:${banner.entry.notification.title}`);
43+
44+
it("drops a removed environment's queued banners and keeps the others", () => {
45+
const marks = new Map<EnvironmentId, PluginNotificationMark | undefined>();
46+
let queue: ReadonlyArray<Banner> = [];
47+
queue = receive(queue, marks, A, frame([]));
48+
queue = receive(queue, marks, B, frame([]));
49+
queue = receive(queue, marks, A, frame(["a1", "a2"]));
50+
queue = receive(queue, marks, B, frame(["b1"]));
51+
expect(shown(queue)).toEqual(["env-a:a1", "env-a:a2", "env-b:b1"]);
52+
53+
queue = removeEnvironmentBanners(queue, A);
54+
expect(shown(queue)).toEqual(["env-b:b1"]);
55+
expect(removeEnvironmentBanners(queue, A)).toBe(queue);
56+
});
57+
58+
it("queues each notification once across reconnects and drops what left the set", () => {
59+
const marks = new Map<EnvironmentId, PluginNotificationMark | undefined>();
60+
let queue: ReadonlyArray<Banner> = [];
61+
// Launch: what the server already held is not news.
62+
queue = receive(queue, marks, A, frame(["old"]));
63+
expect(shown(queue)).toEqual([]);
64+
queue = receive(queue, marks, A, frame(["old", "first"]));
65+
// Back online after missing one, then a second reconnect with nothing new.
66+
queue = receive(queue, marks, A, frame(["old", "first", "missed"]));
67+
const settled = receive(queue, marks, A, frame(["old", "first", "missed"]));
68+
expect(settled).toBe(queue);
69+
expect(shown(queue)).toEqual(["env-a:first", "env-a:missed"]);
70+
// The plugin was disabled while the app was away: its banners go on reconnect.
71+
queue = receive(queue, marks, A, frame(["old"]));
72+
expect(shown(queue)).toEqual([]);
73+
});
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
import type { ReceivedPluginNotification } from "@t3tools/client-runtime/state/plugin-notifications";
2+
import type { EnvironmentId } from "@t3tools/contracts";
3+
4+
/** Banners waiting their turn; older ones are dropped past this. */
5+
const MAX_QUEUED_BANNERS = 5;
6+
7+
export interface Banner {
8+
readonly environmentId: EnvironmentId;
9+
readonly entry: ReceivedPluginNotification;
10+
}
11+
12+
/**
13+
* Applies one environment's frame: drops its banners the server no longer
14+
* retains and queues the new ones. Returns `queue` itself when nothing changed.
15+
*/
16+
export function queueBannerChanges(
17+
queue: ReadonlyArray<Banner>,
18+
environmentId: EnvironmentId,
19+
show: ReadonlyArray<ReceivedPluginNotification>,
20+
keep: ReadonlySet<string>,
21+
): ReadonlyArray<Banner> {
22+
const kept = queue.filter(
23+
(banner) => banner.environmentId !== environmentId || keep.has(banner.entry.key),
24+
);
25+
if (show.length === 0 && kept.length === queue.length) return queue;
26+
return [...kept, ...show.map((entry) => ({ environmentId, entry }))].slice(-MAX_QUEUED_BANNERS);
27+
}
28+
29+
/** Drops a removed environment's banners, which no later frame would. */
30+
export function removeEnvironmentBanners(
31+
queue: ReadonlyArray<Banner>,
32+
environmentId: EnvironmentId,
33+
): ReadonlyArray<Banner> {
34+
const kept = queue.filter((banner) => banner.environmentId !== environmentId);
35+
return kept.length === queue.length ? queue : kept;
36+
}
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
import { createPluginNotificationEnvironmentAtoms } from "@t3tools/client-runtime/state/plugin-notifications";
2+
3+
import { connectionAtomRuntime } from "../connection/runtime";
4+
import { serverEnvironment } from "./server";
5+
6+
export const pluginNotificationEnvironment = createPluginNotificationEnvironmentAtoms(
7+
connectionAtomRuntime,
8+
{ configValueAtom: serverEnvironment.configValueAtom },
9+
);

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -193,6 +193,7 @@ export const RPC_REQUIRED_SCOPES = {
193193
[WS_METHODS.worktreeSetupCancel]: AuthOrchestrationOperateScope,
194194
[WS_METHODS.subscribeResourceTelemetry]: AuthOrchestrationReadScope,
195195
[WS_METHODS.subscribeContributionStatus]: AuthOrchestrationReadScope,
196+
[WS_METHODS.pluginsNotificationsSubscribe]: AuthOrchestrationReadScope,
196197
[WS_METHODS.vcsRefreshStatus]: AuthOrchestrationReadScope,
197198
[WS_METHODS.vcsPull]: AuthOrchestrationOperateScope,
198199
[WS_METHODS.gitRunStackedAction]: AuthOrchestrationOperateScope,

‎apps/server/src/environment/ServerEnvironment.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -256,6 +256,7 @@ export const make = Effect.gen(function* () {
256256
pluginActions: true,
257257
pluginViews: true,
258258
pluginNpm: true,
259+
pluginNotifications: true,
259260
...(serverSelfUpdate === null ? {} : { serverSelfUpdate }),
260261
...(serverInstallation === null ? {} : { serverInstallation }),
261262
// V2 restart recovery uses the environment-owned opt-in. The old

‎apps/server/src/plugins/PluginManifestLoader.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import {
22
PLUGIN_API_VERSION,
33
PLUGIN_EVENTS_CAPABILITY,
44
PLUGIN_MANIFEST_FILE,
5+
PLUGIN_NOTIFICATIONS_CAPABILITY,
56
PLUGIN_SETTINGS_CAPABILITY,
67
PLUGIN_STATUS_CAPABILITY,
78
PLUGIN_TOOLS_CAPABILITY,
@@ -25,6 +26,7 @@ const SUPPORTED_PLUGIN_CAPABILITIES: ReadonlySet<PluginCapabilityName> = new Set
2526
"actions",
2627
PLUGIN_VIEWS_CAPABILITY,
2728
PLUGIN_STATUS_CAPABILITY,
29+
PLUGIN_NOTIFICATIONS_CAPABILITY,
2830
]);
2931

3032
const MAX_MANIFEST_BYTES = 64 * 1024;
@@ -129,8 +131,8 @@ export const loadPluginDirectory = Effect.fn("PluginManifestLoader.loadPluginDir
129131
const actionProblem = checkActions(manifest);
130132
if (actionProblem !== undefined) return yield* fail(actionProblem);
131133

132-
// Statuses are proposed API, so they only exist with the opt-in.
133-
for (const capability of [PLUGIN_STATUS_CAPABILITY])
134+
// Statuses and notifications are proposed API, so they only exist with the opt-in.
135+
for (const capability of [PLUGIN_STATUS_CAPABILITY, PLUGIN_NOTIFICATIONS_CAPABILITY])
134136
if (manifest.capabilities.includes(capability) && !manifest.proposedApi)
135137
return yield* fail(`the "${capability}" capability needs "proposedApi": true.`);
136138

0 commit comments

Comments
 (0)