feat: bridge web provider to agent-browser

Author: thymikee

src/core/dispatch.ts

@@ -100,7 +100,12 @@ async function dispatchKnownCommand(
       return await handleOpenCommand(device, interactor, positionals, context);
     case 'close': {
       const app = positionals[0];
-      if (!app) return { closed: 'session', ...successText('Closed session') };
+      if (!app) {
+        if (device.platform === 'web') {
+          await interactor.close('');
+        }
+        return { closed: 'session', ...successText('Closed session') };
+      }
       await interactor.close(app);
       return { app, ...successText(`Closed: ${app}`) };
     }

src/daemon/handlers/__tests__/session-close-shutdown.test.ts

@@ -47,11 +47,14 @@ import { handleSessionCommands } from '../session.ts';
 import { teardownSessionResources } from '../session-close.ts';
 import { shutdownSimulator } from '../../../platforms/ios/simulator.ts';
 import { runCmd } from '../../../utils/exec.ts';
+import { dispatchCommand } from '../../../core/dispatch.ts';
 import { cleanupAppleXctracePerfCapture } from '../../../platforms/ios/perf-xctrace.ts';
 import { cleanupAndroidNativePerfSession } from '../../../platforms/android/perf.ts';
+import { WEB_DESKTOP_DEVICE } from '../../../__tests__/test-utils/index.ts';
 
 const mockShutdownSimulator = vi.mocked(shutdownSimulator);
 const mockRunCmd = vi.mocked(runCmd);
+const mockDispatchCommand = vi.mocked(dispatchCommand);
 const mockCleanupAppleXctracePerfCapture = vi.mocked(cleanupAppleXctracePerfCapture);
 const mockCleanupAndroidNativePerfSession = vi.mocked(cleanupAndroidNativePerfSession);
 
@@ -345,6 +348,36 @@ test('close stops active Android native perf capture before deleting session', a
   expect(sessionStore.get(sessionName)).toBeUndefined();
 });
 
+test('close dispatches web session cleanup without a positional target', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'web-close-session';
+  sessionStore.set(sessionName, makeSession(sessionName, WEB_DESKTOP_DEVICE));
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'close',
+      positionals: [],
+      flags: {},
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  expect(response?.ok).toBe(true);
+  expect(mockDispatchCommand).toHaveBeenCalledWith(
+    WEB_DESKTOP_DEVICE,
+    'close',
+    [],
+    undefined,
+    expect.objectContaining({ logPath: expect.stringContaining('daemon.log') }),
+  );
+  expect(sessionStore.get(sessionName)).toBeUndefined();
+});
+
 test('daemon session teardown stops active Android native perf capture', async () => {
   const sessionName = 'android-active-native-perf-teardown-session';
   const activeCapture = {

src/daemon/handlers/session-close.ts

@@ -111,11 +111,13 @@ export async function handleCloseCommand(params: {
   }
   await stopSessionApplePerfCapture(session);
   await stopSessionAndroidNativePerfCapture(session);
-  if (req.positionals && req.positionals.length > 0) {
+  const shouldDispatchClose =
+    (req.positionals && req.positionals.length > 0) || session.device.platform === 'web';
+  if (shouldDispatchClose) {
     if (shouldStopAppleRunnerBeforeTargetedClose(session)) {
       await stopAppleRunnerForClose(session);
     }
-    await dispatchCommand(session.device, 'close', req.positionals, req.flags?.out, {
+    await dispatchCommand(session.device, 'close', req.positionals ?? [], req.flags?.out, {
       ...contextFromFlags(logPath, req.flags, session.appBundleId, session.trace?.outPath),
     });
     await settleIosSimulator(session.device, IOS_SIMULATOR_POST_CLOSE_SETTLE_MS);

src/daemon/request-router.ts

@@ -14,6 +14,7 @@ import {
   type LinuxToolProviderResolver,
   type RequestPlatformProviderScope,
   type RecordingProviderResolver,
+  type WebProviderResolver,
   withRequestPlatformProviderScope,
 } from './request-platform-providers.ts';
 import {
@@ -32,6 +33,7 @@ import {
   type RequestExecutionScope,
 } from './request-execution-scope.ts';
 import { canRunReplayScopedAction } from './daemon-command-registry.ts';
+import { createAgentBrowserWebProvider } from '../platforms/web/agent-browser-provider.ts';
 
 // ---------------------------------------------------------------------------
 // Request handler API
@@ -46,6 +48,7 @@ export type RequestRouterDeps = {
   appleRunnerProvider?: AppleRunnerProviderResolver;
   appleToolProvider?: AppleToolProviderResolver;
   linuxToolProvider?: LinuxToolProviderResolver;
+  webProvider?: WebProviderResolver;
   appLogProvider?: AppLogProviderResolver;
   recordingProvider?: RecordingProviderResolver;
   deviceInventoryProvider?: DeviceInventoryProvider;
@@ -64,6 +67,7 @@ export function createRequestHandler(deps: RequestRouterDeps): DaemonInvokeFn {
     appleRunnerProvider,
     appleToolProvider,
     linuxToolProvider,
+    webProvider,
     appLogProvider,
     recordingProvider,
     deviceInventoryProvider,
@@ -132,6 +136,9 @@ export function createRequestHandler(deps: RequestRouterDeps): DaemonInvokeFn {
                 appleRunnerProvider,
                 appleToolProvider,
                 linuxToolProvider,
+                webProvider:
+                  webProvider ??
+                  (shouldUseDefaultWebProvider(lockedScope) ? createDefaultWebProvider : undefined),
                 appLogProvider,
                 recordingProvider,
               },
@@ -195,6 +202,13 @@ export function createRequestHandler(deps: RequestRouterDeps): DaemonInvokeFn {
   return handleRequest;
 }
 
+const createDefaultWebProvider: WebProviderResolver = ({ req, session }) =>
+  createAgentBrowserWebProvider({ session: session?.name ?? req.session });
+
+function shouldUseDefaultWebProvider(scope: LockedRequestScope): boolean {
+  return scope.existingSession?.device.platform === 'web' || scope.req.flags?.platform === 'web';
+}
+
 function unauthorizedResponse(): DaemonResponse {
   return {
     ok: false,

src/platforms/web/agent-browser-provider.test.ts

@@ -0,0 +1,215 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { createAgentBrowserWebProvider } from './agent-browser-provider.ts';
+import { withCommandExecutorOverride, type ExecResult } from '../../utils/exec.ts';
+import { AppError } from '../../utils/errors.ts';
+
+type AgentBrowserCall = {
+  cmd: string;
+  args: string[];
+};
+
+test('agent-browser provider maps supported operations to session-scoped JSON commands', async () => {
+  const calls: AgentBrowserCall[] = [];
+  const provider = createAgentBrowserWebProvider({ session: 'web-session' });
+
+  await withCommandExecutorOverride(recordingExecutor(calls), async () => {
+    await provider.open('https://example.test');
+    await provider.screenshot('/tmp/page.png', { fullscreen: true });
+    await provider.click(10.4, 20.6);
+    await provider.fill(11, 22, 'Ada');
+    await provider.typeText('hello');
+    await provider.scroll('down', { pixels: 400 });
+    await provider.close();
+  });
+
+  assert.deepEqual(
+    calls.map((call) => call.args),
+    [
+      ['open', 'https://example.test', '--json', '--session', 'web-session'],
+      ['screenshot', '--full', '/tmp/page.png', '--json', '--session', 'web-session'],
+      ['mouse', 'move', '10', '21', '--json', '--session', 'web-session'],
+      ['mouse', 'down', '--json', '--session', 'web-session'],
+      ['mouse', 'up', '--json', '--session', 'web-session'],
+      ['mouse', 'move', '11', '22', '--json', '--session', 'web-session'],
+      ['mouse', 'down', '--json', '--session', 'web-session'],
+      ['mouse', 'up', '--json', '--session', 'web-session'],
+      ['press', 'Control+a', '--json', '--session', 'web-session'],
+      ['keyboard', 'type', 'Ada', '--json', '--session', 'web-session'],
+      ['keyboard', 'type', 'hello', '--json', '--session', 'web-session'],
+      ['scroll', 'down', '400', '--json', '--session', 'web-session'],
+      ['close', '--json', '--session', 'web-session'],
+    ],
+  );
+});
+
+test('agent-browser provider normalizes snapshot refs, labels, values, parents, and rects', async () => {
+  const calls: AgentBrowserCall[] = [];
+  const provider = createAgentBrowserWebProvider({ session: 'web-session' });
+
+  const snapshot = await withCommandExecutorOverride(
+    async (cmd, args) => {
+      calls.push({ cmd, args });
+      if (args[0] === 'snapshot') {
+        return jsonResult({
+          success: true,
+          data: {
+            refs: {
+              e1: { role: 'heading', name: 'Welcome' },
+              e2: { role: 'textbox', value: 'Ada' },
+              e3: { role: 'button', name: 'Save' },
+              e4: { role: 'link', name: 'Docs' },
+            },
+            snapshot: [
+              'heading "Welcome" [ref=e1]',
+              '  textbox "Name" value="Ada" [ref=e2]',
+              '  button "Save" [ref=e3]',
+              '  link "Docs" [ref=e4]',
+            ].join('\n'),
+            truncated: false,
+          },
+        });
+      }
+      if (args.slice(0, 3).join(' ') === 'get box @e3') {
+        return jsonResult({ success: false, error: 'No box for element' });
+      }
+      if (args[0] === 'get' && args[1] === 'box') {
+        const ref = args[2];
+        const offset = ref === '@e1' ? 0 : ref === '@e2' ? 10 : 30;
+        return jsonResult({
+          success: true,
+          data: { x: offset + 1, y: offset + 2, width: 100, height: 20 },
+        });
+      }
+      return jsonResult({ success: true, data: {} });
+    },
+    async () => await provider.snapshot({ interactiveOnly: true, depth: 4, scope: '#main' }),
+  );
+
+  assert.deepEqual(calls[0]?.args, [
+    'snapshot',
+    '--interactive',
+    '--compact',
+    '--depth',
+    '4',
+    '--selector',
+    '#main',
+    '--json',
+    '--session',
+    'web-session',
+  ]);
+  assert.deepEqual(snapshot.nodes, [
+    {
+      index: 0,
+      role: 'heading',
+      label: 'Welcome',
+      value: undefined,
+      depth: 0,
+      enabled: undefined,
+      focused: undefined,
+      rect: { x: 1, y: 2, width: 100, height: 20 },
+    },
+    {
+      index: 1,
+      role: 'textbox',
+      label: 'Name',
+      value: 'Ada',
+      depth: 1,
+      enabled: undefined,
+      focused: undefined,
+      parentIndex: 0,
+      rect: { x: 11, y: 12, width: 100, height: 20 },
+    },
+    {
+      index: 2,
+      role: 'button',
+      label: 'Save',
+      value: undefined,
+      depth: 1,
+      enabled: undefined,
+      focused: undefined,
+      parentIndex: 0,
+    },
+    {
+      index: 3,
+      role: 'link',
+      label: 'Docs',
+      value: undefined,
+      depth: 1,
+      enabled: undefined,
+      focused: undefined,
+      parentIndex: 0,
+      rect: { x: 31, y: 32, width: 100, height: 20 },
+    },
+  ]);
+});
+
+test('agent-browser provider surfaces stale ref failures during snapshot geometry lookup', async () => {
+  const provider = createAgentBrowserWebProvider({ session: 'web-session' });
+
+  await assert.rejects(
+    () =>
+      withCommandExecutorOverride(
+        async (_cmd, args) => {
+          if (args[0] === 'snapshot') {
+            return jsonResult({
+              success: true,
+              data: {
+                refs: { e1: { role: 'button', name: 'Save' } },
+                snapshot: 'button "Save" [ref=e1]',
+              },
+            });
+          }
+          return jsonResult({ success: false, error: 'Stale ref @e1' });
+        },
+        async () => await provider.snapshot(),
+      ),
+    (error: unknown) =>
+      error instanceof AppError &&
+      error.code === 'COMMAND_FAILED' &&
+      error.message === 'Stale ref @e1',
+  );
+});
+
+test('agent-browser provider adds doctor guidance for missing binary and invalid JSON', async () => {
+  const provider = createAgentBrowserWebProvider();
+
+  await assert.rejects(
+    () =>
+      withCommandExecutorOverride(
+        async () => {
+          throw new AppError('TOOL_MISSING', 'agent-browser not found');
+        },
+        async () => await provider.open('https://example.test'),
+      ),
+    (error: unknown) =>
+      error instanceof AppError &&
+      error.code === 'TOOL_MISSING' &&
+      error.details?.hint ===
+        'Install agent-browser and run `agent-browser doctor --offline --quick` to verify the local browser setup.',
+  );
+
+  await assert.rejects(
+    () =>
+      withCommandExecutorOverride(
+        async () => ({ stdout: 'not-json', stderr: '', exitCode: 0 }),
+        async () => await provider.open('https://example.test'),
+      ),
+    (error: unknown) =>
+      error instanceof AppError &&
+      error.code === 'COMMAND_FAILED' &&
+      error.message === 'agent-browser returned invalid JSON' &&
+      typeof error.details?.hint === 'string',
+  );
+});
+
+function recordingExecutor(calls: AgentBrowserCall[]) {
+  return async (cmd: string, args: string[]): Promise<ExecResult> => {
+    calls.push({ cmd, args });
+    return jsonResult({ success: true, data: {} });
+  };
+}
+
+function jsonResult(value: unknown): ExecResult {
+  return { stdout: JSON.stringify(value), stderr: '', exitCode: 0 };
+}