fix: launch ACP adapters without host node

Author: felarof99

packages/browseros-agent/apps/server/src/agent/provider-factory.ts

@@ -156,6 +156,7 @@ async function createAcpLanguageModel(
   for (const builtIn of ['claude', 'codex'] as const) {
     const launcher = resolveAcpSpawnCommand({
       agentType: builtIn,
+      browserosDir: getBrowserosDir(),
       resourcesDir: config.resourcesDir,
     })
     if (launcher?.source === 'bundled-bun') {

packages/browseros-agent/apps/server/src/api/services/acpx-probe/probeAgent.ts

@@ -6,6 +6,7 @@
 
 import { type AgentProbeResult, probeAgent as runProbe } from 'acp-probe'
 import { resolveAcpSpawnCommand } from '../../../lib/agents/host-acp/launcher'
+import { getBrowserosDir } from '../../../lib/browseros-dir'
 import { logger } from '../../../lib/logger'
 
 export interface ServerAcpxProbeInput {
@@ -21,6 +22,7 @@ export interface ServerAcpxProbeInput {
    * HttpServerConfig.
    */
   resourcesDir?: string | null
+  browserosDir?: string | null
   platform?: NodeJS.Platform
 }
 
@@ -89,6 +91,7 @@ export async function probeAcpAgent(
   if (!command && agentId) {
     const launcher = resolveAcpSpawnCommand({
       agentType: agentId,
+      browserosDir: input.browserosDir ?? getBrowserosDir(),
       resourcesDir: input.resourcesDir,
       platform: input.platform,
     })

packages/browseros-agent/apps/server/src/lib/agents/acpx/runtime.ts

@@ -27,7 +27,10 @@ import {
   type AgentSessionId,
   MAIN_AGENT_SESSION_ID,
 } from '../agent-types'
-import { resolveBundledBun } from '../host-acp/bundled-bun'
+import {
+  resolveBundledBun,
+  withBundledBunAcpAdapterEnv,
+} from '../host-acp/bundled-bun'
 import { withBundledNativeBinaryPath } from '../host-acp/bundled-native-binary'
 import {
   DANGEROUS_ALLOW_MODE_CANDIDATES,
@@ -753,8 +756,12 @@ function createBrowserosAgentRegistry(input: {
         })
         return wrapCommandWithEnv(
           launch.command,
-          launch.addBundledBunAdapterEnv
-            ? withBundledBunAcpAdapterEnv(commandEnv, input.browserosDir)
+          launch.bundledBunPath
+            ? withBundledBunAcpAdapterEnv({
+                bunPath: launch.bundledBunPath,
+                browserosDir: input.browserosDir,
+                env: commandEnv,
+              })
             : commandEnv,
         )
       }
@@ -773,31 +780,20 @@ function createBrowserosAgentRegistry(input: {
 function resolveBrowserosHostAcpAdapterCommand(input: {
   adapter: 'claude' | 'codex'
   resourcesDir: string | null
-}): { command: string; addBundledBunAdapterEnv: boolean } {
+}): { command: string; bundledBunPath: string | null } {
   const bun = resolveBundledBun({ resourcesDir: input.resourcesDir })
   if (bun) {
     const config = HOST_ACP_ADAPTER_CONFIG[input.adapter]
     return {
       command: `${shellQuote(bun)} x --bun --silent --package ${shellQuote(config.acpPackageSpec)} ${shellQuote(config.acpBin)}`,
-      addBundledBunAdapterEnv: true,
+      bundledBunPath: bun,
     }
   }
 
   const config = HOST_ACP_ADAPTER_CONFIG[input.adapter]
   return {
     command: config.acpCommand,
-    addBundledBunAdapterEnv: false,
-  }
-}
-
-/** Adds the minimum env needed for BrowserOS-managed bundled Bun package installs. */
-function withBundledBunAcpAdapterEnv(
-  env: Record<string, string>,
-  browserosDir: string,
-): Record<string, string> {
-  return {
-    ...env,
-    BUN_INSTALL_CACHE_DIR: join(browserosDir, 'cache', 'bun-install'),
+    bundledBunPath: null,
   }
 }
 

packages/browseros-agent/apps/server/src/lib/agents/host-acp/bundled-bun.ts

@@ -4,8 +4,15 @@
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-import { accessSync, constants, statSync } from 'node:fs'
-import { join } from 'node:path'
+import {
+  accessSync,
+  chmodSync,
+  constants,
+  mkdirSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs'
+import { dirname, join } from 'node:path'
 
 const BUNDLED_BUN_RELATIVE_PATH = join('bin', 'third_party', 'bun')
 const WINDOWS_BUNDLED_BUN_RELATIVE_PATH = join('bin', 'third_party', 'bun.exe')
@@ -33,6 +40,42 @@ export function resolveBundledBun(input: {
   }
 }
 
+/**
+ * Builds the environment used to launch Node-shebang ACP adapter
+ * packages through BrowserOS's bundled Bun. Several adapter packages
+ * publish `#!/usr/bin/env node` entrypoints; GUI-launched apps often
+ * lack the user's Homebrew/nvm Node on PATH, so provide a private
+ * `node` shim that execs bundled Bun.
+ */
+export function withBundledBunAcpAdapterEnv(input: {
+  bunPath: string
+  browserosDir?: string | null
+  env?: Record<string, string | undefined>
+  platform?: NodeJS.Platform
+}): Record<string, string> {
+  const platform = input.platform ?? process.platform
+  const sourceEnv = input.env ?? process.env
+  const env = input.env ? stringEnv(input.env) : {}
+  const pathKey = pathEnvKey(sourceEnv, platform)
+  const delimiter = platform === 'win32' ? ';' : ':'
+  const pathEntries = [
+    ensureBundledNodeShim({
+      bunPath: input.bunPath,
+      browserosDir: input.browserosDir,
+      platform,
+    }),
+    dirname(input.bunPath),
+    ...(sourceEnv[pathKey] ?? '').split(delimiter),
+  ].filter((entry): entry is string => Boolean(entry))
+
+  env[pathKey] = dedupe(pathEntries).join(delimiter)
+  const browserosDir = input.browserosDir?.trim()
+  if (browserosDir) {
+    env.BUN_INSTALL_CACHE_DIR = join(browserosDir, 'cache', 'bun-install')
+  }
+  return env
+}
+
 function bundledBunRelativePath(platform: NodeJS.Platform): string | null {
   if (platform === 'darwin' || platform === 'linux') {
     return BUNDLED_BUN_RELATIVE_PATH
@@ -42,3 +85,61 @@ function bundledBunRelativePath(platform: NodeJS.Platform): string | null {
   }
   return null
 }
+
+function ensureBundledNodeShim(input: {
+  bunPath: string
+  browserosDir?: string | null
+  platform: NodeJS.Platform
+}): string | null {
+  if (input.platform === 'win32') return null
+  const browserosDir = input.browserosDir?.trim()
+  if (!browserosDir) return null
+
+  const shimDir = join(browserosDir, 'cache', 'acp-node-shim')
+  const shimPath = join(shimDir, 'node')
+  try {
+    mkdirSync(shimDir, { recursive: true })
+    writeFileSync(
+      shimPath,
+      `#!/bin/sh\nexec ${shellQuote(input.bunPath)} "$@"\n`,
+      'utf8',
+    )
+    chmodSync(shimPath, 0o755)
+    return shimDir
+  } catch {
+    return null
+  }
+}
+
+function stringEnv(
+  env: Record<string, string | undefined>,
+): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [key, value] of Object.entries(env)) {
+    if (value !== undefined) out[key] = value
+  }
+  return out
+}
+
+function pathEnvKey(
+  env: Record<string, string | undefined>,
+  platform: NodeJS.Platform,
+): string {
+  if (platform !== 'win32') return 'PATH'
+  return Object.keys(env).find((key) => key.toLowerCase() === 'path') ?? 'Path'
+}
+
+function dedupe(values: string[]): string[] {
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const value of values) {
+    if (seen.has(value)) continue
+    seen.add(value)
+    out.push(value)
+  }
+  return out
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, "'\\''")}'`
+}

packages/browseros-agent/apps/server/src/lib/agents/host-acp/launcher.ts

@@ -11,7 +11,7 @@
  * outside darwin / linux / win32).
  */
 
-import { resolveBundledBun } from './bundled-bun'
+import { resolveBundledBun, withBundledBunAcpAdapterEnv } from './bundled-bun'
 import {
   HOST_ACP_ADAPTER_CONFIG,
   type HostAcpAdapter,
@@ -27,6 +27,8 @@ export interface AcpLauncherResolution {
 
 export interface ResolveAcpSpawnCommandInput {
   agentType: string
+  browserosDir?: string | null
+  env?: NodeJS.ProcessEnv
   resourcesDir?: string | null
   platform?: NodeJS.Platform
   /** Injected for tests; production callers leave it unset. */
@@ -55,7 +57,15 @@ export function resolveAcpSpawnCommand(
   })
   if (bunPath) {
     return {
-      command: `${quoteAcpCommandToken(bunPath)} x ${config.acpPackageSpec}`,
+      command: wrapCommandWithEnv(
+        `${quoteAcpCommandToken(bunPath)} x --bun --silent --package ${quoteAcpCommandToken(config.acpPackageSpec)} ${quoteAcpCommandToken(config.acpBin)}`,
+        withBundledBunAcpAdapterEnv({
+          bunPath,
+          browserosDir: input.browserosDir,
+          env: input.env,
+          platform: input.platform,
+        }),
+      ),
       source: 'bundled-bun',
     }
   }
@@ -66,3 +76,14 @@ export function resolveAcpSpawnCommand(
 function quoteAcpCommandToken(value: string): string {
   return `'${value.replace(/'/g, "'\\''")}'`
 }
+
+function wrapCommandWithEnv(
+  command: string,
+  env: Record<string, string>,
+): string {
+  const prefix = Object.entries(env)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, value]) => `${key}=${quoteAcpCommandToken(value)}`)
+    .join(' ')
+  return prefix ? `env ${prefix} ${command}` : command
+}

packages/browseros-agent/apps/server/tests/lib/agents/acpx-runtime.test.ts

@@ -1195,7 +1195,8 @@ Use the BrowserOS MCP server for all browser tasks, including browsing the web,
         `'${bunPath}' x --bun --silent --package '@zed-industries/codex-acp@^0.12.0' 'codex-acp'`,
       )
       expect(codexCommand).toContain('BUN_INSTALL_CACHE_DIR=')
-      expect(codexCommand).toContain(`PATH='${dirname(bunPath)}'`)
+      expect(codexCommand).toContain('cache/acp-node-shim')
+      expect(codexCommand).toContain(dirname(bunPath))
       expect(codexCommand).not.toContain('npx -y')
     },
   )

packages/browseros-agent/apps/server/tests/lib/agents/bundled-bun.test.ts

@@ -4,10 +4,21 @@
  */
 
 import { afterEach, describe, expect, it } from 'bun:test'
-import { chmod, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import {
+  chmod,
+  mkdir,
+  mkdtemp,
+  readFile,
+  rm,
+  stat,
+  writeFile,
+} from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
-import { resolveBundledBun } from '../../../src/lib/agents/host-acp/bundled-bun'
+import {
+  resolveBundledBun,
+  withBundledBunAcpAdapterEnv,
+} from '../../../src/lib/agents/host-acp/bundled-bun'
 
 describe('bundled Bun helpers', () => {
   const tempDirs: string[] = []
@@ -84,4 +95,54 @@ describe('bundled Bun helpers', () => {
 
     expect(resolveBundledBun({ resourcesDir, platform: 'freebsd' })).toBeNull()
   })
+
+  it('creates a private node shim for Unix ACP adapter launches', async () => {
+    const resourcesDir = await mkdtemp(join(tmpdir(), 'browseros-bun-'))
+    const browserosDir = await mkdtemp(join(tmpdir(), 'browseros-dir-'))
+    tempDirs.push(resourcesDir, browserosDir)
+    const bunPath = join(resourcesDir, 'bin', 'third_party', 'bun')
+    await mkdir(dirname(bunPath), { recursive: true })
+    await writeFile(bunPath, '#!/bin/sh\n')
+    await chmod(bunPath, 0o755)
+
+    const env = withBundledBunAcpAdapterEnv({
+      bunPath,
+      browserosDir,
+      env: { PATH: '/usr/bin' },
+      platform: 'darwin',
+    })
+
+    const shimPath = join(browserosDir, 'cache', 'acp-node-shim', 'node')
+    expect(env.PATH.split(':').slice(0, 3)).toEqual([
+      dirname(shimPath),
+      dirname(bunPath),
+      '/usr/bin',
+    ])
+    expect(env.BUN_INSTALL_CACHE_DIR).toBe(
+      join(browserosDir, 'cache', 'bun-install'),
+    )
+    expect(await readFile(shimPath, 'utf8')).toContain(bunPath)
+    expect((await stat(shimPath)).mode & 0o111).not.toBe(0)
+  })
+
+  it('prepends the bundled Bun directory even without a writable BrowserOS dir', async () => {
+    const resourcesDir = await mkdtemp(join(tmpdir(), 'browseros-bun-'))
+    tempDirs.push(resourcesDir)
+    const bunPath = join(resourcesDir, 'bin', 'third_party', 'bun')
+    await mkdir(dirname(bunPath), { recursive: true })
+    await writeFile(bunPath, '#!/bin/sh\n')
+    await chmod(bunPath, 0o755)
+
+    const env = withBundledBunAcpAdapterEnv({
+      bunPath,
+      env: { PATH: '/usr/bin' },
+      platform: 'linux',
+    })
+
+    expect(env.PATH.split(':').slice(0, 2)).toEqual([
+      dirname(bunPath),
+      '/usr/bin',
+    ])
+    expect(env.BUN_INSTALL_CACHE_DIR).toBeUndefined()
+  })
 })