feat: notify when a chat needs input (desktop + web)

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

@@ -0,0 +1,266 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import type * as Electron from "electron";
+import { beforeEach, vi } from "vite-plus/test";
+
+interface FakeNotificationEntry {
+  readonly options: { readonly title?: string; readonly body?: string };
+  readonly listeners: Map<string, (...args: readonly unknown[]) => void>;
+  shown: number;
+  closed: number;
+}
+
+const { notificationState, FakeNotification } = vi.hoisted(() => {
+  const notificationState = {
+    supported: true,
+    constructorThrows: null as Error | null,
+    instances: [] as FakeNotificationEntry[],
+  };
+
+  class FakeNotification {
+    static isSupported(): boolean {
+      return notificationState.supported;
+    }
+
+    readonly entry: FakeNotificationEntry;
+
+    constructor(options: { title?: string; body?: string }) {
+      if (notificationState.constructorThrows !== null) {
+        throw notificationState.constructorThrows;
+      }
+      this.entry = { options, listeners: new Map(), shown: 0, closed: 0 };
+      notificationState.instances.push(this.entry);
+    }
+
+    on(event: string, listener: (...args: readonly unknown[]) => void): this {
+      this.entry.listeners.set(event, listener);
+      return this;
+    }
+
+    show(): void {
+      this.entry.shown += 1;
+    }
+
+    // Electron dismisses the notification and then emits `close`; the fake
+    // mirrors that so the service's bookkeeping is exercised.
+    close(): void {
+      this.entry.closed += 1;
+      this.entry.listeners.get("close")?.();
+    }
+  }
+
+  return { notificationState, FakeNotification };
+});
+
+vi.mock("electron", () => ({ Notification: FakeNotification }));
+
+import { NOTIFICATION_ACTIVATED_CHANNEL } from "../ipc/channels.ts";
+import * as ElectronNotification from "./ElectronNotification.ts";
+import * as ElectronWindow from "./ElectronWindow.ts";
+
+const request = {
+  id: "thread-1",
+  title: "T3 Code needs your input",
+  body: "Claude is waiting on your answer.",
+  environmentId: "local",
+  threadId: "thread-1",
+} as const;
+
+const clickNotification = (index: number) => {
+  const entry = notificationState.instances[index];
+  assert.isDefined(entry);
+  const click = entry.listeners.get("click");
+  if (click === undefined) {
+    throw new Error("Expected the notification to register a click listener.");
+  }
+  click();
+};
+
+const clickFirstNotification = () => clickNotification(0);
+
+const closeNotification = (index: number) => {
+  const entry = notificationState.instances[index];
+  assert.isDefined(entry);
+  const close = entry.listeners.get("close");
+  if (close === undefined) {
+    throw new Error("Expected the notification to register a close listener.");
+  }
+  close();
+};
+
+const silentWindowLayer = Layer.mock(ElectronWindow.ElectronWindow)({
+  focusedMainOrFirst: Effect.succeed(Option.none()),
+  sendAll: () => Effect.void,
+});
+
+describe("ElectronNotification", () => {
+  beforeEach(() => {
+    notificationState.supported = true;
+    notificationState.constructorThrows = null;
+    notificationState.instances = [];
+  });
+
+  it.effect("shows a native notification carrying the request title and body", () =>
+    Effect.gen(function* () {
+      const notifications = yield* ElectronNotification.ElectronNotification;
+      yield* notifications.show(request);
+
+      assert.equal(notificationState.instances.length, 1);
+      assert.deepEqual(notificationState.instances[0]?.options, {
+        title: "T3 Code needs your input",
+        body: "Claude is waiting on your answer.",
+      });
+      assert.equal(notificationState.instances[0]?.shown, 1);
+    }).pipe(
+      Effect.provide(
+        ElectronNotification.layer.pipe(
+          Layer.provide(
+            Layer.mock(ElectronWindow.ElectronWindow)({
+              focusedMainOrFirst: Effect.succeed(Option.none()),
+            }),
+          ),
+        ),
+      ),
+    ),
+  );
+
+  it.effect("reveals the target window and broadcasts the activation on click", () =>
+    Effect.gen(function* () {
+      const window = { id: 7 } as Electron.BrowserWindow;
+      const revealedRef = yield* Ref.make<Option.Option<Electron.BrowserWindow>>(Option.none());
+      const sent = yield* Deferred.make<readonly unknown[]>();
+      const windowLayer = Layer.mock(ElectronWindow.ElectronWindow)({
+        focusedMainOrFirst: Effect.succeed(Option.some(window)),
+        reveal: (target) => Ref.set(revealedRef, Option.some(target)),
+        sendAll: (channel, ...args) =>
+          Deferred.succeed(sent, [channel, ...args]).pipe(Effect.asVoid),
+      });
+
+      yield* Effect.gen(function* () {
+        const notifications = yield* ElectronNotification.ElectronNotification;
+        yield* notifications.show(request);
+
+        clickFirstNotification();
+
+        const broadcast = yield* Deferred.await(sent);
+        assert.deepEqual(broadcast, [
+          NOTIFICATION_ACTIVATED_CHANNEL,
+          { environmentId: "local", threadId: "thread-1" },
+        ]);
+        assert.strictEqual(Option.getOrNull(yield* Ref.get(revealedRef)), window);
+      }).pipe(Effect.provide(ElectronNotification.layer.pipe(Layer.provide(windowLayer))));
+    }),
+  );
+
+  it.effect("broadcasts the activation even when there is no window to reveal", () =>
+    Effect.gen(function* () {
+      const sent = yield* Deferred.make<readonly unknown[]>();
+      const windowLayer = Layer.mock(ElectronWindow.ElectronWindow)({
+        focusedMainOrFirst: Effect.succeed(Option.none()),
+        sendAll: (channel, ...args) =>
+          Deferred.succeed(sent, [channel, ...args]).pipe(Effect.asVoid),
+      });
+
+      yield* Effect.gen(function* () {
+        const notifications = yield* ElectronNotification.ElectronNotification;
+        yield* notifications.show(request);
+
+        clickFirstNotification();
+
+        assert.deepEqual(yield* Deferred.await(sent), [
+          NOTIFICATION_ACTIVATED_CHANNEL,
+          { environmentId: "local", threadId: "thread-1" },
+        ]);
+      }).pipe(Effect.provide(ElectronNotification.layer.pipe(Layer.provide(windowLayer))));
+    }),
+  );
+
+  it.effect("no-ops when the platform does not support native notifications", () =>
+    Effect.gen(function* () {
+      notificationState.supported = false;
+
+      const notifications = yield* ElectronNotification.ElectronNotification;
+      yield* notifications.show(request);
+
+      assert.equal(notificationState.instances.length, 0);
+    }).pipe(
+      Effect.provide(
+        ElectronNotification.layer.pipe(
+          Layer.provide(
+            Layer.mock(ElectronWindow.ElectronWindow)({
+              focusedMainOrFirst: Effect.succeed(Option.none()),
+            }),
+          ),
+        ),
+      ),
+    ),
+  );
+
+  it.effect("closes the previous notification when the same id is shown again", () =>
+    Effect.gen(function* () {
+      const notifications = yield* ElectronNotification.ElectronNotification;
+      yield* notifications.show(request);
+      yield* notifications.show(request);
+      yield* notifications.show({ ...request, id: "thread-2", threadId: "thread-2" });
+
+      assert.equal(notificationState.instances.length, 3);
+      // Only the first is superseded: the third carries a different id.
+      assert.equal(notificationState.instances[0]?.closed, 1);
+      assert.equal(notificationState.instances[1]?.closed, 0);
+      assert.equal(notificationState.instances[2]?.closed, 0);
+    }).pipe(Effect.provide(ElectronNotification.layer.pipe(Layer.provide(silentWindowLayer)))),
+  );
+
+  it.effect("forgets a dismissed notification so it is never closed twice", () =>
+    Effect.gen(function* () {
+      const notifications = yield* ElectronNotification.ElectronNotification;
+      yield* notifications.show(request);
+
+      // The OS dismissal emits `close` without routing through `close()`.
+      closeNotification(0);
+      yield* notifications.show(request);
+
+      assert.equal(notificationState.instances.length, 2);
+      assert.equal(notificationState.instances[0]?.closed, 0);
+    }).pipe(Effect.provide(ElectronNotification.layer.pipe(Layer.provide(silentWindowLayer)))),
+  );
+
+  it.effect("forgets a clicked notification so it is never closed afterwards", () =>
+    Effect.gen(function* () {
+      const notifications = yield* ElectronNotification.ElectronNotification;
+      yield* notifications.show(request);
+
+      clickFirstNotification();
+      yield* notifications.show(request);
+
+      assert.equal(notificationState.instances.length, 2);
+      assert.equal(notificationState.instances[0]?.closed, 0);
+    }).pipe(Effect.provide(ElectronNotification.layer.pipe(Layer.provide(silentWindowLayer)))),
+  );
+
+  it.effect("swallows Electron notification failures instead of failing the caller", () =>
+    Effect.gen(function* () {
+      notificationState.constructorThrows = new Error("notification center unavailable");
+
+      const notifications = yield* ElectronNotification.ElectronNotification;
+      const exit = yield* Effect.exit(notifications.show(request));
+
+      assert.equal(exit._tag, "Success");
+      assert.equal(notificationState.instances.length, 0);
+    }).pipe(
+      Effect.provide(
+        ElectronNotification.layer.pipe(
+          Layer.provide(
+            Layer.mock(ElectronWindow.ElectronWindow)({
+              focusedMainOrFirst: Effect.succeed(Option.none()),
+            }),
+          ),
+        ),
+      ),
+    ),
+  );
+});

apps/desktop/src/electron/ElectronNotification.ts

@@ -0,0 +1,113 @@
+import type { DesktopNotificationActivation, DesktopNotificationRequest } from "@t3tools/contracts";
+import * as Context from "effect/Context";
+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 Electron from "electron";
+
+import { NOTIFICATION_ACTIVATED_CHANNEL } from "../ipc/channels.ts";
+import * as ElectronWindow from "./ElectronWindow.ts";
+
+export class ElectronNotificationShowError extends Schema.TaggedErrorClass<ElectronNotificationShowError>()(
+  "ElectronNotificationShowError",
+  {
+    notificationId: Schema.String,
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Failed to show the Electron notification ${JSON.stringify(this.notificationId)}.`;
+  }
+}
+
+export class ElectronNotification extends Context.Service<
+  ElectronNotification,
+  {
+    /**
+     * Raises a native OS notification. Resolves once the notification has been
+     * handed to the platform, and no-ops when the platform has no notification
+     * support. Clicking the notification reveals the current window and
+     * broadcasts a `DesktopNotificationActivation` to every renderer.
+     */
+    readonly show: (request: DesktopNotificationRequest) => Effect.Effect<void>;
+  }
+>()("@t3tools/desktop/electron/ElectronNotification") {}
+
+export const make = Effect.gen(function* () {
+  const electronWindow = yield* ElectronWindow.ElectronWindow;
+  // The click listener is a bare Electron callback, so the activation effect
+  // has to be run against the captured context (keeps logging/tracing intact).
+  const context = yield* Effect.context<never>();
+  const runFork = Effect.runForkWith(context);
+
+  // Live notifications keyed by `DesktopNotificationRequest.id`, which the
+  // contract defines as a coalescing key: showing again for the same id
+  // replaces the previous entry instead of stacking a second one in
+  // Notification Center (the web path gets this from the notification `tag`).
+  // Holding the JS reference also keeps the notification from being collected
+  // while it is on screen, which is what makes Electron's `click` reliable.
+  const liveNotifications = new Map<string, Electron.Notification>();
+
+  const activate = Effect.fn("desktop.electron.notification.activate")(function* (
+    request: DesktopNotificationRequest,
+  ) {
+    const window = yield* electronWindow.focusedMainOrFirst;
+    if (Option.isSome(window)) {
+      yield* electronWindow.reveal(window.value);
+    }
+
+    const activation: DesktopNotificationActivation = {
+      environmentId: request.environmentId,
+      threadId: request.threadId,
+    };
+    // Broadcast rather than target the revealed window: any renderer may own
+    // the thread, and the activation is idempotent for the ones that don't.
+    yield* electronWindow.sendAll(NOTIFICATION_ACTIVATED_CHANNEL, activation);
+  });
+
+  const show = Effect.fn("desktop.electron.notification.show")(function* (
+    request: DesktopNotificationRequest,
+  ) {
+    const supported = yield* Effect.try({
+      try: () => Electron.Notification.isSupported(),
+      catch: (cause) => new ElectronNotificationShowError({ notificationId: request.id, cause }),
+    });
+    if (!supported) {
+      return;
+    }
+
+    yield* Effect.try({
+      try: () => {
+        const notification = new Electron.Notification({
+          title: request.title,
+          body: request.body,
+        });
+        const forget = () => {
+          if (liveNotifications.get(request.id) === notification) {
+            liveNotifications.delete(request.id);
+          }
+        };
+        notification.on("click", () => {
+          forget();
+          runFork(activate(request));
+        });
+        notification.on("close", forget);
+
+        liveNotifications.get(request.id)?.close();
+        liveNotifications.set(request.id, notification);
+        notification.show();
+      },
+      catch: (cause) => new ElectronNotificationShowError({ notificationId: request.id, cause }),
+    });
+  });
+
+  return ElectronNotification.of({
+    // Notifications are advisory: failing to raise one must never fail the
+    // renderer's invoke, so failures are logged and swallowed here.
+    show: (request) => show(request).pipe(Effect.catch((error) => Effect.logWarning(error))),
+  });
+});
+
+export const layer = Layer.effect(ElectronNotification, make);

apps/desktop/src/ipc/DesktopIpcHandlers.ts

@@ -23,6 +23,7 @@ import {
   issueSshWebSocketTicket,
   resolveSshPasswordPrompt,
 } from "./methods/sshEnvironment.ts";
+import { showNotification } from "./methods/notifications.ts";
 import {
   checkForUpdate,
   downloadUpdate,
@@ -83,6 +84,7 @@ export const installDesktopIpcHandlers = Effect.fn("desktop.ipc.installHandlers"
   yield* ipc.handle(setTheme);
   yield* ipc.handle(showContextMenu);
   yield* ipc.handle(openExternal);
+  yield* ipc.handle(showNotification);
   yield* ipc.handle(getUpdateState);
   yield* ipc.handle(setUpdateChannel);
   yield* ipc.handle(downloadUpdate);