feat: harden browser automation lifecycle

Author: devswha

docs/BROWSER-CUA-VERIFICATION.md

@@ -0,0 +1,82 @@
+# Browser and CUA verification
+
+Last verified: 2026-08-21 on Apple Silicon macOS.
+
+## Implemented surface
+
+- A Bun NDJSON sidecar owns the persistent Chrome-for-Testing profile, tabs,
+  structured CDP actions, input, downloads policy, and screencast frames.
+- The Workspace Browser panel and GJC agent bridge share the same session tabs.
+- Browser HTTP automation is available at `/api/browser/:sessionId`; the first
+  PoC `/api/automation/browser/:sessionId` routes remain as compatibility aliases.
+- `npm run browser:debug` is an HTTP-only client for the running server. It does
+  not launch Chromium and accepts the desktop cookie through
+  `GAJAE_BROWSER_DEBUG_COOKIE` when desktop authentication is enabled.
+- CUA Driver remains an external prerequisite. The status surface reports its
+  version, daemon state, Accessibility permission, and Screen Recording
+  permission. Agent native actions are limited to the reviewed allowlist.
+- Origin and application grants are session-scoped by default. Only an explicit
+  “Always allow” persists; individual grants can be revoked in Settings.
+- Stop closes the browser/CUA session, aborts active work, and clears session
+  grants. A crashed sidecar reaps its owned Chromium process, restarts, restores
+  tab URLs and the active tab, then resumes screencasting.
+
+The PoC intentionally excludes file upload, automatic download saving, browser
+extensions, existing Chrome profiles, force-quitting native apps, clipboard
+reading, file transfer, screen recording, and lock-screen control.
+
+## Automated evidence
+
+The following passed on 2026-08-21:
+
+- `npm run verify`: dependency audit, TypeScript, Rust formatting/clippy/tests,
+  all server and client tests, lint, identity checks, and production builds.
+- `npm run test:e2e:gjc`: seven driver/wire/browser integration scenarios.
+- `npm run test:e2e:browser`: real Chrome-for-Testing actions, popup and tab
+  state, navigation, dialogs, screencast, and interruption of a non-settling
+  page script.
+- Fake sidecar recovery integration: restart, orphan-browser reap, URL restore,
+  active-tab restore, and screencast resubscription.
+- Fake CUA and HTTP route integration: computer call, persistent grant creation,
+  individual revoke, and the public `/api/browser/:sessionId` routes.
+- `npm run smoke:packaged-server -- --tauri-app <app>` and strict `codesign`
+  verification against the generated Tauri app bundle.
+
+## Manual packaged-app evidence
+
+The generated app at
+`src-tauri/target/aarch64-apple-darwin/release/bundle/macos/Gajae Code App.app`
+passed these checks:
+
+- Opened `http://100.78.133.28:8080/` in the Workspace Browser panel and showed
+  the live todo-list Chromium frame.
+- Killed only the owned browser sidecar. The app reaped the orphaned Chromium,
+  started a new sidecar and Chromium process, restored the same URL and tab, and
+  resumed the live frame without restarting the desktop app.
+- Ran a Sol session using `computer.list_apps`; CUA Driver 0.21.0 returned that
+  TextEdit was running and the app remained stable.
+- Requested a previously unapproved `https://example.org` origin, selected
+  **Deny**, and observed a failed-closed tool result while the shared browser
+  stayed on the existing todo page.
+- Started `browser.run` with a promise that never settles, pressed Stop, and
+  observed cancellation and browser-session cleanup in 733 ms.
+
+macOS Accessibility and Screen Recording were already granted for this test.
+They were inspected but not revoked because changing OS privacy permissions is
+outside normal app QA. Denied app-level origin access exercises the app's
+fail-closed approval path without modifying system security settings.
+
+## Upstream SDK dependency
+
+`@gajae-code/coding-agent@0.14.2` and its upstream `main` branch do not yet
+provide an external backend interface for the reserved `browser` and `computer`
+tools. The app therefore still supplies these two tools through the SDK's
+`customTools` option. The requested architecture—inject at built-in tool
+materialization time without a same-name custom-tool overwrite—requires an
+upstream release. It is tracked in
+[gajae-code issue #4809](https://github.com/Yeachan-Heo/gajae-code/issues/4809).
+
+After upstream publishes that API, replace `customTools` in
+`server/gjc-bun-sdk-adapter.ts`, update `@gajae-code/coding-agent`, and rerun the
+same gates and packaged-app scenarios above. No direct `node_modules` patch is
+permitted.

package.json

@@ -65,6 +65,7 @@
     "pretest": "npm run build:core:dev",
     "test:e2e:gjc": "TSX_TSCONFIG_PATH=server/tsconfig.json node --import tsx --test --test-concurrency=1 server/e2e/gjc-slice4.browser.e2e.ts server/e2e/gjc-slice4.wire.e2e.ts",
     "test:e2e:browser": "TSX_TSCONFIG_PATH=server/tsconfig.json node --import tsx --test --test-concurrency=1 server/e2e/browser-sidecar.e2e.ts",
+    "browser:debug": "node scripts/browser-debug-client.mjs",
     "poc:opencodex:cua": "node scripts/check-opencodex-cua-poc.mjs",
     "lint": "eslint src/ server/ shared/ scripts/ vite.config.js tailwind.config.js",
     "lint:fix": "eslint src/ server/ shared/ scripts/ vite.config.js tailwind.config.js --fix",

scripts/browser-debug-client.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+const HELP = `Usage:
+  npm run browser:debug -- [options] status
+  npm run browser:debug -- [options] open [url]
+  npm run browser:debug -- [options] command '<json>'
+  npm run browser:debug -- [options] input '<json>'
+  npm run browser:debug -- [options] close
+
+Options:
+  --base-url <url>  Gajae server URL (default: http://127.0.0.1:3001)
+  --session <id>    Browser session ID (default: browser-debug)
+  --cookie <value>  Desktop cookie value or full Cookie header
+  --api-key <key>   Self-hosted x-api-key value
+
+Environment alternatives:
+  GAJAE_BROWSER_DEBUG_BASE_URL, GAJAE_BROWSER_DEBUG_SESSION,
+  GAJAE_BROWSER_DEBUG_COOKIE, API_KEY
+`;
+
+function parseArguments(argv) {
+  const options = {
+    baseUrl: process.env.GAJAE_BROWSER_DEBUG_BASE_URL ?? 'http://127.0.0.1:3001',
+    sessionId: process.env.GAJAE_BROWSER_DEBUG_SESSION ?? 'browser-debug',
+    cookie: process.env.GAJAE_BROWSER_DEBUG_COOKIE,
+    apiKey: process.env.API_KEY,
+  };
+  const positionals = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === '--help' || value === '-h') return { ...options, command: 'help', values: [] };
+    if (value === '--base-url' || value === '--session' || value === '--cookie' || value === '--api-key') {
+      const next = argv[index + 1];
+      if (!next) throw new Error(`${value} requires a value.`);
+      if (value === '--base-url') options.baseUrl = next;
+      if (value === '--session') options.sessionId = next;
+      if (value === '--cookie') options.cookie = next;
+      if (value === '--api-key') options.apiKey = next;
+      index += 1;
+      continue;
+    }
+    positionals.push(value);
+  }
+  return { ...options, command: positionals[0] ?? 'help', values: positionals.slice(1) };
+}
+
+function requestFor({ command, values, sessionId }) {
+  const session = encodeURIComponent(sessionId);
+  switch (command) {
+    case 'status':
+      return { path: '/api/automation/status', init: {} };
+    case 'open':
+      return {
+        path: `/api/browser/${session}/open`,
+        init: { method: 'POST', body: JSON.stringify({ ...(values[0] ? { url: values[0] } : {}) }) },
+      };
+    case 'command':
+      return {
+        path: `/api/browser/${session}/command`,
+        init: { method: 'POST', body: JSON.stringify({ command: parseJson(values[0], 'command') }) },
+      };
+    case 'input':
+      return {
+        path: `/api/browser/${session}/input`,
+        init: { method: 'POST', body: JSON.stringify({ input: parseJson(values[0], 'input') }) },
+      };
+    case 'close':
+      return { path: `/api/browser/${session}`, init: { method: 'DELETE' } };
+    default:
+      throw new Error(`Unknown command: ${command}`);
+  }
+}
+
+function parseJson(value, label) {
+  if (!value) throw new Error(`${label} requires one JSON object argument.`);
+  const parsed = JSON.parse(value);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${label} must be a JSON object.`);
+  }
+  return parsed;
+}
+
+function cookieHeader(value) {
+  if (!value) return undefined;
+  return value.includes('=') ? value : `gajae_desktop_api_key=${value}`;
+}
+
+export async function runBrowserDebugClient(argv, output = console.log) {
+  const options = parseArguments(argv);
+  if (options.command === 'help') {
+    output(HELP.trimEnd());
+    return;
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(options.sessionId)) {
+    throw new Error('Session ID contains unsupported characters.');
+  }
+  const { path, init } = requestFor(options);
+  const headers = { accept: 'application/json' };
+  if (init.body) headers['content-type'] = 'application/json';
+  if (options.apiKey) headers['x-api-key'] = options.apiKey;
+  const cookie = cookieHeader(options.cookie);
+  if (cookie) headers.cookie = cookie;
+  const response = await fetch(new URL(path, options.baseUrl), { ...init, headers });
+  const text = await response.text();
+  let result;
+  try {
+    result = text ? JSON.parse(text) : null;
+  } catch {
+    result = { response: text };
+  }
+  if (!response.ok) throw new Error(`HTTP ${response.status}: ${JSON.stringify(result)}`);
+  output(JSON.stringify(result, null, 2));
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+  runBrowserDebugClient(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  });
+}

scripts/browser-debug-client.test.mjs

@@ -0,0 +1,41 @@
+import assert from 'node:assert/strict';
+import { once } from 'node:events';
+import { createServer } from 'node:http';
+import test from 'node:test';
+
+import { runBrowserDebugClient } from './browser-debug-client.mjs';
+
+test('browser debug client calls the long-running server instead of launching Chromium', async () => {
+  const requests = [];
+  const server = createServer((request, response) => {
+    let body = '';
+    request.on('data', (chunk) => { body += chunk; });
+    request.on('end', () => {
+      requests.push({ method: request.method, url: request.url, headers: request.headers, body });
+      response.setHeader('content-type', 'application/json');
+      response.end(JSON.stringify({ accepted: true }));
+    });
+  });
+  server.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+  const address = server.address();
+  if (!address || typeof address === 'string') throw new Error('Debug client test server did not bind.');
+  const output = [];
+  try {
+    await runBrowserDebugClient([
+      '--base-url', `http://127.0.0.1:${address.port}`,
+      '--session', 'debug-1',
+      '--cookie', 'secret',
+      'command', '{"action":"observe"}',
+    ], (value) => output.push(value));
+  } finally {
+    server.close();
+    await once(server, 'close');
+  }
+  assert.equal(requests.length, 1);
+  assert.equal(requests[0].method, 'POST');
+  assert.equal(requests[0].url, '/api/browser/debug-1/command');
+  assert.equal(requests[0].headers.cookie, 'gajae_desktop_api_key=secret');
+  assert.deepEqual(JSON.parse(requests[0].body), { command: { action: 'observe' } });
+  assert.deepEqual(output.map(JSON.parse), [{ accepted: true }]);
+});

server/e2e/browser-sidecar.e2e.ts

@@ -194,5 +194,19 @@ test('real Chromium sidecar shares structured actions, tabs, and screencast stat
   const state = await sidecar.request('session.state', 'browser-e2e') as { activeTabId: string | null; tabs: unknown[] };
   assert.equal(state.tabs.length, 1);
   assert.ok(state.activeTabId);
-  assert.deepEqual(await sidecar.request('session.close', 'browser-e2e'), { closed: true });
+
+  const interrupted = assert.rejects(
+    sidecar.request('browser.command', 'browser-e2e', {
+      command: { action: 'run', code: 'new Promise(() => {})', timeoutMs: 30_000 },
+    }),
+    /closed|destroyed|Target|session|Protocol/iu,
+  );
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  const closeStarted = Date.now();
+  assert.deepEqual(await Promise.race([
+    sidecar.request('session.close', 'browser-e2e'),
+    new Promise((_, reject) => setTimeout(() => reject(new Error('session.close was blocked behind browser.run')), 2_000)),
+  ]), { closed: true });
+  assert.ok(Date.now() - closeStarted < 2_000, 'session.close must interrupt a long browser.run');
+  await interrupted;
 });

server/gjc-automation-tools.test.ts

@@ -81,6 +81,53 @@ test('agent browser asks for origin access before opening and records allow once
   }
 });
 
+test('agent browser denial fails closed without opening the requested origin', async () => {
+  const directory = await mkdtemp(join(tmpdir(), 'gajae-automation-deny-'));
+  const socketPath = join(directory, 'bridge.sock');
+  const requests: Array<Record<string, unknown>> = [];
+  const server = net.createServer((socket) => {
+    let buffer = '';
+    socket.setEncoding('utf8');
+    socket.on('data', (chunk) => {
+      buffer += chunk;
+      const newline = buffer.indexOf('\n');
+      if (newline < 0) return;
+      const request = JSON.parse(buffer.slice(0, newline)) as Record<string, unknown>;
+      requests.push(request);
+      socket.end(`${JSON.stringify({
+        id: request.id,
+        ok: true,
+        result: { granted: false, origin: 'https://denied.example' },
+      })}\n`);
+    });
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(socketPath, () => resolve());
+  });
+
+  try {
+    const [browser] = createGjcAutomationTools('app-session', {
+      async select() { return 'Deny'; },
+    }, { socketPath, token: TEST_TOKEN });
+    assert.ok(browser);
+    await assert.rejects(
+      browser.execute(
+        'tool-call-denied',
+        { action: 'open', url: 'https://denied.example/private' },
+        undefined,
+        {} as never,
+        undefined,
+      ),
+      /access .* was denied/iu,
+    );
+    assert.deepEqual(requests.map((request) => request.operation), ['authorize']);
+  } finally {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
 test('agent computer asks for application access before controlling it', async () => {
   const directory = await mkdtemp(join(tmpdir(), 'gajae-computer-tools-'));
   const socketPath = join(directory, 'bridge.sock');

server/index.js

@@ -53,7 +53,12 @@ import providerRoutes from './modules/providers/provider.routes.js';
 import voiceRoutes from './voice-proxy.js';
 import { assetsRoutes } from './modules/assets/index.js';
 import { initializeDatabase, projectsDb, sessionsDb } from './modules/database/index.js';
-import { automationRoutes, automationService, handleBrowserConnection } from './modules/automation/index.js';
+import {
+    automationRoutes,
+    automationService,
+    createBrowserAutomationRouter,
+    handleBrowserConnection,
+} from './modules/automation/index.js';
 import { validateApiKey, authenticateToken, authenticateWebSocket } from './middleware/auth.js';
 import { c } from './utils/colors.js';
 import { evaluateExposure } from './utils/exposure-guard.js';
@@ -194,6 +199,7 @@ app.use('/api/providers', authenticateToken, providerRoutes);
 // Chromium/CDP and CUA Driver automation. The app factory's desktop guard and
 // the normal owner authentication both run before these routes.
 app.use('/api/automation', authenticateToken, automationRoutes);
+app.use('/api/browser', authenticateToken, createBrowserAutomationRouter());
 
 // Agent API Routes (uses API key authentication)