Commit d8fe3d72c82cc3cc6a6e9275494f5e5377b058a6 | the-knife

author	Julius Marminge <51714798+juliusmarminge@users.noreply.github.com> 2026-06-12 18:19:01-07:00
committer	Theo Browne <me@theo.li> 2026-06-13 22:18:37-07:00
log	d8fe3d72c82cc3cc6a6e9275494f5e5377b058a6
tree	695738c2f90e2de2782ac32d727cb9f5495829e1
parent	70ec39ae8094d06eb7a241a007bbc2b0892c2896

Scope preview listeners and control sessions

- Tie preview and debugger listeners to Effect scopes
- Factor shared automation helpers for snapshot and input handling
- Improve cleanup for browser preview sessions and port scanning

13 files changed, 853 insertions(+), 747 deletions(-)

apps
- desktop
  - src
    preview
    Manager.ts
- server
  - src
    mcp
    McpHttpServer.test.ts
    McpHttpServer.ts
    McpSessionRegistry.ts
    PreviewAutomationBroker.test.ts
    PreviewAutomationBroker.ts
    toolkits
    preview
    handlers.ts
    tools.ts
    preview
    Manager.ts
    PortScanner.test.ts
    PortScanner.ts
    server.test.ts
    ws.ts

apps/desktop/src/preview/Manager.ts+544-491

 @@ -48,7 +48,7 @@ import * as Path from "effect/Path";
 import * as Ref from "effect/Ref";
 import * as Schema from "effect/Schema";
 import * as Semaphore from "effect/Semaphore";
-import type * as Scope from "effect/Scope";
+import * as Scope from "effect/Scope";
 import * as SynchronizedRef from "effect/SynchronizedRef";
 import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
 @@ -247,10 +247,7 @@ type PreviewInputSignal =
   | { readonly kind: "key"; readonly key: string; readonly code: string };
 interface ManagedListeners {
-  navigate: () => void;
+  readonly scope: Scope.Closeable;
-  failed: (event: Event, code: number, description: string) => void;
-  humanInput: (_event: unknown, signal?: unknown) => void;
-  beforeInput: (event: Electron.Event, input: Electron.Input) => void;
 }
 interface PickSession {
 @@ -260,6 +257,7 @@ interface PickSession {
 interface BrowserControlSession {
   readonly webContentsId: number;
   readonly semaphore: Semaphore.Semaphore;
+  readonly scope: Scope.Closeable;
   readonly onMessage: (
     event: Electron.Event,
     method: string,
 @@ -339,6 +337,7 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
 ) {
   const fileSystem = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
+  const parentScope = yield* Scope.Scope;
   const context = yield* Effect.context<never>();
   const runFork = Effect.runForkWith(context);
   const resolvedArtifactDirectory = path.resolve(artifactDirectory);
 @@ -622,16 +621,15 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
         copy.delete(webContentsId);
       }),
     ]);
+    if (control) {
+      yield* Scope.close(control.scope, Exit.void).pipe(Effect.ignore);
+      return;
+    }
     yield* Ref.update(diagnosticsRef, (diagnostics) =>
       replaceMap(diagnostics, (copy) => {
         copy.delete(webContentsId);
       }),
     );
-    const wc = webContents.fromId(webContentsId);
-    if (!wc || wc.isDestroyed()) return;
-    if (control) wc.debugger.off("message", control.onMessage);
-    if (!wc.debugger.isAttached()) return;
-    yield* attempt("detachControlSession", () => wc.debugger.detach()).pipe(Effect.ignore);
   });
   const ensureControlSession = Effect.fn("PreviewManager.ensureControlSession")(function* (
 @@ -662,87 +660,103 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
           ),
         );
       }
-      return Effect.gen(function* () {
+      const createControlSession = Effect.fn("PreviewManager.createControlSession")(function* () {
         const semaphore = yield* Semaphore.make(1);
+        const scope = yield* Scope.fork(parentScope, "sequential");
+        const handleDebuggerMessage = Effect.fn("PreviewManager.handleDebuggerMessage")(function* (
+          method: string,
+          params: Record<string, unknown>,
+        ) {
+          if (method === "Page.screencastFrame") {
+            const sessionId = params["sessionId"];
+            if (typeof sessionId === "number") {
+              yield* attemptPromise("ackScreencastFrame", () =>
+                wc.debugger.sendCommand("Page.screencastFrameAck", { sessionId }),
+              ).pipe(Effect.ignore);
+            }
+            const tabId = yield* tabIdForWebContents(wc.id);
+            const metadata =
+              typeof params["metadata"] === "object" && params["metadata"] !== null
+                ? (params["metadata"] as Record<string, unknown>)
+                : {};
+            if (tabId && typeof params["data"] === "string") {
+              const receivedAt = yield* currentIso;
+              const listeners = yield* Ref.get(recordingFrameListenersRef);
+              const frame: DesktopPreviewRecordingFrame = {
+                tabId,
+                data: params["data"],
+                width: typeof metadata["deviceWidth"] === "number" ? metadata["deviceWidth"] : 0,
+                height: typeof metadata["deviceHeight"] === "number" ? metadata["deviceHeight"] : 0,
+                receivedAt,
+              };
+              yield* Effect.forEach(
+                listeners,
+                (listener) => Effect.sync(() => listener(frame)).pipe(Effect.ignore),
+                { discard: true },
+              );
+            }
+          }
+          yield* captureDiagnosticMessage(wc.id, method, params);
+        });
         const onMessage: BrowserControlSession["onMessage"] = (_event, method, params) => {
-          runFork(
+          runFork(handleDebuggerMessage(method, params));
-            Effect.gen(function* () {
-              if (method === "Page.screencastFrame") {
-                const sessionId = params["sessionId"];
-                if (typeof sessionId === "number") {
-                  yield* attemptPromise("ackScreencastFrame", () =>
-                    wc.debugger.sendCommand("Page.screencastFrameAck", { sessionId }),
-                  ).pipe(Effect.ignore);
-                }
-                const tabId = yield* tabIdForWebContents(wc.id);
-                const metadata =
-                  typeof params["metadata"] === "object" && params["metadata"] !== null
-                    ? (params["metadata"] as Record<string, unknown>)
-                    : {};
-                if (tabId && typeof params["data"] === "string") {
-                  const receivedAt = yield* currentIso;
-                  const listeners = yield* Ref.get(recordingFrameListenersRef);
-                  const frame: DesktopPreviewRecordingFrame = {
-                    tabId,
-                    data: params["data"],
-                    width:
-                      typeof metadata["deviceWidth"] === "number" ? metadata["deviceWidth"] : 0,
-                    height:
-                      typeof metadata["deviceHeight"] === "number" ? metadata["deviceHeight"] : 0,
-                    receivedAt,
-                  };
-                  yield* Effect.forEach(
-                    listeners,
-                    (listener) => Effect.sync(() => listener(frame)).pipe(Effect.ignore),
-                    { discard: true },
-                  );
-                }
-              }
-              yield* captureDiagnosticMessage(wc.id, method, params);
-            }),
-          );
         };
-        const control: BrowserControlSession = { webContentsId: wc.id, semaphore, onMessage };
+        yield* Scope.addFinalizer(
-        yield* Ref.update(diagnosticsRef, (diagnostics) =>
+          scope,
-          replaceMap(diagnostics, (copy) => {
+          Effect.all(
-            copy.set(wc.id, {
+            [
-              consoleEntries: [],
-              networkEntries: [],
-              requests: new Map(),
-            });
-          }),
-        );
-        yield* attempt("attachDebuggerListeners", () => {
-          wc.debugger.on("message", onMessage);
-          wc.debugger.attach("1.3");
-        });
-        yield* Effect.all(
-          ["Runtime.enable", "Accessibility.enable", "Network.enable", "Log.enable"].map((method) =>
-            attemptPromise("initializeDebugger", () => wc.debugger.sendCommand(method)),
-          ),
-          { concurrency: "unbounded", discard: true },
-        ).pipe(
-          Effect.tapError(() =>
-            Effect.all([
               Ref.update(diagnosticsRef, (diagnostics) =>
                 replaceMap(diagnostics, (copy) => {
                   copy.delete(wc.id);
                 }),
               ),
-              attempt("detachFailedDebugger", () => {
+              attempt("detachControlSession", () => {
                 wc.debugger.off("message", onMessage);
                 if (wc.debugger.isAttached()) wc.debugger.detach();
               }).pipe(Effect.ignore),
-            ]).pipe(Effect.asVoid),
+            ],
+            { discard: true },
           ),
         );
-        return [
+        const control: BrowserControlSession = {
-          control,
+          webContentsId: wc.id,
-          replaceMap(sessions, (copy) => {
+          semaphore,
-            copy.set(wc.id, control);
+          scope,
-          }),
+          onMessage,
-        ] as const;
+        };
+        const initialize = Effect.fn("PreviewManager.initializeControlSession")(function* () {
+          yield* Ref.update(diagnosticsRef, (diagnostics) =>
+            replaceMap(diagnostics, (copy) => {
+              copy.set(wc.id, {
+                consoleEntries: [],
+                networkEntries: [],
+                requests: new Map(),
+              });
+            }),
+          );
+          yield* attempt("attachDebuggerListeners", () => {
+            wc.debugger.on("message", onMessage);
+            wc.debugger.attach("1.3");
+          });
+          yield* Effect.all(
+            ["Runtime.enable", "Accessibility.enable", "Network.enable", "Log.enable"].map(
+              (method) =>
+                attemptPromise("initializeDebugger", () => wc.debugger.sendCommand(method)),
+            ),
+            { concurrency: "unbounded", discard: true },
+          );
+          return [
+            control,
+            replaceMap(sessions, (copy) => {
+              copy.set(wc.id, control);
+            }),
+          ] as const;
+        });
+        return yield* initialize().pipe(
+          Effect.onError(() => Scope.close(scope, Exit.void).pipe(Effect.ignore)),
+        );
       });
+      return createControlSession();
     });
   });
 @@ -906,25 +920,13 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
   const detachListeners = Effect.fn("PreviewManager.detachListeners")(function* (
     webContentsId: number,
   ) {
-    const handlers = yield* Ref.modify(attachedRef, (attached) => [
+    const managed = yield* Ref.modify(attachedRef, (attached) => [
       attached.get(webContentsId),
       replaceMap(attached, (copy) => {
         copy.delete(webContentsId);
       }),
     ]);
-    if (!handlers) return;
+    if (managed) yield* Scope.close(managed.scope, Exit.void).pipe(Effect.ignore);
-    const wc = webContents.fromId(webContentsId);
-    if (!wc || wc.isDestroyed()) return;
-    yield* attempt("detachListeners", () => {
-      wc.off("did-navigate", handlers.navigate);
-      wc.off("did-navigate-in-page", handlers.navigate);
-      wc.off("page-title-updated", handlers.navigate);
-      wc.off("did-start-loading", handlers.navigate);
-      wc.off("did-stop-loading", handlers.navigate);
-      wc.off("did-fail-load", handlers.failed as never);
-      wc.off("before-input-event", handlers.beforeInput);
-      wc.ipc.off(HUMAN_INPUT_CHANNEL, handlers.humanInput);
-    }).pipe(Effect.ignore);
   });
   const isAppShortcut = (input: Electron.Input): boolean =>
 @@ -987,17 +989,16 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
     tabId: string,
     wc: Electron.WebContents,
   ) {
-    const sync = () =>
+    const scope = yield* Scope.fork(parentScope, "sequential");
-      runFork(
+    const syncState = Effect.fn("PreviewManager.syncWebContentsState")(function* () {
-        Effect.gen(function* () {
+      if (wc.isDestroyed()) return;
-          if (wc.isDestroyed()) return;
+      yield* update(tabId, {
-          yield* update(tabId, {
+        navStatus: computeNavStatus(wc),
-            navStatus: computeNavStatus(wc),
+        canGoBack: wc.navigationHistory.canGoBack(),
-            canGoBack: wc.navigationHistory.canGoBack(),
+        canGoForward: wc.navigationHistory.canGoForward(),
-            canGoForward: wc.navigationHistory.canGoForward(),
+      });
-          });
+    });
-        }),
+    const sync = () => runFork(syncState());
-      );
     const failed = (_event: Event, code: number, description: string): void => {
       if (code === -3) return;
       runFork(
 @@ -1012,73 +1013,85 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
         }),
       );
     };
-    const humanInput = (_event: unknown, rawSignal?: unknown): void => {
+    const handleHumanInput = Effect.fn("PreviewManager.handleHumanInput")(function* (
-      runFork(
+      rawSignal?: unknown,
-        Effect.gen(function* () {
+    ) {
-          if (
+      if (isPreviewInputSignal(rawSignal) && (yield* consumeExpectedAgentInput(tabId, rawSignal))) {
-            isPreviewInputSignal(rawSignal) &&
+        return;
-            (yield* consumeExpectedAgentInput(tabId, rawSignal))
+      }
-          ) {
+      yield* Ref.update(controlEpochRef, (epochs) =>
-            return;
+        replaceMap(epochs, (copy) => {
-          }
+          copy.set(tabId, (epochs.get(tabId) ?? 0) + 1);
-          yield* Ref.update(controlEpochRef, (epochs) =>
-            replaceMap(epochs, (copy) => {
-              copy.set(tabId, (epochs.get(tabId) ?? 0) + 1);
-            }),
-          );
-          yield* update(tabId, { controller: "human" });
-          yield* Effect.sleep(750);
-          const tabs = yield* SynchronizedRef.get(tabsRef);
-          if (tabs.get(tabId)?.controller === "human") {
-            yield* update(tabId, { controller: "none" });
-          }
         }),
       );
+      yield* update(tabId, { controller: "human" });
+      yield* Effect.sleep(750);
+      const tabs = yield* SynchronizedRef.get(tabsRef);
+      if (tabs.get(tabId)?.controller === "human") {
+        yield* update(tabId, { controller: "none" });
+      }
+    });
+    const humanInput = (_event: unknown, rawSignal?: unknown): void => {
+      runFork(handleHumanInput(rawSignal));
     };
+    const forwardShortcut = Effect.fn("PreviewManager.forwardShortcut")(function* (
+      event: Electron.Event,
+      input: Electron.Input,
+    ) {
+      const mainWindow = yield* Ref.get(mainWindowRef);
+      if (!isAppShortcut(input) || Option.isNone(mainWindow) || mainWindow.value.isDestroyed()) {
+        return;
+      }
+      event.preventDefault();
+      mainWindow.value.webContents.sendInputEvent({
+        type: "keyDown",
+        keyCode: input.key,
+        modifiers: [
+          ...(input.meta ? (["meta"] as const) : []),
+          ...(input.shift ? (["shift"] as const) : []),
+          ...(input.control ? (["control"] as const) : []),
+          ...(input.alt ? (["alt"] as const) : []),
+        ],
+      });
+    });
     const beforeInput = (event: Electron.Event, input: Electron.Input): void => {
-      runFork(
+      runFork(forwardShortcut(event, input));
-        Effect.gen(function* () {
-          const mainWindow = yield* Ref.get(mainWindowRef);
-          if (
-            !isAppShortcut(input) ||
-            Option.isNone(mainWindow) ||
-            mainWindow.value.isDestroyed()
-          ) {
-            return;
-          }
-          event.preventDefault();
-          mainWindow.value.webContents.sendInputEvent({
-            type: "keyDown",
-            keyCode: input.key,
-            modifiers: [
-              ...(input.meta ? (["meta"] as const) : []),
-              ...(input.shift ? (["shift"] as const) : []),
-              ...(input.control ? (["control"] as const) : []),
-              ...(input.alt ? (["alt"] as const) : []),
-            ],
-          });
-        }),
-      );
     };
-    yield* attempt("attachListeners", () => {
+    yield* Scope.addFinalizer(
-      wc.on("did-navigate", sync);
+      scope,
-      wc.on("did-navigate-in-page", sync);
+      attempt("detachListeners", () => {
-      wc.on("page-title-updated", sync);
+        wc.off("did-navigate", sync);
-      wc.on("did-start-loading", sync);
+        wc.off("did-navigate-in-page", sync);
-      wc.on("did-stop-loading", sync);
+        wc.off("page-title-updated", sync);
-      wc.on("did-fail-load", failed as never);
+        wc.off("did-start-loading", sync);
-      wc.ipc.on(HUMAN_INPUT_CHANNEL, humanInput);
+        wc.off("did-stop-loading", sync);
-      wc.setWindowOpenHandler(({ url }) => {
+        wc.off("did-fail-load", failed as never);
-        runFork(attemptPromise("openPreviewWindow", () => wc.loadURL(url)).pipe(Effect.ignore));
+        wc.off("before-input-event", beforeInput);
-        return { action: "deny" };
+        wc.ipc.off(HUMAN_INPUT_CHANNEL, humanInput);
+      }).pipe(Effect.ignore),
+    );
+    const install = Effect.fn("PreviewManager.installWebContentsListeners")(function* () {
+      yield* attempt("attachListeners", () => {
+        wc.on("did-navigate", sync);
+        wc.on("did-navigate-in-page", sync);
+        wc.on("page-title-updated", sync);
+        wc.on("did-start-loading", sync);
+        wc.on("did-stop-loading", sync);
+        wc.on("did-fail-load", failed as never);
+        wc.ipc.on(HUMAN_INPUT_CHANNEL, humanInput);
+        wc.setWindowOpenHandler(({ url }) => {
+          runFork(attemptPromise("openPreviewWindow", () => wc.loadURL(url)).pipe(Effect.ignore));
+          return { action: "deny" };
+        });
+        wc.on("before-input-event", beforeInput);
       });
-      wc.on("before-input-event", beforeInput);
+      yield* Ref.update(attachedRef, (attached) =>
+        replaceMap(attached, (copy) => {
+          copy.set(wc.id, { scope });
+        }),
+      );
     });
-    yield* Ref.update(attachedRef, (attached) =>
+    yield* install().pipe(Effect.onError(() => Scope.close(scope, Exit.void).pipe(Effect.ignore)));
-      replaceMap(attached, (copy) => {
-        copy.set(wc.id, { navigate: sync, failed, humanInput, beforeInput });
-      }),
-    );
   });
   const setMainWindow = Effect.fn("PreviewManager.setMainWindow")(function* (
 @@ -1271,7 +1284,7 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
     const annotationTheme = yield* Ref.get(annotationThemeRef);
     return yield* Effect.callback<PreviewAnnotationPayload | null, PreviewManagerError>(
       (resume) => {
-        const cleanup = Effect.gen(function* () {
+        const cleanup = Effect.fn("PreviewManager.cleanupPickElement")(function* () {
           yield* attempt("pickElement.cleanup", () => {
             wc.ipc.removeListener(ELEMENT_PICKED_CHANNEL, onMessage);
             wc.off("destroyed", onDestroyed);
 @@ -1283,18 +1296,19 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
             }),
           );
         });
+        const settlePick = Effect.fn("PreviewManager.settlePickElement")(function* (
+          payload: PreviewAnnotationPayload | null,
+        ) {
+          const active = (yield* Ref.get(pickSessionsRef)).get(tabId);
+          if (!active || active.cancel !== cancel) return;
+          yield* cleanup();
+          resume(Effect.succeed(payload));
+        });
         const settle = (payload: PreviewAnnotationPayload | null) => {
-          runFork(
+          runFork(settlePick(payload));
-            Effect.gen(function* () {
-              const active = (yield* Ref.get(pickSessionsRef)).get(tabId);
-              if (!active || active.cancel !== cancel) return;
-              yield* cleanup;
-              resume(Effect.succeed(payload));
-            }),
-          );
         };
-        const cancel = Effect.gen(function* () {
+        const cancelPickSession = Effect.fn("PreviewManager.cancelPickSession")(function* () {
-          yield* cleanup;
+          yield* cleanup();
           const tabs = yield* SynchronizedRef.get(tabsRef);
           const activeTab = tabs.get(tabId);
           if (activeTab?.webContentsId != null) {
 @@ -1307,6 +1321,7 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
           }
           resume(Effect.succeed(null));
         });
+        const cancel = cancelPickSession();
         const onMessage = (_event: Electron.IpcMainEvent, ...args: unknown[]): void => {
           const payload = args[0];
           if (!isPreviewAnnotationPayload(payload)) {
 @@ -1330,24 +1345,25 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
         };
         const onDestroyed = () => settle(null);
         const onNavigated = () => settle(null);
+        const registerPickElement = Effect.fn("PreviewManager.registerPickElement")(function* () {
+          yield* attempt("pickElement.register", () => {
+            wc.ipc.on(ELEMENT_PICKED_CHANNEL, onMessage);
+            wc.once("destroyed", onDestroyed);
+            wc.once("did-start-navigation", onNavigated);
+            if (!wc.isFocused()) wc.focus();
+            wc.send(START_PICK_CHANNEL, annotationTheme);
+          });
+          yield* Ref.update(pickSessionsRef, (sessions) =>
+            replaceMap(sessions, (copy) => {
+              copy.set(tabId, { cancel });
+            }),
+          );
+        });
         runFork(
-          Effect.gen(function* () {
+          registerPickElement().pipe(
-            yield* attempt("pickElement.register", () => {
-              wc.ipc.on(ELEMENT_PICKED_CHANNEL, onMessage);
-              wc.once("destroyed", onDestroyed);
-              wc.once("did-start-navigation", onNavigated);
-              if (!wc.isFocused()) wc.focus();
-              wc.send(START_PICK_CHANNEL, annotationTheme);
-            });
-            yield* Ref.update(pickSessionsRef, (sessions) =>
-              replaceMap(sessions, (copy) => {
-                copy.set(tabId, { cancel });
-              }),
-            );
-          }).pipe(
             Effect.catch((error: PreviewManagerError) => {
               resume(Effect.fail(error));
-              return cleanup;
+              return cleanup();
             }),
           ),
         );
 @@ -1401,6 +1417,19 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
     };
   });
+  const startScreencast = Effect.fn("PreviewManager.startScreencast")(function* (
+    send: SendCommand,
+  ) {
+    yield* send("Page.enable");
+    yield* send("Page.startScreencast", {
+      format: "jpeg",
+      quality: 80,
+      maxWidth: 1600,
+      maxHeight: 1200,
+      everyNthFrame: 1,
+    });
+  });
   const startRecording = Effect.fn("PreviewManager.startRecording")(function* (tabId: string) {
     const recordingTabId = yield* Ref.get(recordingTabIdRef);
     if (Option.isSome(recordingTabId) && recordingTabId.value !== tabId) {
 @@ -1410,18 +1439,7 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
       );
     }
     const wc = yield* requireWebContents(tabId);
-    yield* withControlSession(tabId, wc, "recording.start", (send) =>
+    yield* withControlSession(tabId, wc, "recording.start", startScreencast);
-      Effect.gen(function* () {
-        yield* send("Page.enable");
-        yield* send("Page.startScreencast", {
-          format: "jpeg",
-          quality: 80,
-          maxWidth: 1600,
-          maxHeight: 1200,
-          everyNthFrame: 1,
-        });
-      }),
-    );
     yield* Ref.set(recordingTabIdRef, Option.some(tabId));
   });
 @@ -1493,104 +1511,108 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
         };
   });
+  const captureAutomationSnapshot = Effect.fn("PreviewManager.captureAutomationSnapshot")(
+    function* (tabId: string, wc: Electron.WebContents, send: SendCommand) {
+      yield* Effect.all([send("Runtime.enable"), send("Accessibility.enable")], {
+        concurrency: 2,
+        discard: true,
+      });
+      const page = yield* evaluateWithDebugger<{
+        url: string;
+        title: string;
+        loading: boolean;
+        visibleText: string;
+        interactiveElements: PreviewAutomationSnapshot["interactiveElements"];
+      }>(
+        send,
+        `(() => {
+          const selectorFor = (element) => {
+            if (element.id) return "#" + CSS.escape(element.id);
+            for (const attribute of ["data-testid", "name"]) {
+              const value = element.getAttribute(attribute);
+              if (value) return element.tagName.toLowerCase() + "[" + attribute + "=" + JSON.stringify(value) + "]";
+            }
+            const buildParts = (current, parts = []) => {
+              if (!current || current.nodeType !== Node.ELEMENT_NODE || parts.length >= 8) {
+                return parts;
+              }
+              const parent = current.parentElement;
+              const siblings = parent
+                ? Array.from(parent.children).filter((child) => child.tagName === current.tagName)
+                : [];
+              const base = current.tagName.toLowerCase();
+              const part = siblings.length > 1
+                ? base + ":nth-of-type(" + (siblings.indexOf(current) + 1) + ")"
+                : base;
+              return buildParts(parent, [part, ...parts]);
+            };
+            return buildParts(element).join(" > ");
+          };
+          const visible = (element) => {
+            const style = getComputedStyle(element);
+            const rect = element.getBoundingClientRect();
+            return style.visibility !== "hidden" && style.display !== "none" && rect.width > 0 && rect.height > 0;
+          };
+          const elements = Array.from(document.querySelectorAll(
+            "a[href],button,input,textarea,select,[role],[tabindex]"
+          )).filter(visible).slice(0, ${MAX_INTERACTIVE_ELEMENTS}).map((element) => {
+            const rect = element.getBoundingClientRect();
+            return {
+              tag: element.tagName.toLowerCase(),
+              role: element.getAttribute("role"),
+              name: element.getAttribute("aria-label") || element.innerText || element.getAttribute("name") || "",
+              selector: selectorFor(element),
+              x: rect.x,
+              y: rect.y,
+              width: rect.width,
+              height: rect.height
+            };
+          });
+          return {
+            url: location.href,
+            title: document.title,
+            loading: document.readyState !== "complete",
+            visibleText: (document.body?.innerText || "").slice(0, ${MAX_VISIBLE_TEXT_LENGTH}),
+            interactiveElements: elements
+          };
+        })()`,
+        true,
+      );
+      const [accessibility, sourceImage, diagnostics, timelines] = yield* Effect.all([
+        send("Accessibility.getFullAXTree"),
+        attemptPromise("automationSnapshot.capturePage", () => wc.capturePage()),
+        Ref.get(diagnosticsRef),
+        Ref.get(actionTimelineRef),
+      ]);
+      const sourceSize = sourceImage.getSize();
+      const image =
+        sourceSize.width > MAX_SCREENSHOT_WIDTH
+          ? sourceImage.resize({ width: MAX_SCREENSHOT_WIDTH })
+          : sourceImage;
+      const size = image.getSize();
+      const browserDiagnostics = diagnostics.get(wc.id);
+      return {
+        ...page,
+        accessibilityTree: accessibility,
+        consoleEntries: [...(browserDiagnostics?.consoleEntries ?? [])],
+        networkEntries: [...(browserDiagnostics?.networkEntries ?? [])],
+        actionTimeline: [...(timelines.get(tabId) ?? [])],
+        screenshot: {
+          mimeType: "image/png" as const,
+          data: image.toPNG().toString("base64"),
+          width: size.width,
+          height: size.height,
+        },
+      };
+    },
+  );
   const automationSnapshot = Effect.fn("PreviewManager.automationSnapshot")(function* (
     tabId: string,
   ) {
     const wc = yield* requireWebContents(tabId);
     return yield* withControlSession(tabId, wc, "snapshot", (send) =>
-      Effect.gen(function* () {
+      captureAutomationSnapshot(tabId, wc, send),
-        yield* Effect.all([send("Runtime.enable"), send("Accessibility.enable")], {
-          concurrency: 2,
-          discard: true,
-        });
-        const page = yield* evaluateWithDebugger<{
-          url: string;
-          title: string;
-          loading: boolean;
-          visibleText: string;
-          interactiveElements: PreviewAutomationSnapshot["interactiveElements"];
-        }>(
-          send,
-          `(() => {
-            const selectorFor = (element) => {
-              if (element.id) return "#" + CSS.escape(element.id);
-              for (const attribute of ["data-testid", "name"]) {
-                const value = element.getAttribute(attribute);
-                if (value) return element.tagName.toLowerCase() + "[" + attribute + "=" + JSON.stringify(value) + "]";
-              }
-              const buildParts = (current, parts = []) => {
-                if (!current || current.nodeType !== Node.ELEMENT_NODE || parts.length >= 8) {
-                  return parts;
-                }
-                const parent = current.parentElement;
-                const siblings = parent
-                  ? Array.from(parent.children).filter((child) => child.tagName === current.tagName)
-                  : [];
-                const base = current.tagName.toLowerCase();
-                const part = siblings.length > 1
-                  ? base + ":nth-of-type(" + (siblings.indexOf(current) + 1) + ")"
-                  : base;
-                return buildParts(parent, [part, ...parts]);
-              };
-              return buildParts(element).join(" > ");
-            };
-            const visible = (element) => {
-              const style = getComputedStyle(element);
-              const rect = element.getBoundingClientRect();
-              return style.visibility !== "hidden" && style.display !== "none" && rect.width > 0 && rect.height > 0;
-            };
-            const elements = Array.from(document.querySelectorAll(
-              "a[href],button,input,textarea,select,[role],[tabindex]"
-            )).filter(visible).slice(0, ${MAX_INTERACTIVE_ELEMENTS}).map((element) => {
-              const rect = element.getBoundingClientRect();
-              return {
-                tag: element.tagName.toLowerCase(),
-                role: element.getAttribute("role"),
-                name: element.getAttribute("aria-label") || element.innerText || element.getAttribute("name") || "",
-                selector: selectorFor(element),
-                x: rect.x,
-                y: rect.y,
-                width: rect.width,
-                height: rect.height
-              };
-            });
-            return {
-              url: location.href,
-              title: document.title,
-              loading: document.readyState !== "complete",
-              visibleText: (document.body?.innerText || "").slice(0, ${MAX_VISIBLE_TEXT_LENGTH}),
-              interactiveElements: elements
-            };
-          })()`,
-          true,
-        );
-        const [accessibility, sourceImage, diagnostics, timelines] = yield* Effect.all([
-          send("Accessibility.getFullAXTree"),
-          attemptPromise("automationSnapshot.capturePage", () => wc.capturePage()),
-          Ref.get(diagnosticsRef),
-          Ref.get(actionTimelineRef),
-        ]);
-        const sourceSize = sourceImage.getSize();
-        const image =
-          sourceSize.width > MAX_SCREENSHOT_WIDTH
-            ? sourceImage.resize({ width: MAX_SCREENSHOT_WIDTH })
-            : sourceImage;
-        const size = image.getSize();
-        const browserDiagnostics = diagnostics.get(wc.id);
-        return {
-          ...page,
-          accessibilityTree: accessibility,
-          consoleEntries: [...(browserDiagnostics?.consoleEntries ?? [])],
-          networkEntries: [...(browserDiagnostics?.networkEntries ?? [])],
-          actionTimeline: [...(timelines.get(tabId) ?? [])],
-          screenshot: {
-            mimeType: "image/png" as const,
-            data: image.toPNG().toString("base64"),
-            width: size.width,
-            height: size.height,
-          },
-        };
-      }),
     );
   });
 @@ -1657,66 +1679,72 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
     );
   });
+  const performAutomationClick = Effect.fn("PreviewManager.performAutomationClick")(function* (
+    tabId: string,
+    input: PreviewAutomationClickInput,
+    send: SendCommand,
+  ) {
+    yield* Effect.all(
+      [send("Runtime.enable"), send("Input.setIgnoreInputEvents", { ignore: false })],
+      { concurrency: 2, discard: true },
+    );
+    const point = yield* resolveClickPoint(send, input);
+    const viewport = yield* evaluateWithDebugger<{ width: number; height: number }>(
+      send,
+      "({ width: window.innerWidth, height: window.innerHeight })",
+      true,
+    );
+    if (point.x < 0 || point.y < 0 || point.x > viewport.width || point.y > viewport.height) {
+      return yield* fail(
+        "automationClick",
+        automationError(
+          "PreviewAutomationExecutionError",
+          `Click coordinates (${point.x}, ${point.y}) are outside the preview viewport.`,
+        ),
+      );
+    }
+    const moveSequence = yield* nextCounter(pointerSequenceRef);
+    const moveCreatedAt = yield* currentIso;
+    yield* emitPointerEvent({
+      tabId,
+      phase: "move",
+      ...point,
+      sequence: moveSequence,
+      createdAt: moveCreatedAt,
+    });
+    yield* Effect.sleep(AGENT_CURSOR_MOVE_MS);
+    const clickSequence = yield* nextCounter(pointerSequenceRef);
+    const clickCreatedAt = yield* currentIso;
+    yield* emitPointerEvent({
+      tabId,
+      phase: "click",
+      ...point,
+      sequence: clickSequence,
+      createdAt: clickCreatedAt,
+    });
+    yield* Effect.sleep(AGENT_CURSOR_CLICK_LEAD_MS);
+    yield* expectAgentInput(tabId, { kind: "pointer", ...point, button: 0 });
+    yield* send("Input.dispatchMouseEvent", {
+      type: "mousePressed",
+      ...point,
+      button: "left",
+      clickCount: 1,
+    });
+    yield* send("Input.dispatchMouseEvent", {
+      type: "mouseReleased",
+      ...point,
+      button: "left",
+      clickCount: 1,
+    });
+  });
   const automationClick = Effect.fn("PreviewManager.automationClick")(function* (
     tabId: string,
     input: PreviewAutomationClickInput,
   ) {
     const wc = yield* requireWebContents(tabId);
     yield* withControlSession(tabId, wc, "click", (send) =>
-      Effect.gen(function* () {
+      performAutomationClick(tabId, input, send),
-        yield* Effect.all(
-          [send("Runtime.enable"), send("Input.setIgnoreInputEvents", { ignore: false })],
-          { concurrency: 2, discard: true },
-        );
-        const point = yield* resolveClickPoint(send, input);
-        const viewport = yield* evaluateWithDebugger<{ width: number; height: number }>(
-          send,
-          "({ width: window.innerWidth, height: window.innerHeight })",
-          true,
-        );
-        if (point.x < 0 || point.y < 0 || point.x > viewport.width || point.y > viewport.height) {
-          return yield* fail(
-            "automationClick",
-            automationError(
-              "PreviewAutomationExecutionError",
-              `Click coordinates (${point.x}, ${point.y}) are outside the preview viewport.`,
-            ),
-          );
-        }
-        const moveSequence = yield* nextCounter(pointerSequenceRef);
-        const moveCreatedAt = yield* currentIso;
-        yield* emitPointerEvent({
-          tabId,
-          phase: "move",
-          ...point,
-          sequence: moveSequence,
-          createdAt: moveCreatedAt,
-        });
-        yield* Effect.sleep(AGENT_CURSOR_MOVE_MS);
-        const clickSequence = yield* nextCounter(pointerSequenceRef);
-        const clickCreatedAt = yield* currentIso;
-        yield* emitPointerEvent({
-          tabId,
-          phase: "click",
-          ...point,
-          sequence: clickSequence,
-          createdAt: clickCreatedAt,
-        });
-        yield* Effect.sleep(AGENT_CURSOR_CLICK_LEAD_MS);
-        yield* expectAgentInput(tabId, { kind: "pointer", ...point, button: 0 });
-        yield* send("Input.dispatchMouseEvent", {
-          type: "mousePressed",
-          ...point,
-          button: "left",
-          clickCount: 1,
-        });
-        yield* send("Input.dispatchMouseEvent", {
-          type: "mouseReleased",
-          ...point,
-          button: "left",
-          clickCount: 1,
-        });
-      }),
     );
   });
 @@ -1769,171 +1797,188 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
     }
   });
+  const performAutomationType = Effect.fn("PreviewManager.performAutomationType")(function* (
+    tabId: string,
+    input: PreviewAutomationTypeInput,
+    send: SendCommand,
+  ) {
+    yield* send("Runtime.enable");
+    yield* focusAutomationTarget(send, input);
+    yield* send("Input.insertText", { text: input.text });
+    const textJson = yield* encodeJson("automationType.encodeText", input.text);
+    yield* evaluateWithDebugger(
+      send,
+      `(() => {
+        const element = document.activeElement;
+        element?.dispatchEvent(new InputEvent("input", { bubbles: true, inputType: "insertText", data: ${textJson} }));
+        element?.dispatchEvent(new Event("change", { bubbles: true }));
+      })()`,
+      false,
+    );
+  });
   const automationType = Effect.fn("PreviewManager.automationType")(function* (
     tabId: string,
     input: PreviewAutomationTypeInput,
   ) {
     const wc = yield* requireWebContents(tabId);
     yield* withControlSession(tabId, wc, "type", (send) =>
-      Effect.gen(function* () {
+      performAutomationType(tabId, input, send),
-        yield* send("Runtime.enable");
-        yield* focusAutomationTarget(send, input);
-        yield* send("Input.insertText", { text: input.text });
-        const textJson = yield* encodeJson("automationType.encodeText", input.text);
-        yield* evaluateWithDebugger(
-          send,
-          `(() => {
-            const element = document.activeElement;
-            element?.dispatchEvent(new InputEvent("input", { bubbles: true, inputType: "insertText", data: ${textJson} }));
-            element?.dispatchEvent(new Event("change", { bubbles: true }));
-          })()`,
-          false,
-        );
-      }),
     );
   });
+  const performAutomationPress = Effect.fn("PreviewManager.performAutomationPress")(function* (
+    tabId: string,
+    input: PreviewAutomationPressInput,
+    send: SendCommand,
+  ) {
+    const modifiers = (input.modifiers ?? []).reduce((value, modifier) => {
+      switch (modifier) {
+        case "Alt":
+          return value | 1;
+        case "Control":
+          return value | 2;
+        case "Meta":
+          return value | 4;
+        case "Shift":
+          return value | 8;
+      }
+    }, 0);
+    const key = input.key;
+    const text = key.length === 1 ? key : undefined;
+    const params = {
+      key,
+      code: key.length === 1 ? `Key${key.toUpperCase()}` : key,
+      modifiers,
+      ...(text ? { text, unmodifiedText: text } : {}),
+    };
+    yield* expectAgentInput(tabId, { kind: "key", key, code: params.code });
+    yield* send("Input.dispatchKeyEvent", { type: "keyDown", ...params });
+    yield* send("Input.dispatchKeyEvent", { type: "keyUp", ...params });
+  });
   const automationPress = Effect.fn("PreviewManager.automationPress")(function* (
     tabId: string,
     input: PreviewAutomationPressInput,
   ) {
     const wc = yield* requireWebContents(tabId);
     yield* withControlSession(tabId, wc, "press", (send) =>
-      Effect.gen(function* () {
+      performAutomationPress(tabId, input, send),
-        const modifiers = (input.modifiers ?? []).reduce((value, modifier) => {
-          switch (modifier) {
-            case "Alt":
-              return value | 1;
-            case "Control":
-              return value | 2;
-            case "Meta":
-              return value | 4;
-            case "Shift":
-              return value | 8;
-          }
-        }, 0);
-        const key = input.key;
-        const text = key.length === 1 ? key : undefined;
-        const params = {
-          key,
-          code: key.length === 1 ? `Key${key.toUpperCase()}` : key,
-          modifiers,
-          ...(text ? { text, unmodifiedText: text } : {}),
-        };
-        yield* expectAgentInput(tabId, { kind: "key", key, code: params.code });
-        yield* send("Input.dispatchKeyEvent", { type: "keyDown", ...params });
-        yield* send("Input.dispatchKeyEvent", { type: "keyUp", ...params });
-      }),
     );
   });
+  const performAutomationScroll = Effect.fn("PreviewManager.performAutomationScroll")(function* (
+    tabId: string,
+    input: PreviewAutomationScrollInput,
+    send: SendCommand,
+  ) {
+    yield* send("Runtime.enable");
+    const locator = automationLocator(input);
+    if (locator) yield* ensurePlaywrightInjected(send);
+    const locatorJson = locator
+      ? yield* encodeJson("automationScroll.encodeLocator", locator)
+      : null;
+    const result = yield* evaluateWithDebugger<
+      { ok: true } | { invalidSelector: true; message: string } | { notFound: true }
+    >(
+      send,
+      `(() => {
+        try {
+          const target = ${locatorJson ? `(() => { const injected = globalThis.__t3PlaywrightInjected; return injected.querySelector(injected.parseSelector(${locatorJson}), document, true); })()` : "window"};
+          if (!target) return { notFound: true };
+          target.scrollBy({ left: ${input.deltaX ?? 0}, top: ${input.deltaY ?? 0}, behavior: "instant" });
+          return { ok: true };
+        } catch (error) {
+          return { invalidSelector: true, message: String(error) };
+        }
+      })()`,
+      true,
+    );
+    if ("invalidSelector" in result) {
+      return yield* fail(
+        "automationScroll",
+        automationError("PreviewAutomationInvalidSelectorError", result.message, {
+          selector: input.selector ?? "",
+        }),
+      );
+    }
+    if ("notFound" in result) {
+      return yield* fail(
+        "automationScroll",
+        automationError(
+          "PreviewAutomationExecutionError",
+          `No element matches locator ${locator}.`,
+        ),
+      );
+    }
+  });
   const automationScroll = Effect.fn("PreviewManager.automationScroll")(function* (
     tabId: string,
     input: PreviewAutomationScrollInput,
   ) {
     const wc = yield* requireWebContents(tabId);
     yield* withControlSession(tabId, wc, "scroll", (send) =>
-      Effect.gen(function* () {
+      performAutomationScroll(tabId, input, send),
-        yield* send("Runtime.enable");
-        const locator = automationLocator(input);
-        if (locator) yield* ensurePlaywrightInjected(send);
-        const locatorJson = locator
-          ? yield* encodeJson("automationScroll.encodeLocator", locator)
-          : null;
-        const result = yield* evaluateWithDebugger<
-          { ok: true } | { invalidSelector: true; message: string } | { notFound: true }
-        >(
-          send,
-          `(() => {
-            try {
-              const target = ${locatorJson ? `(() => { const injected = globalThis.__t3PlaywrightInjected; return injected.querySelector(injected.parseSelector(${locatorJson}), document, true); })()` : "window"};
-              if (!target) return { notFound: true };
-              target.scrollBy({ left: ${input.deltaX ?? 0}, top: ${input.deltaY ?? 0}, behavior: "instant" });
-              return { ok: true };
-            } catch (error) {
-              return { invalidSelector: true, message: String(error) };
-            }
-          })()`,
-          true,
-        );
-        if ("invalidSelector" in result) {
-          return yield* fail(
-            "automationScroll",
-            automationError("PreviewAutomationInvalidSelectorError", result.message, {
-              selector: input.selector ?? "",
-            }),
-          );
-        }
-        if ("notFound" in result) {
-          return yield* fail(
-            "automationScroll",
-            automationError(
-              "PreviewAutomationExecutionError",
-              `No element matches locator ${locator}.`,
-            ),
-          );
-        }
-      }),
     );
   });
+  const performAutomationEvaluate = Effect.fn("PreviewManager.performAutomationEvaluate")(
+    function* (input: PreviewAutomationEvaluateInput, send: SendCommand) {
+      yield* send("Runtime.enable");
+      const value = yield* evaluateWithDebugger(
+        send,
+        input.expression,
+        input.returnByValue ?? true,
+        input.awaitPromise ?? true,
+      );
+      const serialized = yield* encodeJson("automationEvaluate.encodeResult", value);
+      if (Buffer.byteLength(serialized, "utf8") > MAX_EVALUATION_BYTES) {
+        return yield* fail(
+          "automationEvaluate",
+          automationError(
+            "PreviewAutomationResultTooLargeError",
+            `Evaluation result exceeds ${MAX_EVALUATION_BYTES} bytes.`,
+            { maximumBytes: MAX_EVALUATION_BYTES },
+          ),
+        );
+      }
+      return value;
+    },
+  );
   const automationEvaluate = Effect.fn("PreviewManager.automationEvaluate")(function* (
     tabId: string,
     input: PreviewAutomationEvaluateInput,
   ) {
     const wc = yield* requireWebContents(tabId);
     return yield* withControlSession(tabId, wc, "evaluate", (send) =>
-      Effect.gen(function* () {
+      performAutomationEvaluate(input, send),
-        yield* send("Runtime.enable");
-        const value = yield* evaluateWithDebugger(
-          send,
-          input.expression,
-          input.returnByValue ?? true,
-          input.awaitPromise ?? true,
-        );
-        const serialized = yield* encodeJson("automationEvaluate.encodeResult", value);
-        if (Buffer.byteLength(serialized, "utf8") > MAX_EVALUATION_BYTES) {
-          return yield* fail(
-            "automationEvaluate",
-            automationError(
-              "PreviewAutomationResultTooLargeError",
-              `Evaluation result exceeds ${MAX_EVALUATION_BYTES} bytes.`,
-              { maximumBytes: MAX_EVALUATION_BYTES },
-            ),
-          );
-        }
-        return value;
-      }),
     );
   });
-  const automationWaitFor = Effect.fn("PreviewManager.automationWaitFor")(function* (
+  const performAutomationWaitFor = Effect.fn("PreviewManager.performAutomationWaitFor")(function* (
-    tabId: string,
     input: PreviewAutomationWaitForInput,
+    send: SendCommand,
   ) {
-    const wc = yield* requireWebContents(tabId);
     const timeoutMs = input.timeoutMs ?? 15_000;
-    yield* withControlSession(tabId, wc, "waitFor", (send) =>
+    yield* send("Runtime.enable");
-      Effect.gen(function* () {
+    const locator = automationLocator(input);
-        yield* send("Runtime.enable");
+    if (locator) yield* ensurePlaywrightInjected(send);
-        const locator = automationLocator(input);
+    const [locatorJson, textJson, urlIncludesJson] = yield* Effect.all([
-        if (locator) yield* ensurePlaywrightInjected(send);
+      locator ? encodeJson("automationWaitFor.encodeLocator", locator) : Effect.succeed(null),
-        const [locatorJson, textJson, urlIncludesJson] = yield* Effect.all([
+      input.text ? encodeJson("automationWaitFor.encodeText", input.text) : Effect.succeed(null),
-          locator ? encodeJson("automationWaitFor.encodeLocator", locator) : Effect.succeed(null),
+      input.urlIncludes
-          input.text
+        ? encodeJson("automationWaitFor.encodeUrl", input.urlIncludes)
-            ? encodeJson("automationWaitFor.encodeText", input.text)
+        : Effect.succeed(null),
-            : Effect.succeed(null),
+    ]);
-          input.urlIncludes
+    const deadline = (yield* currentMillis) + timeoutMs;
-            ? encodeJson("automationWaitFor.encodeUrl", input.urlIncludes)
+    while ((yield* currentMillis) <= deadline) {
-            : Effect.succeed(null),
+      const result = yield* evaluateWithDebugger<
-        ]);
+        { matched: boolean } | { invalidSelector: true; message: string }
-        const deadline = (yield* currentMillis) + timeoutMs;
+      >(
-        while ((yield* currentMillis) <= deadline) {
+        send,
-          const result = yield* evaluateWithDebugger<
+        `(() => {
-            { matched: boolean } | { invalidSelector: true; message: string }
-          >(
-            send,
-            `(() => {
               try {
                 const selectorMatched = ${locatorJson ? `(() => { const injected = globalThis.__t3PlaywrightInjected; return injected.querySelector(injected.parseSelector(${locatorJson}), document, false) !== null; })()` : "true"};
                 const textMatched = ${
 @@ -1947,27 +1992,35 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
                 return { invalidSelector: true, message: String(error) };
               }
             })()`,
-            true,
+        true,
-          );
+      );
-          if ("invalidSelector" in result) {
+      if ("invalidSelector" in result) {
-            return yield* fail(
-              "automationWaitFor",
-              automationError("PreviewAutomationInvalidSelectorError", result.message, {
-                selector: input.selector ?? "",
-              }),
-            );
-          }
-          if (result.matched) return;
-          yield* Effect.sleep(100);
-        }
         return yield* fail(
           "automationWaitFor",
-          automationError(
+          automationError("PreviewAutomationInvalidSelectorError", result.message, {
-            "PreviewAutomationTimeoutError",
+            selector: input.selector ?? "",
-            `Preview condition did not match within ${timeoutMs}ms.`,
+          }),
-          ),
         );
-      }),
+      }
+      if (result.matched) return;
+      yield* Effect.sleep(100);
+    }
+    return yield* fail(
+      "automationWaitFor",
+      automationError(
+        "PreviewAutomationTimeoutError",
+        `Preview condition did not match within ${timeoutMs}ms.`,
+      ),
+    );
+  });
+  const automationWaitFor = Effect.fn("PreviewManager.automationWaitFor")(function* (
+    tabId: string,
+    input: PreviewAutomationWaitForInput,
+  ) {
+    const wc = yield* requireWebContents(tabId);
+    yield* withControlSession(tabId, wc, "waitFor", (send) =>
+      performAutomationWaitFor(input, send),
     );
   });

apps/server/src/mcp/McpHttpServer.test.ts+1-1

...	@@ -158,7 +158,7 @@ it.effect("registers annotated tools and preserves authenticated request context	...	@@ -158,7 +158,7 @@ it.effect("registers annotated tools and preserves authenticated request context
158	Effect.provideService(McpSchema.McpServerClient, client),	158	Effect.provideService(McpSchema.McpServerClient, client),
159	);	159	);
160	expect(press.isError).toBe(false);	160	expect(press.isError).toBe(false);
161	expect(press.structuredContent).toBeUndefined();	161	expect(press.structuredContent).toBeNull();
162	expect(press.content).toEqual([{ type: "text", text: "null" }]);	162	expect(press.content).toEqual([{ type: "text", text: "null" }]);
163	}),	163	}),
164	).pipe(Effect.provide(TestLayer)),	164	).pipe(Effect.provide(TestLayer)),

apps/server/src/mcp/McpHttpServer.ts+80-75

...	@@ -13,8 +13,15 @@ import packageJson from "../../package.json" with { type: "json" };	...	@@ -13,8 +13,15 @@ import packageJson from "../../package.json" with { type: "json" };
13	import * as McpInvocationContext from "./McpInvocationContext.ts";	13	import * as McpInvocationContext from "./McpInvocationContext.ts";
14	import * as McpSessionRegistry from "./McpSessionRegistry.ts";	14	import * as McpSessionRegistry from "./McpSessionRegistry.ts";
15	import * as PreviewAutomationBroker from "./PreviewAutomationBroker.ts";	15	import * as PreviewAutomationBroker from "./PreviewAutomationBroker.ts";
16	import { PreviewToolkitHandlersLive } from "./toolkits/preview/handlers.ts";	16	import {
17	import { PreviewToolkit } from "./toolkits/preview/tools.ts";	17	PreviewSnapshotToolkitHandlersLive,
		18	PreviewStandardToolkitHandlersLive,
		19	} from "./toolkits/preview/handlers.ts";
		20	import {
		21	PreviewSnapshotTool,
		22	PreviewSnapshotToolkit,
		23	PreviewStandardToolkit,
		24	} from "./toolkits/preview/tools.ts";
18		25
19	const unauthorized = HttpServerResponse.jsonUnsafe(	26	const unauthorized = HttpServerResponse.jsonUnsafe(
20	{	27	{
...	@@ -81,97 +88,95 @@ const McpAuthMiddlewareLive = HttpRouter.middleware<{	...	@@ -81,97 +88,95 @@ const McpAuthMiddlewareLive = HttpRouter.middleware<{
81	provides: McpInvocationContext.McpInvocationContext;	88	provides: McpInvocationContext.McpInvocationContext;
82	}>()(makeMcpAuthMiddleware).layer;	89	}>()(makeMcpAuthMiddleware).layer;
83		90
84	const registerPreviewToolkit = Effect.fn("McpHttpServer.registerPreviewToolkit")(function* () {	91	const registerPreviewSnapshot = Effect.fn("McpHttpServer.registerPreviewSnapshot")(function* () {
85	const server = yield* McpServer.McpServer;	92	const server = yield* McpServer.McpServer;
86	const built = yield* PreviewToolkit;	93	const broker = yield* PreviewAutomationBroker.PreviewAutomationBroker;
87	const handleTool = built.handle as unknown as (	94	const built = yield* PreviewSnapshotToolkit;
88	name: keyof typeof built.tools,	95	const tool = PreviewSnapshotTool;
89	payload: unknown,	96	yield* server.addTool({
90	) => Effect.Effect<	97	tool: new McpSchema.Tool({
91	Stream.Stream<{ readonly encodedResult: unknown }, Error>,	98	name: tool.name,
92	Error,	99	description: Tool.getDescription(tool),
93	McpInvocationContext.McpInvocationContext	100	inputSchema: Tool.getJsonSchema(tool),
94	>;	101	annotations: {
95	for (const tool of Object.values(built.tools)) {	102	...Context.getOption(tool.annotations, Tool.Title).pipe(
96	yield* server.addTool({	103	Option.map((title) => ({ title })),
97	tool: new McpSchema.Tool({	104	Option.getOrUndefined,
98	name: tool.name,	105	),
99	description: Tool.getDescription(tool),	106	readOnlyHint: Context.get(tool.annotations, Tool.Readonly),
100	inputSchema: Tool.getJsonSchema(tool),	107	destructiveHint: Context.get(tool.annotations, Tool.Destructive),
101	annotations: {	108	idempotentHint: Context.get(tool.annotations, Tool.Idempotent),
102	...Context.getOption(tool.annotations, Tool.Title).pipe(	109	openWorldHint: Context.get(tool.annotations, Tool.OpenWorld),
103	Option.map((title) => ({ title })),	110	},
104	Option.getOrUndefined,	111	}),
105	),	112	annotations: tool.annotations,
106	readOnlyHint: Context.get(tool.annotations, Tool.Readonly),	113	handle: (payload) =>
107	destructiveHint: Context.get(tool.annotations, Tool.Destructive),	114	Effect.withFiber((fiber) => {
108	idempotentHint: Context.get(tool.annotations, Tool.Idempotent),	115	const invocation = Context.getUnsafe(
109	openWorldHint: Context.get(tool.annotations, Tool.OpenWorld),	116	fiber.context,
110	},	117	McpInvocationContext.McpInvocationContext,
111	}),	118	);
112	annotations: tool.annotations,	119	return built.handle("preview_snapshot", payload).pipe(
113	handle: (payload) =>
114	handleTool(tool.name as keyof typeof built.tools, payload).pipe(
115	Stream.unwrap,	120	Stream.unwrap,
116	Stream.run(Sink.last()),	121	Stream.run(Sink.last()),
117	Effect.flatMap(Effect.fromOption),	122	Effect.flatMap(Effect.fromOption),
		123	Effect.provideService(PreviewAutomationBroker.PreviewAutomationBroker, broker),
		124	Effect.provideService(McpInvocationContext.McpInvocationContext, invocation),
118	Effect.matchCause({	125	Effect.matchCause({
119	onFailure: (cause) =>	126	onFailure: (cause) =>
120	new McpSchema.CallToolResult({	127	new McpSchema.CallToolResult({
121	isError: true,	128	isError: true,
122	content: [{ type: "text", text: Cause.pretty(cause) }],	129	content: [{ type: "text", text: Cause.pretty(cause) }],
123	}),	130	}),
124	onSuccess: (result) => {	131	onSuccess: ({ encodedResult }) => {
125	if (tool.name === "preview_snapshot") {	132	const snapshot = encodedResult as {
126	const snapshot = result.encodedResult as {	133	readonly screenshot: {
127	readonly screenshot: {	134	readonly mimeType: "image/png";
128	readonly mimeType: "image/png";	135	readonly data: string;
129	readonly data: string;	136	readonly width: number;
130	readonly width: number;	137	readonly height: number;
131	readonly height: number;
132	};
133	readonly [key: string]: unknown;
134	};	138	};
135	const { screenshot, ...page } = snapshot;	139	readonly [key: string]: unknown;
136	const metadata = {	140	};
137	...page,	141	const { screenshot, ...page } = snapshot;
138	screenshot: {	142	const metadata = {
139	mimeType: screenshot.mimeType,	143	...page,
140	width: screenshot.width,	144	screenshot: {
141	height: screenshot.height,	145	mimeType: screenshot.mimeType,
142	},	146	width: screenshot.width,
143	};	147	height: screenshot.height,
144	return new McpSchema.CallToolResult({	148	},
145	isError: false,	149	};
146	structuredContent: metadata,
147	content: [
148	{ type: "text", text: JSON.stringify(metadata) },
149	{
150	type: "image",
151	data: new Uint8Array(Buffer.from(screenshot.data, "base64")),
152	mimeType: screenshot.mimeType,
153	},
154	],
155	});
156	}
157	const encodedResultText = JSON.stringify(result.encodedResult) ?? "null";
158	return new McpSchema.CallToolResult({	150	return new McpSchema.CallToolResult({
159	isError: false,	151	isError: false,
160	structuredContent:	152	structuredContent: metadata,
161	result.encodedResult !== null && typeof result.encodedResult === "object"	153	content: [
162	? result.encodedResult	154	{ type: "text", text: JSON.stringify(metadata) },
163	: undefined,	155	{
164	content: [{ type: "text", text: encodedResultText }],	156	type: "image",
		157	data: new Uint8Array(Buffer.from(screenshot.data, "base64")),
		158	mimeType: screenshot.mimeType,
		159	},
		160	],
165	});	161	});
166	},	162	},
167	}),	163	}),
168	) as unknown as Effect.Effect<McpSchema.CallToolResult, never, McpSchema.McpServerClient>,	164	);
169	});	165	}),
170	}	166	});
171	});	167	});
172		168
173	export const PreviewToolkitRegistrationLive = Layer.effectDiscard(registerPreviewToolkit()).pipe(	169	const PreviewStandardToolkitRegistrationLive = McpServer.toolkit(PreviewStandardToolkit).pipe(
174	Layer.provide(PreviewToolkitHandlersLive),	170	Layer.provide(PreviewStandardToolkitHandlersLive),
		171	);
		172
		173	const PreviewSnapshotRegistrationLive = Layer.effectDiscard(registerPreviewSnapshot()).pipe(
		174	Layer.provide(PreviewSnapshotToolkitHandlersLive),
		175	);
		176
		177	export const PreviewToolkitRegistrationLive = Layer.mergeAll(
		178	PreviewStandardToolkitRegistrationLive,
		179	PreviewSnapshotRegistrationLive,
175	);	180	);
176		181
177	const McpTransportLive = McpServer.layerHttp({	182	const McpTransportLive = McpServer.layerHttp({

apps/server/src/mcp/McpSessionRegistry.ts+35-33

 @@ -1,9 +1,10 @@
 import { ProviderInstanceId, ThreadId } from "@t3tools/contracts";
+import * as Clock from "effect/Clock";
 import * as Context from "effect/Context";
 import * as Crypto from "effect/Crypto";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
-import * as Ref from "effect/Ref";
+import * as SynchronizedRef from "effect/SynchronizedRef";
 import { HttpServer } from "effect/unstable/http";
 import { ServerEnvironment } from "../environment/Services/ServerEnvironment.ts";
 @@ -59,15 +60,15 @@ const bytesToHex = (bytes: Uint8Array): string =>
 const tokenFromBytes = (bytes: Uint8Array): string => Buffer.from(bytes).toString("base64url");
-const make = Effect.fn("McpSessionRegistry.make")(function* (
+const makeWithOptions = Effect.fn("McpSessionRegistry.make")(function* (
   options: McpSessionRegistryOptions = {},
 ) {
   const crypto = yield* Crypto.Crypto;
   const environment = yield* ServerEnvironment;
   const environmentId = yield* environment.getEnvironmentId;
   const httpServer = yield* HttpServer.HttpServer;
-  const state = yield* Ref.make<RegistryState>({ records: new Map() });
+  const state = yield* SynchronizedRef.make<RegistryState>({ records: new Map() });
-  const now = options.now ?? Date.now;
+  const currentTimeMillis = options.now ? Effect.sync(options.now) : Clock.currentTimeMillis;
   const idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
   const maximumLifetimeMs = options.maximumLifetimeMs ?? DEFAULT_MAXIMUM_LIFETIME_MS;
   const endpoint =
 @@ -81,21 +82,18 @@ const make = Effect.fn("McpSessionRegistry.make")(function* (
       .pipe(Effect.map(bytesToHex), Effect.orDie);
   const pruneExpired = (records: ReadonlyMap<string, CredentialRecord>, timestamp: number) => {
-    let changed = false;
+    const next = new Map(
-    const next = new Map<string, CredentialRecord>();
+      Array.from(records).filter(
-    for (const [hash, record] of records) {
+        ([, record]) =>
-      if (timestamp <= record.scope.expiresAt && timestamp - record.lastUsedAt <= idleTimeoutMs) {
+          timestamp <= record.scope.expiresAt && timestamp - record.lastUsedAt <= idleTimeoutMs,
-        next.set(hash, record);
+      ),
-      } else {
+    );
-        changed = true;
+    return next.size === records.size ? records : next;
-      }
-    }
-    return changed ? next : records;
   };
   const issue: McpSessionRegistryShape["issue"] = Effect.fn("McpSessionRegistry.issue")(
     function* (request) {
-      const issuedAt = now();
+      const issuedAt = yield* currentTimeMillis;
       const providerSessionId = yield* crypto.randomUUIDv4.pipe(Effect.orDie);
       const rawToken = yield* crypto.randomBytes(32).pipe(Effect.map(tokenFromBytes), Effect.orDie);
       const tokenHash = yield* hashToken(rawToken);
 @@ -109,7 +107,7 @@ const make = Effect.fn("McpSessionRegistry.make")(function* (
         issuedAt,
         expiresAt,
       };
-      yield* Ref.update(state, ({ records }) => {
+      yield* SynchronizedRef.update(state, ({ records }) => {
         const next = new Map(pruneExpired(records, issuedAt));
         next.set(tokenHash, { tokenHash, scope, lastUsedAt: issuedAt });
         return { records: next };
 @@ -132,23 +130,20 @@ const make = Effect.fn("McpSessionRegistry.make")(function* (
     function* (rawToken) {
       if (rawToken.length === 0) return undefined;
       const tokenHash = yield* hashToken(rawToken);
-      const timestamp = now();
+      const timestamp = yield* currentTimeMillis;
-      let resolved: McpInvocationContext.McpInvocationScope | undefined;
+      return yield* SynchronizedRef.modify(state, ({ records }) => {
-      yield* Ref.update(state, ({ records }) => {
         const current = pruneExpired(records, timestamp);
         const record = current.get(tokenHash);
-        if (!record) return { records: current };
+        if (!record) return [undefined, { records: current }] as const;
-        resolved = record.scope;
         const next = new Map(current);
         next.set(tokenHash, { ...record, lastUsedAt: timestamp });
-        return { records: next };
+        return [record.scope, { records: next }] as const;
       });
-      return resolved;
     },
   );
   const revokeWhere = (predicate: (record: CredentialRecord) => boolean) =>
-    Ref.update(state, ({ records }) => ({
+    SynchronizedRef.update(state, ({ records }) => ({
       records: new Map(Array.from(records).filter(([, record]) => !predicate(record))),
     }));
 @@ -163,27 +158,34 @@ const make = Effect.fn("McpSessionRegistry.make")(function* (
     revokeThread: Effect.fn("McpSessionRegistry.revokeThread")(function* (threadId) {
       yield* revokeWhere((record) => record.scope.threadId === threadId);
     }),
-    revokeAll: Ref.set(state, { records: new Map() }),
+    revokeAll: SynchronizedRef.set(state, { records: new Map() }),
   });
 });
 let activeMcpSessionRegistry: McpSessionRegistryShape | undefined;
-export const layer: Layer.Layer<
+const make = Effect.acquireRelease(
-  McpSessionRegistry,
+  makeWithOptions().pipe(
-  never,
-  Crypto.Crypto | ServerEnvironment | HttpServer.HttpServer
-> = Layer.effect(
-  McpSessionRegistry,
-  make().pipe(
     Effect.tap((registry) =>
       Effect.sync(() => {
         activeMcpSessionRegistry = registry;
       }),
     ),
   ),
+  (registry) =>
+    Effect.sync(() => {
+      if (activeMcpSessionRegistry === registry) {
+        activeMcpSessionRegistry = undefined;
+      }
+    }),
 );
+export const layer: Layer.Layer<
+  McpSessionRegistry,
+  never,
+  Crypto.Crypto | ServerEnvironment | HttpServer.HttpServer
+> = Layer.effect(McpSessionRegistry, make);
 export const issueActiveMcpCredential = (
   request: McpCredentialRequest,
 ): Effect.Effect<McpIssuedCredential | undefined> =>
 @@ -201,5 +203,5 @@ export const revokeAllActiveMcpCredentials = (): Effect.Effect<void> =>
 /** Exposed for tests. */
 export const __testing = {
-  make,
+  make: makeWithOptions,
 };

apps/server/src/mcp/PreviewAutomationBroker.test.ts+3-3

apps/server/src/mcp/PreviewAutomationBroker.ts+53-49

 @@ -21,8 +21,8 @@ import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as Queue from "effect/Queue";
-import * as Ref from "effect/Ref";
 import * as Stream from "effect/Stream";
+import * as SynchronizedRef from "effect/SynchronizedRef";
 import * as McpInvocationContext from "./McpInvocationContext.ts";
 @@ -71,6 +71,7 @@ interface BrokerState {
   readonly clients: ReadonlyMap<string, ClientConnection>;
   readonly owners: ReadonlyMap<string, PreviewAutomationOwner>;
   readonly pending: ReadonlyMap<string, PendingRequest>;
+  readonly requestSequence: number;
 }
 const makeResponseError = (
 @@ -119,33 +120,35 @@ const makeResponseError = (
   }
 };
-const make = Effect.fn("PreviewAutomationBroker.make")(function* () {
+const make = Effect.gen(function* PreviewAutomationBrokerMake() {
-  const state = yield* Ref.make<BrokerState>({
+  const state = yield* SynchronizedRef.make<BrokerState>({
     clients: new Map(),
     owners: new Map(),
     pending: new Map(),
+    requestSequence: 0,
   });
-  let requestSequence = 0;
   const disconnect = Effect.fn("PreviewAutomationBroker.disconnect")(function* (
     clientId: string,
     queue: ClientConnection["queue"],
   ) {
-    const toFail: PendingRequest[] = [];
+    const toFail = yield* SynchronizedRef.modify(state, (current) => {
-    yield* Ref.update(state, (current) => {
+      if (current.clients.get(clientId)?.queue !== queue) {
-      if (current.clients.get(clientId)?.queue !== queue) return current;
+        return [[] as ReadonlyArray<PendingRequest>, current] as const;
+      }
       const clients = new Map(current.clients);
       const owners = new Map(current.owners);
       const pending = new Map(current.pending);
+      const disconnected: PendingRequest[] = [];
       clients.delete(clientId);
       owners.delete(clientId);
       for (const [requestId, entry] of pending) {
         if (entry.clientId === clientId) {
           pending.delete(requestId);
-          toFail.push(entry);
+          disconnected.push(entry);
         }
       }
-      return { clients, owners, pending };
+      return [disconnected, { ...current, clients, owners, pending }] as const;
     });
     yield* Effect.forEach(
       toFail,
 @@ -165,12 +168,10 @@ const make = Effect.fn("PreviewAutomationBroker.make")(function* () {
     "PreviewAutomationBroker.connect",
   )(function* (clientId) {
     const queue = yield* Queue.unbounded<import("@t3tools/contracts").PreviewAutomationRequest>();
-    let previous: ClientConnection | undefined;
+    const previous = yield* SynchronizedRef.modify(state, (current) => {
-    yield* Ref.update(state, (current) => {
-      previous = current.clients.get(clientId);
       const clients = new Map(current.clients);
       clients.set(clientId, { clientId, queue });
-      return { ...current, clients };
+      return [current.clients.get(clientId), { ...current, clients }] as const;
     });
     if (previous) yield* disconnect(clientId, previous.queue);
     return Stream.fromQueue(queue).pipe(Stream.ensuring(disconnect(clientId, queue)));
 @@ -179,7 +180,7 @@ const make = Effect.fn("PreviewAutomationBroker.make")(function* () {
   const reportOwner: PreviewAutomationBrokerShape["reportOwner"] = Effect.fn(
     "PreviewAutomationBroker.reportOwner",
   )(function* (owner) {
-    yield* Ref.update(state, (current) => {
+    yield* SynchronizedRef.update(state, (current) => {
       const owners = new Map(current.owners);
       owners.set(owner.clientId, owner);
       return { ...current, owners };
 @@ -189,7 +190,7 @@ const make = Effect.fn("PreviewAutomationBroker.make")(function* () {
   const clearOwner: PreviewAutomationBrokerShape["clearOwner"] = Effect.fn(
     "PreviewAutomationBroker.clearOwner",
   )(function* (clientId) {
-    yield* Ref.update(state, (current) => {
+    yield* SynchronizedRef.update(state, (current) => {
       const owners = new Map(current.owners);
       owners.delete(clientId);
       return { ...current, owners };
 @@ -199,13 +200,12 @@ const make = Effect.fn("PreviewAutomationBroker.make")(function* () {
   const respond: PreviewAutomationBrokerShape["respond"] = Effect.fn(
     "PreviewAutomationBroker.respond",
   )(function* (response) {
-    let pending: PendingRequest | undefined;
+    const pending = yield* SynchronizedRef.modify(state, (current) => {
-    yield* Ref.update(state, (current) => {
+      const entry = current.pending.get(response.requestId);
-      pending = current.pending.get(response.requestId);
+      if (!entry) return [undefined, current] as const;
-      if (!pending) return current;
       const next = new Map(current.pending);
       next.delete(response.requestId);
-      return { ...current, pending: next };
+      return [entry, { ...current, pending: next }] as const;
     });
     if (!pending) return;
     if (response.ok) {
 @@ -225,7 +225,7 @@ const make = Effect.fn("PreviewAutomationBroker.make")(function* () {
   const invoke = Effect.fn("PreviewAutomationBroker.invoke")(function* <A = unknown>(
     input: Parameters<PreviewAutomationBrokerShape["invoke"]>[0],
   ): Effect.fn.Return<A, PreviewAutomationError> {
-    const current = yield* Ref.get(state);
+    const current = yield* SynchronizedRef.get(state);
     const candidates = Array.from(current.owners.values())
       .filter(
         (owner) =>
 @@ -256,48 +256,52 @@ const make = Effect.fn("PreviewAutomationBroker.make")(function* () {
         message: "The browser host does not have an active tab.",
       });
     }
-    const requestId = `preview-${requestSequence++}`;
     const timeoutMs = input.timeoutMs ?? 15_000;
     const deferred = yield* Deferred.make<unknown, PreviewAutomationError>();
-    yield* Ref.update(state, (next) => {
+    const requestId = yield* SynchronizedRef.modify(state, (next) => {
+      const requestId = `preview-${next.requestSequence}`;
       const pending = new Map(next.pending);
       pending.set(requestId, { clientId: owner.clientId, deferred });
-      return { ...next, pending };
+      return [requestId, { ...next, pending, requestSequence: next.requestSequence + 1 }] as const;
-    });
-    const offered = yield* Queue.offer(connection.queue, {
-      requestId,
-      threadId: input.scope.threadId,
-      tabId: input.tabId ?? owner.tabId ?? undefined,
-      operation: input.operation,
-      input: input.input,
-      timeoutMs,
     });
-    if (!offered) {
+    const removePending = SynchronizedRef.update(state, (next) => {
-      return yield* new PreviewAutomationUnavailableError({
+      if (!next.pending.has(requestId)) return next;
-        message: "The preview automation client is no longer accepting requests.",
-      });
-    }
-    const result = yield* Deferred.await(deferred).pipe(Effect.timeoutOption(timeoutMs));
-    yield* Ref.update(state, (next) => {
       const pending = new Map(next.pending);
       pending.delete(requestId);
       return { ...next, pending };
     });
-    return yield* Option.match(result, {
+    const awaitResponse = Effect.fn("PreviewAutomationBroker.awaitResponse")(function* () {
-      onNone: () =>
+      const offered = yield* Queue.offer(connection.queue, {
-        Effect.fail(
+        requestId,
-          new PreviewAutomationTimeoutError({
+        threadId: input.scope.threadId,
-            message: `Preview automation timed out after ${timeoutMs}ms.`,
+        tabId: input.tabId ?? owner.tabId ?? undefined,
-          }),
+        operation: input.operation,
-        ),
+        input: input.input,
-      onSome: (value) => Effect.succeed(value as A),
+        timeoutMs,
+      });
+      if (!offered) {
+        return yield* new PreviewAutomationUnavailableError({
+          message: "The preview automation client is no longer accepting requests.",
+        });
+      }
+      const result = yield* Deferred.await(deferred).pipe(Effect.timeoutOption(timeoutMs));
+      return yield* Option.match(result, {
+        onNone: () =>
+          Effect.fail(
+            new PreviewAutomationTimeoutError({
+              message: `Preview automation timed out after ${timeoutMs}ms.`,
+            }),
+          ),
+        onSome: (value) => Effect.succeed(value as A),
+      });
     });
+    return yield* awaitResponse().pipe(Effect.ensuring(removePending));
   });
   return PreviewAutomationBroker.of({ connect, reportOwner, clearOwner, respond, invoke });
-});
+}).pipe(Effect.withSpan("PreviewAutomationBroker.make"));
-export const layer = Layer.effect(PreviewAutomationBroker, make());
+export const layer = Layer.effect(PreviewAutomationBroker, make);
 /** Exposed for tests. */
 export const __testing = {

apps/server/src/mcp/toolkits/preview/handlers.ts+20-8

 @@ -9,7 +9,7 @@ import type {
 import * as McpInvocationContext from "../../McpInvocationContext.ts";
 import * as PreviewAutomationBroker from "../../PreviewAutomationBroker.ts";
-import { PreviewToolkit } from "./tools.ts";
+import { PreviewSnapshotToolkit, PreviewStandardToolkit, PreviewToolkit } from "./tools.ts";
 const invoke = Effect.fn("PreviewToolkit.invoke")(function* <A>(
   operation: PreviewAutomationOperation,
 @@ -30,7 +30,7 @@ const invoke = Effect.fn("PreviewToolkit.invoke")(function* <A>(
   });
 });
-export const PreviewToolkitHandlersLive = PreviewToolkit.toLayer({
+const handlers = {
   preview_status: () => invoke<PreviewAutomationStatus>("status", {}),
   preview_open: (input) =>
     invoke<PreviewAutomationStatus>("open", {
 @@ -40,12 +40,24 @@ export const PreviewToolkitHandlersLive = PreviewToolkit.toLayer({
     }),
   preview_navigate: (input) => invoke<PreviewAutomationStatus>("navigate", input, input.timeoutMs),
   preview_snapshot: () => invoke<PreviewAutomationSnapshot>("snapshot", {}),
-  preview_click: (input) => invoke<void>("click", input, input.timeoutMs),
+  preview_click: (input) => invoke<void>("click", input, input.timeoutMs).pipe(Effect.as(null)),
-  preview_type: (input) => invoke<void>("type", input, input.timeoutMs),
+  preview_type: (input) => invoke<void>("type", input, input.timeoutMs).pipe(Effect.as(null)),
-  preview_press: (input) => invoke<void>("press", input),
+  preview_press: (input) => invoke<void>("press", input).pipe(Effect.as(null)),
-  preview_scroll: (input) => invoke<void>("scroll", input),
+  preview_scroll: (input) => invoke<void>("scroll", input).pipe(Effect.as(null)),
-  preview_evaluate: (input) => invoke<unknown>("evaluate", input),
+  preview_evaluate: (input) =>
-  preview_wait_for: (input) => invoke<void>("waitFor", input, input.timeoutMs),
+    invoke<unknown>("evaluate", input).pipe(Effect.map((result) => result ?? null)),
+  preview_wait_for: (input) =>
+    invoke<void>("waitFor", input, input.timeoutMs).pipe(Effect.as(null)),
   preview_recording_start: () => invoke<PreviewAutomationRecordingStatus>("recordingStart", {}),
   preview_recording_stop: () => invoke<PreviewAutomationRecordingArtifact>("recordingStop", {}),
+} satisfies Parameters<typeof PreviewToolkit.toLayer>[0];
+const { preview_snapshot, ...standardHandlers } = handlers;
+export const PreviewStandardToolkitHandlersLive = PreviewStandardToolkit.toLayer(standardHandlers);
+export const PreviewSnapshotToolkitHandlersLive = PreviewSnapshotToolkit.toLayer({
+  preview_snapshot,
 });
+export const PreviewToolkitHandlersLive = PreviewToolkit.toLayer(handlers);

apps/server/src/mcp/toolkits/preview/tools.ts+21

 @@ -84,6 +84,7 @@ export const PreviewClickTool = browserTool(
     description:
       "Click exactly one page target. Prefer locator with a Playwright selector such as role=button[name='Send']; selector accepts legacy CSS; x and y are viewport CSS pixels and must be supplied together. Call preview_snapshot first when the target is unknown.",
     parameters: PreviewAutomationClickInput,
+    success: Schema.Null,
     failure: PreviewAutomationError,
     dependencies,
   }).annotate(Tool.Title, "Click preview page"),
 @@ -94,6 +95,7 @@ export const PreviewTypeTool = browserTool(
     description:
       "Insert literal text into one input. Prefer locator with a Playwright role/text selector; selector accepts legacy CSS. If neither is supplied, types into the currently focused element. Set clear=true to replace existing text.",
     parameters: PreviewAutomationTypeInput,
+    success: Schema.Null,
     failure: PreviewAutomationError,
     dependencies,
   }).annotate(Tool.Title, "Type into preview page"),
 @@ -104,6 +106,7 @@ export const PreviewPressTool = browserTool(
     description:
       "Press one keyboard key in the active page, for example {key:'Enter'}, {key:'Escape'}, or {key:'a',modifiers:['Meta']}. This targets the page's current focus.",
     parameters: PreviewAutomationPressInput,
+    success: Schema.Null,
     failure: PreviewAutomationError,
     dependencies,
   }).annotate(Tool.Title, "Press key in preview page"),
 @@ -114,6 +117,7 @@ export const PreviewScrollTool = safeBrowserTool(
     description:
       "Scroll by CSS pixels. Positive deltaY scrolls down and positive deltaX scrolls right. Without locator/selector it scrolls the viewport; otherwise it scrolls that container. At least one delta is required.",
     parameters: PreviewAutomationScrollInput,
+    success: Schema.Null,
     failure: PreviewAutomationError,
     dependencies,
   }).annotate(Tool.Title, "Scroll preview page"),
 @@ -135,6 +139,7 @@ export const PreviewWaitForTool = readonlyBrowserTool(
     description:
       "Wait until all supplied conditions match: a Playwright locator, legacy CSS selector, visible-text substring, and/or URL substring. Provide at least one condition. Defaults to 15 seconds, maximum 60 seconds.",
     parameters: PreviewAutomationWaitForInput,
+    success: Schema.Null,
     failure: PreviewAutomationError,
     dependencies,
   }).annotate(Tool.Title, "Wait for preview page condition"),
 @@ -173,3 +178,19 @@ export const PreviewToolkit = Toolkit.make(
   PreviewRecordingStartTool,
   PreviewRecordingStopTool,
 );
+export const PreviewStandardToolkit = Toolkit.make(
+  PreviewStatusTool,
+  PreviewOpenTool,
+  PreviewNavigateTool,
+  PreviewClickTool,
+  PreviewTypeTool,
+  PreviewPressTool,
+  PreviewScrollTool,
+  PreviewEvaluateTool,
+  PreviewWaitForTool,
+  PreviewRecordingStartTool,
+  PreviewRecordingStopTool,
+);
+export const PreviewSnapshotToolkit = Toolkit.make(PreviewSnapshotTool);

apps/server/src/preview/Manager.ts+3-3

...	@@ -127,7 +127,7 @@ const buildIdleSnapshot = (input: {	...	@@ -127,7 +127,7 @@ const buildIdleSnapshot = (input: {
127	updatedAt: input.updatedAt,	127	updatedAt: input.updatedAt,
128	});	128	});
129		129
130	const make = Effect.fn("PreviewManager.make")(function* () {	130	const make = Effect.gen(function* PreviewManagerMake() {
131	const stateRef = yield* SynchronizedRef.make<ManagerState>(initialState);	131	const stateRef = yield* SynchronizedRef.make<ManagerState>(initialState);
132	// Unbounded PubSub is fine here — events are tiny and we don't want to	132	// Unbounded PubSub is fine here — events are tiny and we don't want to
133	// block publishers if a subscriber is slow. WS clients backpressure on	133	// block publishers if a subscriber is slow. WS clients backpressure on
...	@@ -357,6 +357,6 @@ const make = Effect.fn("PreviewManager.make")(function* () {	...	@@ -357,6 +357,6 @@ const make = Effect.fn("PreviewManager.make")(function* () {
357	events,	357	events,
358	subscribeEvents: PubSub.subscribe(eventsPubSub),	358	subscribeEvents: PubSub.subscribe(eventsPubSub),
359	} satisfies PreviewManagerShape;	359	} satisfies PreviewManagerShape;
360	});	360	}).pipe(Effect.withSpan("PreviewManager.make"));
361		361
362	export const layer = Layer.effect(PreviewManager, make());	362	export const layer = Layer.effect(PreviewManager, make);

apps/server/src/preview/PortScanner.test.ts+3-5

 @@ -249,20 +249,18 @@ effectIt.layer(TestPortDiscoveryLive)("PortDiscovery integration (TCP probe fall
   );
   it.effect(
-    "retain() drives an immediate broadcast to subscribers",
+    "retain drives an immediate broadcast to subscribers",
     Effect.fn("PortScannerTest.retainBroadcastsImmediately")(function* () {
       yield* windowsPlatform;
       const { port } = yield* commonDevServer;
       const received: number[] = [];
       const scanner = yield* PortScanner.PortDiscovery;
-      const unsubscribe = yield* scanner.subscribe((servers) =>
+      yield* scanner.subscribe((servers) =>
         Effect.sync(() => {
           for (const server of servers) received.push(server.port);
         }),
       );
-      const release = yield* scanner.retain();
+      yield* scanner.retain;
-      unsubscribe();
-      release();
       expect(received).toContain(port);
     }),
   );

apps/server/src/preview/PortScanner.ts+74-55

 @@ -8,13 +8,13 @@
  * Windows / lsof missing: checks a curated list of common dev ports through
  * the shared Net service.
  *
- * Polling is reference-counted via `retain()`. A single layer-scoped fiber
+ * Polling is reference-counted via scoped `retain`. A single layer-scoped fiber
  * polls forever, but each tick is a no-op when the retain count is zero.
  */
 import { ThreadId, type DiscoveredLocalServer } from "@t3tools/contracts";
 import * as Net from "@t3tools/shared/Net";
 import { LSOF_LOCAL_HOST_TOKENS } from "@t3tools/shared/preview";
-import { Cause, Context, Duration, Effect, Layer, Ref, Schedule } from "effect";
+import { Cause, Context, Duration, Effect, Layer, Ref, Schedule, Scope } from "effect";
 import { ProcessRunner } from "../processRunner.ts";
 @@ -22,8 +22,8 @@ export interface PortDiscoveryShape {
   readonly scan: () => Effect.Effect<ReadonlyArray<DiscoveredLocalServer>>;
   readonly subscribe: (
     listener: (servers: ReadonlyArray<DiscoveredLocalServer>) => Effect.Effect<void>,
-  ) => Effect.Effect<() => void>;
+  ) => Effect.Effect<void, never, Scope.Scope>;
-  readonly retain: () => Effect.Effect<() => void>;
+  readonly retain: Effect.Effect<void, never, Scope.Scope>;
   readonly registerTerminalProcesses: (input: {
     readonly threadId: string;
     readonly terminalId: string;
 @@ -51,6 +51,15 @@ type Listener = (servers: ReadonlyArray<DiscoveredLocalServer>) => Effect.Effect
 interface ScannerState {
   readonly lastSnapshot: ReadonlyArray<DiscoveredLocalServer>;
+  readonly listeners: ReadonlySet<Listener>;
+  readonly terminalProcesses: ReadonlyMap<
+    string,
+    {
+      readonly owner: TerminalProcessOwner;
+      readonly processIds: ReadonlySet<number>;
+    }
+  >;
+  readonly retainCount: number;
 }
 interface TerminalProcessOwner {
 @@ -170,24 +179,15 @@ const serversEqual = (
   return true;
 };
-const make = Effect.fn("PortDiscovery.make")(function* () {
+const make = Effect.gen(function* PortDiscoveryMake() {
   const net = yield* Net.NetService;
   const processRunner = yield* ProcessRunner;
   const stateRef = yield* Ref.make<ScannerState>({
     lastSnapshot: [],
+    listeners: new Set(),
+    terminalProcesses: new Map(),
+    retainCount: 0,
   });
-  const listeners = new Set<Listener>();
-  const terminalProcesses = new Map<
-    string,
-    {
-      readonly owner: TerminalProcessOwner;
-      readonly processIds: ReadonlySet<number>;
-    }
-  >();
-  // Plain integer because the release callback returned by `retain()` runs
-  // outside any Effect context (the WS subscriber's release path) and must
-  // be a synchronous side-effect-only function.
-  let retainCount = 0;
   const probeCommonPorts = Effect.fn("PortDiscovery.probeCommonPorts")(function* () {
     const results = yield* Effect.forEach(
 @@ -214,8 +214,9 @@ const make = Effect.fn("PortDiscovery.make")(function* () {
   });
   const scanOnce = Effect.fn("PortDiscovery.scan")(function* () {
+    const state = yield* Ref.get(stateRef);
     const terminalByProcessId = new Map<number, TerminalProcessOwner>();
-    for (const registration of terminalProcesses.values()) {
+    for (const registration of state.terminalProcesses.values()) {
       for (const processId of registration.processIds) {
         terminalByProcessId.set(processId, registration.owner);
       }
 @@ -254,17 +255,23 @@ const make = Effect.fn("PortDiscovery.make")(function* () {
     return yield* probeCommonPorts();
   });
-  const broadcast = (servers: ReadonlyArray<DiscoveredLocalServer>): Effect.Effect<void> =>
+  const broadcast = Effect.fn("PortDiscovery.broadcast")(function* (
-    Effect.forEach(Array.from(listeners), (listener) => listener(servers), { discard: true });
+    servers: ReadonlyArray<DiscoveredLocalServer>,
+  ) {
+    const listeners = (yield* Ref.get(stateRef)).listeners;
+    yield* Effect.forEach(listeners, (listener) => listener(servers), { discard: true });
+  });
   const pollTick = Effect.fn("PortDiscovery.pollTick")(
     function* () {
-      if (retainCount <= 0) return;
+      if ((yield* Ref.get(stateRef)).retainCount <= 0) return;
       const next = yield* scanOnce();
-      const state = yield* Ref.get(stateRef);
+      const changed = yield* Ref.modify(stateRef, (state) =>
-      if (serversEqual(state.lastSnapshot, next)) return;
+        serversEqual(state.lastSnapshot, next)
-      yield* Ref.update(stateRef, (s) => ({ ...s, lastSnapshot: next }));
+          ? [false, state]
-      yield* broadcast(next);
+          : [true, { ...state, lastSnapshot: next }],
+      );
+      if (changed) yield* broadcast(next);
     },
     Effect.catchCause((cause: Cause.Cause<never>) =>
       Effect.logWarning("preview port scan failed", Cause.pretty(cause)),
 @@ -275,58 +282,70 @@ const make = Effect.fn("PortDiscovery.make")(function* () {
   // currently retained, so the cost is one Ref.get every POLL_INTERVAL.
   yield* Effect.forkScoped(pollTick().pipe(Effect.repeat(Schedule.spaced(POLL_INTERVAL))));
-  const retain: PortDiscoveryShape["retain"] = Effect.fn("PortDiscovery.retain")(function* () {
+  const acquireRetention = Effect.fn("PortDiscovery.retain")(function* () {
-    const wasIdle = retainCount === 0;
+    const wasIdle = yield* Ref.modify(stateRef, (state) => [
-    retainCount += 1;
+      state.retainCount === 0,
+      { ...state, retainCount: state.retainCount + 1 },
+    ]);
     if (wasIdle) {
       // Run an immediate scan + broadcast so the new retainer doesn't have
       // to wait up to POLL_INTERVAL for the first emission.
       yield* pollTick();
     }
-    let released = false;
-    return () => {
-      if (released) return;
-      released = true;
-      retainCount = Math.max(0, retainCount - 1);
-    };
   });
+  const retain: PortDiscoveryShape["retain"] = Effect.acquireRelease(acquireRetention(), () =>
+    Ref.update(stateRef, (state) => ({
+      ...state,
+      retainCount: Math.max(0, state.retainCount - 1),
+    })),
+  );
   const subscribe: PortDiscoveryShape["subscribe"] = Effect.fn("PortDiscovery.subscribe")(
-    function* (listener) {
+    (listener) =>
-      return yield* Effect.sync(() => {
+      Effect.acquireRelease(
-        listeners.add(listener);
+        Ref.update(stateRef, (state) => ({
-        return () => {
+          ...state,
-          listeners.delete(listener);
+          listeners: new Set([...state.listeners, listener]),
-        };
+        })),
-      });
+        () =>
-    },
+          Ref.update(stateRef, (state) => {
+            const listeners = new Set(state.listeners);
+            listeners.delete(listener);
+            return { ...state, listeners };
+          }),
+      ),
   );
   const registerTerminalProcesses: PortDiscoveryShape["registerTerminalProcesses"] = Effect.fn(
     "PortDiscovery.registerTerminalProcesses",
   )(function* (input) {
-    yield* Effect.sync(() => {
+    const owner = {
-      const owner = {
+      threadId: ThreadId.make(input.threadId),
-        threadId: ThreadId.make(input.threadId),
+      terminalId: input.terminalId,
-        terminalId: input.terminalId,
+    };
-      };
+    const processIds = new Set(
-      const processIds = new Set(
+      input.processIds.filter((processId) => Number.isInteger(processId) && processId > 0),
-        input.processIds.filter((processId) => Number.isInteger(processId) && processId > 0),
+    );
-      );
+    yield* Ref.update(stateRef, (state) => {
+      const terminalProcesses = new Map(state.terminalProcesses);
       const key = terminalOwnerKey(owner);
       if (processIds.size === 0) {
         terminalProcesses.delete(key);
-        return;
+      } else {
+        terminalProcesses.set(key, { owner, processIds });
       }
-      terminalProcesses.set(key, { owner, processIds });
+      return { ...state, terminalProcesses };
     });
   });
   const unregisterTerminal: PortDiscoveryShape["unregisterTerminal"] = Effect.fn(
     "PortDiscovery.unregisterTerminal",
   )(function* (input) {
-    yield* Effect.sync(() => {
+    yield* Ref.update(stateRef, (state) => {
+      const terminalProcesses = new Map(state.terminalProcesses);
       terminalProcesses.delete(terminalOwnerKey(input));
+      return { ...state, terminalProcesses };
     });
   });
 @@ -337,9 +356,9 @@ const make = Effect.fn("PortDiscovery.make")(function* () {
     registerTerminalProcesses,
     unregisterTerminal,
   } satisfies PortDiscoveryShape;
-});
+}).pipe(Effect.withSpan("PortDiscovery.make"));
-export const layer = Layer.effect(PortDiscovery, make());
+export const layer = Layer.effect(PortDiscovery, make);
 /** Exposed for tests. */
 export const __testing = {

apps/server/src/server.test.ts+2-2

...	@@ -683,8 +683,8 @@ const buildAppUnderTest = (options?: {	...	@@ -683,8 +683,8 @@ const buildAppUnderTest = (options?: {
683	}),	683	}),
684	Layer.mock(PortScanner.PortDiscovery)({	684	Layer.mock(PortScanner.PortDiscovery)({
685	scan: () => Effect.succeed([]),	685	scan: () => Effect.succeed([]),
686	subscribe: () => Effect.succeed(() => {}),	686	subscribe: () => Effect.void,
687	retain: () => Effect.succeed(() => {}),	687	retain: Effect.void,
688	registerTerminalProcesses: () => Effect.void,	688	registerTerminalProcesses: () => Effect.void,
689	unregisterTerminal: () => Effect.void,	689	unregisterTerminal: () => Effect.void,
690	}),	690	}),

apps/server/src/ws.ts+14-22

...	@@ -1425,29 +1425,21 @@ const makeWsRpcLayer = (currentSession: AuthenticatedSession) =>	...	@@ -1425,29 +1425,21 @@ const makeWsRpcLayer = (currentSession: AuthenticatedSession) =>
1425	observeRpcStream(	1425	observeRpcStream(
1426	WS_METHODS.subscribeDiscoveredLocalServers,	1426	WS_METHODS.subscribeDiscoveredLocalServers,
1427	Stream.callback<DiscoveredLocalServerList>((queue) =>	1427	Stream.callback<DiscoveredLocalServerList>((queue) =>
1428	Effect.acquireRelease(	1428	Effect.gen(function* () {
1429	Effect.gen(function* () {	1429	yield* portDiscovery.retain;
1430	const release = yield* portDiscovery.retain();	1430	const initial = yield* portDiscovery.scan();
1431	const initial = yield* portDiscovery.scan();	1431	const initialScannedAt = DateTime.formatIso(yield* DateTime.now);
1432	const initialScannedAt = DateTime.formatIso(yield* DateTime.now);	1432	yield* Queue.offer(queue, {
1433	yield* Queue.offer(queue, {	1433	servers: initial,
1434	servers: initial,	1434	scannedAt: initialScannedAt,
1435	scannedAt: initialScannedAt,	1435	});
1436	});	1436	yield* portDiscovery.subscribe((servers) =>
1437	const unsubscribe = yield* portDiscovery.subscribe((servers) =>	1437	Effect.gen(function* () {
1438	Effect.gen(function* () {	1438	const scannedAt = DateTime.formatIso(yield* DateTime.now);
1439	const scannedAt = DateTime.formatIso(yield* DateTime.now);	1439	yield* Queue.offer(queue, { servers, scannedAt });
1440	yield* Queue.offer(queue, { servers, scannedAt });
1441	}),
1442	);
1443	return { unsubscribe, release };
1444	}),
1445	({ unsubscribe, release }) =>
1446	Effect.sync(() => {
1447	unsubscribe();
1448	release();
1449	}),	1440	}),
1450	),	1441	);
		1442	}),
1451	),	1443	),
1452	{ "rpc.aggregate": "preview" },	1444	{ "rpc.aggregate": "preview" },
1453	),	1445	),

...	@@ -23,7 +23,7 @@ const scope = {	...	@@ -23,7 +23,7 @@ const scope = {
23	it.effect("routes a request to the focused owner and correlates its response", () =>	23	it.effect("routes a request to the focused owner and correlates its response", () =>
24	Effect.scoped(	24	Effect.scoped(
25	Effect.gen(function* () {	25	Effect.gen(function* () {
26	const broker = yield* PreviewAutomationBroker.__testing.make();	26	const broker = yield* PreviewAutomationBroker.__testing.make;
27	const requests = yield* broker.connect("client-1");	27	const requests = yield* broker.connect("client-1");
28	yield* Stream.runForEach(requests, (request) =>	28	yield* Stream.runForEach(requests, (request) =>
29	broker.respond({	29	broker.respond({
...	@@ -56,7 +56,7 @@ it.effect("routes a request to the focused owner and correlates its response", (	...	@@ -56,7 +56,7 @@ it.effect("routes a request to the focused owner and correlates its response", (
56		56
57	it.effect("rejects calls when no focused owner exists", () =>	57	it.effect("rejects calls when no focused owner exists", () =>
58	Effect.gen(function* () {	58	Effect.gen(function* () {
59	const broker = yield* PreviewAutomationBroker.__testing.make();	59	const broker = yield* PreviewAutomationBroker.__testing.make;
60	const error = yield* broker	60	const error = yield* broker
61	.invoke<void>({ scope, operation: "status", input: {} })	61	.invoke<void>({ scope, operation: "status", input: {} })
62	.pipe(Effect.flip);	62	.pipe(Effect.flip);
...	@@ -67,7 +67,7 @@ it.effect("rejects calls when no focused owner exists", () =>	...	@@ -67,7 +67,7 @@ it.effect("rejects calls when no focused owner exists", () =>
67	it.effect("routes interactive commands to a hidden durable browser host", () =>	67	it.effect("routes interactive commands to a hidden durable browser host", () =>
68	Effect.scoped(	68	Effect.scoped(
69	Effect.gen(function* () {	69	Effect.gen(function* () {
70	const broker = yield* PreviewAutomationBroker.__testing.make();	70	const broker = yield* PreviewAutomationBroker.__testing.make;
71	const requests = yield* broker.connect("client-hidden");	71	const requests = yield* broker.connect("client-hidden");
72	yield* Stream.runForEach(requests, (request) =>	72	yield* Stream.runForEach(requests, (request) =>
73	broker.respond({ requestId: request.requestId, ok: true }),	73	broker.respond({ requestId: request.requestId, ok: true }),