@abot-ai/runtime 1.4.0 → 1.5.0

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

@@ -0,0 +1,141 @@
+const genericMessage = "ABot Spark could not complete this review. No specific cause is available.";
+
+// Exact content-free codes only. Never turn an arbitrary provider error into UI copy.
+const groups = [
+  ["macOS Accessibility permission is required. Open Computer access for the exact companion executable to approve. Spark waits up to two minutes for your consent.", ["macos_accessibility_permission_required"]],
+  ["macOS Accessibility permission was removed. Re-enable access for the companion in Computer access, then stop and start collection.", ["macos_accessibility_permission_revoked"]],
+  ["macOS Accessibility permission was not granted within two minutes. Complete permission setup in Computer access, then stop and start collection to check again.", ["macos_accessibility_permission_timeout"]],
+  ["Collection is working through Windows accessibility. Some apps do not expose all visible content; this is a coverage limit, not a connection failure.", ["uia_application_coverage"]],
+  ["Collection is working through macOS accessibility. Some apps do not expose all visible content; this is a coverage limit, not a connection failure.", ["ax_application_coverage"]],
+  ["Collection is working through Linux accessibility. Some apps do not expose all visible content; this is a coverage limit, not a connection failure.", ["atspi_application_coverage", "wayland_atspi_coverage", "x11_atspi_coverage"]],
+  ["The current app is not exposing readable content. Collection can continue when readable content becomes available.", ["accessibility_read_unavailable", "focused_window_unavailable"]],
+  ["Rapid screen changes are temporarily muted to avoid collecting repeated activity. Collection resumes after switching windows, editing, or a quiet period.", ["continuous_activity"]],
+  ["Collection is paused because this application is excluded in Settings.", ["application_excluded"]],
+  ["Collection is paused while the screen is locked or a secure desktop is active.", ["screen_locked_or_secure_desktop", "screen_locked"]],
+  ["ABot's own interface is excluded from collection to avoid learning from its own output.", ["runtime_interface_excluded"]],
+  ["Collection is outside its configured hours. It resumes during the next collection window.", ["learning_outside_collection_window"]],
+  ["Processing is outside its configured hours. Pending activity is kept within its retention limit.", ["learning_outside_processing_window"]],
+  ["The computer has no accessible graphical session. Sign in to a desktop session to collect activity.", ["graphical_session_unavailable"]],
+  ["The collector cannot verify whether the screen is locked, so collection is paused.", ["session_lock_state_unavailable"]],
+  ["Linux accessibility dependencies are missing. Update Computer access setup on this computer.", ["linux_atspi_python_dependencies_missing"]],
+  ["Window-change events are unavailable. Collection is using accessibility events with reduced coverage.", ["x11_events_unavailable_atspi_only"]],
+  ["The Windows accessibility collector is unavailable. Check Computer access and its permissions.", ["windows_uia_helper_unavailable", "foreground_events_unavailable"]],
+  ["The proactive model's explanation was missing or invalid. That attempt did not create a suggestion; collection and learning are separate.", ["proactive_reason_invalid"]],
+  ["The proactive model returned an unreadable response. No suggestion was created.", ["proactive_output_invalid_json"]],
+  ["The proactive model returned a decision that could not be accepted. No suggestion was created.", ["proactive_decision_invalid", "proactive_none_payload_invalid"]],
+  ["The model could not complete a step of the proactive review. No suggestion was created.", ["proactive_staged_output_invalid", "proactive_staged_output_fields_invalid", "proactive_objective_invalid"]],
+  ["The proactive suggestion needs a valid title and message before it can be shown.", ["proactive_title_invalid", "proactive_message_invalid"]],
+  ["The proactive suggestion referred to missing, changed, or invalid knowledge. It was not delivered.", ["proactive_sources_invalid", "proactive_source_invalid", "proactive_source_stale_or_unknown", "proactive_source_duplicate", "proactive_sources_required"]],
+  ["The proactive suggestion had a missing or invalid expiry or review time. It was not delivered.", ["proactive_expiry_required", "proactive_time_invalid", "proactive_time_not_future", "proactive_time_too_distant", "proactive_reference_time_invalid"]],
+  ["Choose an available proactive model in Spark Settings before allowing or starting proactive mode.", ["proactive_model_required", "proactive_model_profile_unavailable", "proactive_model_profile_overridden"]],
+  ["The proactive review reached its time limit. No suggestion was created.", ["proactive_review_timeout"]],
+  ["Proactive mode has reached its daily message limit. It can send suggestions after the daily limit resets.", ["proactive_daily_message_limit_reached"]],
+  ["Proactive mode is outside its configured hours. It resumes during the next proactive window.", ["proactive_outside_window"]],
+  ["Proactive mode is turned off.", ["proactive_disabled"]],
+  ["The proactive review yielded resources to your active conversation.", ["proactive_interactive_preempted"]],
+  ["The proactive review was superseded by changed settings or knowledge.", ["proactive_superseded", "proactive_preferences_changed", "proactive_revision_conflict"]],
+  ["The proactive review was interrupted. The same knowledge is not retried automatically to avoid repeated model costs.", ["proactive_review_interrupted"]],
+  ["The suggestion could not be delivered to a conversation. Check the runtime connection.", ["proactive_session_delivery_unavailable"]],
+  ["The proactive activity could not start. Other ABot Spark activities can continue independently.", ["proactive_start_failed"]],
+  ["Saved proactive state could not be read safely.", ["proactive_state_invalid", "proactive_state_too_large"]],
+  ["The proactive review's context is too large for its allowed limit.", ["proactive_knowledge_context_too_large"]],
+  ["Proactive mode could not complete this review. No specific cause is available.", ["proactive_failed"]],
+  ["Scheduled knowledge review could not start. Other ABot Spark activities can continue independently.", ["learning_reassessment_start_failed"]],
+  ["Scheduled knowledge review is waiting for capacity.", ["learning_reassessment_capacity"]],
+  ["Scheduled knowledge review could not finish. Existing knowledge is kept.", ["learning_reassessment_failed"]],
+  ["Learning data cleanup could not finish. Check the runtime's storage access.", ["learning_maintenance_failed"]],
+  ["No computer is paired for learning. Connect a computer to start collecting.", ["host_not_paired"]],
+  ["The paired computer is disconnected. Reconnect it or open computer setup.", ["host_disconnected"]],
+  ["The computer connection is unavailable. Connect a computer for learning.", ["host_broker_unavailable"]],
+  ["This Host Companion cannot collect learning activity. Install the current companion.", ["host_observations_unsupported"]],
+  ["The paired computer did not respond. Check that its companion is running.", ["host_observation_connect_timeout"]],
+  ["A Host Companion connection is required to collect computer activity.", ["learning_host_unavailable"]],
+  ["The connected computer changed. Connect it again for learning.", ["learning_device_changed"]],
+  ["Another runtime is already collecting activity from this computer.", ["host_observations_already_owned"]],
+  ["The computer connection request was cancelled.", ["host_observation_cancelled"]],
+  ["Allow this activity in Spark Settings before starting it.", ["learning_activity_not_allowed"]],
+  ["Choose a learning model in Spark Settings before allowing or starting collection or learning.", ["learning_model_required"]],
+  ["The selected learning model is unavailable. Choose another model.", ["learning_model_profile_unavailable"]],
+  ["The selected learning model cannot be used for background learning. Choose another model.", ["learning_model_profile_overridden"]],
+  ["The learning model could not process activity. Check its configuration in Settings.", ["learning_model_request_failed"]],
+  ["The model did not finish its response.", ["output_incomplete"]],
+  ["This review reached its time limit before finishing.", ["learning_batch_timeout"]],
+  ["Long-term memory or its embedding model is unavailable. Check Memory settings.", ["learning_memory_unavailable"]],
+  ["Learning storage is unavailable. Check Memory settings.", ["learning_storage_unavailable"]],
+  ["Review progress could not be saved. Processing stopped to avoid repeating completed model work. Earlier saved progress is kept within its retention limit.", ["learning_review_progress_storage_unavailable", "learning_review_progress_capacity"]],
+  ["Saved review progress could not be read safely. No changes from this review were applied.", ["learning_review_progress_invalid"]],
+  ["Saved review progress reached its retention limit. This review cannot continue from that checkpoint.", ["learning_review_progress_expired"]],
+  ["The staged review could not continue safely. No changes from this review were applied.", ["co_worker_review_stage_limit_invalid", "co_worker_review_stage_order_invalid"]],
+  ["Collection was turned off.", ["learning_disabled"]],
+  ["Processing was paused. Pending activity remains subject to its retention limit.", ["learning_processing_paused"]],
+  ["The pending activity was deleted.", ["learning_pending_deleted"]],
+  ["Processing stopped before this review finished.", ["learning_stopped"]],
+  ["This activity reached its retention limit before the review finished.", ["learning_batch_expired"]],
+  ["This review yielded resources to an active conversation.", ["learning_interactive_preempted"]],
+  ["This review was superseded by a newer learning state.", ["learning_generation_superseded"]],
+  ["One observation is too large for the selected model's context window.", ["learning_observation_exceeds_context"]],
+  ["The selected model's context capacity is too small for this review. Choose a model with a larger context window.", [
+    "request_context_final_envelope_exceeds_window", "request_context_required_content_exceeds_budget", "learning_review_context_exceeds_budget",
+  ]],
+  ["Waiting in smaller batches to fit the selected model.", ["learning_batch_partitioned"]],
+  ["Waiting because processing is turned off for an application. Pending activity remains subject to expiry and storage limits.", ["learning_application_processing_excluded"]],
+  ["This review is waiting for queue space to split safely. Its observations remain pending within the retention limit.", ["learning_partition_capacity"]],
+  ["The review referred to activity that could not be verified.", [
+    "learning_proposal_source_unknown", "learning_decision_source_unknown", "learning_proposal_device_mismatch", "learning_proposal_source_required",
+  ]],
+  ["The underlying knowledge changed before this review could be saved.", ["learning_knowledge_conflict"]],
+  ["Learning needs its embeddings updated before this review can be saved.", ["learning_embedding_reindex_required"]],
+  ["The review tried to change a memory protected by a manual edit.", ["learning_memory_protected"]],
+  ["The review could not be saved because its receipt storage limit was reached.", ["learning_receipt_capacity"]],
+  ["The proposed memory duplicates an existing item and needs an update instead.", ["learning_duplicate_requires_bound_update"]],
+  ["The model returned an invalid request to create a new candidate.", ["learning_create_target_invalid"]],
+  ["The model returned a learning decision with missing or unsupported fields. This review was not saved.", ["learning_review_output_contract_invalid"]],
+  ["The model returned an unreadable response format.", ["learning_output_invalid_json"]],
+  ["The model returned the wrong response structure.", ["learning_output_object_required"]],
+  ["The model's response did not include its learning decisions.", ["learning_output_decisions_missing"]],
+  ["The model returned its learning decisions in the wrong format.", ["learning_output_decisions_not_array"]],
+  ["The model returned more learning decisions than this review allows.", ["learning_output_decision_limit"]],
+  ["The model returned a decision that could not be accepted.", [
+    "learning_action_invalid", "learning_decision_invalid", "learning_decision_list_invalid",
+    "learning_decisions_invalid", "learning_target_invalid", "learning_target_kind_invalid", "learning_review_action_invalid",
+    "learning_review_cause_invalid", "learning_reason_invalid", "learning_merge_binding_invalid", "invalid_learning_proposal",
+  ]],
+  ["The review referred to an item that could not be found.", ["learning_decision_target_unknown", "learning_merge_source_unknown"]],
+  ["The review requested more than one change to the same item.", ["learning_decision_target_repeated"]],
+  ["The model returned an invalid candidate score.", ["learning_score_invalid", "learning_certainty_invalid"]],
+  ["The model returned a reinforcement decision that could not be accepted.", ["learning_reinforcement_invalid"]],
+  ["The proposed content is not valid for a memory.", ["learning_content_invalid"]],
+  ["The proposed content exceeds the memory size limit.", ["learning_content_exceeds_limit"]],
+  ["The proposed memory was blocked because it may contain sensitive information.", ["learning_content_sensitive"]],
+  ["The candidate could not be saved because its identity conflicts with an existing item.", ["learning_candidate_identity_conflict", "learning_candidate_identity_duplicate"]],
+  ["The candidate expired before this review could update it.", ["learning_candidate_expired"]],
+  ["Some saved learning data could not be read safely.", [
+    "learning_candidate_certainty_corrupt", "learning_candidate_embedding_missing", "learning_candidate_score_corrupt",
+    "learning_candidate_vector_binding_corrupt", "learning_candidate_vector_corrupt", "learning_candidates_corrupt",
+    "learning_maturation_store_corrupt", "learning_receipts_corrupt", "invalid_learning_state",
+  ]],
+  ["The learning policy contains an invalid setting.", ["learning_maturation_policy_invalid"]],
+  ["The model returned an invalid future review time.", ["learning_reconsideration_invalid", "learning_reconsideration_not_future"]],
+  ["The review requested a change that is not allowed without new supporting activity.", ["learning_review_cannot_raise_score", "learning_review_cannot_reinforce"]],
+  ["The scheduled review included activity it was not allowed to use.", ["learning_review_observations_unexpected"]],
+  ["This item is not due for another review yet.", ["learning_review_target_not_due"]],
+  ["The embedding configuration changed during this review.", ["long_term_memory_embedding_binding_changed"]],
+  ["The embedding request contained no usable text.", ["long_term_memory_embedding_input_empty"]],
+  ["The embedding provider returned data that could not be used.", ["long_term_memory_embedding_response_invalid", "long_term_memory_embedding_vector_count_invalid"]],
+  ["The collected batch could not be read safely.", ["invalid_learning_batch", "invalid_learning_batch_expiry"]],
+  ["The daily model-call limit was reached. Eligible work can continue after it resets.", ["co_worker_model_daily_budget_exhausted"]],
+  ["The daily embedding-call limit was reached. Eligible work can continue after it resets.", ["co_worker_embedding_daily_budget_exhausted"]],
+  ["The daily embedding-text limit was reached. Eligible work can continue after it resets.", ["co_worker_embedding_character_budget_exhausted"]],
+  ["The available model capacity is busy. This review must wait.", ["co_worker_resources_busy"]],
+  ["Computer activity collection is not supported on this platform.", ["platform_unsupported"]],
+  ["Computer activity collection needs a dependency that is unavailable.", ["macos_swift_tools_unavailable", "collector_dependency_unavailable"]],
+  ["The computer activity collector could not start.", ["collector_start_failed"]],
+  ["The computer activity collector returned data that could not be accepted.", ["collector_output_limit", "collector_protocol_invalid"]],
+  [genericMessage, ["learning_failed"]],
+];
+const messages = Object.freeze(Object.fromEntries(groups.flatMap(([message, codes]) => codes.map(code => [code, message]))));
+
+export function learningFailureCopy(reason) {
+  if (typeof reason === "string" && Object.hasOwn(messages, reason)) return { message: messages[reason], code: reason };
+  return { message: genericMessage, code: null };
+}

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

@@ -0,0 +1,101 @@
+import { hostSetupIsReady } from "../system-host/rendering.js";
+import { agentMarkup, renderAgent } from "./agent-view.js";
+import { createAgentMotion } from "./agent-motion.js";
+import { renderLearningProposals, handleProposalClick } from "./proposal-view.js";
+import { learningFailurePresentation } from "./presentation.js";
+import { homeActivityStartPatch, readActivityPermissions } from "./activity-controls.js";
+import { computerUpdateNoticeMarkup, renderComputerUpdateNotice } from "./computer-update-notice.js";
+import { macCollectionRestartNoticeMarkup, renderMacCollectionRestartNotice, handleMacCollectionRestartClick } from "./macos-collection-restart-notice.js";
+
+function canStartHomeLearning(snapshot) {
+  if (!homeActivityStartPatch(snapshot)) return false;
+  if (snapshot.statusError || learningFailurePresentation(snapshot.status))
+    return false;
+  if (readActivityPermissions(snapshot.status.preferences).collection)
+    return hostSetupIsReady(snapshot.hostConnection);
+  return true;
+}
+
+function homeLearningActionLabel(snapshot) {
+  if (hasIndependentHomeActivity(snapshot.status)) return "Open ABot Spark";
+  return canStartHomeLearning(snapshot)
+    ? "Start ABot Spark"
+    : "Set up ABot Spark";
+}
+
+export function hasIndependentHomeActivity(status) {
+  if (status?.preferences?.enabled) return true;
+  if (status?.preferences?.proactiveEnabled) return true;
+  if (status?.preferences?.modelProfileId && !status.preferences.processingPaused) return true;
+  return Boolean(status?.processing);
+}
+
+export function createPassiveLearningHome({
+  actions,
+  openLearning,
+  openSetup = openLearning,
+  openComputerAccess = openSetup,
+}) {
+  let root = null;
+  let renderedSnapshot = {};
+  let motion;
+
+  function mount(nextRoot) {
+    if (root === nextRoot) return;
+    motion?.dispose();
+    root?.removeEventListener("click", handleClick);
+    root = nextRoot;
+    if (!root) return;
+    root.innerHTML = `${computerUpdateNoticeMarkup()}${macCollectionRestartNoticeMarkup()}
+    <div class="home-learning-agent">${agentMarkup({
+      compact: true,
+      actionMarkup: '<button type="button" class="home-text-button" data-learning-open>Open ABot Spark</button>',
+    })}</div>
+    <div class="co-worker-proposals" data-learning-proposals></div>
+    <p class="home-learning-status" data-learning-status hidden></p>`;
+    root.addEventListener("click", handleClick);
+    motion = createAgentMotion(root);
+  }
+
+  function handleClick(event) {
+    if (handleMacCollectionRestartClick(root, event, actions)) return;
+    const update = event.target.closest("[data-learning-open-update]");
+    if (update && root.contains(update)) {
+      openComputerAccess();
+      return;
+    }
+    if (handleProposalClick(root, event, actions)) return;
+    const button = event.target.closest("[data-learning-open]");
+    if (!button || !root.contains(button) || button.disabled) return;
+    const snapshot = actions?.snapshot?.() ?? renderedSnapshot;
+    if (snapshot.saving || snapshot.loadingStatus) return;
+    if (hasIndependentHomeActivity(snapshot.status)) {
+      openLearning();
+      return;
+    }
+    if (!canStartHomeLearning(snapshot)) {
+      openSetup();
+      return;
+    }
+    void actions.configure(homeActivityStartPatch(snapshot));
+  }
+
+  function render(snapshot) {
+    renderedSnapshot = snapshot;
+    if (!root) return;
+    renderComputerUpdateNotice(root, snapshot);
+    renderMacCollectionRestartNotice(root, snapshot);
+    renderAgent(root, snapshot);
+    renderLearningProposals(root, snapshot, { limit: 1 });
+    motion?.update(snapshot);
+    root.hidden = false;
+    const action = root.querySelector("[data-learning-open]");
+    action.textContent = homeLearningActionLabel(snapshot);
+    action.disabled = Boolean(snapshot.saving || snapshot.loadingStatus);
+    const error = root.querySelector("[data-learning-status]");
+    error.textContent = snapshot.statusError || "";
+    error.hidden = !snapshot.statusError;
+  }
+
+  return Object.freeze({ mount, render });
+}

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

@@ -0,0 +1,137 @@
+import { escapeAttribute, escapeHtml } from "../../lib/text-format.js";
+import { learningTimeLabel } from "./presentation.js";
+
+const pageSize = 20;
+const views = new WeakMap();
+
+export function learningKnowledgeMarkup() {
+  return `<div class="co-worker-knowledge" data-learning-knowledge>
+    <section class="co-worker-knowledge-column" aria-label="Candidates">
+      <div class="co-worker-knowledge-heading"><div><h4>Candidates <span data-learning-candidate-count></span></h4>
+        <p>Patterns from conversations and computer activity.</p></div><span data-learning-threshold></span></div>
+      <p class="co-worker-knowledge-note" data-learning-candidate-note role="status" hidden></p>
+      <div class="co-worker-knowledge-list" data-learning-candidates></div>
+      <p class="co-worker-knowledge-note">Not used as memory yet. Promotion also requires two independent reinforcements. Scores are model judgments, not probabilities.</p>
+      <nav class="co-worker-knowledge-pagination" data-learning-pagination aria-label="Candidate pages" hidden>
+        <button type="button" data-learning-knowledge-page="previous" aria-label="Previous candidates">Previous</button>
+        <span data-learning-page-summary aria-live="polite"></span>
+        <button type="button" data-learning-knowledge-page="next" aria-label="Next candidates">Next</button>
+      </nav>
+    </section>
+    <section class="co-worker-knowledge-column" aria-label="Established memory">
+      <div class="co-worker-knowledge-heading"><div><h4>Established memory</h4>
+        <p>Recent memories <span data-learning-saved-count></span></p></div>
+        <button type="button" data-learning-memories>Manage memories</button></div>
+      <div class="co-worker-knowledge-list" data-learning-saved></div>
+      <p class="co-worker-knowledge-note" data-learning-history-note>Recent context from your activity. Manage memories opens the full list.</p>
+    </section>
+  </div>`;
+}
+
+export function renderLearningKnowledge(root, snapshot) {
+  const host = root.querySelector("[data-learning-knowledge]");
+  if (!host) return;
+  let view = views.get(root);
+  if (!view || view.host !== host || view.environmentId !== snapshot.environmentId) {
+    view = { host, page: 0, environmentId: snapshot.environmentId };
+    views.set(root, view);
+  }
+  view.snapshot = snapshot;
+  renderCandidates(view);
+  renderMemories(view);
+}
+
+export function handleKnowledgeClick(root, event) {
+  const button = event.target.closest?.("button[data-learning-knowledge-page]");
+  const view = views.get(root);
+  if (!button || !view || !view.host.contains(button) || button.disabled) return false;
+  const direction = button.dataset.learningKnowledgePage;
+  if (direction !== "previous" && direction !== "next") return false;
+  event.preventDefault();
+  view.page += direction === "next" ? 1 : -1;
+  renderCandidates(view);
+  return true;
+}
+
+function renderCandidates(view) {
+  const { host, snapshot } = view;
+  const candidates = Array.isArray(snapshot.candidates) ? snapshot.candidates : [];
+  view.page = Math.max(0, Math.min(view.page, Math.ceil(candidates.length / pageSize) - 1));
+  const offset = view.page * pageSize;
+  const threshold = boundedScore(snapshot.status?.preferences?.maturation?.promotionScore) ?? 90;
+  setText(host, "[data-learning-threshold]", `Promote at ${threshold}`);
+  setText(host, "[data-learning-candidate-count]", String(candidates.length));
+  const note = snapshot.candidateError ? `Candidates could not be refreshed: ${snapshot.candidateError}` : "";
+  setText(host, "[data-learning-candidate-note]", note);
+  host.querySelector("[data-learning-candidate-note]").hidden = !note;
+  const empty = snapshot.loadingCandidates ? "Loading candidates…"
+    : snapshot.candidateError ? "Candidates are unavailable. Refresh to try again."
+      : "No candidates yet. Useful patterns will appear here as ABot learns.";
+  const markup = candidates.length ? candidates.slice(offset, offset + pageSize).map(candidateMarkup).join("")
+    : `<p class="co-worker-knowledge-empty">${escapeHtml(empty)}</p>`;
+  replaceList(view, "candidateMarkup", "[data-learning-candidates]", markup);
+  host.querySelector("[data-learning-pagination]").hidden = candidates.length <= pageSize;
+  setText(host, "[data-learning-page-summary]", candidates.length
+    ? `${offset + 1}–${Math.min(offset + pageSize, candidates.length)} of ${candidates.length}` : "");
+  host.querySelector('[data-learning-knowledge-page="previous"]').disabled = view.page === 0;
+  host.querySelector('[data-learning-knowledge-page="next"]').disabled = offset + pageSize >= candidates.length;
+}
+
+function renderMemories(view) {
+  const { snapshot, host } = view;
+  const memories = Array.isArray(snapshot.status?.recentMemories) ? snapshot.status.recentMemories : [];
+  setText(host, "[data-learning-saved-count]", memories.length ? String(memories.length) : "");
+  const empty = !snapshot.status ? snapshot.statusError ? "Saved insights could not be loaded." : "Loading saved insights…"
+    : "No recent memories learned from activity. Open Manage memories to see everything already saved.";
+  const markup = memories.length ? memories.map((memory) => `<article class="co-worker-record">
+    ${recordContentMarkup(memory.content)}
+    <div class="co-worker-record-meta">${timeMarkup("Saved", memory.createdAt)}</div>
+  </article>`).join("") : `<p class="co-worker-knowledge-empty">${escapeHtml(empty)}</p>`;
+  replaceList(view, "memoryMarkup", "[data-learning-saved]", markup);
+}
+
+function candidateMarkup(candidate) {
+  const score = boundedScore(candidate.score);
+  const reinforcements = Array.isArray(candidate.reinforcements) ? candidate.reinforcements.length : 0;
+  const evidenceMarkup = "<span>" + Math.min(2, reinforcements) + " / 2 independent reinforcements</span>";
+  const dates = timeMarkup("Last reinforced", candidate.lastReinforcedAt) + timeMarkup("Expires", candidate.expiresAt);
+  const scoreMarkup = score === null ? "Not scored" : `<meter min="0" max="100" value="${score}" aria-label="Model assessment: ${score} out of 100">${score}</meter><span>${score} / 100</span>`;
+  return `<article class="co-worker-record" data-learning-candidate-id="${escapeAttribute(candidate.id)}">
+    ${recordContentMarkup(candidate.content)}
+    <div class="co-worker-record-footer"><span class="co-worker-record-score">${scoreMarkup}</span>
+      ${dates || candidate.reason ? `<details class="co-worker-record-details"><summary>Why this candidate</summary>
+        ${candidate.reason ? `<p class="co-worker-record-reason" dir="auto">${escapeHtml(candidate.reason)}</p>` : ""}
+        <div class="co-worker-record-meta">${evidenceMarkup}${dates}</div></details>` : ""}
+    </div>
+  </article>`;
+}
+
+function recordContentMarkup(value) {
+  const text = typeof value === "string" ? value : "";
+  if (text.length <= 240 && text.split("\n").length < 4)
+    return `<p class="co-worker-record-content" dir="auto">${escapeHtml(text)}</p>`;
+  return `<details class="co-worker-record-reading"><summary>
+    <span class="co-worker-record-content" dir="auto">${escapeHtml(text)}</span>
+    <span class="co-worker-record-read-more">Read more</span><span class="co-worker-record-read-less">Show less</span>
+  </summary></details>`;
+}
+
+function boundedScore(value) {
+  return typeof value === "number" && Number.isFinite(value) ? Math.min(100, Math.max(0, Math.round(value))) : null;
+}
+
+function timeMarkup(label, value) {
+  if (!Number.isFinite(Date.parse(value || ""))) return "";
+  return `<span>${label} <time datetime="${escapeAttribute(value)}">${escapeHtml(learningTimeLabel(value))}</time></span>`;
+}
+
+function setText(root, selector, value) {
+  const element = root.querySelector(selector);
+  if (element.textContent !== value) element.textContent = value;
+}
+
+function replaceList(view, key, selector, markup) {
+  if (view[key] === markup) return;
+  view[key] = markup;
+  view.host.querySelector(selector).innerHTML = markup;
+}

package/dist/src/web-ui/app/components/passive-learning/macos-collection-consent.js

@@ -0,0 +1,78 @@
+import { macCompanionPermissionPath } from "../system-host/macos-permissions.js";
+import { createMacPermissionDialog } from "../system-host/macos-permission-dialog.js";
+
+function requiresMacCollectionConsent(preferences, snapshot) {
+  if (preferences.enabled !== true) return false;
+  if (snapshot.status?.preferences?.enabled !== false) return false;
+  return Boolean(macCompanionPermissionPath(snapshot.hostConnection));
+}
+
+function collectionConsentContext(snapshot) {
+  const host = snapshot.hostConnection;
+  return JSON.stringify([
+    snapshot.environmentId,
+    host?.hostId,
+    host?.connected,
+    host?.connectionId,
+    host?.identity?.os,
+    host?.identity?.homeDir,
+    host?.companion?.installedVersion,
+  ]);
+}
+
+function canContinueCollectionStart(snapshot, context) {
+  if (snapshot.saving) return false;
+  if (snapshot.status?.preferences?.enabled !== false) return false;
+  if (!macCompanionPermissionPath(snapshot.hostConnection)) return false;
+  return collectionConsentContext(snapshot) === context;
+}
+
+/** Covers explicit collection starts from Home, Spark controls and Settings. */
+export function createMacCollectionConsent({
+  actions,
+  container,
+  createDialog = createMacPermissionDialog,
+}) {
+  let dialog;
+  let pending;
+
+  function cancel() {
+    pending = undefined;
+    dialog?.cancel();
+  }
+  async function confirmStart(preferences, request, path) {
+    try {
+      dialog ??= createDialog({ container });
+      const approved = await dialog.confirm(path);
+      if (pending !== request) return;
+      if (!approved) return;
+      if (!canContinueCollectionStart(actions.snapshot(), request.context))
+        return;
+      pending = undefined;
+      return actions.configure(preferences);
+    } finally {
+      if (pending === request) pending = undefined;
+    }
+  }
+  return {
+    configure(preferences) {
+      if (pending) return;
+      const snapshot = actions.snapshot();
+      if (!requiresMacCollectionConsent(preferences, snapshot))
+        return actions.configure(preferences);
+      if (snapshot.saving) return;
+      const request = { context: collectionConsentContext(snapshot) };
+      pending = request;
+      return confirmStart(
+        preferences,
+        request,
+        macCompanionPermissionPath(snapshot.hostConnection),
+      );
+    },
+    update(snapshot) {
+      if (!pending) return;
+      if (!canContinueCollectionStart(snapshot, pending.context)) cancel();
+    },
+    cancel,
+  };
+}

package/dist/src/web-ui/app/components/passive-learning/macos-collection-restart-notice.js

@@ -0,0 +1,52 @@
+const permissionReasons = new Set([
+  "macos_accessibility_permission_required",
+  "macos_accessibility_permission_timeout",
+  "macos_accessibility_permission_revoked",
+]);
+
+function hasEnabledMacCollection(snapshot) {
+  if (snapshot.hostConnection?.identity?.os !== "macos") return false;
+  return snapshot.status?.preferences?.enabled === true;
+}
+
+export function hasMacCollectionPermissionBlock(snapshot) {
+  if (!hasEnabledMacCollection(snapshot)) return false;
+  if (snapshot.status.collectionState !== "permission_required") return false;
+  return permissionReasons.has(snapshot.status.collectionReason);
+}
+
+function canRestartMacCollection(snapshot, actions) {
+  if (!hasMacCollectionPermissionBlock(snapshot)) return false;
+  if (snapshot.saving || snapshot.loadingStatus) return false;
+  if (snapshot.restartingCollection) return false;
+  return typeof actions.restartCollection === "function";
+}
+
+export function macCollectionRestartNoticeMarkup() {
+  return `<div class="co-worker-computer-update" data-learning-mac-restart hidden role="status">
+    <span class="co-worker-computer-update-icon" aria-hidden="true">↻</span>
+    <div class="co-worker-computer-update-copy"><p class="co-worker-computer-update-title">Spark needs Accessibility access</p>
+      <p>Already granted access? Restart collection to check again.</p></div>
+    <button type="button" data-learning-restart-collection>Restart collection</button>
+  </div>`;
+}
+
+export function renderMacCollectionRestartNotice(root, snapshot) {
+  const notice = root.querySelector("[data-learning-mac-restart]");
+  const blocked = hasMacCollectionPermissionBlock(snapshot);
+  const restartingMacCollection = hasEnabledMacCollection(snapshot) && snapshot.restartingCollection;
+  notice.hidden = !blocked && !restartingMacCollection;
+  notice.setAttribute("aria-busy", String(Boolean(snapshot.restartingCollection)));
+  const button = notice.querySelector("[data-learning-restart-collection]");
+  button.disabled = Boolean(snapshot.saving || snapshot.loadingStatus || snapshot.restartingCollection || !blocked);
+  button.textContent = snapshot.restartingCollection ? "Restarting collection…" : "Restart collection";
+}
+
+export function handleMacCollectionRestartClick(root, event, actions) {
+  const button = event.target.closest("[data-learning-restart-collection]");
+  if (!button || !root.contains(button)) return false;
+  if (button.disabled) return true;
+  if (!canRestartMacCollection(actions.snapshot(), actions)) return true;
+  void actions.restartCollection();
+  return true;
+}