@yeaft/webchat-agent 1.0.417 → 1.0.419

package/local-runtime/server/handlers/agent-browser.js

@@ -5,6 +5,7 @@ import {
   browserRoutes,
   completeBrowserRequest,
   deleteBrowserPeer,
+  findBrowserRequest,
   deleteBrowserRoute,
   getBrowserPeer,
   getBrowserRoute,
@@ -12,6 +13,9 @@ import {
 } from '../browser-runtime-routes.js';
 
 const AGENT_BROWSER_TYPES = new Set([
+  'browser_runtime_status_result',
+  'browser_runtime_install_progress',
+  'browser_runtime_error',
   'browser_session_created',
   'browser_session_error',
   'browser_session_snapshot',
@@ -56,6 +60,50 @@ function sessionSnapshot(msg) {
   };
 }
 
+function safeByteCount(value) {
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < 0) return 0;
+  return Math.min(number, 4 * 1024 * 1024 * 1024);
+}
+
+function publicRuntimeMessage(agentId, requestId, msg) {
+  if (msg?.type === 'browser_runtime_error') {
+    return {
+      type: msg.type,
+      agentId,
+      requestId,
+      code: clean(msg.code, 128) || 'browser_runtime_error',
+      safeError: clean(msg.safeError, 500) || null,
+    };
+  }
+  if (msg?.type === 'browser_runtime_install_progress') {
+    return {
+      type: msg.type,
+      agentId,
+      requestId,
+      downloadedBytes: safeByteCount(msg.downloadedBytes),
+      totalBytes: safeByteCount(msg.totalBytes),
+    };
+  }
+  return {
+    type: 'browser_runtime_status_result',
+    agentId,
+    requestId,
+    supported: msg?.supported === true,
+    state: clean(msg?.state, 32) || 'unknown',
+    installed: msg?.installed === true,
+    enabled: msg?.enabled === true,
+    ready: msg?.ready === true,
+    buildId: clean(msg?.buildId, 128) || null,
+    platform: clean(msg?.platform, 32) || null,
+    downloadBytes: safeByteCount(msg?.downloadBytes),
+    downloadedBytes: safeByteCount(msg?.downloadedBytes),
+    totalBytes: safeByteCount(msg?.totalBytes),
+    probeCode: clean(msg?.probeCode, 128) || null,
+    safeError: clean(msg?.safeError, 500) || null,
+  };
+}
+
 function publicSessionMessage(agentId, msg) {
   if (msg?.type === 'browser_session_error') {
     return {
@@ -84,7 +132,7 @@ function publicSessionMessage(agentId, msg) {
 }
 
 async function sendCreateResponse(agentId, msg) {
-  const request = completeBrowserRequest(agentId, msg);
+  const request = completeBrowserRequest(agentId, msg, { kinds: 'browser_session_create' });
   if (!request) return true;
   const client = browserClientForPeer({
     clientId: request.clientId,
@@ -130,13 +178,47 @@ async function sendCreateResponse(agentId, msg) {
 /** Agent-authenticated Browser events routed only through Server-owned ledgers. */
 export async function handleAgentBrowser(agentId, agent, msg) {
   if (!AGENT_BROWSER_TYPES.has(msg?.type)) return false;
+  if (msg.type === 'browser_runtime_install_progress') {
+    const request = findBrowserRequest(agentId, msg.requestId);
+    if (!request || request.state !== 'pending' || request.kind !== 'browser_runtime_install') return true;
+    const client = browserClientForPeer({
+      clientId: request.clientId,
+      webConnectionId: request.webConnectionId,
+      webConnectionGeneration: request.webConnectionGeneration,
+    });
+    if (client?.userId === request.ownerUserId) {
+      await sendToWebClient(client, publicRuntimeMessage(agentId, request.requestId, msg));
+    }
+    return true;
+  }
+  if (msg.type === 'browser_runtime_status_result' || msg.type === 'browser_runtime_error') {
+    const pendingRequest = findBrowserRequest(agentId, msg.requestId);
+    const request = completeBrowserRequest(agentId, msg, {
+      consume: pendingRequest?.kind === 'browser_runtime_status',
+      kinds: ['browser_runtime_status', 'browser_runtime_install', 'browser_runtime_enable'],
+    });
+    if (!request) return true;
+    const client = browserClientForPeer({
+      clientId: request.clientId,
+      webConnectionId: request.webConnectionId,
+      webConnectionGeneration: request.webConnectionGeneration,
+    });
+    if (client?.userId !== request.ownerUserId) return true;
+    const response = publicRuntimeMessage(agentId, request.requestId, msg);
+    request.response = response;
+    await sendToWebClient(client, response);
+    return true;
+  }
   if (msg.type === 'browser_session_created'
       || (msg.type === 'browser_session_error' && msg.requestId)) {
     return sendCreateResponse(agentId, msg);
   }
 
   if (msg.type === 'browser_session_list_result') {
-    const request = completeBrowserRequest(agentId, msg, { consume: true });
+    const request = completeBrowserRequest(agentId, msg, {
+      consume: true,
+      kinds: 'browser_session_list',
+    });
     if (!request) return true;
     for (const snapshot of Array.isArray(msg.sessions) ? msg.sessions : []) {
       if (!snapshot?.browserSessionId) continue;
@@ -154,7 +236,10 @@ export async function handleAgentBrowser(agentId, agent, msg) {
   }
 
   if (msg.type === 'browser_session_snapshot' && msg.requestId) {
-    const request = completeBrowserRequest(agentId, msg, { consume: true });
+    const request = completeBrowserRequest(agentId, msg, {
+      consume: true,
+      kinds: ['browser_session_get', 'browser_session_close'],
+    });
     if (!request) return true;
     const client = browserClientForPeer({
       clientId: request.clientId,

package/local-runtime/server/handlers/agent-sync.js

@@ -74,6 +74,20 @@ export async function handleAgentSync(agentId, agent, msg) {
       break;
     }
 
+    case 'agent_capabilities_updated': {
+      const capabilities = Array.isArray(msg.capabilities)
+        ? [...new Set(msg.capabilities.filter(value => (
+          typeof value === 'string' && value.length > 0 && value.length <= 128
+        )).slice(0, 128))]
+        : null;
+      if (!capabilities || capabilities.length === 0) break;
+      agent.capabilities = capabilities;
+      // Transport encryption negotiation is connection-scoped and immutable.
+      // A runtime capability refresh must never flip framing mid-connection.
+      await broadcastAgentList();
+      break;
+    }
+
     case 'agent_metrics': {
       agent.metrics = normalizeAgentMetrics(msg.metrics || {});
       agent.metricsUpdatedAt = Date.now();

package/local-runtime/server/handlers/client-browser.js

@@ -15,6 +15,9 @@ import {
 } from '../browser-runtime-routes.js';
 
 const CLIENT_BROWSER_TYPES = new Set([
+  'browser_runtime_status',
+  'browser_runtime_install',
+  'browser_runtime_enable',
   'browser_session_create',
   'browser_session_get',
   'browser_session_list',
@@ -34,8 +37,11 @@ function digest(value) {
 }
 
 async function fail(client, msg, code, safeError = code) {
+  const type = String(msg.type || '');
   await sendToWebClient(client, {
-    type: String(msg.type || '').startsWith('browser_peer_') ? 'browser_peer_error' : 'browser_session_error',
+    type: type.startsWith('browser_peer_') ? 'browser_peer_error'
+      : type.startsWith('browser_runtime_') ? 'browser_runtime_error'
+        : 'browser_session_error',
     requestId: clean(msg.requestId) || null,
     browserSessionId: clean(msg.browserSessionId) || null,
     peerId: clean(msg.peerId) || null,
@@ -46,6 +52,10 @@ async function fail(client, msg, code, safeError = code) {
   return true;
 }
 
+function agentSupportsBrowserSetup(agent) {
+  return new Set(agent?.capabilities || []).has('browser_runtime_setup');
+}
+
 function agentSupportsBrowser(agent) {
   const capabilities = new Set(agent?.capabilities || []);
   return capabilities.has('browser_runtime')
@@ -98,17 +108,54 @@ function ownerRoute(client, msg) {
 export async function handleClientBrowser(client, msg, checkAgentAccess) {
   if (!CLIENT_BROWSER_TYPES.has(msg?.type)) return false;
   if (!CONFIG.browserRuntime.enabled) return fail(client, msg, 'browser_runtime_disabled');
-  if (client.browserRuntimeProtocol !== 1) return fail(client, msg, 'browser_protocol_required');
+  const setupRequest = String(msg.type || '').startsWith('browser_runtime_');
+  if (setupRequest) {
+    if (client.browserRuntimeSetupProtocol !== 1) {
+      return fail(client, msg, 'browser_setup_protocol_required');
+    }
+  } else if (client.browserRuntimeProtocol !== 1) {
+    return fail(client, msg, 'browser_protocol_required');
+  }
   const agentId = clean(msg.agentId);
   if (!await checkAgentAccess(agentId)) return true;
   const agent = agents.get(agentId);
-  if (!agentSupportsBrowser(agent)) return fail(client, msg, 'browser_runtime_unavailable');
+  if (setupRequest ? !agentSupportsBrowserSetup(agent) : !agentSupportsBrowser(agent)) {
+    return fail(client, msg, 'browser_runtime_unavailable');
+  }
   const requestId = clean(msg.requestId);
   const requestRequired = msg.type !== 'browser_peer_answer'
     && msg.type !== 'browser_peer_ice_candidate';
   if (requestRequired && !requestId) return fail(client, msg, 'browser_request_id_required');
   const identity = browserServerIdentity(client);
 
+  if (setupRequest) {
+    const canonical = msg.type === 'browser_runtime_install' ? {
+      confirmedBuildId: clean(msg.confirmedBuildId, 128),
+      confirmedDownloadBytes: Number(msg.confirmedDownloadBytes) || 0,
+    } : {};
+    const registration = registerBrowserCreateRequest({
+      agentId,
+      client,
+      requestId,
+      digest: digest({ type: msg.type, ...canonical }),
+      kind: msg.type,
+    });
+    if (registration.conflict) return fail(client, msg, 'browser_request_conflict');
+    if (registration.capacity) return fail(client, msg, 'browser_request_capacity');
+    if (registration.duplicate) {
+      if (registration.request.response) await sendToWebClient(client, registration.request.response);
+      return true;
+    }
+    await sendToAgent(agent, {
+      type: msg.type,
+      agentId,
+      requestId: registration.request.serverRequestId,
+      ...canonical,
+      serverIdentity: identity,
+    });
+    return true;
+  }
+
   if (msg.type === 'browser_session_create') {
     const canonical = canonicalCreate(msg);
     if (!canonical) return fail(client, msg, 'browser_url_invalid');

package/local-runtime/server/handlers/client-conversation.js

@@ -27,6 +27,10 @@ import {
   chatCatalogKey,
   yeaftCatalogKey,
 } from '../session-catalog.js';
+import {
+  agentSupportsYeaftPlugins,
+  YEAFT_PLUGINS_UNSUPPORTED_ERROR,
+} from '../yeaft-plugin-capability.js';
 
 
 function isRetiredCollabSessionId(id) {
@@ -44,6 +48,14 @@ function emptyYeaftToolStats(reason = '') {
   return payload;
 }
 
+function emptyYeaftPluginCatalog(error = null) {
+  return {
+    type: 'yeaft_plugin_catalog_result',
+    catalog: { tools: [], skills: [], mcpServers: [] },
+    ...(error ? { error } : {}),
+  };
+}
+
 async function sendVpSnapshotError(client, msg, error) {
   await sendToWebClient(client, {
     type: 'yeaft_output',
@@ -420,6 +432,7 @@ export async function handleClientConversation(clientId, client, msg, checkAgent
             agentName: agent.name,
             workDir: agent.workDir,
             capabilities: agent.capabilities || ['terminal', 'file_editor', 'background_tasks'],
+            ...(agent.capabilityMetadataProvided === true ? { capabilityMetadataProvided: true } : {}),
             version: agent.version || null,
             conversations: filteredConvs,
             slashCommands: agent.slashCommands || [],
@@ -1628,6 +1641,15 @@ export async function handleClientConversation(clientId, client, msg, checkAgent
           }
           return true;
         }
+        if (relayType === 'yeaft_plugin_catalog'
+            && !agentSupportsYeaftPlugins(agents.get(relayAgentId))) {
+          await sendToWebClient(client, {
+            ...emptyYeaftPluginCatalog(YEAFT_PLUGINS_UNSUPPORTED_ERROR),
+            agentId: relayAgentId,
+            requestId: msg.requestId || null,
+          });
+          return true;
+        }
         const relayAgent = agents.get(relayAgentId);
         if (!relayAgent || relayAgent.ws?.readyState !== 1) {
           if (relayType === 'yeaft_fetch_tool_stats') {

package/local-runtime/server/handlers/client-misc.js

@@ -3,11 +3,27 @@ import {
   sendToWebClient, forwardToAgent, broadcastAgentList
 } from '../ws-utils.js';
 import { resolveWorkbenchRequest } from '../workbench-route.js';
+import {
+  agentSupportsYeaftPlugins,
+  YEAFT_PLUGINS_CAPABILITY,
+  YEAFT_PLUGINS_UNSUPPORTED_ERROR,
+} from '../yeaft-plugin-capability.js';
 
 // Only Agents that explicitly advertise the package-replacement-safe updater
 // may receive remote upgrade commands. Version thresholds are insufficient:
 // builds without this capability may still inherit the installed package cwd.
 export const SAFE_REMOTE_UPGRADE_CAPABILITY = 'remote_upgrade_safe';
+export { YEAFT_PLUGINS_CAPABILITY, YEAFT_PLUGINS_UNSUPPORTED_ERROR };
+
+async function rejectUnsupportedYeaftPlugins(client, msg, agentId) {
+  await sendToWebClient(client, {
+    type: msg.type === 'update_yeaft_plugins' ? 'yeaft_plugins_updated' : 'yeaft_plugins',
+    agentId,
+    requestId: msg.requestId || null,
+    plugins: {},
+    error: YEAFT_PLUGINS_UNSUPPORTED_ERROR,
+  });
+}
 
 export function requiresManualUpgradeBridge(capabilities, platform = null) {
   if (Array.isArray(capabilities) && capabilities.includes(SAFE_REMOTE_UPGRADE_CAPABILITY)) return false;
@@ -204,6 +220,10 @@ export async function handleClientMisc(clientId, client, msg, checkAgentAccess)
       const targetAgentId = msg.agentId || client.currentAgent;
       if (!targetAgentId) break;
       if (!await checkAgentAccess(targetAgentId)) break;
+      if (!agentSupportsYeaftPlugins(agents.get(targetAgentId))) {
+        await rejectUnsupportedYeaftPlugins(client, msg, targetAgentId);
+        break;
+      }
       await forwardToAgent(targetAgentId, {
         type: 'get_yeaft_plugins',
         requestId: msg.requestId || null,
@@ -215,6 +235,10 @@ export async function handleClientMisc(clientId, client, msg, checkAgentAccess)
       const targetAgentId = msg.agentId || client.currentAgent;
       if (!targetAgentId) break;
       if (!await checkAgentAccess(targetAgentId)) break;
+      if (!agentSupportsYeaftPlugins(agents.get(targetAgentId))) {
+        await rejectUnsupportedYeaftPlugins(client, msg, targetAgentId);
+        break;
+      }
       const hasPlugins = Object.prototype.hasOwnProperty.call(msg, 'plugins');
       const hasConfig = Object.prototype.hasOwnProperty.call(msg, 'config');
       await forwardToAgent(targetAgentId, {

package/local-runtime/server/ws-agent.js

@@ -120,7 +120,13 @@ export function handleAgentConnection(ws, url) {
             return;
           }
 
-          const capabilities = Array.isArray(msg.capabilities) ? msg.capabilities : urlCapabilities;
+          const authCapabilitiesProvided = Array.isArray(msg.capabilities);
+          // Modern Agents always include this query key, including for an
+          // explicit empty list. The key's presence is the metadata signal;
+          // its value only determines the effective capability list.
+          const urlCapabilitiesProvided = url.searchParams.has('capabilities');
+          const capabilityMetadataProvided = authCapabilitiesProvided || urlCapabilitiesProvided;
+          const capabilities = authCapabilitiesProvided ? msg.capabilities : urlCapabilities;
           const agentVersion = msg.version || null;
           const agentPlatform = typeof msg.platform === 'string' && msg.platform
             ? msg.platform
@@ -152,6 +158,7 @@ export function handleAgentConnection(ws, url) {
             pending.workDir,
             authResult.sessionKey,
             capabilities,
+            capabilityMetadataProvided,
             ownerId,
             ownerUsername,
             agentVersion,
@@ -243,7 +250,7 @@ function handleAgentDisconnect(agentId, agentName, ws) {
   broadcastAgentList();
 }
 
-function completeAgentRegistration(ws, agentId, agentName, workDir, sessionKey, capabilities = [], ownerId = null, ownerUsername = null, agentVersion = null, instanceId = null, agentPlatform = null) {
+function completeAgentRegistration(ws, agentId, agentName, workDir, sessionKey, capabilities = [], capabilityMetadataProvided = false, ownerId = null, ownerUsername = null, agentVersion = null, instanceId = null, agentPlatform = null) {
   // 如果是重连，保留 conversations；否则（server 重启）创建空 Map
   const existingAgent = agents.get(agentId);
   const conversations = existingAgent?.conversations || new Map();
@@ -274,6 +281,9 @@ function completeAgentRegistration(ws, agentId, agentName, workDir, sessionKey,
     isAlive: true,
     lastSeenAt: Date.now(),
     capabilities: effectiveCapabilities,
+    // The fallback list supports old UI features but cannot prove that an
+    // Agent made an explicit capability claim.
+    capabilityMetadataProvided,
     proxyPorts,
     slashCommands,
     slashCommandDescriptions,
@@ -352,6 +362,7 @@ async function handleAgentMessage(agentId, msg, ws) {
     'file_content', 'file_saved', 'file_op_result', 'file_search_result',
     'git_status_result', 'git_diff_result', 'git_op_result',
     'terminal_created', 'terminal_output', 'terminal_closed', 'terminal_error',
+    'agent_capabilities_updated', 'browser_runtime_status_result', 'browser_runtime_install_progress', 'browser_runtime_error',
     'browser_session_created', 'browser_session_error', 'browser_session_snapshot', 'browser_session_list_result',
     'browser_peer_prepared', 'browser_peer_offer', 'browser_peer_ice_candidate', 'browser_peer_state', 'browser_peer_error'
   ]);

package/local-runtime/server/ws-client.js

@@ -6,7 +6,12 @@ import { authenticateRequest } from './auth/request-auth.js';
 import { encodeKey } from './encryption.js';
 import { userDb } from './database.js';
 import { agents, clearYeaftDebugRequestsForClient, webClients, isHeartbeatMessageType, trackRequest } from './context.js';
-import { applyClientHello, BROWSER_RUNTIME_PROTOCOL, WORKBENCH_ROUTE_PROTOCOL } from './client-protocol.js';
+import {
+  applyClientHello,
+  BROWSER_RUNTIME_PROTOCOL,
+  BROWSER_RUNTIME_SETUP_PROTOCOL,
+  WORKBENCH_ROUTE_PROTOCOL,
+} from './client-protocol.js';
 import { clearWorkbenchCorrelationsForClient } from './workbench-correlation.js';
 import { clearBrowserRuntimeForClient } from './browser-runtime-routes.js';
 import {
@@ -88,6 +93,7 @@ export function handleWebConnection(ws, url, req = {}) {
     // Explicit protocols have no omission-based downgrade for security fields.
     workbenchRouteProtocol: 0,
     browserRuntimeProtocol: 0,
+    browserRuntimeSetupProtocol: 0,
   });
 
   // 心跳响应处理
@@ -116,6 +122,7 @@ export function handleWebConnection(ws, url, req = {}) {
       yeaftSessionInventoryComplete: true,
       workbenchRouteProtocol: WORKBENCH_ROUTE_PROTOCOL,
       browserRuntimeProtocol: BROWSER_RUNTIME_PROTOCOL,
+      browserRuntimeSetupProtocol: BROWSER_RUNTIME_SETUP_PROTOCOL,
       browserRuntimeEnabled: CONFIG.browserRuntime.enabled,
     }));
     setTimeout(() => broadcastAgentList(), 100);
@@ -249,6 +256,7 @@ async function handleWebMessage(clientId, msg) {
       type: 'client_hello_ack',
       workbenchRouteProtocol: client.workbenchRouteProtocol,
       browserRuntimeProtocol: client.browserRuntimeProtocol,
+      browserRuntimeSetupProtocol: client.browserRuntimeSetupProtocol,
       browserRuntimeEnabled: CONFIG.browserRuntime.enabled,
     });
     return;

package/local-runtime/server/ws-utils.js

@@ -169,6 +169,7 @@ export async function broadcastAgentList() {
           status: agent.status || 'ready',
           latency: agent.latency || null,
           capabilities: agent.capabilities || ['terminal', 'file_editor', 'background_tasks'],
+          ...(agent.capabilityMetadataProvided === true ? { capabilityMetadataProvided: true } : {}),
           version: agent.version || null,
           yeaftStatus: agent.yeaftStatus || null,
           proxyPorts: agent.proxyPorts || [],

package/local-runtime/server/yeaft-plugin-capability.js

@@ -0,0 +1,11 @@
+// Plugin protocol support is omission-compatible: old Agents that never
+// advertised capability metadata keep the legacy relay path. Once an Agent
+// explicitly provides metadata, omitting this token is an explicit refusal.
+export const YEAFT_PLUGINS_CAPABILITY = 'yeaft_plugins';
+export const YEAFT_PLUGINS_UNSUPPORTED_ERROR = 'The selected Agent does not support Plugins; upgrade and restart the Agent';
+
+export function agentSupportsYeaftPlugins(agent) {
+  if (agent?.capabilityMetadataProvided !== true) return true;
+  return Array.isArray(agent.capabilities)
+    && agent.capabilities.includes(YEAFT_PLUGINS_CAPABILITY);
+}

package/local-runtime/version.json

@@ -1 +1 @@
-{"version":"1.0.417"}
+{"version":"1.0.419"}