Skip to content

Commit 8c89523

Browse files
kevlingoclaude
andcommitted
feat(server): let an agent ring the user with session_notify
Hooks fire for every agent, which is the wrong shape when sub-sessions report to one orchestrator and only that orchestrator should interrupt a person. This is a tool instead: the session that decides the user is needed is the session that rings, and nobody else does. A ping is a doorbell, not history. It publishes to an in-memory bus that a new subscribeAttention WebSocket stream fans out to every attached client, and nothing is written down: the reason the agent rang is already in its thread, and an event-sourced ping would ring again on the next reconnect replay. Clients drop a ping older than two minutes and never ring the same one twice, which is what makes a reconnect quiet. Each client answers in three ways, because no one of them is enough. A synthesised tone says "now" to someone in the room, a toast says which session is asking, and the desktop app raises a real Windows notification, which is the only part that survives a minimized window. Four sounds, picked in Settings under Integrations or named per call, and the whole thing is behind a switch that is server-authoritative like the other agent grants. Claude Opus 5 in T3 Code. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent 5299980 commit 8c89523

31 files changed

Lines changed: 902 additions & 5 deletions
Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
/**
2+
* ElectronNotification - OS notifications raised on behalf of an agent.
3+
*
4+
* The renderer can play a sound, but only the main process can put something in
5+
* the Windows Action Center, and that is the half that survives a minimized
6+
* window. Clicking the notification brings the app forward, since the whole
7+
* point of the ping is that the user is needed here.
8+
*
9+
* @module ElectronNotification
10+
*/
11+
import * as Context from "effect/Context";
12+
import * as Effect from "effect/Effect";
13+
import * as Layer from "effect/Layer";
14+
import * as Option from "effect/Option";
15+
import * as Electron from "electron";
16+
17+
import * as ElectronWindow from "./ElectronWindow.ts";
18+
19+
export interface DesktopNotificationInput {
20+
readonly title: string;
21+
readonly body: string;
22+
/**
23+
* The renderer already played the chosen tone, so the OS sound would be a
24+
* second, different noise on top of it. Left to the caller because a client
25+
* that could not play audio wants the opposite answer.
26+
*/
27+
readonly silent: boolean;
28+
}
29+
30+
export class ElectronNotification extends Context.Service<
31+
ElectronNotification,
32+
{
33+
/** Resolves false when the OS refuses notifications, so callers can say so. */
34+
readonly show: (input: DesktopNotificationInput) => Effect.Effect<boolean>;
35+
}
36+
>()("@t3tools/desktop/electron/ElectronNotification") {}
37+
38+
/** @public Service construction is part of the canonical Effect module API. */
39+
export const make = Effect.gen(function* () {
40+
const windows = yield* ElectronWindow.ElectronWindow;
41+
42+
return ElectronNotification.of({
43+
show: (input) =>
44+
Effect.gen(function* () {
45+
if (!Electron.Notification.isSupported()) {
46+
return false;
47+
}
48+
const notification = new Electron.Notification({
49+
title: input.title,
50+
body: input.body,
51+
silent: input.silent,
52+
});
53+
notification.on("click", () => {
54+
void Effect.runPromise(
55+
Effect.gen(function* () {
56+
const window = yield* windows.focusedMainOrFirst;
57+
if (Option.isNone(window)) return;
58+
yield* windows.reveal(window.value);
59+
}).pipe(Effect.provideService(ElectronWindow.ElectronWindow, windows)),
60+
);
61+
});
62+
notification.show();
63+
return true;
64+
}).pipe(
65+
// A notification that throws must never take the ping's caller with it:
66+
// the sound has already played and the agent is waiting on a result.
67+
Effect.catchCause((cause) =>
68+
Effect.logWarning("desktop notification failed", { cause }).pipe(Effect.as(false)),
69+
),
70+
),
71+
});
72+
});
73+
74+
export const layer = Layer.effect(ElectronNotification)(make);

‎apps/desktop/src/ipc/DesktopIpcHandlers.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ import {
4141
openSystemSettings,
4242
probeRemoteEditors,
4343
pickFolder,
44+
showAttentionNotification,
4445
pickProjectFavicon,
4546
pickThemeFiles,
4647
setTheme,
@@ -122,6 +123,7 @@ export const installDesktopIpcHandlers = Effect.fn("desktop.ipc.installHandlers"
122123
yield* ipc.handle(showContextMenu);
123124
yield* ipc.handle(openExternal);
124125
yield* ipc.handle(openSystemSettings);
126+
yield* ipc.handle(showAttentionNotification);
125127
yield* ipc.handle(probeRemoteEditors);
126128
yield* ipc.handle(getUpdateState);
127129
yield* ipc.handle(setUpdateChannel);

‎apps/desktop/src/ipc/channels.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,3 +105,4 @@ export const PREVIEW_RECORDING_SAVE_CHANNEL = "desktop:preview-recording-save";
105105
export const PREVIEW_RECORDING_FRAME_CHANNEL = "desktop:preview-recording-frame";
106106
export const PREVIEW_STATE_CHANGE_CHANNEL = "desktop:preview-state-change";
107107
export const PREVIEW_POINTER_EVENT_CHANNEL = "desktop:preview-pointer-event";
108+
export const SHOW_ATTENTION_NOTIFICATION_CHANNEL = "desktop:show-attention-notification";

‎apps/desktop/src/ipc/methods/window.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import {
66
EDITORS,
77
EditorId,
88
PickedThemeFileSchema,
9+
DesktopAttentionNotificationSchema,
910
PickFolderOptionsSchema,
1011
PRIMARY_LOCAL_ENVIRONMENT_ID,
1112
REMOTE_CAPABLE_EDITOR_IDS,
@@ -31,6 +32,7 @@ import * as DesktopWslEnvironment from "../../wsl/DesktopWslEnvironment.ts";
3132
import * as ElectronApp from "../../electron/ElectronApp.ts";
3233
import * as ElectronDialog from "../../electron/ElectronDialog.ts";
3334
import * as ElectronMenu from "../../electron/ElectronMenu.ts";
35+
import * as ElectronNotification from "../../electron/ElectronNotification.ts";
3436
import * as ElectronShell from "../../electron/ElectronShell.ts";
3537
import * as ElectronTheme from "../../electron/ElectronTheme.ts";
3638
import * as ElectronWindow from "../../electron/ElectronWindow.ts";
@@ -299,6 +301,16 @@ export const openExternal = DesktopIpc.makeIpcMethod({
299301
}),
300302
});
301303

304+
export const showAttentionNotification = DesktopIpc.makeIpcMethod({
305+
channel: IpcChannels.SHOW_ATTENTION_NOTIFICATION_CHANNEL,
306+
payload: DesktopAttentionNotificationSchema,
307+
result: Schema.Boolean,
308+
handler: Effect.fn("desktop.ipc.window.showAttentionNotification")(function* (input) {
309+
const notifications = yield* ElectronNotification.ElectronNotification;
310+
return yield* notifications.show(input);
311+
}),
312+
});
313+
302314
export const openSystemSettings = DesktopIpc.makeIpcMethod({
303315
channel: IpcChannels.OPEN_SYSTEM_SETTINGS_CHANNEL,
304316
payload: SystemSettingsPaneSchema,

‎apps/desktop/src/main.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ import * as ElectronMenu from "./electron/ElectronMenu.ts";
2727
import * as ElectronPowerMonitor from "./electron/ElectronPowerMonitor.ts";
2828
import * as ElectronProtocol from "./electron/ElectronProtocol.ts";
2929
import * as ElectronSafeStorage from "./electron/ElectronSafeStorage.ts";
30+
import * as ElectronNotification from "./electron/ElectronNotification.ts";
3031
import * as ElectronShell from "./electron/ElectronShell.ts";
3132
import * as ElectronTheme from "./electron/ElectronTheme.ts";
3233
import * as ElectronUpdater from "./electron/ElectronUpdater.ts";
@@ -130,6 +131,10 @@ const electronLayer = Layer.mergeAll(
130131
ElectronUpdater.layer,
131132
ElectronWindow.layer,
132133
DesktopIpc.layer(Electron.ipcMain),
134+
).pipe(
135+
// Notifications reveal the window they came from, so this one is built on top
136+
// of the window service rather than beside it.
137+
Layer.merge(ElectronNotification.layer.pipe(Layer.provide(ElectronWindow.layer))),
133138
);
134139

135140
const desktopFoundationLayer = Layer.mergeAll(

‎apps/desktop/src/preload.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,8 @@ contextBridge.exposeInMainWorld("desktopBridge", {
141141
ipcRenderer.invoke(IpcChannels.SET_WSL_BACKEND_ENABLED_CHANNEL, enabled),
142142
setWslDistro: (distro) => ipcRenderer.invoke(IpcChannels.SET_WSL_DISTRO_CHANNEL, distro),
143143
setWslOnly: (enabled) => ipcRenderer.invoke(IpcChannels.SET_WSL_ONLY_CHANNEL, enabled),
144+
showAttentionNotification: (input) =>
145+
ipcRenderer.invoke(IpcChannels.SHOW_ATTENTION_NOTIFICATION_CHANNEL, input),
144146
pickFolder: (options) => ipcRenderer.invoke(IpcChannels.PICK_FOLDER_CHANNEL, options),
145147
pickProjectFavicon: (initialPath) =>
146148
ipcRenderer.invoke(IpcChannels.PICK_PROJECT_FAVICON_CHANNEL, initialPath),
Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
/**
2+
* AttentionBus - in-memory fan-out for `session_notify` pings.
3+
*
4+
* A ping is a doorbell: an agent decides the user is needed in person, every
5+
* client attached to this server rings once, and nothing is written down. It is
6+
* deliberately not an orchestration event. The reason the agent rang is already
7+
* in its thread, a stored ping would ring again on the next reconnect replay,
8+
* and a doorbell that rings for yesterday's question is worse than none.
9+
*
10+
* @module AttentionBus
11+
*/
12+
import type { AttentionPing } from "@t3tools/contracts";
13+
import * as Context from "effect/Context";
14+
import * as Effect from "effect/Effect";
15+
import * as Layer from "effect/Layer";
16+
import * as PubSub from "effect/PubSub";
17+
import * as Ref from "effect/Ref";
18+
import * as Stream from "effect/Stream";
19+
20+
export interface AttentionBusShape {
21+
/**
22+
* Rings every subscriber. Returns how many were listening, which is what the
23+
* tool reports back: zero means the ping went nowhere, and an agent that is
24+
* told so can say it rather than assume it was heard.
25+
*/
26+
readonly publish: (ping: AttentionPing) => Effect.Effect<number>;
27+
readonly subscribe: () => Stream.Stream<AttentionPing>;
28+
}
29+
30+
export class AttentionBus extends Context.Service<AttentionBus, AttentionBusShape>()(
31+
"t3/attention/AttentionBus",
32+
) {}
33+
34+
export const layer = Layer.effect(AttentionBus)(
35+
Effect.gen(function* () {
36+
// Dropping is the right failure mode for a doorbell: a client too slow to
37+
// take a ping is a client that is not listening, and queueing pings would
38+
// ring a burst at whoever reconnects.
39+
const pings = yield* Effect.acquireRelease(PubSub.dropping<AttentionPing>(16), (pubsub) =>
40+
PubSub.shutdown(pubsub),
41+
);
42+
// PubSub does not expose its subscriber count, and the count is the only
43+
// honest answer to "did anyone hear that", so it is tracked here.
44+
const listeners = yield* Ref.make(0);
45+
46+
return AttentionBus.of({
47+
publish: (ping) =>
48+
Effect.gen(function* () {
49+
const reached = yield* Ref.get(listeners);
50+
yield* PubSub.publish(pings, ping);
51+
return reached;
52+
}),
53+
subscribe: () =>
54+
Stream.unwrap(
55+
Effect.gen(function* () {
56+
yield* Ref.update(listeners, (count) => count + 1);
57+
return Stream.fromPubSub(pings).pipe(
58+
Stream.ensuring(Ref.update(listeners, (count) => Math.max(0, count - 1))),
59+
);
60+
}),
61+
),
62+
});
63+
}),
64+
);

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,8 @@ export const RPC_REQUIRED_SCOPES = {
106106
[WS_METHODS.attachmentsCreateUploadUrl]: AuthOrchestrationOperateScope,
107107
[WS_METHODS.attachmentsDelete]: AuthOrchestrationOperateScope,
108108
[WS_METHODS.providerUploadFeedback]: AuthOrchestrationOperateScope,
109+
// Reading a ping is reading: it names a thread and its message, nothing more.
110+
[WS_METHODS.subscribeAttention]: AuthOrchestrationReadScope,
109111
[WS_METHODS.subscribeVcsStatus]: AuthOrchestrationReadScope,
110112
[WS_METHODS.subscribeResourceTelemetry]: AuthOrchestrationReadScope,
111113
[WS_METHODS.vcsRefreshStatus]: AuthOrchestrationReadScope,

‎apps/server/src/mcp/toolkits/orchestration/handlers.test.ts‎

Lines changed: 80 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,14 @@ import {
1111
import * as Data from "effect/Data";
1212
import * as Effect from "effect/Effect";
1313
import * as Layer from "effect/Layer";
14+
import * as Fiber from "effect/Fiber";
1415
import * as Option from "effect/Option";
16+
import * as Stream from "effect/Stream";
1517
import { McpSchema, McpServer } from "effect/unstable/ai";
1618

19+
import * as AttentionBus from "../../../attention/AttentionBus.ts";
1720
import { OrchestrationThreadSettleBlockedError } from "../../../orchestration/Errors.ts";
21+
import * as ServerSettings from "../../../serverSettings.ts";
1822
import {
1923
OrchestrationEngineService,
2024
type OrchestrationEngineShape,
@@ -95,7 +99,13 @@ class RefusedByTest extends Data.TaggedError("RefusedByTest")<{ readonly message
9599
* Stub engine that records what was dispatched and can be told to fail a
96100
* given command type once.
97101
*/
98-
function makeHarness(threads: ReadonlyArray<OrchestrationThreadShell>) {
102+
function makeHarness(
103+
threads: ReadonlyArray<OrchestrationThreadShell>,
104+
settings?: {
105+
readonly enableAgentAttentionAlerts?: boolean;
106+
readonly agentAttentionSound?: "chime" | "ping" | "alert" | "knock";
107+
},
108+
) {
99109
const dispatched: Array<OrchestrationCommand> = [];
100110
const failing = new Set<OrchestrationCommand["type"]>();
101111
// Command types the decider would refuse as "still needs attention", which
@@ -139,10 +149,14 @@ function makeHarness(threads: ReadonlyArray<OrchestrationThreadShell>) {
139149
}),
140150
} as unknown as ProjectionSnapshotQueryShape;
141151

152+
// A real bus rather than a mock: what the tool reports is the listener count,
153+
// and only the bus knows it.
142154
const layer = McpHttpServer.OrchestrationToolkitRegistrationLive.pipe(
143155
Layer.provideMerge(McpServer.McpServer.layer),
144156
Layer.provideMerge(Layer.succeed(OrchestrationEngineService, engine)),
145157
Layer.provideMerge(Layer.succeed(ProjectionSnapshotQuery, query)),
158+
Layer.provideMerge(AttentionBus.layer),
159+
Layer.provideMerge(ServerSettings.layerTest(settings ?? {})),
146160
Layer.provideMerge(NodeServices.layer),
147161
);
148162
return { dispatched, failing, blocking, layer };
@@ -443,6 +457,71 @@ it.effect("says a settled session is holding a name that spawn cannot reuse", ()
443457
),
444458
);
445459

460+
it.effect("rings every listener with the user's default sound", () =>
461+
Effect.scoped(
462+
Effect.gen(function* () {
463+
const bus = yield* AttentionBus.AttentionBus;
464+
const heard = yield* Effect.forkChild(Stream.runHead(bus.subscribe()));
465+
// The subscription attaches asynchronously; publishing before it does
466+
// would report a listener count of zero and lose the ping.
467+
yield* Effect.yieldNow;
468+
469+
const result = yield* callTool("session_notify", {
470+
message: "Ticket 15.8.5 needs a decision on the migration order",
471+
});
472+
473+
expect(result.isError).toBe(false);
474+
expect(result.structuredContent).toEqual({ delivered: 1, sound: "chime" });
475+
const ping = yield* Fiber.join(heard);
476+
expect(Option.getOrNull(ping)).toEqual({
477+
threadId: "thread-orchestrator",
478+
threadTitle: "orchestrator",
479+
message: "Ticket 15.8.5 needs a decision on the migration order",
480+
sound: "chime",
481+
requestedAt: expect.any(String),
482+
});
483+
}).pipe(Effect.provide(makeHarness(baseThreads).layer)),
484+
),
485+
);
486+
487+
it.effect("lets the caller pick a sound, and reports that nobody heard it", () =>
488+
Effect.scoped(
489+
Effect.gen(function* () {
490+
// No subscriber on purpose: an agent told nobody heard it can say so
491+
// instead of assuming the user was rung.
492+
const result = yield* callTool("session_notify", { message: "Need you", sound: "alert" });
493+
expect(result.structuredContent).toEqual({ delivered: 0, sound: "alert" });
494+
}).pipe(Effect.provide(makeHarness(baseThreads).layer)),
495+
),
496+
);
497+
498+
it.effect("drops the ping when the user turned attention alerts off", () =>
499+
Effect.scoped(
500+
Effect.gen(function* () {
501+
const bus = yield* AttentionBus.AttentionBus;
502+
const heard = yield* Effect.forkChild(Stream.runHead(bus.subscribe()));
503+
yield* Effect.yieldNow;
504+
505+
const result = yield* callTool("session_notify", { message: "Need you", sound: "alert" });
506+
507+
// Succeeds rather than fails: a failure reads to an agent as "retry",
508+
// and the user's answer is "not wanted", not "try again".
509+
expect(result.isError).toBe(false);
510+
expect(result.structuredContent).toEqual({ delivered: 0, sound: "alert" });
511+
yield* Fiber.interrupt(heard);
512+
}).pipe(Effect.provide(makeHarness(baseThreads, { enableAgentAttentionAlerts: false }).layer)),
513+
),
514+
);
515+
516+
it.effect("refuses an empty message before it reaches the bus", () =>
517+
Effect.scoped(
518+
Effect.gen(function* () {
519+
const result = yield* callTool("session_notify", { message: " " }).pipe(Effect.flip);
520+
expect(result._tag).toBe("InvalidParams");
521+
}).pipe(Effect.provide(makeHarness(baseThreads).layer)),
522+
),
523+
);
524+
446525
it.effect("settles a finished session by name and by threadId", () =>
447526
Effect.scoped(
448527
Effect.gen(function* () {

0 commit comments

Comments
 (0)