Skip to content

Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.

TypeScript

fix(byoa): distinguish blocked engines from missing CLIs during pairing

bingqilinweimaotaiae18eff5d351
diff --git a/server/src/__tests__/agents-computer-pairing-cli.test.ts b/server/src/__tests__/agents-computer-pairing-cli.test.ts
new file mode 100644
index 0000000..f610c41
--- /dev/null
+++ b/server/src/__tests__/agents-computer-pairing-cli.test.ts
@@ -0,0 +1,117 @@
+import assert from 'node:assert/strict'
+import { execFile } from 'node:child_process'
+import { mkdir, mkdtemp, readdir, rm, writeFile } from 'node:fs/promises'
+import { createServer } from 'node:http'
+import { tmpdir } from 'node:os'
+import { delimiter, join, resolve, sep } from 'node:path'
+import { test } from 'node:test'
+import { fileURLToPath } from 'node:url'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+// Exercise the actual CLI dispatcher, PATH scan, .cmd version probes, and
+// pairing request. The local server refuses pairing before config/service writes.
+test('Windows pairing CLI distinguishes policy refusal from missing engines', { skip: process.platform !== 'win32' }, async (t) => {
+ const root = await mkdtemp(join(tmpdir(), 'cumora-pairing-cli-'))
+ const requests: Array<{ path: string; body: Record<string, unknown> }> = []
+ const server = createServer(async (req, res) => {
+ let body = ''
+ for await (const chunk of req) body += chunk
+ requests.push({ path: req.url ?? '', body: JSON.parse(body) })
+ res.writeHead(400, { 'Content-Type': 'application/json' })
+ res.end(JSON.stringify({ error: 'fixture pairing rejected' }))
+ })
+ try {
+ await new Promise<void>((done) => server.listen(0, '127.0.0.1', done))
+ const address = server.address()
+ assert.ok(address && typeof address !== 'string')
+ const serverUrl = `http://127.0.0.1:${address.port}`
+
+ async function run(name: string, engines: Record<string, string>, preferred: string, compatibility = false) {
+ const dir = join(root, name)
+ const bin = join(dir, 'bin')
+ const home = join(dir, 'home')
+ await mkdir(bin, { recursive: true })
+ await mkdir(home)
+ for (const [id, version] of Object.entries(engines)) {
+ await writeFile(join(bin, `${id}.cmd`), `@echo off\r\necho ${version}\r\n`)
+ }
+ // Windows env names are case-insensitive; remove inherited Path variants.
+ const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !['path', 'node_options', 'cumora_byoa_allow_unsandboxed'].includes(key.toLowerCase())))
+ Object.assign(env, {
+ PATH: [bin, join(process.env.SystemRoot ?? 'C:\\Windows', 'System32')].join(delimiter),
+ PATHEXT: '.COM;.EXE;.BAT;.CMD',
+ USERPROFILE: home,
+ HOME: home,
+ CUMORA_BYOA_ALLOW_UNSANDBOXED: compatibility ? '1' : '0',
+ })
+ let output = ''
+ try {
+ await execFileAsync(process.execPath, [
+ '--import', import.meta.resolve('tsx'),
+ fileURLToPath(new URL('../cli-bin.ts', import.meta.url)),
+ 'agent', 'computer', '--pair', 'fixture-code', '--server', serverUrl,
+ '--engine', preferred, '--install-service',
+ ], { cwd: dir, env, timeout: 20_000, windowsHide: true })
+ assert.fail('the fixture must stop before installing a service')
+ } catch (error) {
+ const result = error as Error & { code?: number; killed?: boolean; stdout?: string; stderr?: string }
+ assert.equal(result.code, 1, result.message)
+ assert.ok(!result.killed, 'CLI must fail promptly, not time out')
+ output = `${result.stdout ?? ''}${result.stderr ?? ''}`
+ }
+ assert.deepEqual(await readdir(home), [], 'pairing failure must not write config or supervisor files')
+ return output
+ }
+
+ await t.test('installed Pi with runnable Codex produces the PowerShell compatibility hint', async () => {
+ const output = await run('installed-pi', { claude: '2.1.199', codex: '0.138.0', pi: '0.85.1' }, 'pi')
+ assert.match(output, /pi is installed but cannot run/)
+ assert.ok(output.includes("$env:CUMORA_BYOA_ALLOW_UNSANDBOXED = '1'"))
+ assert.doesNotMatch(output, /pi (?:is not installed|was not found)/)
+ assert.equal(requests.length, 0)
+ const assignment = output.split('\n').find((line) => line.trim().startsWith('$env:'))?.trim()
+ assert.ok(assignment)
+ const powershell = join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe')
+ const result = await execFileAsync(powershell, [
+ '-NoProfile', '-NonInteractive', '-Command',
+ `${assignment}; [Console]::Write($env:CUMORA_BYOA_ALLOW_UNSANDBOXED)`,
+ ], { timeout: 10_000, windowsHide: true })
+ assert.equal(result.stdout, '1', 'the displayed assignment must work in PowerShell')
+ })
+ await t.test('missing Pi is diagnosed from the unfiltered PATH inventory', async () => {
+ const output = await run('missing-pi', { claude: '2.1.199', codex: '0.138.0' }, 'pi')
+ assert.match(output, /pi was not found on PATH\. Installed: claude, codex\./)
+ assert.equal(requests.length, 0)
+ })
+ await t.test('Pi alone still receives its specific policy refusal', async () => {
+ const output = await run('only-pi', { pi: '0.85.1' }, 'pi')
+ assert.match(output, /pi is installed but cannot run/)
+ assert.equal(requests.length, 0)
+ })
+ await t.test('an old Codex receives the version refusal and PowerShell hint', async () => {
+ const output = await run('old-codex', { codex: '0.137.9' }, 'codex')
+ assert.match(output, /version 0.137.9 is older than the secure minimum 0.138.0/)
+ assert.ok(output.includes("$env:CUMORA_BYOA_ALLOW_UNSANDBOXED = '1'"))
+ assert.equal(requests.length, 0)
+ })
+ await t.test('compatibility opt-in reaches pairing with Pi as the default engine', async () => {
+ const output = await run('compatibility', { codex: '0.138.0', pi: '0.85.1' }, 'pi', true)
+ assert.match(output, /fixture pairing rejected/)
+ assert.equal(requests.length, 1)
+ assert.equal(requests[0].path, '/api/computers/pair')
+ assert.deepEqual(requests[0].body.engines, ['pi', 'codex'])
+ })
+ await t.test('secure Codex still reaches pairing without exposing Pi as runnable', async () => {
+ const output = await run('secure-codex', { codex: '0.138.0', pi: '0.85.1' }, 'codex')
+ assert.match(output, /fixture pairing rejected/)
+ assert.equal(requests.length, 2)
+ assert.deepEqual(requests[1].body.engines, ['codex'])
+ })
+ } finally {
+ await new Promise<void>((done) => server.close(() => done()))
+ assert.ok(resolve(root).startsWith(`${resolve(tmpdir())}${sep}`))
+ await rm(root, { recursive: true, force: true })
+ }
+})
diff --git a/server/src/__tests__/agents-computer-pairing-engine.test.ts b/server/src/__tests__/agents-computer-pairing-engine.test.ts
new file mode 100644
index 0000000..deac27c
--- /dev/null
+++ b/server/src/__tests__/agents-computer-pairing-engine.test.ts
@@ -0,0 +1,87 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { validatePairingEngine } from '../agents/computer/daemon.js'
+import { runnableEngineIds, type EngineId } from '../agents/computer/engine.js'
+
+test('installed Pi is reported as policy-disabled even when Codex is runnable (#289)', () => {
+ const installed: EngineId[] = ['claude', 'codex', 'pi']
+ for (const platform of ['win32', 'linux', 'darwin'] as const) {
+ const evaluated = { runnable: runnableEngineIds(installed, {}, platform), blocked: [] }
+ assert.throws(() => validatePairingEngine('pi', installed, evaluated, platform), (error: Error) => {
+ assert.match(error.message, /pi is installed but cannot run/)
+ assert.match(error.message, /secure BYOA default/)
+ assert.match(error.message, /CUMORA_BYOA_ALLOW_UNSANDBOXED/)
+ assert.doesNotMatch(error.message, /not installed|not found on PATH/)
+ return true
+ })
+ }
+})
+
+test('policy and capability refusals show compatibility instructions for the target platform', () => {
+ for (const platform of ['win32', 'linux', 'darwin'] as const) {
+ for (const id of ['pi', 'claude'] as const) {
+ const blocked = id === 'claude' ? [{ id, reason: 'version below secure minimum' }] : []
+ assert.throws(() => validatePairingEngine(id, [id], { runnable: [], blocked }, platform), (error: Error) => {
+ if (platform === 'win32') {
+ assert.match(error.message, /PowerShell:/)
+ assert.ok(error.message.includes("$env:CUMORA_BYOA_ALLOW_UNSANDBOXED = '1'"))
+ assert.match(error.message, /rerun your original Cumora command in this PowerShell session/)
+ assert.doesNotMatch(error.message, /CUMORA_BYOA_ALLOW_UNSANDBOXED=1 npx/)
+ } else {
+ assert.match(error.message, /CUMORA_BYOA_ALLOW_UNSANDBOXED=1 npx cumora@latest agent computer/)
+ assert.doesNotMatch(error.message, /PowerShell|\$env:/)
+ }
+ return true
+ })
+ }
+ }
+})
+
+test('Pi is diagnosed specifically even when no engine is runnable', () => {
+ assert.throws(
+ () => validatePairingEngine('pi', ['pi'], { runnable: [], blocked: [] }),
+ /pi is installed but cannot run/,
+ )
+})
+
+test('a missing requested engine lists the raw installed inventory', () => {
+ assert.throws(
+ () => validatePairingEngine('pi', ['claude', 'codex'], { runnable: ['codex'], blocked: [] }),
+ /pi was not found on PATH\. Installed: claude, codex\./,
+ )
+ assert.throws(
+ () => validatePairingEngine('pi', [], { runnable: [], blocked: [] }),
+ /pi was not found on PATH\. Installed: none\./,
+ )
+})
+
+test('a requested engine with an incompatible version reports its own reason', () => {
+ const reason = 'version 2.1.199 is older than the secure minimum 2.1.248'
+ assert.throws(
+ () => validatePairingEngine('claude', ['claude', 'codex'], {
+ runnable: ['codex'], blocked: [{ id: 'claude', reason }],
+ }),
+ (error: Error) => {
+ assert.match(error.message, /claude is installed but cannot run/)
+ assert.ok(error.message.includes(reason))
+ return true
+ },
+ )
+})
+
+test('an unknown engine is rejected even with an empty inventory', () => {
+ assert.throws(
+ () => validatePairingEngine('unknown', [], { runnable: [], blocked: [] }),
+ /--engine must be one of:/,
+ )
+})
+
+test('secure Codex and explicitly opted-in Pi remain valid choices', () => {
+ const installed: EngineId[] = ['codex', 'pi']
+ assert.doesNotThrow(() => validatePairingEngine('codex', installed, {
+ runnable: runnableEngineIds(installed, {}, 'win32'), blocked: [],
+ }))
+ assert.doesNotThrow(() => validatePairingEngine('pi', installed, {
+ runnable: runnableEngineIds(installed, { CUMORA_BYOA_ALLOW_UNSANDBOXED: '1' }, 'win32'), blocked: [],
+ }))
+})
diff --git a/server/src/agents/computer/daemon.ts b/server/src/agents/computer/daemon.ts
index 881f400..64b780d 100644
--- a/server/src/agents/computer/daemon.ts
+++ b/server/src/agents/computer/daemon.ts
@@ -861,29 +861,39 @@ function missingEngineMessage(): string {
].join('\n')
}
-function sandboxedEngineMessage(installed: readonly EngineId[]): string {
+function unsandboxedCompatibilityHint(platform: NodeJS.Platform): string {
+ return platform === 'win32'
+ ? [
+ ' PowerShell:',
+ " $env:CUMORA_BYOA_ALLOW_UNSANDBOXED = '1'",
+ ' # Then rerun your original Cumora command in this PowerShell session.',
+ ].join('\n')
+ : ' CUMORA_BYOA_ALLOW_UNSANDBOXED=1 npx cumora@latest agent computer ...'
+}
+
+function sandboxedEngineMessage(installed: readonly EngineId[], platform: NodeJS.Platform = process.platform): string {
return [
`installed engines are disabled by Cumora's secure BYOA default: ${installed.join(', ')}`,
'',
- process.platform === 'win32'
+ platform === 'win32'
? 'Use Codex on native Windows, or run Claude Code inside WSL2.'
: 'Install and sign in to Claude Code or Codex.',
'Grok, Cursor, OpenCode, pi, Gemini, Qwen, Antigravity, and native-Windows Claude currently lack',
'a Cumora-verified fail-closed host boundary.',
'',
'Compatibility only (grants the model your host files, environment, and network):',
- ' CUMORA_BYOA_ALLOW_UNSANDBOXED=1 npx cumora@latest agent computer ...',
+ unsandboxedCompatibilityHint(platform),
].join('\n')
}
-function incapableEngineMessage(blocked: ReadonlyArray<{ id: EngineId; reason: string }>): string {
+function incapableEngineMessage(blocked: ReadonlyArray<{ id: EngineId; reason: string }>, platform: NodeJS.Platform = process.platform): string {
return [
'installed secure engines cannot enforce Cumora\'s BYOA boundary:',
...blocked.map(({ id, reason }) => ` - ${id}: ${reason}`),
'',
'Update the CLI and install any named sandbox dependencies, then retry.',
'Compatibility only (disables this capability gate and host boundary):',
- ' CUMORA_BYOA_ALLOW_UNSANDBOXED=1 npx cumora@latest agent computer ...',
+ unsandboxedCompatibilityHint(platform),
].join('\n')
}
@@ -938,6 +948,30 @@ async function blockedSnapshotRows(
}))
}
+/** Diagnose an explicit choice without confusing installation with permission
+ * to run. Both inventories come from the same scan. */
+export function validatePairingEngine(
+ preferredEngine: string,
+ installed: readonly EngineId[],
+ evaluated: RunnableEngineEvaluation,
+ platform: NodeJS.Platform = process.platform,
+): void {
+ if (!ENGINE_IDS.includes(preferredEngine as EngineId)) {
+ throw new Error(`--engine must be one of: ${ENGINE_IDS.join(', ')} (got "${preferredEngine}")`)
+ }
+ const id = preferredEngine as EngineId
+ if (!installed.includes(id)) {
+ throw new Error(`--engine ${id} chosen, but ${id} was not found on PATH. Installed: ${installed.join(', ') || 'none'}.`)
+ }
+ if (!evaluated.runnable.includes(id)) {
+ const blocked = evaluated.blocked.find((entry) => entry.id === id)
+ throw new Error([
+ `--engine ${id} chosen: ${id} is installed but cannot run under Cumora's secure BYOA default.`,
+ blocked ? incapableEngineMessage([blocked], platform) : sandboxedEngineMessage([id], platform),
+ ].join('\n\n'))
+ }
+}
+
/** The engines this machine can run, plus the ones it cannot and why.
*
* The refusals used to stop at the console.warn below. Pairing then reported
@@ -945,13 +979,16 @@ async function blockedSnapshotRows(
* engine that was skipped until the first PATH rescan minutes later — which is
* precisely the window in which someone asks why their Claude Code is not
* listed. */
-async function requireLocalEngine(): Promise<RunnableEngineEvaluation> {
+async function requireLocalEngine(preferredEngine?: string): Promise<RunnableEngineEvaluation> {
const detected = await detectEnginesWithStatus()
if (!detected.reliable) {
throw new Error('could not scan PATH (`which` / `where` failed). Fix that, then retry pairing.')
}
- if (detected.engines.length === 0) throw new Error(missingEngineMessage())
const evaluated = await evaluateRunnableEngines(detected.engines)
+ // Check the requested engine against the raw PATH inventory first. The
+ // runnable list excludes installed engines refused by the security policy.
+ if (preferredEngine) validatePairingEngine(preferredEngine, detected.engines, evaluated)
+ if (detected.engines.length === 0) throw new Error(missingEngineMessage())
if (evaluated.runnable.length === 0) {
if (evaluated.blocked.length > 0) throw new Error(incapableEngineMessage(evaluated.blocked))
throw new Error(sandboxedEngineMessage(detected.engines))
@@ -1531,21 +1568,15 @@ async function detectHostName(): Promise<string> {
}
async function doPair(code: string, serverUrl: string, preferredEngine?: string): Promise<void> {
- const evaluated = await requireLocalEngine()
- const detected = evaluated.runnable
+ const evaluated = await requireLocalEngine(preferredEngine)
+ const runnable = evaluated.runnable
// The chosen engine becomes this computer's DEFAULT — it's sent first in the
// engines list, which the server stores as available_engines[0] and uses as
// the engine for the starter team and any agent assigned here without an
// explicit override. (No separate column needed: "first = default".)
- let engines = [...detected]
+ let engines = [...runnable]
if (preferredEngine) {
- if (!ENGINE_IDS.includes(preferredEngine as EngineId)) {
- throw new Error(`--engine must be one of: ${ENGINE_IDS.join(', ')} (got "${preferredEngine}")`)
- }
- if (!detected.includes(preferredEngine as EngineId)) {
- throw new Error(`--engine ${preferredEngine} chosen, but ${preferredEngine} is not installed on this machine. Installed: ${detected.join(', ') || 'none'}.`)
- }
- engines = [preferredEngine as EngineId, ...detected.filter((e) => e !== preferredEngine)]
+ engines = [preferredEngine as EngineId, ...runnable.filter((e) => e !== preferredEngine)]
}
const blockedIds = evaluated.blocked.map(({ id }) => id)
const snapshot = [