@abot-ai/runtime 1.3.1 → 1.5.0

package/dist/src/web-ui/app/components/home-guidance/daily-review.js

@@ -0,0 +1,80 @@
+import { escapeHtml } from "../../lib/text-format.js";
+
+export function createDailyReviewDialog({ container, onDecision, onDismiss }) {
+  const documentRoot = container.ownerDocument;
+  const dialog = documentRoot.createElement("dialog");
+  dialog.className = "daily-memory-review";
+  dialog.setAttribute("aria-labelledby", "dailyMemoryTitle");
+  dialog.setAttribute("aria-describedby", "dailyMemoryDescription");
+  dialog.innerHTML = `<header><h2 id="dailyMemoryTitle">Review saved memories</h2>
+    <button type="button" data-review-close aria-label="Close daily memory review">×</button></header>
+    <p id="dailyMemoryDescription">Review memories saved by ABot Spark. Keep or delete each one.</p>
+    <div class="daily-review-progress"><span data-review-count></span><progress data-review-progress aria-label="Memories reviewed"></progress></div>
+    <article class="daily-review-card" data-review-card tabindex="0" aria-label="Memory review"></article>
+    <p class="daily-review-error" role="alert" data-review-error hidden></p>
+    <div class="daily-review-actions"><button type="button" data-review-delete>Delete memory</button>
+      <button type="button" data-review-keep>Keep memory</button></div>
+    <p class="daily-review-note">These memories are already saved. Keep marks them as reviewed in this browser.</p>
+    <button type="button" class="daily-review-later" data-review-later>Not now</button>`;
+  container.append(dialog);
+  let returnFocus;
+  const close = () => { dialog.close(); onDismiss(); };
+  dialog.querySelector("[data-review-close]").addEventListener("click", close);
+  dialog.querySelector("[data-review-later]").addEventListener("click", close);
+  dialog.addEventListener("cancel", (event) => { event.preventDefault(); close(); });
+  dialog.addEventListener("close", () => {
+    if (returnFocus?.isConnected && !returnFocus.closest("[hidden]")) returnFocus.focus();
+  });
+  dialog.querySelector("[data-review-delete]").addEventListener("click", () => void onDecision("delete"));
+  dialog.querySelector("[data-review-keep]").addEventListener("click", () => void onDecision("keep"));
+  function render(snapshot) {
+    const { items, index, busy, error } = snapshot;
+    const record = items[index];
+    const hasReviewLoadError = !record && Boolean(error);
+    let completionText = items.length ? "Review complete." : "No memories to review.";
+    if (hasReviewLoadError) completionText = "Review unavailable.";
+    const contentKey = record ? `${record.id}:${record.updatedAt}` : completionText;
+    const card = dialog.querySelector("[data-review-card]");
+    if (card.dataset.record !== contentKey) {
+      card.dataset.record = contentKey;
+      card.innerHTML = record
+        ? `<p dir="auto">${escapeHtml(record.content)}</p><span>Saved ${escapeHtml(new Date(record.createdAt).toLocaleDateString())}</span>`
+        : `<p>${completionText}</p>`;
+      card.scrollTop = 0;
+    }
+    const count = dialog.querySelector("[data-review-count]");
+    count.textContent = record ? `${index + 1} of ${items.length}` : `${items.length} reviewed`;
+    if (hasReviewLoadError) count.textContent = "";
+    dialog.querySelector(".daily-review-progress").hidden = hasReviewLoadError;
+    const progress = dialog.querySelector("progress");
+    progress.max = Math.max(1, items.length);
+    progress.value = hasReviewLoadError ? 0 : index;
+    dialog.querySelector("[data-review-error]").textContent = error;
+    dialog.querySelector("[data-review-error]").hidden = !error;
+    dialog.querySelector(".daily-review-actions").hidden = !record;
+    for (const button of dialog.querySelectorAll(".daily-review-actions button")) button.disabled = busy;
+    dialog.querySelector("[data-review-delete]").textContent = busy ? "Deleting…" : "Delete memory";
+    const later = dialog.querySelector("[data-review-later]");
+    later.textContent = record ? "Not now" : "Done";
+    if (hasReviewLoadError) later.textContent = "Close";
+    dialog.querySelector(".daily-review-note").hidden = hasReviewLoadError;
+    if (!record && dialog.open) dialog.querySelector("[data-review-later]").focus();
+  }
+  function canOpen() {
+    if (dialog.open || documentRoot.hidden) return false;
+    if (documentRoot.querySelector("dialog[open]")) return false;
+    const focused = documentRoot.activeElement;
+    return !focused?.matches("input, textarea, select, [contenteditable=true]");
+  }
+  return {
+    render, canOpen,
+    isOpen: () => dialog.open,
+    open() {
+      returnFocus = documentRoot.activeElement;
+      dialog.showModal();
+      dialog.querySelector("[data-review-later]").focus();
+    },
+    hide() { if (dialog.open) dialog.close(); },
+    dispose() { dialog.close(); dialog.remove(); },
+  };
+}

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

@@ -0,0 +1,160 @@
+import { createSystemHostVisibility } from "../system-host/visibility.js";
+import { hasIndependentHomeActivity } from "../passive-learning/home.js";
+import { selectHomeSuggestion } from "./suggestion-policy.js";
+import { createHomeGuidancePreferences } from "../../services/home-guidance-preferences.js";
+import { createDailyMemoryReview } from "../../controllers/daily-memory-review.js";
+import { createDailyReviewDialog } from "./daily-review.js";
+import { createDailyReviewEntry } from "./daily-review-entry.js";
+
+export function createHomeGuidance({ container, homeRegion, client, getEnvironmentId,
+  getLearningSnapshot, getConnectionState, supportsConnection, refreshConnection,
+  onOpen, isRuntimeReady = () => true, storage }) {
+  const documentRoot = container?.ownerDocument;
+  if (!documentRoot) return { render() {}, dispose() {} };
+  let preferenceStorage = storage;
+  try { preferenceStorage ??= documentRoot.defaultView?.localStorage; } catch { /* Session-only preferences. */ }
+  const preferences = createHomeGuidancePreferences(preferenceStorage);
+  const root = documentRoot.createElement("aside");
+  root.className = "home-guidance";
+  root.hidden = true;
+  root.setAttribute("aria-label", "Setup suggestion");
+  root.innerHTML = `<div class="home-guidance-copy"><h3 class="home-row-title"></h3><p class="home-row-detail"></p></div>
+    <button type="button" class="home-text-button" data-guidance-open></button>
+    <button type="button" class="home-text-button" data-guidance-dismiss aria-label="Dismiss this suggestion" title="Hide this suggestion"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="m4 4 8 8m0-8-8 8" /></svg></button>`;
+  const reviewEntry = createDailyReviewEntry({ container, onOpen: openMemoryReview });
+  container.prepend(root);
+  let environment = getEnvironmentId();
+  let revision = 0;
+  let memory = null;
+  let plugins = null;
+  let visible = false;
+  let loaded = false;
+  let loading = false;
+  let disposed = false;
+  let hiddenThisVisit = false;
+  let selected = null;
+  let reviewDismissed = false;
+  let openingReview = false;
+  let review;
+  const dialog = createDailyReviewDialog({ container,
+    onDecision: (action) => review.decide(action),
+    onDismiss: () => { reviewDismissed = true; render(); },
+  });
+  review = createDailyMemoryReview({ client, getEnvironmentId, preferences, render: (snapshot) => {
+    dialog.render(snapshot);
+    if (canOfferDailyReview(snapshot) && dialog.canOpen() && review.markOffered()) dialog.open();
+    renderSuggestion();
+  } });
+  root.querySelector("[data-guidance-open]").addEventListener("click", () => {
+    if (root.hidden || !selected) return;
+    onOpen(selected.id);
+  });
+  root.querySelector("[data-guidance-dismiss]").addEventListener("click", () => {
+    if (!selected) return;
+    preferences.dismiss(environment, selected.id);
+    hiddenThisVisit = true;
+    renderSuggestion();
+  });
+  const visibility = createSystemHostVisibility({ documentRoot, getRoot: () => homeRegion,
+    isActive: () => Boolean(homeRegion), onChange: visibilityChanged });
+
+  async function loadSuggestions() {
+    if (loading || disposed || !visible || !isRuntimeReady()) return;
+    loading = true;
+    const operation = ++revision;
+    const target = getEnvironmentId();
+    const [memoryRead, pluginsRead] = await Promise.allSettled([
+      client.loadLongTermMemoryStatus(target), client.getRuntimePlugins(target),
+    ]);
+    if (operation !== revision || target !== getEnvironmentId() || disposed) return;
+    memory = memoryRead.status === "fulfilled" ? memoryRead.value?.status : null;
+    plugins = pluginsRead.status === "fulfilled" ? pluginsRead.value : null;
+    loading = false;
+    loaded = true;
+    render();
+  }
+  function renderSuggestion() {
+    reviewEntry.render({ visible: canShowMemoryReviewEntry(),
+      remaining: review?.snapshot().remaining || 0, loading: openingReview });
+    selected = selectHomeSuggestion({ memory, plugins,
+      connection: supportsConnection() ? getConnectionState() : null,
+      dismissed: preferences.dismissed(environment) });
+    root.hidden = !visible || hiddenThisVisit || dialog.isOpen() || !selected;
+    if (root.hidden) return;
+    root.querySelector("h3").textContent = selected.title;
+    root.querySelector("p").textContent = selected.description;
+    root.querySelector("[data-guidance-open]").textContent = selected.action;
+  }
+  function hasCurrentLearningActivity() {
+    const learning = getLearningSnapshot();
+    if (learning?.environmentId !== environment || learning.statusError) return false;
+    return hasIndependentHomeActivity(learning.status);
+  }
+  function canReviewSavedMemories() {
+    if (disposed || !visible || !isRuntimeReady()) return false;
+    if (memory?.enabled === false) return false;
+    if (memory?.available === false) return false;
+    if (hasCurrentLearningActivity()) return true;
+    return memory?.enabled === true && memory?.available !== false;
+  }
+  function canShowMemoryReviewEntry() {
+    if (!canReviewSavedMemories() || dialog.isOpen()) return false;
+    return review?.snapshot().remaining > 0;
+  }
+  function canOfferDailyReview(snapshot) {
+    if (!visible || reviewDismissed || !snapshot.remaining) return false;
+    return hasCurrentLearningActivity();
+  }
+  async function openMemoryReview() {
+    if (openingReview || !canReviewSavedMemories() || !dialog.canOpen()) return;
+    const operation = revision;
+    const target = environment;
+    openingReview = reviewDismissed = true;
+    renderSuggestion();
+    const loadedReview = await review.loadForReview();
+    if (disposed || operation !== revision || target !== getEnvironmentId()) return;
+    openingReview = false;
+    if (loadedReview && canReviewSavedMemories() && dialog.canOpen()) {
+      review.markOffered();
+      dialog.open();
+    }
+    renderSuggestion();
+  }
+  function syncEnvironment() {
+    const next = getEnvironmentId();
+    if (next === environment) return;
+    revision += 1;
+    environment = next;
+    memory = plugins = null;
+    loaded = loading = hiddenThisVisit = reviewDismissed = openingReview = false;
+    dialog.hide();
+    review.reset();
+  }
+  function render() {
+    if (disposed) return;
+    syncEnvironment();
+    if (visible && !loaded && !loading) void loadSuggestions();
+    const canReview = canReviewSavedMemories();
+    review.update(canReview);
+    if (!canReview) dialog.hide();
+    renderSuggestion();
+  }
+  function visibilityChanged() {
+    if (disposed) return;
+    const next = visibility.isVisible();
+    if (next === visible) return;
+    visible = next;
+    if (visible) {
+      hiddenThisVisit = reviewDismissed = false;
+      loaded = false;
+      if (supportsConnection()) void refreshConnection();
+    } else {
+      openingReview = false;
+      dialog.hide();
+    }
+    render();
+  }
+  visibility.watch();
+  visibilityChanged();
+  return { render, dispose() { disposed = true; revision += 1; review.reset(); visibility.dispose(); dialog.dispose(); reviewEntry.dispose(); root.remove(); } };
+}

package/dist/src/web-ui/app/components/home-guidance/suggestion-policy.js

@@ -0,0 +1,35 @@
+import { needsComputerSetup } from "../system-host/setup-notice.js";
+
+const suggestions = {
+  memory: {
+    id: "memory", icon: "memory", title: "Set up passive memory",
+    description: "Keep useful context between conversations. Choose an embedding model to get started.",
+    action: "Set up memory",
+  },
+  computer: {
+    id: "computer", icon: "computer", title: "Connect your computer",
+    description: "Access local apps and tools, with permissions you control.",
+    action: "Connect computer",
+  },
+  plugin: {
+    id: "plugin", icon: "memory", title: "Review your memory setup",
+    description: "Passive memory is ready. Review whether you still need the separate memory plugin.",
+    action: "Review memory plugin",
+  },
+};
+
+function hasEnabledMemoryPlugin(plugins) {
+  const plugin = plugins?.plugins?.find((item) => item.id === "memory");
+  if (!plugin || plugin.blockedByGlobalPolicy) return false;
+  if (plugin.pluginEnabled === false) return false;
+  return plugin.selectedCapabilityCount > 0;
+}
+
+export function selectHomeSuggestion({ memory, plugins, connection, dismissed = [] }) {
+  const eligible = [];
+  if (memory?.enabled === false) eligible.push("memory");
+  if (needsComputerSetup(connection)) eligible.push("computer");
+  const memoryReady = memory?.enabled === true && memory.available !== false;
+  if (memoryReady && hasEnabledMemoryPlugin(plugins)) eligible.push("plugin");
+  return suggestions[eligible.find((id) => !dismissed.includes(id))] || null;
+}

package/dist/src/web-ui/app/components/long-term-memory/manager.js

@@ -55,6 +55,8 @@ export function createLongTermMemoryManager({
     if (action === "edit") actions.beginEdit(recordId);
     if (action === "cancel-edit") actions.cancelEdit();
     if (action === "clear-search") void actions.search("");
+    if (action === "toggle-origin")
+      void actions.setOriginFilter(view.originFilter ? "" : "passive_observation");
     if (action === "previous-page") void actions.changePage(-1);
     if (action === "next-page") void actions.changePage(1);
     if (action === "delete") confirmAndDelete(recordId);
@@ -109,7 +111,11 @@ export function createLongTermMemoryManager({
     );
   }
 
-  return Object.freeze({ mount, render });
+  return Object.freeze({
+    mount,
+    render,
+    focus: () => root?.querySelector(".memory-management-heading h4")?.scrollIntoView({ block: "start" }),
+  });
 }
 
 function managerMarkup(view) {
@@ -124,6 +130,7 @@ function managerMarkup(view) {
       </div>
       ${availabilityMarkup(view)}
       <div class="memory-management-toolbar">
+        <button class="memory-origin-filter" type="button" data-memory-management-action="toggle-origin" aria-pressed="${!view.query && view.originFilter === "passive_observation"}" ${view.query ? "disabled title=\"Activity filter is paused during semantic search\"" : ""}>Computer activity${view.query && view.originFilter ? " (paused)" : ""}</button>
         <form class="memory-search" role="search" data-memory-search-form>
           <label class="sr-only" for="memoryManagementSearch">Search stored memories</label>
           <div class="memory-search-shell">

package/dist/src/web-ui/app/components/long-term-memory/record-list.js

@@ -43,6 +43,7 @@ function renderMemoryRecord(record, view) {
               Updated ${escapeHtml(formatMemoryTimestamp(record.updatedAt))}
             </time>
           </div>
+          ${renderObservationSources(record.observationSources)}
         </div>
       </div>
       <div class="memory-record-actions">
@@ -69,6 +70,12 @@ function renderMemoryRecord(record, view) {
   `;
 }
 
+function renderObservationSources(sources) {
+  if (!Array.isArray(sources) || sources.length === 0) return "";
+  return `<details class="memory-observation-sources"><summary>Activity sources (${sources.length})</summary><ul>${sources.map((source) =>
+    `<li>${escapeHtml(String(source.kind || "Observation"))} · ${escapeHtml(formatMemoryTimestamp(source.observedAt))}${source.reason ? ` · ${escapeHtml(String(source.reason))}` : ""}${source.certainty ? ` · ${escapeHtml(String(source.certainty))}` : ""}</li>`).join("")}</ul></details>`;
+}
+
 function renderContent(content) {
   const collapsible = memoryContentNeedsExpansion(content);
   return `

package/dist/src/web-ui/app/components/long-term-memory/view-model.js

@@ -12,6 +12,8 @@ export function createMemoryManagerView(snapshot) {
     status: memoryStatus(snapshot),
     emptyMessage: snapshot.query
       ? "No memories match this search."
+      : snapshot.originFilter === "passive_observation"
+        ? "No memories from computer activity yet."
       : "No long-term memories have been stored yet.",
     pageLabel: pageLabel(snapshot),
     hasPreviousPage: snapshot.offset > 0,
@@ -38,6 +40,7 @@ export function formatMemoryTimestamp(value) {
 export function memoryOriginLabel(origin) {
   const labels = {
     passive_response: "Learned from conversation",
+    passive_observation: "Learned from computer activity",
     web_ui: "Added in Web UI",
     management_api: "Added through API",
   };

package/dist/src/web-ui/app/components/long-term-memory/workspace.js

@@ -0,0 +1,48 @@
+function memoryTabIndexForKey(key, index, count) {
+  if (key === "Home") return 0;
+  if (key === "End") return count - 1;
+  if (key === "ArrowRight") return (index + 1) % count;
+  if (key === "ArrowLeft") return (index + count - 1) % count;
+  return -1;
+}
+
+export function createMemoryWorkspace({ root }) {
+  const tabs = ["memories", "setup"].map((name) => ({
+    name,
+    button: root?.querySelector('[data-memory-tab="' + name + '"]'),
+    panel: root?.querySelector('[data-memory-panel="' + name + '"]'),
+  }));
+
+  function hasMemoryTabSurface(tab) {
+    if (!tab?.button) return false;
+    return Boolean(tab.panel);
+  }
+
+  function activate(name, { focus = false } = {}) {
+    const selected = tabs.find((tab) => tab.name === name);
+    if (!hasMemoryTabSurface(selected)) return false;
+    for (const tab of tabs) {
+      if (!hasMemoryTabSurface(tab)) continue;
+      const active = tab === selected;
+      tab.panel.hidden = !active;
+      tab.button.setAttribute("aria-selected", String(active));
+      tab.button.tabIndex = active ? 0 : -1;
+      tab.button.classList.toggle("active", active);
+    }
+    if (focus) selected.button.focus();
+    return true;
+  }
+
+  tabs.forEach((tab, index) => {
+    if (!hasMemoryTabSurface(tab)) return;
+    tab.button.addEventListener("click", () => activate(tab.name));
+    tab.button.addEventListener("keydown", (event) => {
+      const nextIndex = memoryTabIndexForKey(event.key, index, tabs.length);
+      if (nextIndex < 0) return;
+      event.preventDefault();
+      activate(tabs[nextIndex].name, { focus: true });
+    });
+  });
+  activate("memories");
+  return { activate };
+}

package/dist/src/web-ui/app/components/model-setup/rendering.js

@@ -0,0 +1,99 @@
+import { escapeHtml } from "../../lib/text-format.js";
+import { formatContextWindowTokens } from "../runtime-setup/context-window.js";
+import {
+  renderConnectionField,
+  renderConnectionFields,
+  renderProviderChoices,
+} from "../runtime-setup/connection-form.js";
+import { renderWizardShell } from "../runtime-setup/wizard-shell.js";
+import {
+  modelProviderType,
+  selectedModelProvider,
+  requiresModelCredential,
+} from "./validation.js";
+
+export const MODEL_SETUP_STEPS = ["Provider", "Model", "Ready"];
+export const MODEL_SETUP_ID = "addModelSetup";
+
+export function modelSetupTitles(state) {
+  return [
+    "Choose a provider",
+    "Add your model",
+    state.applied
+      ? "Model applied"
+      : state.saved
+        ? "Model saved"
+        : "Review your model",
+  ];
+}
+
+export function renderModelProviderChoices(state) {
+  const providers = state.providers.map((provider) => ({
+    id: `existing:${provider.id}`,
+    label: provider.label || provider.id,
+    description: `${provider.id} · ${provider.type} · existing connection`,
+  }));
+  providers.push(
+    {
+      id: "new:openai",
+      label: "New OpenAI connection",
+      description: "A separate connection using your API key",
+    },
+    {
+      id: "new:ollama",
+      label: "New Ollama connection",
+      description: "A model on your computer or server",
+    },
+  );
+  return renderProviderChoices({ providers, provider: state.choice });
+}
+
+export function renderModelFields(state) {
+  const provider = selectedModelProvider(state);
+  const credentialConfigured = !requiresModelCredential(state);
+  return `${!provider ? renderConnectionField({ field: "connection-id", label: "Connection ID", value: state.newProviderId, idPrefix: MODEL_SETUP_ID, help: "A unique name for this provider connection." }) : `<p class="runtime-setup-feedback">Using ${escapeHtml(provider.label || provider.id)} · ${escapeHtml(provider.id)}</p>`}
+    ${renderConnectionFields({ providers: [{ id: state.choice, credentialConfigured }], provider: state.choice, providerType: modelProviderType(state), existingProvider: Boolean(provider), allowCredentialReplacement: false, modelId: state.model, contextWindowTokens: state.contextWindowTokens, baseUrl: state.baseUrl, idPrefix: MODEL_SETUP_ID })}
+    ${renderConnectionField({ field: "profile-id", label: "Model profile ID", value: state.profileId, idPrefix: MODEL_SETUP_ID, placeholder: "Suggested from the model ID", help: "A unique name for this model in ABot. Existing model defaults will stay the same." })}`;
+}
+
+export function renderModelReview(state) {
+  const provider = selectedModelProvider(state);
+  return `<div class="runtime-setup-result"><dl><div><dt>Connection</dt><dd>${escapeHtml(provider?.id || state.newProviderId)}</dd></div><div><dt>Model</dt><dd>${escapeHtml(state.model)}</dd></div><div><dt>Context window</dt><dd>${escapeHtml(formatContextWindowTokens(state.contextWindowTokens))}</dd></div><div><dt>Profile</dt><dd>${escapeHtml(state.profileId)}</dd></div></dl><p>${state.applied ? "Your model is applied. Refresh the model list to continue." : state.saved ? "Your model is saved. Apply it when your agent is idle." : "Save this model and apply the configuration. This does not send a model request."}</p></div>`;
+}
+
+export function modelSetupFooter(state) {
+  const disabled = state.busy ? "disabled" : "";
+  const back =
+    state.step > 0 && !state.saved
+      ? `<button type="button" class="runtime-setup-secondary" data-model-action="back" data-runtime-setup-action="model-back" ${disabled}>Back</button>`
+      : "";
+  const label = state.busy
+    ? state.busy === "saving"
+      ? "Saving…"
+      : state.busy === "applying"
+        ? "Applying…"
+        : "Loading…"
+    : state.step < 2
+      ? "Continue"
+      : state.applied
+        ? "Refresh model list"
+        : state.saved
+          ? "Apply model"
+          : "Save and apply";
+  const action = state.step === 2 ? "finish" : "next";
+  return `<div class="model-setup-back-actions"><button type="button" class="runtime-setup-secondary" data-model-action="cancel" data-runtime-setup-action="model-cancel" ${disabled}>${state.saved ? "Close" : "Cancel"}</button>${back}</div><button type="button" class="runtime-setup-action" data-model-action="${action}" data-runtime-setup-action="model-${action}" ${state.busy || !state.loaded || !state.choice ? "disabled" : ""}>${label}</button>`;
+}
+
+export function modelSetupMarkup(state) {
+  return renderWizardShell({
+    steps: MODEL_SETUP_STEPS,
+    step: state.step,
+    title: modelSetupTitles(state)[state.step],
+    form: false,
+    idPrefix: MODEL_SETUP_ID,
+    panelClass: "model-setup-panel",
+    content:
+      '<div data-model-providers></div><form data-model-form novalidate></form><div data-model-review hidden></div><p class="runtime-setup-feedback" data-model-feedback id="addModelSetupError" role="status"></p><button type="button" class="runtime-setup-inline-action" data-model-action="reload" data-runtime-setup-action="model-reload" hidden>Try again</button>',
+    footer: modelSetupFooter(state),
+  });
+}

package/dist/src/web-ui/app/components/model-setup/save-flow.js

@@ -0,0 +1,116 @@
+import { selectedModelProvider } from "./validation.js";
+import {
+  isDefinitiveModelSaveRejection,
+  modelSaveErrorMessage,
+  deferredModelMessage,
+} from "./save-outcome.js";
+
+export function createModelSaveFlow({
+  state,
+  beginOperation,
+  isCurrent,
+  settleStaleOperation,
+  readRequest,
+  clearSecret,
+  render,
+  closeCompleted,
+  saveModel,
+  applySetup,
+  beginRuntimeMutation,
+  endRuntimeMutation,
+  onSaved,
+  onDeferred,
+  onComplete,
+}) {
+  async function refreshModelList(operation) {
+    state.busy = "refreshing";
+    render();
+    const refreshed = await onComplete(state.saved);
+    if (!isCurrent(operation)) return false;
+    if (refreshed === false) {
+      state.error = "Model applied. Refresh the model list to continue.";
+      return false;
+    }
+    return true;
+  }
+
+  async function finish() {
+    if (state.busy) return false;
+    if (!beginRuntimeMutation("model settings")) {
+      state.error =
+        "Save or reset configuration changes before adding a model.";
+      render();
+      return false;
+    }
+    const operation = beginOperation();
+    let completed = false;
+    try {
+      state.error = "";
+      state.notice = "";
+      if (!state.saved) {
+        const input = readRequest();
+        if (!input) return false;
+        clearSecret();
+        state.busy = "saving";
+        render();
+        let payload;
+        try {
+          payload = await saveModel(input);
+        } finally {
+          delete input.apiKey;
+        }
+        if (!isCurrent(operation)) return false;
+        if (
+          !payload?.model?.profileId ||
+          !payload.model.providerId ||
+          !payload.model.model
+        )
+          throw new Error("Saved model identity unavailable");
+        state.saveOutcomeUncertain = false;
+        state.saved = payload.model;
+        onSaved(state.saved);
+      }
+      if (!state.applied) {
+        state.busy = "applying";
+        render();
+        const payload = await applySetup();
+        if (!isCurrent(operation)) return false;
+        if (payload?.activation?.status === "restart_required") {
+          state.notice = deferredModelMessage(payload.activation);
+          state.busy = "refreshing";
+          render();
+          const refreshed = await onDeferred(state.saved);
+          if (!isCurrent(operation)) return false;
+          if (refreshed === false) state.error = modelSaveErrorMessage(state);
+          return false;
+        }
+        if (payload?.activation?.status !== "ready")
+          throw new Error("Model application unavailable");
+        state.applied = true;
+      }
+      completed = await refreshModelList(operation);
+    } catch (error) {
+      if (!isCurrent(operation)) return false;
+      if (state.busy === "saving")
+        state.saveOutcomeUncertain = !isDefinitiveModelSaveRejection(error);
+      const credentialSaved = error?.payload?.credentialSaved === true;
+      if (credentialSaved)
+        state.credentialSavedFor =
+          selectedModelProvider(state)?.id || state.newProviderId;
+      state.error = modelSaveErrorMessage(state, error);
+      if (credentialSaved)
+        state.error +=
+          " Your API key was saved privately and will be reused on retry.";
+    } finally {
+      endRuntimeMutation();
+      if (isCurrent(operation)) {
+        state.busy = "";
+        if (completed) closeCompleted();
+        else render();
+      } else settleStaleOperation(operation);
+    }
+    return completed;
+  }
+
+  return { finish };
+}

package/dist/src/web-ui/app/components/model-setup/save-outcome.js

@@ -0,0 +1,32 @@
+/** Only a canonical client-error response proves that this save was rejected. */
+export function isDefinitiveModelSaveRejection(error) {
+  if (!Number.isInteger(error?.status)) return false;
+  if (error.status < 400) return false;
+  if (error.status >= 500) return false;
+  return typeof error.payload?.error === "string";
+}
+
+export function modelSaveFailureMessage(state) {
+  if (state.applied) return "Model applied. Could not refresh the model list.";
+  if (state.saved && state.busy === "refreshing")
+    return "Model saved. It is not active yet. Could not refresh the model list.";
+  if (state.saved)
+    return "Model saved. Could not apply the configuration. Try again when your agent is idle.";
+  if (state.saveOutcomeUncertain)
+    return "The model save could not be confirmed. Try again to check the saved model and apply it.";
+  return "Could not save this model. Check the connection details and try again.";
+}
+
+export function modelSaveErrorMessage(state, error) {
+  const fallback = modelSaveFailureMessage(state);
+  const detail = error?.payload?.message;
+  if (!detail) return fallback;
+  if (state.saved) return `${fallback} ${detail}`;
+  return detail;
+}
+
+export function deferredModelMessage(activation) {
+  const status = "Model saved. It is not active yet.";
+  if (!activation.message) return `${status} Apply it when your agent is idle.`;
+  return `${status} ${activation.message}`;
+}