@abot-ai/runtime 1.4.0 → 1.5.0

package/dist/src/web-ui/app/components/system-host/macos-connection-actions.js

@@ -0,0 +1,92 @@
+import {
+  hasLocalMacSetup,
+  hasMacSetup,
+  macConnectionCommand,
+  macRepairConnectionCommand,
+  readMacPairingReceipt,
+} from "./macos-setup.js";
+
+export function createMacConnectionActions({
+  state,
+  connectLocal,
+  createPairing,
+  getRuntimeOrigin,
+  canInstallOnPlatform,
+  beginRequest,
+  finishRequest,
+  isCurrentResponse,
+  getSurfaceRevision,
+  isVisible,
+  load,
+}) {
+  function canApplyMacResponse(operation, surface) {
+    if (!isCurrentResponse(operation)) return false;
+    if (surface !== getSurfaceRevision()) return false;
+    return isVisible();
+  }
+  function macActionFailure(error) {
+    if (typeof error?.message !== "string")
+      return "Mac connection could not be completed. Try again.";
+    return (
+      error.message.trim().slice(0, 500) ||
+      "Mac connection could not be completed. Try again."
+    );
+  }
+  async function connectMac() {
+    if (typeof connectLocal !== "function") return false;
+    if (!canInstallOnPlatform("macos")) return false;
+    if (!hasLocalMacSetup(state.snapshot)) return false;
+    const operation = beginRequest();
+    const surface = getSurfaceRevision();
+    let connected = false;
+    try {
+      await connectLocal();
+      if (!canApplyMacResponse(operation, surface)) return false;
+      state.manualMac = null;
+      state.downloaded = null;
+      state.message = "Mac connection started. Checking readiness…";
+      connected = true;
+    } catch (error) {
+      if (canApplyMacResponse(operation, surface))
+        state.actionError = macActionFailure(error);
+    } finally {
+      finishRequest(operation);
+    }
+    if (!connected) return false;
+    return load();
+  }
+  async function pairMac() {
+    if (!canInstallOnPlatform("macos")) return false;
+    if (!hasMacSetup(state.snapshot)) return false;
+    if (hasLocalMacSetup(state.snapshot)) return false;
+    const repair = state.snapshot.paired === true;
+    if (!repair && typeof createPairing !== "function") return false;
+    state.manualMac = null;
+    const operation = beginRequest();
+    const surface = getSurfaceRevision();
+    try {
+      const pairing = repair
+        ? {}
+        : readMacPairingReceipt(await createPairing());
+      if (!canApplyMacResponse(operation, surface)) return false;
+      const instructions = repair
+        ? macRepairConnectionCommand()
+        : macConnectionCommand(getRuntimeOrigin());
+      state.manualMac = {
+        ...instructions,
+        ...pairing,
+        repair,
+      };
+      state.downloaded = null;
+      state.message = "";
+      return true;
+    } catch (error) {
+      if (canApplyMacResponse(operation, surface))
+        state.actionError = macActionFailure(error);
+      return false;
+    } finally {
+      finishRequest(operation);
+    }
+  }
+  return { connectMac, pairMac };
+}

package/dist/src/web-ui/app/components/system-host/macos-permission-dialog.js

@@ -0,0 +1,95 @@
+/** An explanation before the existing collection action can ask macOS for consent. */
+export function createMacPermissionDialog({
+  container,
+  copyText = (value) => navigator.clipboard.writeText(value),
+}) {
+  const documentRoot = container.ownerDocument;
+  const dialog = documentRoot.createElement("dialog");
+  dialog.className = "mac-permission-dialog";
+  dialog.setAttribute("aria-labelledby", "macPermissionTitle");
+  dialog.setAttribute("aria-describedby", "macPermissionDescription");
+  dialog.innerHTML = `<div class="mac-permission-content">
+    <div class="mac-permission-top"><span class="mac-permission-icon" aria-hidden="true">⌘</span>
+      <button type="button" class="mac-permission-close" data-mac-permission-cancel aria-label="Cancel and close">×</button></div>
+    <p class="mac-permission-eyebrow">Computer access · macOS</p>
+    <h2 id="macPermissionTitle" tabindex="-1">Before you enable Spark</h2>
+    <p class="mac-permission-lead">macOS will show <strong>“node”</strong>.</p>
+    <p id="macPermissionDescription" class="mac-permission-description">That is the executable used by ABot’s computer companion. Check the path below to identify ABot’s copy before allowing access.</p>
+    <div class="mac-permission-identity">
+      <p>ABot’s companion executable on the connected Mac</p>
+      <div class="mac-permission-path"><code data-mac-permission-path tabindex="0"></code>
+        <button type="button" data-mac-permission-copy aria-label="Copy companion executable path">Copy path</button></div>
+      <p class="mac-permission-path-note">Other apps also use node. Allow the entry for this exact path.</p>
+    </div>
+    <p class="mac-permission-usage">Spark uses Accessibility to read activity that your apps make accessible. <strong>Spark collects only while collection is enabled.</strong></p>
+    <details class="mac-permission-details"><summary>What you are allowing</summary>
+      <p><strong>Accessibility is an operating-system permission.</strong> It can allow this executable to read accessible app content and interact with your computer.</p>
+      <p>Turning Spark collection off stops collection, but keeps the macOS permission. Revoke it anytime in <strong>System Settings → Privacy &amp; Security → Accessibility</strong>.</p>
+      <p>Some app content may remain unavailable. Screen capture or other actions may need separate permission. An update may require your consent again.</p>
+    </details>
+    <p class="mac-permission-feedback" data-mac-permission-feedback role="status" aria-live="polite"></p>
+  </div>
+  <div class="mac-permission-footer"><span>Next: macOS permission step, if needed</span>
+    <div><button type="button" data-mac-permission-cancel>Cancel</button>
+      <button type="button" class="mac-permission-continue" data-mac-permission-continue>Continue →</button></div>
+  </div>`;
+  (documentRoot.body ?? container).append(dialog);
+  const pathElement = dialog.querySelector("[data-mac-permission-path]");
+  const feedback = dialog.querySelector("[data-mac-permission-feedback]");
+  const copy = dialog.querySelector("[data-mac-permission-copy]");
+  let pending;
+  let returnFocus;
+
+  function finish(approved) {
+    if (!pending) return;
+    const resolve = pending;
+    pending = undefined;
+    dialog.close();
+    if (returnFocus?.isConnected && !returnFocus.closest("[hidden]"))
+      returnFocus.focus();
+    resolve(approved);
+  }
+  for (const button of dialog.querySelectorAll("[data-mac-permission-cancel]"))
+    button.addEventListener("click", () => finish(false));
+  dialog
+    .querySelector("[data-mac-permission-continue]")
+    .addEventListener("click", () => finish(true));
+  dialog.addEventListener("cancel", (event) => {
+    event.preventDefault();
+    finish(false);
+  });
+  dialog.addEventListener("close", () => finish(false));
+  copy.addEventListener("click", async () => {
+    try {
+      await copyText(pathElement.textContent);
+      feedback.textContent = "Companion path copied.";
+      copy.textContent = "Copied";
+    } catch {
+      feedback.textContent =
+        "Copy is unavailable. Select the path and use your copy shortcut.";
+      pathElement.focus();
+    }
+  });
+  return {
+    confirm(path) {
+      if (pending) return Promise.resolve(false);
+      pathElement.textContent = path;
+      feedback.textContent = "";
+      copy.textContent = "Copy path";
+      dialog.querySelector("details").open = false;
+      returnFocus = documentRoot.activeElement;
+      return new Promise((resolve) => {
+        pending = resolve;
+        dialog.showModal();
+        dialog.querySelector("h2").focus();
+      });
+    },
+    cancel() {
+      finish(false);
+    },
+    dispose() {
+      finish(false);
+      dialog.remove();
+    },
+  };
+}

package/dist/src/web-ui/app/components/system-host/macos-permissions.js

@@ -0,0 +1,36 @@
+import { escapeHtml } from "../../lib/text-format.js";
+
+function hasManagedMacPermissionRuntime(version) {
+  if (!Number.isInteger(version)) return false;
+  return version >= 6;
+}
+
+export function macCompanionPermissionPath(snapshot) {
+  if (!snapshot?.paired) return "";
+  if (snapshot.identity?.os !== "macos") return "";
+  if (!hasManagedMacPermissionRuntime(snapshot.companion?.installedVersion))
+    return "";
+  const home = snapshot.identity.homeDir;
+  const prefix =
+    typeof home === "string" && home.startsWith("/")
+      ? home.replace(/\/+$/u, "")
+      : "~";
+  return prefix + "/.abot/host-companion/runtime/node";
+}
+
+/** The managed companion keeps its macOS permission subject at one private path. */
+export function renderMacPermissionGuide(snapshot) {
+  if (!snapshot?.paired) return "";
+  if (snapshot.identity?.os !== "macos") return "";
+  const version = snapshot.companion?.installedVersion;
+  if (!hasManagedMacPermissionRuntime(version))
+    return '<p class="system-host-note">Update the Mac connection to set up Spark permissions for its dedicated companion runtime.</p>';
+  return `<details class="system-host-manual" data-system-host-mac-permissions>
+    <summary>macOS permissions for Spark</summary>
+    <p>The connection is ready independently of macOS permission to read activity. Start collection in Spark to request Accessibility access.</p>
+    <p>On the connected Mac, open System Settings → Privacy &amp; Security → Accessibility (Device Control &amp; Data Access on some macOS versions). Use the add button, press Command–Shift–G and select this companion executable:</p>
+    <pre><code>${escapeHtml(macCompanionPermissionPath(snapshot))}</code></pre>
+    <p>macOS may display it as node. Check its path before enabling access. This private runtime belongs to the ABot companion and is reused at sign-in.</p>
+    <p>Spark checks for approval for up to two minutes without collecting content. After that, stop and start collection to check again. A runtime replacement can require consent again.</p>
+  </details>`;
+}

package/dist/src/web-ui/app/components/system-host/macos-setup.js

@@ -0,0 +1,91 @@
+import { escapeHtml } from "../../lib/text-format.js";
+
+export function hasMacSetup(snapshot) {
+  if (snapshot?.readiness?.ready === true) return false;
+  return snapshot?.readiness?.platforms?.includes("macos") === true;
+}
+
+export function hasLocalMacSetup(snapshot) {
+  if (!hasMacSetup(snapshot)) return false;
+  return snapshot.readiness.localSetupAvailable === true;
+}
+
+function hasLoopbackRuntimeOrigin(url) {
+  if (!["http:", "https:"].includes(url.protocol)) return false;
+  if (url.hostname === "localhost") return true;
+  if (url.hostname.endsWith(".localhost")) return true;
+  if (url.hostname === "[::1]") return true;
+  return /^127(?:\.\d{1,3}){3}$/u.test(url.hostname);
+}
+
+export function macConnectionCommand(origin) {
+  try {
+    const url = new URL(origin);
+    if (hasLoopbackRuntimeOrigin(url))
+      return {
+        command: `abot host connect --url '${url.origin.replaceAll("'", "'\\''")}'`,
+        needsForwarding: false,
+      };
+  } catch {
+    // A remote or unavailable browser origin cannot identify a local forwarded port.
+  }
+  return {
+    command: "abot host connect --url http://localhost:<forwarded-port>",
+    needsForwarding: true,
+  };
+}
+
+export function macRepairConnectionCommand() {
+  return {
+    command: "abot host status\nabot host connect --url '<saved-runtime-url>'",
+    needsForwarding: false,
+  };
+}
+
+export function readMacPairingReceipt(receipt) {
+  if (!/^[A-Za-z0-9_-]{43}$/u.test(receipt?.code ?? ""))
+    throw new Error("The pairing response was invalid. Try again.");
+  if (!Number.isFinite(Date.parse(receipt.expiresAt)))
+    throw new Error("The pairing response was invalid. Try again.");
+  return { code: receipt.code, expiresAt: receipt.expiresAt };
+}
+
+export function renderMacSetupAction(snapshot, disabled) {
+  if (!hasMacSetup(snapshot)) return "";
+  const local = hasLocalMacSetup(snapshot);
+  const localLabel = snapshot.paired
+    ? "Repair Mac connection"
+    : "Connect this Mac";
+  const label = local ? localLabel : "Connect a Mac";
+  const action = local ? "local" : "manual";
+  return `<button type="button" data-system-host-mac="${action}" ${disabled ? "disabled" : ""}>${label}</button>`;
+}
+
+export function renderMacSetupNotice(snapshot) {
+  if (!hasMacSetup(snapshot)) return "";
+  if (!hasLocalMacSetup(snapshot))
+    return "<p>On the Mac you want to connect, use an installed ABot CLI in Terminal. The connection starts now and at future sign-ins for that Mac user.</p>";
+  const name = snapshot.readiness.localComputerName;
+  const computer = name ? ` <strong>${escapeHtml(name)}</strong>` : " this Mac";
+  return `<p>Connect${computer} using its installed ABot. This enables the companion now and at future sign-ins for the user running ABot. Allow the macOS permissions requested for desktop access.</p>`;
+}
+
+export function renderMacConnectionInstructions(manual) {
+  if (!manual) return "";
+  const expired =
+    manual.expiresAt && Date.parse(manual.expiresAt) <= Date.now();
+  const forwarding = manual.needsForwarding
+    ? "<p>Use an existing local port forward on the Mac to this Runtime. Replace &lt;forwarded-port&gt; with its localhost port. A remote Runtime address cannot be used directly.</p>"
+    : "";
+  const pairing =
+    manual.code && !expired
+      ? `<p>When Terminal asks, paste this one-time code:</p><pre><code>${escapeHtml(manual.code)}</code></pre><p>Code expires at ${escapeHtml(new Date(manual.expiresAt).toLocaleTimeString())}.</p>`
+      : "";
+  const repair = manual.repair
+    ? "<p>On the Mac already paired with ABot, run <code>abot host status</code> first. Replace &lt;saved-runtime-url&gt; in the connect command with the exact saved <code>url</code> shown by status, keeping the quotes. This resumes the saved connection. If this is a different Mac, return to the paired Mac or explicitly unpair before creating a new connection.</p>"
+    : "";
+  const expiration = expired
+    ? "<p>This pairing code expired. Choose Connect a Mac again for a fresh code.</p>"
+    : "";
+  return `<div class="system-host-manual"><p>Open Terminal on the Mac with ABot installed and run:</p><pre><code>${escapeHtml(manual.command)}</code></pre>${forwarding}${repair}${pairing}${expiration}<p>Return here and wait for Ready after connecting.</p></div>`;
+}

package/dist/src/web-ui/app/components/system-host/manager.js

@@ -1,14 +1,19 @@
 import { downloadHostSetup } from "./download.js";
 import { hostSetupIsReady, renderSystemHostConnection } from "./rendering.js";
 import { createSystemHostVisibility } from "./visibility.js";
+import { createMacConnectionActions } from "./macos-connection-actions.js";
 
 export function createSystemHostConnectionManager({
   loadConnection,
   downloadSetup,
+  connectLocal,
+  createPairing,
+  getRuntimeOrigin = () => globalThis.location?.origin,
   revokeConnection,
   supportsConnection = () => true,
   saveDownload = downloadHostSetup,
   documentRoot = globalThis.document,
+  compact = false,
   onChange = () => {},
   schedulePoll = (callback, delay) => setTimeout(callback, delay),
   cancelPoll = (timer) => clearTimeout(timer),
@@ -23,6 +28,8 @@ export function createSystemHostConnectionManager({
     message: "",
     statusUnavailable: false,
     downloaded: null,
+    manualMac: null,
+    managementOpen: false,
   };
   let revision = 0;
   let pollTimer;
@@ -36,14 +43,40 @@ export function createSystemHostConnectionManager({
     isActive: () => state.active,
     onChange: visibilityChanged,
   });
+  const mac = createMacConnectionActions({
+    state,
+    connectLocal,
+    createPairing,
+    getRuntimeOrigin,
+    canInstallOnPlatform,
+    beginRequest,
+    finishRequest,
+    isCurrentResponse,
+    load,
+    getSurfaceRevision: () => surfaceRevision,
+    isVisible: () => visibility.isVisible(),
+  });
   function markup() {
     return renderSystemHostConnection({
       ...state,
       error: state.error || state.actionError,
       supported: supportsConnection(),
+      compact,
     });
   }
   function afterPaint(root = state.root) {
+    const management = root?.querySelector("[data-system-host-management]");
+    management?.addEventListener("toggle", () => {
+      if (management !== state.root?.querySelector("[data-system-host-management]")) return;
+      state.managementOpen = management.open;
+      lastNotification = markup();
+    });
+    root
+      ?.querySelector('[data-system-host-mac="local"]')
+      ?.addEventListener("click", () => void mac.connectMac());
+    root
+      ?.querySelector('[data-system-host-mac="manual"]')
+      ?.addEventListener("click", () => void mac.pairMac());
     root
       ?.querySelector("[data-system-host-refresh]")
       ?.addEventListener("click", () => void load());
@@ -90,6 +123,8 @@ export function createSystemHostConnectionManager({
     if (!visible && wasVisible) surfaceRevision += 1;
     wasVisible = visible;
     if (!visible) {
+      state.manualMac = null;
+      notify();
       stopPolling();
       return;
     }
@@ -131,6 +166,7 @@ export function createSystemHostConnectionManager({
       state.statusUnavailable = false;
       state.error = "";
       if (hostSetupIsReady(snapshot)) {
+        state.manualMac = null;
         state.downloaded = null;
         state.message = "";
         state.actionError = "";
@@ -161,7 +197,9 @@ export function createSystemHostConnectionManager({
     return message || "Setup could not be downloaded. Try again.";
   }
   async function install(platform) {
+    if (platform === "macos") return false;
     if (!canInstallOnPlatform(platform)) return false;
+    state.manualMac = null;
     const operation = beginRequest();
     const surface = surfaceRevision;
     try {
@@ -195,8 +233,9 @@ export function createSystemHostConnectionManager({
       if (!isCurrentResponse(operation)) return false;
       state.snapshot = snapshot;
       state.downloaded = null;
+      state.manualMac = null;
       state.statusUnavailable = false;
-      state.message = "Computer access revoked.";
+      state.message = "Computer unpaired.";
       return true;
     } catch {
       if (isCurrentResponse(operation))
@@ -219,20 +258,28 @@ export function createSystemHostConnectionManager({
     state.snapshot = null;
     state.statusUnavailable = false;
     state.downloaded = null;
+    state.manualMac = null;
     state.error = "";
     state.actionError = "";
     state.message = "";
+    state.managementOpen = false;
     stopPolling();
     wasVisible = false;
+    render();
   }
   return {
     state,
     load,
     install,
+    ...mac,
     revoke,
     markup,
     afterPaint,
     setActive,
+    openManagement() {
+      state.managementOpen = true;
+      notify();
+    },
     reset,
     mount(root) {
       state.root = root;

package/dist/src/web-ui/app/components/system-host/rendering.js

@@ -1,22 +1,40 @@
 import { escapeHtml } from "../../lib/text-format.js";
+import { renderMacPermissionGuide } from "./macos-permissions.js";
+import {
+  renderMacSetupAction,
+  renderMacSetupNotice,
+  renderMacConnectionInstructions,
+} from "./macos-setup.js";
 
 export function hostSetupIsReady(snapshot) {
   if (snapshot?.readiness) return snapshot.readiness.ready === true;
   return snapshot?.connected === true;
 }
+function hostCompanionUpdateRequired(snapshot) {
+  return snapshot?.readiness?.companionUpdateRequired === true;
+}
+function pairedCompanionIsOffline(snapshot) {
+  if (!snapshot?.paired) return false;
+  return snapshot.connected === false;
+}
 function connectionStatus(snapshot, statusUnavailable, busy) {
   if (statusUnavailable) return "Status unavailable";
   if (busy || !snapshot) return "Checking this computer…";
   if (hostSetupIsReady(snapshot)) return "Ready";
-  if (snapshot.paired) return "Paired · offline";
+  if (pairedCompanionIsOffline(snapshot)) return "Paired · offline";
+  if (hostCompanionUpdateRequired(snapshot)) return "Update needed";
+  if (snapshot.connected) return "Computer access unavailable";
+  if (snapshot?.readiness?.directAccessReady) return "Direct access available";
   return "Setup needed";
 }
+function hostAccessIsAvailable(snapshot, supported, statusUnavailable, busy) {
+  if (!supported || statusUnavailable || busy) return false;
+  return hostSetupIsReady(snapshot);
+}
 function readyDescription(snapshot) {
-  if (snapshot?.readiness?.route === "native")
-    return "ABot can already use this computer. No extra installation is needed.";
-  if (snapshot?.readiness?.route === "wsl_interop")
-    return "Windows access through WSL is ready. No extra installation is needed.";
-  return "Your computer is connected and ready.";
+  if (["native", "wsl_interop"].includes(snapshot?.readiness?.route))
+    return "Direct commands are available. No extra installation is needed for direct commands.";
+  return "Your computer is connected for system tools and ABot Spark. Background collection starts only when you enable it.";
 }
 function renderIdentity(snapshot) {
   const identity = snapshot?.identity || {};
@@ -37,23 +55,33 @@ function renderIdentity(snapshot) {
 function renderSetupActions(snapshot, disabled) {
   if (hostSetupIsReady(snapshot)) return "";
   const platforms = snapshot?.readiness?.platforms || [];
-  const labels = {
+  const setupLabels = {
     windows: "Set up Windows access",
-    macos: "Set up Mac access",
+    linux: "Set up Linux access",
   };
-  return platforms
-    .filter((platform) => Object.hasOwn(labels, platform))
-    .map(
-      (platform) =>
-        `<button type="button" data-system-host-install="${platform}" ${disabled ? "disabled" : ""}>${labels[platform]}</button>`,
-    )
-    .join("");
+  const updateLabels = {
+    windows: "Update Windows connection",
+    linux: "Update Linux connection",
+  };
+  const labels = hostCompanionUpdateRequired(snapshot)
+    ? updateLabels
+    : setupLabels;
+  return (
+    renderMacSetupAction(snapshot, disabled) +
+    platforms
+      .filter((platform) => Object.hasOwn(labels, platform))
+      .map(
+        (platform) =>
+          `<button type="button" data-system-host-install="${platform}" ${disabled ? "disabled" : ""}>${labels[platform]}</button>`,
+      )
+      .join("")
+  );
 }
 function hasInstallablePlatform(snapshot) {
   if (hostSetupIsReady(snapshot)) return false;
   return (
     snapshot?.readiness?.platforms?.some((platform) =>
-      ["windows", "macos"].includes(platform),
+      ["windows", "linux"].includes(platform),
     ) === true
   );
 }
@@ -61,7 +89,24 @@ function setupDownloadHasExpired(downloaded) {
   if (!downloaded?.expiresAt) return false;
   return Date.parse(downloaded.expiresAt) <= Date.now();
 }
-export function renderSystemHostConnection({
+export function renderSystemHostConnection(input) {
+  const content = renderConnectionDetails(input);
+  if (!input.compact) return content;
+  const { snapshot, supported, statusUnavailable, busy, managementOpen } = input;
+  const available = hostAccessIsAvailable(snapshot, supported, statusUnavailable, busy);
+  const status = supported ? connectionStatus(snapshot, statusUnavailable, busy) : "Unavailable";
+  return `<details class="system-host-compact" data-system-host-management ${managementOpen ? "open" : ""}>
+    <summary class="system-host-summary">
+      <span class="system-host-summary-title">Computer access</span>
+      <span class="system-host-status" role="status" data-tone="${available ? "ready" : "unavailable"}"><span class="system-host-status-dot" aria-hidden="true"></span>${escapeHtml(status)}</span>
+      <span class="system-host-summary-name">${escapeHtml(snapshot?.identity?.name || "")}</span>
+      <span class="system-host-summary-action" aria-hidden="true"><span>⌄</span></span>
+    </summary>
+    <div class="system-host-management-body">${content}</div>
+  </details>`;
+}
+
+function renderConnectionDetails({
   snapshot,
   supported,
   busy,
@@ -69,20 +114,31 @@ export function renderSystemHostConnection({
   message,
   statusUnavailable,
   downloaded,
+  manualMac,
 }) {
   const ready = hostSetupIsReady(snapshot);
+  const available = hostAccessIsAvailable(
+    snapshot,
+    supported,
+    statusUnavailable,
+    busy,
+  );
   const restart = snapshot?.readiness?.restartRequired === true;
   return `<section class="system-host-panel" aria-label="Connected computer" aria-busy="${busy ? "true" : "false"}">
-    <div class="system-host-heading"><div><h2>Computer access</h2><p>Use applications and system commands on your computer.</p></div><button type="button" data-system-host-refresh ${busy || !supported ? "disabled" : ""}>Refresh status</button></div>
-    <p class="system-host-note">Shared by all environments in this ABot installation. Your selected tools and ASK, Full or Full+ mode still apply.</p>
-    <p class="system-host-status" role="status">${supported ? connectionStatus(snapshot, statusUnavailable, busy) : "Computer access setup requires the local Runtime backend."}</p>
+    <div class="system-host-heading"><div><h2>Computer access</h2><p>One connection for computer tools and ABot Spark.</p></div><button type="button" data-system-host-refresh ${busy || !supported ? "disabled" : ""}>Refresh status</button></div>
+    <p class="system-host-note">Shared by all environments and compatible plugins in this ABot installation. Tool approvals and ABot Spark collection are controlled separately.</p>
+    <p class="system-host-status" role="status" data-tone="${available ? "ready" : "unavailable"}"><span class="system-host-status-dot" aria-hidden="true"></span><span>${supported ? connectionStatus(snapshot, statusUnavailable, busy) : "Computer access setup requires the local Runtime backend."}</span></p>
     ${ready && !statusUnavailable && !busy ? `<p>${readyDescription(snapshot)}</p>` : ""}
     ${renderIdentity(snapshot)}
+    ${supported ? renderMacPermissionGuide(snapshot) : ""}
+    ${supported ? renderMacSetupNotice(snapshot) : ""}
+    ${supported ? renderMacConnectionInstructions(manualMac) : ""}
     ${!ready && snapshot?.readiness?.message ? `<p class="system-host-note">${escapeHtml(snapshot.readiness.message)}</p>` : ""}
-    ${hasInstallablePlatform(snapshot) && supported ? "<p>Download setup for the computer hosting ABot, then open the downloaded file. It installs what is needed and connects automatically. Follow any permission prompts shown by your operating system.</p>" : ""}
+    ${hasInstallablePlatform(snapshot) && supported ? "<p>Download setup for the computer hosting ABot, then open the downloaded file. It checks prerequisites and connects automatically. Follow any permission prompts shown by your operating system.</p>" : ""}
     ${restart ? '<p class="system-host-restart" role="note">Opening the setup file enables Windows access and automatically restarts the selected WSL distribution. This interrupts its services and conversations. Finish active work before opening the setup file.</p>' : ""}
     ${downloaded ? `<div class="system-host-download"><p><strong>Downloaded:</strong> ${escapeHtml(downloaded.filename)}</p><p>${setupDownloadHasExpired(downloaded) ? "Setup download expired. Download setup again." : "Open this file to continue. A download alone does not mean access is ready."}</p>${downloaded.expiresAt && !setupDownloadHasExpired(downloaded) ? `<p class="system-host-note">Open before ${escapeHtml(new Date(downloaded.expiresAt).toLocaleTimeString())}.</p>` : ""}</div>` : ""}
     <div class="${error ? "error-text" : "system-host-note"}" role="${error ? "alert" : "status"}" aria-live="polite">${escapeHtml(error || message || "")}</div>
-    <div class="system-host-actions">${supported ? renderSetupActions(snapshot, busy) : ""}${snapshot?.paired ? `<button type="button" data-system-host-revoke ${busy ? "disabled" : ""}>Disconnect computer</button>` : ""}</div>
+    ${snapshot?.paired ? '<p class="system-host-note">Unpairing disconnects this companion. To reconnect, run Computer access setup again. Saved insights are kept.</p>' : ""}
+    <div class="system-host-actions">${supported ? renderSetupActions(snapshot, busy) : ""}${snapshot?.paired ? `<button type="button" data-system-host-revoke ${busy ? "disabled" : ""}>Unpair computer</button>` : ""}</div>
   </section>`;
 }

package/dist/src/web-ui/app/components/system-host/setup-notice.js

@@ -1,6 +1,6 @@
 import { createSystemHostVisibility } from "./visibility.js";
 
-function needsComputerSetup(state) {
+export function needsComputerSetup(state) {
   if (!state || state.busy || state.statusUnavailable) return false;
   const snapshot = state.snapshot;
   const readiness = snapshot?.readiness;
@@ -9,7 +9,7 @@ function needsComputerSetup(state) {
   if (!["container", "wsl"].includes(readiness.environment)) return false;
   if (!Array.isArray(readiness.platforms)) return false;
   return readiness.platforms.some((platform) =>
-    ["windows", "macos"].includes(platform),
+    ["windows", "macos", "linux"].includes(platform),
   );
 }
 

package/dist/src/web-ui/app/components/tool-approval-card.js

@@ -21,20 +21,22 @@ export function createToolApprovalCard({
 
   const header = documentRoot.createElement("div");
   header.className = "approval-message-header";
-  const label = documentRoot.createElement("span");
-  label.className = "approval-message-label";
-  label.textContent = "Approval required";
   const title = documentRoot.createElement("strong");
   title.className = "approval-message-title";
-  title.textContent = `Allow ${toolLabel} to run?`;
-  header.append(label, title);
+  title.textContent = toolLabel;
+  header.appendChild(title);
 
   const detail = documentRoot.createElement("p");
   detail.className = "approval-message-detail";
   detail.dir = "auto";
   detail.textContent =
     textOf(event?.summary) || "The runtime is waiting for your decision.";
-  bubble.append(header, detail);
+  const explanation = documentRoot.createElement("details");
+  explanation.className = "approval-message-explanation";
+  const explanationLabel = documentRoot.createElement("summary");
+  explanationLabel.textContent = "Action details";
+  explanation.append(explanationLabel, detail);
+  bubble.append(header, explanation);
 
   const evidence = createConversationToolEvidence(
     { ...event?.toolActivity, executed: false },