@amd-gaia/agent-ui 0.22.0 → 0.23.0

package/main.cjs

@@ -63,6 +63,13 @@ const backendInstaller = require("./services/backend-installer.cjs");
 const installerProgressDialog = require("./services/backend-installer-progress-dialog.cjs");
 const autoUpdater = require("./services/auto-updater.cjs");
 const agentSeeder = require("./services/agent-seeder.cjs");
+const systemMetrics = require("./services/system-metrics.cjs");
+const {
+  parseDeepLink,
+  extractDeepLinkFromArgv,
+  dispatchDeepLink,
+  buildInstallPrompt,
+} = require("./services/deep-link.cjs");
 
 // ── F7: Ozone hint (issue #782) ─────────────────────────────────────────────
 // Electron-recommended switch for distro-agnostic Linux behaviour: picks
@@ -586,7 +593,12 @@ function initializeServices() {
   console.log("[main] Initializing services...");
 
   // T2: Agent Process Manager (manages OS agent subprocesses)
-  agentProcessManager = new AgentProcessManager(mainWindow);
+  // getBackendPort lets its install/uninstall handlers proxy to the live
+  // Python backend's install runtime (issue #1721) on whatever random port
+  // port-manager picked this session.
+  agentProcessManager = new AgentProcessManager(mainWindow, {
+    getBackendPort: () => backendPort,
+  });
 
   // T1: Tray Manager (system tray icon + context menu)
   trayManager = new TrayManager(mainWindow, { backendPort });
@@ -599,6 +611,9 @@ function initializeServices() {
     trayManager
   );
 
+  // #2007: System metrics for the observability dashboard
+  systemMetrics.registerIpcHandlers();
+
   console.log("[main] Services initialized");
 }
 
@@ -723,6 +738,178 @@ async function bootstrapBackend() {
   return false;
 }
 
+// ── gaia:// deep-link install bridge (issue #1725) ──────────────────────────
+//
+// The website's "Open in GAIA" button opens a `gaia://hub/install/<id>` URL.
+// The OS routes it to this app (registered as the gaia:// protocol client);
+// we parse it and hand the agent id to the install runtime (issue #1721).
+//
+// Sources of the URL differ per OS:
+//   • macOS      — the `open-url` app event (registered before whenReady).
+//   • Win/Linux  — a command-line argument, either at cold start (process.argv)
+//                  or on a second launch (the `second-instance` event argv).
+// A malformed/unsupported link surfaces a loud error dialog — never a silent
+// no-op (deep-link.cjs throws with an actionable message).
+
+/** Holds a deep link that arrived before services were ready. */
+let pendingDeepLinkUrl = null;
+
+/**
+ * Register this app as the handler for the gaia:// scheme. In dev (`electron .`)
+ * the launcher is Electron itself, so the app path must be threaded through
+ * explicitly; packaged builds register their own executable.
+ */
+function registerProtocolHandler() {
+  try {
+    let registered;
+    if (process.defaultApp && process.argv.length >= 2) {
+      // Dev: `electron . <args>` — point the scheme at this script.
+      registered = app.setAsDefaultProtocolClient("gaia", process.execPath, [
+        path.resolve(process.argv[1]),
+      ]);
+    } else {
+      registered = app.setAsDefaultProtocolClient("gaia");
+    }
+    if (registered) {
+      console.log("[main] Registered as gaia:// protocol client");
+    } else {
+      console.warn(
+        "[main] Could not register gaia:// protocol client — deep-link installs may not route to this app"
+      );
+    }
+  } catch (err) {
+    console.warn(
+      `[main] setAsDefaultProtocolClient failed: ${err && err.message ? err.message : err}`
+    );
+  }
+}
+
+/**
+ * Entry point for any inbound deep link. Queues the URL if services aren't up
+ * yet, otherwise dispatches immediately. Parse failures are surfaced loudly.
+ */
+function handleDeepLink(rawUrl) {
+  let command;
+  try {
+    command = parseDeepLink(rawUrl);
+  } catch (err) {
+    const message = err && err.message ? err.message : String(err);
+    console.error(`[main] Rejected deep link: ${message}`);
+    try {
+      dialog.showErrorBox("Invalid GAIA link", message);
+    } catch {
+      /* dialog may be unavailable pre-ready — the log line above still fires */
+    }
+    return;
+  }
+
+  // If services aren't wired yet (cold start still bootstrapping), stash it.
+  if (!agentProcessManager) {
+    console.log("[main] Deep link received before services ready — queuing");
+    pendingDeepLinkUrl = rawUrl;
+    return;
+  }
+
+  void runDeepLink(command);
+}
+
+/**
+ * Explicit, INFORMED per-agent confirmation for a web-triggered install. This
+ * is the security gate: the user must confirm the SPECIFIC agent — and see
+ * its real trust tier and permissions, not just its bare id — before any
+ * download happens (issue #2196 review; hardened so the shown facts match
+ * the backend's non-verified gate, which now covers every non-verified
+ * agent, not just native ones). Defaults to the safe (Cancel) option.
+ *
+ * Fails closed: if the agent can't be found in the catalog, or the backend
+ * is unreachable, the install is refused with an explanatory error — never
+ * installed blind.
+ * @returns {Promise<boolean>}
+ */
+async function confirmDeepLinkInstall(command) {
+  let entry;
+  try {
+    entry = await agentProcessManager.fetchCatalogEntry(command.agentId);
+  } catch (err) {
+    const message = err && err.message ? err.message : String(err);
+    console.error(
+      `[main] Refusing deep-link install of "${command.agentId}": ${message}`
+    );
+    try {
+      dialog.showErrorBox("Could not verify this agent", message);
+    } catch {
+      /* best-effort */
+    }
+    return false;
+  }
+
+  const prompt = buildInstallPrompt(entry);
+  const choice = await dialog.showMessageBox(
+    mainWindow && !mainWindow.isDestroyed() ? mainWindow : null,
+    {
+      type: "question",
+      buttons: [prompt.requiresTrust ? "Trust & Install" : "Install", "Cancel"],
+      defaultId: 1, // Enter selects the safe option
+      cancelId: 1,
+      title: prompt.title,
+      message: prompt.message,
+      detail: prompt.detail,
+      noLink: true,
+    }
+  );
+  return !!choice && choice.response === 0;
+}
+
+/** Wire the injected deep-link dispatcher to this process's runtime effects. */
+async function runDeepLink(command) {
+  console.log(`[main] Deep-link install request: ${command.agentId}`);
+  try {
+    await dispatchDeepLink(command, {
+      confirm: confirmDeepLinkInstall,
+      installAgent: (agentId, opts) => agentProcessManager.installAgent(agentId, opts),
+      focusWindow: () => {
+        if (mainWindow && !mainWindow.isDestroyed()) {
+          if (mainWindow.isMinimized()) mainWindow.restore();
+          if (!mainWindow.isVisible()) mainWindow.show();
+          mainWindow.focus();
+        }
+      },
+      logger: { log: console.log.bind(console), error: console.error.bind(console) },
+    });
+  } catch (err) {
+    const message = err && err.message ? err.message : String(err);
+    console.error(
+      `[main] Deep-link install of "${command.agentId}" failed: ${message}`
+    );
+    try {
+      dialog.showErrorBox(`Could not install "${command.agentId}"`, message);
+    } catch {
+      /* best-effort */
+    }
+  }
+}
+
+/** Drain a queued deep link, plus any gaia:// URL present in the cold-start argv. */
+function processStartupDeepLinks() {
+  if (pendingDeepLinkUrl) {
+    const url = pendingDeepLinkUrl;
+    pendingDeepLinkUrl = null;
+    handleDeepLink(url);
+    return;
+  }
+  const fromArgv = extractDeepLinkFromArgv(process.argv);
+  if (fromArgv) handleDeepLink(fromArgv);
+}
+
+// macOS delivers deep links via this event; it can fire before whenReady, so
+// register it at module load and let handleDeepLink queue as needed.
+app.on("open-url", (event, url) => {
+  event.preventDefault();
+  handleDeepLink(url);
+});
+
+registerProtocolHandler();
+
 // ── App Lifecycle ──────────────────────────────────────────────────────────
 
 // Note: electron-squirrel-startup was removed in Phase C of the
@@ -760,7 +947,7 @@ if (!gotTheSingleInstanceLock) {
   process.exit(0);
 }
 
-app.on("second-instance", (_event, _argv, _cwd) => {
+app.on("second-instance", (_event, argv, _cwd) => {
   // A second launch happened while we were running. Surface our window
   // (the user almost certainly wanted to see it). mainWindow may be null
   // if we're still in the bootstrap phase — in that case the first
@@ -771,6 +958,11 @@ app.on("second-instance", (_event, _argv, _cwd) => {
     if (!mainWindow.isVisible()) mainWindow.show();
     mainWindow.focus();
   }
+
+  // Win/Linux: a `gaia://…` deep link from the second launch arrives as an argv
+  // entry. Route it into the already-running first instance (issue #1725).
+  const deepLink = extractDeepLinkFromArgv(argv);
+  if (deepLink) handleDeepLink(deepLink);
 });
 
 app.whenReady().then(async () => {
@@ -837,6 +1029,10 @@ app.whenReady().then(async () => {
   // Setup Windows Jump List (T11)
   setupJumpList();
 
+  // Act on any gaia:// deep link that arrived during bootstrap or via the
+  // cold-start command line (issue #1725). Services are now wired.
+  processStartupDeepLinks();
+
   // Show loading state
   await loadApp();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amd-gaia/agent-ui",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "type": "module",
   "productName": "GAIA Agent UI",
   "description": "Privacy-first agentic AI interface with document Q&A - runs 100% locally on AMD Ryzen AI",
@@ -64,7 +64,7 @@
     "electron-updater": "^6.8.3"
   },
   "devDependencies": {
-    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/jest-dom": "^7.0.0",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",
     "@types/react": "^19.2.17",
@@ -72,7 +72,7 @@
     "@vitejs/plugin-react": "^6.0.2",
     "electron": "^43.0.0",
     "electron-builder": "^26.8.1",
-    "jsdom": "^29.1.1",
+    "jsdom": "^30.0.1",
     "lucide-react": "^1.17.0",
     "msw": "^2.7.0",
     "qrcode": "^1.5.4",

package/preload.cjs

@@ -13,6 +13,7 @@
  *   notification:*   — Desktop notifications & permission prompts (T5)
  *   install:*        — First-run backend install progress (Phase A)
  *   gaia:update:*    — Auto-update status & manual check (Phase F)
+ *   system:*         — System metrics for the observability dashboard (#2007)
  */
 
 const { contextBridge, ipcRenderer } = require("electron");
@@ -35,7 +36,9 @@ contextBridge.exposeInMainWorld("gaiaAPI", {
     sendRpc: (id, method, params) =>
       ipcRenderer.invoke("agent:send-rpc", id, method, params),
     getManifest: () => ipcRenderer.invoke("agent:get-manifest"),
-    install: (id) => ipcRenderer.invoke("agent:install", id),
+    // install(id, opts?) — opts: { trustNative?, version? }. Proxies to the
+    // backend install runtime; progress arrives via onInstallProgress (#1721).
+    install: (id, opts) => ipcRenderer.invoke("agent:install", id, opts),
     uninstall: (id) => ipcRenderer.invoke("agent:uninstall", id),
 
     // Event streams (return unsubscribe functions)
@@ -43,6 +46,7 @@ contextBridge.exposeInMainWorld("gaiaAPI", {
     onStderr: (cb) => onEvent("agent:stderr", cb),
     onStatusChange: (cb) => onEvent("agent:status-change", cb),
     onCrashed: (cb) => onEvent("agent:crashed", cb),
+    onInstallProgress: (cb) => onEvent("agent:install-progress", cb),
   },
 
   // ── Tray configuration (T1) ───────────────────────────────────────────
@@ -60,6 +64,11 @@ contextBridge.exposeInMainWorld("gaiaAPI", {
       ipcRenderer.invoke("notification:respond", id, action, remember),
     onNotification: (cb) => onEvent("notification:new", cb),
   },
+
+  // ── System metrics for the observability dashboard (#2007) ────────────
+  system: {
+    getMetrics: () => ipcRenderer.invoke("system:get-metrics"),
+  },
 });
 
 // ── Install progress (Phase A) ──────────────────────────────────────────

package/services/agent-process-manager.cjs

@@ -59,18 +59,42 @@ const STDERR_BUFFER_MAX = 10000;
 /** Max bytes kept in stdout buffer per agent (protects against malformed output without newlines) */
 const STDOUT_BUFFER_MAX = 1024 * 1024; // 1 MB
 
+/** Poll interval while waiting on the backend install-status endpoint (ms) */
+const INSTALL_POLL_INTERVAL = 750;
+
+/**
+ * Hard ceiling on a single install poll loop (ms). A `uv pip install` of a
+ * large wheel over a slow link can legitimately take minutes; we cap at 15 to
+ * turn a wedged backend into a loud timeout instead of an infinite spinner.
+ */
+const INSTALL_TIMEOUT = 15 * 60 * 1000;
+
+/** Header the UI backend requires on state-changing hub routes (see hub.py). */
+const UI_HEADER = { "X-Gaia-UI": "1" };
+
 // ── AgentProcessManager ──────────────────────────────────────────────────
 
 class AgentProcessManager extends EventEmitter {
   /**
    * @param {Electron.BrowserWindow} mainWindow — for sending IPC events to renderer
+   * @param {{ getBackendPort?: () => (number | null) }} [options]
+   *   getBackendPort resolves the live Python-backend port. The install/uninstall
+   *   handlers proxy to that backend's `/api/agents/*` routes (the real install
+   *   runtime), so without a resolver those handlers fail loudly rather than
+   *   duplicating download/verify/uv logic in the main process (issue #1721).
    */
-  constructor(mainWindow) {
+  constructor(mainWindow, options = {}) {
     super();
 
     /** @type {Electron.BrowserWindow} */
     this.mainWindow = mainWindow;
 
+    /** @type {(() => (number | null)) | null} */
+    this._getBackendPort =
+      typeof options.getBackendPort === "function"
+        ? options.getBackendPort
+        : null;
+
     /**
      * Running processes keyed by agentId.
      * @type {Record<string, {
@@ -251,6 +275,265 @@ class AgentProcessManager extends EventEmitter {
     return this.startAgent(agentId);
   }
 
+  // ── Public API: Install / Uninstall (issue #1721) ────────────────────
+  //
+  // The install RUNTIME lives in the Python backend (src/gaia/hub/installer.py,
+  // exposed by src/gaia/ui/routers/hub.py): R2 download, SHA-256 verify,
+  // `uv pip install` into ~/.gaia/agents/<id>/, hot-register, backup/rollback,
+  // and the native-trust gate. Rather than reimplement that in the main
+  // process, these handlers proxy to those routes so there is exactly one
+  // tested install path. Progress streams to the renderer over the existing
+  // `agent:install-progress` channel.
+
+  /**
+   * Resolve the live backend base URL, or throw an actionable error.
+   * @returns {string}
+   */
+  _backendBaseUrl() {
+    const port = this._getBackendPort ? this._getBackendPort() : null;
+    if (!port) {
+      throw new Error(
+        "GAIA backend is not running — cannot install or uninstall agents. " +
+          "The Python backend exposes the install runtime at /api/agents/install; " +
+          "wait for it to finish starting, or restart GAIA if this persists."
+      );
+    }
+    // 127.0.0.1 (not localhost) matches the backend's _require_localhost allowlist
+    // and avoids a DNS/IPv6 hop on Windows.
+    return `http://127.0.0.1:${port}`;
+  }
+
+  /**
+   * Fetch a single agent's catalog entry (tier, permissions, verified status)
+   * from the live backend. Used by the gaia:// deep-link install gate
+   * (main.cjs) to build an informed trust prompt — the confirmation must show
+   * the agent's real tier/permissions, not just its bare id.
+   *
+   * Throws with an actionable message when the backend is unreachable or the
+   * agent id isn't in the catalog. Callers MUST treat that as a refusal —
+   * never install without having shown the user what they're installing.
+   *
+   * @param {string} agentId
+   * @returns {Promise<object>} the matching catalog entry
+   */
+  async fetchCatalogEntry(agentId) {
+    if (typeof agentId !== "string" || !agentId.trim()) {
+      throw new Error("fetchCatalogEntry requires a non-empty agent id");
+    }
+    const base = this._backendBaseUrl();
+
+    let resp;
+    try {
+      resp = await fetch(`${base}/api/agents/catalog`, {
+        headers: { ...UI_HEADER },
+      });
+    } catch (err) {
+      throw new Error(
+        `Could not reach the GAIA backend to look up "${agentId}" in the agent catalog: ${err.message}`
+      );
+    }
+
+    if (!resp.ok) {
+      const detail = await this._readErrorDetail(resp);
+      throw new Error(
+        `Agent catalog request failed (HTTP ${resp.status}): ${detail}`
+      );
+    }
+
+    const body = await resp.json();
+    const agents = Array.isArray(body && body.agents) ? body.agents : [];
+    const entry = agents.find((a) => a && a.id === agentId);
+    if (!entry) {
+      throw new Error(`"${agentId}" was not found in the agent catalog.`);
+    }
+    return entry;
+  }
+
+  /**
+   * Install a published agent via the backend runtime, streaming progress.
+   *
+   * @param {string} agentId
+   * @param {{ trustNative?: boolean, version?: string | null }} [opts]
+   * @returns {Promise<{ id: string, status: string, version: string | null }>}
+   */
+  async installAgent(agentId, opts = {}) {
+    if (typeof agentId !== "string" || !agentId.trim()) {
+      throw new Error("installAgent requires a non-empty agent id");
+    }
+    const base = this._backendBaseUrl();
+    const trustNative = opts.trustNative === true;
+    const version =
+      typeof opts.version === "string" && opts.version ? opts.version : null;
+
+    this._emitInstallProgress(agentId, {
+      status: "queued",
+      phase: "queued",
+      percent: 0,
+    });
+
+    // ── Kick off the background install (202) ──
+    let resp;
+    try {
+      resp = await fetch(`${base}/api/agents/install`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...UI_HEADER },
+        body: JSON.stringify({ id: agentId, trust_native: trustNative, version }),
+      });
+    } catch (err) {
+      throw new Error(
+        `Could not reach the GAIA backend to install "${agentId}": ${err.message}`
+      );
+    }
+
+    if (!resp.ok) {
+      const detail = await this._readErrorDetail(resp);
+      if (resp.status === 409) {
+        throw new Error(`An install for "${agentId}" is already in progress.`);
+      }
+      if (resp.status === 403) {
+        // Native agents require explicit trust — surface the backend's reason.
+        throw new Error(
+          `Install of "${agentId}" was refused: ${detail} ` +
+            `(pass trustNative once the user accepts the trust prompt).`
+        );
+      }
+      throw new Error(
+        `Install request for "${agentId}" failed (HTTP ${resp.status}): ${detail}`
+      );
+    }
+
+    // ── Poll install-status until terminal ──
+    const deadline = Date.now() + INSTALL_TIMEOUT;
+    let lastState = null;
+    while (Date.now() < deadline) {
+      await this._sleep(INSTALL_POLL_INTERVAL);
+
+      let statusResp;
+      try {
+        statusResp = await fetch(
+          `${base}/api/agents/${encodeURIComponent(agentId)}/install-status`,
+          { headers: { ...UI_HEADER } }
+        );
+      } catch (err) {
+        throw new Error(
+          `Lost contact with the GAIA backend while installing "${agentId}": ${err.message}`
+        );
+      }
+
+      // A brief 404 window is possible between the 202 and the worker seeding
+      // progress; keep polling until the deadline rather than failing early.
+      if (statusResp.status === 404) continue;
+      if (!statusResp.ok) {
+        const detail = await this._readErrorDetail(statusResp);
+        throw new Error(
+          `Install-status poll for "${agentId}" failed (HTTP ${statusResp.status}): ${detail}`
+        );
+      }
+
+      lastState = await statusResp.json();
+      this._emitInstallProgress(agentId, {
+        status: lastState.status,
+        phase: lastState.phase,
+        percent: lastState.percent,
+        version: lastState.version,
+        error: lastState.error,
+      });
+
+      if (lastState.status === "completed") {
+        // Hot-register already happened backend-side; refresh our manifest so
+        // getAgentStatus / startAgent see the new binary paths.
+        this.reloadManifest();
+        return {
+          id: agentId,
+          status: "completed",
+          version: lastState.version || null,
+        };
+      }
+      if (lastState.status === "failed") {
+        throw new Error(
+          `Install of "${agentId}" failed: ${lastState.error || "unknown error"}`
+        );
+      }
+    }
+
+    throw new Error(
+      `Install of "${agentId}" timed out after ${Math.round(
+        INSTALL_TIMEOUT / 1000
+      )}s (last phase: ${lastState ? lastState.phase : "unknown"}).`
+    );
+  }
+
+  /**
+   * Uninstall a hub-installed agent: stop any running sidecar, then delegate
+   * removal + de-registration to the backend runtime.
+   *
+   * @param {string} agentId
+   * @returns {Promise<{ id: string, status: string }>}
+   */
+  async uninstallAgent(agentId) {
+    if (typeof agentId !== "string" || !agentId.trim()) {
+      throw new Error("uninstallAgent requires a non-empty agent id");
+    }
+    const base = this._backendBaseUrl();
+
+    // Stop a running sidecar first so its dir/executable isn't held open.
+    if (this.processes[agentId]) {
+      await this.stopAgent(agentId);
+    }
+
+    let resp;
+    try {
+      resp = await fetch(`${base}/api/agents/${encodeURIComponent(agentId)}`, {
+        method: "DELETE",
+        headers: { ...UI_HEADER },
+      });
+    } catch (err) {
+      throw new Error(
+        `Could not reach the GAIA backend to uninstall "${agentId}": ${err.message}`
+      );
+    }
+
+    if (!resp.ok) {
+      const detail = await this._readErrorDetail(resp);
+      if (resp.status === 404) {
+        throw new Error(`"${agentId}" is not installed.`);
+      }
+      if (resp.status === 400) {
+        // e.g. refusing to remove a builtin — surface the backend's reason.
+        throw new Error(`Cannot uninstall "${agentId}": ${detail}`);
+      }
+      throw new Error(
+        `Uninstall of "${agentId}" failed (HTTP ${resp.status}): ${detail}`
+      );
+    }
+
+    this.reloadManifest();
+    return { id: agentId, status: "uninstalled" };
+  }
+
+  /** Read a FastAPI-style `{detail}` error body without throwing. */
+  async _readErrorDetail(resp) {
+    try {
+      const body = await resp.json();
+      if (body && typeof body.detail === "string") return body.detail;
+      return JSON.stringify(body);
+    } catch {
+      return resp.statusText || `HTTP ${resp.status}`;
+    }
+  }
+
+  _emitInstallProgress(agentId, progress) {
+    this._sendToRenderer("agent:install-progress", {
+      agentId,
+      ...progress,
+      timestamp: Date.now(),
+    });
+  }
+
+  _sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
   // ── Public API: Monitoring ───────────────────────────────────────────
 
   /**
@@ -803,14 +1086,12 @@ class AgentProcessManager extends EventEmitter {
       return this.getManifest();
     });
 
-    ipcMain.handle("agent:install", async (_event, agentId) => {
-      // TODO: T7 — agent installer integration
-      throw new Error("Agent installation not yet implemented");
+    ipcMain.handle("agent:install", async (_event, agentId, opts) => {
+      return this.installAgent(agentId, opts || {});
     });
 
     ipcMain.handle("agent:uninstall", async (_event, agentId) => {
-      // TODO: T7 — agent uninstaller integration
-      throw new Error("Agent uninstallation not yet implemented");
+      return this.uninstallAgent(agentId);
     });
   }
 }