@yeaft/webchat-agent 1.0.490 → 1.0.491

package/index.js

@@ -177,7 +177,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', 'session_history_search', 'session_history_outline', 'session_history_window_prefetch', 'file_reference_resolution', 'yeaft_plugins', 'yeaft_managed_skills', 'settings_request_correlation'];
+  const capabilities = ['background_tasks', 'file_editor', 'ping_session', 'plaintext-ok', 'workbench_session_routes', 'workbench_request_correlation', 'workbench_terminal_cleanup_fence', '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 (isWorkCenterEnabled()) {
     capabilities.push('work_center', 'work_center_message_v2');

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

@@ -9,14 +9,19 @@ import {
   clearAgentDirCache,
 } from '../ws-utils.js';
 import {
+  agentSupportsWorkbenchRequestCorrelation,
+  agentSupportsWorkbenchTerminalCleanupFence,
   currentWorkbenchWorkspaceGeneration,
   workbenchRouteKeyFromConversationId,
 } from '../workbench-route.js';
 import {
+  consumeLegacyWorkbenchRequest,
   consumeWorkbenchRequest,
   deleteWorkbenchTerminalOwner,
   getWorkbenchTerminalOwner,
+  isLegacyWorkbenchRequestQuarantined,
   registerWorkbenchTerminalOwner,
+  workbenchTerminalCleanupMessage,
 } from '../workbench-correlation.js';
 
 function stripAgentRouting(msg) {
@@ -50,6 +55,28 @@ async function sendToPendingClient(agentId, msg, pending) {
   return true;
 }
 
+function consumeRouteResponse(agentId, agent, msg, routeKey) {
+  if (msg._workbenchRequestId) {
+    return consumeWorkbenchRequest({
+      agentId,
+      requestId: msg._workbenchRequestId,
+      responseType: msg.type,
+      routeKey,
+    });
+  }
+  const agentRecord = agents.get(agentId) || agent;
+  if (agentSupportsWorkbenchRequestCorrelation(agentRecord)) return null;
+  return consumeLegacyWorkbenchRequest({
+    agentId,
+    responseType: msg.type,
+    routeKey,
+    userId: msg._requestUserId,
+    clientId: msg._requestClientId || null,
+    publicRequestId: typeof msg.requestId === 'string' ? msg.requestId : null,
+    terminalId: msg.terminalId || null,
+  });
+}
+
 async function forwardLegacyResponse(agentId, msg) {
   const visible = { ...stripAgentRouting(msg), agentId };
   const agent = agents.get(agentId);
@@ -83,25 +110,25 @@ function cacheBinaryPreview(msg) {
   };
 }
 
-async function handleTerminalResponse(agentId, msg, routeKey) {
+async function handleTerminalResponse(agentId, agent, 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 pending = consumeRouteResponse(agentId, agent, msg, routeKey);
+    const quarantined = isLegacyWorkbenchRequestQuarantined(pending);
+    if (!pending || quarantined) {
       const agentRecord = agents.get(agentId);
-      if (agentRecord && terminalId && msg.workbenchWorkspaceGeneration) {
-        await sendToAgent(agentRecord, {
-          type: 'terminal_close',
-          conversationId: msg.conversationId,
-          terminalId,
-          workbenchRouteKey: routeKey,
-          workbenchWorkspaceGeneration: msg.workbenchWorkspaceGeneration,
-        });
+      const cleanup = quarantined ? pending : {
+        requestId: msg._workbenchRequestId || null,
+        conversationId: msg.conversationId,
+        routeKey,
+        workspaceGeneration: msg.workbenchWorkspaceGeneration,
+        terminalId,
+      };
+      const closeMessage = workbenchTerminalCleanupMessage(cleanup);
+      if (agentRecord
+          && closeMessage
+          && agentSupportsWorkbenchTerminalCleanupFence(agentRecord)) {
+        await sendToAgent(agentRecord, closeMessage);
       }
       return;
     }
@@ -117,16 +144,18 @@ async function handleTerminalResponse(agentId, msg, routeKey) {
 
   // 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 (msg.type === 'terminal_error') {
+    const pending = consumeRouteResponse(agentId, agent, msg, routeKey);
+    // Explicit opaque ids and quarantined legacy replies must never fall
+    // through to terminal ownership. A quarantine tombstone describes the
+    // expired create, not any same-id replacement owner.
+    if (isLegacyWorkbenchRequestQuarantined(pending)) return;
     if (pending?.terminalId) deleteWorkbenchTerminalOwner(agentId, pending.terminalId);
-    if (pending?.routeKey === routeKey) await sendToPendingClient(agentId, msg, pending);
-    return;
+    if (pending?.routeKey === routeKey) {
+      await sendToPendingClient(agentId, msg, pending);
+      return;
+    }
+    if (msg._workbenchRequestId) return;
   }
 
   const owner = terminalId ? getWorkbenchTerminalOwner(agentId, terminalId) : null;
@@ -148,13 +177,8 @@ async function handleAgentDirectoryPickerResponse(agentId, msg) {
   await sendToPendingClient(agentId, msg, pending);
 }
 
-async function handleOneShotResponse(agentId, msg, routeKey) {
-  const pending = consumeWorkbenchRequest({
-    agentId,
-    requestId: msg._workbenchRequestId,
-    responseType: msg.type,
-    routeKey,
-  });
+async function handleOneShotResponse(agentId, agent, msg, routeKey) {
+  const pending = consumeRouteResponse(agentId, agent, msg, routeKey);
   if (!pending) return;
   const currentGeneration = currentWorkbenchWorkspaceGeneration({
     route: pending.route,
@@ -192,8 +216,8 @@ export async function handleAgentFileTerminal(agentId, agent, rawMsg) {
   }
 
   if (routeKey) {
-    if (terminalTypes.has(msg.type)) await handleTerminalResponse(agentId, msg, routeKey);
-    else await handleOneShotResponse(agentId, msg, routeKey);
+    if (terminalTypes.has(msg.type)) await handleTerminalResponse(agentId, agent, msg, routeKey);
+    else await handleOneShotResponse(agentId, agent, msg, routeKey);
     return true;
   }
 
@@ -204,6 +228,10 @@ export async function handleAgentFileTerminal(agentId, agent, rawMsg) {
     return true;
   }
 
+  // Opaque correlation ids are Server-owned. A response carrying one cannot
+  // downgrade to legacy routing when its conversation is invalid or stale.
+  if (msg._workbenchRequestId) 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:')) {

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

@@ -190,6 +190,9 @@ export async function handleClientMisc(clientId, client, msg, checkAgentAccess)
           conversationId: resolved.conversationId || msg.conversationId || client.currentConversation,
           workbenchRouteKey: resolved.routeKey,
           workbenchWorkspaceGeneration: resolved.workspaceGeneration,
+          restoreRequestId: typeof msg.restoreRequestId === 'string'
+            ? msg.restoreRequestId
+            : null,
           openFiles: saved?.files || [],
           activeIndex: saved?.activeIndex || 0
         });

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

@@ -4,7 +4,10 @@ import {
   sendToWebClient, forwardToAgent,
   verifyConversationOwnership, getCachedDir
 } from '../ws-utils.js';
-import { resolveWorkbenchRequest } from '../workbench-route.js';
+import {
+  agentSupportsWorkbenchRequestCorrelation,
+  resolveWorkbenchRequest,
+} from '../workbench-route.js';
 import {
   deleteWorkbenchRequest,
   getWorkbenchTerminalOwner,
@@ -61,6 +64,82 @@ const RESPONSE_TYPES = Object.freeze({
   upload_to_dir: ['file_op_result'],
 });
 
+const TIMEOUT_RESPONSE_TYPES = Object.freeze({
+  terminal_create: 'terminal_error',
+  read_file: 'file_content',
+  resolve_file_references: 'file_references_resolved',
+  write_file: 'file_saved',
+  list_directory: 'directory_listing',
+  git_status: 'git_status_result',
+  git_diff: 'git_diff_result',
+  git_add: 'git_op_result',
+  git_reset: 'git_op_result',
+  git_restore: 'git_op_result',
+  git_commit: 'git_op_result',
+  git_push: 'git_op_result',
+  file_search: 'file_search_result',
+  create_file: 'file_op_result',
+  delete_files: 'file_op_result',
+  move_files: 'file_op_result',
+  copy_files: 'file_op_result',
+  upload_to_dir: 'file_op_result',
+});
+
+const FILE_OPERATIONS = Object.freeze({
+  create_file: 'create',
+  delete_files: 'delete',
+  move_files: 'move',
+  copy_files: 'copy',
+  upload_to_dir: 'upload',
+});
+
+function workbenchTimeoutResponse({ agentId, msg, resolved }) {
+  const type = TIMEOUT_RESPONSE_TYPES[msg.type];
+  if (!type) return null;
+  const error = 'Workbench request timed out';
+  const response = {
+    type,
+    agentId,
+    conversationId: resolved.conversationId,
+    workbenchRouteKey: resolved.routeKey,
+    workbenchWorkspaceGeneration: resolved.workspaceGeneration,
+    ...(typeof msg.requestId === 'string' ? { requestId: msg.requestId } : {}),
+    error,
+  };
+  if (msg.type === 'terminal_create') {
+    return { ...response, terminalId: msg.terminalId || null, message: error };
+  }
+  if (msg.type === 'read_file') {
+    return { ...response, filePath: msg.filePath };
+  }
+  if (msg.type === 'resolve_file_references') {
+    return { ...response, references: [] };
+  }
+  if (msg.type === 'write_file') {
+    return { ...response, filePath: msg.filePath, requestedFilePath: msg.filePath };
+  }
+  if (msg.type === 'list_directory') {
+    return { ...response, dirPath: msg.dirPath, entries: [] };
+  }
+  if (msg.type === 'git_status') {
+    return { ...response, files: [] };
+  }
+  if (msg.type === 'git_diff') {
+    return { ...response, diff: '' };
+  }
+  if (msg.type.startsWith('git_')) {
+    return { ...response, success: false, operation: msg.type.slice(4) };
+  }
+  if (msg.type === 'file_search') {
+    return { ...response, query: msg.query, results: [] };
+  }
+  return {
+    ...response,
+    success: false,
+    operation: FILE_OPERATIONS[msg.type] || msg.type,
+  };
+}
+
 function canonicalWorkbenchMessage(msg, resolved, { canonicalWorkDir = false } = {}) {
   const {
     _requestUserId: _ignoredUserId,
@@ -93,6 +172,7 @@ function correlateWorkbenchRequest({ agentId, clientId, client, msg, resolved, c
   }
   const expectedResponseTypes = RESPONSE_TYPES[msg.type];
   if (!expectedResponseTypes) return canonical;
+  const supportsRequestCorrelation = agentSupportsWorkbenchRequestCorrelation(agents.get(agentId));
   const registration = {
     agentId,
     clientId,
@@ -106,6 +186,12 @@ function correlateWorkbenchRequest({ agentId, clientId, client, msg, resolved, c
     expectedResponseTypes,
     publicRequestId: typeof msg.requestId === 'string' ? msg.requestId : null,
     terminalId: msg.terminalId || null,
+    allowLegacyCorrelation: !supportsRequestCorrelation,
+    onTimeout: async () => {
+      if (!client.authenticated || client.userId !== registration.userId) return;
+      const response = workbenchTimeoutResponse({ agentId, msg, resolved });
+      if (response) await sendToWebClient(client, response);
+    },
   };
   const requestId = registerWorkbenchRequest(registration);
   if (!requestId) return null;
@@ -114,7 +200,14 @@ function correlateWorkbenchRequest({ agentId, clientId, client, msg, resolved, c
     deleteWorkbenchRequest({ agentId, requestId });
     return null;
   }
-  return { ...canonical, _workbenchRequestId: requestId };
+  return {
+    ...canonical,
+    _workbenchRequestId: requestId,
+    ...(!supportsRequestCorrelation ? {
+      _requestUserId: client.userId,
+      _requestClientId: clientId,
+    } : {}),
+  };
 }
 
 async function forwardCorrelatedWorkbenchRequest({ agentId, clientId, client, msg, resolved, canonical }) {

package/local-runtime/server/workbench-correlation.js

@@ -4,8 +4,31 @@ const REQUEST_TTL_MS = 2 * 60 * 1000;
 const MAX_PENDING = 4096;
 
 const pendingRequests = new Map();
+const expiredRequests = new Map();
 const terminalOwners = new Map();
 
+export const LEGACY_WORKBENCH_REQUEST_QUARANTINED = Symbol(
+  'legacy-workbench-request-quarantined',
+);
+
+export function isLegacyWorkbenchRequestQuarantined(value) {
+  return value?.quarantine === LEGACY_WORKBENCH_REQUEST_QUARANTINED;
+}
+
+export function workbenchTerminalCleanupMessage(owner) {
+  if (!owner?.terminalId || !owner?.conversationId || !owner?.routeKey
+      || !owner?.workspaceGeneration) return null;
+  const requestId = owner.requestId || owner.pendingRequestId || null;
+  return {
+    type: 'terminal_close',
+    conversationId: owner.conversationId,
+    terminalId: owner.terminalId,
+    workbenchRouteKey: owner.routeKey,
+    workbenchWorkspaceGeneration: owner.workspaceGeneration,
+    ...(requestId ? { _workbenchRequestId: requestId } : {}),
+  };
+}
+
 function requestKey(agentId, requestId) {
   return `${String(agentId || '')}\u0000${String(requestId || '')}`;
 }
@@ -22,11 +45,56 @@ function releasePendingTerminalReservation(pending) {
   if (owner?.pendingRequestId === pending.requestId) terminalOwners.delete(key);
 }
 
+function pruneExpiredRequests(now = Date.now()) {
+  for (const [key, expired] of expiredRequests) {
+    if (expired?.expiresAt > now) continue;
+    expiredRequests.delete(key);
+  }
+}
+
+function quarantineExpiredRequest(key, pending, now = Date.now()) {
+  if (!pending?.allowLegacyCorrelation) return;
+  pruneExpiredRequests(now);
+  while (expiredRequests.size >= MAX_PENDING) {
+    const oldest = expiredRequests.keys().next().value;
+    if (oldest == null) break;
+    expiredRequests.delete(oldest);
+  }
+  expiredRequests.set(key, {
+    agentId: pending.agentId,
+    requestId: pending.requestId,
+    conversationId: pending.conversationId,
+    workspaceGeneration: pending.workspaceGeneration,
+    responseTypes: new Set(pending.expectedResponseTypes),
+    routeKey: pending.routeKey,
+    userId: pending.userId,
+    clientId: pending.clientId,
+    publicRequestId: pending.publicRequestId,
+    terminalId: pending.terminalId,
+    expiresAt: now + REQUEST_TTL_MS,
+  });
+}
+
+function expirePending(key, pending, reason = 'timeout') {
+  if (pendingRequests.get(key) !== pending) return false;
+  pendingRequests.delete(key);
+  if (pending.timeout) clearTimeout(pending.timeout);
+  pending.timeout = null;
+  releasePendingTerminalReservation(pending);
+  quarantineExpiredRequest(key, pending);
+  if (typeof pending?.onTimeout === 'function') {
+    Promise.resolve(pending.onTimeout(pending, reason)).catch(error => {
+      console.error('[Server] Failed to report Workbench request timeout:', error);
+    });
+  }
+  return true;
+}
+
 function prune(now = Date.now()) {
+  pruneExpiredRequests(now);
   for (const [key, pending] of pendingRequests) {
     if (pending && pending.expiresAt > now) continue;
-    pendingRequests.delete(key);
-    releasePendingTerminalReservation(pending);
+    expirePending(key, pending);
   }
 }
 
@@ -43,6 +111,8 @@ export function registerWorkbenchRequest({
   expectedResponseTypes,
   publicRequestId = null,
   terminalId = null,
+  allowLegacyCorrelation = false,
+  onTimeout = null,
 }) {
   if (!agentId || !clientId || !userId || !routeKey || !conversationId
       || !workspaceGeneration || !requestType) return null;
@@ -54,9 +124,7 @@ export function registerWorkbenchRequest({
   while (pendingRequests.size >= MAX_PENDING) {
     const oldest = pendingRequests.keys().next().value;
     if (oldest == null) break;
-    const evicted = pendingRequests.get(oldest);
-    pendingRequests.delete(oldest);
-    releasePendingTerminalReservation(evicted);
+    expirePending(oldest, pendingRequests.get(oldest), 'capacity');
   }
   const requestId = randomUUID();
   const key = requestKey(agentId, requestId);
@@ -74,20 +142,26 @@ export function registerWorkbenchRequest({
     expectedResponseTypes: new Set(expected),
     publicRequestId,
     terminalId,
+    allowLegacyCorrelation: allowLegacyCorrelation === true,
+    onTimeout,
     expiresAt: Date.now() + REQUEST_TTL_MS,
     timeout: null,
   };
   pending.timeout = setTimeout(() => {
-    const current = pendingRequests.get(key);
-    if (current !== pending) return;
-    pendingRequests.delete(key);
-    releasePendingTerminalReservation(pending);
+    expirePending(key, pending);
   }, REQUEST_TTL_MS);
   pending.timeout.unref?.();
   pendingRequests.set(key, pending);
   return requestId;
 }
 
+function consumePending(key, pending) {
+  pendingRequests.delete(key);
+  if (pending.timeout) clearTimeout(pending.timeout);
+  pending.timeout = null;
+  return pending;
+}
+
 export function consumeWorkbenchRequest({ agentId, requestId, responseType, routeKey = null }) {
   if (!agentId || !requestId || !responseType) return null;
   prune();
@@ -95,17 +169,90 @@ export function consumeWorkbenchRequest({ agentId, requestId, responseType, rout
   const pending = pendingRequests.get(key);
   if (!pending || !pending.expectedResponseTypes.has(responseType)) return null;
   if (routeKey && pending.routeKey !== routeKey) return null;
-  pendingRequests.delete(key);
-  if (pending.timeout) clearTimeout(pending.timeout);
-  pending.timeout = null;
-  return pending;
+  return consumePending(key, pending);
+}
+
+/**
+ * Correlate responses from the short-lived Agent release window that supported
+ * Session Workbench routes but did not echo `_workbenchRequestId`. Agent fields
+ * only filter Server-owned pending records; they never directly select a Web
+ * client. Ambiguous matches are intentionally left pending to time out.
+ */
+function matchesLegacyCorrelation(record, {
+  agentId,
+  responseType,
+  routeKey,
+  userId,
+  clientId,
+  publicRequestId,
+  terminalId,
+}, responseTypes) {
+  if (record.agentId !== agentId
+      || record.routeKey !== routeKey
+      || record.userId !== userId
+      || !responseTypes?.has(responseType)) return false;
+  if (clientId && record.clientId !== clientId) return false;
+  if (publicRequestId && record.publicRequestId !== publicRequestId) return false;
+  if (terminalId && record.terminalId !== terminalId) return false;
+  return true;
+}
+
+export function consumeLegacyWorkbenchRequest({
+  agentId,
+  responseType,
+  routeKey,
+  userId,
+  clientId = null,
+  publicRequestId = null,
+  terminalId = null,
+}) {
+  if (!agentId || !responseType || !routeKey || !userId) return null;
+  const correlation = {
+    agentId,
+    responseType,
+    routeKey,
+    userId,
+    clientId,
+    publicRequestId,
+    terminalId,
+  };
+  prune();
+  for (const [key, expired] of expiredRequests) {
+    if (!matchesLegacyCorrelation(expired, correlation, expired.responseTypes)) continue;
+    // A public request id identifies the expired request exactly, so one late
+    // response can retire its tombstone. Without one, old and retried responses
+    // are indistinguishable; keep the quarantine until TTL rather than risk
+    // consuming a newer pending request.
+    if (publicRequestId) expiredRequests.delete(key);
+    return {
+      quarantine: LEGACY_WORKBENCH_REQUEST_QUARANTINED,
+      agentId: expired.agentId,
+      requestId: expired.requestId,
+      conversationId: expired.conversationId,
+      routeKey: expired.routeKey,
+      workspaceGeneration: expired.workspaceGeneration,
+      terminalId: expired.terminalId,
+    };
+  }
+  const matches = [];
+  for (const [key, pending] of pendingRequests) {
+    if (!matchesLegacyCorrelation(pending, correlation, pending.expectedResponseTypes)) continue;
+    matches.push([key, pending]);
+    if (matches.length > 1) return null;
+  }
+  if (matches.length !== 1) return null;
+  return consumePending(matches[0][0], matches[0][1]);
 }
 
 export function deleteWorkbenchRequest({ agentId, requestId }) {
   const key = requestKey(agentId, requestId);
   const pending = pendingRequests.get(key);
   const deleted = pendingRequests.delete(key);
-  if (deleted) releasePendingTerminalReservation(pending);
+  if (deleted) {
+    if (pending.timeout) clearTimeout(pending.timeout);
+    pending.timeout = null;
+    releasePendingTerminalReservation(pending);
+  }
   return deleted;
 }
 
@@ -144,17 +291,25 @@ export function deleteWorkbenchTerminalOwner(agentId, terminalId) {
 
 export function clearWorkbenchCorrelationsForClient(clientId) {
   if (!clientId) return [];
-  for (const [key, pending] of pendingRequests) {
-    if (pending?.clientId !== clientId) continue;
-    pendingRequests.delete(key);
-    releasePendingTerminalReservation(pending);
-  }
+  // Capture terminal cleanup capabilities before releasing pending creates.
+  // releasePendingTerminalReservation() removes the matching owner, but the
+  // disconnect path still needs its exact create token to cancel Agent work.
   const terminals = [];
   for (const [key, owner] of terminalOwners) {
     if (owner?.clientId !== clientId) continue;
     terminals.push(owner);
     terminalOwners.delete(key);
   }
+  for (const [key, pending] of pendingRequests) {
+    if (pending?.clientId !== clientId) continue;
+    pendingRequests.delete(key);
+    if (pending.timeout) clearTimeout(pending.timeout);
+    pending.timeout = null;
+    releasePendingTerminalReservation(pending);
+  }
+  for (const [key, expired] of expiredRequests) {
+    if (expired?.clientId === clientId) expiredRequests.delete(key);
+  }
   return terminals;
 }
 
@@ -163,16 +318,26 @@ export function clearWorkbenchCorrelationsForAgent(agentId) {
   for (const [key, pending] of pendingRequests) {
     if (pending?.agentId !== agentId) continue;
     pendingRequests.delete(key);
+    if (pending.timeout) clearTimeout(pending.timeout);
+    pending.timeout = null;
     releasePendingTerminalReservation(pending);
   }
+  for (const [key, expired] of expiredRequests) {
+    if (expired?.agentId === agentId) expiredRequests.delete(key);
+  }
   for (const [key, owner] of terminalOwners) {
     if (owner?.agentId === agentId) terminalOwners.delete(key);
   }
 }
 
 export function __testResetWorkbenchCorrelations() {
-  for (const pending of pendingRequests.values()) releasePendingTerminalReservation(pending);
+  for (const pending of pendingRequests.values()) {
+    if (pending.timeout) clearTimeout(pending.timeout);
+    pending.timeout = null;
+    releasePendingTerminalReservation(pending);
+  }
   pendingRequests.clear();
+  expiredRequests.clear();
   terminalOwners.clear();
 }
 

package/local-runtime/server/workbench-route.js

@@ -4,6 +4,20 @@ import { sessionDb } from './db/session-db.js';
 import { yeaftSessionDb } from './db/yeaft-session-db.js';
 
 export const WORKBENCH_SESSION_ROUTE_CAPABILITY = 'workbench_session_routes';
+export const WORKBENCH_REQUEST_CORRELATION_CAPABILITY = 'workbench_request_correlation';
+export const WORKBENCH_TERMINAL_CLEANUP_FENCE_CAPABILITY = 'workbench_terminal_cleanup_fence';
+
+function agentHasCapability(agent, capability) {
+  return Array.isArray(agent?.capabilities) && agent.capabilities.includes(capability);
+}
+
+export function agentSupportsWorkbenchRequestCorrelation(agent) {
+  return agentHasCapability(agent, WORKBENCH_REQUEST_CORRELATION_CAPABILITY);
+}
+
+export function agentSupportsWorkbenchTerminalCleanupFence(agent) {
+  return agentHasCapability(agent, WORKBENCH_TERMINAL_CLEANUP_FENCE_CAPABILITY);
+}
 
 const PROVIDERS = new Set(['yeaft', 'claude-code', 'copilot']);
 const SCOPES = new Set(['main', 'files-folder-picker', 'git-folder-picker']);

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

@@ -17,7 +17,11 @@ import {
   BROWSER_RUNTIME_SETUP_PROTOCOL,
   WORKBENCH_ROUTE_PROTOCOL,
 } from './client-protocol.js';
-import { clearWorkbenchCorrelationsForClient } from './workbench-correlation.js';
+import {
+  clearWorkbenchCorrelationsForClient,
+  workbenchTerminalCleanupMessage,
+} from './workbench-correlation.js';
+import { agentSupportsWorkbenchTerminalCleanupFence } from './workbench-route.js';
 import { clearBrowserRuntimeForClient } from './browser-runtime-routes.js';
 import {
   parseMessage, sendToWebClient, sendToAgent,
@@ -30,6 +34,17 @@ import { handleClientMisc } from './handlers/client-misc.js';
 import { clearWorkCenterRequestsForClient, handleClientWorkCenter } from './handlers/client-work-center.js';
 import { recordPerfTraceEvent } from './perf-trace.js';
 
+export function cleanupWorkbenchForDisconnectedClient(clientId) {
+  const ownedTerminals = clearWorkbenchCorrelationsForClient(clientId);
+  for (const owner of ownedTerminals) {
+    const agent = agents.get(owner.agentId);
+    const closeMessage = workbenchTerminalCleanupMessage(owner);
+    if (!agent || !closeMessage || !agentSupportsWorkbenchTerminalCleanupFence(agent)) continue;
+    void sendToAgent(agent, closeMessage)
+      .catch(error => console.warn('[Workbench] PTY disconnect cleanup failed:', error.message));
+  }
+}
+
 export function handleWebConnection(ws, url, req = {}) {
   const clientId = randomUUID();
 
@@ -203,18 +218,7 @@ export function handleWebConnection(ws, url, req = {}) {
         },
       }).catch(error => console.warn('[BrowserRuntime] peer disconnect cleanup failed:', error.message));
     }
-    const ownedTerminals = clearWorkbenchCorrelationsForClient(clientId);
-    for (const owner of ownedTerminals) {
-      const agent = agents.get(owner.agentId);
-      if (!agent) continue;
-      void sendToAgent(agent, {
-        type: 'terminal_close',
-        terminalId: owner.terminalId,
-        conversationId: owner.conversationId,
-        workbenchRouteKey: owner.routeKey,
-        workbenchWorkspaceGeneration: owner.workspaceGeneration,
-      }).catch(error => console.warn('[Workbench] PTY disconnect cleanup failed:', error.message));
-    }
+    cleanupWorkbenchForDisconnectedClient(clientId);
     webClients.delete(clientId);
     console.log(`Web client disconnected: ${clientId}`);
   });

package/local-runtime/version.json

@@ -1 +1 @@
-{"version":"1.0.490"}
+{"version":"1.0.491"}