neoagent 2.1.18-beta.21 → 2.1.18-beta.23

package/docs/capabilities.md

@@ -121,4 +121,6 @@ Runtime settings let operators choose where higher-risk work runs:
 
 Remote execution uses `remote_worker_base_url` and an encrypted `remote_worker_token`. Production policy can require the secure VM profile and a strong VM guest token.
 
-These controls matter operationally: the browser, Android emulator, local files, and shell commands run wherever the NeoAgent backend or configured worker is running, not necessarily on the computer where you are reading the docs.
+These controls matter operationally: the browser, Android emulator, local files, and shell commands run wherever the NeoAgent backend, configured worker, or paired browser extension is running, not necessarily on the computer where you are reading the docs. Logs from a different server or remote browser may not match the logs on the local machine.
+
+For extension-only remote browser control, download `/api/browser-extension/download` from NeoAgent, unzip it on the remote machine, load the folder in `chrome://extensions`, and pair after logging in. The extension uses Chrome's debugger permission for full browser control, so Chrome will show its normal debugging warning while attached. The popup can check whether the server has a newer extension bundle, but unpacked Developer Mode installs still need a manual download and reload.

package/docs/configuration.md

@@ -89,6 +89,8 @@ Production policy can require the VM backend. In that case, set a strong `NEOAGE
 
 Remote worker settings are stored through the app as `remote_worker_base_url` and encrypted `remote_worker_token` values. Use an `http` or `https` worker URL only.
 
+The browser backend can also be set to `extension`. In that mode, browser actions use the paired Chrome extension connection rather than the server-local Puppeteer browser. To install only the extension on a remote machine, open NeoAgent, download `/api/browser-extension/download`, unzip it, load the folder through `chrome://extensions` with Developer mode enabled, then pair after logging in to NeoAgent. Unpacked Chrome extensions cannot replace themselves automatically; use the extension popup's update check to compare against the server bundle, then download and reload the latest ZIP when needed.
+
 ## Secrets Guidance
 
 Treat `SESSION_SECRET`, provider API keys, OAuth client secrets, messaging credentials, and Telnyx tokens as sensitive. Do not commit them, print them in logs, or expose them in client-side code. Store them in server-side environment variables or a secrets manager, restrict access to operators who need them, and rotate them immediately if you suspect exposure.

package/extensions/chrome-browser/background.mjs

@@ -0,0 +1,209 @@
+import { createBrowserProtocol } from './protocol.mjs';
+
+const STORAGE_KEYS = ['serverUrl', 'token', 'pairingId', 'pairingSecret', 'approvalUrl', 'status'];
+const protocol = createBrowserProtocol(chrome);
+let socket = null;
+let reconnectTimer = null;
+
+function getStorage(keys = STORAGE_KEYS) {
+  return chrome.storage.local.get(keys);
+}
+
+function setStorage(values) {
+  return chrome.storage.local.set(values);
+}
+
+function removeStorage(keys) {
+  return chrome.storage.local.remove(keys);
+}
+
+function normalizeServerUrl(value) {
+  return String(value || '').trim().replace(/\/+$/, '');
+}
+
+function websocketUrl(serverUrl, token) {
+  const url = new URL('/api/browser-extension/ws', serverUrl);
+  url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+  url.searchParams.set('token', token);
+  return url.toString();
+}
+
+function compareVersions(a, b) {
+  const left = String(a || '0').split('.').map((part) => Number(part) || 0);
+  const right = String(b || '0').split('.').map((part) => Number(part) || 0);
+  const length = Math.max(left.length, right.length);
+  for (let i = 0; i < length; i += 1) {
+    const delta = (left[i] || 0) - (right[i] || 0);
+    if (delta !== 0) return delta;
+  }
+  return 0;
+}
+
+async function updateStatus(status) {
+  await setStorage({ status });
+  chrome.runtime.sendMessage({ type: 'status', status }).catch(() => {});
+}
+
+async function connect() {
+  const { serverUrl, token } = await getStorage(['serverUrl', 'token']);
+  if (!serverUrl || !token) {
+    await updateStatus('not_paired');
+    return { connected: false };
+  }
+  if (socket && socket.readyState === WebSocket.OPEN) {
+    return { connected: true };
+  }
+  if (socket) {
+    try { socket.close(); } catch {}
+  }
+
+  socket = new WebSocket(websocketUrl(serverUrl, token));
+  await updateStatus('connecting');
+
+  socket.addEventListener('open', () => {
+    updateStatus('connected');
+  });
+  socket.addEventListener('close', () => {
+    updateStatus('disconnected');
+    clearTimeout(reconnectTimer);
+    reconnectTimer = setTimeout(() => connect().catch(() => {}), 5000);
+  });
+  socket.addEventListener('error', () => {
+    updateStatus('disconnected');
+  });
+  socket.addEventListener('message', (event) => {
+    handleSocketMessage(event.data).catch((error) => {
+      console.error('NeoAgent command handling failed', error);
+    });
+  });
+
+  return { connected: false };
+}
+
+async function handleSocketMessage(raw) {
+  let message;
+  try {
+    message = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  if (!message || message.type !== 'command' || !message.id) {
+    return;
+  }
+  try {
+    const result = await protocol.run(message.command, message.payload || {});
+    socket?.send(JSON.stringify({ type: 'result', id: message.id, ok: true, result }));
+  } catch (error) {
+    socket?.send(JSON.stringify({
+      type: 'result',
+      id: message.id,
+      ok: false,
+      error: error?.message || String(error),
+    }));
+  }
+}
+
+async function startPairing(serverUrl) {
+  const normalized = normalizeServerUrl(serverUrl);
+  if (!normalized) throw new Error('NeoAgent server URL required.');
+  const response = await fetch(`${normalized}/api/browser-extension/pairing/request`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ extensionName: 'NeoAgent Browser' }),
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) throw new Error(payload.error || `Pairing failed: ${response.status}`);
+  await setStorage({
+    serverUrl: normalized,
+    pairingId: payload.pairingId,
+    pairingSecret: payload.pairingSecret,
+    approvalUrl: payload.approvalUrl,
+    status: 'approval_pending',
+  });
+  await chrome.tabs.create({ url: payload.approvalUrl, active: true });
+  return payload;
+}
+
+async function claimPairing() {
+  const { serverUrl, pairingId, pairingSecret } = await getStorage(['serverUrl', 'pairingId', 'pairingSecret']);
+  if (!serverUrl || !pairingId || !pairingSecret) {
+    throw new Error('No pending pairing request.');
+  }
+  const response = await fetch(`${serverUrl}/api/browser-extension/pairing/${encodeURIComponent(pairingId)}/claim`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ pairingSecret, extensionName: 'NeoAgent Browser' }),
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) throw new Error(payload.error || `Claim failed: ${response.status}`);
+  await setStorage({
+    token: payload.token,
+    tokenId: payload.tokenId,
+    status: 'paired',
+  });
+  await removeStorage(['pairingId', 'pairingSecret', 'approvalUrl']);
+  await connect();
+  return payload;
+}
+
+async function disconnect() {
+  clearTimeout(reconnectTimer);
+  reconnectTimer = null;
+  if (socket) {
+    try { socket.close(); } catch {}
+  }
+  socket = null;
+  await removeStorage(['token', 'tokenId', 'pairingId', 'pairingSecret', 'approvalUrl']);
+  await updateStatus('not_paired');
+}
+
+async function checkForUpdates() {
+  const { serverUrl } = await getStorage(['serverUrl']);
+  if (!serverUrl) throw new Error('NeoAgent server URL required.');
+  const response = await fetch(`${serverUrl}/api/browser-extension/latest`);
+  const latest = await response.json().catch(() => ({}));
+  if (!response.ok) throw new Error(latest.error || `Update check failed: ${response.status}`);
+  const currentVersion = chrome.runtime.getManifest().version;
+  return {
+    currentVersion,
+    latestVersion: latest.version || currentVersion,
+    downloadUrl: latest.downloadUrl || `${serverUrl}/api/browser-extension/download`,
+    updateAvailable: compareVersions(latest.version, currentVersion) > 0,
+  };
+}
+
+async function openDownload() {
+  const { serverUrl } = await getStorage(['serverUrl']);
+  if (!serverUrl) throw new Error('NeoAgent server URL required.');
+  await chrome.tabs.create({ url: `${serverUrl}/api/browser-extension/download`, active: true });
+  return { success: true };
+}
+
+chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {
+  const run = async () => {
+    switch (message?.type) {
+      case 'startPairing':
+        return startPairing(message.serverUrl);
+      case 'claimPairing':
+        return claimPairing();
+      case 'connect':
+        return connect();
+      case 'disconnect':
+        return disconnect();
+      case 'checkForUpdates':
+        return checkForUpdates();
+      case 'openDownload':
+        return openDownload();
+      case 'getState':
+        return getStorage([...STORAGE_KEYS, 'tokenId']);
+      default:
+        return { error: 'unknown message' };
+    }
+  };
+  run()
+    .then((result) => sendResponse({ ok: true, result }))
+    .catch((error) => sendResponse({ ok: false, error: error.message || String(error) }));
+  return true;
+});
+
+connect().catch(() => {});

package/extensions/chrome-browser/manifest.json

@@ -0,0 +1,17 @@
+{
+  "manifest_version": 3,
+  "name": "NeoAgent Browser",
+  "version": "1.0.0",
+  "description": "Connect this Chrome browser to NeoAgent for browser automation.",
+  "minimum_chrome_version": "118",
+  "permissions": ["debugger", "storage", "tabs"],
+  "host_permissions": ["http://*/*", "https://*/*"],
+  "action": {
+    "default_title": "NeoAgent Browser",
+    "default_popup": "popup.html"
+  },
+  "background": {
+    "service_worker": "background.mjs",
+    "type": "module"
+  }
+}

package/extensions/chrome-browser/popup.css

@@ -0,0 +1,69 @@
+body {
+  margin: 0;
+  width: 320px;
+  background: #0f172a;
+  color: #e5e7eb;
+  font: 14px/1.4 system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+main {
+  padding: 16px;
+}
+
+h1 {
+  margin: 0 0 10px;
+  font-size: 18px;
+}
+
+#status {
+  margin: 0 0 12px;
+  color: #38bdf8;
+  font-weight: 700;
+}
+
+label {
+  display: grid;
+  gap: 6px;
+  color: #cbd5e1;
+}
+
+input {
+  box-sizing: border-box;
+  width: 100%;
+  padding: 9px 10px;
+  border: 1px solid #334155;
+  border-radius: 8px;
+  background: #111827;
+  color: #f8fafc;
+}
+
+.actions {
+  display: grid;
+  gap: 8px;
+  margin-top: 12px;
+}
+
+button {
+  border: 0;
+  border-radius: 8px;
+  padding: 9px 10px;
+  background: #0284c7;
+  color: white;
+  font: inherit;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+button.secondary {
+  background: #334155;
+}
+
+.hint,
+.message {
+  color: #94a3b8;
+  font-size: 12px;
+}
+
+.message {
+  min-height: 1.2em;
+}

package/extensions/chrome-browser/popup.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>NeoAgent Browser</title>
+  <link rel="stylesheet" href="popup.css">
+</head>
+<body>
+  <main>
+    <h1>NeoAgent Browser</h1>
+    <p id="status">Loading...</p>
+    <label>
+      Server URL
+      <input id="serverUrl" type="url" placeholder="https://neoagent.example.com">
+    </label>
+    <div class="actions">
+      <button id="pair">Pair after login</button>
+      <button id="claim">Finish pairing</button>
+      <button id="checkUpdate" class="secondary">Check for update</button>
+      <button id="download" class="secondary">Download latest ZIP</button>
+      <button id="disconnect" class="secondary">Disconnect</button>
+    </div>
+    <p class="hint">Pairing opens NeoAgent so you can log in there. This extension never stores your NeoAgent password.</p>
+    <p id="message" class="message"></p>
+  </main>
+  <script src="popup.js" type="module"></script>
+</body>
+</html>

package/extensions/chrome-browser/popup.js

@@ -0,0 +1,81 @@
+const statusEl = document.querySelector('#status');
+const serverUrlEl = document.querySelector('#serverUrl');
+const messageEl = document.querySelector('#message');
+
+function send(type, payload = {}) {
+  return chrome.runtime.sendMessage({ type, ...payload }).then((response) => {
+    if (!response?.ok) throw new Error(response?.error || 'Extension action failed.');
+    return response.result;
+  });
+}
+
+function setMessage(text) {
+  messageEl.textContent = text || '';
+}
+
+async function refresh() {
+  const state = await send('getState');
+  statusEl.textContent = `Status: ${state.status || 'not_paired'}`;
+  if (state.serverUrl) serverUrlEl.value = state.serverUrl;
+}
+
+document.querySelector('#pair').addEventListener('click', async () => {
+  try {
+    setMessage('');
+    await send('startPairing', { serverUrl: serverUrlEl.value });
+    await refresh();
+    setMessage('Log in and approve the extension in the opened NeoAgent tab.');
+  } catch (error) {
+    setMessage(error.message);
+  }
+});
+
+document.querySelector('#claim').addEventListener('click', async () => {
+  try {
+    setMessage('');
+    await send('claimPairing');
+    await refresh();
+    setMessage('Connected.');
+  } catch (error) {
+    setMessage(error.message);
+  }
+});
+
+document.querySelector('#disconnect').addEventListener('click', async () => {
+  try {
+    setMessage('');
+    await send('disconnect');
+    await refresh();
+  } catch (error) {
+    setMessage(error.message);
+  }
+});
+
+document.querySelector('#checkUpdate').addEventListener('click', async () => {
+  try {
+    setMessage('');
+    const result = await send('checkForUpdates');
+    setMessage(
+      result.updateAvailable
+        ? `Update available: ${result.currentVersion} -> ${result.latestVersion}.`
+        : `Current version ${result.currentVersion} is up to date.`,
+    );
+  } catch (error) {
+    setMessage(error.message);
+  }
+});
+
+document.querySelector('#download').addEventListener('click', async () => {
+  try {
+    setMessage('');
+    await send('openDownload');
+  } catch (error) {
+    setMessage(error.message);
+  }
+});
+
+chrome.runtime.onMessage.addListener((message) => {
+  if (message?.type === 'status') refresh().catch(() => {});
+});
+
+refresh().catch((error) => setMessage(error.message));