fix: harden runtime boundary follow-ups

Author: thymikee

src/__tests__/runtime-diff-screenshot.test.ts

@@ -22,13 +22,15 @@ test('runtime diff screenshot captures live current image and cleans temporary c
   const baseline = path.join(dir, 'baseline.png');
   const diffOut = path.join(dir, 'diff.png');
   let capturedCurrentPath: string | undefined;
+  let capturedOptions: BackendScreenshotOptions | undefined;
 
   fs.writeFileSync(baseline, solidPngBuffer(10, 10, { r: 0, g: 0, b: 0 }));
 
   try {
     const device = createAgentDevice({
-      backend: createScreenshotBackend((outPath) => {
+      backend: createScreenshotBackend((outPath, options) => {
         capturedCurrentPath = outPath;
+        capturedOptions = options;
         fs.writeFileSync(outPath, solidPngBuffer(10, 10, { r: 255, g: 255, b: 255 }));
         return { path: outPath };
       }),
@@ -42,6 +44,7 @@ test('runtime diff screenshot captures live current image and cleans temporary c
       current: { kind: 'live' },
       out: { kind: 'path', path: diffOut },
       threshold: 0,
+      surface: 'menubar',
     });
 
     assert.equal(result.match, false);
@@ -50,6 +53,7 @@ test('runtime diff screenshot captures live current image and cleans temporary c
     assert.equal(fs.existsSync(diffOut), true);
     assert.equal(typeof capturedCurrentPath, 'string');
     assert.equal(fs.existsSync(capturedCurrentPath!), false);
+    assert.equal(capturedOptions?.surface, 'menubar');
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }

src/__tests__/runtime-interactions.test.ts

@@ -102,6 +102,14 @@ test('runtime interactions reject unsupported macOS desktop and menubar surfaces
     () => desktop.interactions.click({ kind: 'point', x: 1, y: 2 }, { session: 'default' }),
     /click is not supported on macOS desktop sessions yet/,
   );
+  await assert.rejects(
+    () =>
+      desktop.interactions.click(
+        { kind: 'point', x: 1, y: 2 },
+        { session: 'default', metadata: { surface: 'app' } },
+      ),
+    /click is not supported on macOS desktop sessions yet/,
+  );
 
   const menubar = createInteractionDevice(fillableSnapshot(), {
     platform: 'macos',

src/__tests__/runtime-snapshot.test.ts

@@ -116,6 +116,47 @@ test('runtime snapshot emits filtered Android guidance from backend analysis', a
   ]);
 });
 
+test('runtime snapshot stale-drop warning uses the runtime clock', async () => {
+  const session = {
+    name: 'default',
+    snapshot: makeSnapshotState(
+      Array.from({ length: 20 }, (_, index) => ({
+        index,
+        depth: 0,
+        type: 'Text',
+        label: `Before ${index}`,
+      })),
+      { backend: 'android' },
+    ),
+  };
+  session.snapshot.createdAt = 1_000;
+  const device = createAgentDevice({
+    backend: createSnapshotBackend(() => ({
+      snapshot: makeSnapshotState([{ index: 0, depth: 0, type: 'Text', label: 'After' }], {
+        backend: 'android',
+      }),
+    })),
+    artifacts: createLocalArtifactAdapter(),
+    sessions: {
+      get: () => session,
+      set: (record) => {
+        session.snapshot = record.snapshot!;
+      },
+    },
+    policy: localCommandPolicy(),
+    clock: {
+      now: () => 1_500,
+      sleep: async () => {},
+    },
+  });
+
+  const result = await device.capture.snapshot({ session: 'default' });
+
+  assert.deepEqual(result.warnings, [
+    'Recent snapshots dropped sharply in node count, which suggests stale or mid-transition UI. Use screenshot as visual truth, wait briefly, then re-snapshot once.',
+  ]);
+});
+
 function createSnapshotBackend(
   captureSnapshot: () => BackendSnapshotResult | Promise<BackendSnapshotResult>,
 ): AgentDeviceBackend {

src/cli/commands/screenshot.ts

@@ -95,6 +95,7 @@ function createClientScreenshotBackend(
         session: context.session,
         overlayRefs: options?.overlayRefs,
         fullscreen: options?.fullscreen,
+        surface: options?.surface,
       });
       return {
         path: result.path,

src/client-types.ts

@@ -311,6 +311,7 @@ export type CaptureScreenshotOptions = AgentDeviceRequestOverrides & {
   path?: string;
   overlayRefs?: boolean;
   fullscreen?: boolean;
+  surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
 };
 
 export type CaptureScreenshotResult = {

src/commands/capture-diff-screenshot.ts

@@ -26,6 +26,7 @@ export type DiffScreenshotCommandOptions = CommandContext & {
   currentOverlayOut?: FileOutputRef;
   threshold?: number;
   overlayRefs?: boolean;
+  surface?: BackendScreenshotOptions['surface'];
 };
 
 export type DiffScreenshotCommandResult = ScreenshotDiffResult & {
@@ -119,14 +120,14 @@ function normalizeThreshold(threshold: unknown): number {
 
 async function captureLiveCurrentScreenshot(
   runtime: AgentDeviceRuntime,
-  options: CommandContext,
+  options: DiffScreenshotCommandOptions,
 ): Promise<ResolvedInputFile> {
   const temp = await createCommandTempFile(runtime, {
     prefix: 'agent-device-diff-current',
     ext: '.png',
   });
   try {
-    await captureScreenshot(runtime, options, temp.path);
+    await captureScreenshot(runtime, options, temp.path, screenshotSurfaceOptions(options));
   } catch (error) {
     await temp.cleanup();
     throw error;
@@ -156,6 +157,7 @@ async function maybeAttachCurrentOverlay(
   try {
     const overlayResult = await captureScreenshot(runtime, options, overlayOutput.path, {
       overlayRefs: true,
+      ...screenshotSurfaceOptions(options),
     });
     const overlayArtifact = await overlayOutput.publish();
     if (overlayArtifact) artifacts.push(overlayArtifact);
@@ -201,6 +203,12 @@ async function captureScreenshot(
   );
 }
 
+function screenshotSurfaceOptions(
+  options: Pick<DiffScreenshotCommandOptions, 'surface'>,
+): BackendScreenshotOptions {
+  return options.surface ? { surface: options.surface } : {};
+}
+
 function resolveCurrentOverlayOutputRef(
   options: DiffScreenshotCommandOptions,
   diffOutputPath: string | undefined,

src/commands/capture-snapshot.ts

@@ -132,6 +132,7 @@ async function captureRuntimeSnapshot(
     },
   );
   const snapshot = normalizeBackendSnapshot(result, runtime);
+  const warningTime = now(runtime);
   return {
     snapshot,
     result,
@@ -141,6 +142,7 @@ async function captureRuntimeSnapshot(
       snapshot,
       options,
       session,
+      now: warningTime,
     }),
   };
 }
@@ -154,7 +156,7 @@ function normalizeBackendSnapshot(
     nodes: result.nodes ?? [],
     truncated: result.truncated,
     backend: result.backend as SnapshotState['backend'],
-    createdAt: runtime.clock?.now() ?? Date.now(),
+    createdAt: now(runtime),
   };
 }
 
@@ -189,6 +191,7 @@ function buildSnapshotWarnings(params: {
   snapshot: SnapshotState;
   options: SnapshotCommandOptions;
   session: CommandSessionRecord | undefined;
+  now: number;
 }): string[] {
   const warnings = [...(params.result.warnings ?? [])];
   const interactiveOnly = params.options.interactiveOnly === true;
@@ -219,7 +222,7 @@ function buildSnapshotWarnings(params: {
   if (
     !params.result.freshness &&
     previousSnapshot &&
-    Date.now() - previousSnapshot.createdAt <= 2_000 &&
+    params.now - previousSnapshot.createdAt <= 2_000 &&
     isLikelyStaleSnapshotDrop(previousSnapshot.nodes.length, params.snapshot.nodes.length)
   ) {
     warnings.push(
@@ -248,6 +251,10 @@ function isLikelyStaleSnapshotDrop(previousCount: number, currentCount: number):
   return currentCount <= Math.floor(previousCount * 0.2);
 }
 
+function now(runtime: AgentDeviceRuntime): number {
+  return runtime.clock?.now() ?? Date.now();
+}
+
 function uniqueStrings(values: string[]): string[] {
   return Array.from(new Set(values));
 }

src/commands/interactions.ts

@@ -279,6 +279,7 @@ async function assertSupportedInteractionSurface(
   if (runtime.backend.platform !== 'macos') return;
   const surface = await resolveInteractionSurface(runtime, options);
   if (surface !== 'desktop' && surface !== 'menubar') return;
+  // Menu bar button activation is supported by the existing daemon path; text entry is not.
   if (surface === 'menubar' && (action === 'click' || action === 'press')) return;
   throw new AppError(
     'UNSUPPORTED_OPERATION',
@@ -290,8 +291,6 @@ async function resolveInteractionSurface(
   runtime: AgentDeviceRuntime,
   options: CommandContext,
 ): Promise<unknown> {
-  const metadataSurface = options.metadata?.surface;
-  if (metadataSurface) return metadataSurface;
   const session = await runtime.sessions.get(options.session ?? 'default');
   return session?.metadata?.surface;
 }