Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Hermetic async CLI spawn wrappers for subprocess tests against the real
* `src/cli.ts` entrypoint. Consolidates the hand-rolled `run()` helpers in
* ambient-recall-cli.test.ts / cli-dispatch-thin-client.test.ts.
*
* Constraints:
* - Async Bun.spawn (NOT spawnSync/execFileSync) — the test event loop
* stays responsive; see init-mcp-only.test.ts for the rationale.
* - Hermetic env: DATABASE_URL / GBRAIN_DATABASE_URL /
* GBRAIN_REMOTE_CLIENT_SECRET are ALWAYS stripped (a dev shell's ambient
* Postgres URL or remote secret must never reach a test child), the real
* CLI is spawned with `--no-env-file` so a repo-root .env cannot
* re-inject what the strip removed, and GBRAIN_SKIP_STARTUP_HOOKS=1 so no
* detached check-update child leaks past the test (override via opts.env
* if a test needs the hooks). Provider keys (OPENAI_/ANTHROPIC_API_KEY)
* are NOT stripped here — the bunfig provider-keys preload already scrubs
* them from the test process, so children inherit the scrubbed set;
* strip per-call via opts.env when a test re-injects them.
* - `opts.home` sets BOTH HOME and GBRAIN_HOME so the child cannot read or
* clobber the operator's real ~/.gbrain.
* - The DIRECT child is reaped: timeout sends SIGTERM, escalates to SIGKILL
* +2s later, and the result always awaits `exited`. Grandchildren the CLI
* forks are NOT swept — a caller whose CLI spawns heavy subprocesses
* should assert on their completion, not rely on the timeout kill.
*/
import { existsSync } from 'node:fs';
import { dirname, join } from 'node:path';
export interface CliResult {
stdout: string;
stderr: string;
exitCode: number;
}
export interface CliSpawnOpts {
/** Merged over the hermetic base env; `undefined` value deletes the key. */
env?: Record<string, string | undefined>;
/** Child working directory. Default: repo root. */
cwd?: string;
/** Sets HOME and GBRAIN_HOME in the child. */
home?: string;
/** SIGTERM the child after this long (SIGKILL +2s later). Default 60000. */
timeoutMs?: number;
}
/**
* Locate the repo root by walking up until `src/cli.ts` exists — never
* hardcode a `../..` depth (survives this helper moving directories).
*/
function findRepoRoot(from: string): string {
let dir = from;
for (;;) {
if (existsSync(join(dir, 'src', 'cli.ts'))) return dir;
const parent = dirname(dir);
if (parent === dir) {
throw new Error(`cli-spawn: no src/cli.ts found in any ancestor of ${from}`);
}
dir = parent;
}
}
const REPO_ROOT = findRepoRoot(import.meta.dir);
const CLI_PATH = join(REPO_ROOT, 'src', 'cli.ts');
/**
* Test seam: replaces the `[process.execPath, CLI_PATH]` command prefix so
* cli-spawn's own unit tests can exercise pool/timeout/env behavior against a
* tiny `bun -e` fixture instead of booting the real CLI (~1.5GB PGLite).
* Pass null to restore the real CLI. Reset in afterEach — module-global.
*/
let spawnTargetOverride: readonly string[] | null = null;
export function _setSpawnTarget(cmd: readonly string[] | null): void {
spawnTargetOverride = cmd;
}
function buildEnv(opts?: CliSpawnOpts): Record<string, string> {
const env: Record<string, string> = {};
for (const [k, v] of Object.entries(process.env)) {
if (v !== undefined) env[k] = v;
}
delete env.DATABASE_URL;
delete env.GBRAIN_DATABASE_URL;
delete env.GBRAIN_REMOTE_CLIENT_SECRET;
env.GBRAIN_SKIP_STARTUP_HOOKS = '1';
if (opts?.home !== undefined) {
env.HOME = opts.home;
env.GBRAIN_HOME = opts.home;
}
if (opts?.env) {
for (const [k, v] of Object.entries(opts.env)) {
if (v === undefined) delete env[k];
else env[k] = v;
}
}
return env;
}
// Wrapper exists so `Child` is the exact inferred Subprocess specialization
// (stdout/stderr typed as ReadableStream) without naming Bun generics.
function spawnChild(cmd: string[], env: Record<string, string>, cwd: string) {
return Bun.spawn({ cmd, env, cwd, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' });
}
type Child = ReturnType<typeof spawnChild>;
async function spawnOnce(
args: string[],
opts: CliSpawnOpts | undefined,
onSpawn?: (proc: Child) => void,
onSettle?: (proc: Child) => void,
): Promise<CliResult> {
// --no-env-file: bun auto-loads a repo-root .env into the child, which
// would re-inject the exact vars buildEnv() strips (a dev .env defining
// GBRAIN_DATABASE_URL un-hermeticizes every consumer). The wrapper this
// helper replaced passed the flag for the same reason.
const prefix = spawnTargetOverride ?? [process.execPath, '--no-env-file', CLI_PATH];
const proc = spawnChild([...prefix, ...args], buildEnv(opts), opts?.cwd ?? REPO_ROOT);
onSpawn?.(proc);
const timeoutMs = opts?.timeoutMs ?? 60_000;
const term = setTimeout(() => {
try { proc.kill(); } catch { /* already exited */ }
}, timeoutMs);
// A child that ignores SIGTERM would hang the suite; escalate.
const hardKill = setTimeout(() => {
try { proc.kill(9); } catch { /* already exited */ }
}, timeoutMs + 2_000);
try {
const [stdout, stderr, exitCode] = await Promise.all([
new Response(proc.stdout).text(),
new Response(proc.stderr).text(),
proc.exited,
]);
// Bun types `exited` as Promise<number>, but a signal-killed child's
// code is runtime-defined; coerce a hypothetical null to -1 so
// CliResult.exitCode is always a number (and never 0 on timeout).
return { stdout, stderr, exitCode: exitCode ?? -1 };
} catch (err) {
// A rejected pipe read exits Promise.all BEFORE proc.exited — without
// this, the finally below would clear both kill timers on a still-running
// child and break the reap guarantee.
try { proc.kill(9); } catch { /* already exited */ }
await proc.exited.catch(() => {});
throw err;
} finally {
clearTimeout(term);
clearTimeout(hardKill);
onSettle?.(proc);
}
}
/**
* Spawn `bun src/cli.ts <args>` once. Never throws on nonzero exit — the
* exit code is data (assert on it). Throws only when the spawn itself fails
* (missing executable) — see runCliBatch for the reap guarantee there.
*/
export async function runCli(args: string[], opts?: CliSpawnOpts): Promise<CliResult> {
return spawnOnce(args, opts);
}
/**
* Run many CLI invocations through a bounded-concurrency pool, results in
* INPUT order regardless of completion order.
*
* DEFAULT WIDTH 2 — do not raise casually. The cap is per-invocation: the
* parallel runner puts 4 shards on one machine, so 4 shards x width
* multiplies CLI children machine-wide, and each child can boot a ~1.5GB
* PGLite. Keep 2 unless the file is alone in a lane.
*
* If any spawn throws, all still-running children are killed and awaited
* (reaped — no orphans) before the error propagates.
*/
export async function runCliBatch(
argvs: string[][],
opts?: CliSpawnOpts & { width?: number },
): Promise<CliResult[]> {
const width = Math.max(1, Math.floor(opts?.width ?? 2));
const results: CliResult[] = new Array(argvs.length);
const live = new Set<Child>();
let aborted = false;
let next = 0;
async function worker(): Promise<void> {
for (;;) {
if (aborted) return;
const i = next;
next += 1;
if (i >= argvs.length) return;
results[i] = await spawnOnce(
argvs[i],
opts,
p => live.add(p),
p => live.delete(p),
);
}
}
const workers = Array.from({ length: Math.min(width, argvs.length) }, () => worker());
try {
await Promise.all(workers);
} catch (err) {
aborted = true;
for (const p of live) {
try { p.kill(); } catch { /* already exited */ }
}
// Wait for every worker to settle (a sibling may have spawned between
// the sweep above and its abort check), then sweep + reap once more.
await Promise.allSettled(workers);
for (const p of live) {
try { p.kill(); } catch { /* already exited */ }
}
await Promise.allSettled([...live].map(p => p.exited));
throw err;
}
return results;
}
// Keyed on (argv, home) ONLY — env/cwd/timeout differences do NOT miss.
const memo = new Map<string, Promise<CliResult>>();
/**
* Memoized runCli for PURE READ-ONLY invocations (`--help`, `--tools-json`,
* `--version`) that many tests repeat verbatim. A hit returns the identical
* CliResult object without respawning. Never use for anything that touches
* the brain or depends on opts.env — the key is argv + home only. Failed
* spawns are evicted so an error isn't cached.
*/
export function runCliMemo(args: string[], opts?: CliSpawnOpts): Promise<CliResult> {
if (opts?.env !== undefined || opts?.cwd !== undefined) {
// The memo key is argv+home+timeout ONLY — an env/cwd-varying call served
// from cache would silently return a result produced under different inputs.
throw new Error('runCliMemo: opts.env/opts.cwd are not part of the memo key — use runCli');
}
const key = JSON.stringify([args, opts?.home ?? null, opts?.timeoutMs ?? null]);
const hit = memo.get(key);
if (hit) return hit;
// Freeze the settled result: hits share ONE object across test files in the
// same shard process — a caller mutating it would poison later consumers.
// Nonzero exits (including timeout kills, exitCode -1/143) are EVICTED after
// being returned to the caller that triggered them — one overloaded-machine
// timeout must not poison every later identical assertion in the shard.
const p = runCli(args, opts).then(r => {
if (r.exitCode !== 0) memo.delete(key);
return Object.freeze(r) as CliResult;
});
memo.set(key, p);
p.catch(() => memo.delete(key));
return p;
}
export function clearCliMemo(): void {
memo.clear();
}