fix(server): queued preview actions no longer start after their deadline, except recording stop

apps/server/src/mcp/McpHttpServer.test.ts

@@ -244,10 +244,17 @@ it.effect("tells the agent how to fall back when no desktop app can run the snap
 );
 
 it.effect.each([
-  { mode: "default", input: {}, images: false },
-  { mode: "explicit image", input: { includeImage: true }, images: true },
-  { mode: "text only", input: { includeImage: false }, images: false },
-])("returns fresh $mode snapshots on repeated MCP calls", ({ input, images }) =>
+  { mode: "default", input: {}, images: false, legacyHost: false },
+  { mode: "default from an older host", input: {}, images: false, legacyHost: true },
+  { mode: "explicit image", input: { includeImage: true }, images: true, legacyHost: false },
+  { mode: "text only", input: { includeImage: false }, images: false, legacyHost: false },
+  {
+    mode: "text only from an older host",
+    input: { includeImage: false },
+    images: false,
+    legacyHost: true,
+  },
+])("returns fresh $mode snapshots on repeated MCP calls", ({ input, images, legacyHost }) =>
   Effect.scoped(
     Effect.gen(function* () {
       const server = yield* McpServer.McpServer;
@@ -287,7 +294,8 @@ it.effect.each([
           tabId: alternateTabId,
           threadId,
         });
-        expect(event.request.input).toEqual({});
+        const capture = requests <= 6 && images;
+        expect(event.request.input).toEqual(capture ? {} : { includeImage: false });
         return broker.respond({
           clientId: "mcp-image-option-client",
           connectionId: event.connectionId,
@@ -296,7 +304,8 @@ it.effect.each([
           result: {
             ...page,
             title: `Snapshot ${requests}`,
-            screenshot: { ...screenshot, data: png },
+            // Older hosts ignore the capture preference and still return a full PNG.
+            ...(capture || legacyHost ? { screenshot: { ...screenshot, data: png } } : {}),
           },
         });
       }).pipe(Effect.forkScoped);
@@ -312,7 +321,11 @@ it.effect.each([
             Effect.provideService(McpInvocationContext.McpInvocationContext, invocation),
             Effect.provideService(McpSchema.McpServerClient, client),
           );
-        const metadata = { ...page, title: `Snapshot ${call}`, screenshot };
+        const metadata = {
+          ...page,
+          title: `Snapshot ${call}`,
+          ...(images || legacyHost ? { screenshot } : {}),
+        };
         const { accessibilityTree: _tree, ...boundedMetadata } = metadata;
         expect(snapshot.isError).toBe(false);
         expect(snapshot.structuredContent).toEqual({
@@ -352,7 +365,10 @@ it.effect.each([
           Effect.provideService(McpSchema.McpServerClient, client),
         );
       expect(nextDefault.content.map((content) => content.type)).toEqual(["text", "text", "text"]);
-      expect(nextDefault.structuredContent).toMatchObject({ title: "Snapshot 7", screenshot });
+      expect(nextDefault.structuredContent).toMatchObject({ title: "Snapshot 7" });
+      if (legacyHost)
+        expect(nextDefault.structuredContent).toHaveProperty("screenshot", screenshot);
+      else expect(nextDefault.structuredContent).not.toHaveProperty("screenshot");
       expect(nextDefault.structuredContent).not.toHaveProperty("accessibilityTree");
       expect(requests).toBe(7);
     }),
@@ -439,6 +455,20 @@ it.effect("saves the snapshot PNG on request and reports its path", () =>
       const [only, ...others] = pathOnly.content;
       expect(others).toEqual([]);
       expect(only?.type === "text" ? decodeJsonText(only.text) : null).toEqual(saved);
+      const explicitPathOnly = yield* callSnapshot({ save: true, includeImage: false });
+      expect(explicitPathOnly.structuredContent).toEqual({
+        url: snapshotResult.url,
+        screenshotPath: expect.any(String),
+      });
+      expect(explicitPathOnly.content.map((content) => content.type)).toEqual(["text"]);
+      const explicitSaved = explicitPathOnly.structuredContent as {
+        readonly screenshotPath: string;
+      };
+      expect(Buffer.from(yield* fileSystem.readFile(explicitSaved.screenshotPath)).toString()).toBe(
+        "png",
+      );
+      // Saves always capture; the unsaved default call is text-only.
+      expect(inputs).toEqual([{}, { includeImage: false }, {}, {}]);
     }),
   ).pipe(Effect.provide(layerTest)),
 );
@@ -850,6 +880,9 @@ it.effect("registers annotated tools and preserves authenticated request context
       expect(snapshotTool?.tool.annotations?.readOnlyHint).toBe(false);
       expect(snapshotTool?.tool.annotations?.idempotentHint).toBe(false);
       expect(snapshotTool?.tool.annotations?.openWorldHint).toBe(true);
+      // This formatter advertises no required PNG output schema to MCP clients.
+      // PreviewAutomationSnapshot validates the host result inside this server.
+      expect(snapshotTool?.tool.outputSchema).toBeUndefined();
 
       const clickTool = server.tools.find(({ tool }) => tool.name === "preview_click");
       expect(clickTool?.tool.annotations?.readOnlyHint).toBe(false);

apps/server/src/mcp/McpHttpServer.ts

@@ -492,17 +492,22 @@ const registerPreviewSnapshot = Effect.fn("McpHttpServer.registerPreviewSnapshot
             Effect.gen(function* () {
               const snapshot = encodedResult as SnapshotMetadata & {
                 readonly url: string;
-                readonly screenshot: {
+                readonly screenshot?: {
                   readonly mimeType: "image/png";
                   readonly data: string;
                   readonly width: number;
                   readonly height: number;
                 };
               };
               const { screenshot, ...page } = snapshot;
-              const png = new Uint8Array(Buffer.from(screenshot.data, "base64"));
+              const png =
+                screenshot === undefined
+                  ? undefined
+                  : new Uint8Array(Buffer.from(screenshot.data, "base64"));
               const screenshotPath =
-                payload?.save === true ? yield* saveScreenshot(snapshot.url, png) : undefined;
+                payload?.save === true && png !== undefined
+                  ? yield* saveScreenshot(snapshot.url, png)
+                  : undefined;
               // Images stay out of tool history unless asked for: providers replay them on every
               // later request, and some reject inline images outright.
               const includeImage = payload?.includeImage === true;
@@ -520,11 +525,15 @@ const registerPreviewSnapshot = Effect.fn("McpHttpServer.registerPreviewSnapshot
               }
               const metadata = {
                 ...page,
-                screenshot: {
-                  mimeType: screenshot.mimeType,
-                  width: screenshot.width,
-                  height: screenshot.height,
-                },
+                ...(screenshot === undefined
+                  ? {}
+                  : {
+                      screenshot: {
+                        mimeType: screenshot.mimeType,
+                        width: screenshot.width,
+                        height: screenshot.height,
+                      },
+                    }),
                 ...(screenshotPath === undefined ? {} : { screenshotPath }),
               };
               const bounded = boundSnapshotMetadata(metadata);
@@ -551,7 +560,7 @@ const registerPreviewSnapshot = Effect.fn("McpHttpServer.registerPreviewSnapshot
                           text: `Snapshot text was bounded. Omitted: ${bounded.omitted.join("; ")}.`,
                         },
                       ]),
-                  ...(includeImage
+                  ...(includeImage && screenshot !== undefined && png !== undefined
                     ? [{ type: "image" as const, data: png, mimeType: screenshot.mimeType }]
                     : []),
                 ],