@abot-ai/runtime 1.3.1 → 1.5.0

package/dist/src/web-ui/app/components/passive-learning/presentation.js

@@ -0,0 +1,183 @@
+import { learningFailureCopy } from "./failure-copy.js";
+
+const setupRequiredReasons = new Set([
+  "host_not_paired",
+  "host_observations_unsupported",
+  "learning_host_unavailable",
+]);
+
+const connectReasons = new Set([
+  ...setupRequiredReasons,
+  "host_disconnected",
+  "host_broker_unavailable",
+  "host_observation_connect_timeout",
+  "learning_device_changed",
+  "macos_accessibility_permission_required",
+  "macos_accessibility_permission_timeout",
+  "macos_accessibility_permission_revoked",
+]);
+
+const failureStates = new Set([
+  "failed", "unavailable", "disconnected", "permission_required",
+]);
+
+const collectionFailureReasons = new Set([
+  ...connectReasons,
+  "host_observations_already_owned",
+  "host_observation_cancelled",
+  "platform_unsupported",
+  "macos_swift_tools_unavailable",
+  "collector_output_limit",
+  "collector_protocol_invalid",
+  "collector_dependency_unavailable",
+  "collector_start_failed",
+]);
+
+export function learningCollectionStatus(status) {
+  if (!status || status.collectionState === undefined) return status;
+  return { ...status, state: status.collectionState, reason: status.collectionReason };
+}
+
+export function hasLearningProcessingFailure(status) {
+  if (status?.processingReason) return true;
+  if (status?.collectionState !== undefined) return false;
+  if (status?.state !== "failed") return false;
+  return !collectionFailureReasons.has(status.reason);
+}
+
+const visibleAccessibilityReasons = new Set([
+  "uia_application_coverage",
+  "ax_application_coverage",
+  "atspi_application_coverage",
+  "wayland_atspi_coverage",
+  "x11_atspi_coverage",
+]);
+
+export function learningFailurePresentation(status) {
+  if (!status) return null;
+  const processingFailure = hasLearningProcessingFailure(status);
+  status = processingFailure ? { ...status, state: "failed", reason: status.processingReason || status.reason } : learningCollectionStatus(status);
+  if (!failureStates.has(status.state)) return null;
+  if (!status.preferences?.enabled && !processingFailure) return null;
+  const connectComputer = connectReasons.has(status.reason);
+  const explanation = learningFailureCopy(status.reason);
+  const fallback = status.state === "permission_required"
+    ? "Computer access needs permission before learning can collect activity."
+    : "Learning cannot collect activity right now. See Activity for technical details.";
+  const message = explanation.code || processingFailure ? explanation.message : fallback;
+  return { message, connectComputer };
+}
+
+export function learningIntroText(status) {
+  status = learningCollectionStatus(status);
+  if (status?.preferences?.enabled && status.reason === "continuous_activity")
+    return "Continuous screen changes are muted. Collection resumes after switching windows, editing, or 30 quiet seconds.";
+  if (!status) return "Checking collection status…";
+  if (!status.preferences?.enabled)
+    return "No activity is being collected. Your saved insights are kept.";
+  if (failureStates.has(status.state))
+    return "Collection needs attention. Your saved insights are still available.";
+  if (status.state === "paused")
+    return "Collection is paused. Your saved insights are still available.";
+  if (status.reason === "accessibility_read_unavailable")
+    return "The current app is not providing readable content.";
+  if (status.state === "partial" || status.state === "collecting")
+    return "Learning from visible computer activity.";
+  return "Connecting to your computer.";
+}
+
+export function learningProcessingLabel(status) {
+  if (!status) return "";
+  if (status.preferences?.processingPaused)
+    return "Processing paused. Pending activity is kept until its retention limit.";
+  if (status.processing || status.activeBatches > 0) return "Processing collected activity.";
+  if (!status.preferences?.modelProfileId)
+    return "Choose a model in Settings to process collected activity.";
+  if (hasLearningProcessingFailure(status))
+    return "Processing needs attention before pending activity can be reviewed.";
+  if (status.pendingObservations > 0)
+    return "Pending activity will be processed on the existing schedule.";
+  return "Processing is ready when activity is available.";
+}
+
+export function learningRetentionText(status) {
+  const hours = status?.retentionHours;
+  if (typeof hours === "number" && Number.isFinite(hours) && hours > 0)
+    return `Pending activity expires ${hours} hours after collection, including while processing is paused. Saved insights are kept.`;
+  return "Pending activity is kept within the configured retention period, including while processing is paused. Saved insights are kept.";
+}
+
+export function hasVisibleLearningWork(status) {
+  if (!status) return false;
+  if (status.preferences?.enabled) return true;
+  return hasUnprocessedLearningActivity(status);
+}
+
+export function hasUnprocessedLearningActivity(status) {
+  if (!status) return false;
+  if (status.blockedObservations > 0) return true;
+  if (status.pendingObservations > 0) return true;
+  if (status.activeBatches > 0) return true;
+  return status.processing === true;
+}
+
+export function learningCoveragePresentation(status) {
+  status = learningCollectionStatus(status);
+  if (!status) return { label: "Checking access", detail: "" };
+  if (!status.preferences?.enabled)
+    return { label: "Not collecting", detail: "" };
+  if (status.state === "partial" && status.reason === "accessibility_read_unavailable")
+    return { label: "Some content unreadable", detail: "The active app did not expose readable content." };
+  if (status.state === "partial" && visibleAccessibilityReasons.has(status.reason))
+    return { label: "Visible app content", detail: "Some content is not exposed by apps." };
+  if (status.state === "partial")
+    return { label: "Limited app visibility", detail: "Some content may be unavailable." };
+  if (status.state === "collecting")
+    return { label: "App content available", detail: "Coverage varies by app." };
+  if (status.state === "starting")
+    return { label: "Checking access", detail: "" };
+  return { label: "Not collecting", detail: "" };
+}
+
+export function learningStateLabel(status) {
+  status = learningCollectionStatus(status);
+  if (!status) return "Loading";
+  if (!status.preferences?.enabled) return "Collection stopped";
+  if (status.state === "partial" && status.reason === "accessibility_read_unavailable")
+    return "Limited access";
+  if (failureStates.has(status.state) && setupRequiredReasons.has(status.reason))
+    return "Setup required";
+  const labels = {
+    starting: "Connecting",
+    collecting: "Collecting",
+    partial: "Collecting",
+    unavailable: "Unavailable",
+    permission_required: "Permission required",
+    paused: "Paused",
+    stopped: "Stopped",
+    disconnected: "Disconnected",
+    failed: "Failed",
+    off: "Waiting to start",
+  };
+  return labels[status.state] || "Status unavailable";
+}
+
+export function learningTimeLabel(value) {
+  const timestamp = Date.parse(String(value || ""));
+  if (!Number.isFinite(timestamp)) return "Not yet";
+  return new Intl.DateTimeFormat(undefined, {
+    dateStyle: "medium",
+    timeStyle: "short",
+  }).format(timestamp);
+}
+
+export function learningModelLabel(profile) {
+  const name = profile.label || profile.id;
+  const provider = profile.providerId || profile.provider || "Provider unavailable";
+  return `${name} · ${provider}`;
+}
+
+export function learningPreview(value, limit = 110) {
+  const text = String(value || "").replaceAll(/\s+/gu, " ").trim();
+  return text.length > limit ? `${text.slice(0, limit).trimEnd()}…` : text;
+}

package/dist/src/web-ui/app/components/passive-learning/processing-state.js

@@ -0,0 +1,13 @@
+/** Queue totals exclude the batches already being processed. */
+export function isObservationReviewActive(status) {
+  if (status?.processing) return true;
+  return status?.activeBatches > 0;
+}
+
+export function observationReviewSummary(status) {
+  const batches = status?.activeBatches || 0;
+  const waiting = status?.pendingObservations || 0;
+  const running = batches > 0 ? `${batches} ${batches === 1 ? "batch" : "batches"} in progress` : "Review in progress";
+  const queue = waiting > 0 ? `${waiting} waiting` : "No observations waiting";
+  return `${running} · ${queue}`;
+}

package/dist/src/web-ui/app/components/passive-learning/proposal-notifications.js

@@ -0,0 +1,106 @@
+const MAX_SEEN_DELIVERIES = 100;
+
+function isProposalDelivery(message, environmentId) {
+  if (message?.type !== "learning.changed") return false;
+  if (message.environmentId !== environmentId) return false;
+  if (message.event?.type !== "proposal_delivered") return false;
+  return [message.event.proposalId, message.event.sessionId].every(
+    (id) =>
+      typeof id === "string" &&
+      id.length > 0 &&
+      id.length <= 256 &&
+      !/[\u0000-\u001f\u007f]/u.test(id),
+  );
+}
+
+/** Live deliveries alone announce themselves. Restored snapshots never produce a toast. */
+export function createProposalNotifications({
+  getEnvironmentId,
+  openSession,
+  getDocument = () => document,
+}) {
+  const seen = new Set();
+  let root;
+  let current;
+  let ownerDocument;
+
+  function syncVisibility() {
+    if (!root) return;
+    root.hidden = !current || ownerDocument.visibilityState === "hidden";
+  }
+
+  function hide() {
+    current = undefined;
+    if (root) root.hidden = true;
+  }
+
+  async function handleClick(event) {
+    const button = event.target.closest("button");
+    if (!button || !root?.contains(button)) return;
+    if (button.matches("[data-proposal-notice-close]")) {
+      hide();
+      return;
+    }
+    if (!button.matches("[data-proposal-notice-open]")) return;
+    const proposal = current;
+    if (!proposal || proposal.environmentId !== getEnvironmentId()) {
+      hide();
+      return;
+    }
+    button.disabled = true;
+    try {
+      const opened = await openSession(
+        proposal.sessionId,
+        proposal.environmentId,
+      );
+      if (current === proposal && opened !== false) hide();
+    } catch {
+      if (current !== proposal) return;
+      root.querySelector("[data-proposal-notice-description]").textContent =
+        "The conversation could not be opened. You can also find it in Chats.";
+    } finally {
+      if (current === proposal) button.disabled = false;
+    }
+  }
+
+  function mount() {
+    if (root) return;
+    const doc = getDocument();
+    ownerDocument = doc;
+    root = doc.createElement("aside");
+    root.className = "co-worker-proposal-toast";
+    root.setAttribute("role", "status");
+    root.setAttribute("aria-live", "polite");
+    root.setAttribute("aria-atomic", "true");
+    root.addEventListener("click", handleClick);
+    doc.addEventListener?.("visibilitychange", syncVisibility);
+    doc.body.append(root);
+  }
+
+  return Object.freeze({
+    handleRealtime(message) {
+      const environmentId = getEnvironmentId();
+      if (!isProposalDelivery(message, environmentId)) return;
+      const key = JSON.stringify([environmentId, message.event.proposalId]);
+      if (seen.has(key)) return;
+      seen.add(key);
+      if (seen.size > MAX_SEEN_DELIVERIES)
+        seen.delete(seen.values().next().value);
+      mount();
+      current = { environmentId, sessionId: message.event.sessionId };
+      root.innerHTML = `<div class="co-worker-proposal-toast-copy"><p>ABot Spark has a suggestion</p>
+        <span data-proposal-notice-description>A new conversation is ready when you are.</span>
+        <button type="button" class="home-text-button" data-proposal-notice-open>Read suggestion ↗</button></div>
+        <button type="button" class="home-text-button" data-proposal-notice-close aria-label="Dismiss notification">×</button>`;
+      syncVisibility();
+    },
+    environmentChanged: hide,
+    dispose() {
+      hide();
+      root?.removeEventListener("click", handleClick);
+      ownerDocument?.removeEventListener?.("visibilitychange", syncVisibility);
+      root?.remove();
+      root = undefined;
+    },
+  });
+}

package/dist/src/web-ui/app/components/passive-learning/proposal-read-state.js

@@ -0,0 +1,23 @@
+import { isSessionReadStateUnavailable } from "../../lib/session-read-state.js";
+
+function hasReadProposalConversation(proposal, sessions) {
+  const session = sessions.find((item) => item.id === proposal.sessionId);
+  if (!session || isSessionReadStateUnavailable(session)) return false;
+  // Each proposal starts its own conversation. Any confirmed assistant read
+  // boundary in that conversation includes the opening proposal.
+  return Boolean(session.lastReadMessageId ?? session.readState?.lastReadMessageId);
+}
+
+/** Invitations reflect confirmed reads without changing the stored proposal history. */
+export function visibleProposalSnapshot(snapshot, sessionSnapshot) {
+  if (!snapshot.status?.proactive) return snapshot;
+  if (!sessionSnapshot) return snapshot;
+  if (sessionSnapshot.environmentId !== snapshot.environmentId) return snapshot;
+  const proposals = (snapshot.status.proactive.proposals ?? []).filter(
+    (proposal) => !hasReadProposalConversation(proposal, sessionSnapshot.sessions),
+  );
+  return {
+    ...snapshot,
+    status: { ...snapshot.status, proactive: { ...snapshot.status.proactive, proposals } },
+  };
+}

package/dist/src/web-ui/app/components/passive-learning/proposal-view.js

@@ -0,0 +1,23 @@
+import { escapeAttribute, escapeHtml } from "../../lib/text-format.js";
+const renderKeys = new WeakMap();
+
+export function renderLearningProposals(root, snapshot, { limit = 3 } = {}) {
+  const container = root.querySelector("[data-learning-proposals]");
+  if (!container) return;
+  const proposals = [...(snapshot.status?.proactive?.proposals ?? [])].reverse().filter((item) => item.status === "delivered").slice(0, limit);
+  const key = JSON.stringify([snapshot.environmentId, proposals, snapshot.dismissingProposalId, snapshot.proposalError]);
+  if (renderKeys.get(container) === key) return;
+  renderKeys.set(container, key);
+  container.innerHTML = proposals.map((item) => `<article class="co-worker-proposal"><div class="co-worker-proposal-icon" aria-hidden="true">✦</div><div><span class="co-worker-eyebrow">ABot Spark · conversation ready</span><h4 dir="auto">${escapeHtml(item.title)}</h4><p dir="auto">${escapeHtml(item.message)}</p><div class="co-worker-proposal-actions"><button type="button" data-learning-proposal-open="${escapeAttribute(item.id)}">Open conversation ↗</button><button type="button" data-learning-proposal-dismiss="${escapeAttribute(item.id)}"${snapshot.dismissingProposalId ? " disabled" : ""}>Not now</button></div></div></article>`).join("") + (snapshot.proposalError ? `<p role="status">${escapeHtml(snapshot.proposalError)}</p>` : "");
+}
+
+export function handleProposalClick(root, event, actions = {}) {
+  const open = event.target.closest("[data-learning-proposal-open]");
+  if (open && root.contains(open)) { void actions.openProposal?.(open.dataset.learningProposalOpen); return true; }
+  const dismiss = event.target.closest("[data-learning-proposal-dismiss]");
+  if (dismiss && root.contains(dismiss)) {
+    if (!dismiss.disabled) void actions.dismissProposal?.(dismiss.dataset.learningProposalDismiss);
+    return true;
+  }
+  return false;
+}

package/dist/src/web-ui/app/components/passive-learning/settings-view.js

@@ -0,0 +1,82 @@
+import { escapeAttribute } from "../../lib/text-format.js";
+
+function field(key, label, { type = "number", value = "", min = 1, max, legacy = "", step = "1", options } = {}) {
+  const attrs = `data-learning-setting="${key}" ${legacy ? `data-learning-${legacy}` : ""}`;
+  const control = type === "select"
+    ? `<select ${attrs} aria-label="${label}">${options || '<option value="">Choose a model</option>'}</select>`
+    : `<input ${attrs} type="${type}" value="${escapeAttribute(value)}" ${type === "number" ? `min="${min}" step="${step}" ${max ? `max="${max}"` : ""}` : ""} ${type === "text" ? 'autocomplete="off" maxlength="100"' : ""} required />`;
+  return `<label class="co-worker-setting-field">${label}${control}</label>`;
+}
+
+function toggle(key, label, legacy = "", small = false) {
+  return `<label class="${small ? "co-worker-hours-toggle" : "co-worker-setting-switch"}"><input type="checkbox" data-learning-setting="${key}" ${legacy ? `data-learning-${legacy}` : ""} /><span>${label}</span></label>`;
+}
+
+function windowFields(axis, timeZone) {
+  const legacy = axis === "processing" ? "" : `${axis}-`;
+  return `${toggle(`${axis}Hours`, "Set activity hours", `${legacy}hours`, true)}
+    <div class="co-worker-window-fields" data-learning-window-for="${axis}" data-learning-${legacy}window hidden>
+      <div class="co-worker-setting-pair">${field(`${axis}Start`, "From", { type: "time", value: "09:00", legacy: `${legacy}start` })}
+      ${field(`${axis}End`, "Until", { type: "time", value: "17:00", legacy: `${legacy}end` })}</div>
+      ${field(`${axis}TimeZone`, "Time zone", { type: "text", value: timeZone, legacy: `${legacy}time-zone` })}
+    </div>`;
+}
+
+export function learningSettingsMarkup(timeZone = "UTC") {
+  return `<form class="passive-learning-settings co-worker-settings" data-learning-settings>
+    <div class="co-worker-settings-header">
+      <div class="co-worker-settings-intro"><h4>Activity permissions</h4><p>Choose what Spark may do. Saving permission does not start an activity; use its Start button when you are ready.</p></div>
+      <button type="submit" data-learning-save disabled>Save settings</button>
+    </div>
+    <div class="co-worker-settings-grid">
+      <section class="co-worker-settings-card" data-learning-settings-axis="collection">
+        <h4>Collection</h4><p>Notice changes in your active applications.</p>
+        ${toggle("collectionEnabled", "Allow collection", "collection-enabled")}
+        ${windowFields("collection", timeZone)}
+        <p class="co-worker-setting-note">Revoking permission stops collection. Pending observations keep their existing retention limit.</p>
+      </section>
+      <section class="co-worker-settings-card" data-learning-settings-axis="processing">
+        <h4>Learning</h4><p>Review activity and refine what ABot Spark knows.</p>
+        ${toggle("processingEnabled", "Allow learning", "processing-enabled")}
+        ${field("modelProfileId", "Learning model", { type: "select", legacy: "model" })}
+        ${field("analysisTrigger", "Start a review", { type: "select", options: '<option value="interval">By time</option><option value="observations">By observation count</option>' })}
+        <div data-learning-trigger-for="interval">${field("analysisIntervalMinutes", "Review interval (minutes)", { value: 15, max: 1440, legacy: "interval" })}</div>
+        <div data-learning-trigger-for="observations" hidden>${field("analysisObservationCount", "Eligible observations waiting", { value: 100, max: 256 })}
+          <p class="co-worker-setting-note">Reviews waiting observations in small batches. Starts earlier if eligible activity nears the storage limit. New observations wait for the next review; blocked apps do not count. Hours, budgets and retention still apply.</p></div>
+        ${windowFields("processing", timeZone)}
+        <p class="co-worker-setting-note">Runs only when there is eligible work. Pausing keeps pending observations within their retention limit.</p>
+      </section>
+      <section class="co-worker-settings-card" data-learning-settings-axis="proactive">
+        <h4>Proactive mode</h4><p>Start a conversation when there is something useful to offer.</p>
+        ${toggle("proactiveEnabled", "Allow proactive mode", "proactive-enabled")}
+        ${field("proactiveModelProfileId", "Proactive model", { type: "select", legacy: "proactive-model" })}
+        ${field("proactiveIntervalMinutes", "Check interval (minutes)", { value: 60, max: 1440, legacy: "proactive-interval" })}
+        ${windowFields("proactive", timeZone)}
+        <p class="co-worker-setting-note">Can use existing knowledge while collection is off. Messages only; actions need your approval.</p>
+      </section>
+    </div>
+    <section class="co-worker-settings-limits">
+      <div class="co-worker-settings-intro"><h4>Shared limits</h4><p>Learning and proactive reviews share this daily budget. Failed attempts count too.</p></div>
+      <div class="co-worker-limits-grid">
+        ${field("modelCallsPerDay", "Model calls per day", { value: 24 })}
+        ${field("proactiveMessagesPerDay", "Proactive messages per day", { value: 2, max: 100 })}
+        ${field("maxConcurrentBatches", "Concurrent cloud calls", { value: 1, max: 8, legacy: "concurrency" })}
+        ${field("embeddingCallsPerDay", "Embedding calls per day", { value: 96 })}
+        ${field("embeddingCharactersPerDay", "Embedding input characters per day", { value: 1048576 })}
+        ${field("budgetTimeZone", "Daily budget time zone", { type: "text", value: "UTC" })}
+      </div>
+      <p class="co-worker-setting-note">Local models run one call at a time. A time-zone change does not reset the current budget.</p>
+    </section>
+    <details class="co-worker-settings-limits co-worker-memory-policy">
+      <summary>When a candidate becomes memory</summary>
+      <p class="co-worker-setting-note">Applies to automatic learning from conversations and computer activity. Promotion needs your chosen score and two independent reinforcements. Scores express model judgment, not probability.</p>
+      <div class="co-worker-limits-grid">
+        ${field("promotionScore", "Promotion score (out of 100)", { value: 90, min: 0, max: 100 })}
+        ${field("retentionDays", "Days without reinforcement", { value: 30, max: 365 })}
+        ${field("maxCandidates", "Maximum candidates", { value: 500, max: 5000 })}
+        ${field("candidateMiB", "Candidate storage limit (MiB)", { value: 2, min: 0.0009765625, max: 20, step: "any" })}
+      </div>
+    </details>
+    <div class="co-worker-settings-footer"><span data-learning-settings-feedback role="status" aria-live="polite"></span><button type="submit" data-learning-save disabled>Save settings</button></div>
+  </form>`;
+}

package/dist/src/web-ui/app/components/passive-learning/settings.js

@@ -0,0 +1,178 @@
+import { learningModelLabel } from "./presentation.js";
+import { hasActivityModel, readActivityPermissions } from "./activity-controls.js";
+
+const timeZone = () => Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+const checkboxFields = new Set(["collectionEnabled", "processingEnabled", "proactiveEnabled", "collectionHours", "processingHours", "proactiveHours"]);
+const integerLimits = { analysisIntervalMinutes: [1, 1440], analysisObservationCount: [1, 256], proactiveIntervalMinutes: [1, 1440],
+  proactiveMessagesPerDay: [1, 100], maxConcurrentBatches: [1, 8], modelCallsPerDay: [1, Number.MAX_SAFE_INTEGER],
+  embeddingCallsPerDay: [1, Number.MAX_SAFE_INTEGER], embeddingCharactersPerDay: [1, Number.MAX_SAFE_INTEGER],
+  promotionScore: [0, 100], retentionDays: [1, 365], maxCandidates: [1, 5000] };
+
+function savedSettings(preferences = {}) {
+  const limits = preferences.resourceLimits || {}, maturation = preferences.maturation || {};
+  const permissions = readActivityPermissions(preferences);
+  const values = { collectionEnabled: permissions.collection, processingEnabled: permissions.learning,
+    proactiveEnabled: permissions.proactive, modelProfileId: preferences.modelProfileId || "",
+    proactiveModelProfileId: preferences.proactiveModelProfileId || "",
+    analysisTrigger: preferences.analysisTrigger ?? "interval", analysisObservationCount: preferences.analysisObservationCount ?? 100,
+    analysisIntervalMinutes: preferences.analysisIntervalMinutes ?? 15, proactiveIntervalMinutes: preferences.proactiveIntervalMinutes ?? 60,
+    proactiveMessagesPerDay: preferences.proactiveMessagesPerDay ?? 2, maxConcurrentBatches: preferences.maxConcurrentBatches ?? limits.maxConcurrentCalls ?? 1,
+    modelCallsPerDay: limits.modelCallsPerDay ?? 24, embeddingCallsPerDay: limits.embeddingCallsPerDay ?? 96,
+    embeddingCharactersPerDay: limits.embeddingCharactersPerDay ?? 1048576, budgetTimeZone: limits.timeZone || "UTC",
+    promotionScore: maturation.promotionScore ?? 90, retentionDays: maturation.retentionDays ?? 30,
+    maxCandidates: maturation.maxCandidates ?? 500, candidateMiB: (maturation.maxBytes ?? 2097152) / 1048576 };
+  for (const [axis, window] of [["collection", preferences.collectionWindow], ["processing", preferences.analysisWindow], ["proactive", preferences.proactiveWindow]]) {
+    Object.assign(values, { [`${axis}Hours`]: Boolean(window), [`${axis}Start`]: window?.start || "09:00",
+      [`${axis}End`]: window?.end || "17:00", [`${axis}TimeZone`]: window?.timeZone || timeZone() });
+  }
+  return Object.fromEntries(Object.entries(values).map(([key, value]) => [key, checkboxFields.has(key) ? value : String(value)]));
+}
+
+function preferencesFrom(values) {
+  const window = (axis) => values[`${axis}Hours`] ? { start: values[`${axis}Start`], end: values[`${axis}End`], timeZone: values[`${axis}TimeZone`].trim() } : null;
+  return { activityPermissions: { collection: values.collectionEnabled, learning: values.processingEnabled, proactive: values.proactiveEnabled },
+    ...(values.modelProfileId ? { modelProfileId: values.modelProfileId } : {}),
+    proactiveModelProfileId: values.proactiveModelProfileId || null,
+    analysisTrigger: values.analysisTrigger,
+    ...(values.analysisTrigger === "observations" ? { analysisObservationCount: Number(values.analysisObservationCount) }
+      : { analysisIntervalMinutes: Number(values.analysisIntervalMinutes) }),
+    analysisWindow: window("processing"), collectionWindow: window("collection"),
+    proactiveIntervalMinutes: Number(values.proactiveIntervalMinutes), proactiveWindow: window("proactive"),
+    proactiveMessagesPerDay: Number(values.proactiveMessagesPerDay), maxConcurrentBatches: Number(values.maxConcurrentBatches),
+    resourceLimits: { modelCallsPerDay: Number(values.modelCallsPerDay), embeddingCallsPerDay: Number(values.embeddingCallsPerDay),
+      embeddingCharactersPerDay: Number(values.embeddingCharactersPerDay), maxConcurrentCalls: Number(values.maxConcurrentBatches), timeZone: values.budgetTimeZone.trim() },
+    maturation: { promotionScore: Number(values.promotionScore), retentionDays: Number(values.retentionDays),
+      maxCandidates: Number(values.maxCandidates), maxBytes: Number(values.candidateMiB) * 1048576 } };
+}
+
+function isInactiveLearningSetting(key, values) {
+  if (key === "analysisObservationCount") return values.analysisTrigger !== "observations";
+  if (key === "analysisIntervalMinutes") return values.analysisTrigger === "observations";
+  return false;
+}
+
+export function createLearningSettings({ root, actions, openSettings = () => {} }) {
+  let environment;
+  let committed = savedSettings();
+  let values = { ...committed };
+  let modelOptionsKey = "";
+  let feedback = "";
+  const form = root.querySelector("[data-learning-settings]");
+  const input = (key) => root.querySelector(`[data-learning-setting="${key}"]`);
+  const changed = () => Object.keys(values).some((key) => values[key] !== committed[key]);
+
+  function models(profiles = []) {
+    const key = JSON.stringify(profiles.map((profile) => [profile.id, profile.label, profile.providerId, profile.provider]));
+    if (key === modelOptionsKey) return;
+    modelOptionsKey = key;
+    for (const name of ["modelProfileId", "proactiveModelProfileId"]) {
+      const select = input(name); select.replaceChildren();
+      const append = (label, id) => { const option = root.ownerDocument.createElement("option"); option.textContent = label; option.value = id; select.append(option); };
+      append(name === "proactiveModelProfileId" ? "Same as learning" : "Choose a model", "");
+      for (const profile of profiles) if (typeof profile.id === "string") append(learningModelLabel(profile), profile.id);
+    }
+  }
+
+  function render(snapshot) {
+    const next = savedSettings(snapshot.status?.preferences);
+    if (snapshot.environmentId !== environment) {
+      environment = snapshot.environmentId; values = { ...next }; committed = next; feedback = ""; modelOptionsKey = "";
+    } else if (snapshot.status) {
+      for (const key of Object.keys(next)) if (values[key] === committed[key]) values[key] = next[key];
+      committed = next;
+    }
+    models(snapshot.models || []);
+    for (const [key, value] of Object.entries(values)) {
+      const element = input(key);
+      if (!element) continue;
+      if (checkboxFields.has(key)) element.checked = value;
+      else {
+        if (element.tagName === "SELECT" && value && ![...element.querySelectorAll("option")].some((option) => option.value === value)) {
+          const option = root.ownerDocument.createElement("option"); option.value = value; option.textContent = `${value} · unavailable`; element.append(option);
+        }
+        if (element.value !== value) element.value = value;
+      }
+      element.disabled = snapshot.saving || !snapshot.status || isInactiveLearningSetting(key, values);
+    }
+    for (const mode of ["interval", "observations"])
+      root.querySelector(`[data-learning-trigger-for="${mode}"]`).hidden = values.analysisTrigger !== mode;
+    for (const axis of ["collection", "processing", "proactive"]) {
+      const window = root.querySelector(`[data-learning-window-for="${axis}"]`);
+      window.hidden = !values[`${axis}Hours`];
+      for (const element of window.querySelectorAll("input")) element.disabled ||= window.hidden;
+      root.querySelector(`[data-learning-settings-axis="${axis}"]`).dataset.enabled = String(values[`${axis}Enabled`]);
+    }
+    for (const save of root.querySelectorAll("[data-learning-save]")) {
+      save.textContent = snapshot.saving ? "Saving…" : "Save settings";
+      save.disabled = snapshot.saving || !snapshot.status || !changed();
+    }
+    root.querySelector("[data-learning-settings-feedback]").textContent = feedback || (changed() ? "Unsaved changes" : "");
+  }
+
+  function handleChange(event) {
+    if (!form?.contains(event.target)) return false;
+    const key = event.target.dataset.learningSetting;
+    if (!Object.hasOwn(values, key)) return false;
+    values[key] = checkboxFields.has(key) ? event.target.checked : event.target.value;
+    feedback = "";
+    render(actions.snapshot());
+    return true;
+  }
+
+  function invalid(key, message) {
+    feedback = message; openSettings(); input(key)?.focus(); render(actions.snapshot()); return false;
+  }
+  function validate() {
+    const profiles = actions.snapshot().models || [];
+    if ((values.collectionEnabled || values.processingEnabled) && !hasActivityModel("learning", values, profiles))
+      return invalid("modelProfileId", "Choose an available learning model first.");
+    if (values.proactiveEnabled && !hasActivityModel("proactive", values, profiles))
+      return invalid("proactiveModelProfileId", "Choose an available model for proactive mode.");
+    for (const key of Object.keys(integerLimits)) {
+      if (isInactiveLearningSetting(key, values)) continue;
+      const number = Number(values[key]), [minimum, maximum] = integerLimits[key];
+      if (!Number.isSafeInteger(number) || number < minimum || number > maximum)
+        return invalid(key, `Enter a whole number between ${minimum} and ${maximum}.`);
+    }
+    const bytes = Number(values.candidateMiB) * 1048576;
+    if (!Number.isSafeInteger(bytes) || bytes < 1024 || bytes > 20971520)
+      return invalid("candidateMiB", "Set a candidate limit between 1 KiB and 20 MiB, in whole bytes.");
+    const zones = ["budgetTimeZone"];
+    for (const axis of ["collection", "processing", "proactive"]) {
+      if (!values[`${axis}Hours`]) continue;
+      for (const suffix of ["Start", "End"]) if (!/^(?:[01]\d|2[0-3]):[0-5]\d$/u.test(values[`${axis}${suffix}`]))
+        return invalid(`${axis}${suffix}`, "Choose a valid start and end time.");
+      zones.push(`${axis}TimeZone`);
+    }
+    for (const key of zones) {
+      try { new Intl.DateTimeFormat("en-US", { timeZone: values[key].trim() }).format(0); }
+      catch { return invalid(key, "Enter a valid time zone, such as Asia/Jerusalem."); }
+    }
+    if (form.checkValidity?.() === false) { openSettings(); form.reportValidity?.(); return false; }
+    return true;
+  }
+
+  async function saveSettings() {
+    const draft = values, submitted = { ...values };
+    const status = await actions.configure(preferencesFrom(submitted));
+    if (!status?.preferences || values !== draft) return;
+    const saved = savedSettings(status.preferences);
+    for (const key of Object.keys(submitted)) {
+      if (!isInactiveLearningSetting(key, submitted)) continue;
+      if (values[key] === submitted[key]) values[key] = saved[key];
+    }
+    render(actions.snapshot());
+  }
+
+  function handleSubmit(event) {
+    if (event.target !== form) return false;
+    event.preventDefault();
+    const snapshot = actions.snapshot();
+    if (snapshot.saving || !snapshot.status) return true;
+    render(snapshot);
+    if (validate()) void saveSettings();
+    return true;
+  }
+
+  return Object.freeze({ render, handleChange, handleSubmit, draft: () => preferencesFrom(values) });
+}