Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

5.2 KB
Raw Blame
// Terminal capability reality: the only universal alert mechanism a plain terminal possesses
// is the BEL control character (\x07). Standard terminals do not support volume control, and
// desktop notifications via escape sequences (such as OSC 777 or OSC 9) risk spitting unparsed
// escape garbage that corrupts the line-rendered TUI frame. Therefore, attention notification
// only supports "off" and "bell", with "off" as the safe default.

import process from "node:process";
import { needsAttention } from "./mso-agent-session-list.mjs";

export const BEL = "\x07";
export const ATTENTION_SETTING_KEY = "attention";
export const ATTENTION_SETTING_PATH = "attention.notifications";
export const ATTENTION_MODES = Object.freeze(["off", "bell"]);

function getSessionId(row) {
  if (!row || typeof row !== "object") return null;
  const id = row.id ?? row.agentSession?.id;
  if (id != null && String(id).length > 0) return String(id);
  const name = row.name ?? row.agentSession?.name;
  if (name != null && String(name).length > 0) return String(name);
  return null;
}

function isSessionActive(row, activeId) {
  if (activeId == null) return false;
  const id = String(row?.id ?? row?.agentSession?.id ?? "");
  const name = String(row?.name ?? row?.agentSession?.name ?? "").replace(/^@/, "").trim();
  const target = String(activeId).replace(/^@/, "").trim();
  return (id !== "" && id === String(activeId)) || (name !== "" && name === target);
}

// Pure function calculating attention transitions without performing side effects.
// Screen loop wiring can consume this pure transition evaluator directly.
export function evaluateAttention(sessions, knownAttention = new Set(), options = {}) {
  const activeId = options.activeId ?? null;
  const mode = options.mode ?? "off";
  const isSuspended = Boolean(options.isSuspended);

  const nextAttention = new Set();
  const transitions = [];

  if (Array.isArray(sessions)) {
    for (const row of sessions) {
      const id = getSessionId(row);
      if (!id) continue;
      const needs = needsAttention(row);
      if (needs) {
        nextAttention.add(id);
        const active = isSessionActive(row, activeId);
        // Hysteresis: ring at most once per attention transition per session.
        // The active session never rings because the user is already focused on it
        // (for instance, typing a prompt in that session).
        if (!active && !knownAttention.has(id)) {
          transitions.push(id);
        }
      }
    }
  }

  // Bell only rings when enabled, not suspended, and at least one background session transitioned.
  const shouldRing = mode === "bell" && !isSuspended && transitions.length > 0;

  return {
    shouldRing,
    transitions,
    nextAttention,
  };
}

// Stateful notifier tracking session transitions across repaint cycles and suspension.
export function createAttentionNotifier(options = {}) {
  const output = options.output ?? process.stdout;
  let knownAttention = new Set(options.initialAttention || []);
  let suspended = Boolean(options.isSuspended);
  let wasSuspended = suspended;
  let justResumed = false;

  const getMode = typeof options.getMode === "function"
    ? options.getMode
    : () => (options.mode ?? "off");

  const getActiveId = typeof options.getActiveId === "function"
    ? options.getActiveId
    : () => (options.activeId ?? null);

  const getIsSuspended = typeof options.isSuspended === "function"
    ? options.isSuspended
    : () => suspended;

  function suspend() {
    suspended = true;
  }

  function resume() {
    if (!suspended) return;
    suspended = false;
    // Mark justResumed so that the repaint triggered upon resuming never fires the bell.
    justResumed = true;
  }

  function notify(sessions, callOptions = {}) {
    const mode = callOptions.mode ?? getMode();
    const activeId = callOptions.activeId ?? getActiveId();
    const isSusp = callOptions.isSuspended ?? getIsSuspended();

    // Detect external resume transitions when isSuspended flips from true to false
    if (wasSuspended && !isSusp) {
      justResumed = true;
    }
    wasSuspended = isSusp;

    // Default off means zero writes to stdout: byte-for-byte nothing is emitted.
    if (mode !== "bell") {
      const { nextAttention } = evaluateAttention(sessions, knownAttention, {
        activeId,
        mode: "off",
        isSuspended: true,
      });
      knownAttention = nextAttention;
      return { shouldRing: false, transitions: [], nextAttention };
    }

    // Suppress bell while suspended or during the repaint of a suspend/resume cycle.
    const suppress = isSusp || justResumed;
    if (justResumed) {
      justResumed = false;
    }

    const result = evaluateAttention(sessions, knownAttention, {
      activeId,
      mode: suppress ? "off" : "bell",
      isSuspended: suppress,
    });

    knownAttention = result.nextAttention;

    if (result.shouldRing && output && typeof output.write === "function") {
      output.write(BEL);
    }

    return result;
  }

  function reset() {
    knownAttention.clear();
    suspended = false;
    wasSuspended = false;
    justResumed = false;
  }

  return {
    notify,
    suspend,
    resume,
    reset,
    isSuspended: () => suspended,
    getKnownAttention: () => new Set(knownAttention),
  };
}