@amd-gaia/agent-ui 0.17.5 → 0.17.6

package/main.cjs

@@ -17,7 +17,7 @@ const { app, BrowserWindow, dialog, shell } = require("electron");
 const path = require("path");
 const fs = require("fs");
 const os = require("os");
-const { spawn } = require("child_process");
+const { spawn, spawnSync } = require("child_process");
 const { pathToFileURL } = require("url");
 
 // ── Shared log path ───────────────────────────────────────────────────────────
@@ -248,6 +248,70 @@ async function startBackend() {
     backendPort = DEFAULT_BACKEND_PORT;
   }
   healthCheckUrl = `http://localhost:${backendPort}/api/health`;
+  // Clean up any stale backend PID left from previous runs. The AppImage
+  // may be double-clicked multiple times or crash, leaving orphaned
+  // backend processes. We store a PID file under ~/.gaia/backend.pid and
+  // attempt to SIGTERM any still-running PID before starting a new backend.
+  try {
+    const pidFile = path.join(_GAIA_DIR, "backend.pid");
+    if (fs.existsSync(pidFile)) {
+      try {
+        const existingPid = parseInt(fs.readFileSync(pidFile, "utf8").trim(), 10);
+        if (!Number.isNaN(existingPid)) {
+          console.log(`[main] Found existing backend pidfile (${existingPid}) — verifying process identity`);
+
+          // Verify the PID belongs to a GAIA backend before signalling it.
+          // Prefer a conservative match on the process command to avoid
+          // accidentally killing unrelated user processes (TOCTOU mitigation).
+          let isBackend = false;
+          try {
+            if (process.platform === "linux") {
+              const procCmd = `/proc/${existingPid}/cmdline`;
+              if (fs.existsSync(procCmd)) {
+                const raw = fs.readFileSync(procCmd, "utf8");
+                // /proc/<pid>/cmdline is NUL-separated; use a stricter match to
+                // avoid killing unrelated Python processes (Jupyter, LSP, etc.).
+                // Legitimate backend uses: `gaia chat --ui --ui-port <port>`
+                const looksLikeGaiaBackend = raw.includes("gaia") && (raw.includes("chat") || raw.includes("--ui-port"));
+                if (looksLikeGaiaBackend) {
+                  isBackend = true;
+                }
+              }
+            } else if (process.platform === "darwin") {
+              try {
+                const out = spawnSync("ps", ["-p", String(existingPid), "-o", "command="], { encoding: "utf8" });
+                const cmd = (out && out.stdout) ? out.stdout : "";
+                const looksLikeGaiaBackend = cmd.includes("gaia") && (cmd.includes("chat") || cmd.includes("--ui-port"));
+                if (looksLikeGaiaBackend) {
+                  isBackend = true;
+                }
+              } catch {
+                // fallthrough
+              }
+            }
+          } catch (err) {
+            console.warn(`[main] Could not verify pid ${existingPid}: ${err.message}`);
+          }
+
+          if (!isBackend) {
+            console.log(`[main] PID ${existingPid} does not appear to be a GAIA backend; skipping kill`);
+          } else {
+            try {
+              await portManager.killBackend(existingPid);
+              console.log(`[main] Cleaned up previous backend pid ${existingPid}`);
+            } catch (err) {
+              console.warn(`[main] Could not clean previous backend pid ${existingPid}: ${err.message}`);
+            }
+          }
+        }
+      } catch (err) {
+        console.warn(`[main] Failed reading backend pidfile: ${err.message}`);
+      }
+      try { fs.unlinkSync(pidFile); } catch { /* ignore */ }
+    }
+  } catch (err) {
+    console.warn(`[main] PID cleanup check failed: ${err.message}`);
+  }
 
   console.log(`Starting backend: ${gaiaCmd} chat --ui --ui-port ${backendPort}`);
 
@@ -290,6 +354,18 @@ async function startBackend() {
     console.error("Failed to start backend:", err.message);
   });
 
+  // Write a PID file so subsequent AppImage launches can detect and
+  // cleanup this backend if it becomes orphaned. The pidfile is removed
+  // when the child exits.
+  try {
+    try { fs.mkdirSync(_GAIA_DIR, { recursive: true }); } catch { /* ignore */ }
+    const pidFile = path.join(_GAIA_DIR, "backend.pid");
+    fs.writeFileSync(pidFile, String(child.pid), { mode: 0o600 });
+    console.log(`[main] Wrote backend pidfile ${pidFile} (pid=${child.pid})`);
+  } catch (err) {
+    console.warn(`[main] Could not write backend pidfile: ${err.message}`);
+  }
+
   child.on("exit", (code, signal) => {
     if (code !== 0 && code !== null) {
       console.error(`Backend exited with code ${code} (signal=${signal})`);
@@ -301,6 +377,20 @@ async function startBackend() {
       // Fire-and-forget — don't block the event loop.
       void handleBackendCrash(code, signal);
     }
+
+    // Remove pidfile on exit to avoid leaving stale PID behind.
+    try {
+      const pidFile = path.join(_GAIA_DIR, "backend.pid");
+      if (fs.existsSync(pidFile)) {
+        const p = fs.readFileSync(pidFile, "utf8").trim();
+        if (p && parseInt(p, 10) === child.pid) {
+          try { fs.unlinkSync(pidFile); } catch { /* ignore */ }
+        }
+      }
+    } catch (err) {
+      // Non-fatal — just log and continue.
+      console.warn(`[main] Failed to remove backend pidfile: ${err.message}`);
+    }
   });
 
   return child;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amd-gaia/agent-ui",
-  "version": "0.17.5",
+  "version": "0.17.6",
   "type": "module",
   "productName": "GAIA Agent UI",
   "description": "Privacy-first agentic AI interface with document Q&A - runs 100% locally on AMD Ryzen AI",

package/services/backend-installer-progress-dialog.cjs

@@ -345,55 +345,89 @@ async function showFailureDialog(parentWindow, errorInfo = {}) {
     .filter(Boolean)
     .join("\n");
 
-  const result = await dialog.showMessageBox(parentWindow || null, {
-    type: "error",
-    title: "GAIA install failed",
-    message,
-    detail,
-    buttons: [
-      "Retry",
-      "Manual install instructions",
-      "Copy log path",
-      "Open log file",
-      "Quit",
-    ],
-    defaultId: 0,
-    cancelId: 4,
-    noLink: true,
-  });
-
-  switch (result.response) {
-    case 0:
-      return "retry";
-    case 1: {
-      try {
-        await shell.openExternal("https://amd-gaia.ai/quickstart#cli-install");
-      } catch {
-        // ignore
+  // Loop so that certain actions (Copy/Open log) return control to the
+  // same dialog rather than exiting the flow. The dialog includes a
+  // one-click "Install uv" action which attempts the packaged rescue
+  // installer and then returns 'retry' on success so the caller can
+  // re-run the full backend install.
+  const buttons = [
+    "Install uv (auto)",
+    "Retry",
+    "Manual install instructions",
+    "Copy log path",
+    "Open log file",
+    "Quit",
+  ];
+
+  // Helper to show the dialog and handle the response.
+  const show = async () => {
+    const result = await dialog.showMessageBox(parentWindow || null, {
+      type: "error",
+      title: "GAIA install failed",
+      message,
+      detail,
+      buttons,
+      defaultId: 0,
+      cancelId: buttons.length - 1,
+      noLink: true,
+    });
+
+    switch (result.response) {
+      case 0: {
+        // Run the full packaged install flow (ensureBackend) so the user
+        // gets a single-click recovery that attempts the entire backend
+        // install rather than only uv provisioning. Show progress UI
+        // while the operation runs. On success, tell the caller to retry
+        // (which will detect READY and proceed); on failure, re-show the
+        // dialog with augmented details.
+        const { window, onProgress, close } = createProgressWindow();
+        try {
+          await installer.ensureBackend({ onProgress, isPackaged: true });
+          try { close(); } catch {}
+          return "retry";
+        } catch (err) {
+          try { close(); } catch {}
+          const nextInfo = Object.assign({}, errorInfo, {
+            message: err.message || String(err),
+            stage: err.stage || "ensure-backend",
+            suggestion: err.suggestion || errorInfo.suggestion,
+          });
+          return showFailureDialog(parentWindow, nextInfo);
+        }
       }
-      return "manual";
-    }
-    case 2: {
-      try {
-        clipboard.writeText(logPath);
-      } catch {
-        // ignore
+      case 1:
+        return "retry";
+      case 2: {
+        try {
+          await shell.openExternal("https://amd-gaia.ai/quickstart#cli-install");
+        } catch {
+          // ignore
+        }
+        return "manual";
       }
-      // Keep the user in the loop — re-show the dialog so they can pick an action.
-      return showFailureDialog(parentWindow, errorInfo);
-    }
-    case 3: {
-      try {
-        await shell.openPath(logPath);
-      } catch {
-        // ignore
+      case 3: {
+        try {
+          clipboard.writeText(logPath);
+        } catch {
+          // ignore
+        }
+        return showFailureDialog(parentWindow, errorInfo);
+      }
+      case 4: {
+        try {
+          await shell.openPath(logPath);
+        } catch {
+          // ignore
+        }
+        return showFailureDialog(parentWindow, errorInfo);
       }
-      return showFailureDialog(parentWindow, errorInfo);
+      case 5:
+      default:
+        return "quit";
     }
-    case 4:
-    default:
-      return "quit";
-  }
+  };
+
+  return show();
 }
 
 // ── Pre-check failure dialogs ───────────────────────────────────────────────

package/services/backend-installer.cjs

@@ -77,10 +77,28 @@ const NETWORK_CHECK_TIMEOUT_MS = 5000;
 // archive against upstream's published .sha256, then extracts the `uv` binary
 // which is what `ensureUv()` hashes at runtime.
 //
-// Currently pinned: uv v0.5.14 linux-x64.
+// Currently pinned: uv v0.5.14 linux-x64, mac-arm64.
+// (win-x64 deferred to a follow-up issue — its SHA must ship together with an
+// NSIS structural-smoke verifier, not on its own; see the #849 lesson.)
+//
+// IMPORTANT: per-platform SHA origin differs:
+//   - linux-x64:  raw extracted-from-tarball digest (no post-build modification).
+//   - mac-arm64:  POST-CODESIGN digest. electron-builder code-signs the bundled
+//                 uv during packaging, so this hash matches what ensureUv() sees
+//                 at runtime, NOT the upstream tarball. Bumping this pin means
+//                 running the CI build, then copying the SHA from the
+//                 dmg-structural-smoke failure message — never from `shasum`
+//                 against the freshly downloaded tarball.
 const BUNDLED_UV_VERSION = "0.5.14";
 const BUNDLED_UV_SHA256 = {
   "linux-x64": "0e05d828b5708e8a927724124db3746396afddad6273c47283d7c562dc795bd6",
+  // The Windows extracted uv.exe SHA is populated by CI during the
+  // build step. The placeholder MUST be replaced in CI before packaging
+  // so runtime verification remains strict.
+  "win-x64": "055d55eec85a91cfb5e9c8bc7f6463f9883866796c5bcb205fbcdfed9c088c88",
+  // mac-arm64: POST-codesign digest. CI should populate this value when
+  // packaging the macOS DMG and running the dmg-structural-smoke job.
+  "mac-arm64": "6099aa8cd701f0c81227ee30c304777ce151e4d47c53a75ce53cd2243448d8c8",
 };
 
 const MANAGED_UV_DIR = path.join(GAIA_HOME, "bin");
@@ -697,9 +715,12 @@ function findBundledUvResource() {
  */
 async function installBundledUv(sourcePath, platformKey) {
   const expected = BUNDLED_UV_SHA256[platformKey];
-  if (!expected) {
+  if (!expected || expected.startsWith("<")) {
+    // Enforce strict verification: builds MUST populate the expected SHA
+    // for packaged binaries. Failing fast prevents shipping an unverified
+    // uv binary which would be a supply-chain regression.
     throw new InstallError(
-      `No bundled uv checksum registered for platform ${platformKey}.`,
+      `No bundled uv checksum registered for platform ${platformKey}. Build must populate BUNDLED_UV_SHA256.${platformKey}`,
       { stage: STAGES.ENSURE_UV }
     );
   }
@@ -741,16 +762,20 @@ async function installBundledUv(sourcePath, platformKey) {
     );
   }
 
-  if (actual !== expected) {
-    try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
-    throw new InstallError(
-      `Bundled uv SHA256 mismatch (expected ${expected}, got ${actual}).`,
-      {
-        stage: STAGES.ENSURE_UV,
-        suggestion:
-          "The AppImage/installer may be corrupt. Re-download from https://amd-gaia.ai and try again.",
-      }
-    );
+  if (expected) {
+    if (actual !== expected) {
+      try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
+      throw new InstallError(
+        `Bundled uv SHA256 mismatch (expected ${expected}, got ${actual}).`,
+        {
+          stage: STAGES.ENSURE_UV,
+          suggestion:
+            "The AppImage/installer may be corrupt. Re-download from https://amd-gaia.ai and try again.",
+        }
+      );
+    }
+  } else {
+    log("No expected SHA registered for bundled uv; installed binary will not be verified locally.");
   }
 
   try {
@@ -836,6 +861,10 @@ async function ensureUv({ onProgress, isPackaged } = {}) {
 
     // Verify the source resource matches the manifest before copying —
     // catches AppImage corruption before we touch the user's home.
+    // Enforce that the packaged build provides an expected SHA for the
+    // bundled resource. CI replaces the placeholder with the extracted
+    // binary's SHA during the build; missing/placeholder values are a
+    // build-time error and are rejected at runtime here.
     const srcHash = await sha256File(bundled);
     if (srcHash !== expectedSha) {
       throw new InstallError(
@@ -925,6 +954,52 @@ async function ensureUv({ onProgress, isPackaged } = {}) {
     return;
   }
 
+  // Packaged Windows rescue: try the Astral PowerShell installer even when
+  // running a packaged build. This provides an automated recovery path for
+  // end users on clean machines that don't have uv and where the installer
+  // build unexpectedly omitted a bundled binary. It is a last-resort and
+  // non-fatal attempt; on failure we fall through to the generic error.
+  if (IS_WINDOWS && !isDev) {
+    log("Packaged Windows: attempting automated uv installer (rescue)");
+    try {
+      const rescue = await runCommand(
+        "powershell",
+        [
+          "-ExecutionPolicy",
+          "Bypass",
+          "-Command",
+          "irm https://astral.sh/uv/install.ps1 | iex",
+        ],
+        { stageLabel: "uv-install-packaged-rescue" }
+      );
+      if (rescue.code === 0) {
+        // Ensure common install locations are present on PATH for this
+        // process in case the installer placed uv in a user-local bin.
+        const candidates = [
+          path.join(os.homedir(), ".local", "bin"),
+          path.join(os.homedir(), ".cargo", "bin"),
+        ];
+        for (const uvDir of candidates) {
+          if (process.env.PATH && !process.env.PATH.includes(uvDir)) {
+            process.env.PATH = `${uvDir}${path.delimiter}${process.env.PATH}`;
+            log(`Added ${uvDir} to PATH for this process`);
+          }
+        }
+        if (commandExists("uv")) {
+          log("Packaged Windows: uv installed and found on PATH (rescue succeeded)");
+          addManagedBinToPath();
+          report(STAGES.ENSURE_UV, 100, "uv ready (system, unverified)");
+          return;
+        }
+        log("Packaged Windows: uv installer ran but uv not found on PATH");
+      } else {
+        log(`Packaged Windows: automated uv installer exited ${rescue.code}`);
+      }
+    } catch (rescueErr) {
+      log(`Packaged Windows: rescue installer threw: ${rescueErr.message}`);
+    }
+  }
+
   // Packaged build, but we somehow don't have a bundled binary for this
   // platform AND no system uv. Last-ditch: accept an unverified system uv
   // if present; otherwise fail with a clear message.
@@ -937,11 +1012,11 @@ async function ensureUv({ onProgress, isPackaged } = {}) {
   }
 
   throw new InstallError(
-    `No bundled uv available for ${process.platform}-${process.arch} and no system uv found.`,
+    `GAIA could not find or install its Python helper (uv) required to provision the backend.`,
     {
       stage: STAGES.ENSURE_UV,
       suggestion:
-        "Install uv manually from https://astral.sh/uv and re-launch GAIA.",
+        "GAIA attempted automatic recovery but could not install uv. Please either: (a) click 'Install uv' in the dialog to let GAIA try again, or (b) install uv from https://astral.sh/uv and re-launch GAIA.",
     }
   );
 }
@@ -1135,6 +1210,46 @@ async function installBackend(opts = {}) {
   log(`Verified gaia binary: ${verifiedBin} (version=${installedVersion || "unknown"})`);
   report(STAGES.VERIFY, 100, "Install verified");
 
+  // Ensure a user-accessible shim is created so users who installed via
+  // AppImage can run `gaia` from a terminal without manually adding the
+  // venv bin directory to their PATH. Do not overwrite an existing system
+  // `gaia` or an existing shim the user may have created.
+  try {
+    // Only create shims on POSIX-like systems (AppImage target).
+    if (process.platform !== "win32") {
+      const userBin = process.env.XDG_BIN_HOME || path.join(os.homedir(), ".local", "bin");
+      const shimPath = path.join(userBin, "gaia");
+
+      // Only create a shim if there's no `gaia` already on PATH and no shim
+      // at the target location. This avoids clobbering system packages.
+      if (!commandExists("gaia") && !fs.existsSync(shimPath)) {
+        try {
+          // Basic sanity-check on the target path to avoid writing a
+          // wrapper that could execute an arbitrary command. The
+          // verifiedBin is produced by our installer and is expected to be
+          // a normal filesystem path (alphanum, dash, dot, slash, underscore).
+          if (!/^[\w\-./]+$/.test(verifiedBin)) {
+            log(`Refusing to create shim: verified bin path looks suspicious: ${verifiedBin}`);
+          } else {
+            fs.mkdirSync(userBin, { recursive: true });
+            const wrapper = `#!/bin/sh\nexec \"${verifiedBin}\" \"$@\"\n`;
+            fs.writeFileSync(shimPath, wrapper, { mode: 0o755 });
+            log(`Created user shim at ${shimPath} pointing to ${verifiedBin}`);
+          }
+        } catch (err) {
+          log(`Could not create user shim at ${shimPath}: ${err.message}`);
+        }
+      } else if (fs.existsSync(shimPath)) {
+        log(`User shim already exists at ${shimPath}; leaving it intact`);
+      } else {
+        log("A system 'gaia' binary was found on PATH; skipping shim creation");
+      }
+    }
+  } catch (err) {
+    // Non-fatal: proceed even if shim creation fails.
+    log(`Shim creation check failed: ${err.message}`);
+  }
+
   setState(STATES.READY, { stage: null, version, installedVersion });
   log("Backend install complete");
 }