neoagent 3.2.1-beta.1 → 3.2.1-beta.11

package/extensions/chrome-browser/background.mjs

@@ -1,16 +1,31 @@
-import { createBrowserProtocol } from './protocol.mjs';
+import {
+  EXTENSION_PROTOCOL_VERSION,
+  MESSAGE_TYPES,
+  createBrowserProtocol,
+} from './protocol.mjs';
 import { DEFAULT_SERVER_URL } from './config.mjs';
+import { fetchJsonWithTimeout } from './http.mjs';
 
 const STORAGE_KEYS = ['serverUrl', 'configuredServerUrl', 'token', 'pairingId', 'pairingSecret', 'approvalUrl', 'status', 'extensionName'];
-const protocol = createBrowserProtocol(chrome);
 let socket = null;
 let reconnectTimer = null;
-let suppressSocketClose = false;
-const DEFAULT_FETCH_TIMEOUT_MS = 10000;
+let connectPromise = null;
+let connectionEpoch = 0;
+let reconnectAttempt = 0;
+let statusUpdateQueue = Promise.resolve();
+let commandQueue = Promise.resolve();
+const activeCommandControllers = new Map();
+const pendingUrlValidations = new Map();
 const DEFAULT_WS_CONNECT_TIMEOUT_MS = 10000;
+const DEFAULT_URL_VALIDATION_TIMEOUT_MS = 6500;
+const MAX_PENDING_URL_VALIDATIONS = 256;
+const RECONNECT_BASE_DELAY_MS = 1000;
+const RECONNECT_MAX_DELAY_MS = 60 * 1000;
 const KEEPALIVE_ALARM_NAME = 'neoagent-extension-keepalive';
 const KEEPALIVE_ALARM_MINUTES = 1;
-const EXTENSION_PROTOCOL_VERSION = 1;
+const protocol = createBrowserProtocol(chrome, {
+  validateUrl: requestUrlValidation,
+});
 
 function getStorage(keys = STORAGE_KEYS) {
   return chrome.storage.local.get(keys);
@@ -25,7 +40,24 @@ function removeStorage(keys) {
 }
 
 function normalizeServerUrl(value) {
-  return String(value || '').trim().replace(/\/+$/, '');
+  const raw = String(value || '').trim();
+  if (!raw) return '';
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error('NeoAgent server URL is invalid.');
+  }
+  if (!['http:', 'https:'].includes(parsed.protocol)) {
+    throw new Error('NeoAgent server URL must use http or https.');
+  }
+  if (parsed.username || parsed.password) {
+    throw new Error('NeoAgent server URL must not contain credentials.');
+  }
+  parsed.search = '';
+  parsed.hash = '';
+  parsed.pathname = parsed.pathname.replace(/\/+$/, '');
+  return parsed.toString().replace(/\/+$/, '');
 }
 
 function configuredServerUrl() {
@@ -40,7 +72,7 @@ async function resolveServerUrl(preferred) {
 }
 
 function websocketUrl(serverUrl, token) {
-  const url = new URL('/api/browser-extension/ws', serverUrl);
+  const url = new URL('api/browser-extension/ws', `${serverUrl}/`);
   url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
   // Token in the URL is required for the HTTP upgrade handshake; the browser
   // WebSocket API does not support custom headers. Ensure the server's access
@@ -49,19 +81,6 @@ function websocketUrl(serverUrl, token) {
   return url.toString();
 }
 
-async function fetchWithTimeout(url, options = {}, timeoutMs = DEFAULT_FETCH_TIMEOUT_MS) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    return await fetch(url, {
-      ...options,
-      signal: controller.signal,
-    });
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
 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);
@@ -73,9 +92,14 @@ function compareVersions(a, b) {
   return 0;
 }
 
-async function updateStatus(status) {
-  await setStorage({ status });
-  chrome.runtime.sendMessage({ type: 'status', status }).catch(() => {});
+async function updateStatus(status, expectedEpoch = null) {
+  const task = statusUpdateQueue.catch(() => {}).then(async () => {
+    if (expectedEpoch != null && expectedEpoch !== connectionEpoch) return;
+    await setStorage({ status });
+    await Promise.resolve(chrome.runtime.sendMessage({ type: 'status', status })).catch(() => {});
+  });
+  statusUpdateQueue = task.catch(() => {});
+  return task;
 }
 
 function clearReconnectTimer() {
@@ -83,113 +107,298 @@ function clearReconnectTimer() {
   reconnectTimer = null;
 }
 
+function scheduleReconnect() {
+  clearReconnectTimer();
+  const exponentialDelay = Math.min(
+    RECONNECT_MAX_DELAY_MS,
+    RECONNECT_BASE_DELAY_MS * (2 ** Math.min(reconnectAttempt, 6)),
+  );
+  reconnectAttempt += 1;
+  const jitterMs = Math.floor(exponentialDelay * Math.random() * 0.25);
+  reconnectTimer = setTimeout(() => connect().catch(() => {}), exponentialDelay + jitterMs);
+}
+
 function ensureKeepaliveAlarm() {
   chrome.alarms?.create?.(KEEPALIVE_ALARM_NAME, {
     periodInMinutes: KEEPALIVE_ALARM_MINUTES,
   });
 }
 
-async function handleSocketDisconnected(ws) {
-  if (socket !== ws) {
-    return;
+function rejectPendingUrlValidations(error, expectedSocket = null) {
+  for (const entry of Array.from(pendingUrlValidations.values())) {
+    if (!expectedSocket || entry.socket === expectedSocket) entry.reject(error);
+  }
+}
+
+function requestUrlValidation(url, options = {}) {
+  const ws = socket;
+  if (!ws || ws.readyState !== WebSocket.OPEN) {
+    return Promise.reject(new Error('NeoAgent browser security validation is unavailable.'));
+  }
+  if (pendingUrlValidations.size >= MAX_PENDING_URL_VALIDATIONS) {
+    return Promise.reject(new Error('Too many browser URL validations are pending.'));
   }
+
+  const id = crypto.randomUUID();
+  const signal = options.signal || null;
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let timer = null;
+    const cleanup = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+      pendingUrlValidations.delete(id);
+    };
+    const finish = (callback, value) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      callback(value);
+    };
+    const onAbort = () => finish(
+      reject,
+      signal.reason instanceof Error
+        ? signal.reason
+        : new Error('Browser URL validation was aborted.'),
+    );
+    const entry = {
+      socket: ws,
+      resolve: (allowed) => finish(resolve, allowed === true),
+      reject: (error) => finish(reject, error),
+    };
+    timer = setTimeout(() => {
+      entry.reject(new Error('Browser URL validation timed out.'));
+    }, DEFAULT_URL_VALIDATION_TIMEOUT_MS);
+    if (signal?.aborted) {
+      onAbort();
+      return;
+    }
+    signal?.addEventListener('abort', onAbort, { once: true });
+    pendingUrlValidations.set(id, entry);
+    if (!sendSocketMessage(ws, {
+      type: MESSAGE_TYPES.URL_VALIDATION_REQUEST,
+      version: EXTENSION_PROTOCOL_VERSION,
+      id,
+      url: String(url || ''),
+    })) {
+      entry.reject(new Error('Browser URL validation could not be sent.'));
+    }
+  });
+}
+
+async function handleSocketDisconnected(ws, socketEpoch) {
+  if (socket !== ws || socketEpoch !== connectionEpoch) return;
   socket = null;
-  if (suppressSocketClose) {
-    suppressSocketClose = false;
-    return;
+  const disconnectedEpoch = ++connectionEpoch;
+  try {
+    if (ws.readyState !== WebSocket.CLOSED) ws.close();
+  } catch {}
+  for (const controller of activeCommandControllers.values()) {
+    controller.abort(new Error('NeoAgent browser connection closed.'));
   }
+  activeCommandControllers.clear();
+  rejectPendingUrlValidations(new Error('NeoAgent browser connection closed.'), ws);
   const { token } = await getStorage(['token']);
+  if (connectionEpoch !== disconnectedEpoch || socket) return;
   if (!token) {
-    await updateStatus('not_paired');
+    await updateStatus('not_paired', disconnectedEpoch);
     return;
   }
-  await updateStatus('disconnected');
-  clearReconnectTimer();
-  reconnectTimer = setTimeout(() => connect().catch(() => {}), 5000);
+  await updateStatus('disconnected', disconnectedEpoch);
+  if (connectionEpoch === disconnectedEpoch && !socket) scheduleReconnect();
 }
 
-async function connect() {
-  const { token } = await getStorage(['token']);
-  const serverUrl = await resolveServerUrl();
+async function connectOnce() {
+  const startingEpoch = connectionEpoch;
+  const { token, serverUrl: storedServerUrl } = await getStorage(['token', 'serverUrl']);
+  if (startingEpoch !== connectionEpoch) return { connected: false, cancelled: true };
+  const serverUrl = normalizeServerUrl(storedServerUrl) || configuredServerUrl();
   if (!serverUrl || !token) {
-    await updateStatus('not_paired');
+    await updateStatus('not_paired', startingEpoch);
     return { connected: false };
   }
   if (socket && socket.readyState === WebSocket.OPEN) {
     return { connected: true };
   }
-  if (socket) {
-    try { socket.close(); } catch {}
+  if (socket && socket.readyState === WebSocket.CONNECTING) {
+    return { connected: false, connecting: true };
+  }
+  const staleSocket = socket;
+  socket = null;
+  if (staleSocket) {
+    rejectPendingUrlValidations(new Error('NeoAgent browser connection was replaced.'), staleSocket);
+    try { staleSocket.close(); } catch {}
   }
   clearReconnectTimer();
-  suppressSocketClose = false;
 
-  const ws = new WebSocket(websocketUrl(serverUrl, token));
+  const socketEpoch = ++connectionEpoch;
+  let ws;
+  try {
+    ws = new WebSocket(websocketUrl(serverUrl, token));
+  } catch (error) {
+    await updateStatus('disconnected', socketEpoch);
+    scheduleReconnect();
+    throw error;
+  }
   socket = ws;
-  await updateStatus('connecting');
-  const connectTimeout = setTimeout(() => {
-    if (socket === ws && ws.readyState !== WebSocket.OPEN) {
-      try { ws.close(); } catch {}
-    }
-  }, DEFAULT_WS_CONNECT_TIMEOUT_MS);
+  const ready = new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (callback, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(connectTimeout);
+      callback(value);
+    };
+    const disconnect = (error, logLabel) => {
+      finish(reject, error);
+      handleSocketDisconnected(ws, socketEpoch).catch((disconnectError) => {
+        console.error(logLabel, disconnectError);
+      });
+    };
+    const connectTimeout = setTimeout(() => {
+      disconnect(
+        new Error(`NeoAgent browser connection timed out after ${DEFAULT_WS_CONNECT_TIMEOUT_MS}ms.`),
+        'NeoAgent connection timeout handling failed',
+      );
+    }, DEFAULT_WS_CONNECT_TIMEOUT_MS);
 
-  ws.addEventListener('open', () => {
-    if (socket !== ws) return;
-    clearTimeout(connectTimeout);
-    updateStatus('connected');
-  });
-  ws.addEventListener('close', () => {
-    clearTimeout(connectTimeout);
-    handleSocketDisconnected(ws).catch((error) => {
-      console.error('NeoAgent disconnect handling failed', error);
+    ws.addEventListener('open', () => {
+      if (socket !== ws || socketEpoch !== connectionEpoch) {
+        try { ws.close(); } catch {}
+        finish(reject, new Error('NeoAgent browser connection was superseded.'));
+        return;
+      }
+      reconnectAttempt = 0;
+      updateStatus('connected', socketEpoch).catch((error) => {
+        console.error('NeoAgent connected status update failed', error);
+      });
+      finish(resolve, { connected: true });
     });
-  });
-  ws.addEventListener('error', () => {
-    clearTimeout(connectTimeout);
-    handleSocketDisconnected(ws).catch((error) => {
-      console.error('NeoAgent socket error handling failed', error);
+    ws.addEventListener('close', () => {
+      disconnect(
+        new Error('NeoAgent browser connection closed before it was ready.'),
+        'NeoAgent disconnect handling failed',
+      );
     });
-  });
-  ws.addEventListener('message', (event) => {
-    handleSocketMessage(event.data).catch((error) => {
-      console.error('NeoAgent command handling failed', error);
+    ws.addEventListener('error', () => {
+      disconnect(
+        new Error('NeoAgent browser connection failed.'),
+        'NeoAgent socket error handling failed',
+      );
+    });
+    ws.addEventListener('message', (event) => {
+      handleSocketMessage(ws, event.data).catch((error) => {
+        console.error('NeoAgent command handling failed', error);
+      });
     });
   });
+  // The socket can fail while the storage status write is still pending. Attach
+  // a handler immediately; returning `ready` below still preserves rejection.
+  ready.catch(() => {});
 
-  return { connected: false };
+  await updateStatus('connecting', socketEpoch).catch((error) => {
+    console.error('NeoAgent connecting status update failed', error);
+  });
+  return ready;
 }
 
-async function handleSocketMessage(raw) {
+function connect() {
+  if (socket?.readyState === WebSocket.OPEN) {
+    return Promise.resolve({ connected: true });
+  }
+  if (connectPromise) return connectPromise;
+  const pending = connectOnce();
+  connectPromise = pending;
+  pending.then(
+    () => { if (connectPromise === pending) connectPromise = null; },
+    () => { if (connectPromise === pending) connectPromise = null; },
+  );
+  return pending;
+}
+
+function sendSocketMessage(ws, message) {
+  if (socket !== ws || ws.readyState !== WebSocket.OPEN) return false;
+  try {
+    ws.send(JSON.stringify(message));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function handleSocketMessage(ws, raw) {
   let message;
   try {
     message = JSON.parse(raw);
   } catch {
     return;
   }
-  if (!message || message.type !== 'command' || !message.id) {
+  if (!message || !message.id) {
     return;
   }
+  if (message.type === MESSAGE_TYPES.URL_VALIDATION_RESULT) {
+    const pending = pendingUrlValidations.get(String(message.id));
+    if (!pending || pending.socket !== ws) return;
+    pending.resolve(
+      Number(message.version) === EXTENSION_PROTOCOL_VERSION
+      && message.allowed === true,
+    );
+    return;
+  }
+  if (message.type !== MESSAGE_TYPES.COMMAND) return;
   if (message.version != null && Number(message.version) !== EXTENSION_PROTOCOL_VERSION) {
-    socket?.send(JSON.stringify({
-      type: 'result',
+    sendSocketMessage(ws, {
+      type: MESSAGE_TYPES.RESULT,
       version: EXTENSION_PROTOCOL_VERSION,
       id: message.id,
       ok: false,
       error: `Unsupported protocol version: ${message.version}`,
-    }));
+    });
     return;
   }
+
+  if (message.command === 'cancelCommand') {
+    const commandId = String(message.payload?.commandId || '');
+    const controller = activeCommandControllers.get(commandId);
+    controller?.abort(new Error('Browser command cancelled by NeoAgent.'));
+    sendSocketMessage(ws, {
+      type: MESSAGE_TYPES.RESULT,
+      version: EXTENSION_PROTOCOL_VERSION,
+      id: message.id,
+      ok: true,
+      result: { success: Boolean(controller), commandId },
+    });
+    return;
+  }
+
+  const controller = new AbortController();
+  activeCommandControllers.set(message.id, controller);
+  const execute = () => protocol.run(message.command, message.payload || {}, {
+    signal: controller.signal,
+  });
+  const queued = commandQueue.then(execute, execute);
+  commandQueue = queued.catch(() => {});
   try {
-    const result = await protocol.run(message.command, message.payload || {});
-    socket?.send(JSON.stringify({ type: 'result', version: EXTENSION_PROTOCOL_VERSION, id: message.id, ok: true, result }));
+    const result = await queued;
+    sendSocketMessage(ws, {
+      type: MESSAGE_TYPES.RESULT,
+      version: EXTENSION_PROTOCOL_VERSION,
+      id: message.id,
+      ok: true,
+      result,
+    });
   } catch (error) {
-    socket?.send(JSON.stringify({
-      type: 'result',
+    sendSocketMessage(ws, {
+      type: MESSAGE_TYPES.RESULT,
       version: EXTENSION_PROTOCOL_VERSION,
       id: message.id,
       ok: false,
       error: error?.message || String(error),
-    }));
+    });
+  } finally {
+    if (activeCommandControllers.get(message.id) === controller) {
+      activeCommandControllers.delete(message.id);
+    }
   }
 }
 
@@ -198,16 +407,25 @@ async function startPairing(serverUrl) {
   if (!normalized) throw new Error('NeoAgent server URL required.');
   const { extensionName } = await getStorage(['extensionName']);
   const nameToUse = String(extensionName || 'Chrome Extension').trim() || 'Chrome Extension';
-  const response = await fetchWithTimeout(`${normalized}/api/browser-extension/pairing/request`, {
+  const { response, payload } = await fetchJsonWithTimeout(`${normalized}/api/browser-extension/pairing/request`, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
     body: JSON.stringify({ extensionName: nameToUse }),
   });
-  const payload = await response.json().catch(() => ({}));
   if (!response.ok) throw new Error(payload.error || `Pairing failed: ${response.status}`);
+  if (!payload.pairingId || !payload.pairingSecret) {
+    throw new Error('NeoAgent server returned an incomplete pairing response.');
+  }
   const approvalUrl = String(payload.approvalUrl || '');
   const approvalParsed = (() => { try { return new URL(approvalUrl); } catch { return null; } })();
-  if (!approvalParsed || !['http:', 'https:'].includes(approvalParsed.protocol)) {
+  const serverParsed = new URL(normalized);
+  if (
+    !approvalParsed
+    || !['http:', 'https:'].includes(approvalParsed.protocol)
+    || approvalParsed.origin !== serverParsed.origin
+    || approvalParsed.username
+    || approvalParsed.password
+  ) {
     throw new Error('Invalid approval URL returned by server.');
   }
   await setStorage({
@@ -226,14 +444,17 @@ async function claimPairing() {
   if (!serverUrl || !pairingId || !pairingSecret) {
     throw new Error('No pending pairing request.');
   }
+  const normalizedServerUrl = normalizeServerUrl(serverUrl);
   const nameToUse = String(extensionName || 'Chrome Extension').trim() || 'Chrome Extension';
-  const response = await fetchWithTimeout(`${serverUrl}/api/browser-extension/pairing/${encodeURIComponent(pairingId)}/claim`, {
+  const { response, payload } = await fetchJsonWithTimeout(`${normalizedServerUrl}/api/browser-extension/pairing/${encodeURIComponent(pairingId)}/claim`, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
     body: JSON.stringify({ pairingSecret, extensionName: nameToUse }),
   });
-  const payload = await response.json().catch(() => ({}));
   if (!response.ok) throw new Error(payload.error || `Claim failed: ${response.status}`);
+  if (!payload.token || !payload.tokenId) {
+    throw new Error('NeoAgent server returned an incomplete pairing claim.');
+  }
   await setStorage({
     token: payload.token,
     tokenId: payload.tokenId,
@@ -246,20 +467,29 @@ async function claimPairing() {
 
 async function disconnect() {
   clearReconnectTimer();
-  suppressSocketClose = true;
-  if (socket) {
-    try { socket.close(); } catch {}
-  }
+  reconnectAttempt = 0;
+  const disconnectedEpoch = ++connectionEpoch;
+  connectPromise = null;
+  const previousSocket = socket;
   socket = null;
+  if (previousSocket) {
+    try { previousSocket.close(); } catch {}
+  }
+  for (const controller of activeCommandControllers.values()) {
+    controller.abort(new Error('NeoAgent browser connection was disconnected.'));
+  }
+  activeCommandControllers.clear();
+  rejectPendingUrlValidations(new Error('NeoAgent browser connection was disconnected.'));
   await removeStorage(['token', 'tokenId', 'pairingId', 'pairingSecret', 'approvalUrl']);
-  await updateStatus('not_paired');
+  await updateStatus('not_paired', disconnectedEpoch);
 }
 
 async function checkForUpdates(preferredServerUrl) {
   const serverUrl = await resolveServerUrl(preferredServerUrl);
   if (!serverUrl) throw new Error('NeoAgent server URL required.');
-  const response = await fetchWithTimeout(`${serverUrl}/api/browser-extension/latest`);
-  const latest = await response.json().catch(() => ({}));
+  const { response, payload: latest } = await fetchJsonWithTimeout(
+    `${serverUrl}/api/browser-extension/latest`,
+  );
   if (!response.ok) throw new Error(latest.error || `Update check failed: ${response.status}`);
   const manifest = chrome.runtime.getManifest();
   const currentVersion = manifest.version;

package/extensions/chrome-browser/http.mjs

@@ -0,0 +1,136 @@
+export const DEFAULT_EXTENSION_HTTP_TIMEOUT_MS = 10000;
+export const DEFAULT_MAX_SERVER_RESPONSE_BYTES = 1024 * 1024;
+
+function abortError(signal, fallback = 'NeoAgent server request was aborted.') {
+  if (signal?.reason instanceof Error) return signal.reason;
+  const error = new Error(String(signal?.reason || fallback));
+  error.name = 'AbortError';
+  error.code = 'ABORT_ERR';
+  return error;
+}
+
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw abortError(signal);
+}
+
+function responseTooLargeError(maxResponseBytes) {
+  const error = new Error(
+    `NeoAgent server response exceeded the ${maxResponseBytes}-byte safety limit.`,
+  );
+  error.code = 'EXTENSION_RESPONSE_TOO_LARGE';
+  return error;
+}
+
+function waitForAbortable(promise, signal) {
+  throwIfAborted(signal);
+  if (!signal) return Promise.resolve(promise);
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(abortError(signal));
+    signal.addEventListener('abort', onAbort, { once: true });
+    Promise.resolve(promise).then(resolve, reject).finally(() => {
+      signal.removeEventListener('abort', onAbort);
+    });
+  });
+}
+
+export async function readJsonResponse(response, options = {}) {
+  const signal = options.signal || null;
+  const maxResponseBytes = Math.max(
+    1,
+    Number(options.maxResponseBytes) || DEFAULT_MAX_SERVER_RESPONSE_BYTES,
+  );
+  throwIfAborted(signal);
+  const contentLength = Number(response?.headers?.get?.('content-length'));
+  if (Number.isFinite(contentLength) && contentLength > maxResponseBytes) {
+    await Promise.resolve(response?.body?.cancel?.()).catch(() => {});
+    throw responseTooLargeError(maxResponseBytes);
+  }
+
+  const reader = response?.body?.getReader?.();
+  let text = '';
+  if (!reader) {
+    text = await waitForAbortable(response.text(), signal);
+    if (new TextEncoder().encode(text).byteLength > maxResponseBytes) {
+      throw responseTooLargeError(maxResponseBytes);
+    }
+  } else {
+    const decoder = new TextDecoder();
+    let totalBytes = 0;
+    const cancelReader = () => {
+      try {
+        Promise.resolve(reader.cancel(signal?.reason)).catch(() => {});
+      } catch {}
+    };
+    signal?.addEventListener('abort', cancelReader, { once: true });
+    try {
+      while (true) {
+        const { done, value } = await waitForAbortable(reader.read(), signal);
+        if (done) break;
+        const chunk = value instanceof Uint8Array ? value : new Uint8Array(value || []);
+        totalBytes += chunk.byteLength;
+        if (totalBytes > maxResponseBytes) {
+          await Promise.resolve(reader.cancel()).catch(() => {});
+          throw responseTooLargeError(maxResponseBytes);
+        }
+        text += decoder.decode(chunk, { stream: true });
+      }
+      text += decoder.decode();
+    } finally {
+      signal?.removeEventListener('abort', cancelReader);
+      reader.releaseLock?.();
+    }
+  }
+
+  if (!text.trim()) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error('NeoAgent server returned invalid JSON.');
+  }
+}
+
+export async function fetchJsonWithTimeout(url, options = {}, config = {}) {
+  const timeoutMs = Math.max(
+    1,
+    Number(config.timeoutMs) || DEFAULT_EXTENSION_HTTP_TIMEOUT_MS,
+  );
+  const maxResponseBytes = Math.max(
+    1,
+    Number(config.maxResponseBytes) || DEFAULT_MAX_SERVER_RESPONSE_BYTES,
+  );
+  const fetchImpl = typeof config.fetchImpl === 'function' ? config.fetchImpl : fetch;
+  const callerSignal = options.signal || null;
+  throwIfAborted(callerSignal);
+
+  const controller = new AbortController();
+  const onCallerAbort = () => controller.abort(callerSignal.reason);
+  callerSignal?.addEventListener('abort', onCallerAbort, { once: true });
+  const timer = setTimeout(() => {
+    const error = new Error(`NeoAgent server request timed out after ${timeoutMs}ms.`);
+    error.code = 'EXTENSION_HTTP_TIMEOUT';
+    controller.abort(error);
+  }, timeoutMs);
+
+  const { signal: _signal, ...fetchOptions } = options;
+  try {
+    const response = await waitForAbortable(
+      fetchImpl(url, {
+        ...fetchOptions,
+        signal: controller.signal,
+      }),
+      controller.signal,
+    );
+    const payload = await readJsonResponse(response, {
+      signal: controller.signal,
+      maxResponseBytes,
+    });
+    return { response, payload };
+  } catch (error) {
+    if (callerSignal?.aborted) throw abortError(callerSignal);
+    if (controller.signal.aborted) throw abortError(controller.signal);
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    callerSignal?.removeEventListener('abort', onCallerAbort);
+  }
+}