@amd-gaia/agent-ui 0.21.2 → 0.23.0

package/services/backend-installer.cjs

@@ -77,25 +77,27 @@ const INSTALL_RETRY_BACKOFF_MS = 3000;
 // `curl | sh` path is retained only as an unpackaged-dev fallback so
 // contributors running from source keep working.
 //
-// When bumping uv, update BOTH:
+// When bumping uv, update:
 //   - .github/workflows/build-installers.yml (tarball .tar.gz SHA256 — archive)
-//   - BUNDLED_UV_SHA256 below (extracted ELF binary SHA256)
-// These are two different digests: the workflow verifies the downloaded
-// archive against upstream's published .sha256, then extracts the `uv` binary
-// which is what `ensureUv()` hashes at runtime.
+//   - BUNDLED_UV_SHA256 below (extracted binary SHA256, linux-x64/win-x64 only)
 //
-// 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.
+// IMPORTANT: per-platform verification strategy differs:
+//   - linux-x64 / win-x64: BUNDLED_UV_SHA256 pins the raw extracted-binary
+//     digest (no post-build modification) — deterministic across CI runs.
+//   - mac-arm64: NOT pinned here. electron-builder code-signs the bundled uv
+//     during packaging (ad-hoc `identity=-` when no Developer ID cert is
+//     configured, which is every CI build today), and ad-hoc codesign output
+//     depends on the codesign/Xcode toolchain baked into the GitHub-hosted
+//     `macos-latest` runner image — which floats and is NOT reproducible
+//     across CI runs (observed: macos-15-arm64 vs macos-26-arm64 images
+//     produced two different digests for byte-identical source). A fixed
+//     SHA256 pin is therefore not deterministic on macOS and would fail
+//     ~half of CI runs and brick first-launch on user machines whenever the
+//     runner image rolls. Instead, ensureUv() and the dmg-structural-smoke
+//     test both run `codesign --verify --strict` against the bundled binary
+//     — this validates the on-disk signature is intact/untampered without
+//     depending on the exact signing bytes, and still fails loud on
+//     corruption or an actually-invalid signature.
 const BUNDLED_UV_VERSION = "0.5.14";
 const BUNDLED_UV_SHA256 = {
   "linux-x64": "0e05d828b5708e8a927724124db3746396afddad6273c47283d7c562dc795bd6",
@@ -103,9 +105,12 @@ const BUNDLED_UV_SHA256 = {
   // 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",
+  // mac-arm64: intentionally absent. See the comment block above — the
+  // post-codesign digest is not deterministic across CI runner images, so
+  // mac-arm64 is verified via codesignVerify() (identity/signature validity)
+  // instead of a fixed SHA256 pin. bundledUvPlatformKey() still returns
+  // "mac-arm64"; callers must not treat a missing entry here as "unpinned
+  // platform" for darwin — see ensureUv()/installBundledUv().
 };
 
 const MANAGED_UV_DIR = path.join(GAIA_HOME, "bin");
@@ -640,7 +645,8 @@ function _extraCaCertificates() {
   try {
     return [fs.readFileSync(file, "utf8")];
   } catch (err) {
-    log(`Could not read NODE_EXTRA_CA_CERTS (${file}): ${err.message}`);
+    // err.message already names the offending path — don't re-log the env value.
+    log(`Could not read NODE_EXTRA_CA_CERTS: ${err.message}`);
     return [];
   }
 }
@@ -720,7 +726,10 @@ function _probeViaProxy(target, proxy, ca, finish, setSock) {
   try {
     proxyUrl = new URL(proxy);
   } catch {
-    finish({ ok: false, kind: "connectivity", message: `${target.href}: invalid proxy URL "${proxy}"` });
+    // HTTPS_PROXY/HTTP_PROXY may embed credentials (http://user:pass@host) —
+    // strip the userinfo before the value reaches the install log.
+    const redacted = proxy.replace(/^(\w+:\/\/)[^@/]*@/, "$1***@");
+    finish({ ok: false, kind: "connectivity", message: `${target.href}: invalid proxy URL "${redacted}"` });
     return;
   }
   const headers = {};
@@ -924,6 +933,27 @@ function sha256File(filePath) {
   });
 }
 
+/**
+ * Verify a macOS binary's code signature is structurally intact via
+ * `codesign --verify --strict`. Used in place of a fixed SHA256 pin for
+ * mac-arm64 (see the BUNDLED_UV_SHA256 comment) — ad-hoc-signed binaries
+ * (identity=-, which is every CI build today) pass this check, but a
+ * corrupted, tampered, or actually-unsigned binary fails it. This does NOT
+ * depend on the specific bytes any given codesign/Xcode toolchain produces,
+ * so it is stable across GitHub-hosted runner image rollovers where a fixed
+ * digest pin is not.
+ *
+ * @param {string} binPath
+ * @returns {{ ok: boolean, output: string }}
+ */
+function codesignVerify(binPath) {
+  const result = spawnSync("codesign", ["--verify", "--strict", binPath], {
+    encoding: "utf8",
+  });
+  const output = `${result.stdout || ""}${result.stderr || ""}`.trim();
+  return { ok: result.status === 0, output };
+}
+
 /**
  * Resolve the bundled uv binary path inside the Electron resources dir.
  * Returns null if this isn't an Electron-packaged runtime (no
@@ -945,15 +975,22 @@ function findBundledUvResource() {
 }
 
 /**
- * Atomically install the bundled uv into ~/.gaia/bin/uv after verifying
- * its SHA256 against BUNDLED_UV_SHA256. Returns the installed path.
+ * Atomically install the bundled uv into ~/.gaia/bin/uv after verifying it.
+ * Returns the installed path.
  *
- * Writes to `uv.tmp-<pid>-<rand>` with mode 0o700, verifies hash,
- * `chmod +x`, then `fs.rename()` (atomic on same filesystem).
+ * Verification strategy differs by platform (see the BUNDLED_UV_SHA256
+ * comment): mac-arm64 uses `codesign --verify --strict` (darwin only —
+ * post-codesign SHA256 is not deterministic across CI runner images);
+ * linux-x64 / win-x64 use the SHA256 pin in BUNDLED_UV_SHA256, which IS
+ * deterministic for those platforms (no post-build re-signing).
+ *
+ * Writes to `uv.tmp-<pid>-<rand>` with mode 0o700, verifies, `chmod +x`,
+ * then `fs.rename()` (atomic on same filesystem).
  */
 async function installBundledUv(sourcePath, platformKey) {
+  const isDarwin = platformKey === "mac-arm64";
   const expected = BUNDLED_UV_SHA256[platformKey];
-  if (!expected || expected.startsWith("<")) {
+  if (!isDarwin && (!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.
@@ -989,18 +1026,39 @@ async function installBundledUv(sourcePath, platformKey) {
     rs.pipe(ws);
   });
 
-  let actual;
-  try {
-    actual = await sha256File(tmpPath);
-  } catch (err) {
-    try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
-    throw new InstallError(
-      `Could not hash copied uv binary: ${err.message}`,
-      { stage: STAGES.ENSURE_UV }
-    );
-  }
+  if (isDarwin) {
+    // chmod BEFORE codesign --verify: codesign needs the execute bit to
+    // resolve the binary's designated requirement on some toolchains.
+    try {
+      fs.chmodSync(tmpPath, 0o700);
+    } catch (err) {
+      log(`Warning: chmod on tmp uv failed: ${err.message}`);
+    }
+    const { ok, output } = codesignVerify(tmpPath);
+    if (!ok) {
+      try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
+      throw new InstallError(
+        `Bundled uv failed code signature verification (codesign --verify --strict): ${output || "no output"}`,
+        {
+          stage: STAGES.ENSURE_UV,
+          suggestion:
+            "The AppImage/installer may be corrupt. Re-download from https://amd-gaia.ai and try again.",
+        }
+      );
+    }
+    log("Bundled uv passed codesign --verify --strict");
+  } else {
+    let actual;
+    try {
+      actual = await sha256File(tmpPath);
+    } catch (err) {
+      try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
+      throw new InstallError(
+        `Could not hash copied uv binary: ${err.message}`,
+        { stage: STAGES.ENSURE_UV }
+      );
+    }
 
-  if (expected) {
     if (actual !== expected) {
       try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
       throw new InstallError(
@@ -1012,14 +1070,12 @@ async function installBundledUv(sourcePath, platformKey) {
         }
       );
     }
-  } else {
-    log("No expected SHA registered for bundled uv; installed binary will not be verified locally.");
-  }
 
-  try {
-    if (!IS_WINDOWS) fs.chmodSync(tmpPath, 0o700);
-  } catch (err) {
-    log(`Warning: chmod on tmp uv failed: ${err.message}`);
+    try {
+      if (!IS_WINDOWS) fs.chmodSync(tmpPath, 0o700);
+    } catch (err) {
+      log(`Warning: chmod on tmp uv failed: ${err.message}`);
+    }
   }
 
   try {
@@ -1057,9 +1113,11 @@ function addManagedBinToPath() {
 
 /**
  * Ensure `uv` is available. Preference order (per issue #782 / T3):
- *   1. Managed copy at ~/.gaia/bin/uv with matching SHA256 (warm-install fast path).
+ *   1. Managed copy at ~/.gaia/bin/uv already verified (warm-install fast path):
+ *      SHA256 pin on linux-x64/win-x64, `codesign --verify --strict` on mac-arm64.
  *   2. Bundled binary in process.resourcesPath/vendor/uv/<platform>/uv:
- *      copy atomically to ~/.gaia/bin/uv with SHA256 verification.
+ *      copy atomically to ~/.gaia/bin/uv with the same platform-appropriate
+ *      verification.
  *   3. DEV-ONLY fallback (app.isPackaged === false OR no resourcesPath):
  *      the original `curl | sh` from astral.sh. Not a shipped-user path.
  *   4. System `uv` on PATH (last resort — unverified version).
@@ -1071,10 +1129,20 @@ async function ensureUv({ onProgress, isPackaged } = {}) {
   report(STAGES.ENSURE_UV, 0, "Checking uv (Python package manager)");
 
   const platformKey = bundledUvPlatformKey();
+  const isDarwin = platformKey === "mac-arm64";
   const expectedSha = platformKey ? BUNDLED_UV_SHA256[platformKey] : null;
 
-  // Fast path: warm install already on disk with correct hash.
-  if (expectedSha && fs.existsSync(MANAGED_UV_BIN)) {
+  // Fast path: warm install already on disk and still passes verification.
+  if (isDarwin && fs.existsSync(MANAGED_UV_BIN)) {
+    const { ok, output } = codesignVerify(MANAGED_UV_BIN);
+    if (ok) {
+      log(`Managed uv at ${MANAGED_UV_BIN} passed codesign --verify --strict — reusing`);
+      addManagedBinToPath();
+      report(STAGES.ENSURE_UV, 100, "uv ready (cached)");
+      return;
+    }
+    log(`Managed uv failed codesign verification (${output || "no output"}) — replacing`);
+  } else if (expectedSha && fs.existsSync(MANAGED_UV_BIN)) {
     try {
       const actual = await sha256File(MANAGED_UV_BIN);
       if (actual === expectedSha) {
@@ -1097,22 +1165,36 @@ async function ensureUv({ onProgress, isPackaged } = {}) {
     report(STAGES.ENSURE_UV, 30, "Installing bundled uv");
     log(`Using bundled uv from ${bundled}`);
 
-    // 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(
-        `Bundled uv resource SHA256 mismatch (expected ${expectedSha}, got ${srcHash}).`,
-        {
-          stage: STAGES.ENSURE_UV,
-          suggestion:
-            "The installer appears to be corrupt. Re-download GAIA from https://amd-gaia.ai and try again.",
-        }
-      );
+    // Verify the source resource before copying — catches installer
+    // corruption before we touch the user's home. mac-arm64 uses
+    // codesign --verify --strict (see BUNDLED_UV_SHA256 comment for why a
+    // fixed digest isn't viable there); other platforms use the SHA256 pin,
+    // which CI must have populated — a missing/placeholder value is a
+    // build-time error, rejected at runtime here.
+    if (isDarwin) {
+      const { ok, output } = codesignVerify(bundled);
+      if (!ok) {
+        throw new InstallError(
+          `Bundled uv resource failed code signature verification (codesign --verify --strict): ${output || "no output"}`,
+          {
+            stage: STAGES.ENSURE_UV,
+            suggestion:
+              "The installer appears to be corrupt. Re-download GAIA from https://amd-gaia.ai and try again.",
+          }
+        );
+      }
+    } else {
+      const srcHash = await sha256File(bundled);
+      if (srcHash !== expectedSha) {
+        throw new InstallError(
+          `Bundled uv resource SHA256 mismatch (expected ${expectedSha}, got ${srcHash}).`,
+          {
+            stage: STAGES.ENSURE_UV,
+            suggestion:
+              "The installer appears to be corrupt. Re-download GAIA from https://amd-gaia.ai and try again.",
+          }
+        );
+      }
     }
     await installBundledUv(bundled, platformKey);
     addManagedBinToPath();
@@ -1452,11 +1534,11 @@ async function installBackend(opts = {}) {
           ? "GAIA retried with the OS certificate store and it still failed. "
           : "") +
         "Ask IT to install the proxy's root CA in your system's trusted certificate store, then relaunch GAIA. " +
-        "See https://amd-gaia.ai/quickstart#cli-install";
+        "See https://amd-gaia.ai/docs/quickstart#cli-install";
     } else {
       suggestion = `Try installing manually:\n  uv pip install ${pipPackage} --python ${
         IS_WINDOWS ? `${GAIA_VENV_DISPLAY}/Scripts/python.exe` : `${GAIA_VENV_DISPLAY}/bin/python`
-      }\nThen restart GAIA. See https://amd-gaia.ai/quickstart#cli-install`;
+      }\nThen restart GAIA. See https://amd-gaia.ai/docs/quickstart#cli-install`;
     }
     throw new InstallError(
       `Failed to install ${pipPackage} (pip exit ${installResult.code}).`,
@@ -1473,7 +1555,7 @@ async function installBackend(opts = {}) {
       `GAIA binary not found at ${GAIA_VENV_DISPLAY} after install.`,
       {
         stage: STAGES.INSTALL_PACKAGE,
-        suggestion: "The package was installed but the gaia executable is missing. Try reinstalling from https://amd-gaia.ai/quickstart",
+        suggestion: "The package was installed but the gaia executable is missing. Try reinstalling from https://amd-gaia.ai/docs/quickstart",
       }
     );
   }
@@ -1710,7 +1792,7 @@ async function ensureBackend(opts = {}) {
         "GAIA backend not found after installation.",
         {
           stage: STAGES.VERIFY,
-          suggestion: "Check the log file and try reinstalling. See https://amd-gaia.ai/quickstart",
+          suggestion: "Check the log file and try reinstalling. See https://amd-gaia.ai/docs/quickstart",
         }
       );
       setState(STATES.FAILED, {

package/services/deep-link.cjs

@@ -0,0 +1,230 @@
+// Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+/**
+ * deep-link.cjs — parse `gaia://` deep links (issue #1725).
+ *
+ * The website's "Open in GAIA" button hands the running app a
+ * `gaia://hub/install/<id>` URL. This module is the pure, Electron-free
+ * parser so it can be unit-tested without a running app; main.cjs owns the
+ * OS protocol registration and dispatch to the install runtime.
+ *
+ * Design: parse errors are THROWN with an actionable message (no silent
+ * fallback). main.cjs surfaces the message to the user instead of dropping a
+ * malformed link on the floor.
+ */
+
+"use strict";
+
+const SCHEME = "gaia:";
+
+// Agent ids as published on the hub: start alphanumeric, then letters, digits,
+// dot, dash, underscore. Bounded length keeps a hostile link from ballooning.
+const AGENT_ID_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+
+/**
+ * Parse a `gaia://` deep link into a structured command.
+ *
+ * Supported form:
+ *   gaia://hub/install/<id>  → { action: "install", agentId }
+ *
+ * @param {string} rawUrl
+ * @returns {{ action: "install", agentId: string }}
+ * @throws {Error} with an actionable message on anything malformed/unsupported
+ */
+function parseDeepLink(rawUrl) {
+  if (typeof rawUrl !== "string" || !rawUrl.trim()) {
+    throw new Error(
+      'Not a GAIA deep link — expected a "gaia://…" URL but got ' +
+        (rawUrl === "" ? "an empty string" : JSON.stringify(rawUrl)) +
+        "."
+    );
+  }
+
+  const trimmed = rawUrl.trim();
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw new Error(`Malformed GAIA deep link "${trimmed}" — not a valid URL.`);
+  }
+
+  if (parsed.protocol !== SCHEME) {
+    throw new Error(
+      `Unsupported URL scheme "${parsed.protocol}" — GAIA deep links must start with "gaia://".`
+    );
+  }
+
+  const host = parsed.hostname;
+  const segments = parsed.pathname.split("/").filter(Boolean);
+
+  if (host === "hub" && segments[0] === "install") {
+    const agentId = segments[1] ? decodeURIComponent(segments[1]) : "";
+    if (!agentId) {
+      throw new Error(
+        `GAIA install link "${trimmed}" is missing an agent id — expected gaia://hub/install/<id>.`
+      );
+    }
+    if (!AGENT_ID_RE.test(agentId)) {
+      throw new Error(
+        `GAIA install link has an invalid agent id "${agentId}" — ids may contain letters, digits, dot, dash and underscore.`
+      );
+    }
+    if (segments.length > 2) {
+      throw new Error(
+        `GAIA install link "${trimmed}" has unexpected extra path segments — expected gaia://hub/install/<id>.`
+      );
+    }
+    return { action: "install", agentId };
+  }
+
+  throw new Error(
+    `Unrecognized GAIA deep link "${trimmed}" — only gaia://hub/install/<id> is supported.`
+  );
+}
+
+/**
+ * Find the first `gaia://` argument in an argv array (Windows/Linux hand the
+ * deep link to the app as a command-line argument). Returns null if absent.
+ *
+ * @param {string[]} argv
+ * @returns {string | null}
+ */
+function extractDeepLinkFromArgv(argv) {
+  if (!Array.isArray(argv)) return null;
+  for (const arg of argv) {
+    if (typeof arg === "string" && arg.startsWith("gaia://")) return arg;
+  }
+  return null;
+}
+
+/**
+ * Act on a parsed deep-link command, with every Electron/runtime effect
+ * injected so the security-critical control flow is unit-testable.
+ *
+ * SECURITY (issue #2196 review): a `gaia://hub/install/<id>` link comes from an
+ * untrusted web page, so the install MUST be gated behind an explicit per-agent
+ * confirmation — the same trust bar the in-app install enforces (#2201). A bare
+ * OS "Open GAIA?" prompt is NOT consent to download and run a specific agent.
+ * If `confirm` does not return true, no install is attempted. `confirm` is
+ * expected to have shown the agent's real catalog tier and permissions first
+ * (see `buildInstallPrompt`), not just its bare id, before resolving true.
+ *
+ * Once confirmed, the install is sent with the trust override set — the
+ * backend's non-verified gate now covers every non-verified agent, not just
+ * native ones, and this out-of-band flow already required its own explicit
+ * per-agent confirmation regardless of tier.
+ *
+ * @param {{ action: string, agentId: string }} command
+ * @param {{
+ *   confirm: (command: {action: string, agentId: string}) => Promise<boolean>,
+ *   installAgent: (agentId: string, opts?: { trustNative?: boolean }) => Promise<any>,
+ *   focusWindow?: () => void,
+ *   logger?: { log?: (...a: any[]) => void, error?: (...a: any[]) => void },
+ * }} deps
+ * @returns {Promise<{ installed: boolean, reason?: string }>}
+ */
+async function dispatchDeepLink(command, deps) {
+  const { confirm, installAgent, focusWindow, logger } = deps || {};
+  const log = (logger && logger.log) || (() => {});
+
+  if (!command || command.action !== "install") {
+    throw new Error(
+      `Unsupported deep-link action "${command && command.action}".`
+    );
+  }
+  if (typeof confirm !== "function" || typeof installAgent !== "function") {
+    throw new Error(
+      "dispatchDeepLink requires confirm() and installAgent() dependencies"
+    );
+  }
+
+  // Surface the app first so the confirmation dialog is clearly GAIA's.
+  if (typeof focusWindow === "function") focusWindow();
+
+  const approved = await confirm(command);
+  if (approved !== true) {
+    log(`[deep-link] User declined install of "${command.agentId}"`);
+    return { installed: false, reason: "declined" };
+  }
+
+  log(`[deep-link] Confirmed — installing "${command.agentId}"`);
+  await installAgent(command.agentId, { trustNative: true });
+  return { installed: true };
+}
+
+// ── Informed trust prompt (security fix: gate ALL non-verified agents) ─────
+//
+// The bare confirm dialog above only ever showed the raw agent id — no tier,
+// no permissions, no AMD-verified indicator. That's per-agent confirmation,
+// but it isn't INFORMED consent. buildInstallPrompt renders the same facts
+// the in-app trust gate (hubLanes.trustGateFor) shows, from a catalog entry,
+// so the caller (main.cjs) can put them in front of the user before they
+// confirm.
+
+const TIER_LABEL = {
+  verified: "AMD Verified",
+  community: "Community",
+  experimental: "Experimental",
+};
+
+/** Normalize a possibly-missing/unknown tier the same way the in-app gate does. */
+function normalizeTier(entry) {
+  const t = entry && entry.security_tier;
+  return t === "verified" || t === "community" ? t : "experimental";
+}
+
+/**
+ * Build the confirmation prompt for a deep-link install from its catalog
+ * entry. Pure — no Electron dependency — so the trust posture is
+ * unit-testable without a running dialog.
+ *
+ * @param {{
+ *   id: string,
+ *   name?: string,
+ *   security_tier?: "verified" | "community" | "experimental",
+ *   permissions?: string[],
+ * } | null | undefined} entry — the agent's catalog entry.
+ * @returns {{ title: string, message: string, detail: string, requiresTrust: boolean }}
+ * @throws {Error} if no entry is given — never build a prompt for an agent
+ *   that couldn't be looked up; the caller must fail closed instead.
+ */
+function buildInstallPrompt(entry) {
+  if (!entry || typeof entry !== "object") {
+    throw new Error(
+      "buildInstallPrompt requires a catalog entry — refuse rather than prompting blind."
+    );
+  }
+
+  const tier = normalizeTier(entry);
+  const requiresTrust = tier !== "verified";
+  const name = entry.name || entry.id;
+  const permissions = Array.isArray(entry.permissions) ? entry.permissions : [];
+
+  const detail = [
+    `Tier: ${TIER_LABEL[tier]}${requiresTrust ? " — NOT AMD-verified" : ""}`,
+    permissions.length
+      ? `Permissions: ${permissions.join(", ")}`
+      : "Permissions: none declared",
+    requiresTrust
+      ? "This agent has not been audited by AMD. Only continue if you trust the " +
+        "publisher — installing downloads and runs third-party code on your machine."
+      : "This agent has been reviewed and verified by AMD.",
+  ].join("\n\n");
+
+  return {
+    title: requiresTrust
+      ? "Install untrusted agent from the web?"
+      : "Install agent from the web?",
+    message: `A website asked GAIA to install "${name}" (${entry.id}).`,
+    detail,
+    requiresTrust,
+  };
+}
+
+module.exports = {
+  parseDeepLink,
+  extractDeepLinkFromArgv,
+  dispatchDeepLink,
+  buildInstallPrompt,
+};