@elizaos/app-core 2.0.0-beta.3 → 2.0.3-beta.3

package/scripts/run-node-runtime.mjs

@@ -1,4 +1,7 @@
+import { spawnSync } from "node:child_process";
+
 const KNOWN_UNSTABLE_BUN_LINUX = /^1\.3\.9(?:$|[-+].*)/;
+const MIN_NODE_MAJOR = 24;
 
 /**
  * Bun 1.3.9 has known Linux segfault reports in long-running workloads.
@@ -15,16 +18,25 @@ export function isKnownUnstableBunOnLinux({ platform, bunVersion }) {
 /**
  * Runtime selection priority:
  * 1) Explicit ELIZA_RUNTIME override (bun|node)
- * 2) Safety fallback for known unstable Bun/Linux combo
- * 3) Default to bun
+ * 2) Safety fallback for known unstable Bun/Linux combo when Node is available
+ * 3) Default to an available runtime, preferring bun
  */
-export function chooseElizaRuntime({ requestedRuntime, platform, bunVersion }) {
+export function chooseElizaRuntime({
+  requestedRuntime,
+  platform,
+  bunVersion,
+  hasBun,
+  hasNode,
+}) {
   const normalized = requestedRuntime?.trim().toLowerCase();
   if (normalized === "bun" || normalized === "node") {
     return { runtime: normalized, warning: null };
   }
 
-  if (isKnownUnstableBunOnLinux({ platform, bunVersion })) {
+  if (
+    hasNode !== false &&
+    isKnownUnstableBunOnLinux({ platform, bunVersion })
+  ) {
     return {
       runtime: "node",
       warning:
@@ -32,6 +44,10 @@ export function chooseElizaRuntime({ requestedRuntime, platform, bunVersion }) {
     };
   }
 
+  if (hasBun === false && hasNode) {
+    return { runtime: "node", warning: null };
+  }
+
   return { runtime: "bun", warning: null };
 }
 
@@ -39,9 +55,20 @@ export function resolveNodeExecPath({
   currentExecPath,
   platform,
   explicitNodePath,
+  probeNode = probeNodeExecutable,
 }) {
   const explicit = explicitNodePath?.trim();
   if (explicit) {
+    const validation = validateNodeExecutable({
+      candidate: explicit,
+      platform,
+      probeNode,
+    });
+    if (!validation.ok) {
+      throw new Error(
+        `Invalid ELIZA_NODE_PATH=${explicit}: ${validation.reason}. Set ELIZA_NODE_PATH to a standard Node.js ${MIN_NODE_MAJOR}+ executable.`,
+      );
+    }
     return explicit;
   }
 
@@ -52,10 +79,159 @@ export function resolveNodeExecPath({
   const looksLikeBun = /(?:^|[\\/])bun(?:\.exe)?$/.test(normalized);
 
   if (!looksLikeBun && normalized.length > 0) {
-    return currentExecPath;
+    const validation = validateNodeExecutable({
+      candidate: currentExecPath,
+      platform,
+      probeNode,
+    });
+    if (validation.ok) {
+      return currentExecPath;
+    }
+  }
+
+  const nodeCommand = platform === "win32" ? "node.exe" : "node";
+  const validation = validateNodeExecutable({
+    candidate: nodeCommand,
+    platform,
+    probeNode,
+    allowMissingPath: true,
+  });
+  if (validation.ok) {
+    return nodeCommand;
+  }
+
+  throw new Error(
+    `No usable Node.js ${MIN_NODE_MAJOR}+ executable found (${validation.reason}). Install Node.js ${MIN_NODE_MAJOR}+ or set ELIZA_NODE_PATH=/absolute/path/to/node.`,
+  );
+}
+
+function isCodexBundledNode(candidate, platform) {
+  const normalized = (candidate ?? "").replace(/\\/g, "/");
+  return (
+    platform === "darwin" &&
+    normalized.includes("/Applications/Codex.app/Contents/Resources/node")
+  );
+}
+
+export function parseNodeMajor(version) {
+  const major = /^(\d+)(?:\.|$)/.exec(version ?? "")?.[1];
+  return major ? Number.parseInt(major, 10) : null;
+}
+
+export function validateNodeProbeOutput(output) {
+  const text = output?.trim() ?? "";
+  if (text === "bun") {
+    return { ok: false, reason: "resolved to Bun, not Node.js" };
+  }
+  const match = /^node:(.+)$/.exec(text);
+  if (!match) {
+    return { ok: false, reason: "did not report a Node.js runtime" };
+  }
+  const major = parseNodeMajor(match[1]);
+  if (major === null) {
+    return { ok: false, reason: `could not parse Node.js version ${match[1]}` };
+  }
+  if (major < MIN_NODE_MAJOR) {
+    return {
+      ok: false,
+      reason: `Node.js ${match[1]} is too old; Node.js ${MIN_NODE_MAJOR}+ is required`,
+    };
+  }
+  return { ok: true, reason: null };
+}
+
+export function validateNodeExecutable({
+  candidate,
+  platform,
+  probeNode = probeNodeExecutable,
+  allowMissingPath = false,
+}) {
+  if (!candidate?.trim()) {
+    return { ok: false, reason: "path is empty" };
+  }
+  if (isCodexBundledNode(candidate, platform)) {
+    return { ok: false, reason: "Codex-bundled macOS Node is not supported" };
+  }
+  const probe = probeNode(candidate);
+  if (probe.status !== 0) {
+    if (allowMissingPath) {
+      return {
+        ok: false,
+        reason: "node command was not found or failed to run",
+      };
+    }
+    return {
+      ok: false,
+      reason:
+        probe.stderr || probe.error || "executable failed the runtime probe",
+    };
+  }
+  return validateNodeProbeOutput(probe.stdout);
+}
+
+export function probeNodeExecutable(candidate) {
+  try {
+    const result = spawnSync(
+      candidate,
+      [
+        "-e",
+        "process.stdout.write(process.versions.bun ? 'bun' : 'node:' + (process.versions.node || ''))",
+      ],
+      { encoding: "utf8" },
+    );
+    return {
+      status: result.status ?? 1,
+      stdout: result.stdout?.trim() ?? "",
+      stderr: result.stderr?.trim() ?? "",
+      error: result.error?.message,
+    };
+  } catch (error) {
+    return {
+      status: 1,
+      stdout: "",
+      stderr: "",
+      error: error instanceof Error ? error.message : String(error),
+    };
   }
+}
+
+export function resolveNodeExecPathFromCandidates({
+  candidates,
+  platform,
+  explicitNodePath,
+  probeNode = probeNodeExecutable,
+}) {
+  const explicit = explicitNodePath?.trim();
+  if (explicit) {
+    return resolveNodeExecPath({
+      currentExecPath: explicit,
+      platform,
+      explicitNodePath: explicit,
+      probeNode,
+    });
+  }
+
+  let lastReason = "no candidates were provided";
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    const validation = validateNodeExecutable({
+      candidate,
+      platform,
+      probeNode,
+    });
+    if (validation.ok) {
+      return candidate;
+    }
+    lastReason = `${candidate}: ${validation.reason}`;
+  }
+
+  throw new Error(
+    `No usable Node.js ${MIN_NODE_MAJOR}+ executable found (${lastReason}). Install Node.js ${MIN_NODE_MAJOR}+ or set ELIZA_NODE_PATH=/absolute/path/to/node.`,
+  );
+}
 
-  return platform === "win32" ? "node.exe" : "node";
+export function getRequiredNodeMajor() {
+  return MIN_NODE_MAJOR;
 }
 
 export function resolveRuntimeExecPath({
@@ -63,9 +239,10 @@ export function resolveRuntimeExecPath({
   currentExecPath,
   platform,
   explicitNodePath,
+  bunPath,
 }) {
   if (runtime === "bun") {
-    return "bun";
+    return bunPath?.trim() || "bun";
   }
   return resolveNodeExecPath({
     currentExecPath,

package/scripts/run-node-runtime.test.mjs

@@ -0,0 +1,167 @@
+import { describe, expect, test } from "vitest";
+import {
+  chooseElizaRuntime,
+  parseNodeMajor,
+  resolveNodeExecPath,
+  resolveNodeExecPathFromCandidates,
+  validateNodeExecutable,
+  validateNodeProbeOutput,
+} from "./run-node-runtime.mjs";
+
+const probe = (outputs) => (candidate) =>
+  outputs[candidate] ?? {
+    status: 1,
+    stdout: "",
+    stderr: "missing",
+  };
+
+describe("run-node-runtime node validation", () => {
+  test("defaults to Bun when both runtimes are available", () => {
+    expect(
+      chooseElizaRuntime({
+        platform: "darwin",
+        hasBun: true,
+        hasNode: true,
+      }),
+    ).toEqual({ runtime: "bun", warning: null });
+  });
+
+  test("defaults to Node when Bun is unavailable", () => {
+    expect(
+      chooseElizaRuntime({
+        platform: "darwin",
+        hasBun: false,
+        hasNode: true,
+      }),
+    ).toEqual({ runtime: "node", warning: null });
+  });
+
+  test("keeps Bun-only installs on Bun without requiring Node", () => {
+    expect(
+      chooseElizaRuntime({
+        platform: "darwin",
+        hasBun: true,
+        hasNode: false,
+      }),
+    ).toEqual({ runtime: "bun", warning: null });
+  });
+
+  test("honors explicit runtime overrides", () => {
+    expect(
+      chooseElizaRuntime({
+        requestedRuntime: "node",
+        platform: "darwin",
+        hasBun: true,
+        hasNode: true,
+      }),
+    ).toEqual({ runtime: "node", warning: null });
+    expect(
+      chooseElizaRuntime({
+        requestedRuntime: "bun",
+        platform: "darwin",
+        hasBun: true,
+        hasNode: true,
+      }),
+    ).toEqual({ runtime: "bun", warning: null });
+  });
+
+  test("falls back from unstable Bun 1.3.9 on Linux only when Node is available", () => {
+    const withNode = chooseElizaRuntime({
+      platform: "linux",
+      bunVersion: "1.3.9",
+      hasBun: true,
+      hasNode: true,
+    });
+    expect(withNode.runtime).toBe("node");
+    expect(withNode.warning).toContain("Bun 1.3.9");
+
+    expect(
+      chooseElizaRuntime({
+        platform: "linux",
+        bunVersion: "1.3.9",
+        hasBun: true,
+        hasNode: false,
+      }),
+    ).toEqual({ runtime: "bun", warning: null });
+  });
+
+  test("parses Node major versions", () => {
+    expect(parseNodeMajor("24.1.0")).toBe(24);
+    expect(parseNodeMajor("25")).toBe(25);
+    expect(parseNodeMajor("v24.1.0")).toBeNull();
+  });
+
+  test("rejects Bun probe output", () => {
+    expect(validateNodeProbeOutput("bun")).toEqual({
+      ok: false,
+      reason: "resolved to Bun, not Node.js",
+    });
+  });
+
+  test("rejects Node versions below the repo requirement", () => {
+    const result = validateNodeProbeOutput("node:23.9.0");
+    expect(result.ok).toBe(false);
+    expect(result.reason).toContain("Node.js 24+ is required");
+  });
+
+  test("accepts Node 24 and newer", () => {
+    expect(validateNodeProbeOutput("node:24.0.0")).toEqual({
+      ok: true,
+      reason: null,
+    });
+    expect(validateNodeProbeOutput("node:25.1.0")).toEqual({
+      ok: true,
+      reason: null,
+    });
+  });
+
+  test("rejects Codex-bundled macOS Node", () => {
+    const result = validateNodeExecutable({
+      candidate: "/Applications/Codex.app/Contents/Resources/node",
+      platform: "darwin",
+      probeNode: probe({}),
+    });
+    expect(result.ok).toBe(false);
+    expect(result.reason).toContain("Codex-bundled");
+  });
+
+  test("throws for an invalid explicit ELIZA_NODE_PATH", () => {
+    expect(() =>
+      resolveNodeExecPath({
+        currentExecPath: "/valid/node",
+        explicitNodePath: "/bad/bun",
+        platform: "darwin",
+        probeNode: probe({
+          "/bad/bun": { status: 0, stdout: "bun", stderr: "" },
+          "/valid/node": { status: 0, stdout: "node:24.0.0", stderr: "" },
+        }),
+      }),
+    ).toThrow(/Invalid ELIZA_NODE_PATH=\/bad\/bun/);
+  });
+
+  test("skips invalid candidates and returns a valid Node", () => {
+    expect(
+      resolveNodeExecPathFromCandidates({
+        candidates: ["/old/node", "/bun", "/good/node"],
+        platform: "linux",
+        probeNode: probe({
+          "/old/node": { status: 0, stdout: "node:22.12.0", stderr: "" },
+          "/bun": { status: 0, stdout: "bun", stderr: "" },
+          "/good/node": { status: 0, stdout: "node:24.2.0", stderr: "" },
+        }),
+      }),
+    ).toBe("/good/node");
+  });
+
+  test("falls back from a Bun current executable to node command when valid", () => {
+    expect(
+      resolveNodeExecPath({
+        currentExecPath: "/usr/local/bin/bun",
+        platform: "linux",
+        probeNode: probe({
+          node: { status: 0, stdout: "node:24.0.0", stderr: "" },
+        }),
+      }),
+    ).toBe("node");
+  });
+});

package/scripts/run-node-tsx.mjs

@@ -1,37 +1,28 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import fs from "node:fs";
+import path from "node:path";
 import process from "node:process";
-
-function isRealNodeExecutable(candidate) {
-  if (!candidate || !fs.existsSync(candidate)) {
-    return false;
-  }
-  const stat = fs.statSync(candidate);
-  if (!stat.isFile()) {
-    return false;
-  }
-  const normalized = candidate.replace(/\\/g, "/");
-  return !/\/bun-node-[^/]+\/node$/.test(normalized);
-}
+import { resolveNodeExecPathFromCandidates } from "./run-node-runtime.mjs";
 
 function resolveNodeCmd() {
-  if (isRealNodeExecutable(process.env.npm_node_execpath)) {
-    return process.env.npm_node_execpath;
-  }
-  for (const candidate of [
-    "/opt/homebrew/bin/node",
-    "/usr/local/bin/node",
-    "/usr/bin/node",
-  ]) {
-    if (isRealNodeExecutable(candidate)) {
-      return candidate;
-    }
-  }
-  if (isRealNodeExecutable(process.execPath)) {
-    return process.execPath;
-  }
-  return "node";
+  const pathCandidates = (process.env.PATH ?? "")
+    .split(path.delimiter)
+    .filter(Boolean)
+    .map((dir) =>
+      path.join(dir, process.platform === "win32" ? "node.exe" : "node"),
+    );
+  return resolveNodeExecPathFromCandidates({
+    candidates: [
+      process.env.npm_node_execpath,
+      process.execPath,
+      ...pathCandidates,
+      "/opt/homebrew/bin/node",
+      "/usr/local/bin/node",
+      "/usr/bin/node",
+    ],
+    explicitNodePath: process.env.ELIZA_NODE_PATH,
+    platform: process.platform,
+  });
 }
 
 const args = process.argv.slice(2);
@@ -40,12 +31,62 @@ if (args.length === 0) {
   process.exit(1);
 }
 
-const child = spawn(resolveNodeCmd(), ["--import", "tsx", ...args], {
+function withWorkspaceNodePath(env) {
+  const rootModules = path.join(process.cwd(), "node_modules");
+  const bunModules = path.join(rootModules, ".bun", "node_modules");
+  const modulePaths = [rootModules, bunModules];
+  return {
+    ...env,
+    NODE_PATH: env.NODE_PATH
+      ? `${modulePaths.join(path.delimiter)}${path.delimiter}${env.NODE_PATH}`
+      : modulePaths.join(path.delimiter),
+    PWD: process.cwd(),
+  };
+}
+
+const nodeArgs = [
+  // WHY: this runner executes TypeScript workspace scripts before every
+  // workspace package has a fresh dist build. Prefer source exports for
+  // packages that declare the eliza-source condition, matching Vitest's
+  // source-mode aliases and avoiding stale/missing dist imports in CI probes.
+  "--conditions=eliza-source",
+  "--import",
+  "tsx",
+  ...args,
+];
+
+const child = spawn(resolveNodeCmd(), nodeArgs, {
   cwd: process.cwd(),
-  env: { ...process.env, PWD: process.cwd() },
+  env: withWorkspaceNodePath(process.env),
   stdio: "inherit",
 });
 
+const SIGNAL_EXIT_CODE = {
+  SIGHUP: 129,
+  SIGINT: 130,
+  SIGTERM: 143,
+};
+
+let forwardedSignal = null;
+let forceKillTimer = null;
+
+function forwardSignal(signal) {
+  forwardedSignal = signal;
+  if (child.exitCode == null && child.signalCode == null) {
+    child.kill(signal);
+    forceKillTimer = setTimeout(() => {
+      if (child.exitCode == null && child.signalCode == null) {
+        child.kill("SIGKILL");
+      }
+    }, 10_000);
+    forceKillTimer.unref?.();
+  }
+}
+
+for (const signal of Object.keys(SIGNAL_EXIT_CODE)) {
+  process.once(signal, () => forwardSignal(signal));
+}
+
 child.on("error", (error) => {
   console.error(
     `[run-node-tsx] Failed to spawn Node: ${error instanceof Error ? error.message : String(error)}`,
@@ -54,9 +95,15 @@ child.on("error", (error) => {
 });
 
 child.on("exit", (code, signal) => {
+  if (forceKillTimer) {
+    clearTimeout(forceKillTimer);
+    forceKillTimer = null;
+  }
   if (signal) {
-    process.kill(process.pid, signal);
-    return;
+    process.exit(SIGNAL_EXIT_CODE[signal] ?? 1);
+  }
+  if (forwardedSignal) {
+    process.exit(SIGNAL_EXIT_CODE[forwardedSignal] ?? 1);
   }
   process.exit(code ?? 1);
 });

package/scripts/run-node.mjs

@@ -158,22 +158,62 @@ const MAX_RESTARTS_IN_WINDOW = 5;
 const RESTART_WINDOW_MS = 60_000;
 const restartTimestamps = [];
 
+const commandExists = (command) => {
+  const pathEnv = process.env.PATH ?? "";
+  if (!pathEnv) return false;
+  const isWindows = process.platform === "win32";
+  const extensions = isWindows
+    ? (process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean)
+    : [""];
+  for (const dir of pathEnv.split(path.delimiter).filter(Boolean)) {
+    for (const ext of extensions) {
+      const candidate = path.join(
+        dir,
+        isWindows && !command.toLowerCase().endsWith(ext.toLowerCase())
+          ? `${command}${ext}`
+          : command,
+      );
+      if (fs.existsSync(candidate)) return true;
+    }
+  }
+  return false;
+};
+
 const runNode = () => {
+  const hasBun = commandExists("bun");
+  const hasNode = commandExists("node");
   const { runtime, warning } = chooseElizaRuntime({
     requestedRuntime: process.env.ELIZA_RUNTIME,
     platform: process.platform,
     bunVersion: process.versions?.bun,
+    hasBun,
+    hasNode,
   });
   if (warning) {
     logRunner(`${warning} Set ELIZA_RUNTIME=bun to force Bun runtime.`);
   }
+  if (runtime === "bun" && !hasBun) {
+    logRunner("Bun runtime was selected, but bun was not found in PATH.");
+    process.exit(1);
+  }
+  if (runtime === "node" && !hasNode) {
+    logRunner("Node.js runtime was selected, but node was not found in PATH.");
+    process.exit(1);
+  }
   const execPath = resolveRuntimeExecPath({
     runtime,
     currentExecPath: process.execPath,
     platform: process.platform,
     explicitNodePath: process.env.ELIZA_NODE_PATH,
   });
-  const nodeProcess = spawn(execPath, ["eliza.mjs", ...args], {
+  // Forks rename `eliza.mjs` to their own entry filename.
+  // Letting them override the spawned filename via `ELIZA_ENTRY_FILE` avoids
+  // every fork having to ship a shim at the old name. Read from `env` (the
+  // local snapshot built at module load) for consistency with what the child
+  // process actually receives — `.env.worktree` overrides applied above are
+  // visible here too.
+  const entryFile = env.ELIZA_ENTRY_FILE?.trim() || "eliza.mjs";
+  const nodeProcess = spawn(execPath, [entryFile, ...args], {
     cwd,
     env,
     stdio: "inherit",