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
/** Engine version probing, run on the daemon's own machine.
*
* The Computers tab shows, per engine, the version installed on *that*
* computer. Only the daemon can answer that — the desktop app can scan its own
* PATH, but that is a different machine whenever you are not sitting at the one
* you paired. So the probe lives here and rides the heartbeat's engine rescan.
*
* Local versions are re-probed on every rescan (cheap: one spawn per engine,
* against an already-resolved absolute path). Upstream "latest" lookups hit the
* network — or a slow `about` / `update --check` subcommand — so they are cached
* well past the rescan interval.
*/
import { spawn } from 'node:child_process'
import fs from 'node:fs'
import path from 'node:path'
interface CommandInvocation {
command: string
args: string[]
windowsVerbatimArguments?: boolean
}
/** npm on Windows installs an extensionless POSIX shim before the runnable
* `.cmd` shim in `where` output. CreateProcess cannot execute either file
* directly, so select the sibling batch shim and invoke it through ComSpec. */
export function versionCommandInvocation(
command: string,
args: string[],
platform = process.platform,
comspec = process.env.ComSpec || 'cmd.exe',
forceShell = false,
): CommandInvocation {
if (platform !== 'win32') return { command, args }
let runnable = command
if (!/\.(?:cmd|bat|com|exe)$/i.test(runnable)) {
for (const ext of ['.cmd', '.bat', '.exe', '.com']) {
if (fs.existsSync(`${command}${ext}`)) {
runnable = `${command}${ext}`
break
}
}
}
if (!forceShell && !/\.(?:cmd|bat)$/i.test(runnable)) return { command: runnable, args }
return comspecInvocation(comspec, runnable, args)
}
/** cmd.exe `/s /c` with one quoted command line. Node's `shell: true` joins
* argv without quoting, so a model id containing `&` becomes a second command.
* Arguments outside the unquoted token set are quoted; quotes inside them are
* doubled, which is cmd's escape. */
function comspecInvocation(comspec: string, runnable: string, args: string[]): CommandInvocation {
const commandArgs = args.map((arg) => {
const value = String(arg)
return /^[\w./:=+-]+$/u.test(value) ? value : `"${value.replace(/"/g, '""')}"`
})
const commandLine = `""${runnable}"${commandArgs.length ? ` ${commandArgs.join(' ')}` : ''}"`
return {
command: comspec,
args: ['/d', '/s', '/c', commandLine],
windowsVerbatimArguments: true,
}
}
/** How to ask an engine its version, and how to find out what the newest one is. */
export interface EngineVersionSpec {
/** Args that make the binary print its version (`--version` for all but hermes). */
versionArgs: string[]
/** npm package, when the CLI ships on the public registry. */
npm?: string
/** Extra flags the vendor documents for a global install (pi needs --ignore-scripts). */
npmFlags?: string
/** Homebrew formula, when the CLI is also brewable. */
brew?: string
/** The vendor's own updater, preferred over brew/npm when it exists. */
selfUpdate?: string
/** Restrict a vendor updater to binaries owned by its standalone installer. */
selfUpdatePath?: RegExp
/** CLIs that report upstream themselves instead of via the npm registry. */
latestVia?: 'cursor-about' | 'grok-check'
}
/** Keep in sync with src/lib/engines.ts (ENGINE_LABEL / ENGINE_BIN /
* RUNNABLE_ENGINE_IDS) and, for engines Cumora can actually wake, ENGINE_IDS
* in agents/computer/engine.ts. */
export const ENGINE_VERSION_SPECS: Record<string, EngineVersionSpec> = {
claude: {
versionArgs: ['--version'],
npm: '@anthropic-ai/claude-code',
brew: 'claude-code',
selfUpdate: 'claude update',
},
cursor: {
versionArgs: ['--version'],
latestVia: 'cursor-about',
selfUpdate: 'cursor-agent update',
},
codex: {
versionArgs: ['--version'],
npm: '@openai/codex',
brew: 'codex',
selfUpdate: 'codex update',
selfUpdatePath: /[/\\]\.codex[/\\]packages[/\\]standalone[/\\]/i,
},
grok: {
versionArgs: ['--version'],
latestVia: 'grok-check',
npm: '@xai-official/grok',
selfUpdate: 'grok update',
},
opencode: {
versionArgs: ['--version'],
npm: 'opencode-ai',
selfUpdate: 'opencode upgrade',
},
pi: {
versionArgs: ['--version'],
npm: '@earendil-works/pi-coding-agent',
npmFlags: '--ignore-scripts',
selfUpdate: 'pi update',
},
gemini: {
versionArgs: ['--version'],
npm: '@google/gemini-cli',
brew: 'gemini-cli',
},
qwen: {
versionArgs: ['--version'],
npm: '@qwen-code/qwen-code',
},
antigravity: {
versionArgs: ['--version'],
selfUpdate: 'agy update',
},
zcode: {
versionArgs: ['--version'],
},
maka: {
versionArgs: ['--version'],
selfUpdate: 'maka update --target latest',
},
omp: {
versionArgs: ['--version'],
npm: '@oh-my-pi/pi-coding-agent',
selfUpdate: 'omp update',
},
hermes: {
versionArgs: ['version'],
selfUpdate: 'hermes update',
},
}
/** Upstream versions change on the vendor's release cadence, not ours, and the
* rescan runs every 5 minutes. Cache far longer than the rescan so a paired
* machine is not making the same registry call all day. A stale `latest` only
* delays noticing a new release; it never produces a wrong "outdated" badge,
* because the *local* side of the comparison is always freshly probed. */
const LATEST_TTL_MS = 6 * 60 * 60 * 1000
const latestCache = new Map<string, { at: number; version: string | null }>()
/** Test seam: drop memoized upstream versions. */
export function clearLatestCache(): void {
latestCache.clear()
}
/** Pull the first version-looking token out of CLI output. Accepts both semver
* and the CalVer some vendors print (`2026.08.30`). */
/** Lines that carry a version number but never the CLI's OWN version.
*
* `npm warn EBADENGINE Unsupported engine { required: { node: '>=20.19.0' } }`
* and `(node:1234) [DEP0040] DeprecationWarning: …` both routinely precede a
* CLI's real output, and both contain something that looks exactly like a
* version. Taking the first match in the combined stream then reads the
* warning's number as the engine's version — which is how a Claude Code 2.0.9
* came back as "20.19.0" and satisfied the 2.1.248 secure floor. The gate that
* exists to refuse an un-sandboxable CLI failed OPEN on unrelated noise. */
const VERSION_NOISE_LINE =
/^\s*(?:npm\s+(?:warn|WARN|notice|err)|\(node:\d+\)|warning:|warn\b|deprecat|debugger\s|\[dep\d)/i
const VERSION_TOKEN = /v?(\d{4}\.\d{2}\.\d{2}(?:-[\w.]+)?|\d+\.\d+\.\d+(?:[-+][\w.]+)?)/i
/** The version a command reported. stdout is what a CLI prints its own version
* on, so it is asked first; stderr is only a fallback for the engines that
* report there, and can no longer outrank the real answer. */
export function versionFromOutput(out: CommandOutput): string | null {
return parseCliVersion(out.stdout) ?? parseCliVersion(out.stderr)
}
/** The version a CLI reported, ignoring lines that are someone else's version.
*
* Scans line by line rather than the blob so a warning cannot win merely by
* arriving first. */
export function parseCliVersion(text: string | null | undefined): string | null {
if (!text) return null
// Warnings are frequently multi-line, and only the FIRST line carries the
// marker — npm's EBADENGINE puts the version on an indented continuation:
// npm warn EBADENGINE Unsupported engine {
// required: { node: '>=20.19.0' }
// }
// So a line is noise if it announces itself as one, or if it is a
// continuation of one: indented, or a bare closing brace. Suppression only
// ever begins after a marker line, so output with no warnings is untouched.
let inNoise = false
for (const line of String(text).split(/\r?\n/)) {
if (VERSION_NOISE_LINE.test(line)) { inNoise = true; continue }
if (inNoise && (/^\s+\S/.test(line) || /^\s*[)}\]]+[,;]?\s*$/.test(line) || line.trim() === '')) continue
inNoise = false
const m = line.match(VERSION_TOKEN)
if (m) return m[1]
}
return null
}
function versionParts(v: string): number[] {
const main = String(v).replace(/^v/i, '').split(/[-+]/)[0] ?? ''
return main.split('.').map((n) => Number.parseInt(n, 10) || 0)
}
/** Semver/CalVer floor used for local capability gates. A prerelease at the
* exact numeric floor remains below the final release; unknown versions fail
* closed at the caller. */
export function isCliVersionAtLeast(current: string | null, minimum: string): boolean {
if (!current) return false
const a = versionParts(current)
const b = versionParts(minimum)
const n = Math.max(a.length, b.length)
for (let i = 0; i < n; i++) {
const x = a[i] ?? 0
const y = b[i] ?? 0
if (x > y) return true
if (x < y) return false
}
const currentMain = current.trim().replace(/^v/i, '').split('+', 1)[0]
const minimumMain = minimum.trim().replace(/^v/i, '').split('+', 1)[0]
return !(currentMain.includes('-') && !minimumMain.includes('-'))
}
/** True only when `latest` is strictly newer. Unknown on either side means we
* say nothing rather than nag. */
export function isCliOutdated(current: string | null, latest: string | null): boolean {
if (!current || !latest) return false
if (current === latest) return false
const a = versionParts(current)
const b = versionParts(latest)
const n = Math.max(a.length, b.length)
for (let i = 0; i < n; i++) {
const x = a[i] ?? 0
const y = b[i] ?? 0
if (y > x) return true
if (y < x) return false
}
return false
}
function realpathOf(binPath: string): string {
try {
return fs.realpathSync(binPath)
} catch {
return binPath
}
}
/** npm's Windows shims are a few hundred bytes; anything larger is not one, and
* reading a real binary looking for a package name would be pointless work. */
const SHIM_READ_LIMIT = 64 * 1024
/** The package directory `file` sits inside, when that directory is in a
* node_modules tree — `…/node_modules/@openai/codex/bin/codex.js` is in
* @openai/codex. */
function owningPackageDir(file: string): string | null {
for (let dir = path.dirname(file); ; dir = path.dirname(dir)) {
const parent = path.dirname(dir)
if (parent === dir) return null
const above = path.basename(parent)
// `<pkg>` directly under node_modules, or `<@scope>/<pkg>` under it.
if (above === 'node_modules') return dir
if (above.startsWith('@') && path.basename(path.dirname(parent)) === 'node_modules') return dir
}
}
/** The version the package containing `file` records, or null when `file` is in
* none — the read half of `npmPackageVersion`, shared by both shapes. */
function versionOfOwner(file: string): string | null {
const owner = owningPackageDir(realpathOf(file))
return owner ? versionFromPackageJson(owner) : null
}
/** The path a shim names at `at`, the position of its `/node_modules/`: the text
* before that is the directory the line starts from — the shim's own (`%dp0%`,
* `%~dp0`, `$basedir`) or a real path — and the text after it runs to the end of
* the quoted path. pnpm keeps a store directory in between
* (`…/global/5/node_modules`), so the prefix is resolved, not assumed to sit
* beside the shim. Null when a variable is left unexpanded: a name nothing can
* be read from. */
function shimPathAt(flat: string, at: number, shimDir: string): string | null {
// pnpm quotes every path it writes, and a global directory may hold a space
// (`…/global packages/5/…`), so a quoted span — not whitespace — is the
// boundary when there is one. Quotes never span a line in a shim.
const from = flat.lastIndexOf('\n', at) + 1
let to = flat.indexOf('\n', at)
if (to < 0) to = flat.length
let span: [number, number] | null = null
let open = -1
let quote = ''
for (let i = from; i < to && !span; i++) {
const ch = flat.charAt(i)
if (!quote) {
if (ch === '"' || ch === "'") {
quote = ch
open = i
}
} else if (ch === quote) {
if (at > open && at < i) span = [open + 1, i]
quote = ''
}
}
if (!span && quote && at > open) span = [open + 1, to]
if (!span) {
let start = at
while (start > from && !/[\s(=;,`]/.test(flat.charAt(start - 1))) start--
let stop = at
while (stop < to && !/[\s);,`]/.test(flat.charAt(stop))) stop++
span = [start, stop]
}
let token = flat.slice(span[0], span[1])
const self = /^(?:%~dp0|%dp0%|\$basedir|\$\{basedir\})\/?/i.exec(token)
if (self) token = token.slice(self[0].length).replace(/^\/+/, '')
if (/[%$]/.test(token)) return null
return path.resolve(shimDir, token)
}
function versionFromPackageJson(pkgDir: string): string | null {
try {
const raw = fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf8')
const version = (JSON.parse(raw) as { version?: unknown }).version
return typeof version === 'string' ? parseCliVersion(version) : null
} catch {
return null
}
}
/** The version recorded by the npm package that owns `binPath`, or null when it
* belongs to none — read, never run.
*
* Two shapes, because npm puts a shim *beside* node_modules rather than a link
* into it: a path already inside the package tree is answered by walking up to
* its package.json, while `C:\…\opencode` (the shim) only names the package in
* its text (`%dp0%\node_modules\opencode-ai\bin\opencode.exe`). Magpie splits
* these the same way, as npmVersion and shimVersion. pnpm's shim is the second
* shape with the store in the middle — `%~dp0\..\global\5\node_modules\…` — so
* the path is resolved from the shim's directory instead of assumed beside it.
*
* This exists because an installed CLI can fail to answer: opencode-ai ships a
* placeholder `bin/opencode.exe` until its postinstall runs, and that
* placeholder exits with an error instead of a version — so the Computers tab
* read "版本未知" for a CLI whose package plainly said 1.19.4. */
export function npmPackageVersion(binPath: string | null): string | null {
if (!binPath) return null
const real = realpathOf(binPath)
const owned = versionOfOwner(real)
if (owned) return owned
let text: string
try {
const stat = fs.statSync(real)
if (!stat.isFile() || stat.size > SHIM_READ_LIMIT) return null
text = fs.readFileSync(real, 'utf8')
} catch {
return null
}
// Shims spell the path with the separator of the platform they came from, and
// a pnpm shim mentions several; take the first that names an installed package.
const flat = text.replace(/\\/g, '/')
for (let at = flat.indexOf('/node_modules/'); at >= 0; at = flat.indexOf('/node_modules/', at + 1)) {
const target = shimPathAt(flat, at, path.dirname(real))
const version = target ? versionOfOwner(target) : null
if (version) return version
}
return null
}
/** What this machine has installed for one engine: what the CLI prints, else
* what its npm package records.
*
* Asked in that order deliberately, unlike magpie (which reads the package
* first and so never runs an npm CLI): `claude update` and `codex update`
* replace the binary in place, so the printed version describes what will
* actually run while package.json can lag behind it. The package is only the
* fallback for a CLI that cannot answer at all — which is the whole bug. */
async function installedVersion(id: string, binPath: string): Promise<string | null> {
const spec = ENGINE_VERSION_SPECS[id]
if (!spec) return null
const printed = versionFromOutput(await spawnCommand(binPath, spec.versionArgs, 6000))
return printed ?? npmPackageVersion(binPath)
}
export function isHomebrewInstall(real: string, formula: string): boolean {
// npm under Homebrew's Node belongs to npm, not the Node formula's keg.
return real.match(/(?:^|[/\\])(?:Cellar|Caskroom)[/\\]([^/\\]+)[/\\]/i)?.[1] === formula
}
/** Prefer the CLI's own updater when it has one (`pi update`, `claude update`):
* that is the path vendors document, and it behaves the same on Windows. Fall
* back to brew only when the binary actually came from brew, else npm. */
export function inferUpdateCommand(spec: EngineVersionSpec, binPath: string | null): string | null {
if (spec.selfUpdate && (!spec.selfUpdatePath || (binPath && spec.selfUpdatePath.test(realpathOf(binPath))))) {
return spec.selfUpdate
}
if (spec.brew && binPath && isHomebrewInstall(realpathOf(binPath), spec.brew)) {
return `brew upgrade ${spec.brew}`
}
if (!spec.npm) return null
return `npm install -g ${spec.npmFlags ? `${spec.npmFlags} ` : ''}${spec.npm}@latest`
}
export function parseCursorAbout(text: string): string | null {
const latestLine = text.split(/\r?\n/).find((line) => /^\s*Latest\b/i.test(line))
if (!latestLine) return null
return parseCliVersion(latestLine)
}
export function parseGrokCheck(text: string): string | null {
try {
const data = JSON.parse(text) as Record<string, unknown>
return typeof data.latestVersion === 'string' ? data.latestVersion : null
} catch {
return parseCliVersion(text)
}
}
export interface CommandOutput {
stdout: string
stderr: string
/** stdout first — the order every combined-text caller wants. */
combined: string
/** Exit code, or null when it never ran or was killed on timeout. */
code?: number | null
}
/** Run a command and return its output, or empty strings on any failure. Never
* rejects: a missing or wedged CLI must not take down the rescan.
*
* The streams are returned APART because they mean different things: a CLI
* prints its version on stdout and its warnings on stderr, and merging them
* let an `npm warn EBADENGINE … node: '>=20.19.0'` line stand in for an
* engine's version at the secure floor. */
function spawnCommand(cmd: string, args: string[], timeoutMs: number, forceShell = false): Promise<CommandOutput> {
return new Promise((resolve) => {
let settled = false
let child: ReturnType<typeof spawn>
try {
const invocation = versionCommandInvocation(cmd, args, process.platform, undefined, forceShell)
child = spawn(invocation.command, invocation.args, {
stdio: ['ignore', 'pipe', 'pipe'],
windowsHide: true,
windowsVerbatimArguments: invocation.windowsVerbatimArguments === true,
})
} catch {
resolve({ stdout: '', stderr: '', combined: '', code: null })
return
}
// Kept apart, then joined stdout-first. A CLI prints its version on stdout
// and its warnings on stderr, so scanning stdout first means a warning
// cannot win by arriving earlier — which is what let an npm EBADENGINE
// line stand in for an engine's version at the secure floor. Some engines
// do report the version on stderr, so it stays in the text, just after.
let stdout = ''
let stderr = ''
child.stdout?.on('data', (buf: Buffer) => { stdout += buf.toString('utf8') })
child.stderr?.on('data', (buf: Buffer) => { stderr += buf.toString('utf8') })
const captured = (code: number | null): CommandOutput => ({
stdout: stdout.trim(),
stderr: stderr.trim(),
combined: `${stdout}\n${stderr}`.trim(),
code,
})
const finish = (value: CommandOutput) => {
if (settled) return
settled = true
clearTimeout(timer)
resolve(value)
}
const timer = setTimeout(() => {
// shortcut: kills the direct child only, so a wedged npm.cmd can outlive
// this on Windows; upgrade to a process-tree kill if that shows up.
try { child.kill() } catch { /* already gone */ }
finish(captured(null))
}, timeoutMs)
child.on('error', () => finish({ stdout: '', stderr: '', combined: '', code: null }))
child.on('close', (code) => finish(captured(code)))
})
}
async function npmLatest(pkg: string): Promise<string | null> {
try {
const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(pkg)}/latest`, {
headers: { 'User-Agent': 'cumora-daemon', Accept: 'application/json' },
signal: AbortSignal.timeout(5000),
})
if (!res.ok) return null
const data = await res.json() as Record<string, unknown>
return typeof data.version === 'string' ? data.version : null
} catch {
return null
}
}
async function probeLatest(id: string, spec: EngineVersionSpec, binPath: string | null): Promise<string | null> {
const cached = latestCache.get(id)
if (cached && Date.now() - cached.at < LATEST_TTL_MS) return cached.version
let version: string | null = null
try {
if (spec.latestVia === 'cursor-about' && binPath) {
const about = (await spawnCommand(binPath, ['about'], 10_000)).combined
version = parseCursorAbout(about) || parseCliVersion(about)
} else if (spec.latestVia === 'grok-check' && binPath) {
const check = (await spawnCommand(binPath, ['update', '--check', '--json'], 12_000)).combined
version = parseGrokCheck(check)
}
if (!version && spec.npm) version = await npmLatest(spec.npm)
} catch {
version = null
}
latestCache.set(id, { at: Date.now(), version })
return version
}
/** What the daemon reports per engine, beyond the bin path. */
export interface EngineVersionInfo {
version: string | null
latest: string | null
outdated: boolean
updateCommand: string | null
}
/** Probe one engine on this machine. `binPath` is the already-resolved absolute
* path, so this never depends on the daemon's PATH being as rich as a shell's. */
export async function probeEngineVersion(id: string, binPath: string | null): Promise<EngineVersionInfo> {
const spec = ENGINE_VERSION_SPECS[id]
const empty: EngineVersionInfo = { version: null, latest: null, outdated: false, updateCommand: null }
if (!spec || !binPath) return empty
const version = await installedVersion(id, binPath)
const latest = await probeLatest(id, spec, binPath)
const outdated = isCliOutdated(version, latest)
return {
version,
latest,
outdated,
updateCommand: outdated ? inferUpdateCommand(spec, binPath) : null,
}
}
/** Local-only version probe for security capability gates. Unlike
* probeEngineVersion(), this never contacts npm or an engine updater — and,
* unlike it, never falls back to package.json either: this answer decides
* whether a binary may run under the sandbox, so a CLI that cannot say what it
* is stays unverified rather than borrowing the version of the package it was
* installed from. */
export async function probeLocalEngineVersion(id: string, binPath: string | null): Promise<string | null> {
const spec = ENGINE_VERSION_SPECS[id]
if (!spec || !binPath) return null
return versionFromOutput(await spawnCommand(binPath, spec.versionArgs, 6000))
}
/** Retry only an inconclusive local version probe. A concrete version (whether
* compatible or too old) is authoritative and returns immediately. Delays are
* injectable so the retry contract can be tested without wall-clock sleeps. */
export async function probeLocalEngineVersionWithRetry(
id: string,
binPath: string | null,
retryDelaysMs: readonly number[] = [0, 250, 1000],
): Promise<string | null> {
if (!binPath) return null
for (const delayMs of retryDelaysMs) {
if (delayMs > 0) await new Promise<void>((resolve) => setTimeout(resolve, delayMs))
const version = await probeLocalEngineVersion(id, binPath)
if (version) return version
}
return null
}
/** A global npm install or a brew upgrade downloads and unpacks: minutes, not
* seconds, on a slow link. */
const UPDATE_TIMEOUT_MS = 10 * 60 * 1000
/** The update as argv. The CLI's own updater is named after the CLI (`claude
* update`), and on Windows a bare `claude` is a `.cmd` shim only cmd.exe can
* start — so the resolved path takes its place. npm and brew stay as they are:
* they are package managers, not the CLI. */
export function updateArgv(command: string, binPath: string | null): string[] {
const argv = command.split(/\s+/)
if (binPath && argv[0] !== 'npm' && argv[0] !== 'brew') argv[0] = binPath
return argv
}
/** Run one engine's update on this machine and say whether it worked.
*
* The command is derived here from the same spec that produced the command the
* app shows, and only the engine *id* ever crosses the wire — a request can
* pick which known updater runs, never what it is.
*
* shortcut: the daemon's own PATH is thinner than a login shell's, so an npm
* that lives under a version manager may not be the one found here; upgrade to
* resolving npm/brew from the CLI's own folder if a mis-install shows up. */
export async function runEngineUpdate(
id: string,
binPath: string | null,
): Promise<{ ok: boolean; command: string | null; error?: string }> {
if (!binPath) return { ok: false, command: null, error: `${id} is no longer installed` }
const spec = ENGINE_VERSION_SPECS[id]
const command = spec ? inferUpdateCommand(spec, binPath) : null
if (!command) return { ok: false, command, error: `no update command is known for ${id}` }
// The cached "latest" is 6 hours old by design; after an update it would make
// the engine read as still behind until it expires.
latestCache.delete(id)
const [file, ...args] = updateArgv(command, binPath)
if (!file) return { ok: false, command, error: `no update command is known for ${id}` }
// Through ComSpec on Windows: `npm` is a .cmd shim there, and CreateProcess
// cannot start one directly.
const out = await spawnCommand(file, args, UPDATE_TIMEOUT_MS, true)
if (out.code === 0) return { ok: true, command }
const detail = out.combined.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).pop()
return { ok: false, command, error: detail || `exit ${out.code ?? 'timeout'}` }
}