@abot-ai/runtime 1.3.0 → 1.4.0

package/dist/src/web-ui/app/components/runtime-config-activation.js

@@ -0,0 +1,83 @@
+/** Explicit application of saved files; presentation never stops an owner itself. */
+export function createRuntimeConfigActivation({
+  root,
+  getWorkspace,
+  apply,
+  refresh,
+  getEnvironmentId,
+  onAppliedSettled = () => true,
+}) {
+  if (!root?.ownerDocument) return { markPending() {}, markApplied() {} };
+  const panel = root.ownerDocument.createElement("section");
+  panel.className = "runtime-config-activation";
+  panel.setAttribute("aria-label", "Apply saved configuration");
+  panel.innerHTML =
+    '<p role="status" aria-live="polite">Apply saved changes when your agent is idle.</p><button type="button">Apply changes</button>';
+  const status = panel.querySelector("p");
+  const button = panel.querySelector("button");
+  root.prepend(panel);
+  let busy = false;
+
+  function markPending() {
+    status.textContent = "Changes saved. Apply them to update your agent.";
+  }
+
+  function markApplied() {
+    status.textContent = "Saved changes are now active.";
+  }
+
+  async function applySavedConfiguration() {
+    if (busy) return;
+    const workspace = getWorkspace();
+    if (!workspace?.beginExternalRuntimeMutation("saved configuration")) return;
+    const environment = getEnvironmentId();
+    let activated = false;
+    busy = true;
+    button.disabled = true;
+    status.textContent = "Applying saved changes…";
+    try {
+      const result = await apply();
+      if (environment !== getEnvironmentId()) return;
+      if (result?.activation?.status !== "ready") {
+        status.textContent =
+          result?.activation?.message ||
+          "Saved changes are waiting to be applied.";
+        return;
+      }
+      activated = true;
+      const refreshed = await refresh();
+      if (environment !== getEnvironmentId()) return;
+      status.textContent =
+        refreshed === false
+          ? "Changes applied. Refresh configuration to update this view."
+          : "Saved changes are now active.";
+    } catch (error) {
+      if (environment !== getEnvironmentId()) return;
+      if (activated) {
+        status.textContent =
+          "Changes applied. Refresh configuration to update this view.";
+      } else {
+        status.textContent =
+          error instanceof Error
+            ? error.message
+            : "Changes could not be applied. Try again.";
+      }
+    } finally {
+      busy = false;
+      button.disabled = false;
+      workspace.endExternalRuntimeMutation();
+      if (environment !== getEnvironmentId()) {
+        status.textContent =
+          "Environment changed. Apply saved changes when your agent is idle.";
+      }
+    }
+    if (!activated) return;
+    if (environment !== getEnvironmentId()) return;
+    if (onAppliedSettled() === false)
+      status.textContent =
+        "Changes applied. Finish your current edits, then refresh configuration to update environments.";
+  }
+
+  button.addEventListener("click", applySavedConfiguration);
+  return { markPending, markApplied };
+}

package/dist/src/web-ui/app/components/runtime-setup/bridge-guide.d.ts

@@ -0,0 +1,9 @@
+import type { createRuntimeSetupGuide } from "../runtime-setup-guide.js";
+
+export declare function createBridgeSetupGuide(options: {
+  container: HTMLElement;
+  conversationRegion: HTMLElement;
+  getEnvironmentId?(): string;
+  getSetupCommandMode?(): "source" | "package" | undefined;
+  copyText?(value: string): Promise<void>;
+}): ReturnType<typeof createRuntimeSetupGuide>;

package/dist/src/web-ui/app/components/runtime-setup/bridge-guide.js

@@ -0,0 +1,198 @@
+import { textOf } from "../../lib/text-format.js";
+import { renderBridgeSetup } from "./bridge-rendering.js";
+import { buildBridgeSetupCommands } from "./commands.js";
+import { createSetupViewState } from "./view-state.js";
+import { showConnectionFieldError } from "./connection-form.js";
+import { selectSetupProvider } from "./connection-state.js";
+import {
+  DEFAULT_OLLAMA_BASE_URL,
+  validateRuntimeSetupBaseUrl,
+  validateRuntimeSetupModelId,
+} from "./validation.js";
+
+export function createBridgeSetupGuide({
+  container,
+  conversationRegion,
+  getEnvironmentId = () => "",
+  getSetupCommandMode = () => "source",
+  copyText = (value) => navigator.clipboard.writeText(value),
+}) {
+  const state = {
+    provider: "",
+    modelId: "",
+    baseUrl: DEFAULT_OLLAMA_BASE_URL,
+    step: 0,
+    error: "",
+  };
+  const viewState = createSetupViewState(container);
+  let availability = { status: "loading" };
+  let environmentId = getEnvironmentId();
+  let revision = 0;
+  let bound = false;
+  let onCheckAgain = () => {};
+
+  function reset() {
+    revision += 1;
+    Object.assign(state, {
+      provider: "",
+      modelId: "",
+      baseUrl: DEFAULT_OLLAMA_BASE_URL,
+      step: 0,
+      error: "",
+    });
+    viewState.reset();
+  }
+
+  function paint(focus = false) {
+    viewState.capture();
+    container.innerHTML = renderBridgeSetup(
+      state,
+      availability,
+      getSetupCommandMode(),
+    );
+    viewState.restore({ focus, busy: availability.status === "checking" });
+  }
+
+  function showFieldError(field, message) {
+    state.error = message;
+    paint();
+    showConnectionFieldError(container, field);
+    return false;
+  }
+
+  function validateBridgeConnection() {
+    if (!state.provider)
+      return showFieldError("provider", "Choose a provider.");
+    const model = validateRuntimeSetupModelId(state.modelId);
+    if (!model.valid) return showFieldError("model-id", model.message);
+    if (state.provider !== "ollama") return true;
+    const address = validateRuntimeSetupBaseUrl(state.baseUrl);
+    if (!address.valid)
+      return showFieldError("ollama-base-url", address.message);
+    return true;
+  }
+
+  async function copyCommand(commandId) {
+    if (
+      !["ollama-pull", "setup", "model-gateway", "web-ui"].includes(commandId)
+    )
+      return;
+    if (!validateBridgeConnection()) return;
+    const commands = buildBridgeSetupCommands(
+      state.provider,
+      state.modelId,
+      state.baseUrl,
+      getSetupCommandMode(),
+    );
+    if (!commands[commandId]) return;
+    const operationRevision = revision;
+    const operationEnvironment = getEnvironmentId();
+    let message = "Copied";
+    try {
+      await copyText(commands[commandId]);
+    } catch {
+      message = "Could not copy";
+    }
+    const copyIsCurrent =
+      operationRevision === revision &&
+      operationEnvironment === getEnvironmentId();
+    if (!copyIsCurrent) return;
+    const status = container.querySelector(
+      `[data-runtime-copy-status="${commandId}"]`,
+    );
+    if (status) status.textContent = message;
+  }
+
+  function submit(event) {
+    event.preventDefault();
+    if (availability.status === "checking" || state.step !== 0) return;
+    if (!validateBridgeConnection()) return;
+    state.step = 1;
+    state.error = "";
+    revision += 1;
+    paint(true);
+  }
+
+  function click(event) {
+    if (availability.status === "checking") return;
+    const target = event.target.closest?.("[data-runtime-setup-action]");
+    const action = target?.dataset.runtimeSetupAction;
+    if (action === "check") void onCheckAgain();
+    if (action === "copy" && state.step === 1)
+      void copyCommand(target.dataset.runtimeCommand);
+    if (action !== "back") return;
+    state.step = 0;
+    state.error = "";
+    revision += 1;
+    paint(true);
+  }
+
+  function change(event) {
+    if (availability.status === "checking" || state.step !== 0) return;
+    const field = event.target.closest?.("[data-runtime-setup-field]");
+    if (field?.dataset.runtimeSetupField !== "provider") return;
+    selectSetupProvider(state, field.value);
+    state.error = "";
+    revision += 1;
+    paint();
+    container
+      .querySelector(
+        `[data-runtime-setup-field="provider"][value="${state.provider}"]`,
+      )
+      ?.focus?.({ preventScroll: true });
+  }
+
+  function input(event) {
+    if (availability.status === "checking" || state.step !== 0) return;
+    const field = event.target.closest?.("[data-runtime-setup-field]");
+    if (!field) return;
+    if (field.dataset.runtimeSetupField === "model-id")
+      state.modelId = textOf(field.value);
+    if (field.dataset.runtimeSetupField === "ollama-base-url")
+      state.baseUrl = textOf(field.value);
+    field.removeAttribute?.("aria-invalid");
+    revision += 1;
+  }
+
+  function bind({ onCheckAgain: checkAgain = () => {} } = {}) {
+    onCheckAgain = checkAgain;
+    if (bound) return;
+    bound = true;
+    container.addEventListener("submit", submit);
+    container.addEventListener("click", click);
+    container.addEventListener("change", change);
+    container.addEventListener("input", input);
+  }
+
+  function render(setup) {
+    availability = setup || { status: "loading" };
+    if (environmentId !== getEnvironmentId()) {
+      reset();
+      environmentId = getEnvironmentId();
+    }
+    const visible =
+      availability.showGuide !== false &&
+      ["checking", "error", "setup_required"].includes(availability.status);
+    container.hidden = !visible;
+    conversationRegion.hidden = visible;
+    if (!visible) {
+      dispose();
+      return;
+    }
+    paint();
+  }
+
+  function dispose() {
+    reset();
+    container.replaceChildren();
+  }
+
+  return {
+    bind,
+    render,
+    dispose,
+    clearSecret() {},
+    focusAction: () =>
+      container.querySelector('[data-runtime-setup-action="check"]')?.focus?.(),
+  };
+}

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

@@ -0,0 +1,107 @@
+import { escapeHtml } from "../../lib/text-format.js";
+import {
+  renderProviderChoices,
+  renderConnectionField,
+} from "./connection-form.js";
+import { buildBridgeSetupCommands } from "./commands.js";
+import { renderWizardShell } from "./wizard-shell.js";
+
+const PROVIDERS = [
+  {
+    id: "ollama",
+    label: "Ollama",
+    description: "A model on your computer or server",
+  },
+  { id: "openai", label: "OpenAI", description: "A hosted model" },
+];
+
+function commandBlock(id, label, command) {
+  return `<div class="runtime-bridge-command"><div><span>${escapeHtml(label)}</span><button type="button" data-runtime-setup-action="copy" data-runtime-command="${id}" aria-describedby="runtimeBridgeCopy-${id}">Copy</button></div>
+    <pre><code>${escapeHtml(command)}</code></pre><small id="runtimeBridgeCopy-${id}" data-runtime-copy-status="${id}" aria-live="polite"></small></div>`;
+}
+
+function connectionMarkup(state) {
+  let content = renderProviderChoices({ ...state, providers: PROVIDERS });
+  content += renderConnectionField({
+    field: "model-id",
+    label: "Model ID",
+    value: state.modelId,
+    placeholder: "Exact model name",
+    help: "Enter the model name provided by your service.",
+  });
+  if (state.provider === "ollama")
+    content += renderConnectionField({
+      field: "ollama-base-url",
+      label: "Ollama address",
+      type: "url",
+      value: state.baseUrl,
+      help: "Use the address reachable from the computer running the runtime.",
+    });
+  return content;
+}
+
+function commandsMarkup(state, commandMode) {
+  const commands = buildBridgeSetupCommands(
+    state.provider,
+    state.modelId,
+    state.baseUrl,
+    commandMode,
+  );
+  let content =
+    '<p class="runtime-setup-feedback">Run these commands in the runtime project used by your Bridge. This page cannot run commands or restart services.</p>';
+  if (state.provider === "ollama")
+    content += commandBlock(
+      "ollama-pull",
+      "Ollama host · download the model",
+      commands["ollama-pull"],
+    );
+  content += commandBlock("setup", "Runtime host · initialize", commands.setup);
+  if (state.provider === "openai")
+    content +=
+      '<p class="runtime-setup-feedback">After initialization, set <code>OPENAI_API_KEY</code> in the runtime’s <code>.env</code> with your local editor or secret manager. Keep the key out of this page and terminal commands.</p>';
+  content +=
+    '<p class="runtime-setup-feedback">The initializer preserves existing files. Restart the runtime services and Bridge after changing configuration so they load the new settings.</p>';
+  if (commands["model-gateway"])
+    content += commandBlock(
+      "model-gateway",
+      "Restart the model gateway",
+      commands["model-gateway"],
+    );
+  content +=
+    '<p class="runtime-setup-feedback">Restart this Web UI using its original Bridge launch command or service configuration. Preserve <code>LLM_RUNTIME_WEB_BACKEND=bridge</code>, the configured Bridge URLs, and authentication settings.</p>';
+  return content;
+}
+
+export function renderBridgeSetup(state, availability, commandMode) {
+  const checking = availability.status === "checking";
+  let feedback = "";
+  if (state.error)
+    feedback = `<p class="runtime-setup-feedback error" role="alert">${escapeHtml(state.error)}</p>`;
+  else if (checking)
+    feedback =
+      '<p class="runtime-setup-feedback" role="status">Checking the model catalog…</p>';
+  else if (availability.status === "error")
+    feedback = `<p class="runtime-setup-feedback error" role="alert">Could not check the model catalog. ${escapeHtml(availability.message)}</p>`;
+  const disabled = checking ? "disabled" : "";
+  const check = `<button type="button" class="runtime-setup-action" data-runtime-setup-action="check" ${disabled}>${checking ? "Checking…" : "Check again"}</button>`;
+  const footer =
+    state.step === 0
+      ? `${check}<button type="submit" class="runtime-setup-action" ${checking || !state.provider ? "disabled" : ""}>Show commands</button>`
+      : `<button type="button" class="runtime-setup-secondary" data-runtime-setup-action="back" ${disabled}>Back</button>${check}`;
+  return renderWizardShell({
+    steps: ["Provider", "Commands"],
+    step: state.step,
+    title:
+      state.step === 0
+        ? "Connect the external runtime"
+        : "Finish setup on the runtime host",
+    description:
+      "This Web UI connects through a Bridge. Configure its runtime, then check model availability again.",
+    content:
+      (state.step === 0
+        ? connectionMarkup(state)
+        : commandsMarkup(state, commandMode)) + feedback,
+    footer,
+    busy: checking,
+  });
+}

package/dist/src/web-ui/app/components/runtime-setup/commands.js

@@ -0,0 +1,54 @@
+import {
+  DEFAULT_OLLAMA_BASE_URL,
+  normalizeProvider,
+  validateRuntimeSetupBaseUrl,
+  validateRuntimeSetupModelId,
+} from "./validation.js";
+
+export function buildRuntimeSetupCommands(
+  provider,
+  modelId,
+  ollamaBaseUrl = DEFAULT_OLLAMA_BASE_URL,
+  setupCommandMode = "source",
+) {
+  const selectedProvider = normalizeProvider(provider);
+  const validation = validateRuntimeSetupModelId(modelId);
+  const baseUrlValidation = validateRuntimeSetupBaseUrl(ollamaBaseUrl);
+  const providerArgument = selectedProvider || "<provider>";
+  const modelArgument = validation.valid ? validation.value : "<model-id>";
+  const baseUrlArgument = baseUrlValidation.valid
+    ? baseUrlValidation.value
+    : "<ollama-base-url>";
+  const packaged = setupCommandMode === "package";
+  const initPrefix = packaged ? "npx abot init" : "npm run init --";
+  const init = `${initPrefix} --provider ${providerArgument} --model ${modelArgument}${
+    selectedProvider === "ollama" ? ` --base-url ${baseUrlArgument}` : ""
+  }`;
+  return {
+    "ollama-pull": `ollama pull ${modelArgument}`,
+    setup: init,
+    "model-gateway": packaged ? "npx abot start" : "npm run model-gateway",
+    "web-ui": packaged ? "" : "npm run web-ui",
+  };
+}
+
+// Bridge launch settings are private server state, not browser configuration.
+export function buildBridgeSetupCommands(
+  provider,
+  modelId,
+  ollamaBaseUrl,
+  setupCommandMode,
+) {
+  const commands = buildRuntimeSetupCommands(
+    provider,
+    modelId,
+    ollamaBaseUrl,
+    setupCommandMode,
+  );
+  const packaged = setupCommandMode === "package";
+  return {
+    ...commands,
+    "model-gateway": packaged ? "" : commands["model-gateway"],
+    "web-ui": "",
+  };
+}

package/dist/src/web-ui/app/components/runtime-setup/configuration-recovery.js

@@ -0,0 +1,25 @@
+import { escapeHtml } from "../../lib/text-format.js";
+
+export function requiresConfigurationRecovery(availability) {
+  return availability?.recovery === "configuration";
+}
+
+export function preserveConfigurationRecovery(current, incoming) {
+  if (!requiresConfigurationRecovery(current)) return incoming;
+  const transient =
+    incoming.status === "checking" || incoming.status === "error";
+  if (!transient) return incoming;
+  return { ...incoming, recovery: "configuration" };
+}
+
+export function renderConfigurationRecovery(availability) {
+  const checking = availability.status === "checking";
+  return `<section class="runtime-setup-panel" aria-labelledby="runtimeSetupRecoveryTitle">
+    <header class="runtime-setup-heading"><h3 id="runtimeSetupRecoveryTitle" tabindex="-1" data-runtime-setup-title>Review your existing configuration</h3>
+    <p>Your model profiles are saved, but need attention before ABot can start.</p></header>
+    <div class="runtime-setup-content"><p role="status">${escapeHtml(availability.message || "Open Configuration to repair the existing model and provider settings.")}</p>
+    <p>Open Configuration to review your model profiles and provider connections. Your existing settings will be preserved.</p></div>
+    <footer class="runtime-setup-footer"><button type="button" class="runtime-setup-secondary" data-runtime-setup-action="check" ${checking ? "disabled" : ""}>${checking ? "Checking…" : "Check again"}</button>
+    <button type="button" class="runtime-setup-action" data-runtime-setup-action="configuration" ${checking ? "disabled" : ""}>Open Configuration</button></footer>
+  </section>`;
+}

package/dist/src/web-ui/app/components/runtime-setup/connection-form.js

@@ -0,0 +1,154 @@
+import { escapeAttribute, escapeHtml, textOf } from "../../lib/text-format.js";
+import { validateContextWindowTokens } from "./context-window.js";
+import { canEditSetupConnection } from "./connection-state.js";
+import {
+  validateRuntimeSetupBaseUrl,
+  validateRuntimeSetupModelId,
+} from "./validation.js";
+
+export function renderProviderChoices(state) {
+  const options = state.providers
+    .map(
+      (provider) => `<label class="runtime-provider-option">
+    <input type="radio" name="runtimeSetupProvider" value="${escapeAttribute(provider.id)}" data-runtime-setup-field="provider" ${state.provider === provider.id ? "checked" : ""} />
+    <span><strong>${escapeHtml(provider.label)}</strong><small>${escapeHtml(provider.description || (provider.id === "ollama" ? "A model on your computer or server" : "A hosted model using your API key"))}</small></span>
+  </label>`,
+    )
+    .join("");
+  return `<fieldset class="runtime-provider-fieldset"><legend class="sr-only">Choose a provider</legend><div class="runtime-provider-options">${options}</div></fieldset>`;
+}
+
+export function renderConnectionField({
+  field,
+  label,
+  type = "text",
+  value = "",
+  placeholder = "",
+  help = "",
+  required = true,
+  readonly = false,
+  min = "",
+  step = "",
+  idPrefix = "runtimeSetup",
+}) {
+  return `<label class="runtime-setup-field"><span>${label}</span>
+    <input type="${type}" data-runtime-setup-field="${field}" value="${escapeAttribute(value)}" placeholder="${escapeAttribute(placeholder)}" autocomplete="${type === "password" ? "new-password" : "off"}" spellcheck="false" ${min ? `min="${escapeAttribute(min)}"` : ""} ${step ? `step="${escapeAttribute(step)}"` : ""} ${required ? "required" : ""} ${readonly ? "readonly" : ""} aria-describedby="${idPrefix}Help-${field}" />
+    <small id="${idPrefix}Help-${field}">${help}</small>
+  </label>`;
+}
+
+export function renderConnectionFields(state) {
+  const selectedProvider = state.providers.find(
+    (provider) => provider.id === state.provider,
+  );
+  const credentialConfigured = selectedProvider?.credentialConfigured === true;
+  const providerType = state.providerType || state.provider;
+  const idPrefix = state.idPrefix || "runtimeSetup";
+  const model =
+    renderConnectionField({
+      idPrefix,
+      field: "model-id",
+      label: "Model ID",
+      value: state.modelId,
+      placeholder: "Exact model name",
+      readonly: !canEditSetupConnection(state),
+      help: "Enter the model name provided by your service.",
+    }) +
+    renderConnectionField({
+      idPrefix,
+      field: "context-window",
+      label: "Context window (tokens)",
+      type: "number",
+      value: state.contextWindowTokens,
+      min: "1",
+      step: "1",
+      readonly: !canEditSetupConnection(state),
+      help: "Use a value supported by your model. Larger windows need more memory with Ollama. You can change this later in Configuration.",
+    });
+  if (providerType === "ollama") {
+    if (state.existingProvider) return model;
+    return (
+      model +
+      renderConnectionField({
+        idPrefix,
+        field: "ollama-base-url",
+        label: "Ollama address",
+        type: "url",
+        value: state.baseUrl,
+        readonly: !canEditSetupConnection(state),
+        placeholder: "http://127.0.0.1:11434",
+        help: "Use the address reachable from the computer running ABot.",
+      })
+    );
+  }
+  if (credentialConfigured && state.allowCredentialReplacement === false)
+    return model;
+  return (
+    model +
+    renderConnectionField({
+      idPrefix,
+      field: "api-key",
+      label: credentialConfigured ? "API key (optional)" : "API key",
+      type: "password",
+      required: !credentialConfigured,
+      placeholder: credentialConfigured
+        ? "Leave blank to keep your saved key"
+        : "Enter your OpenAI API key",
+      help: "Saved privately on the ABot server. Never stored in this browser.",
+    })
+  );
+}
+
+export function clearConnectionSecret(container) {
+  const input = container.querySelector('[data-runtime-setup-field="api-key"]');
+  if (input) input.value = "";
+}
+
+export function readConnectionSecret(container) {
+  return textOf(
+    container.querySelector('[data-runtime-setup-field="api-key"]')?.value,
+  ).trim();
+}
+
+export function validateConnectionFields({
+  modelId,
+  contextWindowTokens,
+  providerType,
+  baseUrl,
+  existingProvider = false,
+}) {
+  const model = validateRuntimeSetupModelId(modelId);
+  if (!model.valid)
+    return { valid: false, field: "model-id", message: model.message };
+  const context = validateContextWindowTokens(contextWindowTokens);
+  if (!context.valid) return context;
+  const input = { model: model.value, contextWindowTokens: context.value };
+  if (providerType === "ollama" && !existingProvider) {
+    const address = validateRuntimeSetupBaseUrl(baseUrl);
+    if (!address.valid)
+      return {
+        valid: false,
+        field: "ollama-base-url",
+        message: address.message,
+      };
+    input.baseUrl = address.value;
+  }
+  return { valid: true, input };
+}
+
+export function showConnectionFieldError(
+  container,
+  field,
+  messageId = "runtimeSetupError",
+  idPrefix = "runtimeSetup",
+) {
+  const input = container.querySelector(
+    `[data-runtime-setup-field="${field}"]`,
+  );
+  input?.setAttribute?.("aria-invalid", "true");
+  input?.setAttribute?.(
+    "aria-describedby",
+    `${idPrefix}Help-${field} ${messageId}`,
+  );
+  input?.focus?.();
+}