@axhub/genie 0.1.8 → 0.2.0

package/server/external-agent/ws.js

@@ -0,0 +1,1526 @@
+import { WebSocket } from 'ws';
+
+import { SessionEventMirrorWriter } from '../session-core/runtimeWriter.js';
+import { abortAgentSessionWithWriter } from '../session-core/abortSession.js';
+import {
+  AgentSessionAbortedError,
+  buildSessionNavigation,
+  normalizeExternalAgentAbortRequest,
+  normalizeExternalAgentRunRequest,
+  runExternalAgentRequest
+} from './service.js';
+import {
+  buildSessionRuntimeSnapshot,
+  createSessionRuntimeSubscriptionKey,
+  subscribeToSessionRuntimeStateChanges
+} from '../session-core/runtimeState.js';
+import { SUPPORTED_PROVIDERS } from '../../shared/conversationEvents.js';
+import { materializeDataUrlImageToFile, sanitizeFileName } from '../utils/agentImages.js';
+
+const INTEGRATION_ROLE_FRONTEND_PAGE = 'frontend-page';
+const INTEGRATION_ROLE_EXTERNAL_CLIENT = 'external-client';
+const INTEGRATION_REQUEST_TTL_MS = 10 * 60 * 1000;
+const INTEGRATION_PING_TIMEOUT_MS = 1500;
+const INTEGRATION_EDITOR_REQUEST_TIMEOUT_MS = 15000;
+const INTEGRATION_EDITOR_TYPE_PREFIX = 'integration.editor.';
+const INTEGRATION_EDITOR_RESULT_SUFFIX = '.result';
+const INTEGRATION_EDITOR_CAPABILITIES = Object.freeze({
+  'integration.editor.snapshot.get': 'editor.snapshot',
+  'integration.editor.nodes.list': 'editor.nodes.list',
+  'integration.editor.node.screenshot.get': 'editor.node.screenshot',
+  'integration.editor.context-images.get': 'editor.context-images',
+  'integration.editor.editing.set': 'editor.editing.set'
+});
+
+const integrationConnections = new Map();
+const pendingIntegrationRequests = new Map();
+const pendingIntegrationPings = new Map();
+const sessionStateSubscriptionsByWs = new Map();
+const sessionStateSubscribersByKey = new Map();
+
+function sendJson(ws, payload) {
+  if (ws.readyState === WebSocket.OPEN) {
+    ws.send(JSON.stringify(payload));
+  }
+}
+
+function normalizeNonEmptyString(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const normalized = value.trim();
+  return normalized ? normalized : null;
+}
+
+function createRuntimeId(prefix = 'integration') {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return `${prefix}_${crypto.randomUUID()}`;
+  }
+
+  return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeOptionalString(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  return value.trim();
+}
+
+function normalizePositiveInteger(value) {
+  const next = Number(value);
+  if (!Number.isInteger(next) || next <= 0) {
+    return null;
+  }
+  return next;
+}
+
+function isEditorResultMessageType(type) {
+  return typeof type === 'string'
+    && type.startsWith(INTEGRATION_EDITOR_TYPE_PREFIX)
+    && type.endsWith(INTEGRATION_EDITOR_RESULT_SUFFIX);
+}
+
+function getRequestId(data) {
+  return normalizeNonEmptyString(data?.requestId) || null;
+}
+
+function sendRequestError(ws, { requestId, provider, sessionId = null, error, statusCode = 400 }) {
+  sendJson(ws, {
+    type: 'agent.error',
+    requestId: requestId || null,
+    provider: provider || null,
+    sessionId,
+    error,
+    statusCode
+  });
+}
+
+function sendIntegrationError(ws, { requestId, code, message }) {
+  sendJson(ws, {
+    type: 'integration.error',
+    requestId: requestId || null,
+    payload: {
+      code,
+      message
+    }
+  });
+}
+
+function createAgentStateError(ws, { requestId, provider, sessionId, error, statusCode = 400 }) {
+  sendRequestError(ws, {
+    requestId,
+    provider,
+    sessionId,
+    error,
+    statusCode
+  });
+}
+
+function normalizeAgentStatePayload(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw Object.assign(new Error('payload must be an object'), { statusCode: 400 });
+  }
+
+  const sessionId = normalizeNonEmptyString(payload.sessionId);
+  if (!sessionId) {
+    throw Object.assign(new Error('sessionId is required'), { statusCode: 400 });
+  }
+
+  const provider = normalizeNonEmptyString(payload.provider)?.toLowerCase() || null;
+  if (!provider) {
+    throw Object.assign(new Error('provider is required'), { statusCode: 400 });
+  }
+
+  if (!SUPPORTED_PROVIDERS.includes(provider)) {
+    throw Object.assign(new Error(`provider must be one of: ${SUPPORTED_PROVIDERS.join(', ')}`), { statusCode: 400 });
+  }
+
+  return {
+    sessionId,
+    provider
+  };
+}
+
+function addSessionStateSubscription(ws, subscriptionKey) {
+  if (!subscriptionKey) {
+    return;
+  }
+
+  if (!sessionStateSubscriptionsByWs.has(ws)) {
+    sessionStateSubscriptionsByWs.set(ws, new Set());
+  }
+  sessionStateSubscriptionsByWs.get(ws).add(subscriptionKey);
+
+  if (!sessionStateSubscribersByKey.has(subscriptionKey)) {
+    sessionStateSubscribersByKey.set(subscriptionKey, new Set());
+  }
+  sessionStateSubscribersByKey.get(subscriptionKey).add(ws);
+}
+
+function removeSessionStateSubscriptionsForWs(ws) {
+  const subscriptionKeys = sessionStateSubscriptionsByWs.get(ws);
+  if (!subscriptionKeys) {
+    return;
+  }
+
+  subscriptionKeys.forEach((subscriptionKey) => {
+    const subscribers = sessionStateSubscribersByKey.get(subscriptionKey);
+    if (!subscribers) {
+      return;
+    }
+
+    subscribers.delete(ws);
+    if (subscribers.size === 0) {
+      sessionStateSubscribersByKey.delete(subscriptionKey);
+    }
+  });
+
+  sessionStateSubscriptionsByWs.delete(ws);
+}
+
+async function handleAgentStateQuery(ws, data) {
+  const requestId = getRequestId(data);
+
+  let normalized = null;
+  try {
+    normalized = normalizeAgentStatePayload(data?.payload);
+  } catch (error) {
+    createAgentStateError(ws, {
+      requestId,
+      provider: data?.payload?.provider || null,
+      sessionId: data?.payload?.sessionId || null,
+      error: error.message,
+      statusCode: error.statusCode || 400
+    });
+    return;
+  }
+
+  const snapshot = await buildSessionRuntimeSnapshot(normalized.provider, normalized.sessionId);
+  if (!snapshot) {
+    createAgentStateError(ws, {
+      requestId,
+      provider: normalized.provider,
+      sessionId: normalized.sessionId,
+      error: 'Session not found for provider',
+      statusCode: 404
+    });
+    return;
+  }
+
+  sendJson(ws, {
+    type: 'agent.state.snapshot',
+    requestId,
+    payload: {
+      sessionId: snapshot.sessionId,
+      provider: snapshot.provider,
+      phase: snapshot.phase,
+      isLoading: snapshot.isLoading,
+      canAbortSession: snapshot.canAbortSession,
+      hasPendingApproval: snapshot.hasPendingApproval,
+      updatedAt: snapshot.updatedAt
+    }
+  });
+}
+
+async function handleAgentStateSubscribe(ws, data) {
+  const requestId = getRequestId(data);
+
+  let normalized = null;
+  try {
+    normalized = normalizeAgentStatePayload(data?.payload);
+  } catch (error) {
+    createAgentStateError(ws, {
+      requestId,
+      provider: data?.payload?.provider || null,
+      sessionId: data?.payload?.sessionId || null,
+      error: error.message,
+      statusCode: error.statusCode || 400
+    });
+    return;
+  }
+
+  const snapshot = await buildSessionRuntimeSnapshot(normalized.provider, normalized.sessionId);
+  if (!snapshot) {
+    createAgentStateError(ws, {
+      requestId,
+      provider: normalized.provider,
+      sessionId: normalized.sessionId,
+      error: 'Session not found for provider',
+      statusCode: 404
+    });
+    return;
+  }
+
+  const subscriptionKey = createSessionRuntimeSubscriptionKey(normalized.provider, normalized.sessionId);
+  addSessionStateSubscription(ws, subscriptionKey);
+
+  sendJson(ws, {
+    type: 'agent.state.subscribed',
+    requestId,
+    payload: {
+      sessionId: snapshot.sessionId,
+      provider: snapshot.provider,
+      subscriptionKey
+    }
+  });
+}
+
+function cleanupExpiredPendingIntegrationRequests() {
+  const now = Date.now();
+  for (const [requestId, entry] of pendingIntegrationRequests.entries()) {
+    if (!entry?.createdAt || now - entry.createdAt > INTEGRATION_REQUEST_TTL_MS) {
+      if (entry?.timeoutId) {
+        clearTimeout(entry.timeoutId);
+      }
+      pendingIntegrationRequests.delete(requestId);
+    }
+  }
+}
+
+function clearPendingIntegrationRequest(requestId) {
+  const entry = pendingIntegrationRequests.get(requestId);
+  if (entry?.timeoutId) {
+    clearTimeout(entry.timeoutId);
+  }
+  pendingIntegrationRequests.delete(requestId);
+  return entry || null;
+}
+
+function storePendingIntegrationRequest(requestId, originWs, options = {}) {
+  if (!requestId) {
+    return;
+  }
+
+  cleanupExpiredPendingIntegrationRequests();
+  const timeoutMs = normalizePositiveInteger(options.timeoutMs) || INTEGRATION_EDITOR_REQUEST_TIMEOUT_MS;
+  const nextEntry = {
+    originWs,
+    createdAt: Date.now(),
+    timeoutId: null,
+    awaitResult: options.awaitResult === true,
+    requestType: options.requestType || null,
+    requestPayload: isPlainObject(options.requestPayload) ? { ...options.requestPayload } : null
+  };
+  nextEntry.timeoutId = setTimeout(() => {
+    const current = pendingIntegrationRequests.get(requestId);
+    if (current !== nextEntry) {
+      return;
+    }
+    pendingIntegrationRequests.delete(requestId);
+    if (!originWs || originWs.readyState !== WebSocket.OPEN) {
+      return;
+    }
+    sendIntegrationError(originWs, {
+      requestId,
+      code: 'REQUEST_TIMEOUT',
+      message: `Timed out waiting for response to ${options.requestType || 'integration request'}`
+    });
+  }, timeoutMs);
+  pendingIntegrationRequests.set(requestId, nextEntry);
+}
+
+function removePendingIntegrationRequestsForWs(ws) {
+  for (const [requestId, entry] of pendingIntegrationRequests.entries()) {
+    if (entry?.originWs === ws) {
+      clearPendingIntegrationRequest(requestId);
+    }
+  }
+}
+
+function touchIntegrationConnection(ws) {
+  const existing = integrationConnections.get(ws);
+  if (!existing) {
+    return null;
+  }
+
+  const updated = {
+    ...existing,
+    lastSeenAt: new Date().toISOString()
+  };
+  integrationConnections.set(ws, updated);
+  return updated;
+}
+
+function listIntegrationConnections({ role = null, channel = null, clientId = null } = {}) {
+  return Array.from(integrationConnections.values()).filter((meta) => {
+    if (role && meta.role !== role) {
+      return false;
+    }
+
+    if (channel && meta.channel !== channel) {
+      return false;
+    }
+
+    if (clientId && meta.clientId !== clientId) {
+      return false;
+    }
+
+    return true;
+  });
+}
+
+function buildEditorClientSummary(meta) {
+  return {
+    channel: meta.channel,
+    clientId: meta.clientId,
+    sessionId: meta.sessionId || null,
+    pageUrl: meta.pageUrl || null,
+    lastSeenAt: meta.lastSeenAt || null,
+    connectedAt: meta.connectedAt || null,
+    connectionId: meta.connectionId || null,
+    capabilities: Array.isArray(meta.capabilities) ? meta.capabilities.slice() : []
+  };
+}
+
+function sanitizeFallbackBaseName(value, fallback = 'image') {
+  return sanitizeFileName(String(value || '').trim()) || fallback;
+}
+
+async function materializeEditorScreenshotPayload(payload, pendingRequest) {
+  if (!isPlainObject(payload)) {
+    throw Object.assign(new Error('editor screenshot result payload must be an object'), {
+      code: 'INVALID_PAYLOAD'
+    });
+  }
+
+  if (typeof payload.absolutePath === 'string' && payload.absolutePath.trim()) {
+    return payload;
+  }
+
+  const imageSource = isPlainObject(payload.image) ? payload.image : payload;
+  if (typeof imageSource.data !== 'string' || !imageSource.data.trim()) {
+    throw Object.assign(new Error('editor screenshot result must include image.data as a data URL'), {
+      code: 'INVALID_PAYLOAD'
+    });
+  }
+
+  const outputDir = normalizeOptionalString(pendingRequest?.requestPayload?.downloadPath) || process.cwd();
+  const elementKey = normalizeOptionalString(payload.elementKey)
+    || normalizeOptionalString(pendingRequest?.requestPayload?.elementKey)
+    || 'node-screenshot';
+  const fileMeta = await materializeDataUrlImageToFile(imageSource, outputDir, {
+    label: 'editor screenshot',
+    fallbackBaseName: sanitizeFallbackBaseName(elementKey, 'node-screenshot')
+  });
+
+  return {
+    ...payload,
+    elementKey,
+    absolutePath: fileMeta.absolutePath,
+    mimeType: fileMeta.mimeType,
+    width: normalizePositiveInteger(payload.width) || normalizePositiveInteger(imageSource.width) || null,
+    height: normalizePositiveInteger(payload.height) || normalizePositiveInteger(imageSource.height) || null,
+    size: fileMeta.size
+  };
+}
+
+async function materializeEditorContextImagesPayload(payload, pendingRequest) {
+  if (!isPlainObject(payload) || !Array.isArray(payload.items)) {
+    throw Object.assign(new Error('editor context-images result payload must include items[]'), {
+      code: 'INVALID_PAYLOAD'
+    });
+  }
+
+  if (payload.items.every((item) => typeof item?.absolutePath === 'string' && item.absolutePath.trim())) {
+    return payload;
+  }
+
+  const outputDir = normalizeOptionalString(pendingRequest?.requestPayload?.downloadPath) || process.cwd();
+  const nextItems = [];
+
+  for (const [index, item] of payload.items.entries()) {
+    if (!isPlainObject(item)) {
+      throw Object.assign(new Error(`editor context image item ${index} must be an object`), {
+        code: 'INVALID_PAYLOAD'
+      });
+    }
+
+    const fileMeta = await materializeDataUrlImageToFile(item, outputDir, {
+      label: `editor context image item ${index}`,
+      fallbackBaseName: sanitizeFallbackBaseName(item.name || item.id || `context-image-${index + 1}`, `context-image-${index + 1}`)
+    });
+
+    nextItems.push({
+      ...item,
+      id: normalizeOptionalString(item.id) || `context-image-${index + 1}`,
+      name: normalizeOptionalString(item.name) || sanitizeFallbackBaseName(item.id || `context-image-${index + 1}`, `context-image-${index + 1}`),
+      absolutePath: fileMeta.absolutePath,
+      mimeType: fileMeta.mimeType,
+      size: fileMeta.size,
+      createdAt: Number.isFinite(Number(item.createdAt)) ? Number(item.createdAt) : Date.now(),
+      source: normalizeOptionalString(item.source) || 'prompt-context'
+    });
+  }
+
+  return {
+    ...payload,
+    items: nextItems
+  };
+}
+
+async function maybeMaterializeEditorResult(data, pendingRequest) {
+  if (!pendingRequest?.requestType || !isPlainObject(data)) {
+    return data;
+  }
+
+  if (
+    pendingRequest.requestType === 'integration.editor.node.screenshot.get'
+    && data.type === 'integration.editor.node.screenshot.result'
+  ) {
+    return {
+      ...data,
+      payload: await materializeEditorScreenshotPayload(data.payload, pendingRequest)
+    };
+  }
+
+  if (
+    pendingRequest.requestType === 'integration.editor.context-images.get'
+    && data.type === 'integration.editor.context-images.result'
+  ) {
+    return {
+      ...data,
+      payload: await materializeEditorContextImagesPayload(data.payload, pendingRequest)
+    };
+  }
+
+  return data;
+}
+
+function buildPresenceEventPayload(meta, event) {
+  return {
+    channel: meta.channel,
+    event,
+    clientId: meta.clientId,
+    sessionId: meta.sessionId || null,
+    pageUrl: meta.pageUrl || null,
+    timestamp: new Date().toISOString()
+  };
+}
+
+function broadcastPresenceEvent(meta, event) {
+  if (!meta?.channel) {
+    return;
+  }
+
+  const payload = buildPresenceEventPayload(meta, event);
+  for (const clientMeta of listIntegrationConnections({
+    role: INTEGRATION_ROLE_EXTERNAL_CLIENT,
+    channel: meta.channel
+  })) {
+    sendJson(clientMeta.ws, {
+      type: 'integration.presence',
+      requestId: createRuntimeId('presence'),
+      payload
+    });
+  }
+}
+
+function unregisterIntegrationConnection(ws) {
+  const existing = integrationConnections.get(ws);
+  removeSessionStateSubscriptionsForWs(ws);
+  if (!existing) {
+    removePendingIntegrationRequestsForWs(ws);
+    removePendingIntegrationPingsForWs(ws);
+    return;
+  }
+
+  integrationConnections.delete(ws);
+  removePendingIntegrationRequestsForWs(ws);
+  removePendingIntegrationPingsForWs(ws);
+
+  if (existing.role === INTEGRATION_ROLE_FRONTEND_PAGE) {
+    broadcastPresenceEvent(existing, 'frontend-offline');
+  }
+}
+
+function validateIntegrationConnectPayload(payload) {
+  if (!payload || typeof payload !== 'object') {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'payload must be an object' };
+  }
+
+  const role = normalizeNonEmptyString(payload.role);
+  if (role !== INTEGRATION_ROLE_FRONTEND_PAGE && role !== INTEGRATION_ROLE_EXTERNAL_CLIENT) {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'role must be frontend-page or external-client' };
+  }
+
+  const channel = normalizeNonEmptyString(payload.channel);
+  if (!channel) {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'channel is required' };
+  }
+
+  const clientId = normalizeNonEmptyString(payload.clientId);
+  if (!clientId) {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'clientId is required' };
+  }
+
+  return {
+    ok: true,
+    payload: {
+      role,
+      channel,
+      clientId,
+      pageUrl: normalizeNonEmptyString(payload.pageUrl) || null,
+      sessionId: normalizeNonEmptyString(payload.sessionId) || null,
+      capabilities: Array.isArray(payload.capabilities)
+        ? payload.capabilities.filter((value) => typeof value === 'string' && value.trim())
+        : []
+    }
+  };
+}
+
+function handleIntegrationConnect(ws, data) {
+  const requestId = getRequestId(data);
+  const validation = validateIntegrationConnectPayload(data?.payload);
+  if (!validation.ok) {
+    sendIntegrationError(ws, {
+      requestId,
+      code: validation.code,
+      message: validation.message
+    });
+    return;
+  }
+
+  const now = new Date().toISOString();
+  const nextMeta = {
+    ...validation.payload,
+    ws,
+    connectionId: integrationConnections.get(ws)?.connectionId || createRuntimeId('conn'),
+    connectedAt: integrationConnections.get(ws)?.connectedAt || now,
+    lastSeenAt: now
+  };
+
+  const previous = integrationConnections.get(ws) || null;
+  integrationConnections.set(ws, nextMeta);
+
+  sendJson(ws, {
+    type: 'integration.connected',
+    requestId,
+    payload: {
+      connectionId: nextMeta.connectionId,
+      role: nextMeta.role,
+      channel: nextMeta.channel,
+      clientId: nextMeta.clientId,
+      serverTime: now
+    }
+  });
+
+  if (previous?.role === INTEGRATION_ROLE_FRONTEND_PAGE) {
+    const previousKey = `${previous.channel}::${previous.clientId}`;
+    const nextKey = `${nextMeta.channel}::${nextMeta.clientId}`;
+    if (previousKey !== nextKey) {
+      broadcastPresenceEvent(previous, 'frontend-offline');
+    }
+  }
+
+  if (nextMeta.role === INTEGRATION_ROLE_FRONTEND_PAGE) {
+    const previousKey = previous ? `${previous.channel}::${previous.clientId}::${previous.role}` : null;
+    const nextKey = `${nextMeta.channel}::${nextMeta.clientId}::${nextMeta.role}`;
+    if (previousKey !== nextKey) {
+      broadcastPresenceEvent(nextMeta, 'frontend-online');
+    }
+  }
+}
+
+function buildFrontendPresence(channel, targetClientId = null) {
+  const clients = listIntegrationConnections({
+    role: INTEGRATION_ROLE_FRONTEND_PAGE,
+    channel,
+    clientId: targetClientId
+  }).map((meta) => ({
+    clientId: meta.clientId,
+    lastSeenAt: meta.lastSeenAt,
+    pageUrl: meta.pageUrl || null,
+    sessionId: meta.sessionId || null
+  }));
+
+  return {
+    connected: clients.length > 0,
+    count: clients.length,
+    clients
+  };
+}
+
+function validateIntegrationPingPayload(payload) {
+  if (!payload || typeof payload !== 'object') {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'payload must be an object' };
+  }
+
+  const channel = normalizeNonEmptyString(payload.channel);
+  if (!channel) {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'channel is required' };
+  }
+
+  return {
+    ok: true,
+    payload: {
+      channel,
+      targetClientId: normalizeNonEmptyString(payload.targetClientId)
+    }
+  };
+}
+
+function buildResponsiveFrontendPresence(responses) {
+  const clients = Array.from(responses.values());
+  return {
+    connected: clients.length > 0,
+    count: clients.length,
+    clients
+  };
+}
+
+function finalizePendingIntegrationPing(probeRequestId) {
+  const pendingPing = pendingIntegrationPings.get(probeRequestId);
+  if (!pendingPing) {
+    return false;
+  }
+
+  pendingIntegrationPings.delete(probeRequestId);
+  if (pendingPing.timeoutId) {
+    clearTimeout(pendingPing.timeoutId);
+  }
+
+  if (!pendingPing.originWs || pendingPing.originWs.readyState !== WebSocket.OPEN) {
+    return false;
+  }
+
+  sendJson(pendingPing.originWs, {
+    type: 'integration.pong',
+    requestId: pendingPing.originRequestId,
+    payload: {
+      server: {
+        status: 'ok',
+        started: true
+      },
+      frontend: buildResponsiveFrontendPresence(pendingPing.responses)
+    }
+  });
+
+  return true;
+}
+
+function removePendingIntegrationPingsForWs(ws) {
+  for (const [probeRequestId, entry] of pendingIntegrationPings.entries()) {
+    if (entry?.originWs === ws) {
+      if (entry.timeoutId) {
+        clearTimeout(entry.timeoutId);
+      }
+      pendingIntegrationPings.delete(probeRequestId);
+    }
+  }
+}
+
+function handleIntegrationPing(ws, data) {
+  const requestId = getRequestId(data);
+  const validation = validateIntegrationPingPayload(data?.payload);
+  if (!validation.ok) {
+    sendIntegrationError(ws, {
+      requestId,
+      code: validation.code,
+      message: validation.message
+    });
+    return;
+  }
+
+  const { channel, targetClientId } = validation.payload;
+  const targets = getTargetFrontendConnections(channel, targetClientId);
+  if (targets.length === 0) {
+    sendJson(ws, {
+      type: 'integration.pong',
+      requestId,
+      payload: {
+        server: {
+          status: 'ok',
+          started: true
+        },
+        frontend: buildFrontendPresence(channel, targetClientId)
+      }
+    });
+    return;
+  }
+
+  const probeRequestId = createRuntimeId('integration_probe');
+  const pendingPing = {
+    originWs: ws,
+    originRequestId: requestId,
+    channel,
+    targetClientId,
+    responses: new Map(),
+    timeoutId: null
+  };
+
+  pendingPing.timeoutId = setTimeout(() => {
+    finalizePendingIntegrationPing(probeRequestId);
+  }, INTEGRATION_PING_TIMEOUT_MS);
+  pendingIntegrationPings.set(probeRequestId, pendingPing);
+
+  for (const target of targets) {
+    sendJson(target.ws, {
+      type: 'integration.ping',
+      requestId: probeRequestId,
+      payload: {
+        channel,
+        targetClientId: targetClientId || null
+      }
+    });
+  }
+}
+
+function handleIntegrationProbeResponse(ws, data) {
+  const probeRequestId = getRequestId(data);
+  if (!probeRequestId) {
+    return false;
+  }
+
+  const pendingPing = pendingIntegrationPings.get(probeRequestId);
+  if (!pendingPing) {
+    return false;
+  }
+
+  const meta = integrationConnections.get(ws);
+  if (!meta || meta.role !== INTEGRATION_ROLE_FRONTEND_PAGE) {
+    return false;
+  }
+
+  if (data?.type === 'integration.ack') {
+    pendingPing.responses.set(meta.clientId, {
+      clientId: meta.clientId,
+      lastSeenAt: new Date().toISOString(),
+      pageUrl: normalizeNonEmptyString(data?.payload?.pageUrl) || meta.pageUrl || null,
+      sessionId: normalizeNonEmptyString(data?.payload?.sessionId) || meta.sessionId || null
+    });
+
+    if (pendingPing.targetClientId) {
+      finalizePendingIntegrationPing(probeRequestId);
+    }
+    return true;
+  }
+
+  if (data?.type === 'integration.error') {
+    return true;
+  }
+
+  return false;
+}
+
+function getTargetFrontendConnections(channel, targetClientId) {
+  return listIntegrationConnections({
+    role: INTEGRATION_ROLE_FRONTEND_PAGE,
+    channel,
+    clientId: targetClientId
+  });
+}
+
+function validateEditorClientsListPayload(payload) {
+  if (payload === undefined || payload === null) {
+    return {
+      ok: true,
+      payload: {
+        channel: null,
+        clientId: null
+      }
+    };
+  }
+
+  if (!isPlainObject(payload)) {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'payload must be an object' };
+  }
+
+  return {
+    ok: true,
+    payload: {
+      channel: normalizeNonEmptyString(payload.channel),
+      clientId: normalizeNonEmptyString(payload.clientId)
+    }
+  };
+}
+
+function validateEditorTargetPayload(payload, extras = {}) {
+  if (!isPlainObject(payload)) {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'payload must be an object' };
+  }
+
+  const channel = normalizeNonEmptyString(payload.channel);
+  if (!channel) {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'channel is required' };
+  }
+
+  const targetClientId = normalizeNonEmptyString(payload.targetClientId);
+  if (!targetClientId) {
+    return { ok: false, code: 'INVALID_TARGET', message: 'targetClientId is required' };
+  }
+
+  return {
+    ok: true,
+    payload: {
+      channel,
+      targetClientId,
+      ...extras
+    }
+  };
+}
+
+function validateEditorSnapshotPayload(payload) {
+  return validateEditorTargetPayload(payload);
+}
+
+function validateEditorNodesListPayload(payload) {
+  if (!isPlainObject(payload)) {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'payload must be an object' };
+  }
+
+  const base = validateEditorTargetPayload(payload, {});
+  if (!base.ok) {
+    return base;
+  }
+
+  let status = [];
+  if (Array.isArray(payload.status)) {
+    status = payload.status
+      .map((value) => normalizeNonEmptyString(value))
+      .filter(Boolean);
+  } else if (typeof payload.status === 'string') {
+    status = payload.status
+      .split(',')
+      .map((value) => normalizeNonEmptyString(value))
+      .filter(Boolean);
+  } else if (payload.status !== undefined && payload.status !== null) {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'status must be a string or string array' };
+  }
+
+  const elementKey = normalizeNonEmptyString(payload.elementKey);
+  const limit = payload.limit === undefined ? null : normalizePositiveInteger(payload.limit);
+  if (payload.limit !== undefined && !limit) {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'limit must be a positive integer' };
+  }
+
+  return {
+    ok: true,
+    payload: {
+      ...base.payload,
+      status,
+      elementKey,
+      limit
+    }
+  };
+}
+
+function validateEditorNodeScreenshotPayload(payload) {
+  if (!isPlainObject(payload)) {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'payload must be an object' };
+  }
+
+  const elementKey = normalizeNonEmptyString(payload.elementKey);
+  if (!elementKey) {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'elementKey is required' };
+  }
+
+  const base = validateEditorTargetPayload(payload, {
+    elementKey,
+    downloadPath: normalizeOptionalString(payload.downloadPath) || null
+  });
+  return base;
+}
+
+function validateEditorContextImagesPayload(payload) {
+  if (payload !== undefined && payload !== null && !isPlainObject(payload)) {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'payload must be an object' };
+  }
+
+  return validateEditorTargetPayload(payload || {}, {
+    downloadPath: normalizeOptionalString(payload?.downloadPath) || null
+  });
+}
+
+function validateEditorEditingSetPayload(payload) {
+  if (!isPlainObject(payload)) {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'payload must be an object' };
+  }
+
+  const elementKey = normalizeNonEmptyString(payload.elementKey);
+  if (!elementKey) {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'elementKey is required' };
+  }
+
+  const state = normalizeNonEmptyString(payload.state);
+  if (state !== 'editing' && state !== 'idle') {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'state must be editing or idle' };
+  }
+
+  return validateEditorTargetPayload(payload, {
+    elementKey,
+    state,
+    taskRef: isPlainObject(payload.taskRef) ? payload.taskRef : null
+  });
+}
+
+function handleEditorClientsList(ws, data) {
+  const requestId = getRequestId(data);
+  const validation = validateEditorClientsListPayload(data?.payload);
+  if (!validation.ok) {
+    sendIntegrationError(ws, {
+      requestId,
+      code: validation.code,
+      message: validation.message
+    });
+    return;
+  }
+
+  const items = listIntegrationConnections({
+    role: INTEGRATION_ROLE_FRONTEND_PAGE,
+    channel: validation.payload.channel,
+    clientId: validation.payload.clientId
+  }).map(buildEditorClientSummary);
+
+  sendJson(ws, {
+    type: 'integration.editor.clients.result',
+    requestId,
+    payload: {
+      items,
+      total: items.length,
+      filters: validation.payload
+    }
+  });
+}
+
+function validateIntegrationContextUpdatePayload(payload) {
+  if (!payload || typeof payload !== 'object') {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'payload must be an object' };
+  }
+
+  const channel = normalizeNonEmptyString(payload.channel);
+  if (!channel) {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'channel is required' };
+  }
+
+  const targetClientId = normalizeNonEmptyString(payload.targetClientId);
+  if (!targetClientId) {
+    return { ok: false, code: 'INVALID_TARGET', message: 'targetClientId is required' };
+  }
+
+  const mode = normalizeNonEmptyString(payload.mode) || 'replace';
+  if (mode !== 'replace' && mode !== 'append') {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'mode must be replace or append' };
+  }
+
+  if (!payload.context || typeof payload.context !== 'object' || Array.isArray(payload.context)) {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'context must be an object' };
+  }
+
+  return {
+    ok: true,
+    payload: {
+      channel,
+      targetClientId,
+      mode,
+      context: payload.context
+    }
+  };
+}
+
+function validateIntegrationPromptUpdatePayload(payload) {
+  if (!payload || typeof payload !== 'object') {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'payload must be an object' };
+  }
+
+  const channel = normalizeNonEmptyString(payload.channel);
+  if (!channel) {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'channel is required' };
+  }
+
+  const targetClientId = normalizeNonEmptyString(payload.targetClientId);
+  if (!targetClientId) {
+    return { ok: false, code: 'INVALID_TARGET', message: 'targetClientId is required' };
+  }
+
+  if (typeof payload.prompt !== 'string') {
+    return { ok: false, code: 'INVALID_PAYLOAD', message: 'prompt must be a string' };
+  }
+
+  return {
+    ok: true,
+    payload: {
+      channel,
+      targetClientId,
+      prompt: payload.prompt,
+      autoSend: payload.autoSend === true
+    }
+  };
+}
+
+function forwardIntegrationMessage(ws, data, { validator, type, awaitResult = false }) {
+  const requestId = getRequestId(data);
+  const validation = validator(data?.payload);
+  if (!validation.ok) {
+    sendIntegrationError(ws, {
+      requestId,
+      code: validation.code,
+      message: validation.message
+    });
+    return;
+  }
+
+  const { channel, targetClientId } = validation.payload;
+  const targets = getTargetFrontendConnections(channel, targetClientId);
+  if (targets.length === 0) {
+    sendIntegrationError(ws, {
+      requestId,
+      code: 'FRONTEND_NOT_ONLINE',
+      message: 'Target frontend page is not connected'
+    });
+    return;
+  }
+
+  const requiredCapability = INTEGRATION_EDITOR_CAPABILITIES[type] || null;
+  if (requiredCapability) {
+    const unsupportedTarget = targets.find((target) => !target.capabilities?.includes(requiredCapability));
+    if (unsupportedTarget) {
+      sendIntegrationError(ws, {
+        requestId,
+        code: 'UNSUPPORTED_FRONTEND_CAPABILITY',
+        message: `Target frontend page does not advertise capability ${requiredCapability}`
+      });
+      return;
+    }
+  }
+
+  storePendingIntegrationRequest(requestId, ws, {
+    awaitResult,
+    requestType: type,
+    timeoutMs: data?.payload?.timeoutMs,
+    requestPayload: validation.payload
+  });
+
+  const outgoingPayload = {
+    type,
+    requestId,
+    payload: validation.payload
+  };
+
+  for (const target of targets) {
+    sendJson(target.ws, outgoingPayload);
+  }
+}
+
+async function forwardIntegrationResponseToOrigin(data) {
+  const requestId = getRequestId(data);
+  if (!requestId) {
+    return false;
+  }
+
+  const pendingRequest = pendingIntegrationRequests.get(requestId);
+  if (!pendingRequest?.originWs || pendingRequest.originWs.readyState !== WebSocket.OPEN) {
+    clearPendingIntegrationRequest(requestId);
+    return false;
+  }
+
+  let outgoingData = data;
+  try {
+    outgoingData = await maybeMaterializeEditorResult(data, pendingRequest);
+  } catch (error) {
+    sendIntegrationError(pendingRequest.originWs, {
+      requestId,
+      code: error.code || 'INTERNAL_ERROR',
+      message: error.message || 'Failed to materialize editor result'
+    });
+    clearPendingIntegrationRequest(requestId);
+    return true;
+  }
+
+  sendJson(pendingRequest.originWs, outgoingData);
+  const isTerminal =
+    outgoingData?.type === 'integration.error'
+    || isEditorResultMessageType(outgoingData?.type)
+    || (outgoingData?.type === 'integration.ack' && pendingRequest.awaitResult !== true);
+  if (isTerminal) {
+    clearPendingIntegrationRequest(requestId);
+  }
+  return true;
+}
+
+class ExternalAgentWebSocketWriter {
+  constructor(ws, { requestId, provider }) {
+    this.ws = ws;
+    this.requestId = requestId;
+    this.provider = provider;
+    this.sessionId = null;
+    this.isWebSocketWriter = true;
+  }
+
+  send(payload) {
+    if (!payload || typeof payload !== 'object') {
+      return;
+    }
+
+    if (typeof payload.sessionId === 'string' && payload.sessionId.trim()) {
+      this.sessionId = payload.sessionId.trim();
+    }
+
+    if (payload.type === 'session-created') {
+      const sessionId = typeof payload.sessionId === 'string' ? payload.sessionId.trim() : this.sessionId;
+      if (!sessionId) {
+        return;
+      }
+
+      this.sessionId = sessionId;
+      sendJson(this.ws, {
+        type: 'agent.session.created',
+        requestId: this.requestId,
+        provider: payload.provider || this.provider,
+        sessionId,
+        ...buildSessionNavigation(sessionId)
+      });
+      return;
+    }
+
+    if (payload.type === 'conversation-event' && payload.event) {
+      const sessionId = payload.sessionId || payload.event?.sessionId || this.sessionId || null;
+      if (sessionId) {
+        this.sessionId = sessionId;
+      }
+
+      sendJson(this.ws, {
+        type: 'agent.event',
+        requestId: this.requestId,
+        provider: payload.provider || payload.event?.provider || this.provider,
+        sessionId,
+        event: payload.event
+      });
+    }
+  }
+
+  setSessionId(sessionId) {
+    this.sessionId = sessionId;
+  }
+
+  getSessionId() {
+    return this.sessionId;
+  }
+}
+
+subscribeToSessionRuntimeStateChanges(({ subscriptionKey, snapshot }) => {
+  const subscribers = sessionStateSubscribersByKey.get(subscriptionKey);
+  if (!subscribers || subscribers.size === 0) {
+    return;
+  }
+
+  subscribers.forEach((ws) => {
+    sendJson(ws, {
+      type: 'agent.state.changed',
+      payload: {
+        subscriptionKey,
+        sessionId: snapshot.sessionId,
+        provider: snapshot.provider,
+        phase: snapshot.phase,
+        isLoading: snapshot.isLoading,
+        canAbortSession: snapshot.canAbortSession,
+        hasPendingApproval: snapshot.hasPendingApproval,
+        updatedAt: snapshot.updatedAt
+      }
+    });
+  });
+});
+
+async function handleAgentRun(ws, request, data) {
+  const requestId = getRequestId(data);
+
+  let normalized = null;
+  try {
+    normalized = normalizeExternalAgentRunRequest(data.payload || {});
+  } catch (error) {
+    sendRequestError(ws, {
+      requestId,
+      provider: data?.payload?.provider || null,
+      sessionId: data?.payload?.sessionId || null,
+      error: error.message,
+      statusCode: error.statusCode || 400
+    });
+    return;
+  }
+
+  sendJson(ws, {
+    type: 'agent.accepted',
+    requestId,
+    provider: normalized.provider,
+    sessionId: normalized.normalizedSessionId
+  });
+
+  const baseWriter = new ExternalAgentWebSocketWriter(ws, {
+    requestId,
+    provider: normalized.provider
+  });
+  const transportWriter = new SessionEventMirrorWriter(baseWriter, normalized.provider);
+
+  try {
+    const result = await runExternalAgentRequest({
+      user: request.user,
+      request: normalized,
+      transportWriter,
+      endTransportOnFinish: false
+    });
+
+    sendJson(ws, {
+      type: 'agent.completed',
+      requestId,
+      provider: normalized.provider,
+      sessionId: result.sessionId || baseWriter.getSessionId() || normalized.normalizedSessionId,
+      result
+    });
+  } catch (error) {
+    const resolvedSessionId = baseWriter.getSessionId() || normalized.normalizedSessionId || null;
+    if (error instanceof AgentSessionAbortedError) {
+      sendJson(ws, {
+        type: 'agent.aborted',
+        requestId,
+        success: true,
+        aborted: true,
+        sessionId: resolvedSessionId,
+        provider: normalized.provider,
+        message: 'Session aborted'
+      });
+      return;
+    }
+
+    sendRequestError(ws, {
+      requestId,
+      provider: normalized.provider,
+      sessionId: resolvedSessionId,
+      error: error.message,
+      statusCode: error.statusCode || 500
+    });
+  }
+}
+
+async function handleAgentAbort(ws, data) {
+  const requestId = getRequestId(data);
+
+  let normalized = null;
+  try {
+    normalized = normalizeExternalAgentAbortRequest(data.payload || {});
+  } catch (error) {
+    sendRequestError(ws, {
+      requestId,
+      provider: data?.payload?.provider || null,
+      sessionId: data?.payload?.sessionId || null,
+      error: error.message,
+      statusCode: error.statusCode || 400
+    });
+    return;
+  }
+
+  try {
+    const writer = new SessionEventMirrorWriter(
+      new ExternalAgentWebSocketWriter(ws, { requestId, provider: normalized.provider }),
+      normalized.provider
+    );
+    const { success } = await abortAgentSessionWithWriter({
+      provider: normalized.provider,
+      sessionId: normalized.sessionId,
+      writer
+    });
+
+    if (!success) {
+      sendRequestError(ws, {
+        requestId,
+        provider: normalized.provider,
+        sessionId: normalized.sessionId,
+        error: 'Active session not found',
+        statusCode: 200
+      });
+      return;
+    }
+
+    sendJson(ws, {
+      type: 'agent.aborted',
+      requestId,
+      success: true,
+      aborted: true,
+      sessionId: normalized.sessionId,
+      provider: normalized.provider,
+      message: 'Session aborted'
+    });
+  } catch (error) {
+    sendRequestError(ws, {
+      requestId,
+      provider: normalized.provider,
+      sessionId: normalized.sessionId,
+      error: error.message,
+      statusCode: 500
+    });
+  }
+}
+
+export function handleExternalAgentWebSocketConnection(ws, request) {
+  ws.on('message', (message) => {
+    let data = null;
+    try {
+      data = JSON.parse(message);
+    } catch {
+      sendRequestError(ws, {
+        requestId: null,
+        provider: null,
+        sessionId: null,
+        error: 'Invalid JSON message',
+        statusCode: 400
+      });
+      return;
+    }
+
+    touchIntegrationConnection(ws);
+
+    if (data?.type === 'ping') {
+      sendJson(ws, {
+        type: 'pong',
+        requestId: getRequestId(data),
+        timestamp: new Date().toISOString()
+      });
+      return;
+    }
+
+    if (data?.type === 'integration.connect') {
+      handleIntegrationConnect(ws, data);
+      return;
+    }
+
+    if (data?.type === 'integration.ping') {
+      handleIntegrationPing(ws, data);
+      return;
+    }
+
+    if (data?.type === 'integration.context.update') {
+      forwardIntegrationMessage(ws, data, {
+        validator: validateIntegrationContextUpdatePayload,
+        type: 'integration.context.update'
+      });
+      return;
+    }
+
+    if (data?.type === 'integration.prompt.update') {
+      forwardIntegrationMessage(ws, data, {
+        validator: validateIntegrationPromptUpdatePayload,
+        type: 'integration.prompt.update'
+      });
+      return;
+    }
+
+    if (data?.type === 'integration.editor.clients.list') {
+      handleEditorClientsList(ws, data);
+      return;
+    }
+
+    if (data?.type === 'integration.editor.snapshot.get') {
+      forwardIntegrationMessage(ws, data, {
+        validator: validateEditorSnapshotPayload,
+        type: 'integration.editor.snapshot.get',
+        awaitResult: true
+      });
+      return;
+    }
+
+    if (data?.type === 'integration.editor.nodes.list') {
+      forwardIntegrationMessage(ws, data, {
+        validator: validateEditorNodesListPayload,
+        type: 'integration.editor.nodes.list',
+        awaitResult: true
+      });
+      return;
+    }
+
+    if (data?.type === 'integration.editor.node.screenshot.get') {
+      forwardIntegrationMessage(ws, data, {
+        validator: validateEditorNodeScreenshotPayload,
+        type: 'integration.editor.node.screenshot.get',
+        awaitResult: true
+      });
+      return;
+    }
+
+    if (data?.type === 'integration.editor.context-images.get') {
+      forwardIntegrationMessage(ws, data, {
+        validator: validateEditorContextImagesPayload,
+        type: 'integration.editor.context-images.get',
+        awaitResult: true
+      });
+      return;
+    }
+
+    if (data?.type === 'integration.editor.editing.set') {
+      forwardIntegrationMessage(ws, data, {
+        validator: validateEditorEditingSetPayload,
+        type: 'integration.editor.editing.set',
+        awaitResult: true
+      });
+      return;
+    }
+
+    if (data?.type === 'integration.ack' || data?.type === 'integration.error' || isEditorResultMessageType(data?.type)) {
+      const handledProbeResponse = handleIntegrationProbeResponse(ws, data);
+      if (handledProbeResponse) {
+        return;
+      }
+
+      void forwardIntegrationResponseToOrigin(data).then((forwarded) => {
+        if (!forwarded && data?.type === 'integration.error') {
+          sendIntegrationError(ws, {
+            requestId: getRequestId(data),
+            code: 'UNSUPPORTED_MESSAGE_TYPE',
+            message: 'No pending integration request found for this response'
+          });
+        }
+      }).catch((error) => {
+        sendIntegrationError(ws, {
+          requestId: getRequestId(data),
+          code: error.code || 'INTERNAL_ERROR',
+          message: error.message || 'Failed to forward integration response'
+        });
+      });
+      return;
+    }
+
+    if (data?.type === 'agent.run') {
+      void handleAgentRun(ws, request, data);
+      return;
+    }
+
+    if (data?.type === 'agent.state.query') {
+      void handleAgentStateQuery(ws, data);
+      return;
+    }
+
+    if (data?.type === 'agent.state.subscribe') {
+      void handleAgentStateSubscribe(ws, data);
+      return;
+    }
+
+    if (data?.type === 'agent.abort') {
+      void handleAgentAbort(ws, data);
+      return;
+    }
+
+    if (typeof data?.type === 'string' && data.type.startsWith('integration.')) {
+      sendIntegrationError(ws, {
+        requestId: getRequestId(data),
+        code: 'UNSUPPORTED_MESSAGE_TYPE',
+        message: 'Unsupported integration message type'
+      });
+      return;
+    }
+
+    sendRequestError(ws, {
+      requestId: getRequestId(data),
+      provider: data?.payload?.provider || null,
+      sessionId: data?.payload?.sessionId || null,
+      error: 'Unsupported message type',
+      statusCode: 400
+    });
+  });
+
+  ws.on('close', () => {
+    unregisterIntegrationConnection(ws);
+  });
+}