@abot-ai/runtime 1.5.0 → 1.6.0

package/dist/src/web-ui/app/components/spark-chat/panel.js

@@ -0,0 +1,109 @@
+const mascot = '<img class="spark-pet" src="/spark-mascot.svg" alt="" aria-hidden="true" draggable="false" />';
+
+export function createSparkChatPanel({ documentRoot = document, launcherAnchor }) {
+  const root = documentRoot.createElement("aside");
+  root.className = "spark-companion";
+  root.hidden = true;
+  root.innerHTML = `
+    <section class="spark-chat-panel" role="dialog" aria-label="ABot SPARK chat" hidden>
+      <header class="spark-chat-header"><button type="button" class="spark-header-mascot" data-spark="mascotButton" aria-label="Minimize SPARK chat" title="Minimize SPARK chat">${mascot}</button><strong>ABot SPARK</strong>
+        <button type="button" data-spark="settingsButton" aria-label="SPARK settings" title="SPARK settings">⚙</button>
+        <button type="button" data-spark="closeButton" aria-label="Minimize SPARK chat" title="Minimize">−</button>
+      </header>
+      <div class="spark-chat-content">
+        <div class="messages-list spark-messages" data-spark="messagesList" role="log" aria-label="SPARK messages" tabindex="0"></div>
+        <button type="button" class="jump-to-latest" data-spark="jumpToLatestButton" hidden>Latest ↓</button>
+      </div>
+      <div class="spark-chat-composer-dock">
+        <div data-spark="composerPlan"></div><div data-spark="composerContextWindow"></div>
+        <form class="spark-compose" data-spark="composerForm">
+          <div class="attachment-preview" data-spark="attachmentPreview"></div>
+          <div class="spark-input-row">
+            <button type="button" class="spark-input-icon" data-spark="attachmentButton" aria-label="Attach a file" title="Attach a file">＋</button>
+            <textarea data-spark="composerInput" rows="1" dir="auto" aria-label="Message SPARK" placeholder="Message SPARK…"></textarea>
+            <button type="button" class="spark-input-icon spark-stop" data-spark="stopButton" aria-label="Stop response" title="Stop response" hidden><span aria-hidden="true">■</span></button>
+            <div class="composer-submit-control" data-spark="composerSubmitControl">
+              <button type="submit" class="send-button" data-spark="sendButton" aria-label="Send"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="m6 11 6-6 6 6M12 5v14" /></svg><span class="sr-only" data-spark="sendButtonLabel">Send</span></button>
+              <button type="button" data-spark="sendNextMenuButton" class="send-next-menu-button" aria-label="More send options" aria-expanded="false" hidden><svg viewBox="0 0 16 16" aria-hidden="true"><path d="m4 6 4 4 4-4" /></svg></button>
+              <div data-spark="sendNextMenu" class="send-next-menu" hidden><button type="button" data-spark="sendNextButton" aria-describedby="spark-send-next-hint">Send next</button><p id="spark-send-next-hint">Wait until this reply is finished.</p></div>
+            </div>
+          </div>
+          <input type="file" data-spark="attachmentInput" hidden multiple>
+        </form>
+        <p class="spark-chat-status" data-spark="messageStatusRegion" role="status" aria-live="polite"></p>
+      </div>
+    </section>
+    <div class="spark-message-notice" hidden role="status" aria-live="polite">
+      <button type="button" data-spark="noticeButton" dir="auto"></button>
+      <button type="button" data-spark="dismissNoticeButton" aria-label="Dismiss message preview">×</button>
+    </div>
+    <button type="button" class="spark-launcher" data-spark="launcherButton" aria-label="Open SPARK chat" aria-expanded="false">${mascot}<span class="spark-unread" data-spark="unreadBadge" hidden></span></button>`;
+  documentRoot.body.append(root);
+  const dom = Object.fromEntries([...root.querySelectorAll("[data-spark]")].map((node) => [node.dataset.spark, node]));
+  const launcherSlot = documentRoot.createElement("div");
+  launcherSlot.className = "spark-rail-launcher";
+  launcherSlot.hidden = true;
+  launcherSlot.append(dom.launcherButton);
+  launcherAnchor?.before(launcherSlot);
+  dom.launcherButton.insertAdjacentHTML("beforeend", '<span class="spark-launcher-label">SPARK</span>');
+  const panel = root.querySelector(".spark-chat-panel");
+  const notice = root.querySelector(".spark-message-notice");
+  const placement = createSparkChatPlacement({ root, launcher: dom.launcherButton, panel, notice, dockAnchor: launcherSlot });
+  dom.launcherButton.title = "Open SPARK · Drag to move · Alt + arrows to move · Alt + Home to return to sidebar";
+  let timer;
+  let previousFocus;
+  let open = false;
+  let onToggle = () => {};
+
+  function setOpen(value, { focus = true } = {}) {
+    if (open === value) return;
+    if (value) previousFocus = documentRoot.activeElement;
+    open = value;
+    panel.hidden = !value;
+    dom.launcherButton.setAttribute("aria-expanded", String(value));
+    if (value) notice.hidden = true;
+    placement.refresh();
+    onToggle(value);
+    if (!focus) return;
+    if (value) dom.messagesList.focus({ preventScroll: true });
+    else (previousFocus?.isConnected ? previousFocus : dom.launcherButton)?.focus({ preventScroll: true });
+  }
+
+  function showNotice(text) {
+    if (open) return;
+    clearTimeout(timer);
+    dom.noticeButton.textContent = text;
+    notice.hidden = false;
+    placement.refresh();
+    timer = setTimeout(() => { notice.hidden = true; }, 7000);
+  }
+  dom.launcherButton.addEventListener("click", () => setOpen(!open));
+  dom.closeButton.addEventListener("click", () => setOpen(false));
+  dom.mascotButton.addEventListener("click", () => setOpen(false));
+  dom.noticeButton.addEventListener("click", () => setOpen(true));
+  dom.dismissNoticeButton.addEventListener("click", () => { notice.hidden = true; });
+  root.addEventListener("keydown", (event) => {
+    if (event.key !== "Escape" || !open) return;
+    if (!dom.sendNextMenu.hidden) return;
+    event.preventDefault(); event.stopPropagation(); setOpen(false);
+  });
+  return {
+    dom, root, panel, isOpen: () => open, setOpen,
+    onToggle(callback) { onToggle = callback; },
+    setAvailable(available) {
+      const availabilityChanged = available !== !root.hidden;
+      root.hidden = !available; launcherSlot.hidden = !available; dom.launcherButton.hidden = !available;
+      if (!available) setOpen(false, { focus: false });
+      if (availabilityChanged) placement.refresh();
+    },
+    resetPosition: placement.reset,
+    showNotice,
+    hideNotice() { clearTimeout(timer); notice.hidden = true; },
+    setUnread(count) {
+      dom.unreadBadge.hidden = !count;
+      dom.unreadBadge.textContent = String(count);
+      dom.launcherButton.setAttribute("aria-label", count ? `Open SPARK chat, ${count} unread messages` : "Open SPARK chat");
+    },
+  };
+}
+import { createSparkChatPlacement } from "./placement.js";

package/dist/src/web-ui/app/components/spark-chat/placement.js

@@ -0,0 +1,198 @@
+import { createSparkPlacementMotion } from "./motion.js";
+
+const storageKey = "abot.spark.launcher.position.v1";
+const margin = 12;
+const dragThreshold = 5;
+const positionGrid = 16;
+
+function readBrowserStorage(windowRoot) {
+  try { return windowRoot.localStorage; } catch { return null; }
+}
+
+function readPosition(storage) {
+  try {
+    const value = JSON.parse(storage?.getItem(storageKey) ?? "null");
+    return value && Number.isFinite(value.x) && Number.isFinite(value.y)
+      ? { x: value.x, y: value.y } : null;
+  } catch { return null; }
+}
+
+function clamp(value, size, available) {
+  return Math.max(margin, Math.min(value, Math.max(margin, available - size - margin)));
+}
+
+function popupOpensAbove(desiredHeight, above, below) {
+  if (above >= desiredHeight) return true;
+  if (below >= desiredHeight) return false;
+  return above >= below;
+}
+
+function hasMovedPastDragThreshold(pointer, event) {
+  return Math.hypot(event.clientX - pointer.x, event.clientY - pointer.y) >= dragThreshold;
+}
+
+/** Browser-only launcher placement; conversation and environment state stay untouched. */
+export function createSparkChatPlacement({ root, launcher, panel, notice, dockAnchor, storage, windowRoot = window }) {
+  const positionStorage = storage === undefined ? readBrowserStorage(windowRoot) : storage;
+  let position = readPosition(positionStorage);
+  let pointer = null;
+  let suppressClick = false;
+  let suppressionTimer;
+  const documentRoot = root.ownerDocument;
+  const motion = createSparkPlacementMotion(windowRoot);
+
+  function persist() {
+    try {
+      if (position) positionStorage?.setItem(storageKey, JSON.stringify(position));
+      else positionStorage?.removeItem(storageKey);
+    } catch { /* Placement remains usable when browser storage is unavailable. */ }
+  }
+
+  function placePopup(node, anchor) {
+    Object.assign(node.style, { height: "", maxHeight: "", minHeight: "" });
+    const rect = node.getBoundingClientRect();
+    const width = node.offsetWidth || rect.width || (node === panel ? 390 : 260);
+    const desiredHeight = node.offsetHeight || rect.height || (node === panel ? 560 : 90);
+    const above = Math.max(0, anchor.top - margin * 2);
+    const below = Math.max(0, windowRoot.innerHeight - anchor.bottom - margin * 2);
+    const opensAbove = popupOpensAbove(desiredHeight, above, below);
+    const available = opensAbove ? above : below;
+    const height = Math.min(desiredHeight, available);
+    const top = opensAbove ? anchor.top - margin - height : anchor.bottom + margin;
+    const left = clamp(anchor.left, width, windowRoot.innerWidth);
+    const originX = Math.max(0, Math.min(width, anchor.left + anchor.width / 2 - left));
+    node.style.setProperty?.("--spark-open-shift", opensAbove ? "10px" : "-10px");
+    Object.assign(node.style, {
+      position: "fixed", right: "auto", bottom: "auto",
+      left: `${left}px`, top: `${top}px`,
+      minHeight: "0px", maxHeight: `${available}px`,
+      transformOrigin: `${originX}px ${opensAbove ? "bottom" : "top"}`,
+    });
+    if (node === panel) node.style.height = `${height}px`;
+  }
+
+  function attachLauncher(parent) {
+    if (launcher.parentNode !== parent) parent.append(launcher);
+  }
+
+  function applyFloatingPosition() {
+    attachLauncher(documentRoot.body);
+    launcher.classList.add("spark-launcher-floating");
+    const rect = launcher.getBoundingClientRect();
+    position = { x: clamp(position.x, rect.width || 60, windowRoot.innerWidth), y: clamp(position.y, rect.height || 60, windowRoot.innerHeight) };
+    Object.assign(launcher.style, { position: "fixed", left: `${position.x}px`, top: `${position.y}px` });
+  }
+
+  function applyDockedPosition() {
+    attachLauncher(dockAnchor);
+    launcher.classList.remove("spark-launcher-floating");
+    Object.assign(launcher.style, { position: "", left: "", top: "" });
+  }
+
+  function refresh() {
+    motion.cancel();
+    const hadLauncherFocus = documentRoot.activeElement === launcher;
+    if (position) applyFloatingPosition();
+    else applyDockedPosition();
+    const anchor = launcher.getBoundingClientRect();
+    placePopup(panel, anchor);
+    placePopup(notice, anchor);
+    if (hadLauncherFocus && documentRoot.activeElement !== launcher) launcher.focus({ preventScroll: true });
+  }
+
+  function reset() {
+    pointer = null;
+    position = null;
+    launcher.classList.remove("spark-launcher-dragging");
+    persist(); refresh();
+  }
+
+  function onPointerDown(event) {
+    if (event.button !== 0 || event.isPrimary === false) return;
+    motion.cancel();
+    suppressClick = false;
+    const rect = launcher.getBoundingClientRect();
+    pointer = { id: event.pointerId, x: event.clientX, y: event.clientY, rect, dragging: false };
+  }
+
+  function beginDrag() {
+    pointer.dragging = true;
+    position = { x: pointer.rect.left, y: pointer.rect.top };
+    refresh();
+    const rect = launcher.getBoundingClientRect();
+    pointer.offsetX = (pointer.x - pointer.rect.left) / Math.max(1, pointer.rect.width) * rect.width;
+    pointer.offsetY = (pointer.y - pointer.rect.top) / Math.max(1, pointer.rect.height) * rect.height;
+    launcher.classList.add("spark-launcher-dragging");
+    launcher.setPointerCapture?.(pointer.id);
+  }
+
+  function onPointerMove(event) {
+    if (!pointer || event.pointerId !== pointer.id) return;
+    const pendingDrag = !pointer.dragging;
+    if (pendingDrag && !hasMovedPastDragThreshold(pointer, event)) return;
+    if (pendingDrag) beginDrag();
+    event.preventDefault();
+    position = { x: event.clientX - pointer.offsetX, y: event.clientY - pointer.offsetY };
+    refresh();
+  }
+
+  function finishPointer(event) {
+    if (!pointer || event.pointerId !== pointer.id) return;
+    const dragged = pointer.dragging;
+    if (launcher.hasPointerCapture?.(pointer.id)) launcher.releasePointerCapture(pointer.id);
+    pointer = null;
+    launcher.classList.remove("spark-launcher-dragging");
+    if (!dragged) return;
+    const captured = motion.capture([launcher, panel, notice]);
+    position = { x: Math.round(position.x / positionGrid) * positionGrid, y: Math.round(position.y / positionGrid) * positionGrid };
+    refresh();
+    persist();
+    motion.settle(captured);
+    suppressClick = true;
+    windowRoot.clearTimeout(suppressionTimer);
+    suppressionTimer = windowRoot.setTimeout(() => { suppressClick = false; }, 0);
+  }
+
+  function onClick(event) {
+    if (!suppressClick) return;
+    suppressClick = false;
+    event.preventDefault(); event.stopImmediatePropagation();
+  }
+
+  function onKeyDown(event) {
+    if (!event.altKey || event.ctrlKey || event.metaKey) return;
+    if (event.key === "Home") { event.preventDefault(); reset(); return; }
+    const step = event.shiftKey ? 48 : 16;
+    const movement = { ArrowLeft: [-step, 0], ArrowRight: [step, 0], ArrowUp: [0, -step], ArrowDown: [0, step] }[event.key];
+    if (!movement) return;
+    event.preventDefault();
+    const rect = launcher.getBoundingClientRect();
+    position = { x: rect.left + movement[0], y: rect.top + movement[1] };
+    refresh(); persist();
+  }
+
+  function onResize() { refresh(); if (position) persist(); }
+  launcher.addEventListener("pointerdown", onPointerDown);
+  launcher.addEventListener("click", onClick, true);
+  launcher.addEventListener("keydown", onKeyDown);
+  windowRoot.addEventListener("pointermove", onPointerMove, { passive: false });
+  windowRoot.addEventListener("pointerup", finishPointer);
+  windowRoot.addEventListener("pointercancel", finishPointer);
+  windowRoot.addEventListener("resize", onResize);
+  refresh();
+
+  return {
+    reset, refresh, isDocked: () => position === null,
+    destroy() {
+      motion.destroy();
+      windowRoot.clearTimeout(suppressionTimer);
+      launcher.removeEventListener("pointerdown", onPointerDown);
+      launcher.removeEventListener("click", onClick, true);
+      launcher.removeEventListener("keydown", onKeyDown);
+      windowRoot.removeEventListener("pointermove", onPointerMove);
+      windowRoot.removeEventListener("pointerup", finishPointer);
+      windowRoot.removeEventListener("pointercancel", finishPointer);
+      windowRoot.removeEventListener("resize", onResize);
+    },
+  };
+}

package/dist/src/web-ui/app/components/spark-chat/results.js

@@ -0,0 +1,44 @@
+import { buildConversationToolActions } from "../../lib/tool-activity-model.js";
+import { buildConversationSources } from "../../lib/web-sources.js";
+import { createConversationSources } from "../conversation-sources.js";
+import { createConversationFileAction } from "../conversation-file-action.js";
+
+/** Keep useful results and failures without exposing the session event inspector. */
+export function createSparkChatResults({ documentRoot = document, onOpenFile, canOpenFile }) {
+  const sources = createConversationSources({ documentRoot });
+  const currentActions = new Map();
+  function createNode({ requestId, events = [], streaming = false }) {
+    const scopedEvents = events.filter((event) => event.requestId === requestId);
+    const actions = buildConversationToolActions({ requestId, events: scopedEvents, streaming });
+    currentActions.set(requestId, actions);
+    const node = documentRoot.createElement("div");
+    node.className = "spark-chat-results";
+    for (const action of actions) {
+      const file = createConversationFileAction({
+        documentRoot, requestId, action, onOpenFile, canOpenFile,
+        isCurrentAction: () => currentActions.get(requestId)?.some((current) =>
+          current.id === action.id && JSON.stringify(current.fileReference) === JSON.stringify(action.fileReference)) === true,
+      });
+      if (file) node.appendChild(file);
+      if (!["failed", "incomplete"].includes(action.status) && !action.partial) continue;
+      const warning = documentRoot.createElement("p");
+      warning.className = "spark-result-warning";
+      warning.setAttribute("role", "status");
+      const error = action.received.find((field) => field.label === "Error")?.value;
+      warning.textContent = error || `${action.title}: ${action.partial ? "Only part of the result is available." : action.statusLabel}`;
+      node.appendChild(warning);
+    }
+    for (const event of scopedEvents) {
+      if (event.toolActivity || !["failed", "warning"].includes(event.tone)) continue;
+      const warning = documentRoot.createElement("p");
+      warning.className = "spark-result-warning";
+      warning.setAttribute("role", "status");
+      warning.textContent = event.summary || event.name;
+      node.appendChild(warning);
+    }
+    const references = sources.createNode(buildConversationSources(scopedEvents));
+    if (references) node.appendChild(references);
+    return node.children.length ? node : null;
+  }
+  return { createNode, reset() { currentActions.clear(); } };
+}

package/dist/src/web-ui/app/components/spark-chat/settings.js

@@ -0,0 +1,84 @@
+import { supportsFullPlus } from "../../lib/tool-permission-mode.js";
+
+export function createSparkChatSettings({ root, onSave, onClear, onOpen, onResetPosition, onOpenModelSettings, getAgentMode, onAgentModeChange, getWebConfig, documentRoot = document }) {
+  const card = documentRoot.createElement("section");
+  card.className = "spark-chat-settings";
+  card.setAttribute("aria-label", "SPARK conversation settings");
+  card.innerHTML = `<header class="spark-settings-header"><div><h4>SPARK chat</h4>
+      <p>A familiar place to talk, wherever you are.</p></div><button type="button" data-spark-open>Open chat</button></header>
+    <form class="spark-settings-row spark-chat-settings-controls">
+      <label for="spark-chat-permissions"><strong>Permissions</strong><span>Choose when SPARK asks before taking action.</span></label>
+      <div class="spark-settings-actions"><select id="spark-chat-permissions" data-spark-permissions aria-label="SPARK conversation permissions"><option value="ask">Ask</option><option value="full_access">Full</option><option value="full_plus">FULL+</option></select>
+      <button type="submit" data-spark-save disabled>Save</button></div>
+    </form>
+    <div class="spark-settings-row">
+      <label for="spark-agent-mode"><strong>Thinking mode</strong><span>Choose how deeply SPARK thinks before replying.</span></label>
+      <select id="spark-agent-mode" data-spark-agent-mode aria-label="SPARK thinking mode"><option value="fast">Fast</option><option value="reasoning" selected>Reasoning</option><option value="deep">Deep</option></select>
+    </div>
+    <div class="spark-settings-row"><div><strong>Chat shortcut</strong><p>Drag SPARK wherever feels right. Use Alt + arrow keys to move it.</p></div>
+      <button type="button" data-spark-reset-position>Return to sidebar</button></div>
+    <div class="spark-settings-row"><div><strong>Conversation history</strong><p>Clear messages while keeping SPARK’s memory and permissions.</p></div>
+      <button type="button" data-spark-clear>Clear messages…</button></div>
+    <p class="spark-settings-model-note">Chat shares the model selected under Proactive mode, including “Same as learning” when selected. <button type="button" data-spark-model-settings>Model settings ↗</button></p>
+    <p data-spark-settings-feedback role="status" aria-live="polite"></p>`;
+  root?.querySelector('[data-learning-panel="chat"]')?.prepend(card);
+  const select = card.querySelector("[data-spark-permissions]");
+  const agentModeSelect = card.querySelector("[data-spark-agent-mode]");
+  const save = card.querySelector("[data-spark-save]");
+  const clear = card.querySelector("[data-spark-clear]");
+  const feedback = card.querySelector("[data-spark-settings-feedback]");
+  let saved = "ask";
+  let ready = false;
+  let busy = false;
+  let environmentId;
+  function controls() {
+    select.disabled = busy || !ready;
+    agentModeSelect.disabled = !ready;
+    save.disabled = busy || !ready || select.value === saved;
+    clear.disabled = busy || !ready;
+  }
+  async function perform(action, successMessage = "") {
+    const environment = environmentId;
+    busy = true; feedback.textContent = ""; controls();
+    try {
+      await action();
+      if (environment === environmentId) feedback.textContent = successMessage;
+    }
+    catch (error) {
+      if (environment === environmentId) feedback.textContent = error.code === "spark_chat_busy"
+        ? "Stop the active request or resolve its approval before clearing SPARK chat."
+        : error.message;
+    }
+    finally { if (environment === environmentId) { busy = false; controls(); } }
+  }
+  select.addEventListener("change", controls);
+  agentModeSelect.addEventListener("change", () => onAgentModeChange(agentModeSelect.value));
+  card.querySelector("form").addEventListener("submit", (event) => {
+    event.preventDefault();
+    if (save.disabled) return;
+    const mode = select.value;
+    void perform(() => onSave(mode), "Permissions saved.");
+  });
+  clear.addEventListener("click", () => {
+    if (clear.disabled) return;
+    if (!window.confirm("Clear all messages in the SPARK conversation? Long-term memory and permissions will be kept.")) return;
+    void perform(onClear);
+  });
+  card.querySelector("[data-spark-open]").addEventListener("click", onOpen);
+  card.querySelector("[data-spark-reset-position]").addEventListener("click", () => onResetPosition?.());
+  card.querySelector("[data-spark-model-settings]").addEventListener("click", () => onOpenModelSettings?.());
+  return {
+    render(configuration, nextEnvironmentId) {
+      if (environmentId !== nextEnvironmentId) {
+        environmentId = nextEnvironmentId; busy = false; ready = false; feedback.textContent = "";
+        select.value = configuration?.toolPermissionMode || "ask";
+      }
+      agentModeSelect.value = getAgentMode();
+      const next = configuration?.toolPermissionMode || "ask";
+      if (!ready || select.value === saved || busy) select.value = next;
+      saved = next; ready = Boolean(configuration?.sessionId);
+      select.querySelector('[value="full_plus"]').disabled = !supportsFullPlus(getWebConfig());
+      controls();
+    },
+  };
+}

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

@@ -0,0 +1,83 @@
+import { hasCompletePermissionReceipt, macPermissionScopes } from "./macos-permission-scopes.js";
+
+export function createMacPermissionPreparation({
+  state, requestPermissions, beginRequest, finishRequest, isCurrentResponse,
+  getSurfaceRevision, isVisible, getEnvironmentId,
+}) {
+  function clear() {
+    for (const route of Object.values(macPermissionScopes)) {
+      state[route.receiptKey] = null;
+      state[route.errorKey] = "";
+    }
+  }
+  function reconcile() {
+    for (const route of Object.values(macPermissionScopes)) {
+      if (route.matches(state[route.receiptKey], state.snapshot, getEnvironmentId())) continue;
+      state[route.receiptKey] = null;
+      state[route.errorKey] = "";
+    }
+  }
+  function canPreparePermissions(route) {
+    if (state.busy || state.statusUnavailable) return false;
+    if (!isVisible()) return false;
+    if (typeof requestPermissions !== "function") return false;
+    return route.canCheck(state.snapshot, getEnvironmentId());
+  }
+  function canApplyPermissionResponse(operation, surface, route, binding) {
+    if (!isCurrentResponse(operation)) return false;
+    if (surface !== getSurfaceRevision()) return false;
+    if (!isVisible()) return false;
+    return route.matches(binding, state.snapshot, getEnvironmentId());
+  }
+  function permissionStillRequired(permission, route) {
+    const receipt = state[route.receiptKey];
+    if (!route.matches(receipt, state.snapshot, getEnvironmentId())) return false;
+    if (permission === "screen_recording")
+      return receipt.permissions.screenRecording === "required";
+    if (permission === "accessibility")
+      return receipt.permissions.accessibility === "required";
+    return false;
+  }
+  async function prepare(permission, scope = "companion") {
+    const route = macPermissionScopes[scope];
+    if (!route || !canPreparePermissions(route)) return false;
+    if (permission && !permissionStillRequired(permission, route)) return false;
+    const binding = route.binding(state.snapshot);
+    const surface = getSurfaceRevision();
+    state[route.errorKey] = "";
+    const operation = beginRequest();
+    try {
+      const receipt = await requestPermissions({
+        ...binding,
+        action: permission ? "request" : "check",
+        ...(permission ? { permission } : {}),
+      });
+      if (!canApplyPermissionResponse(operation, surface, route, binding)) return false;
+      if (!route.matches(receipt, state.snapshot, getEnvironmentId()))
+        throw new Error("permission_receipt_binding_invalid");
+      if (receipt.scope !== scope || !hasCompletePermissionReceipt(receipt))
+        throw new Error("permission_receipt_unavailable");
+      state[route.receiptKey] = receipt;
+      return true;
+    } catch {
+      if (!canApplyPermissionResponse(operation, surface, route, binding)) return false;
+      state[route.receiptKey] = null;
+      state[route.errorKey] = "Permission preparation could not complete. Check the executing Mac, its macOS 14 or later version and Swift developer tools. Refresh the connection, then check again.";
+      return false;
+    } finally {
+      finishRequest(operation);
+    }
+  }
+  function afterPaint(root) {
+    for (const [scope, route] of Object.entries(macPermissionScopes)) {
+      root?.querySelector(`[data-${route.selector}-permissions-check]`)
+        ?.addEventListener("click", () => void prepare(undefined, scope));
+      for (const permission of ["screen_recording", "accessibility"])
+        root?.querySelector(`[data-${route.selector}-permission-request="${permission}"]`)
+          ?.addEventListener("click", () => void prepare(permission, scope));
+    }
+  }
+  return { clear, reconcile, afterPaint, checkPermissions: () => prepare(), requestPermission: prepare,
+    checkNativePermissions: () => prepare(undefined, "native_runtime"),
+    requestNativePermission: permission => prepare(permission, "native_runtime") };
+}

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

@@ -0,0 +1,85 @@
+import { escapeHtml } from "../../lib/text-format.js";
+import { canCheckMacPermissions, canCheckNativePermissions, permissionsMatchConnection, permissionsMatchNativeOwner } from "./macos-permission-scopes.js";
+
+function hasNativePermissionSurface(snapshot) {
+  if (snapshot?.identity?.os === "macos") return true;
+  if (!snapshot?.nativePermissions) return false;
+  return snapshot.nativePermissions.reason !== "native_macos_unavailable";
+}
+function permissionSummary(receipt) {
+  if (!receipt) return "not checked";
+  if (receipt.permissions.screenRecording !== "granted") return "action needed";
+  if (receipt.permissions.accessibility !== "granted") return "action needed";
+  return "granted";
+}
+export function macPermissionSummary(snapshot, receipt, nativeReceipt) {
+  const parts = [];
+  if (hasNativePermissionSurface(snapshot)) {
+    const native = snapshot.nativePermissions;
+    const current = permissionsMatchNativeOwner(nativeReceipt, snapshot, native?.environmentId) ? nativeReceipt : null;
+    parts.push(`SYSTEM · ${native?.available ? permissionSummary(current) : "unavailable"}`);
+  }
+  if (snapshot?.identity?.os === "macos" && snapshot.connected) {
+    const current = permissionsMatchConnection(receipt, snapshot) ? receipt : null;
+    parts.push(`Companion · ${canCheckMacPermissions(snapshot) ? permissionSummary(current) : "update needed"}`);
+  }
+  return parts.join(" · ");
+}
+function permissionStatusLabel(status) {
+  if (status === "granted") return "Granted";
+  if (status === "required") return "Required";
+  return "Not checked";
+}
+function permissionRow(label, permission, status, selector, disabled) {
+  return `<div class="system-host-permission-row"><strong>${label}</strong>
+    <span class="system-host-permission-state" data-granted="${status === "granted"}">${permissionStatusLabel(status)}</span>
+    ${status === "required" ? `<button type="button" data-${selector}-permission-request="${permission}" ${disabled ? "disabled" : ""}>Allow ${label}</button>` : ""}</div>`;
+}
+function renderPermissionRoute({ title, description, selector, available, receipt, identity, permissionHelp, error, disabled }) {
+  return `<section class="system-host-permission-route" data-permission-route="${selector}">
+    <div class="system-host-permission-heading"><h4>${title}</h4>
+      ${available ? `<button type="button" data-${selector}-permissions-check ${disabled ? "disabled" : ""}>${receipt ? "Check again" : "Check permissions"}</button>` : ""}</div>
+    <p class="system-host-note">${escapeHtml(description)}</p>
+    ${available ? permissionRow("Screen Recording", "screen_recording", receipt?.permissions.screenRecording, selector, disabled) + permissionRow("Accessibility", "accessibility", receipt?.permissions.accessibility, selector, disabled) : ""}
+    ${identity ? `<p class="system-host-note">${identity}</p>` : ""}
+    ${receipt ? `<code class="system-host-permission-path" dir="ltr">${escapeHtml(receipt.executablePath)}</code><p class="system-host-note">${permissionHelp} After changing access, choose Check again.${receipt.restartMayBeRequired ? " macOS may require a restart before the new access takes effect; finish setup before starting a conversation." : ""}</p>` : ""}
+    ${error ? `<p role="alert" class="error-text">${escapeHtml(error)}</p>` : ""}
+  </section>`;
+}
+function nativeUnavailableDescription(native) {
+  if (!native) return "Update ABot to check the native SYSTEM route. Companion approval does not confirm SYSTEM access.";
+  if (native.reason === "native_macos_unavailable") return "The selected Runtime is not running natively on macOS. Companion permissions do not grant SYSTEM access on another computer.";
+  if (native.reason === "local_browser_required") return "Open ABot’s local Web UI on the Mac running the Runtime to prepare SYSTEM permissions.";
+  if (native.reason === "runtime_not_started") return "Start the selected Runtime, then refresh Computer access to prepare SYSTEM permissions.";
+  return "The selected Runtime cannot report its permission identity. Update or reconnect it, then refresh Computer access.";
+}
+export function renderMacPermissionPreparation({ snapshot, macPermissions, macPermissionError, nativeMacPermissions, nativeMacPermissionError, busy, statusUnavailable }) {
+  const showNative = hasNativePermissionSurface(snapshot);
+  const showCompanion = snapshot?.identity?.os === "macos" && snapshot.paired;
+  if (!showNative && !showCompanion) return "";
+  const native = snapshot.nativePermissions;
+  const nativeAvailable = canCheckNativePermissions(snapshot, native?.environmentId);
+  const nativeReceipt = permissionsMatchNativeOwner(nativeMacPermissions, snapshot, native?.environmentId) ? nativeMacPermissions : null;
+  const companionAvailable = canCheckMacPermissions(snapshot);
+  const companionReceipt = permissionsMatchConnection(macPermissions, snapshot) ? macPermissions : null;
+  const disabled = busy || statusUnavailable;
+  return `<section class="system-host-permissions" data-system-host-mac-permissions aria-label="macOS permission preparation">
+    <h3>Prepare Mac permissions before a conversation</h3>
+    <p class="system-host-note">SYSTEM and the companion can run under different apps or on different computers. Check each route you use. Checks do not capture content or start Spark; Allow buttons explicitly request access.</p>
+    ${showNative ? renderPermissionRoute({
+      title: "SYSTEM · ABot Runtime", selector: "native-mac", available: nativeAvailable, receipt: nativeReceipt,
+      description: nativeAvailable ? "Direct SYSTEM commands use the selected Runtime’s permissions. Allow Terminal or the application shown by macOS. If asked to reopen it, do so before starting a conversation, then check again." : nativeUnavailableDescription(native),
+      identity: nativeAvailable ? `Runtime computer: <strong>${escapeHtml(native.computerName)}</strong> · Environment: <strong>${escapeHtml(native.environmentId)}</strong>` : "",
+      permissionHelp: "This path identifies the Runtime process; macOS may assign its permissions to Terminal or the application that started it.",
+      error: nativeMacPermissionError, disabled,
+    }) : ""}
+    ${showCompanion ? renderPermissionRoute({
+      title: "Computer tools · ABot companion", selector: "mac", available: companionAvailable, receipt: companionReceipt,
+      description: companionAvailable ? "Screen capture and computer control through the connected companion. Spark collection is controlled separately." : "Connect or update the Mac companion to check its permissions here.",
+      identity: `Companion computer: <strong>${escapeHtml(snapshot.identity.name || "Connected Mac")}</strong>`,
+      permissionHelp: "macOS may label the companion “node”. Match this exact path in System Settings → Privacy &amp; Security.",
+      error: macPermissionError, disabled,
+    }) : ""}
+    <p class="system-host-note">These checks cover Screen Recording and Accessibility. Access to protected folders and automation of individual apps can require additional approval.</p>
+  </section>`;
+}