@amd-gaia/agent-ui 0.24.0 → 0.25.0-rc.2

package/services/deep-link-queue.cjs

@@ -0,0 +1,77 @@
+// Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+/**
+ * deep-link-queue.cjs — hold gaia:// links until the backend can verify them.
+ *
+ * A cold-start "Open in GAIA" link reaches the app long before the backend
+ * listens, and the install gate resolves the agent through the backend's
+ * catalog API (failing closed). This queue holds every link that arrives
+ * before startup has waited for the backend, then dispatches each exactly
+ * once. Electron-free so the ordering can be unit-tested.
+ */
+
+"use strict";
+
+/**
+ * @param {object} deps
+ * @param {(rawUrl: string) => void} deps.dispatch Act on one validated link.
+ * @param {(rawUrls: string[]) => void} deps.reportNotReady Tell the user the
+ *   queued links could not be opened because the backend never came up.
+ * @param {{log: Function}} [deps.logger]
+ */
+function createStartupDeepLinkQueue({ dispatch, reportNotReady, logger = console }) {
+  if (typeof dispatch !== "function" || typeof reportNotReady !== "function") {
+    throw new Error("createStartupDeepLinkQueue requires dispatch and reportNotReady functions");
+  }
+  const pending = [];
+  let drained = false;
+
+  return {
+    /**
+     * Accept a validated link: queue it until drain(), dispatch it after.
+     * @returns {"queued" | "duplicate" | "dispatched"}
+     */
+    accept(rawUrl) {
+      if (drained) {
+        dispatch(rawUrl);
+        return "dispatched";
+      }
+      if (pending.includes(rawUrl)) return "duplicate";
+      pending.push(rawUrl);
+      logger.log(`[deep-link] Queued until the backend is ready: ${rawUrl}`);
+      return "queued";
+    },
+
+    /**
+     * Release the queue once, after startup has waited for the backend.
+     * Later calls are no-ops, so nothing is dispatched twice.
+     *
+     * @param {{backendReady: boolean, argvUrl?: string|null}} opts
+     * @returns {string[]} The links dispatched by this call.
+     */
+    drain({ backendReady, argvUrl = null }) {
+      if (drained) return [];
+      drained = true;
+      const urls = pending.splice(0);
+      if (argvUrl && !urls.includes(argvUrl)) urls.push(argvUrl);
+      if (urls.length === 0) return [];
+      if (!backendReady) {
+        reportNotReady(urls);
+        return [];
+      }
+      for (const url of urls) dispatch(url);
+      return urls;
+    },
+
+    get isDrained() {
+      return drained;
+    },
+
+    get pendingCount() {
+      return pending.length;
+    },
+  };
+}
+
+module.exports = { createStartupDeepLinkQueue };

package/services/link-policy.cjs

@@ -0,0 +1,90 @@
+// Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+/**
+ * link-policy.cjs — which URLs the shell is allowed to hand to the OS.
+ *
+ * The renderer is loaded from `file://`, so a scheme-less link in
+ * LLM-rendered markdown (`/Windows/System32/calc.exe`, `//host/share/x.exe`)
+ * RESOLVES to `file:///C:/…` / `file://host/…` before Electron hands it to
+ * `setWindowOpenHandler`. Passing that to `shell.openExternal` is a
+ * ShellExecute on a local binary or an SMB fetch. The check therefore runs on
+ * the resolved URL and allows only web/mail schemes.
+ *
+ * Electron-free so it can be unit-tested without a running app; main.cjs owns
+ * the window handlers that call it.
+ */
+
+"use strict";
+
+/** The only schemes `shell.openExternal` may ever receive. */
+const ALLOWED_EXTERNAL_SCHEMES = new Set(["http:", "https:", "mailto:"]);
+
+/**
+ * @param {string} rawUrl A URL already resolved by Electron/Chromium.
+ * @returns {boolean} True when it is safe to hand to `shell.openExternal`.
+ */
+function isAllowedExternalUrl(rawUrl) {
+  if (typeof rawUrl !== "string" || rawUrl === "") return false;
+  let parsed;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    return false; // Unresolvable/relative — never openExternal it.
+  }
+  return ALLOWED_EXTERNAL_SCHEMES.has(parsed.protocol.toLowerCase());
+}
+
+/**
+ * True when `targetUrl` is the document already loaded, differing only by
+ * fragment or query — i.e. an in-app anchor, not a navigation away.
+ *
+ * @param {string} targetUrl
+ * @param {string} currentUrl
+ * @returns {boolean}
+ */
+function isInAppNavigation(targetUrl, currentUrl) {
+  if (typeof targetUrl !== "string" || typeof currentUrl !== "string") return false;
+  let target;
+  let current;
+  try {
+    target = new URL(targetUrl);
+    current = new URL(currentUrl);
+  } catch {
+    return false;
+  }
+  return (
+    target.protocol === current.protocol &&
+    target.host === current.host &&
+    target.pathname === current.pathname
+  );
+}
+
+/**
+ * A one-line, user-facing reason a URL was refused. Never silently dropped —
+ * the caller logs this and shows it, so a blocked click is explainable.
+ *
+ * @param {string} rawUrl
+ * @returns {string}
+ */
+function describeBlockedUrl(rawUrl) {
+  const shown = typeof rawUrl === "string" && rawUrl ? rawUrl : String(rawUrl);
+  let scheme = "no scheme";
+  try {
+    scheme = new URL(shown).protocol.replace(/:$/, "");
+  } catch {
+    /* keep "no scheme" */
+  }
+  return (
+    `GAIA refused to open "${shown.slice(0, 300)}" (${scheme}). ` +
+    "Only http, https and mailto links open outside the app — a link that " +
+    "resolves to a local file or network share is never launched."
+  );
+}
+
+module.exports = {
+  ALLOWED_EXTERNAL_SCHEMES,
+  isAllowedExternalUrl,
+  isInAppNavigation,
+  describeBlockedUrl,
+};

package/services/notification-service.cjs

@@ -330,36 +330,58 @@ class NotificationService extends EventEmitter {
     // Listen for agent notifications via the EventEmitter
     this.agentProcessManager.on(
       "agent-notification",
-      (agentId, params) => {
+      this._guardListener("agent-notification", (agentId, params) => {
         this.handleAgentNotification(agentId, params);
-      }
+      })
     );
 
     // Agent crash → generate error notification
-    this.agentProcessManager.on("status-change", (payload) => {
-      if (payload.status === "stopped" && payload.detail) {
-        // Only notify on unexpected stops (crashes)
-        this.handleAgentNotification(payload.agentId, {
-          type: "error",
-          title: "Agent Crashed",
-          message: payload.detail || `Agent ${payload.agentId} stopped unexpectedly`,
-        });
-      }
-    });
+    this.agentProcessManager.on(
+      "status-change",
+      this._guardListener("status-change", (payload) => {
+        if (payload.status === "stopped" && payload.detail) {
+          // Only notify on unexpected stops (crashes)
+          this.handleAgentNotification(payload.agentId, {
+            type: "error",
+            title: "Agent Crashed",
+            message: payload.detail || `Agent ${payload.agentId} stopped unexpectedly`,
+          });
+        }
+      })
+    );
 
     // Crash limit reached → generate error notification
     this.agentProcessManager.on(
       "agent-crash-limit",
-      (agentId, crashCount) => {
+      this._guardListener("agent-crash-limit", (agentId, crashCount) => {
         this.handleAgentNotification(agentId, {
           type: "error",
           title: "Agent Crash Limit Reached",
           message: `Agent ${agentId} crashed ${crashCount} times — automatic restart disabled`,
         });
-      }
+      })
     );
   }
 
+  /**
+   * Wrap an EventEmitter listener so a throw inside it is logged instead of
+   * escaping as an uncaughtException — these fire from a child-process `exit`
+   * handler, where an unhandled throw takes the whole app down with the
+   * backend and sidecars still running.
+   */
+  _guardListener(eventName, fn) {
+    return (...args) => {
+      try {
+        fn(...args);
+      } catch (err) {
+        console.error(
+          `[notif] Listener for "${eventName}" threw and was contained: ` +
+            `${err && err.stack ? err.stack : err}`
+        );
+      }
+    };
+  }
+
   // ── Private: Persistence ─────────────────────────────────────────────
 
   _loadNotifications() {

package/services/tray-manager.cjs

@@ -33,8 +33,47 @@ const DEFAULT_CONFIG = {
     startMinimized: false,
     startOnLogin: false,
   },
+  agents: {},
 };
 
+const AGENT_LOG_LEVELS = ["debug", "info", "warn", "error"];
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Validate an `agents` section (id → AgentConfig), dropping unknown keys. */
+function validateAgents(agents, where) {
+  if (!isPlainObject(agents)) {
+    throw new TypeError(`${where}: agents must be an object`);
+  }
+  const out = {};
+  for (const [id, cfg] of Object.entries(agents)) {
+    if (id.trim() === "") {
+      throw new TypeError(`${where}: agent id must be a non-empty string`);
+    }
+    if (!isPlainObject(cfg)) {
+      throw new TypeError(`${where}: agents.${id} must be an object`);
+    }
+    for (const key of ["autoStart", "restartOnCrash"]) {
+      if (typeof cfg[key] !== "boolean") {
+        throw new TypeError(`${where}: agents.${id}.${key} must be a boolean`);
+      }
+    }
+    if (!AGENT_LOG_LEVELS.includes(cfg.logLevel)) {
+      throw new TypeError(
+        `${where}: agents.${id}.logLevel must be one of ${AGENT_LOG_LEVELS.join(", ")}`
+      );
+    }
+    out[id] = {
+      autoStart: cfg.autoStart,
+      restartOnCrash: cfg.restartOnCrash,
+      logLevel: cfg.logLevel,
+    };
+  }
+  return out;
+}
+
 // ── TrayManager ──────────────────────────────────────────────────────────
 
 class TrayManager {
@@ -53,6 +92,9 @@ class TrayManager {
     /** @type {Electron.Tray | null} */
     this.tray = null;
 
+    /** @type {number} Unread notifications reflected in the tooltip/badge. */
+    this._notificationCount = 0;
+
     /** @type {object} */
     this.config = this._loadConfig();
 
@@ -69,7 +111,8 @@ class TrayManager {
     if (this.tray) return;
 
     this.tray = new Tray(this._icon);
-    this.tray.setToolTip("GAIA");
+    // Re-apply any count that arrived before the tray existed.
+    this.setNotificationCount(this._notificationCount);
 
     // Single-click: show/focus window
     this.tray.on("click", () => this._showWindow());
@@ -95,6 +138,45 @@ class TrayManager {
     this._rebuildContextMenu();
   }
 
+  /**
+   * Reflect the unread-notification count in the tray tooltip (and the dock /
+   * launcher badge where the platform has one).
+   *
+   * @param {number} count Unread notifications; negative/NaN is treated as 0.
+   */
+  setNotificationCount(count) {
+    const unread =
+      typeof count === "number" && Number.isFinite(count) && count > 0
+        ? Math.floor(count)
+        : 0;
+    if (unread !== this._notificationCount) {
+      console.log(`[tray] Unread notifications: ${unread}`);
+    }
+    this._notificationCount = unread;
+
+    const trayAlive =
+      this.tray &&
+      !(typeof this.tray.isDestroyed === "function" && this.tray.isDestroyed());
+    if (trayAlive) {
+      this.tray.setToolTip(
+        unread > 0
+          ? `GAIA — ${unread} unread notification${unread === 1 ? "" : "s"}`
+          : "GAIA"
+      );
+    }
+
+    // Dock (macOS) / Unity launcher (Linux) badge. Windows has no
+    // app.setBadgeCount equivalent — the tooltip above is the badge there.
+    if (process.platform !== "win32" && typeof app.setBadgeCount === "function") {
+      app.setBadgeCount(unread);
+    }
+  }
+
+  /** @returns {number} The unread count last passed to setNotificationCount. */
+  get notificationCount() {
+    return this._notificationCount || 0;
+  }
+
   /** @returns {boolean} Whether minimize-to-tray is enabled. */
   get minimizeToTray() {
     return this.config.tray.minimizeToTray;
@@ -184,32 +266,63 @@ class TrayManager {
   // ── Private: Config persistence ──────────────────────────────────────
 
   _loadConfig() {
+    let loaded = null;
     try {
       if (fs.existsSync(CONFIG_PATH)) {
-        const raw = fs.readFileSync(CONFIG_PATH, "utf8");
-        const loaded = JSON.parse(raw);
-        return {
-          ...DEFAULT_CONFIG,
-          ...loaded,
-          tray: { ...DEFAULT_CONFIG.tray, ...(loaded.tray || {}) },
-        };
+        loaded = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
       }
     } catch (err) {
       console.warn("[tray] Could not load tray config:", err.message);
     }
-    return { ...DEFAULT_CONFIG };
-  }
+    if (!isPlainObject(loaded)) {
+      return { ...DEFAULT_CONFIG, tray: { ...DEFAULT_CONFIG.tray }, agents: {} };
+    }
 
-  _saveConfig() {
+    // Scoped to the agents section: one bad entry must not cost the user their
+    // tray settings, which the next save would then overwrite with defaults.
+    let agents = {};
     try {
-      if (!fs.existsSync(GAIA_DIR)) {
-        fs.mkdirSync(GAIA_DIR, { recursive: true });
+      agents = validateAgents(loaded.agents ?? {}, CONFIG_PATH);
+    } catch (err) {
+      console.error(
+        `[tray] Ignoring invalid agents section in ${CONFIG_PATH}: ${err.message}. ` +
+          "Agent settings fall back to defaults; tray settings are kept."
+      );
+    }
+
+    // Repair on read: the pre-validation handler could store wrong-typed
+    // values, and set-config re-reads stored keys the payload omits.
+    const stored = isPlainObject(loaded.tray) ? loaded.tray : {};
+    const tray = { ...DEFAULT_CONFIG.tray };
+    for (const key of Object.keys(DEFAULT_CONFIG.tray)) {
+      if (typeof stored[key] === "boolean") {
+        tray[key] = stored[key];
+      } else if (key in stored) {
+        console.warn(
+          `[tray] Ignoring non-boolean ${key} in ${CONFIG_PATH}; using default`
+        );
       }
-      fs.writeFileSync(CONFIG_PATH, JSON.stringify(this.config, null, 2), "utf8");
-      console.log("[tray] Config saved to", CONFIG_PATH);
+    }
+
+    return {
+      ...DEFAULT_CONFIG,
+      ...loaded,
+      tray,
+      agents,
+    };
+  }
+
+  _saveConfig(config) {
+    try {
+      fs.mkdirSync(GAIA_DIR, { recursive: true });
+      fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), "utf8");
     } catch (err) {
-      console.error("[tray] Could not save tray config:", err.message);
+      throw new Error(
+        `Could not save settings to ${CONFIG_PATH}: ${err.message}. ` +
+          "Check that the file and its folder are writable."
+      );
     }
+    console.log("[tray] Config saved to", CONFIG_PATH);
   }
 
   // ── Private: IPC handlers ────────────────────────────────────────────
@@ -220,15 +333,42 @@ class TrayManager {
     });
 
     ipcMain.handle("tray:set-config", (_event, cfg) => {
-      if (cfg.tray) {
-        this.config.tray = { ...this.config.tray, ...cfg.tray };
+      if (!isPlainObject(cfg)) {
+        throw new TypeError("tray:set-config expects an object payload");
+      }
+      if (cfg.tray !== undefined && !isPlainObject(cfg.tray)) {
+        throw new TypeError("tray:set-config: tray must be an object");
+      }
+      const agents =
+        cfg.agents === undefined
+          ? null
+          : validateAgents(cfg.agents, "tray:set-config");
+
+      let tray = null;
+      if (cfg.tray !== undefined) {
+        tray = {};
+        for (const key of Object.keys(DEFAULT_CONFIG.tray)) {
+          const value = key in cfg.tray ? cfg.tray[key] : this.config.tray[key];
+          if (typeof value !== "boolean") {
+            throw new TypeError(`tray:set-config: tray.${key} must be a boolean`);
+          }
+          tray[key] = value;
+        }
       }
 
-      this._saveConfig();
-
-      // Apply login-item setting if changed
-      if (cfg.tray && "startOnLogin" in cfg.tray) {
-        this._applyLoginItemSetting(cfg.tray.startOnLogin);
+      if (tray === null && agents === null) {
+        return this.config;
+      }
+      const next = {
+        ...this.config,
+        tray: tray ?? this.config.tray,
+        agents: agents ? { ...this.config.agents, ...agents } : this.config.agents,
+      };
+      this._saveConfig(next);
+      this.config = next;
+
+      if (tray !== null && "startOnLogin" in cfg.tray) {
+        this._applyLoginItemSetting(tray.startOnLogin);
       }
 
       return this.config;