@yeaft/webchat-agent 1.0.458 → 1.0.460

package/connection/message-router.js

@@ -350,7 +350,7 @@ export async function handleMessage(msg) {
       break;
 
     case 'restart_agent':
-      await handleRestartAgent();
+      await handleRestartAgent({ requestId: msg.requestId, clientId: msg.clientId });
       break;
 
     case 'set_dream_enabled': {
@@ -363,15 +363,15 @@ export async function handleMessage(msg) {
         const runtime = await ensureSessionLoaded();
         runtime.config.dream = { ...(runtime.config.dream || {}), enabled };
         runtime.dreamScheduler?.setEnabled?.(enabled);
-        sendToServer({ type: 'dream_enabled_changed', enabled });
+        sendToServer({ type: 'dream_enabled_changed', enabled, requestId: msg.requestId, clientId: msg.clientId });
       } catch (error) {
-        sendToServer({ type: 'dream_enabled_changed', enabled: !enabled, error: error?.message || String(error) });
+        sendToServer({ type: 'dream_enabled_changed', enabled: !enabled, error: error?.message || String(error), requestId: msg.requestId, clientId: msg.clientId });
       }
       break;
     }
 
     case 'upgrade_agent':
-      await handleUpgradeAgent();
+      await handleUpgradeAgent({ requestId: msg.requestId, clientId: msg.clientId });
       break;
 
     // MCP configuration
@@ -495,7 +495,7 @@ export async function handleMessage(msg) {
     // section of config.json. This does not expose trace payloads.
     case 'get_telemetry_settings': {
       const settings = getTelemetrySettings(ctx.CONFIG?.yeaftDir);
-      sendToServer({ type: 'telemetry_settings', ...settings });
+      sendToServer({ type: 'telemetry_settings', requestId: msg.requestId, clientId: msg.clientId, ...settings });
       break;
     }
 
@@ -515,7 +515,7 @@ export async function handleMessage(msg) {
           result.runtimeRefreshError = error?.message || String(error);
         }
       }
-      sendToServer({ type: 'telemetry_settings_updated', ...result });
+      sendToServer({ type: 'telemetry_settings_updated', requestId: msg.requestId, clientId: msg.clientId, ...result });
       break;
     }
 

package/connection/upgrade.js

@@ -92,9 +92,9 @@ function cleanupAndExit(exitCode) {
   }, 500);
 }
 
-export async function handleRestartAgent() {
+export async function handleRestartAgent(correlation = {}) {
   console.log('[Agent] Restart requested, shutting down for PM2/systemd restart...');
-  await sendToServer({ type: 'restart_agent_ack' });
+  await sendToServer({ type: 'restart_agent_ack', requestId: correlation.requestId, clientId: correlation.clientId });
   cleanupAndExit(1);
 }
 
@@ -178,13 +178,18 @@ function compareCmp(cur, cmp) {
   }
 }
 
-export async function handleUpgradeAgent() {
+export async function handleUpgradeAgent(correlation = {}) {
+  const sendUpgradeAck = (payload) => sendToServer({
+    type: 'upgrade_agent_ack',
+    ...payload,
+    requestId: correlation.requestId,
+    clientId: correlation.clientId,
+  });
   if (isContainerAgentRuntime() || ctx.agentCapabilities?.includes(CONTAINER_AGENT_CAPABILITY)) {
     const version = ctx.agentVersion || null;
     const error = buildContainerImageUpgradeMessage(version);
     console.warn(`[Agent] Upgrade rejected (${CONTAINER_IMAGE_UPGRADE_REASON}): ${error}`);
-    await sendToServer({
-      type: 'upgrade_agent_ack',
+    await sendUpgradeAck({
       success: false,
       reason: CONTAINER_IMAGE_UPGRADE_REASON,
       error,
@@ -205,7 +210,7 @@ export async function handleUpgradeAgent() {
     });
     if (!isUpgradeAvailable(ctx.agentVersion, latestVersion)) {
       console.log(`[Agent] No newer version than ${ctx.agentVersion} is available (registry: ${latestVersion}), skipping upgrade.`);
-      await sendToServer({ type: 'upgrade_agent_ack', success: true, alreadyLatest: true, version: ctx.agentVersion });
+      await sendUpgradeAck({ success: true, alreadyLatest: true, version: ctx.agentVersion });
       return;
     }
 
@@ -218,8 +223,7 @@ export async function handleUpgradeAgent() {
     if (requiredNode && !nodeRangeSatisfied(currentNode, requiredNode)) {
       const msg = `Node ${currentNode} does not satisfy required ${requiredNode} for ${pkgName}@${latestVersion}`;
       console.warn(`[Agent] Upgrade aborted: ${msg}`);
-      await sendToServer({
-        type: 'upgrade_agent_ack',
+      await sendUpgradeAck({
         success: false,
         reason: 'node_incompatible',
         error: msg,
@@ -240,7 +244,7 @@ export async function handleUpgradeAgent() {
     if (!isNpmInstall) {
       // 源码运行不支持远程升级（代码在 git repo 中，需要手动 git pull）
       console.log('[Agent] Source-based install detected, remote upgrade not supported.');
-      await sendToServer({ type: 'upgrade_agent_ack', success: false, error: 'Source-based install: please use git pull to upgrade' });
+      await sendUpgradeAck({ success: false, error: 'Source-based install: please use git pull to upgrade' });
       return;
     }
 
@@ -260,9 +264,9 @@ export async function handleUpgradeAgent() {
     const instanceId = resolveInstanceId();
 
     if (isWindows) {
-      await spawnWindowsUpgradeScript(pkgName, installDir, isGlobalInstall, latestVersion, instanceId);
+      await spawnWindowsUpgradeScript(pkgName, installDir, isGlobalInstall, latestVersion, instanceId, sendUpgradeAck);
     } else {
-      await spawnUnixUpgradeScript(pkgName, installDir, isGlobalInstall, latestVersion, instanceId);
+      await spawnUnixUpgradeScript(pkgName, installDir, isGlobalInstall, latestVersion, instanceId, sendUpgradeAck);
     }
 
     // On Windows the detached runner removes the PM2 app only after this
@@ -281,11 +285,11 @@ export async function handleUpgradeAgent() {
     cleanupAndExit(0);
   } catch (e) {
     console.error('[Agent] Upgrade failed:', e.message);
-    await sendToServer({ type: 'upgrade_agent_ack', success: false, error: e.message });
+    await sendUpgradeAck({ success: false, error: e.message });
   }
 }
 
-async function spawnWindowsUpgradeScript(pkgName, installDir, isGlobalInstall, latestVersion, instanceId = DEFAULT_INSTANCE_ID) {
+async function spawnWindowsUpgradeScript(pkgName, installDir, isGlobalInstall, latestVersion, instanceId = DEFAULT_INSTANCE_ID, sendUpgradeAck = (payload) => sendToServer({ type: 'upgrade_agent_ack', ...payload })) {
   const configDir = getConfigDir(instanceId);
   const upgradeDir = join(configDir, 'upgrade-runtime');
   const logDir = join(configDir, 'logs');
@@ -364,7 +368,7 @@ async function spawnWindowsUpgradeScript(pkgName, installDir, isGlobalInstall, l
     spawnProcess: spawn,
   });
   console.log(`[Agent] Spawned Windows upgrade runner via ${launcher} (pm2=${isPm2}, dir=${installDir})`);
-  await sendToServer({ type: 'upgrade_agent_ack', success: true, version: latestVersion, pendingRestart: true });
+  await sendUpgradeAck({ success: true, version: latestVersion, pendingRestart: true });
 }
 
 /**
@@ -529,7 +533,7 @@ export function buildUnixUpgradeScript({
   return shLines.join('\n');
 }
 
-async function spawnUnixUpgradeScript(pkgName, installDir, isGlobalInstall, latestVersion, instanceId = DEFAULT_INSTANCE_ID) {
+async function spawnUnixUpgradeScript(pkgName, installDir, isGlobalInstall, latestVersion, instanceId = DEFAULT_INSTANCE_ID, sendUpgradeAck = (payload) => sendToServer({ type: 'upgrade_agent_ack', ...payload })) {
   const configDir = getConfigDir(instanceId);
   // Create logs/ too: the generated script's `exec > "$LOGFILE" 2>&1` aborts
   // the whole upgrade silently if that directory is missing.
@@ -555,5 +559,5 @@ async function spawnUnixUpgradeScript(pkgName, installDir, isGlobalInstall, late
   });
   child.unref();
   console.log(`[Agent] Spawned upgrade script: ${shPath}`);
-  await sendToServer({ type: 'upgrade_agent_ack', success: true, version: latestVersion, pendingRestart: true });
+  await sendUpgradeAck({ success: true, version: latestVersion, pendingRestart: true });
 }

package/index.js

@@ -175,7 +175,7 @@ async function detectCapabilities() {
   // agent build can speak plaintext WS frames. New servers see this and
   // flip `agent.encryptOutbound = false`, stopping outbound encryption
   // to this peer. Old servers ignore the unknown capability token.
-  const capabilities = ['background_tasks', 'file_editor', 'ping_session', 'plaintext-ok', 'workbench_session_routes', 'work_center', 'work_center_message_v2', 'session_history_search', 'session_history_outline', 'session_history_window_prefetch', 'file_reference_resolution', 'yeaft_plugins', 'yeaft_managed_skills'];
+  const capabilities = ['background_tasks', 'file_editor', 'ping_session', 'plaintext-ok', 'workbench_session_routes', 'work_center', 'work_center_message_v2', 'session_history_search', 'session_history_outline', 'session_history_window_prefetch', 'file_reference_resolution', 'yeaft_plugins', 'yeaft_managed_skills', 'settings_request_correlation'];
   capabilities.push(getAgentUpgradeCapability());
   if (process.platform === 'linux') capabilities.push('work_item_attachments');
   const pty = await loadNodePty();

package/local-runtime/server/context.js

@@ -43,8 +43,104 @@ export const previewFiles = new Map();
 // original Agent/Session ownership check happened, and consume it exactly once.
 const YEAFT_DEBUG_REQUEST_TTL_MS = 30_000;
 const YEAFT_DEBUG_REQUEST_MAX_PENDING = 2048;
+const YEAFT_DEBUG_REQUEST_MAX_PENDING_PER_CLIENT = 256;
 export const pendingYeaftDebugRequests = new Map();
 
+// Agent settings replies share one Agent connection across browser clients.
+// Correlation-capable Agents require exact requestId matching. Legacy Agents are
+// allowed one in-flight request per Agent/operation so an identity-less reply has
+// exactly one possible owner.
+const AGENT_SETTINGS_REQUEST_TTL_MS = 120_000;
+const AGENT_SETTINGS_REQUEST_MAX_PENDING = 2048;
+const AGENT_SETTINGS_REQUEST_MAX_PENDING_PER_CLIENT = 256;
+export const pendingAgentSettingsRequests = new Map();
+
+function agentSettingsRequestKey(agentId, requestId) {
+  return `${String(agentId || '')}\u0000${String(requestId || '')}`;
+}
+
+function pruneAgentSettingsRequests(now = Date.now()) {
+  for (const [key, pending] of pendingAgentSettingsRequests) {
+    if (!pending || pending.expiresAt <= now || !webClients.has(pending.clientId)) {
+      pendingAgentSettingsRequests.delete(key);
+    }
+  }
+}
+
+/** Register an owner-checked settings request before it is sent to the Agent. */
+export function registerAgentSettingsRequest({ agentId, operation, requestId, clientId, allowLegacyReply = false }) {
+  if (!agentId || !operation || !requestId || !clientId) return false;
+  const now = Date.now();
+  pruneAgentSettingsRequests(now);
+  const key = agentSettingsRequestKey(agentId, requestId);
+  if (pendingAgentSettingsRequests.has(key)) return false;
+  let clientPending = 0;
+  for (const pending of pendingAgentSettingsRequests.values()) {
+    if (pending?.clientId === clientId) clientPending++;
+    if (allowLegacyReply && pending?.agentId === agentId && pending?.operation === operation) return false;
+  }
+  if (clientPending >= AGENT_SETTINGS_REQUEST_MAX_PENDING_PER_CLIENT
+      || pendingAgentSettingsRequests.size >= AGENT_SETTINGS_REQUEST_MAX_PENDING) return false;
+  pendingAgentSettingsRequests.set(key, {
+    agentId,
+    operation,
+    requestId,
+    clientId,
+    allowLegacyReply,
+    expiresAt: now + AGENT_SETTINGS_REQUEST_TTL_MS,
+  });
+  return true;
+}
+
+/** Consume an exact response, or the sole explicitly legacy-compatible request. */
+export function consumeAgentSettingsRequest({ agentId, operation, requestId }) {
+  if (!agentId || !operation) return null;
+  pruneAgentSettingsRequests();
+  if (requestId) {
+    const key = agentSettingsRequestKey(agentId, requestId);
+    const pending = pendingAgentSettingsRequests.get(key);
+    if (!pending || pending.operation !== operation) return null;
+    pendingAgentSettingsRequests.delete(key);
+    return pending;
+  }
+  let matchKey = null;
+  let match = null;
+  for (const [key, pending] of pendingAgentSettingsRequests) {
+    if (pending?.agentId !== agentId || pending?.operation !== operation || !pending.allowLegacyReply) continue;
+    if (match) return null;
+    matchKey = key;
+    match = pending;
+  }
+  if (!match) return null;
+  pendingAgentSettingsRequests.delete(matchKey);
+  return match;
+}
+
+export function deleteAgentSettingsRequest({ agentId, requestId, clientId = null }) {
+  const key = agentSettingsRequestKey(agentId, requestId);
+  const pending = pendingAgentSettingsRequests.get(key);
+  if (!pending || (clientId && pending.clientId !== clientId)) return false;
+  return pendingAgentSettingsRequests.delete(key);
+}
+
+export function clearAgentSettingsRequestsForClient(clientId) {
+  if (!clientId) return;
+  for (const [key, pending] of pendingAgentSettingsRequests) {
+    if (pending?.clientId === clientId) pendingAgentSettingsRequests.delete(key);
+  }
+}
+
+export function takeAgentSettingsRequestsForAgent(agentId) {
+  const removed = [];
+  if (!agentId) return removed;
+  for (const [key, pending] of pendingAgentSettingsRequests) {
+    if (pending?.agentId !== agentId) continue;
+    pendingAgentSettingsRequests.delete(key);
+    removed.push(pending);
+  }
+  return removed;
+}
+
 function yeaftDebugRequestKey(agentId, requestId) {
   return `${String(agentId || '')}\u0000${String(requestId || '')}`;
 }
@@ -68,10 +164,12 @@ export function registerYeaftDebugRequest({ agentId, requestId, sessionId, clien
   pruneYeaftDebugRequests(now);
   const key = yeaftDebugRequestKey(agentId, requestId);
   if (pendingYeaftDebugRequests.has(key)) return false;
-  if (pendingYeaftDebugRequests.size >= YEAFT_DEBUG_REQUEST_MAX_PENDING) {
-    const oldestKey = pendingYeaftDebugRequests.keys().next().value;
-    if (oldestKey != null) pendingYeaftDebugRequests.delete(oldestKey);
+  let clientPending = 0;
+  for (const pending of pendingYeaftDebugRequests.values()) {
+    if (pending?.clientId === clientId) clientPending++;
   }
+  if (clientPending >= YEAFT_DEBUG_REQUEST_MAX_PENDING_PER_CLIENT
+      || pendingYeaftDebugRequests.size >= YEAFT_DEBUG_REQUEST_MAX_PENDING) return false;
   pendingYeaftDebugRequests.set(key, {
     agentId,
     requestId,

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

@@ -1,6 +1,10 @@
 import { CONFIG } from '../config.js';
 import { agentInventoryDb, sessionDb, userStatsDb } from '../database.js';
-import { agents, webClients } from '../context.js';
+import {
+  agents,
+  consumeAgentSettingsRequest,
+  webClients,
+} from '../context.js';
 import { sendToWebClient, broadcastAgentList } from '../ws-utils.js';
 import {
   handleProxyResponse, handleProxyResponseChunk, handleProxyResponseEnd,
@@ -12,6 +16,18 @@ const numberMetric = (value) => {
   return Number.isFinite(n) && n >= 0 ? n : 0;
 };
 
+async function sendAgentSettingsReply(agentId, agent, operation, msg, payload) {
+  const pending = consumeAgentSettingsRequest({ agentId, operation, requestId: msg.requestId });
+  if (!pending) return false;
+  if (!msg.requestId) payload.requestId = pending.requestId;
+  const client = webClients.get(pending.clientId);
+  if (!client?.authenticated || (!CONFIG.skipAuth
+    && !((agent.ownerId && client.userId === agent.ownerId)
+      || (!agent.ownerId && client.role === 'admin')))) return false;
+  await sendToWebClient(client, payload);
+  return true;
+}
+
 function normalizeAgentMetrics(metrics = {}) {
   const chatTurns = numberMetric(metrics.chatTurns);
   const yeaftTurns = numberMetric(metrics.yeaftTurns);
@@ -80,16 +96,14 @@ export async function handleAgentSync(agentId, agent, msg) {
         agent.dreamEnabled = msg.enabled !== false;
         await broadcastAgentList();
       }
-      for (const [, client] of webClients) {
-        if (!client.authenticated) continue;
-        if (!CONFIG.skipAuth && agent.ownerId !== client.userId && !(!agent.ownerId && client.role === 'admin')) continue;
-        await sendToWebClient(client, {
-          type: 'dream_enabled_changed',
-          agentId,
-          enabled: msg.error ? agent.dreamEnabled !== false : msg.enabled !== false,
-          ...(msg.error ? { error: msg.error } : {}),
-        });
-      }
+      const payload = {
+        type: 'dream_enabled_changed',
+        agentId,
+        requestId: msg.requestId,
+        enabled: msg.error ? agent.dreamEnabled !== false : msg.enabled !== false,
+        ...(msg.error ? { error: msg.error } : {}),
+      };
+      await sendAgentSettingsReply(agentId, agent, 'dream', msg, payload);
       break;
     }
 
@@ -202,27 +216,14 @@ export async function handleAgentSync(agentId, agent, msg) {
     }
 
     case 'restart_agent_ack': {
-      // 只通知该 Agent 的 owner
-      for (const [, client] of webClients) {
-        if (client.authenticated && (CONFIG.skipAuth ||
-          (agent.ownerId && client.userId === agent.ownerId) ||
-          (!agent.ownerId && client.role === 'admin')
-        )) {
-          await sendToWebClient(client, { type: 'restart_agent_ack', agentId });
-        }
-      }
+      const payload = { type: 'restart_agent_ack', agentId, requestId: msg.requestId };
+      await sendAgentSettingsReply(agentId, agent, 'restart', msg, payload);
       break;
     }
 
     case 'upgrade_agent_ack': {
-      for (const [, client] of webClients) {
-        if (client.authenticated && (CONFIG.skipAuth ||
-          (agent.ownerId && client.userId === agent.ownerId) ||
-          (!agent.ownerId && client.role === 'admin')
-        )) {
-          await sendToWebClient(client, { type: 'upgrade_agent_ack', agentId, success: msg.success, error: msg.error, alreadyLatest: msg.alreadyLatest, version: msg.version, reason: msg.reason, currentNode: msg.currentNode, requiredNode: msg.requiredNode, requiredCapability: msg.requiredCapability });
-        }
-      }
+      const payload = { type: 'upgrade_agent_ack', agentId, requestId: msg.requestId, success: msg.success, error: msg.error, alreadyLatest: msg.alreadyLatest, version: msg.version, reason: msg.reason, currentNode: msg.currentNode, requiredNode: msg.requiredNode, requiredCapability: msg.requiredCapability };
+      await sendAgentSettingsReply(agentId, agent, 'upgrade', msg, payload);
       break;
     }
 
@@ -408,14 +409,14 @@ export async function handleAgentSync(agentId, agent, msg) {
     // trace payloads stay on the Agent.
     case 'telemetry_settings':
     case 'telemetry_settings_updated': {
-      for (const [, client] of webClients) {
-        if (client.authenticated && (CONFIG.skipAuth ||
-          (agent.ownerId && client.userId === agent.ownerId) ||
-          (!agent.ownerId && client.role === 'admin')
-        )) {
-          await sendToWebClient(client, { ...msg, agentId });
-        }
-      }
+      const operation = msg.type === 'yeaft_plugins_updated'
+        ? 'plugins:update'
+        : msg.type === 'yeaft_plugins'
+          ? 'plugins:load'
+          : msg.type === 'telemetry_settings_updated'
+            ? 'telemetry:update'
+            : 'telemetry:load';
+      await sendAgentSettingsReply(agentId, agent, operation, msg, { ...msg, agentId });
       break;
     }
 

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

@@ -1339,9 +1339,12 @@ export async function handleClientConversation(clientId, client, msg, checkAgent
         clientId,
         userId: client.userId,
       });
-      if (!registered) return;
+      if (!registered) {
+        await sendToWebClient(client, { type: 'yeaft_debug_history', agentId: debugAgentId, sessionId: debugSessionId, requestId: debugRequestId, error: 'Request rejected: too many pending requests or duplicate requestId.' });
+        return;
+      }
       try {
-        await forwardToAgent(debugAgentId, {
+        const dispatched = await forwardToAgent(debugAgentId, {
           type: 'yeaft_fetch_debug_history',
           sessionId: debugSessionId,
           requestId: debugRequestId,
@@ -1353,9 +1356,13 @@ export async function handleClientConversation(clientId, client, msg, checkAgent
           search: typeof msg.search === 'string' ? msg.search.slice(0, 500) : '',
           _requestClientId: clientId,
         });
+        if (!dispatched) {
+          deleteYeaftDebugRequest({ agentId: debugAgentId, requestId: debugRequestId, clientId });
+          await sendToWebClient(client, { type: 'yeaft_debug_history', agentId: debugAgentId, sessionId: debugSessionId, requestId: debugRequestId, error: 'Agent is unavailable.' });
+        }
       } catch (err) {
         deleteYeaftDebugRequest({ agentId: debugAgentId, requestId: debugRequestId, clientId });
-        throw err;
+        await sendToWebClient(client, { type: 'yeaft_debug_history', agentId: debugAgentId, sessionId: debugSessionId, requestId: debugRequestId, error: `Failed to send request to Agent: ${err.message}` });
       }
       break;
     }

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

@@ -1,4 +1,9 @@
-import { agents, userFileTabs } from '../context.js';
+import {
+  agents,
+  deleteAgentSettingsRequest,
+  registerAgentSettingsRequest,
+  userFileTabs,
+} from '../context.js';
 import {
   sendToWebClient, forwardToAgent, broadcastAgentList
 } from '../ws-utils.js';
@@ -27,6 +32,26 @@ async function rejectUnsupportedYeaftPlugins(client, msg, agentId) {
   });
 }
 
+async function forwardRegisteredAgentRequest({ client, clientId, agentId, operation, requestId, message, responseType }) {
+  const agent = agents.get(agentId);
+  const allowLegacyReply = !Array.isArray(agent?.capabilities)
+    || !agent.capabilities.includes('settings_request_correlation');
+  if (!registerAgentSettingsRequest({ agentId, operation, requestId, clientId, allowLegacyReply })) {
+    await sendToWebClient(client, { type: responseType, agentId, requestId, error: 'Request rejected: too many pending requests or duplicate requestId.' });
+    return false;
+  }
+  try {
+    if (await forwardToAgent(agentId, message)) return true;
+  } catch (error) {
+    deleteAgentSettingsRequest({ agentId, requestId, clientId });
+    await sendToWebClient(client, { type: responseType, agentId, requestId, error: `Failed to send request to Agent: ${error.message}` });
+    return false;
+  }
+  deleteAgentSettingsRequest({ agentId, requestId, clientId });
+  await sendToWebClient(client, { type: responseType, agentId, requestId, error: 'Agent is unavailable.' });
+  return false;
+}
+
 export function requiresManualUpgradeBridge(capabilities, platform = null) {
   if (Array.isArray(capabilities) && capabilities.includes(SAFE_REMOTE_UPGRADE_CAPABILITY)) return false;
   const normalizedPlatform = typeof platform === 'string' ? platform.trim().toLowerCase() : '';
@@ -52,7 +77,12 @@ export async function handleClientMisc(clientId, client, msg, checkAgentAccess)
       const restartAgentId = msg.agentId;
       if (!restartAgentId) break;
       if (!await checkAgentAccess(restartAgentId)) break;
-      await forwardToAgent(restartAgentId, { type: 'restart_agent' });
+      if (msg.requestId) {
+        await forwardRegisteredAgentRequest({ client, clientId, agentId: restartAgentId, operation: 'restart', requestId: msg.requestId,
+          message: { type: 'restart_agent', requestId: msg.requestId, clientId }, responseType: 'restart_agent_ack' });
+      } else {
+        await forwardToAgent(restartAgentId, { type: 'restart_agent' });
+      }
       break;
     }
 
@@ -60,7 +90,12 @@ export async function handleClientMisc(clientId, client, msg, checkAgentAccess)
       const agentId = msg.agentId;
       if (!agentId) break;
       if (!await checkAgentAccess(agentId)) break;
-      await forwardToAgent(agentId, { type: 'set_dream_enabled', enabled: msg.enabled !== false });
+      if (msg.requestId) {
+        await forwardRegisteredAgentRequest({ client, clientId, agentId, operation: 'dream', requestId: msg.requestId,
+          message: { type: 'set_dream_enabled', enabled: msg.enabled !== false, requestId: msg.requestId, clientId }, responseType: 'dream_enabled_changed' });
+      } else {
+        await forwardToAgent(agentId, { type: 'set_dream_enabled', enabled: msg.enabled !== false });
+      }
       break;
     }
 
@@ -79,6 +114,7 @@ export async function handleClientMisc(clientId, client, msg, checkAgentAccess)
           version: upgradeAgent?.version || null,
           requiredCapability: CONTAINER_AGENT_CAPABILITY,
           error: 'Container Agent is managed as a Docker image. Pull the configured image and recreate the same container through the Server/Sandbox lifecycle while keeping its persistent volumes and host-side agent-secret file.',
+          requestId: msg.requestId,
         });
         break;
       }
@@ -91,10 +127,16 @@ export async function handleClientMisc(clientId, client, msg, checkAgentAccess)
           version: upgradeAgent?.version || null,
           requiredCapability: SAFE_REMOTE_UPGRADE_CAPABILITY,
           error: `Agent ${upgradeAgent?.version || 'unknown'} does not advertise the safe remote-upgrade contract. First stop the selected Agent/service on that machine: if it runs under PM2 or another service manager, stop that exact instance there; if it runs in a foreground terminal, terminate that process. Confirm that process has exited, then run "npm install -g @yeaft/webchat-agent@latest --registry=https://pkg.yeaft.com/". Finally, restart the same Agent instance with its original configuration.`,
+          requestId: msg.requestId,
         });
         break;
       }
-      await forwardToAgent(upgradeAgentId, { type: 'upgrade_agent' });
+      if (msg.requestId) {
+        await forwardRegisteredAgentRequest({ client, clientId, agentId: upgradeAgentId, operation: 'upgrade', requestId: msg.requestId,
+          message: { type: 'upgrade_agent', requestId: msg.requestId, clientId }, responseType: 'upgrade_agent_ack' });
+      } else {
+        await forwardToAgent(upgradeAgentId, { type: 'upgrade_agent' });
+      }
       break;
     }
 
@@ -247,10 +289,8 @@ export async function handleClientMisc(clientId, client, msg, checkAgentAccess)
         await rejectUnsupportedYeaftPlugins(client, msg, targetAgentId);
         break;
       }
-      await forwardToAgent(targetAgentId, {
-        type: 'get_yeaft_plugins',
-        requestId: msg.requestId || null,
-      });
+      await forwardRegisteredAgentRequest({ client, clientId, agentId: targetAgentId, operation: 'plugins:load', requestId: msg.requestId,
+        message: { type: 'get_yeaft_plugins', requestId: msg.requestId }, responseType: 'yeaft_plugins' });
       break;
     }
 
@@ -264,12 +304,15 @@ export async function handleClientMisc(clientId, client, msg, checkAgentAccess)
       }
       const hasPlugins = Object.prototype.hasOwnProperty.call(msg, 'plugins');
       const hasConfig = Object.prototype.hasOwnProperty.call(msg, 'config');
-      await forwardToAgent(targetAgentId, {
-        type: 'update_yeaft_plugins',
-        requestId: msg.requestId || null,
-        // Preserve explicit falsy values so Agent-side schema validation can
-        // reject them. Only an absent payload is the legacy empty selection.
-        plugins: hasPlugins ? msg.plugins : (hasConfig ? msg.config : {}),
+      await forwardRegisteredAgentRequest({ client, clientId, agentId: targetAgentId, operation: 'plugins:update', requestId: msg.requestId,
+        message: {
+          type: 'update_yeaft_plugins',
+          requestId: msg.requestId,
+          // Preserve explicit falsy values so Agent-side schema validation can
+          // reject them. Only an absent payload is the legacy empty selection.
+          plugins: hasPlugins ? msg.plugins : (hasConfig ? msg.config : {}),
+        },
+        responseType: 'yeaft_plugins_updated',
       });
       break;
     }
@@ -291,7 +334,8 @@ export async function handleClientMisc(clientId, client, msg, checkAgentAccess)
       const a = msg.agentId || client.currentAgent;
       if (!a) break;
       if (!await checkAgentAccess(a)) break;
-      await forwardToAgent(a, { type: 'get_telemetry_settings' });
+      await forwardRegisteredAgentRequest({ client, clientId, agentId: a, operation: 'telemetry:load', requestId: msg.requestId,
+        message: { type: 'get_telemetry_settings', requestId: msg.requestId, clientId }, responseType: 'telemetry_settings' });
       break;
     }
 
@@ -299,10 +343,9 @@ export async function handleClientMisc(clientId, client, msg, checkAgentAccess)
       const a = msg.agentId || client.currentAgent;
       if (!a) break;
       if (!await checkAgentAccess(a)) break;
-      await forwardToAgent(a, {
-        type: 'update_telemetry_settings',
-        settings: msg.settings || msg.config || {},
-      });
+      await forwardRegisteredAgentRequest({ client, clientId, agentId: a, operation: 'telemetry:update', requestId: msg.requestId,
+        message: { type: 'update_telemetry_settings', requestId: msg.requestId, clientId, settings: msg.settings || msg.config || {} },
+        responseType: 'telemetry_settings_updated' });
       break;
     }