@vellumai/assistant 0.12.1 → 0.12.2-staging.2

package/src/desktop/desktop-window-manager-config.test.ts

@@ -0,0 +1,230 @@
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, expect, test } from "bun:test";
+
+import { DOMParser } from "@xmldom/xmldom";
+
+import { writeDesktopWindowManagerConfig } from "./desktop-window-manager-config.js";
+import { writeDesktopWindowTheme } from "./desktop-window-theme.js";
+
+const roots: string[] = [];
+afterEach(() => {
+  for (const root of roots.splice(0)) {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("adapts existing settings without removing window controls, application menus or originals", () => {
+  const home = mkdtempSync(join(tmpdir(), "desktop-window-config-"));
+  roots.push(home);
+  const sourceDir = join(home, ".config", "openbox");
+  mkdirSync(sourceDir, { recursive: true });
+  const source = `<openbox_config xmlns="http://openbox.org/3.4/rc">
+    <theme><name>Custom theme</name><titleLayout>NLIMC</titleLayout></theme>
+    <desktops><number>4</number><firstdesk>3</firstdesk></desktops>
+    <keyboard>
+      <keybind key="A-Tab"><action name="NextWindow"/></keybind>
+      <keybind key="C-A-Right"><action name="GoToDesktop"><to>right</to></action></keybind>
+      <keybind key="W-d"><action name="ShowDesktop"/></keybind>
+    </keyboard>
+    <mouse><context name="Desktop">
+      <mousebind button="Up" action="Click"><action name="GoToDesktop"><to>previous</to></action></mousebind>
+      <mousebind button="Middle" action="Press"><action name="ShowMenu"><menu>client-list-combined-menu</menu></action></mousebind>
+      <mousebind button="Right" action="Press"><action name="ShowMenu"><menu>root-menu</menu></action></mousebind>
+    </context><context name="Titlebar">
+      <mousebind button="Left" action="Drag"><action name="Move"/></mousebind>
+    </context></mouse>
+    <menu><file>menu.xml</file><file>/missing/optional-menu.xml</file></menu>
+    <applications><application class="XTerm"><desktop>4</desktop><maximized>yes</maximized></application></applications>
+  </openbox_config>`;
+  const menu = `<openbox_menu xmlns="http://openbox.org/3.4/menu"><menu id="root-menu" label="Menu">
+    <item label="Terminal"><action name="Execute"><command>xterm</command></action></item>
+    <menu id="client-list-menu" label="Desktops"/>
+  </menu></openbox_menu>`;
+  writeFileSync(join(sourceDir, "rc.xml"), source);
+  writeFileSync(join(sourceDir, "menu.xml"), menu);
+  const configDir = join(home, "generated");
+  const path = writeDesktopWindowManagerConfig(configDir, home);
+  const first = readFileSync(path, "utf8");
+  const parsed = new DOMParser().parseFromString(first, "application/xml");
+  const actions = Array.from(parsed.getElementsByTagName("action"));
+  expect(actions.map((action) => action.getAttribute("name"))).toEqual([
+    "NextWindow",
+    "ShowDesktop",
+    "ShowMenu",
+    "Move",
+  ]);
+  expect(actions[2]?.textContent).toBe("root-menu");
+  expect(parsed.getElementsByTagName("theme")[0]?.textContent).toBe(
+    "Custom themeNLIMC",
+  );
+  const rules = Array.from(parsed.getElementsByTagName("application"));
+  expect(rules[0]?.getElementsByTagName("maximized")[0]?.textContent).toBe(
+    "yes",
+  );
+  expect(rules.at(-1)?.getAttribute("class")).toBe("*");
+  expect(rules.at(-1)?.getElementsByTagName("desktop")[0]?.textContent).toBe(
+    "1",
+  );
+  const generatedMenu = readFileSync(
+    parsed.getElementsByTagName("file")[0]!.textContent!,
+    "utf8",
+  );
+  expect(parsed.getElementsByTagName("file")[1]?.textContent).toBe(
+    "/missing/optional-menu.xml",
+  );
+  expect(generatedMenu).toContain('label="Terminal"');
+  expect(generatedMenu).not.toContain('id="client-list-menu"');
+  expect(readFileSync(join(sourceDir, "rc.xml"), "utf8")).toBe(source);
+  expect(readFileSync(join(sourceDir, "menu.xml"), "utf8")).toBe(menu);
+  writeDesktopWindowManagerConfig(configDir, home);
+  expect(readFileSync(path, "utf8")).toBe(first);
+  const themed = writeDesktopWindowTheme(configDir, home);
+  writeDesktopWindowManagerConfig(configDir, home, themed);
+  const composed = new DOMParser().parseFromString(
+    readFileSync(path, "utf8"),
+    "application/xml",
+  );
+  expect(
+    composed.getElementsByTagName("theme")[0]?.getElementsByTagName("name")[0]
+      ?.textContent,
+  ).toBe(join(configDir, "window-theme"));
+  expect(composed.documentElement?.getAttribute("xml:base")).toContain(
+    "/.config/openbox/rc.xml",
+  );
+  expect(composed.getElementsByTagName("action").length).toBe(actions.length);
+  expect(readFileSync(join(sourceDir, "rc.xml"), "utf8")).toBe(source);
+});
+
+test("adapts nested XIncludes while preserving window actions, lookup bases and source files", () => {
+  const home = mkdtempSync(join(tmpdir(), "desktop-window-includes-"));
+  roots.push(home);
+  const sourceDir = join(home, ".config", "openbox");
+  mkdirSync(join(sourceDir, "bindings", "nested"), { recursive: true });
+  const sources = {
+    "rc.xml": `<openbox_config xmlns="http://openbox.org/3.4/rc" xmlns:xi="http://www.w3.org/2001/XInclude">
+      <theme><name>Custom</name></theme>
+      <xi:include href="bindings/keyboard.xml"/>
+      <xi:include href="sections.xml" xpointer="xpointer(/sections/*)"/>
+      <menu><file>menu.xml</file></menu>
+    </openbox_config>`,
+    "sections.xml": `<sections>
+      <desktops><number>4</number><firstdesk>3</firstdesk></desktops>
+      <mouse><screenEdgeWarpTime>400</screenEdgeWarpTime></mouse>
+      <menu><manageDesktops>yes</manageDesktops><file>menu.xml</file></menu>
+      <applications><application class="XTerm"><desktop>4</desktop><maximized>yes</maximized></application></applications>
+    </sections>`,
+    "bindings/keyboard.xml": `<keyboard xmlns="http://openbox.org/3.4/rc" xmlns:xi="http://www.w3.org/2001/XInclude" xml:base="nested/">
+      <keybind key="A-Tab"><action name="NextWindow"/></keybind>
+      <keybind key="C-A-Right"><action name="GoToDesktop"/></keybind>
+      <xi:include href="more.xml" xpointer="xpointer(/bindings/keybind)"/>
+    </keyboard>`,
+    "bindings/nested/more.xml": `<bindings>
+      <keybind key="A-F4"><action name="Close"/></keybind>
+      <keybind key="C-A-Plus"><action name="AddDesktopLast"/></keybind>
+    </bindings>`,
+    "menu.xml": `<openbox_menu xmlns:xi="http://www.w3.org/2001/XInclude">
+      <menu id="root-menu"><xi:include href="menu-items.xml"/></menu>
+    </openbox_menu>`,
+    "menu-items.xml": `<menu id="apps">
+      <item label="Terminal"><action name="Execute"><command>xterm</command></action></item>
+      <item label="Workspaces"><action name="ShowMenu"><menu>client-list-menu</menu></action></item>
+    </menu>`,
+  };
+  for (const [name, contents] of Object.entries(sources)) {
+    writeFileSync(join(sourceDir, name), contents);
+  }
+  const configDir = join(home, "generated");
+  const readXml = (path: string) =>
+    new DOMParser().parseFromString(
+      readFileSync(path, "utf8"),
+      "application/xml",
+    );
+  const config = readXml(
+    writeDesktopWindowManagerConfig(
+      configDir,
+      home,
+      writeDesktopWindowTheme(configDir, home),
+    ),
+  );
+  const include = (document: ReturnType<typeof readXml>) =>
+    document.getElementsByTagNameNS(
+      "http://www.w3.org/2001/XInclude",
+      "include",
+    )[0]!;
+  const sections = readXml(
+    fileURLToPath(
+      config
+        .getElementsByTagNameNS(
+          "http://www.w3.org/2001/XInclude",
+          "include",
+        )[1]!
+        .getAttribute("href")!,
+    ),
+  );
+  expect(sections.getElementsByTagName("number")[0]!.textContent).toBe("1");
+  expect(sections.getElementsByTagName("firstdesk")[0]!.textContent).toBe("1");
+  expect(
+    sections.getElementsByTagName("screenEdgeWarpTime")[0]!.textContent,
+  ).toBe("0");
+  expect(sections.getElementsByTagName("manageDesktops")[0]!.textContent).toBe(
+    "no",
+  );
+  const rules = Array.from(sections.getElementsByTagName("application"));
+  expect(rules[0]!.getElementsByTagName("maximized")[0]!.textContent).toBe(
+    "yes",
+  );
+  expect(rules.at(-1)!.getAttribute("class")).toBe("*");
+  expect(rules.at(-1)!.getElementsByTagName("desktop")[0]!.textContent).toBe(
+    "1",
+  );
+  const keyboard = readXml(
+    fileURLToPath(include(config).getAttribute("href")!),
+  );
+  expect(keyboard.toString()).toContain('name="NextWindow"');
+  expect(keyboard.toString()).not.toContain('name="GoToDesktop"');
+  expect(include(keyboard).getAttribute("xpointer")).toBe(
+    "xpointer(/bindings/keybind)",
+  );
+  const nested = readXml(
+    fileURLToPath(include(keyboard).getAttribute("href")!),
+  );
+  expect(nested.toString()).toContain('name="Close"');
+  expect(nested.toString()).not.toContain('name="AddDesktopLast"');
+  const menu = readXml(config.getElementsByTagName("file")[0]!.textContent!);
+  const items = readXml(fileURLToPath(include(menu).getAttribute("href")!));
+  expect(items.toString()).toContain("xterm");
+  expect(items.toString()).not.toContain("client-list-menu");
+  for (const [name, contents] of Object.entries(sources)) {
+    expect(readFileSync(join(sourceDir, name), "utf8")).toBe(contents);
+  }
+});
+
+for (const entityLocation of ["config", "menu"] as const) {
+  test(`preserves valid ${entityLocation} DTD entities for Openbox when adaptation is unsupported`, () => {
+    const home = mkdtempSync(join(tmpdir(), "desktop-window-entities-"));
+    roots.push(home);
+    const sourceDir = join(home, ".config", "openbox");
+    mkdirSync(sourceDir, { recursive: true });
+    const configPath = join(sourceDir, "rc.xml");
+    const config =
+      entityLocation === "config"
+        ? `<!DOCTYPE openbox_config [<!ENTITY theme "Custom">]><openbox_config><theme><name>&theme;</name></theme></openbox_config>`
+        : `<openbox_config><menu><file>menu.xml</file></menu></openbox_config>`;
+    const menu = `<!DOCTYPE openbox_menu [<!ENTITY terminal "xterm">]><openbox_menu><menu id="root-menu"><item label="Terminal"><action name="Execute"><command>&terminal;</command></action></item></menu></openbox_menu>`;
+    writeFileSync(configPath, config);
+    writeFileSync(join(sourceDir, "menu.xml"), menu);
+    const path = writeDesktopWindowManagerConfig(join(home, "generated"), home);
+    expect(path).toBe(configPath);
+    expect(readFileSync(path, "utf8")).toBe(config);
+    expect(readFileSync(join(sourceDir, "menu.xml"), "utf8")).toBe(menu);
+  });
+}

package/src/desktop/desktop-window-manager-config.ts

@@ -0,0 +1,238 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import {
+  type Document,
+  DOMParser,
+  type Element,
+  XMLSerializer,
+} from "@xmldom/xmldom";
+
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("desktop-window-config");
+
+const XML_NAMESPACE = "http://www.w3.org/XML/1998/namespace";
+const XINCLUDE_NAMESPACE = "http://www.w3.org/2001/XInclude";
+
+const WORKSPACE_MENUS = new Set([
+  "client-list-menu",
+  "client-list-combined-menu",
+]);
+const WORKSPACE_ACTION =
+  /^(GoToDesktop|SendToDesktop.*|AddDesktop.*|RemoveDesktop.*|Desktop(?:Next|Previous|Left|Right|Up|Down|Last)?|ToggleOmnipresent)$/i;
+
+export function writeDesktopWindowManagerConfig(
+  configDir: string,
+  home = homedir(),
+  sourcePath?: string,
+): string {
+  const searchDirs = [join(home, ".config", "openbox"), "/etc/xdg/openbox"];
+  const source = readConfig(sourcePath ?? "rc.xml", searchDirs);
+  if (!source) {
+    throw new Error("Desktop window manager config is missing: rc.xml");
+  }
+  try {
+    return writeManagedConfig(configDir, home, searchDirs, source);
+  } catch (err) {
+    log.warn(
+      { err },
+      "Desktop workspace config could not be adapted; preserving the existing Openbox config",
+    );
+    return source.path;
+  }
+}
+
+function writeManagedConfig(
+  configDir: string,
+  home: string,
+  searchDirs: string[],
+  source: { path: string; contents: string },
+): string {
+  const config = parseXml(source.contents, source.path);
+  const root = config.documentElement!;
+  for (const section of ["desktops", "mouse", "menu", "applications"]) {
+    child(root, section);
+  }
+  mkdirSync(configDir, { recursive: true });
+  const copies = new Map<string, string>();
+  function copyConfig(source: { path: string; contents: string }): string {
+    const existing = copies.get(source.path);
+    if (existing) {
+      return existing;
+    }
+    const path = join(configDir, `openbox-include-${copies.size}.xml`);
+    copies.set(source.path, path);
+    const document = parseXml(source.contents, source.path);
+    adaptReferences(document);
+    writeFileSync(path, new XMLSerializer().serializeToString(document));
+    return path;
+  }
+  function adaptReferences(document: Document): void {
+    removeWorkspaceControls(document);
+    configureWorkspaceSections(document);
+    for (const include of Array.from(
+      document.getElementsByTagNameNS(XINCLUDE_NAMESPACE, "include"),
+    )) {
+      if (include.getAttribute("parse") === "text") {
+        continue;
+      }
+      const url = new URL(include.getAttribute("href") ?? "", xmlBase(include));
+      const included = readConfig(fileURLToPath(url), []);
+      if (included) {
+        include.setAttribute("href", pathToFileURL(copyConfig(included)).href);
+      }
+    }
+    for (const file of Array.from(
+      document.getElementsByTagNameNS("*", "file"),
+    )) {
+      if ((file.parentNode as Element | null)?.localName !== "menu") {
+        continue;
+      }
+      const name = file.textContent?.trim();
+      if (!name) {
+        continue;
+      }
+      const menuSource = readConfig(
+        name.startsWith("~/") ? join(home, name.slice(2)) : name,
+        searchDirs,
+      );
+      if (menuSource) {
+        file.textContent = copyConfig(menuSource);
+      }
+    }
+  }
+  adaptReferences(config);
+  const path = join(configDir, "openbox.xml");
+  writeFileSync(path, new XMLSerializer().serializeToString(config));
+  return path;
+}
+
+function configureWorkspaceSections(document: Document): void {
+  for (const desktops of Array.from(
+    document.getElementsByTagNameNS("*", "desktops"),
+  )) {
+    child(desktops, "number").textContent = "1";
+    child(desktops, "firstdesk").textContent = "1";
+    child(desktops, "popupTime").textContent = "0";
+  }
+  for (const mouse of Array.from(
+    document.getElementsByTagNameNS("*", "mouse"),
+  )) {
+    child(mouse, "screenEdgeWarpTime").textContent = "0";
+  }
+  for (const menu of Array.from(document.getElementsByTagNameNS("*", "menu"))) {
+    if (
+      !menu.hasAttribute("id") &&
+      (menu.parentNode as Element | null)?.localName !== "action"
+    ) {
+      child(menu, "manageDesktops").textContent = "no";
+    }
+  }
+  for (const applications of Array.from(
+    document.getElementsByTagNameNS("*", "applications"),
+  )) {
+    // The last matching rule also covers windows restored with stale assignments.
+    const application = document.createElementNS(
+      applications.namespaceURI,
+      "application",
+    );
+    application.setAttribute("class", "*");
+    child(application, "desktop").textContent = "1";
+    applications.appendChild(application);
+  }
+}
+
+function readConfig(name: string, directories: string[]) {
+  for (const path of isAbsolute(name)
+    ? [name]
+    : directories.map((dir) => join(dir, name))) {
+    try {
+      return { path, contents: readFileSync(path, "utf8") };
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+        throw err;
+      }
+    }
+  }
+  return null;
+}
+
+function parseXml(contents: string, sourcePath: string): Document {
+  const document = new DOMParser({
+    onError: (level, message) => {
+      if (level !== "warning") {
+        throw new Error(message);
+      }
+    },
+  }).parseFromString(contents, "application/xml");
+  const root = document.documentElement!;
+  root.setAttributeNS(
+    XML_NAMESPACE,
+    "xml:base",
+    new URL(
+      root.getAttributeNS(XML_NAMESPACE, "base") ?? "",
+      pathToFileURL(sourcePath),
+    ).href,
+  );
+  return document;
+}
+
+function xmlBase(element: Element): string {
+  const ancestors: Element[] = [];
+  for (
+    let node: Element | null = element;
+    node;
+    node = node.parentNode?.nodeType === 1 ? (node.parentNode as Element) : null
+  ) {
+    ancestors.unshift(node);
+  }
+  let base = "";
+  for (const ancestor of ancestors) {
+    const value = ancestor.getAttributeNS(XML_NAMESPACE, "base");
+    if (value) {
+      base = base ? new URL(value, base).href : value;
+    }
+  }
+  return base;
+}
+
+function child(parent: Element, name: string): Element {
+  const existing = Array.from(parent.childNodes).find(
+    (node): node is Element =>
+      node.nodeType === 1 && (node as Element).localName === name,
+  );
+  if (existing) {
+    return existing;
+  }
+  const element = parent.ownerDocument!.createElementNS(
+    parent.namespaceURI,
+    name,
+  );
+  parent.appendChild(element);
+  return element;
+}
+
+function removeWorkspaceControls(document: Document): void {
+  for (const menu of Array.from(document.getElementsByTagNameNS("*", "menu"))) {
+    if (WORKSPACE_MENUS.has(menu.getAttribute("id") ?? "")) {
+      menu.parentNode?.removeChild(menu);
+    }
+  }
+  for (const action of Array.from(
+    document.getElementsByTagNameNS("*", "action"),
+  )) {
+    const name = action.getAttribute("name") ?? "";
+    const menu = action
+      .getElementsByTagNameNS("*", "menu")[0]
+      ?.textContent?.trim();
+    if (
+      WORKSPACE_ACTION.test(name) ||
+      (name.toLowerCase() === "showmenu" && menu && WORKSPACE_MENUS.has(menu))
+    ) {
+      action.parentNode?.removeChild(action);
+    }
+  }
+}

package/src/desktop/desktop-window-theme.ts

@@ -0,0 +1,170 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { escapeXmlAttr, escapeXmlContent } from "../util/xml.js";
+
+const BUTTON_MASKS = {
+  close: [0x201, 0x102, 0x084, 0x048, 0x030, 0x030, 0x048, 0x084, 0x102, 0x201],
+  max: [0x3ff, 0x201, 0x201, 0x201, 0x201, 0x201, 0x201, 0x201, 0x201, 0x3ff],
+  max_toggled: [
+    0x3fc, 0x204, 0x27f, 0x241, 0x241, 0x241, 0x3c1, 0x041, 0x041, 0x07f,
+  ],
+  iconify: [0, 0, 0, 0, 0x3ff, 0x3ff, 0, 0, 0, 0],
+};
+
+function windowTheme(accentHex: string | null): string {
+  const tint = (base: string, amount: number): string => {
+    if (!accentHex || !/^#[\da-f]{6}$/i.test(accentHex)) {
+      return base;
+    }
+    return (
+      "#" +
+      [1, 3, 5]
+        .map((offset) => {
+          const from = parseInt(base.slice(offset, offset + 2), 16);
+          const to = parseInt(accentHex.slice(offset, offset + 2), 16);
+          return Math.round(from + (to - from) * amount)
+            .toString(16)
+            .padStart(2, "0");
+        })
+        .join("")
+    );
+  };
+  return `
+border.width: 1
+padding.width: 8
+padding.height: 7
+window.client.padding.width: 0
+window.client.padding.height: 0
+window.handle.width: 3
+window.label.text.justify: Center
+window.*.label.text.font: shadow=n
+window.*.title.bg: Flat Solid
+window.*.label.bg: Parentrelative
+window.*.handle.bg: Flat Solid
+window.*.grip.bg: Flat Solid
+window.*.button.*.bg: Parentrelative
+window.*.button.*.hover.bg: Flat Solid
+window.*.button.*.pressed.bg: Flat Solid
+window.active.title.bg: Flat Gradient Horizontal
+window.active.title.bg.color: ${tint("#292930", 0.28)}
+window.active.title.bg.colorTo: #292930
+window.active.border.color: #4a4a54
+window.active.title.separator.color: #202026
+window.active.label.text.color: #f0f0f4
+window.active.handle.bg.color: #292930
+window.active.grip.bg.color: #292930
+window.active.button.*.image.color: #d4d4dc
+window.active.button.*.hover.bg.color: ${tint("#45454f", 0.22)}
+window.active.button.*.pressed.bg.color: ${tint("#555561", 0.18)}
+window.active.button.*.disabled.image.color: #62626e
+window.active.button.close.hover.bg.color: #b64150
+window.active.button.close.pressed.bg.color: #963442
+window.inactive.title.bg.color: #232329
+window.inactive.border.color: #36363f
+window.inactive.title.separator.color: #202026
+window.inactive.label.text.color: #a6a6b2
+window.inactive.handle.bg.color: #232329
+window.inactive.grip.bg.color: #232329
+window.inactive.button.*.image.color: #858592
+window.inactive.button.*.hover.bg.color: #3b3b45
+window.inactive.button.*.pressed.bg.color: #4a4a54
+window.inactive.button.*.disabled.image.color: #565660
+menu.border.width: 1
+menu.border.color: #4a4a54
+menu.title.bg: Flat Solid
+menu.title.bg.color: #292930
+menu.title.text.color: #f0f0f4
+menu.title.text.font: shadow=n
+menu.items.bg: Flat Solid
+menu.items.bg.color: #232329
+menu.items.text.color: #e6e6ee
+menu.items.disabled.text.color: #858592
+menu.items.active.bg: Flat Solid
+menu.items.active.bg.color: #45454f
+menu.items.active.text.color: #ffffff
+menu.items.active.disabled.text.color: #a6a6b2
+menu.separator.color: #45454f
+osd.bg: Flat Solid
+osd.bg.color: #292930
+osd.border.color: #4a4a54
+osd.label.text.color: #f0f0f4
+`;
+}
+
+/** Keep Openbox bindings and placement rules while styling its decorations. */
+export function writeDesktopWindowTheme(
+  configDir: string,
+  home?: string,
+  accentHex: string | null = null,
+): string {
+  let source: string | undefined;
+  let sourcePath = "";
+  const candidates = [
+    ...(home ? [join(home, ".config", "openbox", "rc.xml")] : []),
+    "/etc/xdg/openbox/rc.xml",
+  ];
+  for (const path of candidates) {
+    try {
+      source = readFileSync(path, "utf8");
+      sourcePath = path;
+      break;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+        throw err;
+      }
+    }
+  }
+  if (!source || !/<theme>[^]*?<\/theme>/.test(source)) {
+    throw new Error("Openbox theme configuration is unavailable");
+  }
+  const root = source.match(/<openbox_config\b[^>]*>/)?.[0];
+  if (!root || /\bxml:base\s*=/.test(root)) {
+    throw new Error("Openbox configuration requires its original base URI");
+  }
+  // Relative XIncludes keep resolving beside the source configuration.
+  source = source.replace(root, () =>
+    root.replace(
+      "<openbox_config",
+      `<openbox_config xml:base="${escapeXmlAttr(pathToFileURL(sourcePath).href)}"`,
+    ),
+  );
+  const themeDir = join(configDir, "window-theme");
+  mkdirSync(join(themeDir, "openbox-3"), { recursive: true });
+  writeFileSync(
+    join(themeDir, "openbox-3", "themerc"),
+    windowTheme(accentHex).trimStart(),
+  );
+  for (const [name, rows] of Object.entries(BUTTON_MASKS)) {
+    const bytes = rows.flatMap((row) => [row & 0xff, row >> 8]);
+    writeFileSync(
+      join(themeDir, "openbox-3", `${name}.xbm`),
+      `#define button_width 10\n#define button_height 10\nstatic unsigned char button_bits[] = {\n${bytes.map((byte) => `0x${byte.toString(16)}`).join(",")}};\n`,
+    );
+  }
+  const fonts = [
+    "ActiveWindow",
+    "InactiveWindow",
+    "MenuHeader",
+    "MenuItem",
+    "ActiveOnScreenDisplay",
+    "InactiveOnScreenDisplay",
+  ].map(
+    (place) =>
+      `<font place="${place}"><name>sans</name><size>10</size><weight>normal</weight><slant>normal</slant></font>`,
+  );
+  const theme = `<theme>
+  <name>${escapeXmlContent(themeDir)}</name>
+  <titleLayout>LIMC</titleLayout>
+  <keepBorder>yes</keepBorder>
+  <animateIconify>yes</animateIconify>
+  ${fonts.join("\n  ")}
+</theme>`;
+  const configPath = join(configDir, "window-manager.xml");
+  writeFileSync(
+    configPath,
+    source.replace(/<theme>[^]*?<\/theme>/, () => theme),
+  );
+  return configPath;
+}

package/src/heartbeat/heartbeat-service.ts

@@ -1,6 +1,8 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { channelForBotProvider } from "@vellumai/service-contracts/channels";
+
 import type { HeartbeatAlertEvent } from "../api/events/heartbeat-alert.js";
 import { getConfig } from "../config/loader.js";
 import type { HeartbeatConfig } from "../config/schemas/heartbeat.js";
@@ -55,6 +57,19 @@ const DEFAULT_CHECKLIST = `- Check in with yourself. Read NOW.md. Is it still ac
 const EARLY_HEARTBEAT_THRESHOLD = 3;
 const REENGAGEMENT_COOLDOWN_MS = 18 * 60 * 60 * 1000; // 18 hours
 
+/**
+ * A provider key named by the identity it carries. The keys alone do not say
+ * which is which (`slack` is the integration acting as the connected person,
+ * `slack_channel` is the assistant's own bot), and a heartbeat told to avoid
+ * "slack" would otherwise stop posting through a bot whose credential is fine.
+ */
+function describeUnhealthyProvider(providerKey: string): string {
+  const channel = channelForBotProvider(providerKey);
+  return channel
+    ? `${providerKey} (the ${channel} channel bot)`
+    : `${providerKey} (integration, acts as the connected person)`;
+}
+
 // Stripped-comment form of the guardian persona scaffold. Computed
 // once at module load because stripping comment lines is deterministic
 // and the template itself is a compile-time constant.
@@ -945,10 +960,13 @@ ${checklist}
 </heartbeat-checklist>`;
 
     if (unhealthyProviders.length > 0) {
-      const providers = unhealthyProviders.join(", ");
+      const providers = unhealthyProviders
+        .map(describeUnhealthyProvider)
+        .join(", ");
       prompt += `\n\n<credential-status>
-The following providers have broken or expired credentials: ${providers}.
-Do NOT attempt to use tools for these providers — they will fail. Skip any checklist items that depend on them and note the outage in your summary.
+The following credentials are broken or expired: ${providers}.
+Do NOT attempt to use tools for these providers, they will fail. Skip any checklist items that depend on them and note the outage in your summary.
+A channel bot is the assistant's own identity on a channel and a separate credential from the integration of the same name; it is affected only when listed here as a channel bot.
 </credential-status>`;
     }