@elizaos/app-core 2.0.0-alpha.85 → 2.0.0-beta.2

package/scripts/kernel-patches/vulkan-dispatch-patches/01-vulkan-shaders-gen.patch

@@ -0,0 +1,41 @@
+# MILADY-VK-DISPATCH-PATCH-V1
+#
+# Patch target : ggml/src/ggml-vulkan/vulkan-shaders/vulkan-shaders-gen.cpp
+# Goal         : register the 8 milady standalone .comp files in
+#                process_shaders() so their SPIR-V blobs are emitted into
+#                ggml-vulkan-shaders.hpp as `<name>_data[]` + `<name>_len`.
+#
+# This is an anchor-driven patch (parsed by kernel-patches/vulkan-kernels.mjs).
+# Format:
+#   ANCHOR  <line>     — exact substring; injection happens immediately BEFORE
+#                        the matched line.
+#   SENTINEL <token>   — if this token already exists anywhere in the target
+#                        file, the patch is treated as already applied
+#                        (idempotent re-runs are no-ops).
+#   ---INJECT-BEGIN---
+#   <text to insert verbatim, preserving leading whitespace>
+#   ---INJECT-END---
+#
+# The anchor below is the trailing `for (auto &c : compiles)` wait loop at the
+# bottom of process_shaders() — present in upstream and in v0.4.0-milady fork.
+
+ANCHOR    for (auto &c : compiles) {
+SENTINEL  MILADY-VK-DISPATCH-PATCH-V1
+---INJECT-BEGIN---
+    // MILADY-VK-DISPATCH-PATCH-V1 BEGIN — register milady turbo / qjl / polar
+    // standalone shaders. Each entry causes vulkan-shaders-gen to compile the
+    // matching .comp via glslc (staged into vulkan-shaders/ by
+    // kernel-patches/vulkan-kernels.mjs) and emit `<name>_data[]` + `<name>_len`
+    // symbols into ggml-vulkan-shaders.hpp. The shader sources are
+    // self-contained TUs — no defines are required.
+    string_to_spv("milady_turbo3",         "turbo3.comp",         {});
+    string_to_spv("milady_turbo4",         "turbo4.comp",         {});
+    string_to_spv("milady_turbo3_tcq",     "turbo3_tcq.comp",     {});
+    string_to_spv("milady_qjl",            "qjl.comp",            {});
+    string_to_spv("milady_qjl_get_rows",   "qjl_get_rows.comp",   {});
+    string_to_spv("milady_qjl_mul_mv",     "qjl_mul_mv.comp",     {});
+    string_to_spv("milady_polar",          "polar.comp",          {});
+    string_to_spv("milady_polar_get_rows", "polar_get_rows.comp", {});
+    // MILADY-VK-DISPATCH-PATCH-V1 END
+
+---INJECT-END---

package/scripts/kernel-patches/vulkan-dispatch-patches/02-ggml-vulkan-pipelines.patch

@@ -0,0 +1,86 @@
+# MILADY-VK-DISPATCH-PATCH-V1
+#
+# Patch target : ggml/src/ggml-vulkan/ggml-vulkan.cpp
+# Goal         : declare + create 8 pipelines for the milady standalones so
+#                that their SPIR-V blobs are referenced at link time and the
+#                resulting libggml-vulkan.so contains the new pipeline names.
+#
+# Two hunks (parsed sequentially by kernel-patches/vulkan-kernels.mjs).
+# Each hunk carries its own ANCHOR / SENTINEL / INJECT block. SENTINEL is the
+# same token across both hunks so a partially-applied state still re-checks.
+#
+# OUT OF SCOPE for this patch (deliberate, mirrors metal-kernels.mjs §41):
+#   * Wiring op-level dispatch (ggml_vk_get_dequantize_mul_mat_vec / GGML_OP_*
+#     case branches) for GGML_TYPE_TBQ3_0 / TBQ4_0 / QJL1_256 / Q4_POLAR /
+#     TBQ3_TCQ. The 8 standalones use bespoke push-constant layouts and bind
+#     sets that are NOT compatible with the existing vk_op_binary_push_constants
+#     / vk_mat_vec_push_constants paths. A separate follow-up patch is
+#     required to introduce a milady-native dispatch entrypoint for
+#     GGML_OP_ATTN_SCORE_QJL (which already exists in ggml.h:563 but has no
+#     Vulkan dispatch — only the CPU reference). Until then the kernels live
+#     as live, named pipelines inside libggml-vulkan.so but are not yet
+#     selected by the runtime — `nm libggml-vulkan.so | grep milady_` passes,
+#     end-to-end attention dispatch does not.
+
+# -----------------------------------------------------------------------------
+# Hunk 1 — extend vk_device_struct with 8 pipeline slots.
+# Anchor: just before the closing brace of vk_device_struct. The closing brace
+# is the first `};` after the `pipeline_topk_moe` member at the end of the
+# struct. We anchor on a stable mid-struct line and insert a block.
+# -----------------------------------------------------------------------------
+
+ANCHOR    vk_pipeline pipeline_get_rows_f32[GGML_TYPE_COUNT];
+SENTINEL  MILADY-VK-DISPATCH-PATCH-V1
+---INJECT-BEGIN---
+    // MILADY-VK-DISPATCH-PATCH-V1 BEGIN — milady turbo / qjl / polar pipelines
+    // Pre-allocated pipeline slots for the 8 milady standalone shaders. These
+    // fields keep the pipelines reachable from the device struct so the
+    // shader symbols are referenced at link time. Op-level dispatch wiring is
+    // deferred (see kernel-patches/vulkan-dispatch-patches/02-ggml-vulkan-pipelines.patch
+    // header comment for scope).
+    vk_pipeline pipeline_milady_turbo3;
+    vk_pipeline pipeline_milady_turbo4;
+    vk_pipeline pipeline_milady_turbo3_tcq;
+    vk_pipeline pipeline_milady_qjl;
+    vk_pipeline pipeline_milady_qjl_get_rows;
+    vk_pipeline pipeline_milady_qjl_mul_mv;
+    vk_pipeline pipeline_milady_polar;
+    vk_pipeline pipeline_milady_polar_get_rows;
+    // MILADY-VK-DISPATCH-PATCH-V1 END
+
+---INJECT-END---
+
+# -----------------------------------------------------------------------------
+# Hunk 2 — pipeline-creation calls inside ggml_vk_load_shaders().
+# Anchor: the trailing `for (auto &c : compiles) { c.wait(); }` loop at the
+# bottom of ggml_vk_load_shaders(). Same pattern as upstream uses for every
+# other pipeline.
+#
+# Push-constant sizes + bind counts come directly from the shader sources
+# under packages/inference/vulkan/. wg_denoms = {1,1,1} (no grid rounding —
+# the actual local_size_x = 32 is in the shader's layout qualifier).
+# -----------------------------------------------------------------------------
+
+ANCHOR    for (auto &c : compiles) {
+SENTINEL  MILADY-VK-DISPATCH-PATCH-V1
+---INJECT-BEGIN---
+    // MILADY-VK-DISPATCH-PATCH-V1 BEGIN — create milady turbo / qjl / polar pipelines
+    // Push-constant sizes / bind counts are taken from the matching .comp files.
+    //   turbo3 / turbo4    : 3 storage buffers (q, k_blocks, scores)            + 5*u32 push
+    //   turbo3_tcq         : 4 storage buffers (q, k_blocks, scores, codebook)  + 5*u32 push
+    //   qjl (score)        : 3 storage buffers (q_sketch, packed_k, scores)     + 4*u32 push
+    //   qjl_get_rows       : 3 storage buffers (k_packed, prj, out)             + 2*u32 push
+    //   qjl_mul_mv         : 3 storage buffers (k_blocks, q_sketch, y)          + 2*u32 push
+    //   polar              : 3 storage buffers (k_blocks, q, y)                 + 3*u32 push
+    //   polar_get_rows     : 2 storage buffers (k_block, out)                   + 2*u32 push
+    ggml_vk_create_pipeline(device, device->pipeline_milady_turbo3,         "milady_turbo3",         milady_turbo3_len,         milady_turbo3_data,         "main", 3, 5 * sizeof(uint32_t), {1, 1, 1}, {}, 1);
+    ggml_vk_create_pipeline(device, device->pipeline_milady_turbo4,         "milady_turbo4",         milady_turbo4_len,         milady_turbo4_data,         "main", 3, 5 * sizeof(uint32_t), {1, 1, 1}, {}, 1);
+    ggml_vk_create_pipeline(device, device->pipeline_milady_turbo3_tcq,     "milady_turbo3_tcq",     milady_turbo3_tcq_len,     milady_turbo3_tcq_data,     "main", 4, 5 * sizeof(uint32_t), {1, 1, 1}, {}, 1);
+    ggml_vk_create_pipeline(device, device->pipeline_milady_qjl,            "milady_qjl",            milady_qjl_len,            milady_qjl_data,            "main", 3, 4 * sizeof(uint32_t), {1, 1, 1}, {}, 1);
+    ggml_vk_create_pipeline(device, device->pipeline_milady_qjl_get_rows,   "milady_qjl_get_rows",   milady_qjl_get_rows_len,   milady_qjl_get_rows_data,   "main", 3, 2 * sizeof(uint32_t), {1, 1, 1}, {}, 1);
+    ggml_vk_create_pipeline(device, device->pipeline_milady_qjl_mul_mv,     "milady_qjl_mul_mv",     milady_qjl_mul_mv_len,     milady_qjl_mul_mv_data,     "main", 3, 2 * sizeof(uint32_t), {1, 1, 1}, {}, 1);
+    ggml_vk_create_pipeline(device, device->pipeline_milady_polar,          "milady_polar",          milady_polar_len,          milady_polar_data,          "main", 3, 3 * sizeof(uint32_t), {1, 1, 1}, {}, 1);
+    ggml_vk_create_pipeline(device, device->pipeline_milady_polar_get_rows, "milady_polar_get_rows", milady_polar_get_rows_len, milady_polar_get_rows_data, "main", 2, 2 * sizeof(uint32_t), {1, 1, 1}, {}, 1);
+    // MILADY-VK-DISPATCH-PATCH-V1 END
+
+---INJECT-END---

package/scripts/kernel-patches/vulkan-kernels.mjs

@@ -0,0 +1,281 @@
+// Vulkan kernel-shipment + dispatch wiring for the v0.4.0-milady fork.
+//
+// What this module does:
+//
+//   1. Copies the eight verified standalone .comp shaders from
+//      packages/inference/vulkan/ into the fork at
+//      ggml/src/ggml-vulkan/vulkan-shaders/<name>.comp. The fork's CMakeLists
+//      uses `file(GLOB CONFIGURE_DEPENDS ${input_dir}/*.comp)` to discover
+//      shader sources, so dropping files into vulkan-shaders/ is sufficient
+//      for glslc to compile them. Registration with vulkan-shaders-gen (so
+//      the resulting SPV bytes appear as `<name>_data[]`/`<name>_len` in
+//      ggml-vulkan-shaders.hpp) is handled by the patch in
+//      vulkan-dispatch-patches/01-vulkan-shaders-gen.patch.
+//
+//   2. Applies the two unified-anchor patches under
+//      vulkan-dispatch-patches/:
+//        - 01-vulkan-shaders-gen.patch — adds 8 string_to_spv() registrations
+//          at the bottom of process_shaders().
+//        - 02-ggml-vulkan-pipelines.patch — extends vk_device_struct with 8
+//          pipeline slots and adds 8 ggml_vk_create_pipeline() calls at the
+//          bottom of ggml_vk_load_shaders(). End result: each milady SPV blob
+//          is referenced at link time and `nm libggml-vulkan.so | grep
+//          milady_` shows the new symbols.
+//
+//      Patches are idempotent: each carries a `MILADY-VK-DISPATCH-PATCH-V1`
+//      sentinel; if the sentinel is already present in the target file, the
+//      hunk is skipped (re-running the build is safe).
+//
+// Out of scope (deliberate, mirrors metal-kernels.mjs's same staged approach):
+//
+//   * Op-level dispatch wiring. The 8 standalones use bespoke push-constant
+//     layouts and bind sets that do NOT plug into the existing
+//     vk_op_binary_push_constants / vk_mat_vec_push_constants paths. The
+//     follow-up patch needs to introduce a milady-native dispatch entrypoint
+//     for GGML_OP_ATTN_SCORE_QJL (already declared in ggml.h:563 as a
+//     CPU-only op) and add per-op routing for QJL/Polar K-cache score and
+//     mul_mv. Until that lands, the kernels live as live, named pipelines
+//     inside libggml-vulkan.so but are NOT yet selected at runtime — symbol
+//     audit passes, end-to-end attention dispatch does not.
+//
+//   * Type-aware case branches in ggml_vk_get_dequantize_mul_mat_vec() etc.
+//     Same reason as above: the existing dequant/mul_mat_vec paths assume a
+//     uniform bind-set that the milady kernels intentionally do not match.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const STANDALONE_VULKAN_DIR = path.resolve(
+  __dirname,
+  "..",
+  "..",
+  "..",
+  "inference",
+  "vulkan",
+);
+
+const PATCHES_DIR = path.resolve(__dirname, "vulkan-dispatch-patches");
+
+export const VULKAN_KERNEL_FILES = [
+  "turbo3.comp",
+  "turbo4.comp",
+  "turbo3_tcq.comp",
+  "qjl.comp",
+  "qjl_get_rows.comp",
+  "qjl_mul_mv.comp",
+  "polar.comp",
+  "polar_get_rows.comp",
+];
+
+const SHADER_SENTINEL = "// MILADY-VK-DISPATCH-PATCH-V1";
+const PATCH_SENTINEL = "MILADY-VK-DISPATCH-PATCH-V1";
+
+const PATCH_TARGETS = [
+  {
+    file: "01-vulkan-shaders-gen.patch",
+    target: path.posix.join(
+      "ggml",
+      "src",
+      "ggml-vulkan",
+      "vulkan-shaders",
+      "vulkan-shaders-gen.cpp",
+    ),
+  },
+  {
+    file: "02-ggml-vulkan-pipelines.patch",
+    target: path.posix.join(
+      "ggml",
+      "src",
+      "ggml-vulkan",
+      "ggml-vulkan.cpp",
+    ),
+  },
+];
+
+function assertStandalonesPresent() {
+  const missing = [];
+  for (const name of VULKAN_KERNEL_FILES) {
+    const src = path.join(STANDALONE_VULKAN_DIR, name);
+    if (!fs.existsSync(src)) {
+      missing.push(src);
+      continue;
+    }
+    const stat = fs.statSync(src);
+    if (!stat.isFile() || stat.size === 0) {
+      missing.push(`${src} (not a file or empty)`);
+    }
+  }
+  if (missing.length > 0) {
+    throw new Error(
+      `[vulkan-kernels] missing/invalid standalone shader sources:\n  ${missing.join("\n  ")}`,
+    );
+  }
+}
+
+function copyStandalonesIntoFork(cacheDir, { dryRun }) {
+  // vulkan-shaders/ is the directory the upstream CMakeLists uses for
+  // file(GLOB CONFIGURE_DEPENDS *.comp) — dropping our 8 files there causes
+  // glslc to compile them automatically as part of the existing per-shader
+  // add_custom_command pipeline. The string_to_spv() registration patch
+  // (01-vulkan-shaders-gen.patch) wires the resulting .spv bytes into
+  // ggml-vulkan-shaders.hpp.
+  const targetDir = path.join(
+    cacheDir,
+    "ggml",
+    "src",
+    "ggml-vulkan",
+    "vulkan-shaders",
+  );
+  if (dryRun) {
+    console.log(`[vulkan-kernels] (dry-run) ensure dir ${targetDir}`);
+  } else if (!fs.existsSync(targetDir)) {
+    throw new Error(
+      `[vulkan-kernels] expected vulkan-shaders/ to exist in fork: ${targetDir}`,
+    );
+  }
+  const copied = [];
+  for (const name of VULKAN_KERNEL_FILES) {
+    const src = path.join(STANDALONE_VULKAN_DIR, name);
+    const dst = path.join(targetDir, name);
+    if (dryRun) {
+      console.log(`[vulkan-kernels] (dry-run) cp ${src} -> ${dst}`);
+    } else {
+      const text = fs.readFileSync(src, "utf8");
+      // Mark the staged copy with the same sentinel as the patches so a
+      // human inspecting the fork tree can see the file came from us.
+      const stamped =
+        `${SHADER_SENTINEL} — staged from packages/inference/vulkan/${name} by\n` +
+        `// build-llama-cpp-dflash.mjs. Frozen — do not edit in fork.\n` +
+        text;
+      fs.writeFileSync(dst, stamped, "utf8");
+    }
+    copied.push(name);
+  }
+  return copied;
+}
+
+// Parse one anchor-driven patch file. Returns an array of hunks; each hunk
+// has { anchor, sentinel, inject } strings.
+function parsePatchFile(filePath) {
+  const raw = fs.readFileSync(filePath, "utf8");
+  const lines = raw.split("\n");
+  const hunks = [];
+  let cur = null;
+  let inInject = false;
+  let injectLines = [];
+  for (const line of lines) {
+    if (line.startsWith("ANCHOR")) {
+      cur = { anchor: line.replace(/^ANCHOR\s+/, ""), sentinel: null, inject: null };
+    } else if (line.startsWith("SENTINEL")) {
+      if (!cur) throw new Error(`[vulkan-kernels] SENTINEL before ANCHOR in ${filePath}`);
+      cur.sentinel = line.replace(/^SENTINEL\s+/, "").trim();
+    } else if (line === "---INJECT-BEGIN---") {
+      inInject = true;
+      injectLines = [];
+    } else if (line === "---INJECT-END---") {
+      if (!cur) throw new Error(`[vulkan-kernels] INJECT-END without ANCHOR in ${filePath}`);
+      cur.inject = injectLines.join("\n");
+      hunks.push(cur);
+      cur = null;
+      inInject = false;
+    } else if (inInject) {
+      injectLines.push(line);
+    }
+  }
+  if (hunks.length === 0) {
+    throw new Error(`[vulkan-kernels] no hunks parsed from ${filePath}`);
+  }
+  return hunks;
+}
+
+// Apply one parsed hunk to file contents. Returns { text, applied } where
+// applied=false means the inject block was already present (idempotent skip).
+//
+// Idempotency uses an *exact* check — the inject block already in the file —
+// rather than a coarse global sentinel, so multi-hunk patches against the
+// same file (e.g. struct-field hunk + load-shaders hunk) can be applied
+// independently and re-applied safely.
+function applyHunk(text, hunk, ctx) {
+  // Use the first non-blank line of the inject block as the per-hunk
+  // sentinel. Each inject block in our patches starts with a unique
+  // `// MILADY-VK-DISPATCH-PATCH-V1 BEGIN — <description>` comment, so
+  // first-non-blank identifies it precisely.
+  const firstLine = hunk.inject.split("\n").find((l) => l.trim().length > 0);
+  if (!firstLine) {
+    throw new Error(`[vulkan-kernels] empty inject block in ${ctx}`);
+  }
+  if (text.includes(firstLine)) {
+    return { text, applied: false };
+  }
+  const idx = text.indexOf(hunk.anchor);
+  if (idx === -1) {
+    throw new Error(
+      `[vulkan-kernels] anchor not found in ${ctx}: ${JSON.stringify(hunk.anchor)}`,
+    );
+  }
+  // Find the start of the line containing the anchor so we insert before it.
+  const lineStart = text.lastIndexOf("\n", idx) + 1;
+  const before = text.slice(0, lineStart);
+  const after = text.slice(lineStart);
+  return { text: before + hunk.inject + after, applied: true };
+}
+
+function applyPatches(cacheDir, { dryRun }) {
+  const results = [];
+  for (const { file, target } of PATCH_TARGETS) {
+    const patchPath = path.join(PATCHES_DIR, file);
+    const targetPath = path.join(cacheDir, target);
+    if (!fs.existsSync(patchPath)) {
+      throw new Error(`[vulkan-kernels] missing patch file: ${patchPath}`);
+    }
+    if (!fs.existsSync(targetPath)) {
+      throw new Error(`[vulkan-kernels] missing target file: ${targetPath}`);
+    }
+    const hunks = parsePatchFile(patchPath);
+    if (dryRun) {
+      console.log(
+        `[vulkan-kernels] (dry-run) would apply ${hunks.length} hunk(s) from ${file} to ${target}`,
+      );
+      results.push({ file, target, hunks: hunks.length, applied: 0, skipped: hunks.length });
+      continue;
+    }
+    let text = fs.readFileSync(targetPath, "utf8");
+    let applied = 0;
+    let skipped = 0;
+    for (const hunk of hunks) {
+      const r = applyHunk(text, hunk, target);
+      text = r.text;
+      if (r.applied) applied++; else skipped++;
+    }
+    fs.writeFileSync(targetPath, text, "utf8");
+    results.push({ file, target, hunks: hunks.length, applied, skipped });
+  }
+  return results;
+}
+
+// Public entry point used by build-llama-cpp-dflash.mjs.
+export function patchVulkanKernels(cacheDir, { dryRun = false, target = null } = {}) {
+  if (!cacheDir || !fs.existsSync(cacheDir)) {
+    throw new Error(`[vulkan-kernels] cacheDir does not exist: ${cacheDir}`);
+  }
+  assertStandalonesPresent();
+  const copied = copyStandalonesIntoFork(cacheDir, { dryRun });
+  const patchResults = applyPatches(cacheDir, { dryRun });
+  console.log(
+    `[vulkan-kernels] ${dryRun ? "(dry-run) " : ""}staged ${copied.length} standalone Vulkan shaders into vulkan-shaders/ ` +
+      `and applied ${patchResults.length} dispatch patches:`,
+  );
+  for (const r of patchResults) {
+    console.log(
+      `[vulkan-kernels]   ${r.file} → ${r.target}: ${r.applied} hunk(s) applied, ${r.skipped} idempotent-skipped`,
+    );
+  }
+  // Note: target arg is currently unused. AGENTS.md §3 enforcement (no
+  // milady-missing vulkan binary) is now done at build-llama-cpp-dflash.mjs
+  // post-build via the requiredKernels audit on the SPV blob list.
+  return { copied, patchResults };
+}

package/scripts/lib/allocate-loopback-port.mjs

@@ -0,0 +1,58 @@
+/**
+ * Pick a free loopback TCP port starting at `preferred` (inclusive).
+ *
+ * **Why a sibling of `loopback-port.ts`:** `dev-platform.mjs` runs under Node,
+ * not Bun, but the algorithm must match the Electrobun shell: find the first
+ * bindable 127.0.0.1 port in a range.
+ *
+ * **Why the orchestrator allocates before spawn:** Vite reads `vite.config.ts`
+ * once; its `/api` proxy target must equal the API listen port **at Vite
+ * startup**. If only `dev-server.ts` shifted ports internally, the UI would
+ * proxy to a stale default until Vite restarted. Resolving here keeps
+ * `ELIZA_API_PORT`, `ELIZA_DESKTOP_API_BASE`, `ELIZA_RENDERER_URL`, and
+ * `ELIZA_PORT` (Vite) consistent across all children.
+ */
+
+import { createServer } from "node:net";
+
+/**
+ * @param {number} port
+ * @param {string} [host]
+ * @returns {Promise<boolean>}
+ */
+function tryBindPort(port, host = "127.0.0.1") {
+  return new Promise((resolve) => {
+    const server = createServer();
+    const onErr = () => {
+      server.removeAllListeners();
+      resolve(false);
+    };
+    server.once("error", onErr);
+    server.listen({ port, host }, () => {
+      server.close(() => resolve(true));
+    });
+  });
+}
+
+/**
+ * @param {number} preferred
+ * @param {{ maxHops?: number, host?: string }} [opts]
+ * @returns {Promise<number>}
+ */
+export async function allocateFirstFreeLoopbackPort(preferred, opts = {}) {
+  const host = opts.host ?? "127.0.0.1";
+  const maxHops = opts.maxHops ?? 64;
+  if (!Number.isFinite(preferred) || preferred < 1 || preferred > 65535) {
+    throw new Error(`Invalid preferred port: ${preferred}`);
+  }
+  for (let i = 0; i < maxHops; i++) {
+    const port = preferred + i;
+    if (port > 65535) break;
+    if (await tryBindPort(port, host)) {
+      return port;
+    }
+  }
+  throw new Error(
+    `No free TCP port on ${host} in range ${preferred}–${preferred + maxHops - 1}`,
+  );
+}

package/scripts/lib/api-supervisor.mjs

@@ -0,0 +1,115 @@
+/**
+ * API process supervisor with crash-loop backoff.
+ *
+ * Both `dev-ui.mjs` and `dev-platform.mjs` need to keep the API server alive
+ * across `process.exit(0)` (RESTART action), `process.exit(75)` (CLI runner
+ * restart exit code), and `bun --watch` reloads — but stop trying when the
+ * server keeps exiting in a tight window (a real crash that needs a human).
+ *
+ * The supervisor is unaware of how the API is spawned; callers pass a
+ * `spawnChild()` factory that returns a node ChildProcess. The factory is
+ * called once per launch, including relaunches.
+ *
+ * Defaults:
+ *   - 10s rolling window
+ *   - 5 restarts permitted in that window before giving up
+ *   - 400ms delay between exit and relaunch
+ */
+
+const DEFAULT_WINDOW_MS = 10_000;
+const DEFAULT_LIMIT = 5;
+const DEFAULT_RESPAWN_DELAY_MS = 400;
+
+/**
+ * @typedef {Object} ApiSupervisorOptions
+ * @property {() => import("node:child_process").ChildProcess} spawnChild
+ *   Spawn a fresh API child. Called on `start()` and on every relaunch.
+ * @property {(child: import("node:child_process").ChildProcess) => void} [onSpawn]
+ *   Optional callback after each spawn (e.g. push child into a tracking array,
+ *   wire log prefixers).
+ * @property {(child: import("node:child_process").ChildProcess) => void} [onExit]
+ *   Optional callback before backoff/relaunch decision (e.g. remove child
+ *   from a tracking array, clear handle).
+ * @property {(code: number | null, streak: number) => void} onGiveUp
+ *   Called when the streak exceeds `limit` in `windowMs`. Caller should
+ *   trigger shutdown.
+ * @property {() => boolean} isShuttingDown
+ *   Returns true while the parent process is in shutdown. Suppresses relaunch.
+ * @property {(message: string) => void} [log] Defaults to `console.log`.
+ * @property {(message: string) => void} [warn] Defaults to `console.error`.
+ * @property {number} [windowMs] Default 10_000.
+ * @property {number} [limit] Default 5.
+ * @property {number} [respawnDelayMs] Default 400.
+ */
+
+/**
+ * @param {ApiSupervisorOptions} opts
+ */
+export function createApiSupervisor(opts) {
+  const {
+    spawnChild,
+    onSpawn,
+    onExit,
+    onGiveUp,
+    isShuttingDown,
+    log = console.log.bind(console),
+    warn = console.error.bind(console),
+    windowMs = DEFAULT_WINDOW_MS,
+    limit = DEFAULT_LIMIT,
+    respawnDelayMs = DEFAULT_RESPAWN_DELAY_MS,
+  } = opts;
+
+  let streak = 0;
+  let lastExitAt = 0;
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let pendingRespawn = null;
+
+  function launch() {
+    const child = spawnChild();
+    if (onSpawn) onSpawn(child);
+    child.on("exit", (code) => {
+      if (onExit) onExit(child);
+      if (isShuttingDown()) return;
+
+      const now = Date.now();
+      streak = now - lastExitAt < windowMs ? streak + 1 : 1;
+      lastExitAt = now;
+
+      if (streak > limit) {
+        warn(
+          `API exited with code ${code} ${streak} times in ${
+            windowMs / 1000
+          }s — giving up. Fix the underlying issue and restart the dev process.`,
+        );
+        onGiveUp(code, streak);
+        return;
+      }
+
+      // The agent's RESTART action and `/api/restart` both bounce the server
+      // with `process.exit(0)`; the CLI runner uses 75 as the dedicated
+      // restart exit code; Bun's `--watch` reload also exits cleanly. Treat
+      // any non-shutdown exit as "please restart me" and re-spawn.
+      log(
+        `API exited with code ${code} — relaunching (attempt ${streak}/${limit})…`,
+      );
+      pendingRespawn = setTimeout(() => {
+        pendingRespawn = null;
+        if (!isShuttingDown()) launch();
+      }, respawnDelayMs);
+    });
+    return child;
+  }
+
+  return {
+    start() {
+      return launch();
+    },
+    /** Cancel any pending relaunch (e.g. during shutdown). */
+    cancelPendingRespawn() {
+      if (pendingRespawn) {
+        clearTimeout(pendingRespawn);
+        pendingRespawn = null;
+      }
+    },
+  };
+}

package/scripts/lib/app-dir.mjs

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import path from "node:path";
+
+function hasPackageJson(dir) {
+  return fs.existsSync(path.join(dir, "package.json"));
+}
+
+function firstExistingPackage(candidates) {
+  return candidates.find(hasPackageJson) ?? candidates[0];
+}
+
+export function resolveMainAppDir(repoRoot, appName = "app") {
+  const cwd = path.resolve(process.cwd());
+  const elizaRoot = path.join(repoRoot, "eliza");
+  const cwdIsInsideNestedEliza =
+    hasPackageJson(elizaRoot) &&
+    (cwd === path.resolve(elizaRoot) ||
+      cwd.startsWith(`${path.resolve(elizaRoot)}${path.sep}`));
+
+  const isOuterMonorepo = hasPackageJson(path.join(repoRoot, "eliza"));
+  if (appName === "app") {
+    const localCandidates = [
+      path.join(repoRoot, "packages", "app"),
+      path.join(repoRoot, "apps", "app"),
+    ];
+    const outerCandidates = [
+      path.join(repoRoot, "eliza", "packages", "app"),
+      path.join(repoRoot, "eliza", "apps", "app"),
+      path.join(repoRoot, "apps", "app"),
+    ];
+    return firstExistingPackage(
+      isOuterMonorepo && !cwdIsInsideNestedEliza
+        ? [
+            path.join(repoRoot, "apps", "app"),
+            path.join(repoRoot, "packages", "app"),
+            path.join(repoRoot, "eliza", "packages", "app"),
+            path.join(repoRoot, "eliza", "apps", "app"),
+          ]
+        : isOuterMonorepo
+          ? outerCandidates
+          : localCandidates,
+    );
+  }
+
+  const candidates = [
+    path.join(repoRoot, "apps", appName),
+    path.join(repoRoot, "packages", appName),
+    path.join(repoRoot, "eliza", "apps", appName),
+    path.join(repoRoot, "eliza", "packages", appName),
+  ];
+  return firstExistingPackage(candidates);
+}
+
+export function relativeAppDir(repoRoot, appDir) {
+  return path.relative(repoRoot, appDir).replaceAll(path.sep, "/");
+}
+
+export function resolveElectrobunDir(repoRoot) {
+  const candidates = [
+    path.join(repoRoot, "packages", "app-core", "platforms", "electrobun"),
+    path.join(
+      repoRoot,
+      "eliza",
+      "packages",
+      "app-core",
+      "platforms",
+      "electrobun",
+    ),
+  ];
+  const match = candidates.find((candidate) =>
+    fs.existsSync(path.join(candidate, "electrobun.config.ts")),
+  );
+  return match ?? candidates[0];
+}