@abot-ai/runtime 1.4.0 → 1.5.0

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

@@ -0,0 +1,235 @@
+import { renderAgent } from "./agent-view.js";
+import { renderComputerUpdateNotice } from "./computer-update-notice.js";
+import { renderMacCollectionRestartNotice, handleMacCollectionRestartClick } from "./macos-collection-restart-notice.js";
+import { learningCadenceLabel } from "./agent-state.js";
+import { renderLearningDiagnostics } from "./diagnostics-view.js";
+import { isObservationReviewActive } from "./processing-state.js";
+import { createAgentMotion } from "./agent-motion.js";
+import { createLearningSettings } from "./settings.js";
+import { handleActivityControlClick, renderActivityControls } from "./activity-controls.js";
+import { createLearningApplications } from "./applications-view.js";
+import { renderResourceUsage } from "./usage-view.js";
+import { renderLearningKnowledge, handleKnowledgeClick } from "./knowledge-view.js";
+import { renderLearningProposals, handleProposalClick } from "./proposal-view.js";
+import { escapeAttribute, escapeHtml } from "../../lib/text-format.js";
+import { learningBatchStatusLabel, renderLearningBatchDetail } from "./batch-detail.js";
+import { learningWorkspaceMarkup, navigateLearningTabs, selectLearningView } from "./workspace-view.js";
+import {
+  learningCoveragePresentation,
+  learningFailurePresentation,
+  learningProcessingLabel,
+  learningRetentionText,
+  hasUnprocessedLearningActivity,
+  learningTimeLabel,
+} from "./presentation.js";
+
+const defaultTimeZone = () => Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+
+export function createPassiveLearningMemory({
+  actions, showActivityMemories, openComputerAccess,
+  confirmDelete = (message) => window.confirm(message),
+}) {
+  let root = null;
+  let settings;
+  let applications;
+  let motion;
+  let displayedBatch = null;
+  let displayedBatchId = "";
+  let displayedDetailError = "";
+  let displayedDetailLoading = false;
+  let lastBatchMarkup = "";
+
+  function mount(nextRoot) {
+    if (root === nextRoot) return;
+    motion?.dispose();
+    root?.removeEventListener("click", handleClick);
+    root?.removeEventListener("submit", handleSubmit);
+    root?.removeEventListener("change", handleChange);
+    root?.removeEventListener("input", handleChange);
+    root?.removeEventListener("keydown", handleKeyDown);
+    root = nextRoot;
+    if (!root) return;
+    displayedBatch = null;
+    displayedBatchId = "";
+    lastBatchMarkup = "";
+    root.innerHTML = learningWorkspaceMarkup(defaultTimeZone());
+    settings = createLearningSettings({ root, actions, openSettings: () => selectLearningView(root, "settings") });
+    applications = createLearningApplications({ root, actions });
+    motion = createAgentMotion(root);
+    root.addEventListener("click", handleClick);
+    root.addEventListener("submit", handleSubmit);
+    root.addEventListener("change", handleChange);
+    root.addEventListener("input", handleChange);
+    root.addEventListener("keydown", handleKeyDown);
+    render(actions.snapshot());
+  }
+
+  function handleChange(event) {
+    if (applications.handleChange(event)) return;
+    settings.handleChange(event); renderControls(actions.snapshot());
+  }
+  function handleSubmit(event) { settings.handleSubmit(event); }
+
+  function handleKeyDown(event) {
+    navigateLearningTabs(root, event);
+  }
+
+  function handleClick(event) {
+    if (handleActivityControlClick(root, event, actions, () => selectLearningView(root, "settings"))) return;
+    if (handleMacCollectionRestartClick(root, event, actions)) return;
+    if (handleKnowledgeClick(root, event)) return;
+    if (handleProposalClick(root, event, actions)) return;
+    if (event.target.closest("[data-learning-open-settings]")) {
+      selectLearningView(root, "settings", true);
+      return;
+    }
+    const tab = event.target.closest("button[data-learning-tab]");
+    if (tab && root.contains(tab)) {
+      selectLearningView(root, tab.dataset.learningTab);
+      return;
+    }
+    const clearPending = event.target.closest("button[data-learning-clear-pending]");
+    if (clearPending && root.contains(clearPending)) {
+      deletePending();
+      return;
+    }
+    const setupButton = event.target.closest("button[data-learning-open-setup]") ??
+      event.target.closest("button[data-learning-open-update]") ??
+      event.target.closest("button[data-learning-computer-access]");
+    if (setupButton && root.contains(setupButton)) {
+      openComputerAccess();
+      return;
+    }
+    const button = event.target.closest("button[data-learning-refresh], button[data-learning-batch], button[data-learning-memories]");
+    if (!button || !root.contains(button)) return;
+    if (button.hasAttribute("data-learning-refresh")) void actions.refresh();
+    if (button.hasAttribute("data-learning-batch")) {
+      const previousId = actions.snapshot().selectedBatchId;
+      const nextId = button.dataset.learningBatch;
+      void actions.selectBatch(nextId);
+      if (!nextId) {
+        const previousButton = [...root.querySelectorAll("[data-learning-batches] button")]
+          .find((item) => item.dataset.learningBatch === previousId);
+        previousButton?.focus({ preventScroll: true });
+      }
+    }
+    if (button.hasAttribute("data-learning-memories"))
+      showActivityMemories();
+  }
+
+  function deletePending() {
+    const snapshot = actions.snapshot();
+    if (!snapshot.status || snapshot.saving) return;
+    if (!hasUnprocessedLearningActivity(snapshot.status)) return;
+    if (!confirmDelete("Delete all pending activity, including any review in progress? Saved insights are kept. This cannot be undone.")) return;
+    void actions.clearPending();
+  }
+
+
+  function renderControls(snapshot) {
+    const status = snapshot.status;
+    const disabled = snapshot.saving || !status;
+    renderActivityControls(root, snapshot);
+    root.querySelector("[data-learning-clear-pending]").disabled = disabled || !hasUnprocessedLearningActivity(status);
+  }
+
+  function renderStatus(snapshot) {
+    const status = snapshot.status;
+    const companion = snapshot.hostConnection?.companion;
+    renderComputerUpdateNotice(root, snapshot);
+    renderMacCollectionRestartNotice(root, snapshot);
+    root.querySelector("[data-learning-companion-version]").textContent = companion
+      ? `Installed version: ${companion.installedVersion ?? "unversioned"} · Available: ${companion.availableVersion}` : "Connect your computer to check its companion version.";
+    const attention = learningFailurePresentation(status);
+    const coverage = learningCoveragePresentation(status);
+    root.querySelector("[data-learning-attention]").hidden = !attention;
+    root.querySelector("[data-learning-attention-text]").textContent = attention?.message || "";
+    root.querySelector("[data-learning-open-setup]").hidden = !attention?.connectComputer;
+    root.querySelector("[data-learning-processing-status]").textContent = learningProcessingLabel(status);
+    root.querySelector("[data-learning-retention]").textContent = learningRetentionText(status);
+    const modelId = status?.preferences?.modelProfileId;
+    const model = snapshot.models.find((profile) => profile.id === modelId);
+    root.querySelector("[data-learning-schedule-summary]").textContent = modelId
+      ? `${model?.label || modelId} · ${learningCadenceLabel(status.preferences)}`
+      : "Choose a model in Settings to get started.";
+    root.querySelector("[data-learning-device]").textContent = status?.deviceId || "Not connected now";
+    root.querySelector("[data-learning-coverage]").textContent = coverage.label;
+    root.querySelector("[data-learning-coverage-detail]").textContent = coverage.detail;
+    const reasons = [status?.collectionReason, status?.processingReason, status?.reason, status?.proactive?.reason, status?.reassessment?.reason, status?.maintenanceReason].filter(Boolean);
+    root.querySelector("[data-learning-diagnostics]").hidden = !reasons.length;
+    renderLearningDiagnostics(root.querySelector("[data-learning-reason]"), reasons);
+    root.querySelector("[data-learning-observation]").textContent =
+      learningTimeLabel(status?.lastObservationAt);
+    root.querySelector("[data-learning-pending]").textContent = status
+      ? `${status.pendingObservations || 0} waiting${status.droppedObservations ? ` · ${status.droppedObservations} dropped` : ""}`
+      : "—";
+    const processingActive = !snapshot.statusError && isObservationReviewActive(status);
+    root.querySelector("[data-learning-pending-fact]").setAttribute("data-processing-active", String(processingActive));
+    root.querySelector("[data-learning-processing-badge]").hidden = !processingActive;
+    root.querySelector("[data-learning-analysis]").textContent = status
+      ? `${status.activeBatches ?? 0} active · ${status.effectiveConcurrency ?? 1} parallel${status.nextAnalysisAt ? ` · next ${learningTimeLabel(status.nextAnalysisAt)}` : ""}`
+      : "—";
+    const feedback = snapshot.statusError || snapshot.modelsError || snapshot.batchError;
+    root.querySelector("[data-learning-feedback]").textContent = feedback ||
+      (snapshot.loadingStatus ? "Loading learning status…" : "");
+  }
+
+  function renderBatches(snapshot) {
+    const list = root.querySelector("[data-learning-batches]");
+    if (snapshot.loadingBatches && !snapshot.batches.length) {
+      lastBatchMarkup = "";
+      list.textContent = "Loading reviews…";
+      return;
+    }
+    if (!snapshot.batches.length) {
+      lastBatchMarkup = "";
+      list.textContent = "No activity has been reviewed yet.";
+      return;
+    }
+    const markup = snapshot.batches.map((batch) =>
+      `<button type="button" class="passive-learning-batch" data-learning-batch="${escapeAttribute(batch.id)}" aria-pressed="${batch.id === snapshot.selectedBatchId}">
+        <span class="passive-learning-batch-heading"><time datetime="${escapeAttribute(batch.createdAt)}">${escapeHtml(learningTimeLabel(batch.createdAt))}</time><span>${escapeHtml(learningBatchStatusLabel(batch.status))}</span></span>
+        <small>${Number(batch.observationCount) || 0} observations · ${batch.recordIds?.length || 0} saved · ${batch.candidateIds?.length || 0} candidates</small>
+      </button>`).join("");
+    if (lastBatchMarkup !== markup) {
+      lastBatchMarkup = markup;
+      list.innerHTML = markup;
+    }
+  }
+
+  function renderBatchDetail(snapshot) {
+    const container = root.querySelector("[data-learning-detail]");
+    const batch = snapshot.selectedBatch;
+    if (snapshot.selectedBatchId === displayedBatchId &&
+        batch === displayedBatch &&
+        snapshot.detailError === displayedDetailError &&
+        snapshot.loadingDetail === displayedDetailLoading) return;
+    displayedBatchId = snapshot.selectedBatchId;
+    displayedBatch = batch;
+    displayedDetailError = snapshot.detailError;
+    displayedDetailLoading = snapshot.loadingDetail;
+    renderLearningBatchDetail(container, snapshot);
+  }
+
+  function render(snapshot) {
+    if (!root) return;
+    settings.render(snapshot);
+    applications.render(snapshot);
+    renderControls(snapshot);
+    renderAgent(root, snapshot);
+    motion.update(snapshot);
+    renderStatus(snapshot);
+    renderBatches(snapshot);
+    renderBatchDetail(snapshot);
+    renderLearningKnowledge(root, snapshot);
+    renderLearningProposals(root, snapshot);
+    renderResourceUsage(root, snapshot);
+  }
+
+  function focus() {
+    root?.querySelector("[data-learning-heading]")?.focus({ preventScroll: true });
+    root?.scrollIntoView({ block: "start", behavior: "smooth" });
+  }
+
+  return Object.freeze({ mount, render, focus });
+}

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;
+}