@yeaft/webchat-agent 1.0.413 → 1.0.415

package/cli.js

@@ -61,6 +61,14 @@ const SERVICE_COMMANDS = ['install', 'uninstall', 'start', 'stop', 'restart', 's
 
 if (command === 'doctor') {
   await handleDoctorCommand(subArgs);
+} else if (command === 'browser') {
+  try {
+    const { handleBrowserCommand } = await import('./browser-runtime/cli.js');
+    await handleBrowserCommand(subArgs);
+  } catch (error) {
+    console.error(`Browser Runtime command failed: ${error.code || error.message}`);
+    process.exitCode = 1;
+  }
 } else if (command === 'llm') {
   await handleLlmCommand(subArgs);
 } else if (command === 'local') {
@@ -137,6 +145,10 @@ function printHelp() {
     yeaft-agent status [options]       Show service status
     yeaft-agent logs [options]         View service logs (follow mode)
     yeaft-agent doctor                 Diagnose service configuration
+    yeaft-agent browser install        Install the pinned Chrome for Testing build
+    yeaft-agent browser probe          Validate tabCapture → offscreen → WebRTC
+    yeaft-agent browser enable|disable Change the Browser Runtime feature flag
+    yeaft-agent browser status         Show config and managed browser install status
     yeaft-agent llm <command>          Configure local Yeaft LLM providers/models
     yeaft-agent container <command>    Manage a Dockerized yeaft-agent
     yeaft-agent upgrade [--name <id>]  Upgrade and restart the selected service
@@ -153,6 +165,11 @@ function printHelp() {
     --yeaft-dir <dir>   Yeaft data directory for this instance
     --auto-upgrade      Check for updates on startup
 
+  Browser options:
+    --executable <path> Explicit compatible Chrome for Testing executable
+    --headful           Run the Browser Runtime probe with a visible browser
+    --name <id>         Select the named Agent instance
+
   Environment variables (alternative to flags):
     YEAFT_AGENT_INSTANCE Deprecated local service instance id override
     SERVER_URL          WebSocket server URL
@@ -174,7 +191,7 @@ function printHelp() {
 `);
 }
 
-function printLlmHelp() {
+export function printLlmHelp() {
   console.log(`
   Configure local Yeaft LLM providers/models in ~/.yeaft/config.json.
 
@@ -257,7 +274,7 @@ async function handleLlmCommand(args) {
       const preset = args[1];
       if (preset === 'github-copilot') {
         result = await useGitHubCopilot(current, options);
-        writeLocalLlmConfig(result.config, configPath);
+        writeLocalLlmConfig(result.config, configPath, current);
         console.log(`Configured GitHub Copilot provider with ${result.discovery.models.length} ${result.discovery.source} models.`);
         if (result.discovery.warning) console.log(`Warning: ${result.discovery.warning}`);
         console.log(`Primary model: ${result.config.primaryModel}`);
@@ -266,7 +283,7 @@ async function handleLlmCommand(args) {
       }
       if (preset === 'openai-compatible') {
         result = await useOpenAICompatible(current, options, process.env);
-        writeLocalLlmConfig(result.config, configPath);
+        writeLocalLlmConfig(result.config, configPath, current);
         console.log(`Configured ${result.provider.name} with ${result.discovery.models.length} live models.`);
         console.log(`Primary model: ${result.config.primaryModel}`);
         if (result.config.fastModel) console.log(`Fast model: ${result.config.fastModel}`);
@@ -277,7 +294,7 @@ async function handleLlmCommand(args) {
 
     if (subcommand === 'add-provider') {
       result = addOrUpdateProvider(current, options, process.env);
-      writeLocalLlmConfig(result.config, configPath);
+      writeLocalLlmConfig(result.config, configPath, current);
       console.log(`${result.replaced ? 'Updated' : 'Added'} provider: ${result.provider.name}`);
       if (result.config.primaryModel) console.log(`Primary model: ${result.config.primaryModel}`);
       if (result.config.fastModel) console.log(`Fast model: ${result.config.fastModel}`);
@@ -286,7 +303,7 @@ async function handleLlmCommand(args) {
 
     if (subcommand === 'set-model') {
       result = setLocalModels(current, options);
-      writeLocalLlmConfig(result.config, configPath);
+      writeLocalLlmConfig(result.config, configPath, current);
       if (result.config.primaryModel) console.log(`Primary model: ${result.config.primaryModel}`);
       if (result.config.fastModel) console.log(`Fast model: ${result.config.fastModel}`);
       return;
@@ -294,7 +311,7 @@ async function handleLlmCommand(args) {
 
     if (subcommand === 'remove-provider') {
       result = removeProvider(current, options);
-      writeLocalLlmConfig(result.config, configPath);
+      writeLocalLlmConfig(result.config, configPath, current);
       console.log(result.removed ? `Removed provider: ${options.name}` : `Provider not found: ${options.name}`);
       if (result.cleared.length) {
         console.log(`Cleared ${result.cleared.join(', ')} because it referenced ${options.name}`);
@@ -426,7 +443,7 @@ async function runLlmSetup(current, configPath) {
     const fastAnswer = (await rl.question('Fast model number or id (optional): ')).trim();
     const fast = fastAnswer ? (ids[Number(fastAnswer) - 1] || fastAnswer) : null;
     const result = await useGitHubCopilot(current, { model: primary, fast, allowUnknownModel: false });
-    writeLocalLlmConfig(result.config, configPath);
+    writeLocalLlmConfig(result.config, configPath, current);
     console.log(`Configured GitHub Copilot with ${result.discovery.models.length} ${result.discovery.source} models.`);
     if (result.discovery.warning) console.log(`Warning: ${result.discovery.warning}`);
     console.log(`Primary model: ${result.config.primaryModel}`);

package/connection/index.js

@@ -3,6 +3,7 @@ import ctx from '../context.js';
 import { sendToServer, parseMessage } from './buffer.js';
 import { startAgentHeartbeat, stopAgentHeartbeat, scheduleReconnect } from './heartbeat.js';
 import { handleMessage } from './message-router.js';
+import { cleanupTerminalsForDisconnect } from '../terminal.js';
 
 export function resetConnectionTransport() {
   ctx.sessionKey = null;
@@ -35,6 +36,7 @@ export function connect(WebSocketImpl = WebSocket) {
     console.log(`Disallowed tools: ${ctx.CONFIG.disallowedTools.join(', ')}`);
   }
 
+  const previousSocket = ctx.ws;
   const socket = new WebSocketImpl(url, {
     // Match server's permessage-deflate config (bounded memory,
     // skip compression for small frames). The `ws` library handles
@@ -46,6 +48,12 @@ export function connect(WebSocketImpl = WebSocket) {
       threshold: 1024
     }
   });
+  if (previousSocket && previousSocket !== socket) {
+    const closedTerminals = cleanupTerminalsForDisconnect();
+    if (closedTerminals > 0) {
+      console.log(`[PTY] Closed ${closedTerminals} terminal(s) before Agent transport replacement`);
+    }
+  }
   ctx.ws = socket;
 
   socket.on('open', () => {
@@ -99,6 +107,10 @@ export function connect(WebSocketImpl = WebSocket) {
     ctx.sessionKey = null;
     ctx.pendingAuthTempId = null;
     stopAgentHeartbeat();
+    const closedTerminals = cleanupTerminalsForDisconnect();
+    if (closedTerminals > 0) {
+      console.log(`[PTY] Closed ${closedTerminals} terminal(s) after Agent transport disconnect`);
+    }
 
     if (code === 1008) {
       console.error('Authentication failed. Check AGENT_SECRET configuration.');

package/context.js

@@ -20,6 +20,7 @@ export default {
   CONFIG: null,
   managedCliReady: Promise.resolve([]),
   agentCapabilities: [],
+  browserRuntime: null,
   // Agent 级别的 slash commands 缓存（所有 conversation 共用）
   slashCommands: [],
   // Slash command 描述映射: { commandName: description } — 从 plugin commands/*.md 提取

package/index.js

@@ -23,6 +23,7 @@ import { connect } from './connection.js';
 import { loadMcpServers } from './mcp.js';
 import { SAFE_REMOTE_UPGRADE_CAPABILITY } from './upgrade-command.js';
 import { loadConfig as loadYeaftConfig } from './yeaft/config.js';
+import { bootBrowserRuntime, shutdownBrowserRuntime } from './browser-runtime/index.js';
 import {
   ensureManagedCliTools,
   prepareManagedCliToolEnvironment,
@@ -104,7 +105,7 @@ const { agentName: AGENT_NAME, instanceId: INSTANCE_ID } = resolveRuntimeIdentit
 const YEAFT_DIR = process.env.YEAFT_DIR || fileConfig.yeaftDir || getDefaultYeaftDir(INSTANCE_ID);
 try {
   if (!existsSync(YEAFT_DIR)) {
-    mkdirSync(YEAFT_DIR, { recursive: true });
+    mkdirSync(YEAFT_DIR, { recursive: true, mode: 0o700 });
     console.log(`[Agent] Created yeaft dir: ${YEAFT_DIR}`);
   }
 } catch (err) {
@@ -159,7 +160,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', SAFE_REMOTE_UPGRADE_CAPABILITY, 'work_center', 'work_center_message_v2', 'session_history_search', 'session_history_outline', 'session_history_window_prefetch'];
+  const capabilities = ['background_tasks', 'file_editor', 'ping_session', 'plaintext-ok', 'workbench_session_routes', SAFE_REMOTE_UPGRADE_CAPABILITY, 'work_center', 'work_center_message_v2', 'session_history_search', 'session_history_outline', 'session_history_window_prefetch'];
   if (process.platform === 'linux') capabilities.push('work_item_attachments');
   const pty = await loadNodePty();
   if (pty) capabilities.push('terminal');
@@ -356,6 +357,7 @@ function cleanup() {
       const { shutdownWorkCenter } = await import('./yeaft/work-center/bridge.js');
       await shutdownWorkCenter();
     } catch {}
+    try { await shutdownBrowserRuntime(); } catch {}
     if (ctx.ws) ctx.ws.close();
   });
 }
@@ -396,6 +398,21 @@ process.on('SIGTERM', async () => {
   } catch (error) {
     console.warn(`[Startup] managed rg environment setup failed; using built-in fallback: ${error?.message || error}`);
   }
+  try {
+    const runtimeConfig = loadYeaftConfig({ dir: YEAFT_DIR }).browserRuntime;
+    ctx.browserRuntime = await bootBrowserRuntime({
+      yeaftDir: YEAFT_DIR,
+      config: runtimeConfig,
+    });
+    const probe = ctx.browserRuntime.snapshot().probe;
+    if (probe?.ok) {
+      console.log(`[BrowserRuntime] ready: capture=${probe.captureMode} build=${probe.actualBuildId || probe.expectedBuildId}`);
+    } else if (runtimeConfig?.enabled) {
+      console.warn(`[BrowserRuntime] unavailable: ${probe?.code || 'probe_failed'}`);
+    }
+  } catch (err) {
+    console.warn(`[BrowserRuntime] startup probe failed: ${err?.message || err}`);
+  }
   ctx.agentCapabilities = await detectCapabilities();
   // Prime the models.dev community catalog so the Yeaft engine's *synchronous*
   // hot path (engine.js / config.js / cli.js all read context-window inline)

package/llm-config-cli.js

@@ -1,7 +1,8 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
-import { dirname, join } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
 import { homedir } from 'os';
 import { normalizePluginConfig } from './yeaft/plugins.js';
+import { mutateAgentConfigPath } from './yeaft/config-store.js';
 import {
   discoverGitHubCopilotModels,
   discoverOpenAICompatibleModels,
@@ -40,31 +41,33 @@ export function readLocalLlmConfig(configPath = getDefaultYeaftConfigPath()) {
   return parsed;
 }
 
-export function writeLocalLlmConfig(config, configPath = getDefaultYeaftConfigPath()) {
-  // The CLI exposes this writer publicly, so do not rely on callers having
-  // already used readLocalLlmConfig(). An existing invalid Plugins policy must
-  // remain on disk and keep runtime fail-closed until the user repairs it.
-  const existing = existsSync(configPath) ? readLocalLlmConfig(configPath) : null;
+export function writeLocalLlmConfig(config, configPath = getDefaultYeaftConfigPath(), baseConfig = null) {
   if (!config || typeof config !== 'object' || Array.isArray(config)
     || Object.getPrototypeOf(config) !== Object.prototype) {
     throw new Error(`Invalid config file: expected JSON object at ${configPath}`);
   }
-  const next = { ...config };
-  if (next.plugins === undefined
-    && Object.prototype.hasOwnProperty.call(existing || {}, 'plugins')) {
-    // LLM commands change provider/model fields. They must not remove a
-    // separately-managed Plugin allowlist merely because their payload omits it.
-    next.plugins = existing.plugins;
-  }
-  if (next.plugins !== undefined) {
+  if (config.plugins !== undefined) {
     try {
-      normalizePluginConfig(next.plugins);
-    } catch (err) {
-      throw new Error(`Invalid config file: ${err?.message || err}`);
+      normalizePluginConfig(config.plugins);
+    } catch (error) {
+      throw new Error(`Invalid config file: ${error?.message || error}`);
     }
   }
-  mkdirSync(dirname(configPath), { recursive: true });
-  writeFileSync(configPath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+
+  mutateAgentConfigPath(configPath, current => {
+    const baseline = baseConfig && typeof baseConfig === 'object' && !Array.isArray(baseConfig)
+      ? baseConfig
+      : {};
+    const keys = new Set([...Object.keys(baseline), ...Object.keys(config)]);
+    for (const key of keys) {
+      if (key === 'plugins' && !Object.prototype.hasOwnProperty.call(config, key)) continue;
+      const before = baseline[key];
+      const after = config[key];
+      if (JSON.stringify(before) === JSON.stringify(after)) continue;
+      if (Object.prototype.hasOwnProperty.call(config, key)) current[key] = after;
+      else delete current[key];
+    }
+  });
 }
 
 export function parseModelsCsv(value) {
@@ -313,7 +316,7 @@ export async function tryAutoConfigureGitHubCopilot(configPath = getDefaultYeaft
       ...options,
       model: options.model || DEFAULT_GITHUB_COPILOT_MODEL,
     });
-    writeLocalLlmConfig(result.config, configPath);
+    writeLocalLlmConfig(result.config, configPath, current);
     return { configured: true, reason: 'configured', ...result };
   } catch (error) {
     return {

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

@@ -0,0 +1,14 @@
+export const WORKBENCH_ROUTE_PROTOCOL = 1;
+
+/**
+ * Apply the explicit browser protocol hello to one Server-owned client record.
+ * Unknown or omitted fields leave legacy defaults unchanged.
+ */
+export function applyClientHello(client, message) {
+  if (!client || message?.type !== 'client_hello') return false;
+  if (message.plaintextOk === true) client.encryptOutbound = false;
+  if (message.workbenchRouteProtocol === WORKBENCH_ROUTE_PROTOCOL) {
+    client.workbenchRouteProtocol = WORKBENCH_ROUTE_PROTOCOL;
+  }
+  return true;
+}

package/local-runtime/server/context.js

@@ -29,8 +29,9 @@ export const directoryCache = new Map();
 export const DIR_CACHE_TTL = 5 * 60 * 1000; // 5 minutes
 export const DIR_CACHE_MAX_SIZE = 500;
 
-// ★ Phase 5: File Tab state storage
-// key: `${userId}:${agentId}` → { files: [{path}], activeIndex, timestamp }
+// Workbench Files tab state. Route-aware writers use
+// `${userId}:${routeKey}\0${workspaceGeneration}`; legacy pairs keep the
+// historical `${userId}:${agentId}` key.
 export const userFileTabs = new Map();
 
 // Preview file cache for binary file preview (Office/PDF/Image)

package/local-runtime/server/handlers/agent-file-terminal.js

@@ -1,130 +1,200 @@
 import { randomUUID } from 'crypto';
-import { previewFiles, webClients } from '../context.js';
+import { CONFIG } from '../config.js';
+import { agents, previewFiles, webClients } from '../context.js';
 import {
-  sendToWebClient, forwardToClients,
-  setCachedDir, invalidateParentDirCache, clearAgentDirCache
+  sendToAgent,
+  sendToWebClient,
+  setCachedDir,
+  invalidateParentDirCache,
+  clearAgentDirCache,
 } from '../ws-utils.js';
+import {
+  currentWorkbenchWorkspaceGeneration,
+  workbenchRouteKeyFromConversationId,
+} from '../workbench-route.js';
+import {
+  consumeWorkbenchRequest,
+  deleteWorkbenchTerminalOwner,
+  getWorkbenchTerminalOwner,
+  registerWorkbenchTerminalOwner,
+} from '../workbench-correlation.js';
 
-/**
- * Handle file, terminal, and git messages from agent.
- * Types: terminal_created, terminal_output, terminal_closed, terminal_error,
- *        file_content, file_saved, directory_listing, file_op_result,
- *        git_status_result, git_diff_result, git_op_result, file_search_result
- */
-export async function handleAgentFileTerminal(agentId, agent, msg) {
-  switch (msg.type) {
-    // Terminal messages (forward to web clients)
-    case 'terminal_created':
-    case 'terminal_output':
-    case 'terminal_closed':
-    case 'terminal_error': {
-      const targetClient = msg._requestClientId ? webClients.get(msg._requestClientId) : null;
-      const targetMatchesUser = !msg._requestUserId || targetClient?.userId === msg._requestUserId;
-      if (targetClient?.authenticated && targetMatchesUser) {
-        const { _requestClientId, _requestUserId, ...cleanMsg } = msg;
-        await sendToWebClient(targetClient, cleanMsg);
-        break;
-      }
-      const { _requestClientId, ...fallbackMsg } = msg;
-      await forwardToClients(agentId, msg.conversationId, fallbackMsg);
-      break;
-    }
+function stripAgentRouting(msg) {
+  const {
+    _requestClientId: _ignoredClientId,
+    _requestUserId: _ignoredUserId,
+    _workbenchRequestId: _ignoredRequestId,
+    workbenchRouteKey: _ignoredRouteKey,
+    workbenchWorkspaceGeneration: _ignoredGeneration,
+    ...visible
+  } = msg || {};
+  return visible;
+}
 
-    // File operation messages
-    case 'file_content': {
-      let fwdMsg = { ...msg, agentId };
-      if (msg.binary) {
-        // Binary file: cache on server, forward fileId instead of base64 content
-        const fileId = randomUUID();
-        const token = randomUUID();
-        const filename = msg.filePath.split('/').pop() || 'file';
-        previewFiles.set(fileId, {
-          buffer: Buffer.from(msg.content, 'base64'),
-          mimeType: msg.mimeType,
-          filename,
-          createdAt: Date.now(),
-          token
-        });
-        console.log(`[Server] Cached binary preview: fileId=${fileId}, mime=${msg.mimeType}, path=${msg.filePath}`);
-        fwdMsg = {
-          type: 'file_content',
-          agentId,
+function pendingResponse(agentId, msg, pending) {
+  const { requestId: _agentRequestId, ...visible } = stripAgentRouting(msg);
+  return {
+    ...visible,
+    agentId,
+    conversationId: pending.conversationId,
+    ...(pending.publicRequestId ? { requestId: pending.publicRequestId } : {}),
+    workbenchRouteKey: pending.routeKey,
+    workbenchWorkspaceGeneration: pending.workspaceGeneration,
+  };
+}
+
+async function sendToPendingClient(agentId, msg, pending) {
+  const client = webClients.get(pending?.clientId);
+  if (!client?.authenticated || client.userId !== pending?.userId) return false;
+  await sendToWebClient(client, pendingResponse(agentId, msg, pending));
+  return true;
+}
+
+async function forwardLegacyResponse(agentId, msg) {
+  const visible = { ...stripAgentRouting(msg), agentId };
+  const agent = agents.get(agentId);
+  const conversation = agent?.conversations?.get?.(visible.conversationId);
+  const ownerId = conversation?.userId || agent?.ownerId || null;
+  for (const [, client] of webClients) {
+    if (!client?.authenticated) continue;
+    const allowed = CONFIG.skipAuth
+      || (ownerId ? client.userId === ownerId : client.role === 'admin');
+    if (allowed) await sendToWebClient(client, visible);
+  }
+}
+
+function cacheBinaryPreview(msg) {
+  const fileId = randomUUID();
+  const token = randomUUID();
+  const filename = msg.filePath.split('/').pop() || 'file';
+  previewFiles.set(fileId, {
+    buffer: Buffer.from(msg.content, 'base64'),
+    mimeType: msg.mimeType,
+    filename,
+    createdAt: Date.now(),
+    token,
+  });
+  const { content: _binaryContent, ...projected } = msg;
+  return {
+    ...projected,
+    binary: true,
+    fileId,
+    previewToken: token,
+  };
+}
+
+async function handleTerminalResponse(agentId, msg, routeKey) {
+  const terminalId = msg.terminalId || null;
+  if (msg.type === 'terminal_created') {
+    const pending = consumeWorkbenchRequest({
+      agentId,
+      requestId: msg._workbenchRequestId,
+      responseType: msg.type,
+      routeKey,
+    });
+    if (!pending) {
+      const agentRecord = agents.get(agentId);
+      if (agentRecord && terminalId && msg.workbenchWorkspaceGeneration) {
+        await sendToAgent(agentRecord, {
+          type: 'terminal_close',
           conversationId: msg.conversationId,
-          requestId: msg.requestId,
-          _requestUserId: msg._requestUserId,
-          _requestClientId: msg._requestClientId,
-          filePath: msg.filePath,
-          requestedFilePath: msg.requestedFilePath,
-          binary: true,
-          fileId,
-          previewToken: token,
-          mimeType: msg.mimeType
-        };
-      } else {
-        console.log(`[Server] Forwarding file_content to clients, conv=${msg.conversationId}, path=${msg.filePath}`);
-      }
-      const targetClient = fwdMsg._requestClientId ? webClients.get(fwdMsg._requestClientId) : null;
-      const targetMatchesUser = !fwdMsg._requestUserId || targetClient?.userId === fwdMsg._requestUserId;
-      if (targetClient?.authenticated && targetMatchesUser) {
-        const { _requestClientId, _requestUserId, ...cleanMsg } = fwdMsg;
-        await sendToWebClient(targetClient, cleanMsg);
-      } else {
-        const { _requestClientId, ...fallbackMsg } = fwdMsg;
-        await forwardToClients(agentId, msg.conversationId, fallbackMsg);
+          terminalId,
+          workbenchRouteKey: routeKey,
+          workbenchWorkspaceGeneration: msg.workbenchWorkspaceGeneration,
+        });
       }
-      break;
+      return;
     }
-
-    case 'file_saved': {
-      // Phase 4: 文件保存后失效父目录缓存
-      invalidateParentDirCache(agentId, msg.filePath);
-      const fwdMsg = { ...msg, agentId };
-      const targetClient = msg._requestClientId ? webClients.get(msg._requestClientId) : null;
-      const targetMatchesUser = !msg._requestUserId || targetClient?.userId === msg._requestUserId;
-      if (targetClient?.authenticated && targetMatchesUser) {
-        const { _requestClientId, _requestUserId, ...cleanMsg } = fwdMsg;
-        await sendToWebClient(targetClient, cleanMsg);
-      } else {
-        const { _requestClientId, ...fallbackMsg } = fwdMsg;
-        await forwardToClients(agentId, msg.conversationId, fallbackMsg);
-      }
-      break;
+    if (pending.routeKey !== routeKey || pending.terminalId !== terminalId) {
+      deleteWorkbenchTerminalOwner(agentId, pending.terminalId);
+      return;
     }
+    if (msg.success !== false) registerWorkbenchTerminalOwner({ ...pending, terminalId });
+    else deleteWorkbenchTerminalOwner(agentId, terminalId);
+    await sendToPendingClient(agentId, msg, pending);
+    return;
+  }
 
-    case 'directory_listing': {
-      // Phase 4: 缓存目录列表结果
-      if (msg.dirPath && msg.entries && !msg.error) {
-        setCachedDir(agentId, msg.dirPath, msg.entries);
-      }
-      // 优先定向发送给请求者
-      const dirTargetClientId = msg._requestClientId;
-      if (dirTargetClientId) {
-        const targetClient = webClients.get(dirTargetClientId);
-        if (targetClient?.authenticated) {
-          const { _requestClientId, ...cleanMsg } = msg;
-          await sendToWebClient(targetClient, cleanMsg);
-          break;
-        }
-      }
-      await forwardToClients(agentId, msg.conversationId, msg);
-      break;
-    }
+  // Create errors carry the one-shot create correlation even though a
+  // terminal-id reservation already exists. Consume and release it first.
+  if (msg.type === 'terminal_error' && msg._workbenchRequestId) {
+    const pending = consumeWorkbenchRequest({
+      agentId,
+      requestId: msg._workbenchRequestId,
+      responseType: msg.type,
+      routeKey,
+    });
+    if (pending?.terminalId) deleteWorkbenchTerminalOwner(agentId, pending.terminalId);
+    if (pending?.routeKey === routeKey) await sendToPendingClient(agentId, msg, pending);
+    return;
+  }
+
+  const owner = terminalId ? getWorkbenchTerminalOwner(agentId, terminalId) : null;
+  if (owner) {
+    if (owner.routeKey !== routeKey) return;
+    await sendToPendingClient(agentId, msg, owner);
+    if (msg.type === 'terminal_closed') deleteWorkbenchTerminalOwner(agentId, terminalId);
+  }
+}
 
-    case 'file_op_result':
-      // Phase 4: 文件创建/删除/移动 — 清空该 agent 的所有目录缓存
-      clearAgentDirCache(agentId);
-      await forwardToClients(agentId, msg.conversationId, msg);
-      break;
+async function handleOneShotResponse(agentId, msg, routeKey) {
+  const pending = consumeWorkbenchRequest({
+    agentId,
+    requestId: msg._workbenchRequestId,
+    responseType: msg.type,
+    routeKey,
+  });
+  if (!pending) return;
+  const currentGeneration = currentWorkbenchWorkspaceGeneration({
+    route: pending.route,
+    userId: pending.userId,
+    role: pending.role,
+  });
+  if (!currentGeneration || currentGeneration !== pending.workspaceGeneration) return;
+  const projected = msg.type === 'file_content' && msg.binary
+    ? cacheBinaryPreview(msg)
+    : msg;
+  await sendToPendingClient(agentId, projected, pending);
+}
 
-    case 'git_status_result':
-    case 'git_diff_result':
-    case 'git_op_result':
-    case 'file_search_result':
-      await forwardToClients(agentId, msg.conversationId, msg);
-      break;
+/**
+ * Handle file, terminal, and git messages from an Agent. Route-scoped replies
+ * are delivered only through Server-owned correlations. Agent-supplied client
+ * or user ids never select a browser recipient.
+ */
+export async function handleAgentFileTerminal(agentId, agent, rawMsg) {
+  const msg = rawMsg || {};
+  const routeKey = workbenchRouteKeyFromConversationId(msg.conversationId, agentId);
+  const terminalTypes = new Set([
+    'terminal_created', 'terminal_output', 'terminal_closed', 'terminal_error',
+  ]);
+  const oneShotTypes = new Set([
+    'file_content', 'file_saved', 'directory_listing', 'file_op_result',
+    'git_status_result', 'git_diff_result', 'git_op_result', 'file_search_result',
+  ]);
+  if (!terminalTypes.has(msg.type) && !oneShotTypes.has(msg.type)) return false;
 
-    default:
-      return false; // Not handled
+  if (msg.type === 'file_saved') invalidateParentDirCache(agentId, msg.filePath);
+  if (msg.type === 'file_op_result') clearAgentDirCache(agentId);
+  if (msg.type === 'directory_listing' && msg.dirPath && msg.entries && !msg.error) {
+    setCachedDir(agentId, msg.dirPath, msg.entries);
   }
-  return true; // Handled
+
+  if (routeKey) {
+    if (terminalTypes.has(msg.type)) await handleTerminalResponse(agentId, msg, routeKey);
+    else await handleOneShotResponse(agentId, msg, routeKey);
+    return true;
+  }
+
+  // `_workbench:` is reserved for Server-authored route conversations. An
+  // invalid or cross-Agent value is not a legacy conversation.
+  if (typeof msg.conversationId === 'string' && msg.conversationId.startsWith('_workbench:')) {
+    return true;
+  }
+
+  const projected = msg.type === 'file_content' && msg.binary
+    ? cacheBinaryPreview(msg)
+    : msg;
+  await forwardLegacyResponse(agentId, projected);
+  return true;
 }

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

@@ -53,6 +53,9 @@ function syncYeaftSessionMetadata(agentId, agent, event) {
 
   if (event.type === 'session_list_updated') {
     const rows = Array.isArray(event.sessions) ? event.sessions : [];
+    agent.yeaftSessions = new Map(rows
+      .filter(session => session?.id)
+      .map(session => [session.id, { ...session }]));
     try {
       if (ownerId) {
         reconcileAuthoritativeSessionSnapshot(ownerId, agentId, rows);