@yeaft/webchat-agent 1.0.501 → 1.0.503

package/connection/buffer.js

@@ -57,14 +57,62 @@ function bufferMessage(msg, reason) {
   return 'buffered';
 }
 
-async function sendNow(msg) {
-  if (!ctx.ws || ctx.ws.readyState !== WebSocket.OPEN) return bufferMessage(msg, 'Disconnected');
-  if (ctx.serverEncryptionRequired && ctx.sessionKey) {
-    const encrypted = await encrypt(msg, ctx.sessionKey);
-    ctx.ws.send(JSON.stringify(encrypted));
-  } else {
-    ctx.ws.send(JSON.stringify(msg));
+const FILE_CHUNK_SEND_TIMEOUT_MS = 10_000;
+
+function sendFileChunk(socket, data) {
+  // Production uses Node ws; retain compatibility with synchronous, one-argument
+  // transport stubs without treating a real ws.send() return as a flushed write.
+  if (!(socket instanceof WebSocket) && socket.send.length < 2) {
+    socket.send(data);
+    return 'sent';
+  }
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      clearInterval(connectionCheck);
+      socket.removeListener?.('close', onClose);
+      socket.removeListener?.('error', onError);
+      if (error) reject(error);
+      else resolve('sent');
+    };
+    const onClose = () => finish(new Error('WebSocket closed during file chunk send'));
+    const onError = error => finish(error);
+    const connectionChanged = () => socket !== ctx.ws || socket.readyState !== WebSocket.OPEN;
+    const timeout = setTimeout(() => finish(new Error('File chunk send timed out')), FILE_CHUNK_SEND_TIMEOUT_MS);
+    // Replacing ctx.ws need not emit close on the old socket.
+    const connectionCheck = setInterval(() => {
+      if (connectionChanged()) onClose();
+    }, 100);
+    socket.once?.('close', onClose);
+    socket.once?.('error', onError);
+    try {
+      socket.send(data, error => {
+        if (error) finish(error);
+        else if (connectionChanged()) onClose();
+        else finish();
+      });
+    } catch (error) {
+      finish(error);
+    }
+  });
+}
+
+async function sendNow(msg, queuedSocket) {
+  const socket = ctx.ws;
+  if (!socket || socket.readyState !== WebSocket.OPEN) return bufferMessage(msg, 'Disconnected');
+  // File transfers are request/connection scoped, unlike replayable chat output.
+  if (msg.type === 'file_content_chunk' && queuedSocket !== socket) return 'dropped';
+  const payload = ctx.serverEncryptionRequired && ctx.sessionKey
+    ? await encrypt(msg, ctx.sessionKey) : msg;
+  if (socket !== ctx.ws || socket.readyState !== WebSocket.OPEN) {
+    return bufferMessage(msg, 'Connection changed');
   }
+  const data = JSON.stringify(payload);
+  if (msg.type === 'file_content_chunk') return sendFileChunk(socket, data);
+  socket.send(data);
   return 'sent';
 }
 
@@ -78,7 +126,7 @@ function scheduleOutboundDrain() {
         ctx.outboundSendQueueBytes = Math.max(0, Number(ctx.outboundSendQueueBytes || 0) - Number(item?.bytes || 0));
         const msg = item?.msg ?? item;
         try {
-          const outcome = await sendNow(msg);
+          const outcome = await sendNow(msg, item?.socket);
           item?.resolve?.(outcome);
         } catch (e) {
           console.error(`[WS] Error sending message ${msg?.type}:`, e.message);
@@ -113,7 +161,7 @@ export async function sendToServer(msg) {
     return 'dropped';
   }
   const promise = new Promise((resolve, reject) => {
-    ctx.outboundSendQueue.push({ msg, bytes, resolve, reject });
+    ctx.outboundSendQueue.push({ msg, bytes, resolve, reject, socket: msg.type === 'file_content_chunk' ? ctx.ws : null });
     ctx.outboundSendQueueBytes = Number(ctx.outboundSendQueueBytes || 0) + bytes;
   });
   scheduleOutboundDrain();

package/connection/index.js

@@ -8,6 +8,7 @@ import { cleanupTerminalsForDisconnect } from '../terminal.js';
 export function resetConnectionTransport() {
   ctx.sessionKey = null;
   ctx.serverEncryptionRequired = true;
+  ctx.serverCapabilities = new Set();
   ctx.pendingAuthTempId = null;
 }
 

package/connection/message-router.js

@@ -82,6 +82,7 @@ export async function applyLlmConfigUpdate(msg, dependencies = {}) {
 }
 
 export function applyRegisteredTransport(msg) {
+  ctx.serverCapabilities = new Set(Array.isArray(msg.serverCapabilities) ? msg.serverCapabilities : []);
   if (msg.sessionKey) {
     ctx.sessionKey = decodeKey(msg.sessionKey);
     console.log('Encryption enabled');

package/context.js

@@ -20,6 +20,7 @@ export default {
   CONFIG: null,
   managedCliReady: Promise.resolve([]),
   agentCapabilities: [],
+  serverCapabilities: new Set(),
   browserRuntime: null,
   // Agent 级别的 slash commands 缓存（所有 conversation 共用）
   slashCommands: [],

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', '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'];
+  const capabilities = ['background_tasks', 'file_editor', 'ping_session', 'plaintext-ok', 'workbench_session_routes', 'workbench_request_correlation', 'workbench_terminal_cleanup_fence', 'workbench_file_content_chunks', '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/file-content-assembly.js

@@ -0,0 +1,130 @@
+import { MAX_PREVIEW_FILE_BYTES } from './preview-files.js';
+
+const MAX_CHUNK_BYTES = 1024 * 1024;
+const MAX_ASSEMBLIES = 64;
+const MAX_ASSEMBLY_BYTES = 64 * 1024 * 1024;
+const ASSEMBLY_TTL_MS = 2 * 60 * 1000;
+const assemblies = new Map();
+let assemblyBytes = 0;
+
+function key(agentId, requestId) {
+  return `${String(agentId)}\u0000${String(requestId)}`;
+}
+
+function remove(keyValue) {
+  const existing = assemblies.get(keyValue);
+  if (!existing) return;
+  if (existing.timeout) clearTimeout(existing.timeout);
+  assemblyBytes = Math.max(0, assemblyBytes - existing.receivedBytes);
+  assemblies.delete(keyValue);
+}
+
+function invalid(keyValue, status = 'invalid') {
+  remove(keyValue);
+  return { status };
+}
+
+function prune(now = Date.now()) {
+  for (const [keyValue, assembly] of assemblies) {
+    if (assembly.expiresAt <= now) remove(keyValue);
+  }
+}
+
+function decodeChunk(content) {
+  if (typeof content !== 'string' || content.length === 0 || content.length > 1_398_104) return null;
+  if (content.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(content)) return null;
+  const buffer = Buffer.from(content, 'base64');
+  if (buffer.length === 0 || buffer.length > MAX_CHUNK_BYTES) return null;
+  if (buffer.toString('base64') !== content) return null;
+  return buffer;
+}
+
+export function appendFileContentChunk(agentId, msg) {
+  prune();
+  const requestId = msg?._workbenchRequestId;
+  const chunkIndex = Number(msg?.chunkIndex);
+  const chunkCount = Number(msg?.chunkCount);
+  const totalBytes = Number(msg?.totalBytes);
+  if (!agentId || !requestId
+      || !Number.isSafeInteger(chunkIndex) || chunkIndex < 0
+      || !Number.isSafeInteger(chunkCount) || chunkCount < 2 || chunkCount > 20
+      || !Number.isSafeInteger(totalBytes) || totalBytes <= MAX_CHUNK_BYTES
+      || totalBytes > MAX_PREVIEW_FILE_BYTES
+      || chunkIndex >= chunkCount) return { status: 'invalid' };
+  const buffer = decodeChunk(msg.content);
+  if (!buffer) return { status: 'invalid' };
+  const expectedCount = Math.ceil(totalBytes / MAX_CHUNK_BYTES);
+  const expectedBytes = chunkIndex === chunkCount - 1
+    ? totalBytes - (chunkCount - 1) * MAX_CHUNK_BYTES
+    : MAX_CHUNK_BYTES;
+  if (chunkCount !== expectedCount || buffer.length !== expectedBytes) return { status: 'invalid' };
+
+  const keyValue = key(agentId, requestId);
+  let assembly = assemblies.get(keyValue);
+  if (!assembly) {
+    if (chunkIndex !== 0) return { status: 'out_of_order' };
+    if (assemblies.size >= MAX_ASSEMBLIES || assemblyBytes + buffer.length > MAX_ASSEMBLY_BYTES) {
+      return { status: 'capacity' };
+    }
+    assembly = {
+      chunkCount,
+      totalBytes,
+      mimeType: msg.mimeType,
+      filePath: msg.filePath,
+      requestedFilePath: msg.requestedFilePath,
+      conversationId: msg.conversationId,
+      routeKey: msg.workbenchRouteKey,
+      workspaceGeneration: msg.workbenchWorkspaceGeneration,
+      nextIndex: 0,
+      receivedBytes: 0,
+      chunks: [],
+      expiresAt: Date.now() + ASSEMBLY_TTL_MS,
+      timeout: null,
+    };
+    assembly.timeout = setTimeout(() => remove(keyValue), ASSEMBLY_TTL_MS);
+    assembly.timeout.unref?.();
+    assemblies.set(keyValue, assembly);
+  }
+  if (assembly.nextIndex !== chunkIndex) return invalid(keyValue, 'out_of_order');
+  if (assembly.chunkCount !== chunkCount || assembly.totalBytes !== totalBytes
+      || assembly.mimeType !== msg.mimeType || assembly.filePath !== msg.filePath
+      || assembly.requestedFilePath !== msg.requestedFilePath
+      || assembly.conversationId !== msg.conversationId || assembly.routeKey !== msg.workbenchRouteKey
+      || assembly.workspaceGeneration !== msg.workbenchWorkspaceGeneration) {
+    return invalid(keyValue);
+  }
+  if (assemblyBytes + buffer.length > MAX_ASSEMBLY_BYTES) return invalid(keyValue, 'capacity');
+
+  assembly.chunks.push(buffer);
+  assembly.nextIndex += 1;
+  assembly.receivedBytes += buffer.length;
+  assemblyBytes += buffer.length;
+  assembly.expiresAt = Date.now() + ASSEMBLY_TTL_MS;
+  if (assembly.timeout) clearTimeout(assembly.timeout);
+  assembly.timeout = setTimeout(() => remove(keyValue), ASSEMBLY_TTL_MS);
+  assembly.timeout.unref?.();
+  if (assembly.nextIndex !== assembly.chunkCount) return { status: 'pending' };
+  if (assembly.receivedBytes !== assembly.totalBytes) {
+    remove(keyValue);
+    return { status: 'invalid' };
+  }
+  const completed = Buffer.concat(assembly.chunks, assembly.totalBytes);
+  remove(keyValue);
+  return { status: 'complete', buffer: completed };
+}
+
+export function discardFileContentAssembly(agentId, requestId) {
+  remove(key(agentId, requestId));
+}
+
+export function clearFileContentAssembliesForAgent(agentId) {
+  const prefix = `${String(agentId)}\u0000`;
+  for (const keyValue of assemblies.keys()) {
+    if (keyValue.startsWith(prefix)) remove(keyValue);
+  }
+}
+
+export function __testResetFileContentAssemblies() {
+  assemblies.clear();
+  assemblyBytes = 0;
+}

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

@@ -1,6 +1,6 @@
 import { randomUUID } from 'crypto';
 import { CONFIG } from '../config.js';
-import { agents, previewFiles, webClients } from '../context.js';
+import { agents, webClients } from '../context.js';
 import {
   sendToAgent,
   sendToWebClient,
@@ -17,12 +17,16 @@ import {
 import {
   consumeLegacyWorkbenchRequest,
   consumeWorkbenchRequest,
+  peekWorkbenchRequest,
   deleteWorkbenchTerminalOwner,
   getWorkbenchTerminalOwner,
   isLegacyWorkbenchRequestQuarantined,
   registerWorkbenchTerminalOwner,
   workbenchTerminalCleanupMessage,
 } from '../workbench-correlation.js';
+import { appendFileContentChunk, discardFileContentAssembly } from '../file-content-assembly.js';
+import { cachePreviewFile, MAX_PREVIEW_FILE_BYTES } from '../preview-files.js';
+import { createWorkbenchPreview } from '../workbench-preview.js';
 
 function stripAgentRouting(msg) {
   const {
@@ -49,6 +53,10 @@ function pendingResponse(agentId, msg, pending) {
 }
 
 async function sendToPendingClient(agentId, msg, pending) {
+  if (pending?.onResponse) {
+    await pending.onResponse(msg);
+    return true;
+  }
   const client = webClients.get(pending?.clientId);
   if (!client?.authenticated || client.userId !== pending?.userId) return false;
   await sendToWebClient(client, pendingResponse(agentId, msg, pending));
@@ -90,23 +98,40 @@ async function forwardLegacyResponse(agentId, msg) {
   }
 }
 
-function cacheBinaryPreview(msg) {
+function cacheBinaryPreview(msg, suppliedBuffer = null, pending = null) {
+  const buffer = suppliedBuffer || Buffer.from(msg.content || '', 'base64');
+  if (buffer.length > MAX_PREVIEW_FILE_BYTES) return {
+    ...msg,
+    binary: false,
+    content: '',
+    error: 'File exceeds the 20 MB transfer limit.',
+    errorCode: 'FILE_PREVIEW_TOO_LARGE',
+    errorDetails: { sizeBytes: buffer.length, limitBytes: MAX_PREVIEW_FILE_BYTES },
+  };
   const fileId = randomUUID();
-  const token = randomUUID();
+  const stableToken = createWorkbenchPreview(fileId, pending, msg.filePath);
+  const token = stableToken || randomUUID();
   const filename = msg.filePath.split('/').pop() || 'file';
-  previewFiles.set(fileId, {
-    buffer: Buffer.from(msg.content, 'base64'),
+  if (!cachePreviewFile(fileId, {
+    buffer,
     mimeType: msg.mimeType,
     filename,
     createdAt: Date.now(),
     token,
-  });
+  }) && !stableToken) return {
+    ...msg,
+    binary: false,
+    content: '',
+    error: 'Preview cache is at capacity.',
+    errorCode: 'FILE_PREVIEW_CACHE_FULL',
+  };
   const { content: _binaryContent, ...projected } = msg;
   return {
     ...projected,
     binary: true,
     fileId,
     previewToken: token,
+    previewUrl: `/api/preview/${fileId}?token=${encodeURIComponent(token)}`,
   };
 }
 
@@ -177,7 +202,79 @@ async function handleAgentDirectoryPickerResponse(agentId, msg) {
   await sendToPendingClient(agentId, msg, pending);
 }
 
+function hasCurrentWorkspaceGeneration(pending) {
+  const currentGeneration = currentWorkbenchWorkspaceGeneration({
+    route: pending.route,
+    userId: pending.userId,
+    role: pending.role,
+  });
+  return currentGeneration !== null
+    && (!currentGeneration || currentGeneration === pending.workspaceGeneration);
+}
+
+async function handleFileContentChunk(agentId, agent, msg, routeKey) {
+  if (!msg._workbenchRequestId) return;
+  const pending = peekWorkbenchRequest({
+    agentId,
+    requestId: msg._workbenchRequestId,
+    responseType: 'file_content',
+    routeKey,
+  });
+  if (!pending || pending.requestType !== 'read_file') return;
+  if (!hasCurrentWorkspaceGeneration(pending)) {
+    await pending.onResponse?.({ error: 'Preview workspace is no longer available' });
+    discardFileContentAssembly(agentId, msg._workbenchRequestId);
+    consumeWorkbenchRequest({
+      agentId,
+      requestId: msg._workbenchRequestId,
+      responseType: 'file_content',
+      routeKey,
+    });
+    return;
+  }
+  const result = appendFileContentChunk(agentId, msg);
+  if (result.status === 'pending') return;
+  const consumed = consumeWorkbenchRequest({
+    agentId,
+    requestId: msg._workbenchRequestId,
+    responseType: 'file_content',
+    routeKey,
+  });
+  if (!consumed) return;
+  if (result.status !== 'complete') {
+    discardFileContentAssembly(agentId, msg._workbenchRequestId);
+    const errorCode = result.status === 'capacity'
+      ? 'FILE_PREVIEW_CACHE_FULL'
+      : 'FILE_TRANSFER_INVALID';
+    await sendToPendingClient(agentId, {
+      ...msg,
+      type: 'file_content',
+      binary: false,
+      content: '',
+      error: result.status === 'capacity'
+        ? 'Preview transfer capacity was exceeded.'
+        : 'Preview transfer was incomplete or invalid.',
+      errorCode,
+    }, consumed);
+    return;
+  }
+  const completed = {
+    ...msg,
+    type: 'file_content',
+    content: '',
+  };
+  delete completed.chunkIndex;
+  delete completed.chunkCount;
+  delete completed.totalBytes;
+  await sendToPendingClient(agentId, consumed.onResponse
+    ? { ...completed, buffer: result.buffer }
+    : cacheBinaryPreview(completed, result.buffer, consumed), consumed);
+}
+
 async function handleOneShotResponse(agentId, agent, msg, routeKey) {
+  if (msg.type === 'file_content' && msg._workbenchRequestId) {
+    discardFileContentAssembly(agentId, msg._workbenchRequestId);
+  }
   const pending = consumeRouteResponse(agentId, agent, msg, routeKey);
   if (!pending) return;
   const currentGeneration = currentWorkbenchWorkspaceGeneration({
@@ -185,10 +282,12 @@ async function handleOneShotResponse(agentId, agent, msg, routeKey) {
     userId: pending.userId,
     role: pending.role,
   });
-  if (currentGeneration === null) return;
-  if (currentGeneration && currentGeneration !== pending.workspaceGeneration) return;
-  const projected = msg.type === 'file_content' && msg.binary
-    ? cacheBinaryPreview(msg)
+  if (currentGeneration === null || (currentGeneration && currentGeneration !== pending.workspaceGeneration)) {
+    await pending.onResponse?.({ error: 'Preview workspace is no longer available' });
+    return;
+  }
+  const projected = msg.type === 'file_content' && msg.binary && !pending.onResponse
+    ? cacheBinaryPreview(msg, null, pending)
     : msg;
   await sendToPendingClient(agentId, projected, pending);
 }
@@ -205,7 +304,7 @@ export async function handleAgentFileTerminal(agentId, agent, rawMsg) {
     'terminal_created', 'terminal_output', 'terminal_closed', 'terminal_error',
   ]);
   const oneShotTypes = new Set([
-    'file_content', 'file_references_resolved', 'file_saved', 'directory_listing', 'file_op_result',
+    'file_content', 'file_content_chunk', 'file_references_resolved', '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;
@@ -218,6 +317,7 @@ export async function handleAgentFileTerminal(agentId, agent, rawMsg) {
 
   if (routeKey) {
     if (terminalTypes.has(msg.type)) await handleTerminalResponse(agentId, agent, msg, routeKey);
+    else if (msg.type === 'file_content_chunk') await handleFileContentChunk(agentId, agent, msg, routeKey);
     else await handleOneShotResponse(agentId, agent, msg, routeKey);
     return true;
   }

package/local-runtime/server/preview-files.js

@@ -0,0 +1,33 @@
+import { previewFiles } from './context.js';
+
+export const MAX_PREVIEW_FILE_BYTES = 20 * 1024 * 1024;
+export const PREVIEW_FILE_TTL_MS = 10 * 60 * 1000;
+export const MAX_PREVIEW_CACHE_BYTES = 128 * 1024 * 1024;
+export const MAX_PREVIEW_CACHE_FILES = 256;
+
+function entryBytes(entry) {
+  return Buffer.isBuffer(entry?.buffer) ? entry.buffer.length : 0;
+}
+
+export function prunePreviewFiles(now = Date.now()) {
+  const cutoff = now - PREVIEW_FILE_TTL_MS;
+  for (const [id, file] of previewFiles) {
+    if (!file || file.createdAt < cutoff) previewFiles.delete(id);
+  }
+}
+
+export function cachePreviewFile(fileId, file) {
+  if (!fileId || !Buffer.isBuffer(file?.buffer)) return false;
+  if (file.buffer.length > MAX_PREVIEW_FILE_BYTES) return false;
+  prunePreviewFiles();
+  let totalBytes = 0;
+  for (const value of previewFiles.values()) totalBytes += entryBytes(value);
+  const existingBytes = entryBytes(previewFiles.get(fileId));
+  const isNewEntry = !previewFiles.has(fileId);
+  if ((isNewEntry && previewFiles.size >= MAX_PREVIEW_CACHE_FILES)
+      || totalBytes - existingBytes + file.buffer.length > MAX_PREVIEW_CACHE_BYTES) {
+    return false;
+  }
+  previewFiles.set(fileId, { ...file, createdAt: file.createdAt || Date.now() });
+  return true;
+}

package/local-runtime/server/routes/upload-routes.js

@@ -3,7 +3,9 @@ import multer from 'multer';
 import { CONFIG } from '../config.js';
 import { userDb } from '../database.js';
 import { pendingFiles, previewFiles } from '../context.js';
+import { PREVIEW_FILE_TTL_MS, prunePreviewFiles } from '../preview-files.js';
 import { yeaftAssetStore } from '../yeaft-asset-store.js';
+import { readWorkbenchPreview } from '../workbench-preview.js';
 
 // 文件上传配置 (存储在内存中)
 const upload = multer({
@@ -41,13 +43,8 @@ setInterval(() => {
   }
 }, 60 * 1000);
 
-// Cleanup expired preview files every 60s (10 min TTL)
-setInterval(() => {
-  const cutoff = Date.now() - 10 * 60 * 1000;
-  for (const [id, f] of previewFiles) {
-    if (f.createdAt < cutoff) previewFiles.delete(id);
-  }
-}, 60 * 1000);
+// Cleanup expired preview files every 60s.
+setInterval(() => prunePreviewFiles(), Math.min(60 * 1000, PREVIEW_FILE_TTL_MS));
 
 /**
  * Register file upload and preview routes.
@@ -82,8 +79,16 @@ export function registerUploadRoutes(app, { requireAuth }) {
     res.json({ files: uploaded });
   });
 
-  app.get('/api/preview/:fileId', (req, res) => {
-    const file = previewFiles.get(req.params.fileId);
+  app.get('/api/preview/:fileId', async (req, res) => {
+    let file;
+    try {
+      file = typeof req.query.token === 'string' && req.query.token.startsWith('wb1.')
+        ? await readWorkbenchPreview(req.params.fileId, req.query.token)
+        : previewFiles.get(req.params.fileId);
+    } catch (error) {
+      res.setHeader('Cache-Control', 'no-store');
+      return res.status(error.status || 502).send(error.status ? error.message : 'Preview read failed');
+    }
     if (!file) return res.status(404).send('File not found or expired');
     if (file.token && req.query.token !== file.token) {
       return res.status(403).send('Forbidden');

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

@@ -113,6 +113,7 @@ export function registerWorkbenchRequest({
   terminalId = null,
   allowLegacyCorrelation = false,
   onTimeout = null,
+  onResponse = null,
 }) {
   if (!agentId || !clientId || !userId || !routeKey || !conversationId
       || !workspaceGeneration || !requestType) return null;
@@ -144,6 +145,7 @@ export function registerWorkbenchRequest({
     terminalId,
     allowLegacyCorrelation: allowLegacyCorrelation === true,
     onTimeout,
+    onResponse,
     expiresAt: Date.now() + REQUEST_TTL_MS,
     timeout: null,
   };
@@ -162,6 +164,15 @@ function consumePending(key, pending) {
   return pending;
 }
 
+export function peekWorkbenchRequest({ agentId, requestId, responseType, routeKey = null }) {
+  if (!agentId || !requestId || !responseType) return null;
+  prune();
+  const pending = pendingRequests.get(requestKey(agentId, requestId));
+  if (!pending || !pending.expectedResponseTypes.has(responseType)) return null;
+  if (routeKey && pending.routeKey !== routeKey) return null;
+  return pending;
+}
+
 export function consumeWorkbenchRequest({ agentId, requestId, responseType, routeKey = null }) {
   if (!agentId || !requestId || !responseType) return null;
   prune();
@@ -317,6 +328,7 @@ export function clearWorkbenchCorrelationsForAgent(agentId) {
   if (!agentId) return;
   for (const [key, pending] of pendingRequests) {
     if (pending?.agentId !== agentId) continue;
+    if (pending.onResponse) pending.onTimeout?.(pending, 'disconnect');
     pendingRequests.delete(key);
     if (pending.timeout) clearTimeout(pending.timeout);
     pending.timeout = null;