hermes-agent/apps/desktop/electron/backend-probes.ts
Brooklyn Nicholson b9cb268def fix(desktop): quote spaced Windows shell commands before cmd.exe truncates them
With shell: true, spawn hands the command line to cmd.exe, which cuts it at
the first unquoted space, so installs under spaced paths (C:\Users\John Doe\…)
fail every probe and backend launch. Adds windowsShellCommand() and applies it
at the four shell-delegating sites: the --version probe, the serve --help
probe, and both spawnOwnedBackend call sites.

Adapted from #74073 (thanks @dk3yyyy) to current site locations.
2026-09-29 18:42:10 -05:00

194 lines
5.3 KiB
TypeScript

/** Bounded backend probes. A file on disk is not proof of a usable runtime. */
import { spawn } from 'node:child_process'
import { buildDesktopBackendEnv } from './backend-env'
import { windowsShellCommand } from './windows-child-options'
/** Default probe budget. 5s false-negativeed healthy Windows cold starts (#61764). */
const DEFAULT_PROBE_TIMEOUT_MS = 15_000
/**
* Resolve the backend probe timeout (ms).
* Honours HERMES_PROBE_TIMEOUT_MS when it parses as a positive integer.
*/
function resolveProbeTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {
const raw = env.HERMES_PROBE_TIMEOUT_MS
if (raw == null || raw === '') {
return DEFAULT_PROBE_TIMEOUT_MS
}
const n = Number.parseInt(String(raw), 10)
if (!Number.isFinite(n) || n <= 0) {
return DEFAULT_PROBE_TIMEOUT_MS
}
// Clamp absurd values (ms) so a typo can't hang startup forever.
return Math.min(n, 120_000)
}
const PROBE_TIMEOUT_MS = resolveProbeTimeoutMs()
function isTimeoutError(err: unknown): boolean {
if (!err || typeof err !== 'object') {
return false
}
const e = err as { code?: string; killed?: boolean; signal?: string }
if (e.killed === true) {
return true
}
if (e.code === 'ETIMEDOUT') {
return true
}
// Node marks timed-out execFileSync with SIGTERM on some platforms.
if (e.signal === 'SIGTERM') {
return true
}
return false
}
/**
* Run without blocking the event loop; on timeout only, retry once before failing.
* Non-timeout failures (ENOENT, non-zero exit) fail immediately.
*/
async function execProbe(
command: string,
args: string[],
options: {
cwd?: string
env?: NodeJS.ProcessEnv
stdio: 'ignore'
timeout: number
shell?: boolean
windowsHide?: boolean
}
): Promise<void> {
const run = () =>
new Promise<void>((resolve, reject) => {
const child = spawn(command, args, options)
child.once('error', reject)
child.once('close', (code, signal) => {
// A timed-out probe may handle SIGTERM and exit zero; it is still a timeout.
if (code === 0 && !child.killed) {
resolve()
} else {
reject(
Object.assign(new Error(`Runtime probe failed: ${command} (${signal || code})`), {
code,
signal,
killed: child.killed
})
)
}
})
})
try {
await run()
} catch (err) {
if (!isTimeoutError(err)) {
throw err
}
// One cold-cache / AV miss should not force hermes-setup --update (#61764).
await run()
}
}
/** Probe the checkout at cwd with the same dependency activation as launch. */
async function canImportHermesCli(
pythonPath: string,
opts: { env?: NodeJS.ProcessEnv; cwd?: string } = {}
): Promise<boolean> {
if (!pythonPath) {
return false
}
try {
const env: NodeJS.ProcessEnv = { ...process.env, ...opts.env }
// Bootstrap selects the committed generation before any dependency import.
await execProbe(
pythonPath,
['-c', 'import hermes_bootstrap; import hermes_yaml; import dotenv; import hermes_cli.config'],
{
cwd: opts.cwd,
env: { ...env, ...buildDesktopBackendEnv({ currentEnv: env }) },
stdio: 'ignore',
timeout: PROBE_TIMEOUT_MS,
windowsHide: true
}
)
return true
} catch {
return false
}
}
/**
* Return true iff `<hermesCommand> --version` exits 0.
*
* Used to gate the "existing `hermes` on PATH" rung. Without this, a
* stale hermes.cmd shim left behind by an uninstalled pip install (or
* a half-built venv whose `hermes` entry-point points at a deleted
* Python) survives findOnPath() and gets selected as the backend.
*
* We intentionally avoid invoking the command with the dashboard args
* here -- `--version` is the cheapest "is this binary alive" smoke
* test that every hermes_cli entry-point has supported since 0.1.
*
* @param {string} hermesCommand - Resolved absolute path to a hermes
* executable (or an interpreter+script wrapper).
* @param {boolean} [opts.shell] - Whether to run through a shell. For
* .cmd/.bat shims on Windows spawn needs shell:true to find
* the cmd interpreter; mirrors the same flag isCommandScript() drives
* in resolveHermesBackend.
* @returns {boolean}
*/
/**
* An explicit desktop backend command is a deployment contract, not a PATH
* discovery candidate. In particular, the Nix desktop wrapper points this at
* its immutable, matching Hermes package; it must never fall through to the
* mutable install-script bootstrap path if a best-effort probe is slow.
*/
function shouldTrustHermesOverride(hermesOverride?: string) {
return typeof hermesOverride === 'string' && hermesOverride.trim().length > 0
}
async function verifyHermesCli(hermesCommand: string, opts?: { shell?: boolean }) {
if (!hermesCommand) {
return false
}
try {
await execProbe(windowsShellCommand(hermesCommand, Boolean(opts?.shell)), ['--version'], {
stdio: 'ignore',
timeout: PROBE_TIMEOUT_MS,
shell: Boolean(opts?.shell),
windowsHide: true
})
return true
} catch {
return false
}
}
export {
canImportHermesCli,
DEFAULT_PROBE_TIMEOUT_MS,
execProbe,
isTimeoutError,
PROBE_TIMEOUT_MS,
resolveProbeTimeoutMs,
shouldTrustHermesOverride,
verifyHermesCli
}