farming-code 2.2.23 → 2.2.28

package/backend/server.js

@@ -42,6 +42,10 @@ const { createControlRouter } = require('./control-api');
 const { WorkspaceFileService, WorkspaceFileError } = require('./workspace-file-service');
 const { createWorkspaceFileRouter, resolveWorkspaceRoot } = require('./workspace-file-router');
 const { WorkspaceRootRegistry, rootIdForPath } = require('./workspace-root-registry');
+const {
+  BrowserResourceManager,
+  createBrowserRouter,
+} = require('../extensions/browser/backend');
 const { UsageMonitor } = require('./usage-monitor');
 const { CodexContextWindowReader } = require('./codex-context-window');
 const { DEFAULT_MAX_TURNS: DEFAULT_CODEX_TRANSCRIPT_MAX_TURNS, readCodexTranscript } = require('./codex-transcript');
@@ -129,6 +133,11 @@ async function requireAgentRecoveryForHttp(res) {
 const themeManager = new ThemeManager({ configDir: configManager.farmingDir });
 const workspaceFileService = new WorkspaceFileService();
 const workspaceRootRegistry = new WorkspaceRootRegistry(agentManager);
+const browserResourceManager = new BrowserResourceManager({
+  configDir: configManager.farmingDir,
+  isEnabled: () => configManager.getSettings().browserExtensionEnabled === true,
+});
+browserResourceManager.init();
 const updateService = new FarmingUpdateService({
   rootDir: path.join(__dirname, '..'),
   configDir: configManager.farmingDir,
@@ -527,6 +536,7 @@ app.use(BASE_PATH || '/', express.static(staticAppDir, { index: false }));
 app.use(routePath(BASE_PATH, '/api/files'), createWorkspaceFileRouter(agentManager, workspaceFileService, {
   rootRegistry: workspaceRootRegistry,
 }));
+app.use(routePath(BASE_PATH, '/api/browsers'), createBrowserRouter(browserResourceManager, workspaceRootRegistry));
 
 app.use(routePath(BASE_PATH, '/api/review-sessions'), createReviewSessionRouter(reviewSessionService));
 app.use(routePath(BASE_PATH, '/api/reviews'), createReviewDiffRouter(reviewDiffService, reviewSessionService));
@@ -1554,7 +1564,13 @@ app.post(routePath(BASE_PATH, '/api/agents/:agentId/fork'), express.json(), asyn
     res.status(400).json({ error: 'Unsupported Fork target runtime' });
     return;
   }
+  const requestId = typeof req.body?.requestId === 'string' ? req.body.requestId.trim() : '';
+  if (!/^[A-Za-z0-9._:-]{1,160}$/.test(requestId)) {
+    res.status(400).json({ error: 'Fork requires a valid requestId' });
+    return;
+  }
   const result = await agentManager.forkAgent(req.params.agentId, mode, {
+    requestId,
     ...(targetRuntime ? { targetRuntime } : {}),
     ...(Number.isSafeInteger(req.body?.expectedRevision)
       ? { expectedRevision: req.body.expectedRevision }
@@ -1562,7 +1578,7 @@ app.post(routePath(BASE_PATH, '/api/agents/:agentId/fork'), express.json(), asyn
   });
   if (result.error) {
     const status = result.error === 'Agent not found' ? 404 : 400;
-    res.status(status).json({ error: result.error });
+    res.status(status).json(result);
     return;
   }
 
@@ -1571,32 +1587,12 @@ app.post(routePath(BASE_PATH, '/api/agents/:agentId/fork'), express.json(), asyn
     result.projectWorkspaces = membership.projectWorkspaces;
     result.pinnedProjectWorkspaces = membership.pinnedProjectWorkspaces;
   } catch (error) {
-    let rollbackError = '';
-    try {
-      if (mode === 'new-worktree') {
-        const rollback = await agentManager.deleteForkWorktreeProject(result.workspace, { force: true });
-        if (!rollback?.deleted || rollback.cleanupError) {
-          rollbackError = rollback?.error || rollback?.cleanupError || 'Failed to delete the fork worktree';
-        }
-      } else {
-        const rollback = await agentManager.archiveAgent(result.agentId, {
-          reason: 'project-mount-failed',
-          recordHistory: false,
-          requireEngineExit: true,
-          scheduleProviderArchive: false,
-        });
-        if (rollback?.error) rollbackError = rollback.error;
-      }
-    } catch (cleanupError) {
-      rollbackError = cleanupError?.message || String(cleanupError);
-    }
     broadcastState();
     const mountError = error.message || 'Failed to create Project';
     res.status(500).json({
-      error: rollbackError
-        ? `${mountError}. Rollback failed: ${rollbackError}`
-        : mountError,
-      ...(rollbackError ? { rollbackError } : {}),
+      ...result,
+      error: `${mountError}. Retry the same Fork request to reconcile Project membership.`,
+      retryable: true,
     });
     return;
   }
@@ -1676,31 +1672,26 @@ app.patch(routePath(BASE_PATH, '/api/projects/name'), express.json(), (req, res)
 });
 
 app.post(routePath(BASE_PATH, '/api/projects/create-worktree'), express.json(), async (req, res) => {
-  let created = null;
+  const requestId = typeof req.body?.requestId === 'string' ? req.body.requestId.trim() : '';
+  if (!/^[A-Za-z0-9._:-]{1,160}$/.test(requestId)) {
+    res.status(400).json({ error: 'Project worktree creation requires a valid requestId' });
+    return;
+  }
   try {
     const root = resolveProjectActionRoot(req.body?.rootId);
-    created = await agentManager.createPermanentWorktree(root.canonicalPath);
-    const membership = configManager.mountProjectWorkspace(created.workspace);
+    const created = await agentManager.createPermanentWorktree(root.canonicalPath, { requestId });
     broadcastState();
     res.status(201).json({
-      workspace: created.workspace,
-      branch: created.branch,
-      projectWorkspaces: membership.projectWorkspaces,
-      pinnedProjectWorkspaces: membership.pinnedProjectWorkspaces,
+      ...created,
     });
   } catch (error) {
-    let rollbackError = '';
-    if (created) {
-      const rollback = await agentManager.rollbackPermanentWorktree(created);
-      if (rollback?.rolledBack === false) rollbackError = rollback.error || 'Unknown rollback failure';
-    }
     const status = error instanceof WorkspaceFileError ? error.statusCode : 400;
-    const createError = error.message || 'Failed to create permanent worktree';
+    const operation = configManager.getProjectOperation?.(requestId);
     res.status(status).json({
-      error: rollbackError
-        ? `${createError}. Rollback failed: ${rollbackError}`
-        : createError,
-      ...(rollbackError ? { rollbackError } : {}),
+      error: error.message || 'Failed to create permanent worktree',
+      requestId,
+      ...(operation?.state === 'pending' ? { retryable: true } : {}),
+      ...(['unknown', 'blocked'].includes(operation?.state) ? { uncertain: true } : {}),
     });
   }
 });
@@ -1709,45 +1700,26 @@ app.post(routePath(BASE_PATH, '/api/projects/delete-worktree'), express.json(),
   if (!await requireAgentRecoveryForHttp(res)) return;
   const body = req.body || {};
   const workspace = typeof body.workspace === 'string' ? body.workspace : '';
-  const inspected = await agentManager.inspectForkWorktreeProject(workspace);
-  if (inspected.error || (inspected.requiresForce && body.force !== true)) {
-    if (inspected.requiresForce) {
-      res.status(409).json({
-        ...inspected,
-        error: 'Worktree has uncommitted or untracked files',
-      });
-      return;
-    }
-    const status = inspected.error === 'Workspace not found' || inspected.error === 'Workspace is required' ? 404 : 400;
-    res.status(status).json(inspected);
+  const requestId = typeof body.requestId === 'string' ? body.requestId.trim() : '';
+  if (!/^[A-Za-z0-9._:-]{1,160}$/.test(requestId)) {
+    res.status(400).json({ error: 'Project worktree deletion requires a valid requestId' });
     return;
   }
 
-  const result = await agentManager.deleteForkWorktreeProject(inspected.workspace, { force: body.force === true });
+  const result = await agentManager.deleteForkWorktreeProject(workspace, {
+    force: body.force === true,
+    requestId,
+  });
   if (result.error) {
     broadcastState();
-    const status = result.requiresForce ? 409 : 400;
+    const status = result.requiresForce
+      ? 409
+      : (result.error === 'Workspace not found' || result.error === 'Workspace is required' ? 404 : 400);
     res.status(status).json(result);
     return;
   }
-
-  let membership;
-  try {
-    membership = configManager.removeProjectWorkspace(inspected.workspace);
-  } catch (error) {
-    broadcastState();
-    res.status(500).json({
-      ...result,
-      error: `Worktree was deleted, but Project membership cleanup failed: ${error.message || error}`,
-    });
-    return;
-  }
   broadcastState();
-  res.json({
-    ...result,
-    projectWorkspaces: membership.projectWorkspaces,
-    pinnedProjectWorkspaces: membership.pinnedProjectWorkspaces,
-  });
+  res.json(result);
 });
 
 app.post(routePath(BASE_PATH, '/api/codex/sessions/:sessionId/resume'), express.json(), async (req, res) => {
@@ -2232,11 +2204,35 @@ async function autoResumeMainPageAgentSessions() {
   }
 }
 
-app.post(routePath(BASE_PATH, '/api/settings'), express.json(), (req, res) => {
+app.post(routePath(BASE_PATH, '/api/settings'), express.json(), async (req, res) => {
   const settingsPatch = { ...(req.body || {}) };
   delete settingsPatch.mainPageSessionKeys;
   delete settingsPatch.projectWorkspaces;
   delete settingsPatch.pinnedProjectWorkspaces;
+  const changesBrowserExtension = Object.prototype.hasOwnProperty.call(settingsPatch, 'browserExtensionEnabled');
+  const browserExtensionEnabled = settingsPatch.browserExtensionEnabled === true;
+  if (changesBrowserExtension && browserExtensionEnabled && !browserResourceManager.capability().browser) {
+    res.status(400).json({
+      error: 'Install a Chromium-based browser to use the system Browser in Farming',
+      code: 'BROWSER_EXECUTABLE_NOT_FOUND',
+    });
+    return;
+  }
+  if (
+    changesBrowserExtension
+    && !browserExtensionEnabled
+    && configManager.getSettings().browserExtensionEnabled === true
+  ) {
+    try {
+      await browserResourceManager.stopAll();
+    } catch (error) {
+      res.status(Number(error?.status) || 500).json({
+        error: error?.message || 'Browser extension could not be disabled',
+        code: error?.code || 'BROWSER_DISABLE_FAILED',
+      });
+      return;
+    }
+  }
   configManager.updateSettings(settingsPatch);
   agentSessionsCache.invalidate();
   res.json({
@@ -2299,6 +2295,20 @@ app.get(routePath(BASE_PATH, '/api/themes/:themeId'), (req, res) => {
 
 wss.on('connection', (ws, req) => {
   const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
+  const viewerPrefix = routePath(BASE_PATH, '/api/browsers/');
+  if (url.pathname.startsWith(viewerPrefix) && url.pathname.endsWith('/viewer')) {
+    if (authEnabled && !tokenAuth.verifyWebSocket(req)) {
+      ws.close(4001, 'Authentication required');
+      return;
+    }
+    const encodedId = url.pathname.slice(viewerPrefix.length, -'/viewer'.length);
+    try {
+      browserResourceManager.attachViewer(decodeURIComponent(encodedId), ws);
+    } catch (error) {
+      ws.close(4004, error?.message || 'Browser resource not found');
+    }
+    return;
+  }
   if (url.pathname !== WS_PATH) {
     ws.close(1008, 'Invalid path');
     return;
@@ -2442,9 +2452,9 @@ async function sendInputMessage(ws, data) {
 
 async function sendComposerInputMessage(ws, data) {
   const targetAgentId = resolveInputTargetAgentId(ws, data);
-  const requestId = typeof data.requestId === 'string' ? data.requestId : '';
+  const requestId = typeof data.requestId === 'string' ? data.requestId.trim() : '';
   const responseAgentId = targetAgentId || (typeof data.agentId === 'string' ? data.agentId : '');
-  const respond = (accepted, message = '') => {
+  const respond = (accepted, message = '', uncertain = false) => {
     if (!requestId || !responseAgentId) return;
     ws.send(JSON.stringify({
       type: 'composer-input-result',
@@ -2452,9 +2462,22 @@ async function sendComposerInputMessage(ws, data) {
       agentId: responseAgentId,
       accepted,
       ...(message ? { message } : {}),
+      ...(uncertain ? { uncertain: true } : {}),
     }));
   };
   const message = typeof data.message === 'string' ? data.message : '';
+  if (!/^[A-Za-z0-9._:-]{1,160}$/.test(requestId)) {
+    if (responseAgentId) {
+      ws.send(JSON.stringify({
+        type: 'composer-input-result',
+        requestId: requestId || 'invalid-request',
+        agentId: responseAgentId,
+        accepted: false,
+        message: 'Structured Composer input requires a valid requestId',
+      }));
+    }
+    return;
+  }
   const content = [];
   if (message.trim()) content.push({ type: 'text', text: message });
   const attachmentsRoot = path.resolve(imageAttachmentsDir());
@@ -2496,11 +2519,11 @@ async function sendComposerInputMessage(ws, data) {
     return;
   }
   try {
-    await agentManager.sendComposerMessage(targetAgentId, content);
+    await agentManager.sendComposerMessage(targetAgentId, content, { requestId });
     respond(true);
   } catch (error) {
     const message = error && error.message ? error.message : 'Failed to send Composer message';
-    if (requestId) respond(false, message);
+    if (requestId) respond(false, message, error?.uncertain === true);
     else ws.send(JSON.stringify({ type: 'error', message }));
   }
 }
@@ -3113,11 +3136,12 @@ async function shutdownServer(options = {}) {
     : process.env.FARMING_NATIVE_PTY_HOST_PERSIST !== '0';
 
   try {
+    await browserResourceManager.dispose();
     await agentManager.dispose({ preserveTerminalHost });
   } catch (error) {
     const teardownFrozen = agentManager.disposing === true;
     shutdownStarted = false;
-    console.error('Farming shutdown blocked because Agent runtime cleanup could not be verified:', error);
+    console.error('Farming shutdown blocked because runtime cleanup could not be verified:', error);
     if (teardownFrozen) {
       clearBroadcastTimers();
       tokenAuth.cleanup();
@@ -3129,7 +3153,7 @@ async function shutdownServer(options = {}) {
     }
     if (options.exit === true) process.exitCode = 1;
     return {
-      error: error?.message || 'Agent runtime cleanup could not be verified',
+      error: error?.message || 'Runtime cleanup could not be verified',
       ...(teardownFrozen ? { frozen: true } : {}),
     };
   }
@@ -3247,6 +3271,7 @@ module.exports = {
   server,
   wss,
   agentManager,
+  browserResourceManager,
   workspaceFileService,
   handleMessage,
   resolveCliBinDir,

package/backend/storage-layout.js

@@ -49,6 +49,22 @@ function usageHistoryCacheFile(configDir) {
   return path.join(historyDir(configDir), 'usage-history-v2.sqlite3');
 }
 
+function browserResourcesDir(configDir) {
+  return path.join(configDir, 'browsers');
+}
+
+function browserResourcesFile(configDir) {
+  return path.join(browserResourcesDir(configDir), 'resources.json');
+}
+
+function browserProfileDir(configDir, browserId) {
+  return path.join(browserResourcesDir(configDir), browserId, 'profile');
+}
+
+function farmingAgentBootstrapFile(configDir) {
+  return path.join(configDir, 'farming-agent-bootstrap.zh_cn.md');
+}
+
 function sessionIndexFile(configDir) {
   return path.join(sessionsDir(configDir), 'index.json');
 }
@@ -124,6 +140,10 @@ function farmingNetTrustFile(configDir) {
 module.exports = {
   acpCheckpointsDir,
   agentStateFile,
+  browserProfileDir,
+  browserResourcesDir,
+  browserResourcesFile,
+  farmingAgentBootstrapFile,
   farmingNetInstancesFile,
   farmingNetServerLogFile,
   farmingNetServerStateFile,

package/backend/workspace-file-router.js

@@ -4,6 +4,7 @@ const os = require('os');
 const path = require('path');
 const { inspectGitWorktree } = require('./git-worktree-info');
 const { WorkspaceFileError } = require('./workspace-file-service');
+const { PreviewSessionManager } = require('./preview-session-manager');
 const {
   GLOBAL_WORKSPACE_FILES_AGENT_ID,
   GLOBAL_WORKSPACE_FILES_ROOT,
@@ -57,6 +58,53 @@ function isSameOrDescendantPath(root, target) {
   return relative === '' || Boolean(relative) && !relative.startsWith('..') && !path.isAbsolute(relative);
 }
 
+function previewAuthorizedRootForTarget(allowedRoots, target) {
+  return allowedRoots
+    .filter(root => isSameOrDescendantPath(root, target))
+    .sort((left, right) => right.length - left.length)[0] || '';
+}
+
+function normalizePreviewAssetPath(value) {
+  const normalized = path.posix.normalize(String(value || '').replace(/\\/g, '/').replace(/^\/+/, ''));
+  if (!normalized || normalized === '.') return '';
+  if (normalized === '..' || normalized.startsWith('../') || path.posix.isAbsolute(normalized)) {
+    throw new WorkspaceFileError('preview path must stay inside the authorized root', 403);
+  }
+  return normalized;
+}
+
+function previewContentSecurityPolicy() {
+  return [
+    "default-src 'none'",
+    "script-src 'none'",
+    "style-src 'self' 'unsafe-inline'",
+    "img-src 'self' data:",
+    "font-src 'self' data:",
+    "media-src 'self' data:",
+    "connect-src 'none'",
+    "frame-src 'none'",
+    "object-src 'none'",
+    "base-uri 'none'",
+    "form-action 'none'",
+    "frame-ancestors 'self'",
+  ].join('; ');
+}
+
+function escapeHtmlAttribute(value) {
+  return String(value || '')
+    .replace(/&/g, '&')
+    .replace(/"/g, '"')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+function rewritePreviewHtmlRootReferences(source, rootUrl) {
+  const safeRootUrl = escapeHtmlAttribute(rootUrl);
+  return String(source || '')
+    .replace(/(\b(?:href|src|poster)\s*=\s*["'])\/(?!\/)/gi, `$1${safeRootUrl}`)
+    .replace(/(url\(\s*["']?)\/(?!\/)/gi, `$1${safeRootUrl}`);
+}
+
 function globalUserPathToAbsolute(userPath = '') {
   const normalized = String(userPath || '')
     .trim()
@@ -136,6 +184,23 @@ function assertGlobalWorkspacePathAllowed(agentManager, userPath, options = {})
   return { target: requestedTarget, allowedRoots };
 }
 
+function assertExactExternalFileReadable(userPath) {
+  const requestedTarget = globalUserPathToAbsolute(userPath);
+  let target;
+  let stat;
+  try {
+    target = fs.realpathSync(requestedTarget);
+    stat = fs.statSync(target);
+    fs.accessSync(target, fs.constants.R_OK);
+  } catch {
+    throw new WorkspaceFileError('external file is not readable', 403);
+  }
+  if (!stat.isFile()) {
+    throw new WorkspaceFileError('external path must be a file', 400);
+  }
+  return relativeGlobalPath(target);
+}
+
 function globalSyntheticTree(agentManager, userPath = '') {
   const { target, allowedRoots } = assertGlobalWorkspacePathAllowed(agentManager, userPath, {
     allowAllowedRootAncestor: true,
@@ -205,6 +270,7 @@ function readOptionsForAgent(agentManager, agentId) {
 function createWorkspaceFileRouter(agentManager, fileService, options = {}) {
   const router = express.Router();
   const rootRegistry = options.rootRegistry || workspaceRootRegistryFor(agentManager);
+  const previewSessions = options.previewSessionManager || new PreviewSessionManager();
 
   router.use(express.json({ limit: '3mb' }));
 
@@ -233,11 +299,14 @@ function createWorkspaceFileRouter(agentManager, fileService, options = {}) {
   router.get('/file', async (req, res) => {
     try {
       const rootRef = workspaceRef(req.query);
-      if (isGlobalWorkspaceFilesAgentId(rootRef)) {
-        assertGlobalWorkspacePathAllowed(agentManager, req.query.path || '');
+      const requestPath = isGlobalWorkspaceFilesAgentId(rootRef) && req.query.exact === '1'
+        ? assertExactExternalFileReadable(req.query.path || '')
+        : req.query.path || '';
+      if (isGlobalWorkspaceFilesAgentId(rootRef) && req.query.exact !== '1') {
+        assertGlobalWorkspacePathAllowed(agentManager, requestPath);
       }
       const { root, rootId } = resolveRequestRoot(req.query);
-      const file = await fileService.readFile(root, req.query.path || '', readOptionsForAgent(agentManager, rootRef));
+      const file = await fileService.readFile(root, requestPath, readOptionsForAgent(agentManager, rootRef));
       res.json({ rootId, root, file });
     } catch (error) {
       sendWorkspaceFileError(res, error);
@@ -247,11 +316,14 @@ function createWorkspaceFileRouter(agentManager, fileService, options = {}) {
   router.get('/raw', async (req, res) => {
     try {
       const rootRef = workspaceRef(req.query);
-      if (isGlobalWorkspaceFilesAgentId(rootRef)) {
-        assertGlobalWorkspacePathAllowed(agentManager, req.query.path || '');
+      const requestPath = isGlobalWorkspaceFilesAgentId(rootRef) && req.query.exact === '1'
+        ? assertExactExternalFileReadable(req.query.path || '')
+        : req.query.path || '';
+      if (isGlobalWorkspaceFilesAgentId(rootRef) && req.query.exact !== '1') {
+        assertGlobalWorkspacePathAllowed(agentManager, requestPath);
       }
       const { root } = resolveRequestRoot(req.query);
-      const file = await fileService.readPreviewFile(root, req.query.path || '', readOptionsForAgent(agentManager, rootRef));
+      const file = await fileService.readPreviewFile(root, requestPath, readOptionsForAgent(agentManager, rootRef));
       res
         .status(200)
         .type(file.preview.mediaType)
@@ -264,6 +336,98 @@ function createWorkspaceFileRouter(agentManager, fileService, options = {}) {
     }
   });
 
+  router.post('/previews', async (req, res) => {
+    try {
+      const body = req.body || {};
+      const rootRef = workspaceRef(body);
+      let entryPath = String(body.path || '').trim();
+      if (!/\.html?$/i.test(entryPath)) {
+        throw new WorkspaceFileError('HTML preview requires an .html or .htm file', 415);
+      }
+
+      let authorizedRoot;
+      if (isGlobalWorkspaceFilesAgentId(rootRef)) {
+        if (body.exact === true) {
+          entryPath = assertExactExternalFileReadable(entryPath);
+          authorizedRoot = path.dirname(realPathIfPresent(globalUserPathToAbsolute(entryPath)));
+          if (authorizedRoot === path.parse(authorizedRoot).root) {
+            throw new WorkspaceFileError('external HTML preview directory cannot be the filesystem root', 403);
+          }
+        } else {
+          const authorization = assertGlobalWorkspacePathAllowed(agentManager, entryPath);
+          authorizedRoot = previewAuthorizedRootForTarget(authorization.allowedRoots, realPathIfPresent(authorization.target));
+          if (!authorizedRoot) throw new WorkspaceFileError('global file path is outside allowed workspaces', 403);
+        }
+      }
+
+      const { root, rootId } = resolveRequestRoot(body);
+      await fileService.readFile(root, entryPath, { allowedExternalRoots: [] });
+      const session = previewSessions.createStatic({
+        rootId,
+        workspaceRoot: root,
+        authorizedRoot: realPathIfPresent(authorizedRoot || root),
+        entryPath,
+        baseDirectory: path.posix.dirname(entryPath) === '.' ? '' : path.posix.dirname(entryPath),
+      });
+      res.status(201).json({
+        preview: {
+          id: session.id,
+          kind: session.kind,
+          expiresAt: session.expiresAt,
+        },
+      });
+    } catch (error) {
+      sendWorkspaceFileError(res, error);
+    }
+  });
+
+  router.get('/previews/:sessionId/:scope/*', async (req, res) => {
+    try {
+      const session = previewSessions.get(req.params.sessionId);
+      if (!session) throw new WorkspaceFileError('preview session not found or expired', 404);
+      const scope = req.params.scope;
+      if (scope !== 'base' && scope !== 'root') {
+        throw new WorkspaceFileError('preview scope is invalid', 400);
+      }
+      const assetPath = normalizePreviewAssetPath(req.params[0] || '');
+      const resourcePath = scope === 'base'
+        ? path.posix.join(session.baseDirectory, assetPath)
+        : assetPath;
+      if (!resourcePath) throw new WorkspaceFileError('preview resource path is required', 400);
+
+      const absoluteTarget = realPathIfPresent(path.resolve(session.workspaceRoot, resourcePath));
+      if (!isSameOrDescendantPath(session.authorizedRoot, absoluteTarget)) {
+        throw new WorkspaceFileError('preview path must stay inside the authorized root', 403);
+      }
+
+      const file = await fileService.readResourceFile(session.workspaceRoot, resourcePath, {
+        allowedExternalRoots: [],
+      });
+      const isHtml = /\.html?$/i.test(file.path);
+      const body = isHtml
+        ? Buffer.from(rewritePreviewHtmlRootReferences(
+          file.buffer.toString('utf8'),
+          `${req.baseUrl}/previews/${encodeURIComponent(session.id)}/root/`,
+        ))
+        : file.buffer;
+      res
+        .status(200)
+        .type(path.extname(file.path) || 'application/octet-stream')
+        .set('Cache-Control', 'no-store')
+        .set('X-Content-Type-Options', 'nosniff')
+        .set('Content-Length', String(body.length));
+      if (isHtml) res.set('Content-Security-Policy', previewContentSecurityPolicy());
+      res.send(body);
+    } catch (error) {
+      sendWorkspaceFileError(res, error);
+    }
+  });
+
+  router.delete('/previews/:sessionId', (req, res) => {
+    const deleted = previewSessions.delete(req.params.sessionId);
+    res.status(deleted ? 204 : 404).end();
+  });
+
   router.put('/file', async (req, res) => {
     try {
       const body = req.body || {};
@@ -533,6 +697,7 @@ module.exports = {
   PROJECT_FILES_WORKSPACE_PREFIX,
   PROJECT_FILES_AGENT_PREFIX: PROJECT_FILES_WORKSPACE_PREFIX,
   assertGlobalWorkspacePathAllowed,
+  assertExactExternalFileReadable,
   createWorkspaceFileRouter,
   globalWorkspaceAllowedRoots,
   isGlobalWorkspaceFilesAgentId,

package/backend/workspace-file-service.js

@@ -2199,6 +2199,25 @@ class WorkspaceFileService {
     };
   }
 
+  async readResourceFile(workspaceRoot, userPath, options = {}) {
+    const { target, relativePath } = await this.resolvePath(workspaceRoot, userPath, options);
+    const stat = await fsp.stat(target);
+    if (!stat.isFile()) {
+      throw new WorkspaceFileError('path must be a file', 400);
+    }
+    if (stat.size > this.maxPreviewFileSize) {
+      throw new WorkspaceFileError('file is too large to preview', 413, { size: stat.size });
+    }
+    const buffer = await fsp.readFile(target);
+    return {
+      path: relativePath,
+      buffer,
+      size: stat.size,
+      mtimeMs: stat.mtimeMs,
+      sha1: sha1(buffer),
+    };
+  }
+
   async blameCapability(workspaceRoot, userPath, options = {}) {
     const { root, target, relativePath, actualRelativePath, external } = await this.resolvePath(workspaceRoot, userPath, options);
     const capability = (available, reason = '') => ({

package/backend/workspace-root-registry.js

@@ -27,6 +27,7 @@ function canonicalWorkspacePath(value) {
 function rootIdForPath(value) {
   const canonicalPath = canonicalWorkspacePath(value);
   if (!canonicalPath) return '';
+  if (canonicalPath === GLOBAL_WORKSPACE_FILES_ROOT) return GLOBAL_WORKSPACE_ROOT_ID;
   let hash = 0xcbf29ce484222325n;
   for (const byte of Buffer.from(canonicalPath, 'utf8')) {
     hash ^= BigInt(byte);
@@ -77,15 +78,16 @@ class WorkspaceRootRegistry {
     if (current && current.canonicalPath !== canonicalPath) {
       throw new WorkspaceFileError('workspace root identity collision', 409);
     }
+    const isGlobalRoot = rootId === GLOBAL_WORKSPACE_ROOT_ID;
     const root = Object.freeze({
       rootId,
-      kind: options.kind || current?.kind || 'directory',
+      kind: isGlobalRoot ? 'global' : (options.kind || current?.kind || 'directory'),
       canonicalPath,
       repositoryId: options.repositoryId || current?.repositoryId || '',
       accessPolicy: Object.freeze({
-        readOnly: options.accessPolicy?.readOnly === true,
-        watch: options.accessPolicy?.watch !== false,
-        externalReads: options.accessPolicy?.externalReads !== false,
+        readOnly: isGlobalRoot || options.accessPolicy?.readOnly === true,
+        watch: isGlobalRoot ? false : options.accessPolicy?.watch !== false,
+        externalReads: isGlobalRoot ? false : options.accessPolicy?.externalReads !== false,
       }),
     });
     this.roots.set(rootId, root);