@abot-ai/runtime 1.3.1 → 1.5.0

package/dist/src/web-ui/app/components/schedules/details.js

@@ -1,3 +1,5 @@
+import { toolPermissionModeMeta } from "../../lib/tool-permission-mode.js";
+import { updateLiveRegion } from "../../lib/live-region.js";
 import { escapeHtml } from "../../lib/text-format.js";
 import { scheduleTimeLabel } from "../../lib/schedule-message.js";
 import { scheduleErrorMessage } from "../../lib/schedule-errors.js";
@@ -30,7 +32,7 @@ function runMarkup(run) {
   return `<article class="schedule-run" data-run-id="${escapeHtml(run.id)}">
     <div class="schedule-run-heading"><strong>${scheduleTimeLabel(run.scheduledAt, timeZone)}</strong><span class="schedule-badge" data-state="${escapeHtml(run.status)}">${escapeHtml(run.status)}</span></div>
     <div class="schedule-run-meta">${run.trigger === "manual" ? "Manual run" : "Scheduled run"}${run.startedAt ? ` · Started ${scheduleTimeLabel(run.startedAt, timeZone)}` : ""}${run.finishedAt ? ` · Finished ${scheduleTimeLabel(run.finishedAt, timeZone)}` : ""}</div>
-    <dl class="schedule-run-settings">${fact("Model", run.modelProfileId)}${fact("Mode", run.agentMode)}${fact("Time zone", run.timeZone)}${fact("Job revision", String(run.jobRevision ?? "—"))}</dl>
+    <dl class="schedule-run-settings">${fact("Model", run.modelProfileId)}${fact("Mode", run.agentMode)}${fact("Tool access", toolPermissionModeMeta(run.toolPermissionMode).label)}${fact("Time zone", run.timeZone)}${fact("Job revision", String(run.jobRevision ?? "—"))}</dl>
     ${run.error ? `<p class="schedule-error" dir="auto">${escapeHtml(run.error)}</p>` : ""}
     ${run.resultText ? `<details class="schedule-result" data-disclosure-id="result:${escapeHtml(run.id)}"><summary>View result</summary><pre dir="auto">${escapeHtml(run.resultText)}</pre></details>` : ""}
     <details class="schedule-prompt-disclosure" data-disclosure-id="run:${escapeHtml(run.id)}"><summary>View invocation prompt</summary><pre dir="auto">${escapeHtml(run.prompt)}</pre></details>
@@ -54,14 +56,17 @@ export function renderScheduleDetails({ root, snapshot, actions }) {
   const job = snapshot.jobs.find((item) => item.id === snapshot.selectedId);
   if (!job) {
     root.classList.add("schedule-details-placeholder");
-    root.innerHTML = `<div class="schedule-detail-empty"><span aria-hidden="true">◷</span><h3>${snapshot.selectedId ? "Schedule unavailable" : "Select a schedule"}</h3><p>${snapshot.selectedId ? "This schedule may have been removed with its conversation." : "See when it runs, manage its settings and follow its results here."}</p></div>`;
+    updateLiveRegion(
+      root,
+      `<div class="schedule-detail-empty"><span aria-hidden="true">◷</span><h3>${snapshot.selectedId ? "Schedule unavailable" : "Select a schedule"}</h3><p>${snapshot.selectedId ? "This schedule may have been removed with its conversation." : "See when it runs, manage its settings and follow its results here."}</p></div>`,
+    );
     return;
   }
   root.classList.remove("schedule-details-placeholder");
   const session = snapshot.sessions.find((item) => item.id === job.sessionId);
-  root.innerHTML = `<div class="schedule-detail-heading"><span class="schedule-eyebrow">Scheduled task</span><h3 dir="auto">${escapeHtml(job.title)}</h3><span class="schedule-badge" data-state="${job.state}">${job.state}</span></div>
+  const markup = `<div class="schedule-detail-heading"><span class="schedule-eyebrow">Scheduled task</span><h3 dir="auto">${escapeHtml(job.title)}</h3><span class="schedule-badge" data-state="${job.state}">${job.state}</span></div>
     <div class="schedule-action-row">${actionsMarkup(job, snapshot.mutation)}</div>
-    <dl class="schedule-facts">${fact("Schedule", scheduleDescription(job))}${fact("Next run", scheduleTimeLabel(job.nextRunAt, job.timeZone))}${fact("Time zone", job.timeZone)}${fact("Model", job.modelProfileId)}${fact("Mode", job.agentMode)}${fact("Tool access", "Full")}${fact("Created", scheduleTimeLabel(job.createdAt, job.timeZone))}${fact("Updated", scheduleTimeLabel(job.updatedAt, job.timeZone))}</dl>
+    <dl class="schedule-facts">${fact("Schedule", scheduleDescription(job))}${fact("Next run", scheduleTimeLabel(job.nextRunAt, job.timeZone))}${fact("Time zone", job.timeZone)}${fact("Model", job.modelProfileId)}${fact("Mode", job.agentMode)}${fact("Tool access", toolPermissionModeMeta(job.toolPermissionMode).label)}${fact("Created", scheduleTimeLabel(job.createdAt, job.timeZone))}${fact("Updated", scheduleTimeLabel(job.updatedAt, job.timeZone))}</dl>
     <button type="button" class="schedule-conversation-link" data-open-conversation>↗ <span dir="auto">${escapeHtml(session?.title || job.sessionId)}</span></button>
     <details class="schedule-prompt-disclosure" data-disclosure-id="job:${escapeHtml(job.id)}"><summary>View task prompt</summary><pre dir="auto">${escapeHtml(job.prompt)}</pre></details>
     <small class="schedule-id">Job ${escapeHtml(job.id)} · Revision ${job.revision}</small>
@@ -70,6 +75,7 @@ export function renderScheduleDetails({ root, snapshot, actions }) {
       ${snapshot.loadingRuns ? '<p role="status">Loading runs…</p>' : ""}
       ${snapshot.detailError ? `<p role="alert" class="schedule-error">${escapeHtml(scheduleErrorMessage(snapshot.detailError))}</p>` : ""}
       ${snapshot.runs.map((run) => runMarkup(run)).join("") || (!snapshot.loadingRuns && !snapshot.detailError ? '<p class="schedule-muted">No recorded runs yet.</p>' : "")}</section>`;
+  if (!updateLiveRegion(root, markup)) return;
   for (const button of root.querySelectorAll("[data-job-action]")) {
     button.addEventListener("click", () => {
       if (button.dataset.jobAction === "edit") {

package/dist/src/web-ui/app/components/schedules/form.js

@@ -94,7 +94,14 @@ export function createScheduleForm({
         .map((mode) => ({ value: mode, label: mode })),
       values.agentMode || "reasoning",
     )}</select></label></div>
-    <p class="schedule-permission-note"><strong>Full tool access</strong> · This task runs in its conversation using the saved model and mode.</p>
+    <label>Tool access<select name="toolPermissionMode">${options(
+      [
+        { value: "full_access", label: "Full" },
+        { value: "full_plus", label: "FULL+" },
+      ],
+      values.toolPermissionMode || "full_access",
+    )}</select><small>FULL+ includes system actions without approval prompts. OS permissions still apply.</small></label>
+    <p class="schedule-permission-note">This task runs in its conversation using the saved model, mode and tool access.</p>
     <p class="schedule-form-feedback" role="alert" hidden></p>
     <div class="schedule-action-row"><button type="submit" class="primary-button">${job ? "Save changes" : "Create schedule"}</button><button type="button" data-cancel>Cancel</button></div>`;
   const fields = form.elements;
@@ -180,6 +187,7 @@ export function scheduleFormInput(data, originalSchedule) {
     prompt: value("prompt"),
     modelProfileId: value("modelProfileId"),
     agentMode: value("agentMode"),
+    toolPermissionMode: value("toolPermissionMode") || "full_access",
     timeZone: value("timeZone"),
     schedule,
   };

package/dist/src/web-ui/app/components/schedules/workspace-state.js

@@ -1,3 +1,4 @@
+import { updateLiveRegion } from "../../lib/live-region.js";
 import { escapeHtml } from "../../lib/text-format.js";
 import { scheduleErrorMessage } from "../../lib/schedule-errors.js";
 
@@ -50,9 +51,10 @@ export function renderScheduleWorkspaceState({ root, state, actions }) {
   if (!state) return;
   root.dataset.state = state.kind;
   root.setAttribute("role", state.kind === "error" ? "alert" : "status");
-  root.innerHTML = `<div class="schedule-state-icon" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><circle cx="12" cy="12" r="8.5"/><path d="M12 6.5V12l3.5 2"/></svg></div>
+  const markup = `<div class="schedule-state-icon" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><circle cx="12" cy="12" r="8.5"/><path d="M12 6.5V12l3.5 2"/></svg></div>
     <div class="schedule-state-copy"><h3>${escapeHtml(state.title)}</h3><p>${escapeHtml(state.description)}</p>
     ${state.action ? `<button type="button" class="${state.action === "create" ? "primary-button" : ""}" data-state-action>${escapeHtml(state.actionLabel)}</button>` : ""}</div>`;
+  if (!updateLiveRegion(root, markup)) return;
   root
     .querySelector("[data-state-action]")
     ?.addEventListener("click", () => actions[state.action]());

package/dist/src/web-ui/app/components/schedules/workspace.js

@@ -1,8 +1,9 @@
+import { updateLiveRegion } from "../../lib/live-region.js";
 import { escapeHtml } from "../../lib/text-format.js";
 import { scheduleTimeLabel } from "../../lib/schedule-message.js";
 import {
   emptyScheduleListMessage,
-  matchesScheduleFilter,
+  scheduleListJobs,
   scheduleDescription,
 } from "../../lib/schedule-presentation.js";
 import { createScheduleForm } from "./form.js";
@@ -22,12 +23,12 @@ export function createSchedulesWorkspace({
   confirmDiscard = (message) => window.confirm(message),
 }) {
   let editorIdentity = null;
-  root.innerHTML = `<div class="schedules-toolbar"><label class="schedule-search"><svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7"><circle cx="10.5" cy="10.5" r="6.5"/><path d="m16 16 4.5 4.5"/></svg><input type="search" placeholder="Search schedules…" aria-label="Search schedules"></label>
+  root.innerHTML = `<div class="schedules-content"><div class="schedules-toolbar"><label class="schedule-search"><svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7"><circle cx="10.5" cy="10.5" r="6.5"/><path d="m16 16 4.5 4.5"/></svg><input type="search" placeholder="Search schedules…" aria-label="Search schedules"></label>
     <select aria-label="Filter schedule status"><option value="current">Active &amp; paused</option><option value="active">Active</option><option value="paused">Paused</option><option value="completed">Completed</option><option value="cancelled">Cancelled</option><option value="all">All statuses</option></select>
     <button type="button" data-refresh>Refresh</button><button type="button" class="primary-button" data-create>New schedule</button></div>
     <p class="schedules-feedback" role="status" aria-live="polite"></p>
     <section class="schedule-workspace-state" aria-live="polite" hidden></section>
-    <div class="schedules-layout"><div class="schedules-list" aria-label="Schedules"></div><section class="schedule-details" aria-label="Schedule details"></section></div>`;
+    <div class="schedules-layout"><div class="schedules-list" aria-label="Schedules"></div><section class="schedule-details" aria-label="Schedule details"></section></div></div>`;
   const list = root.querySelector(".schedules-list");
   const details = root.querySelector(".schedule-details");
   const search = root.querySelector('[type="search"]');
@@ -71,16 +72,23 @@ export function createSchedulesWorkspace({
     void actions.filter(query, status);
   }
 
+  function bindListActions() {
+    for (const button of list.querySelectorAll("[data-job-id]")) {
+      button.addEventListener("click", () => {
+        if (button.dataset.jobId === actions.snapshot().selectedId) return;
+        if (prepareLeave()) void actions.select(button.dataset.jobId);
+      });
+    }
+  }
+
   function render(snapshot) {
     search.value = snapshot.query;
     filter.value = snapshot.filter;
-    const visible = snapshot.jobs.filter((job) =>
-      matchesScheduleFilter(
-        job,
-        snapshot.query,
-        snapshot.filter,
-        snapshot.sessions,
-      ),
+    const visible = scheduleListJobs(
+      snapshot.jobs,
+      snapshot.query,
+      snapshot.filter,
+      snapshot.sessions,
     );
     const pageState = scheduleWorkspaceState(snapshot);
     const firstScheduleEditor =
@@ -97,11 +105,13 @@ export function createSchedulesWorkspace({
         chat: () => actions.openConversation(getCurrentSessionId()),
       },
     });
-    feedback.textContent =
+    const feedbackText =
       (snapshot.error ? scheduleErrorMessage(snapshot.error) : "") ||
       (snapshot.loading
         ? "Loading schedules…"
         : `${visible.length} shown · ${snapshot.jobs.length} schedules`);
+    if (feedback.textContent !== feedbackText)
+      feedback.textContent = feedbackText;
     feedback.classList.toggle("schedule-error", Boolean(snapshot.error));
     root.setAttribute("aria-busy", String(snapshot.loading));
     createButton.disabled = snapshot.loading || snapshot.sessions.length === 0;
@@ -111,7 +121,7 @@ export function createSchedulesWorkspace({
     if (pageState) return;
     layout.classList.toggle("schedule-editor-only", snapshot.jobs.length === 0);
     list.hidden = snapshot.jobs.length === 0;
-    list.innerHTML =
+    const listMarkup =
       visible
         .map(
           (
@@ -122,12 +132,7 @@ export function createSchedulesWorkspace({
         )
         .join("") ||
       `<div class="schedule-list-empty">${escapeHtml(emptyScheduleListMessage(snapshot))}</div>`;
-    for (const button of list.querySelectorAll("[data-job-id]")) {
-      button.addEventListener("click", () => {
-        if (button.dataset.jobId === actions.snapshot().selectedId) return;
-        if (prepareLeave()) void actions.select(button.dataset.jobId);
-      });
-    }
+    if (updateLiveRegion(list, listMarkup)) bindListActions();
     if (snapshot.editor) {
       details.classList.remove("schedule-details-placeholder");
       if (editorIdentity === snapshot.editor) return;
@@ -149,17 +154,7 @@ export function createSchedulesWorkspace({
       return;
     }
     editorIdentity = null;
-    const openDetails = new Set(
-      [...details.querySelectorAll("details[data-disclosure-id]")]
-        .filter((node) => node.open)
-        .map((node) => node.dataset.disclosureId),
-    );
     renderScheduleDetails({ root: details, snapshot, actions });
-    for (const node of details.querySelectorAll(
-      "details[data-disclosure-id]",
-    )) {
-      node.open = openDetails.has(node.dataset.disclosureId);
-    }
   }
   return { render, prepareLeave };
 }

package/dist/src/web-ui/app/components/session-sidebar-drag.js

@@ -0,0 +1,58 @@
+export function createSessionSidebarDrag({ canMove, onMove }) {
+  let sourceId = "";
+  let draggedItem = null;
+  let targetItem = null;
+
+  function clearTarget() {
+    targetItem?.classList.remove("session-drop-before", "session-drop-after");
+    targetItem = null;
+  }
+
+  function reset() {
+    clearTarget();
+    draggedItem?.classList.remove("session-dragging");
+    draggedItem = null;
+    sourceId = "";
+  }
+
+  function placementAt(item, event) {
+    const bounds = item.getBoundingClientRect();
+    return event.clientY >= bounds.top + bounds.height / 2 ? "after" : "before";
+  }
+
+  function bind(item, sessionId) {
+    const handle = item.querySelector(".session-open-button");
+    handle.draggable = true;
+    handle.addEventListener("dragstart", (event) => {
+      reset();
+      sourceId = sessionId;
+      draggedItem = item;
+      item.classList.add("session-dragging");
+      event.dataTransfer.effectAllowed = "move";
+      event.dataTransfer.setData("text/plain", sessionId);
+    });
+    handle.addEventListener("dragend", reset);
+    item.addEventListener("dragover", (event) => {
+      clearTarget();
+      if (!canMove(sourceId, sessionId)) return;
+      event.preventDefault();
+      event.dataTransfer.dropEffect = "move";
+      targetItem = item;
+      item.classList.add(`session-drop-${placementAt(item, event)}`);
+    });
+    item.addEventListener("dragleave", (event) => {
+      if (item.contains(event.relatedTarget)) return;
+      clearTarget();
+    });
+    item.addEventListener("drop", (event) => {
+      if (!canMove(sourceId, sessionId)) return;
+      event.preventDefault();
+      const movedSessionId = sourceId;
+      const placement = placementAt(item, event);
+      reset();
+      onMove(movedSessionId, sessionId, placement);
+    });
+  }
+
+  return { bind, reset };
+}

package/dist/src/web-ui/app/components/session-sidebar-sections.js

@@ -0,0 +1,43 @@
+export function renderSessionSidebarSections({
+  root, sessions, archivedCount, showingArchived, onToggleArchived,
+  isPinned, createSessionItem, renderGroups, hasConversations,
+}) {
+  let itemIndex = 0;
+  const createItem = (session) => createSessionItem(session, itemIndex++);
+  if (showingArchived) {
+    const notice = document.createElement("p");
+    notice.className = "session-archive-notice";
+    notice.textContent = "Archived in this browser and environment. Restore a conversation from its menu.";
+    root.appendChild(notice);
+  }
+  const pinned = sessions.filter((session) => isPinned(session.id));
+  const regular = sessions.filter((session) => !isPinned(session.id));
+  if (pinned.length) {
+    const heading = document.createElement("div");
+    heading.className = "project-section-heading pinned-conversations-heading";
+    heading.textContent = "Pinned";
+    root.appendChild(heading);
+    for (const session of pinned) root.appendChild(createItem(session));
+  }
+  const grouped = renderGroups({ root, sessions: regular, createSessionItem: createItem });
+  if (!grouped) {
+    for (const session of regular) root.appendChild(createItem(session));
+    if (sessions.length === 0) {
+      const empty = document.createElement("div");
+      empty.className = "empty-state sidebar-empty-state compact";
+      empty.innerHTML = hasConversations
+        ? "<strong>No matches</strong><span>Try a different conversation name or message.</span>"
+        : "<strong>No conversations yet</strong><span>Start a new conversation to keep its history here.</span>";
+      root.appendChild(empty);
+    }
+  }
+  if (!archivedCount && !showingArchived) return;
+  const toggle = document.createElement("button");
+  toggle.type = "button";
+  toggle.className = "session-archive-toggle";
+  toggle.title = "Conversations archived in this browser and environment";
+  toggle.textContent = showingArchived ? "Back to conversations" : `Archived (${archivedCount})`;
+  toggle.setAttribute("aria-pressed", String(showingArchived));
+  toggle.addEventListener("click", onToggleArchived);
+  root.appendChild(toggle);
+}

package/dist/src/web-ui/app/components/spark-conversation-actions.js

@@ -0,0 +1,62 @@
+export function createSparkConversationActions({
+  getScope,
+  getMessages,
+  getActiveRequestId = () => "",
+  preferences,
+  archiveSession,
+  onArchived = () => {},
+  notify = () => {},
+  documentRoot = document,
+}) {
+  function canReview(message, scope) {
+    if (!scope.environmentId || !scope.sessionId || !preferences) return false;
+    if (getActiveRequestId() || message.streaming || !message.sparkProposalId) return false;
+    const messages = getMessages();
+    if (messages.some((item) => item.role === "user")) return false;
+    if (messages.find((item) => item.role === "assistant") !== message) return false;
+    if (preferences.loadSessionSidebar(scope.environmentId).archivedSessionIds.includes(scope.sessionId)) return false;
+    return !preferences.hasKeptSparkConversation(scope.environmentId, scope.sessionId);
+  }
+
+  function createNode(message, { onKept = () => {} } = {}) {
+    const scope = getScope();
+    if (!canReview(message, scope)) return null;
+    const row = documentRoot.createElement("div");
+    row.className = "spark-conversation-actions";
+    row.setAttribute("role", "group");
+    row.setAttribute("aria-label", "ABot Spark conversation");
+
+    function choose(action) {
+      const current = getScope();
+      if (current.environmentId !== scope.environmentId || current.sessionId !== scope.sessionId) return;
+      if (!canReview(message, scope)) return;
+      try {
+        if (action === "keep") {
+          preferences.keepSparkConversation(scope.environmentId, scope.sessionId);
+          row.hidden = true;
+          onKept();
+          notify("Conversation kept", "success");
+          return;
+        }
+        if (archiveSession?.(scope.sessionId) !== true) return;
+        row.hidden = true;
+        onArchived();
+      } catch {
+        notify("Could not save your choice in this browser. Please try again.", "failed");
+      }
+    }
+
+    for (const [action, label] of [["keep", "Keep"], ["archive", "Not interested"]]) {
+      const button = documentRoot.createElement("button");
+      button.type = "button";
+      button.textContent = label;
+      button.className = "spark-conversation-choice";
+      if (action === "archive") button.title = "Archive this conversation in this browser";
+      button.addEventListener("click", () => choose(action));
+      row.appendChild(button);
+    }
+    return row;
+  }
+
+  return { createNode };
+}

package/dist/src/web-ui/app/components/startup-screen.js

@@ -0,0 +1,30 @@
+export function createStartupScreen({
+  documentRoot = document,
+  reload = () => window.location.reload(),
+} = {}) {
+  const app = documentRoot.getElementById("app");
+  const startup = documentRoot.getElementById("appStartup");
+  const status = documentRoot.getElementById("startupStatus");
+  const retry = documentRoot.getElementById("startupRetry");
+  retry.addEventListener("click", reload);
+
+  function ready() {
+    app.removeAttribute("data-startup-pending");
+    app.removeAttribute("aria-busy");
+    app.inert = false;
+    startup.hidden = true;
+  }
+
+  function fail(error) {
+    app.setAttribute("data-startup-pending", "");
+    app.setAttribute("aria-busy", "true");
+    app.inert = true;
+    startup.hidden = false;
+    status.setAttribute("role", "alert");
+    const detail = error instanceof Error ? error.message : String(error);
+    status.textContent = `ABot could not open. ${detail}`;
+    retry.hidden = false;
+  }
+
+  return { ready, fail };
+}

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

@@ -0,0 +1,38 @@
+/** Save a setup file without retaining its authorization material. */
+export function downloadHostSetup(
+  receipt,
+  {
+    documentRoot = globalThis.document,
+    urlApi = globalThis.URL,
+    decode = globalThis.atob,
+    createBlob = (parts, options) => new Blob(parts, options),
+    defer = (callback) => setTimeout(callback, 1000),
+  } = {},
+) {
+  if (!isSetupDownloadReceipt(receipt))
+    throw new Error("Invalid setup download.");
+  const bytes = Uint8Array.from(decode(receipt.contentBase64), (value) =>
+    value.charCodeAt(0),
+  );
+  const url = urlApi.createObjectURL(
+    createBlob([bytes], { type: receipt.mimeType }),
+  );
+  const link = documentRoot.createElement("a");
+  try {
+    link.href = url;
+    link.download = receipt.filename;
+    link.hidden = true;
+    documentRoot.body.append(link);
+    link.click();
+  } finally {
+    link.remove();
+    defer(() => urlApi.revokeObjectURL(url));
+  }
+}
+function isSetupDownloadReceipt(receipt) {
+  if (typeof receipt?.filename !== "string") return false;
+  if (!/^[a-z0-9][a-z0-9._-]{0,119}$/iu.test(receipt.filename)) return false;
+  if (typeof receipt.mimeType !== "string") return false;
+  if (typeof receipt.contentBase64 !== "string") return false;
+  return receipt.contentBase64.length <= 8 * 1024 * 1024;
+}

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();
+    },
+  };
+}