feat: manage web backend setup (#833)

Author: thymikee

.github/actions/setup-node-pnpm/action.yml

@@ -5,7 +5,7 @@ inputs:
   node-version:
     description: 'Node.js version'
     required: false
-    default: '22.19'
+    default: '24.13'
   pnpm-version:
     description: 'pnpm version'
     required: false

.github/workflows/publish-mcp-registry.yml

@@ -33,7 +33,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
-          node-version: "22"
+          node-version: '24.13'
 
       - name: Resolve release metadata
         id: meta

.github/workflows/release-android-snapshot-helper.yml

@@ -32,7 +32,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
-          node-version: "22"
+          node-version: '24.13'
 
       - name: Install Android SDK packages
         run: |

.github/workflows/release-ios-runner.yml

@@ -26,7 +26,7 @@ jobs:
     env:
       AGENT_DEVICE_XCUITEST_PLATFORM: ios
       AGENT_DEVICE_XCUITEST_DESTINATION: generic/platform=iOS Simulator
-      AGENT_DEVICE_IOS_CLEAN_DERIVED: "1"
+      AGENT_DEVICE_IOS_CLEAN_DERIVED: '1'
     steps:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -36,7 +36,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
-          node-version: "22"
+          node-version: '24.13'
 
       - name: Resolve release metadata
         id: meta

docs/agents/domain.md

@@ -7,5 +7,6 @@ Before architecture, diagnosis, TDD, triage, PRD, or roadmap work, read:
 - `CONTEXT.md` for domain vocabulary, test strategy terms, and architecture language.
 - Relevant ADRs in `docs/adr/` for accepted architecture decisions.
 - This `docs/agents/` directory for issue-tracker and triage-label conventions.
+- `docs/agents/web-backend.md` before changing web automation backend setup or diagnostics.
 
 Use the vocabulary from `CONTEXT.md` in issue titles, refactor proposals, test names, and architecture notes. If a proposed change contradicts an ADR, call that out explicitly and explain why the decision should be reopened.

docs/agents/web-backend.md

@@ -0,0 +1,23 @@
+# Web Backend
+
+Web automation uses a managed `agent-browser` backend as an implementation detail.
+
+- Runtime web commands resolve the backend only from the state-dir managed install at `tools/agent-browser/<version>`.
+- Normal `--platform web` commands do not install the managed backend on first use. If the backend is missing, they fail with a setup hint.
+- Use `agent-device web setup` before first web automation and in CI/sandbox bootstrap steps.
+- Use `agent-device web doctor` to run the backend health check.
+- The managed install respects `--state-dir` / `AGENT_DEVICE_STATE_DIR`.
+- Web automation requires Node 24+ while the rest of agent-device keeps its Node 22 baseline.
+
+Default first-run flow:
+
+```sh
+agent-device web setup
+agent-device open "https://example.com" --platform web
+agent-device snapshot -i --platform web
+agent-device close --platform web
+```
+
+Do not document direct `agent-browser` commands as agent-device features. Browser-specific network,
+CDP, React web, tabs, downloads, auth vaults, and profiling stay out of the minimal web surface until
+there is an explicit agent-device command design for them.

src/cli.ts

@@ -14,6 +14,7 @@ import {
 import { materializeRemoteConnectionForCommand } from './cli/commands/connection-runtime.ts';
 import { tryRunClientBackedCommand } from './cli/commands/router.ts';
 import { runReactDevtoolsCommand } from './cli/commands/react-devtools.ts';
+import { runWebCommand } from './cli/commands/web.ts';
 import { readCliBatchStepsJson } from './cli/batch-steps.ts';
 import {
   createRequestId,
@@ -205,6 +206,14 @@ export async function runCli(argv: string[], deps: CliDeps = DEFAULT_CLI_DEPS):
           process.exit(exitCode);
           return;
         }
+        if (command === 'web') {
+          const exitCode = await runWebCommand(positionals, {
+            flags: effectiveFlags,
+            stateDir: daemonPaths.baseDir,
+          });
+          process.exit(exitCode);
+          return;
+        }
         maybeRunUpgradeNotifier({
           command,
           currentVersion: version,

src/cli/commands/web.ts

@@ -0,0 +1,44 @@
+import {
+  doctorManagedAgentBrowser,
+  setupManagedAgentBrowser,
+} from '../../platforms/web/agent-browser-tool.ts';
+import { AppError } from '../../utils/errors.ts';
+import type { CliFlags } from '../../utils/cli-flags.ts';
+import { printJson } from '../../utils/output.ts';
+
+export async function runWebCommand(
+  positionals: string[],
+  options: { flags: CliFlags; stateDir: string },
+): Promise<number> {
+  const action = positionals[0];
+  switch (action) {
+    case 'setup': {
+      const status = await setupManagedAgentBrowser({
+        stateDir: options.stateDir,
+      });
+      printWebResult(options.flags.json, 'Managed web backend installed.', { status });
+      return 0;
+    }
+    case 'doctor': {
+      const result = await doctorManagedAgentBrowser({
+        stateDir: options.stateDir,
+      });
+      printWebResult(
+        options.flags.json,
+        result.exitCode === 0 ? 'Web backend is healthy.' : 'Web backend doctor reported issues.',
+        result,
+      );
+      return result.exitCode;
+    }
+    default:
+      throw new AppError('INVALID_ARGS', 'web requires setup or doctor');
+  }
+}
+
+function printWebResult(json: boolean | undefined, message: string, data: Record<string, unknown>) {
+  if (json) {
+    printJson({ success: true, data });
+    return;
+  }
+  process.stdout.write(`${message}\n`);
+}

src/command-catalog.ts

@@ -67,6 +67,7 @@ const LOCAL_CLI_COMMANDS = {
   metro: 'metro',
   reactDevtools: 'react-devtools',
   session: 'session',
+  web: 'web',
 } as const;
 
 export const GESTURE_KINDS = ['pan', 'fling', 'swipe', 'pinch', 'rotate', 'transform'] as const;
@@ -89,6 +90,7 @@ const MCP_UNEXPOSED_CLI_COMMANDS = commandSet(
   LOCAL_CLI_COMMANDS.disconnect,
   LOCAL_CLI_COMMANDS.mcp,
   LOCAL_CLI_COMMANDS.reactDevtools,
+  LOCAL_CLI_COMMANDS.web,
   PUBLIC_COMMANDS.prepare,
 );
 
@@ -102,6 +104,7 @@ const CAPABILITY_EXEMPT_CLI_COMMANDS = commandSet(
   LOCAL_CLI_COMMANDS.metro,
   LOCAL_CLI_COMMANDS.reactDevtools,
   LOCAL_CLI_COMMANDS.session,
+  LOCAL_CLI_COMMANDS.web,
   PUBLIC_COMMANDS.appState,
   PUBLIC_COMMANDS.prepare,
   PUBLIC_COMMANDS.batch,

src/daemon-runtime.ts

@@ -83,6 +83,7 @@ export async function startDaemonRuntime(
 
   const handleRequest = createRequestHandler({
     logPath,
+    stateDir: baseDir,
     token,
     sessionStore,
     leaseRegistry,