fix: preserve remote harness output file access

shadowfax92 · shadowfax92 · commit b5f13c5936c7 · 2026-06-22T13:01:25.000-07:00
diff --git a/packages/browseros-agent/apps/server/src/api/routes/mcp.ts b/packages/browseros-agent/apps/server/src/api/routes/mcp.ts
@@ -10,6 +10,10 @@ import type { BrowserSession } from '../../browser/core/session'
 import { logger } from '../../lib/logger'
 import { metrics } from '../../lib/metrics'
 import { Sentry } from '../../lib/sentry'
+import {
+  type BrowserOutputFileAccess,
+  createBrowserOutputFileAccess,
+} from '../../tools/browser/output-file'
 import type { KlavisService } from '../services/klavis'
 import { createMcpServer } from '../services/mcp/mcp-server'
 import type { Env } from '../types'
@@ -24,6 +28,21 @@ interface McpRouteDeps {
   executionDir: string
 }
 
+/** Returns generated-output readback state; scoped harnesses share it across MCP requests. */
+function getRemoteHarnessOutputFileAccess(
+  accessByScope: Map<string, BrowserOutputFileAccess>,
+  scopeId: string | undefined,
+): BrowserOutputFileAccess {
+  if (!scopeId) return createBrowserOutputFileAccess()
+
+  const existing = accessByScope.get(scopeId)
+  if (existing) return existing
+
+  const access = createBrowserOutputFileAccess()
+  accessByScope.set(scopeId, access)
+  return access
+}
+
 function parseOptionalNumber(value: string | undefined): number | undefined {
   if (value === undefined) return undefined
   const n = Number(value)
@@ -57,6 +76,10 @@ export function parseManagedMcpServersHeader(
 
 export function createMcpRoutes(deps: McpRouteDeps) {
   const app = new Hono<Env>()
+  const remoteHarnessOutputFilesByScope = new Map<
+    string,
+    BrowserOutputFileAccess
+  >()
 
   app.get('/', (c) =>
     c.json({
@@ -66,8 +89,8 @@ export function createMcpRoutes(deps: McpRouteDeps) {
   )
 
   app.post('/', async (c) => {
-    const scopeId = c.req.header('X-BrowserOS-Scope-Id') || 'ephemeral'
-    metrics.log('mcp.request', { scopeId })
+    const scopeId = c.req.header('X-BrowserOS-Scope-Id')?.trim() || undefined
+    metrics.log('mcp.request', { scopeId: scopeId ?? 'ephemeral' })
 
     const defaultWindowId = parseOptionalNumber(
       c.req.header('X-BrowserOS-Default-Window-Id'),
@@ -80,6 +103,12 @@ export function createMcpRoutes(deps: McpRouteDeps) {
 
     const isRemoteAgentHarness =
       c.req.query('source') === REMOTE_HERMES_MCP_SOURCE
+    const outputFileAccess = isRemoteAgentHarness
+      ? getRemoteHarnessOutputFileAccess(
+          remoteHarnessOutputFilesByScope,
+          scopeId,
+        )
+      : undefined
 
     // Per-request server + transport: no shared state, no race conditions,
     // no ID collisions. Required by MCP SDK 1.26.0+ security fix (GHSA-345p-7cg4-v4c7).
@@ -92,6 +121,7 @@ export function createMcpRoutes(deps: McpRouteDeps) {
       defaultTabGroupId,
       executionDir: deps.executionDir,
       isRemoteAgentHarness,
+      outputFileAccess,
     })
     const transport = new StreamableHTTPTransport({
       sessionIdGenerator: undefined,
@@ -104,7 +134,7 @@ export function createMcpRoutes(deps: McpRouteDeps) {
     } catch (error) {
       Sentry.withScope((scope) => {
         scope.setTag('route', 'mcp')
-        scope.setTag('scopeId', scopeId)
+        scope.setTag('scopeId', scopeId ?? 'ephemeral')
         Sentry.captureException(error)
       })
       logger.error('Error handling MCP request', {
diff --git a/packages/browseros-agent/apps/server/src/api/services/mcp/mcp-server.ts b/packages/browseros-agent/apps/server/src/api/services/mcp/mcp-server.ts
@@ -7,6 +7,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { SetLevelRequestSchema } from '@modelcontextprotocol/sdk/types.js'
 import type { BrowserSession } from '../../../browser/core/session'
+import type { BrowserOutputFileAccess } from '../../../tools/browser/output-file'
 import type { ConnectorToolScope, KlavisService } from '../klavis'
 import { MCP_INSTRUCTIONS } from './mcp-prompt'
 import { registerTools } from './register-mcp'
@@ -20,6 +21,7 @@ export interface McpServiceDeps {
   defaultTabGroupId?: string
   executionDir: string
   isRemoteAgentHarness: boolean
+  outputFileAccess?: BrowserOutputFileAccess
 }
 
 /** Creates a per-request BrowserOS MCP server with tools for the requested surface. */
@@ -43,6 +45,7 @@ export function createMcpServer(deps: McpServiceDeps): McpServer {
     defaultTabGroupId: deps.defaultTabGroupId,
     executionDir: deps.executionDir,
     isRemoteAgentHarness: deps.isRemoteAgentHarness,
+    outputFileAccess: deps.outputFileAccess,
   })
 
   deps.klavis?.registerMcpTools(server, deps.connectorScope)
diff --git a/packages/browseros-agent/apps/server/src/api/services/mcp/register-mcp.ts b/packages/browseros-agent/apps/server/src/api/services/mcp/register-mcp.ts
@@ -1,5 +1,6 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import type { BrowserSession } from '../../../browser/core/session'
+import type { BrowserOutputFileAccess } from '../../../tools/browser/output-file'
 import {
   type BrowserToolDefaults,
   registerBrowserTools,
@@ -10,6 +11,7 @@ export interface RegisterToolsDeps extends BrowserToolDefaults {
   browserSession: BrowserSession
   executionDir: string
   isRemoteAgentHarness: boolean
+  outputFileAccess?: BrowserOutputFileAccess
 }
 
 /** Registers BrowserOS MCP tools for the current request. */
@@ -22,9 +24,13 @@ export function registerTools(
     defaultTabGroupId: deps.defaultTabGroupId,
   }
 
-  registerBrowserTools(mcpServer, deps.browserSession, defaults)
+  registerBrowserTools(mcpServer, deps.browserSession, defaults, {
+    outputFileAccess: deps.outputFileAccess,
+  })
 
   if (deps.isRemoteAgentHarness) {
-    registerFilesystemMcpTools(mcpServer, deps.executionDir)
+    registerFilesystemMcpTools(mcpServer, deps.executionDir, {
+      outputFileAccess: deps.outputFileAccess,
+    })
   }
 }
diff --git a/packages/browseros-agent/apps/server/src/tools/browser/register.ts b/packages/browseros-agent/apps/server/src/tools/browser/register.ts
@@ -5,6 +5,10 @@ import { logger } from '../../lib/logger'
 import { metrics } from '../../lib/metrics'
 import { shouldLogToolRegistration } from '../registration-log-sampling'
 import { executeTool } from './framework'
+import {
+  type BrowserOutputFileAccess,
+  withBrowserOutputFileAccess,
+} from './output-file'
 import { BROWSER_TOOLS } from './registry'
 
 // The SDK's registerTool is heavily overloaded/generic; retyping it to a concrete signature
@@ -31,13 +35,18 @@ export interface BrowserToolDefaults {
   defaultTabGroupId?: string
 }
 
+export interface BrowserToolRegistrationOptions {
+  outputFileAccess?: BrowserOutputFileAccess
+}
+
 /**
  * Registers the browser-core tool surface on an MCP server, all bound to one BrowserSession.
  */
 export function registerBrowserTools(
   server: McpServer,
   session: BrowserSession,
   defaults: BrowserToolDefaults = {},
+  options: BrowserToolRegistrationOptions = {},
 ): void {
   const register = server.registerTool.bind(server) as unknown as RegisterFn
 
@@ -54,11 +63,15 @@ export function registerBrowserTools(
       async (args, extra) => {
         const startTime = performance.now()
         try {
-          const result = await executeTool(tool, args, {
-            session,
-            ...defaults,
-            signal: extra?.signal,
-          })
+          const result = await withBrowserOutputFileAccess(
+            options.outputFileAccess,
+            () =>
+              executeTool(tool, args, {
+                session,
+                ...defaults,
+                signal: extra?.signal,
+              }),
+          )
           metrics.log('tool_executed', {
             tool_name: tool.name,
             duration_ms: Math.round(performance.now() - startTime),
diff --git a/packages/browseros-agent/apps/server/src/tools/filesystem/build-toolset.ts b/packages/browseros-agent/apps/server/src/tools/filesystem/build-toolset.ts
@@ -4,12 +4,19 @@ import { createEditTool } from './edit'
 import { createFindTool } from './find'
 import { createGrepTool } from './grep'
 import { createLsTool } from './ls'
-import { createReadTool } from './read'
+import { createReadTool, type ReadToolOptions } from './read'
 import { createWriteTool } from './write'
 
-export function buildFilesystemToolSet(cwd: string): ToolSet {
+export interface FilesystemToolSetOptions {
+  read?: ReadToolOptions
+}
+
+export function buildFilesystemToolSet(
+  cwd: string,
+  options: FilesystemToolSetOptions = {},
+): ToolSet {
   return {
-    filesystem_read: createReadTool(cwd),
+    filesystem_read: createReadTool(cwd, options.read),
     filesystem_write: createWriteTool(cwd),
     filesystem_edit: createEditTool(cwd),
     filesystem_bash: createBashTool(cwd),
diff --git a/packages/browseros-agent/apps/server/src/tools/filesystem/read.ts b/packages/browseros-agent/apps/server/src/tools/filesystem/read.ts
@@ -20,6 +20,7 @@ const TOOL_NAME = 'filesystem_read'
 
 export interface ReadToolOptions {
   allowedOutputPaths?: ReadonlySet<string>
+  requireAllowedOutputPath?: boolean
 }
 
 function createImageResult(
@@ -133,6 +134,7 @@ async function resolveReadPath(
   cwd: string | undefined,
   inputPath: string,
   allowedOutputPaths: ReadonlySet<string>,
+  requireAllowedOutputPath: boolean,
 ): Promise<string> {
   if (!cwd)
     return await resolveGeneratedOutputPath(inputPath, allowedOutputPaths)
@@ -141,6 +143,9 @@ async function resolveReadPath(
     return await resolveWorkspacePath(cwd, inputPath)
   } catch (error) {
     if (error instanceof Error && (await isBrowserosStatePath(inputPath))) {
+      if (requireAllowedOutputPath) {
+        return await resolveGeneratedOutputPath(inputPath, allowedOutputPaths)
+      }
       return await resolveBrowserToolOutputPath(inputPath)
     }
     throw error
@@ -150,17 +155,18 @@ async function resolveReadPath(
 /** Creates the read tool for workspace files, or generated browser outputs when no workspace exists. */
 export function createReadTool(cwd?: string, options: ReadToolOptions = {}) {
   const allowedOutputPaths = options.allowedOutputPaths ?? new Set<string>()
+  const supportsGeneratedOutputs = Boolean(options.allowedOutputPaths)
 
   return tool({
     description: cwd
-      ? `Read a file from the filesystem. Returns text content with line numbers, or image data for image files. Text reads are limited to ${MAX_READ_LINES} lines and ${MAX_READ_CHARS} characters per call. Use offset and limit to paginate through large files.`
+      ? `Read a file from the filesystem. Returns text content with line numbers, or image data for image files. Text reads are limited to ${MAX_READ_LINES} lines and ${MAX_READ_CHARS} characters per call. Use offset and limit to paginate through large files.${supportsGeneratedOutputs ? ' Also accepts absolute BrowserOS-generated output file paths returned by browser tools.' : ''}`
       : `Read BrowserOS-generated tool output files by absolute path. Returns text content with line numbers, or image data for image files. Text reads are limited to ${MAX_READ_LINES} lines and ${MAX_READ_CHARS} characters per call. Use offset and limit to paginate through large files.`,
     inputSchema: z.object({
       path: z
         .string()
         .describe(
           cwd
-            ? 'File path relative to the selected workspace'
+            ? `File path relative to the selected workspace${supportsGeneratedOutputs ? ', or an absolute BrowserOS-generated output path returned by a browser tool' : ''}`
             : 'Absolute BrowserOS-generated tool output path returned by a browser tool',
         ),
       offset: z
@@ -180,6 +186,7 @@ export function createReadTool(cwd?: string, options: ReadToolOptions = {}) {
           cwd,
           params.path,
           allowedOutputPaths,
+          options.requireAllowedOutputPath ?? false,
         )
         const ext = extname(resolved).toLowerCase()
 
diff --git a/packages/browseros-agent/apps/server/src/tools/filesystem/register-mcp.ts b/packages/browseros-agent/apps/server/src/tools/filesystem/register-mcp.ts
@@ -13,6 +13,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import type { z } from 'zod'
 import { logger } from '../../lib/logger'
+import type { BrowserOutputFileAccess } from '../browser/output-file'
 import { shouldLogToolRegistration } from '../registration-log-sampling'
 import { buildFilesystemToolSet } from './build-toolset'
 import type { FilesystemToolResult } from './utils'
@@ -43,15 +44,22 @@ type McpRegisterFn = (
   }>,
 ) => void
 
+export interface RegisterFilesystemMcpToolsOptions {
+  outputFileAccess?: BrowserOutputFileAccess
+}
+
 export function registerFilesystemMcpTools(
   server: McpServer,
   cwd: string,
+  options: RegisterFilesystemMcpToolsOptions = {},
 ): void {
   const register = server.registerTool.bind(server) as unknown as McpRegisterFn
-  const tools = buildFilesystemToolSet(cwd) as unknown as Record<
-    string,
-    AiSdkToolLike
-  >
+  const tools = buildFilesystemToolSet(cwd, {
+    read: {
+      allowedOutputPaths: options.outputFileAccess?.paths,
+      requireAllowedOutputPath: Boolean(options.outputFileAccess),
+    },
+  }) as unknown as Record<string, AiSdkToolLike>
 
   for (const [name, tool] of Object.entries(tools)) {
     register(
diff --git a/packages/browseros-agent/apps/server/tests/api/routes/mcp.test.ts b/packages/browseros-agent/apps/server/tests/api/routes/mcp.test.ts
diff --git a/packages/browseros-agent/apps/server/tests/api/services/mcp/register-mcp.test.ts b/packages/browseros-agent/apps/server/tests/api/services/mcp/register-mcp.test.ts
