@amd-gaia/agent-ui 0.21.2 → 0.23.0

package/services/agent-seeder.cjs

@@ -16,20 +16,40 @@
  *              - macOS:   <Bundle>.app/Contents/Resources/agents/<id>/
  *              - Linux:   /opt/<AppName>/resources/agents/<id>/
  *   - Target:  path.join(os.homedir(), ".gaia", "agents", "<id>")
- *   - Sentinel: <target>/.seeded  (exists → already seeded → skip)
+ *   - Sentinel: <target>/.seeded  (this copy completed)
+ *   - Marker:  ~/.gaia/seeder/<id>.seeded  ("this machine seeded <id> once";
+ *     EXISTENCE is the signal — content is informational, never parsed for
+ *     decisions. Lives outside ~/.gaia/agents/ so deleting an agent, or the
+ *     whole agents dir, never resurrects it.)
  *
  * Write protocol (atomic-ish, crash-safe):
  *   1. Remove any stale `<id>.partial/` sibling from a prior failed run.
  *   2. Copy source → `<id>.partial/`.
  *   3. `fs.renameSync(<id>.partial, <id>)` — atomic on the same filesystem.
- *   4. Write `<id>/.seeded` last, so a partial seed never looks complete.
+ *   4. Write `<id>/.seeded`, so a partial seed never looks complete.
+ *   5. Write the marker LAST — a crash between 4 and 5 self-heals next
+ *      launch via the marker back-fill (rule 2 below).
+ *
+ * Per-agent decision order (markers read fresh on every call, no caching):
+ *   1. Marker exists → skip, full stop. A deleted agent is never re-seeded;
+ *      a dir the user re-created under the same id is never touched.
+ *   2. No marker, target has `.seeded` → back-fill the marker, skip.
+ *   3. No marker, target exists WITHOUT `.seeded` → user-owned data,
+ *     log a warning, skip, write no marker.
+ *   4. No marker, no target → seed via the write protocol above.
+ *
+ * Recovery: to get a deleted bundled agent back, remove
+ * `~/.gaia/seeder/<id>.seeded` and relaunch.
+ *
+ * Legacy cleanup: the retired `zoo-agent` demo is removed from
+ * ~/.gaia/agents/ when it is provably an unmodified seeded copy — sentinel
+ * present, no file newer than its seededAt (+5s slack), never through a
+ * symlink. Removed ids are reported via the additive `cleaned` array.
  *
  * Behaviour:
- *   - Target `<id>/` exists WITH `.seeded` → already seeded, skip.
- *   - Target `<id>/` exists WITHOUT `.seeded` → treat as user-owned data,
- *     log a warning, and skip (never clobber a hand-authored agent).
- *   - `process.resourcesPath` unset (dev / Jest) or source dir missing →
- *     empty result, no error.
+ *   - `process.resourcesPath` unset (dev / Jest) → empty result, no error,
+ *     no cleanup (never touch the real HOME from dev/test contexts).
+ *   - Source dir missing → legacy cleanup still runs, then empty result.
  *   - Per-agent failures are isolated: they go into `errors[]` but do not
  *     stop the next agent from being seeded.
  *
@@ -53,6 +73,10 @@ function agentsTargetRoot() {
   return path.join(gaiaHome(), "agents");
 }
 
+function seederMarkersDir() {
+  return path.join(gaiaHome(), "seeder");
+}
+
 function logsDir() {
   return path.join(gaiaHome(), "logs");
 }
@@ -124,6 +148,48 @@ function isDirectory(p) {
   }
 }
 
+// ── Marker helpers ───────────────────────────────────────────────────────
+
+/**
+ * Defense-in-depth: an agent id must be a single plain path segment before
+ * it is used in any path.join or marker filename.
+ */
+function isSinglePathSegment(id) {
+  return (
+    typeof id === "string" &&
+    id.length > 0 &&
+    id !== "." &&
+    id !== ".." &&
+    !id.includes("/") &&
+    !id.includes("\\") &&
+    !id.includes(path.sep)
+  );
+}
+
+function markerPath(id) {
+  if (!isSinglePathSegment(id)) {
+    throw new Error(`Invalid agent id for marker path: ${JSON.stringify(id)}`);
+  }
+  return path.join(seederMarkersDir(), `${id}.seeded`);
+}
+
+function hasMarker(id) {
+  return fs.existsSync(markerPath(id));
+}
+
+function writeMarker(id, source) {
+  fs.mkdirSync(seederMarkersDir(), { recursive: true });
+  fs.writeFileSync(
+    markerPath(id),
+    JSON.stringify(
+      { seededAt: new Date().toISOString(), source },
+      null,
+      2
+    ),
+    { encoding: "utf8" }
+  );
+}
+
 // ── Seeding core ─────────────────────────────────────────────────────────
 
 /**
@@ -135,18 +201,42 @@ function isDirectory(p) {
  * Throws only on programmer error. All IO errors are caught and logged.
  */
 function seedOneAgent(sourceDir, targetRoot, id) {
+  if (!isSinglePathSegment(id)) {
+    log("WARN", `Skipping invalid agent id ${JSON.stringify(id)}`);
+    return { status: "skipped" };
+  }
+
   const src = path.join(sourceDir, id);
   const target = path.join(targetRoot, id);
   const partial = path.join(targetRoot, `${id}.partial`);
   const sentinel = path.join(target, ".seeded");
 
-  // Already seeded?
+  // Rule 1: marker wins, full stop — honors deletion and leaves any
+  // user-recreated dir under the same id untouched.
+  if (hasMarker(id)) {
+    log("INFO", `Skipping "${id}" — already seeded once on this machine (marker present)`);
+    return { status: "skipped" };
+  }
+
+  // Rule 2: seeded before markers existed → back-fill the marker.
+  // Runs every launch, so it also heals a crash between sentinel and marker.
   if (fs.existsSync(sentinel)) {
-    log("INFO", `Skipping "${id}" — already seeded (sentinel present)`);
+    try {
+      writeMarker(id, src);
+      log("INFO", `Skipping "${id}" — already seeded (sentinel present); marker back-filled`);
+    } catch (err) {
+      log(
+        "ERROR",
+        `Failed to back-fill marker for "${id}": ${
+          err && err.message ? err.message : err
+        } — will retry next launch`
+      );
+    }
     return { status: "skipped" };
   }
 
-  // Target exists but no sentinel → user-owned data. Do not touch.
+  // Rule 3: target exists but no sentinel → user-owned data. Do not touch,
+  // write no marker.
   if (fs.existsSync(target)) {
     log(
       "WARN",
@@ -176,7 +266,7 @@ function seedOneAgent(sourceDir, targetRoot, id) {
     copyDirRecursive(src, partial);
     fs.renameSync(partial, target);
 
-    // Write sentinel LAST — its presence means "copy completed".
+    // Write sentinel — its presence means "copy completed".
     fs.writeFileSync(
       sentinel,
       JSON.stringify(
@@ -190,6 +280,9 @@ function seedOneAgent(sourceDir, targetRoot, id) {
       { encoding: "utf8" }
     );
 
+    // Marker LAST — a crash here self-heals via the rule-2 back-fill.
+    writeMarker(id, src);
+
     log("INFO", `Seeded "${id}" from ${src} to ${target}`);
     return { status: "seeded" };
   } catch (err) {
@@ -214,15 +307,156 @@ function seedOneAgent(sourceDir, targetRoot, id) {
   }
 }
 
+// ── Legacy cleanup ───────────────────────────────────────────────────────
+
+// Retired bundled ids removed from user machines when provably unmodified.
+const LEGACY_CLEANUP_IDS = ["zoo-agent"];
+
+// Filesystem mtime granularity + copy latency headroom for the
+// modified-since-seed check.
+const MODIFIED_SLACK_MS = 5000;
+
+function listFilesRecursive(dir) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    // __pycache__/*.pyc is regenerated by the registry on every load — it
+    // postdates seededAt but is not a user modification.
+    if (entry.isDirectory() && entry.name === "__pycache__") continue;
+    if (!entry.isDirectory() && entry.name.endsWith(".pyc")) continue;
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...listFilesRecursive(p));
+    } else {
+      out.push(p);
+    }
+  }
+  return out;
+}
+
+/**
+ * Remove retired seeded demo agents (currently `zoo-agent`) from
+ * ~/.gaia/agents/. Deletes ONLY when the dir is provably an unmodified
+ * seeded copy; anything ambiguous is left in place. Failures are logged
+ * and retried on the next launch (the sentinel keys the retry — no marker
+ * is involved, since a retired id can never be re-seeded anyway).
+ *
+ * @returns {string[]} ids actually removed (verified gone from disk).
+ */
+function cleanupLegacyAgents() {
+  const cleaned = [];
+
+  for (const id of LEGACY_CLEANUP_IDS) {
+    const target = path.join(agentsTargetRoot(), id);
+
+    let st;
+    try {
+      st = fs.lstatSync(target);
+    } catch {
+      continue; // not present — nothing to clean
+    }
+
+    // Never rm through a symlink — it would delete the link target.
+    if (st.isSymbolicLink()) {
+      log(
+        "WARN",
+        `Legacy "${id}" at ${target} is a symlink — leaving it untouched`
+      );
+      continue;
+    }
+
+    if (!st.isDirectory()) {
+      log("WARN", `Legacy "${id}" at ${target} is not a directory — leaving it untouched`);
+      continue;
+    }
+
+    // No sentinel → user-authored, not ours to remove.
+    const sentinel = path.join(target, ".seeded");
+    if (!fs.existsSync(sentinel)) {
+      continue;
+    }
+
+    let seededAtMs;
+    try {
+      seededAtMs = Date.parse(
+        JSON.parse(fs.readFileSync(sentinel, "utf8")).seededAt
+      );
+      if (!Number.isFinite(seededAtMs)) {
+        throw new Error("seededAt missing or not a valid timestamp");
+      }
+    } catch (err) {
+      log(
+        "WARN",
+        `Cannot determine seededAt for legacy "${id}" (${
+          err && err.message ? err.message : err
+        }) — treating as user-modified, leaving it untouched`
+      );
+      continue;
+    }
+
+    // Any file newer than the seed time means the user customized it —
+    // it is their work now, never delete it.
+    let modified = false;
+    try {
+      for (const file of listFilesRecursive(target)) {
+        if (fs.lstatSync(file).mtimeMs > seededAtMs + MODIFIED_SLACK_MS) {
+          log(
+            "WARN",
+            `Legacy "${id}" was modified after seeding (${file}) — leaving it untouched`
+          );
+          modified = true;
+          break;
+        }
+      }
+    } catch (err) {
+      log(
+        "WARN",
+        `Cannot inspect legacy "${id}" for modifications (${
+          err && err.message ? err.message : err
+        }) — leaving it untouched`
+      );
+      continue;
+    }
+    if (modified) {
+      continue;
+    }
+
+    try {
+      fs.rmSync(target, { recursive: true, force: true });
+    } catch (err) {
+      log(
+        "ERROR",
+        `Failed to remove legacy "${id}" at ${target}: ${
+          err && err.message ? err.message : err
+        } — will retry next launch`
+      );
+      continue;
+    }
+
+    // Report success only after verifying it is actually gone.
+    if (fs.existsSync(target)) {
+      log(
+        "ERROR",
+        `Legacy "${id}" still present after removal attempt: ${target} — will retry next launch`
+      );
+      continue;
+    }
+
+    log("INFO", `Removed legacy seeded agent "${id}" from ${target}`);
+    cleaned.push(id);
+  }
+
+  return cleaned;
+}
+
 /**
  * Seed all bundled agents found under `<resourcesPath>/agents/`.
  *
  * Idempotent — safe to call on every app launch.
  *
- * @returns {Promise<{seeded: string[], skipped: string[], errors: {id: string, error: Error}[]}>}
+ * @returns {Promise<{seeded: string[], skipped: string[], errors: {id: string, error: Error}[], cleaned: string[]}>}
  */
 async function seedBundledAgents() {
-  const result = { seeded: [], skipped: [], errors: [] };
+  const result = { seeded: [], skipped: [], errors: [], cleaned: [] };
 
   // Guard against dev / test environments where resourcesPath is unset.
   if (!process.resourcesPath) {
@@ -233,6 +467,11 @@ async function seedBundledAgents() {
     return result;
   }
 
+  // Legacy cleanup runs before the missing-source guard: an upgraded
+  // install must shed the retired zoo-agent even if this build ships no
+  // bundled agents.
+  result.cleaned = cleanupLegacyAgents();
+
   const sourceDir = path.join(process.resourcesPath, "agents");
 
   if (!fs.existsSync(sourceDir) || !isDirectory(sourceDir)) {
@@ -284,7 +523,8 @@ async function seedBundledAgents() {
   log(
     "INFO",
     `Seeding complete — seeded=${result.seeded.length} ` +
-      `skipped=${result.skipped.length} errors=${result.errors.length}`
+      `skipped=${result.skipped.length} errors=${result.errors.length} ` +
+      `cleaned=${result.cleaned.length}`
   );
 
   return result;
@@ -295,7 +535,9 @@ module.exports = {
   // Exposed for tests — do not rely on these from production code.
   _internals: {
     seedOneAgent,
+    cleanupLegacyAgents,
     agentsTargetRoot,
+    seederMarkersDir,
     logFilePath,
   },
 };

package/services/auto-updater.cjs

@@ -4,9 +4,19 @@
 /**
  * auto-updater.cjs — GAIA Agent UI auto-update service.
  *
- * Wraps `electron-updater` for the GitHub Releases auto-update flow.
+ * Wraps `electron-updater` against a CONFIGURABLE generic feed (R2-primary —
+ * issue #1724). The forward-update channel URL is resolved at runtime from
+ * `GAIA_UPDATE_FEED_URL` or `feedUrl` in ~/.gaia/update-config.json, and the
+ * app fetches the mutable `latest*.yml` channel pointer from it. When no feed
+ * is configured the updater enters a loud `no-channel` state (no silent
+ * no-op). The actual R2 publish feed + mutable channel pointer is milestone-52
+ * work (#1719); until it lands, point the env var at any generic feed (a local
+ * mock works) to exercise the path.
+ *
  * Implements §4 Layer 3 + §7 Phase F of docs/plans/desktop-installer.mdx.
- * Issue #1336: adds in-app rollback to a specific previous release.
+ * Issue #1336: in-app rollback to a specific previous release still lists and
+ * installs from GitHub Releases (that path is independent of the forward feed
+ * and migrates to R2 with #1719).
  *
  * Behavior:
  *   - First check 10 seconds after `init()` is called (typically from
@@ -51,6 +61,12 @@ const CHECK_INTERVAL_MS = 4 * 60 * 60 * 1000; // Subsequent checks every 4h
 const LOG_PATH = path.join(os.homedir(), ".gaia", "electron-updater.log");
 const UPDATE_CONFIG_PATH = path.join(os.homedir(), ".gaia", "update-config.json");
 
+// Mutable channel pointer name. electron-updater's generic provider fetches
+// `${feedUrl}/${DEFAULT_CHANNEL}.yml` (+ per-platform variants). The Hub Worker
+// re-points this file each release while versioned artifacts stay immutable —
+// that split is the A6/A7 resolution (#1724).
+const DEFAULT_CHANNEL = "latest";
+
 // per_page=100 is the GitHub API max for a single page; we fetch broadly so
 // draft/prerelease/platform filtering still yields a full page of installable
 // releases before the display cap below. >100 releases would need pagination
@@ -72,6 +88,8 @@ const STATES = Object.freeze({
   DOWNLOADED: "downloaded",
   ERROR: "error",
   DISABLED: "disabled",
+  // No forward-update feed configured — loud, actionable, never a silent no-op.
+  NO_CHANNEL: "no-channel",
 });
 
 // ── Module state ─────────────────────────────────────────────────────────────
@@ -93,6 +111,8 @@ let scheduledTimeout = null;
 let initialCheckTimeout = null;
 let ipcHandlersRegistered = false;
 let initialized = false;
+// The resolved forward-update feed URL (generic/R2), or null when unconfigured.
+let forwardFeedUrl = null;
 
 // Lazy-loaded Electron references (populated inside init()).
 let electronApi = null; // { dialog, ipcMain, app }
@@ -147,13 +167,86 @@ function _loadPin() {
  */
 function _savePin(pinnedVersion) {
   fs.mkdirSync(path.dirname(UPDATE_CONFIG_PATH), { recursive: true });
+  // Merge into any existing config so we don't clobber a persisted feedUrl.
+  let existing = {};
+  try {
+    if (fs.existsSync(UPDATE_CONFIG_PATH)) {
+      existing = JSON.parse(fs.readFileSync(UPDATE_CONFIG_PATH, "utf8")) || {};
+    }
+  } catch {
+    existing = {};
+  }
   fs.writeFileSync(
     UPDATE_CONFIG_PATH,
-    JSON.stringify({ pinnedVersion }, null, 2),
+    JSON.stringify({ ...existing, pinnedVersion }, null, 2),
     "utf8"
   );
 }
 
+// ── Forward-update feed resolution (issue #1724) ────────────────────────────────
+
+/**
+ * Resolve the generic forward-update feed URL, or null if none is configured.
+ * Precedence: GAIA_UPDATE_FEED_URL env > feedUrl in update-config.json.
+ */
+function _resolveFeedUrl() {
+  const envUrl = process.env.GAIA_UPDATE_FEED_URL;
+  if (typeof envUrl === "string" && envUrl.trim()) return envUrl.trim();
+  try {
+    if (fs.existsSync(UPDATE_CONFIG_PATH)) {
+      const cfg = JSON.parse(fs.readFileSync(UPDATE_CONFIG_PATH, "utf8"));
+      if (cfg && typeof cfg.feedUrl === "string" && cfg.feedUrl.trim()) {
+        return cfg.feedUrl.trim();
+      }
+    }
+  } catch (err) {
+    log("warn", "Failed to read feedUrl from update-config.json:", err && err.message);
+  }
+  return null;
+}
+
+/**
+ * Point electron-updater at the configured generic (R2) feed + mutable channel.
+ * When nothing is configured, enter the loud NO_CHANNEL state and set no feed —
+ * an unconfigured updater must never silently pretend it's up to date.
+ *
+ * @returns {boolean} true when a feed was applied, false when NO_CHANNEL.
+ */
+function _applyForwardFeed() {
+  if (!autoUpdaterRef) return false;
+  const url = _resolveFeedUrl();
+  if (!url) {
+    forwardFeedUrl = null;
+    setState({
+      status: STATES.NO_CHANNEL,
+      error:
+        "No update channel configured — set GAIA_UPDATE_FEED_URL (or feedUrl " +
+        "in ~/.gaia/update-config.json) to your R2 channel base URL. " +
+        "Auto-update is paused until a feed is configured.",
+    });
+    log("warn", "No update feed configured — auto-update paused (NO_CHANNEL)");
+    return false;
+  }
+  try {
+    autoUpdaterRef.setFeedURL({
+      provider: "generic",
+      url,
+      channel: DEFAULT_CHANNEL,
+    });
+    forwardFeedUrl = url;
+    log("info", `Update feed set (generic): ${url} [channel=${DEFAULT_CHANNEL}]`);
+    return true;
+  } catch (err) {
+    forwardFeedUrl = null;
+    setState({
+      status: STATES.ERROR,
+      error: `Failed to set update feed URL: ${(err && err.message) || String(err)}`,
+    });
+    log("error", "Failed to set feed URL:", err && err.message);
+    return false;
+  }
+}
+
 // ── State management ─────────────────────────────────────────────────────────
 
 function broadcastState() {
@@ -359,8 +452,10 @@ async function installVersion(tag) {
 /**
  * Clear the version pin and resume normal auto-updates.
  *
- * Restores the GitHub provider feed, sets autoDownload=true, and clears
- * allowDowngrade so the next check is the normal forward-only flow.
+ * Restores the configured forward (R2 generic) feed, sets autoDownload=true,
+ * and clears allowDowngrade so the next check is the normal forward-only flow.
+ * If no feed is configured, resume lands in the loud NO_CHANNEL state rather
+ * than silently reverting to a stale rollback feed.
  */
 function clearPin() {
   // A failed clear is non-fatal — worst case the stale pin re-pauses updates
@@ -375,17 +470,9 @@ function clearPin() {
   if (autoUpdaterRef) {
     autoUpdaterRef.autoDownload = true;
     autoUpdaterRef.allowDowngrade = false;
-    // Restore the GitHub provider (overrides any generic/tagged feed set by
-    // installVersion). Owner/repo must match electron-builder.yml publish block.
-    try {
-      autoUpdaterRef.setFeedURL({
-        provider: "github",
-        owner: "amd",
-        repo: "gaia",
-      });
-    } catch (err) {
-      log("warn", "Failed to restore GitHub feed on resume:", err && err.message);
-    }
+    // Restore the forward channel (overrides any generic/tagged rollback feed
+    // set by installVersion). Loud NO_CHANNEL if unconfigured.
+    _applyForwardFeed();
   }
 
   log("info", "Version pin cleared — auto-updates resumed");
@@ -403,6 +490,16 @@ async function checkForUpdates() {
     log("warn", "checkForUpdates called before init — ignoring");
     return;
   }
+  // No forward feed and not pinned → surface the loud NO_CHANNEL state instead
+  // of asking electron-updater to check a feed that doesn't exist. Re-resolve
+  // first so a feed written to config after init() is picked up here.
+  if (!forwardFeedUrl && !state.pinnedVersion) {
+    if (!_applyForwardFeed()) return;
+    // Feed just became available after a no-feed (NO_CHANNEL) start — init()
+    // skipped arming the periodic scheduler, so arm it now or background checks
+    // never resume once the feed goes live.
+    if (!scheduledTimeout) scheduleNextCheck();
+  }
   if (checkInProgress) {
     log("info", "Skipping check — another check is already in progress");
     return;
@@ -691,6 +788,25 @@ function init(mainWindow) {
     log("warn", "Failed to register IPC handlers:", err && err.message);
   }
 
+  // Point the updater at the configured R2 generic feed (#1724). When a pin is
+  // active, installVersion() owns the feed (rollback path), so skip. With no
+  // pin and no feed, _applyForwardFeed enters the loud NO_CHANNEL state and we
+  // don't schedule checks against a nonexistent feed.
+  let feedReady = true;
+  if (!savedPin) {
+    feedReady = _applyForwardFeed();
+  }
+
+  initialized = true;
+
+  if (!feedReady && !savedPin) {
+    log(
+      "info",
+      "Auto-updater initialized without a channel — checks paused until a feed is configured"
+    );
+    return;
+  }
+
   // First check after CHECK_DELAY_MS, then every CHECK_INTERVAL_MS.
   initialCheckTimeout = setTimeout(async () => {
     try {
@@ -701,7 +817,6 @@ function init(mainWindow) {
     scheduleNextCheck();
   }, CHECK_DELAY_MS);
 
-  initialized = true;
   log(
     "info",
     `Auto-updater initialized; first check in ${CHECK_DELAY_MS}ms`

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

@@ -399,7 +399,7 @@ async function showFailureDialog(parentWindow, errorInfo = {}) {
         return "retry";
       case 2: {
         try {
-          await shell.openExternal("https://amd-gaia.ai/quickstart#cli-install");
+          await shell.openExternal("https://amd-gaia.ai/docs/quickstart#cli-install");
         } catch {
           // ignore
         }