@elizaos/app-core 2.0.0-beta.2 → 2.0.11-beta.5

package/platforms/electrobun/src/native-onboarding.ts

@@ -0,0 +1,270 @@
+/**
+ * Native macOS notification–driven onboarding flow.
+ *
+ * Instead of opening a BrowserWindow for onboarding, this module:
+ * 1. Posts a native macOS notification with action buttons
+ *    ("Local (On-Device)", "Local (Cloud AI)", "Eliza Cloud")
+ * 2. Polls for the user's choice via FFI
+ * 3. Calls the local first-run API to complete onboarding
+ *
+ * This runs entirely in the main process — no renderer needed for the choice.
+ * After the first-run API responds, the caller opens the dashboard.
+ */
+
+import {
+  DEFAULT_ELIZA_CLOUD_TEXT_MODEL,
+  getDefaultStylePreset,
+} from "@elizaos/shared";
+import { buildFirstRunRuntimeConfig } from "../../../src/first-run/first-run-config";
+import { logger } from "./logger";
+import {
+  dismissOnboardingNotification,
+  getOnboardingChoice,
+  type OnboardingChoice,
+  postOnboardingNotification,
+} from "./native/mac-window-effects";
+
+/**
+ * Resolved user choice from the notification, mapped to the runtime fields
+ * understood by the first-run API.
+ */
+export interface ResolvedOnboardingChoice {
+  runtime: "local" | "cloud";
+  localInference: "all-local" | "cloud-inference";
+}
+
+/** Maximum number of times the notification is re-posted when dismissed. */
+const MAX_DISMISS_RETRIES = 3;
+
+/**
+ * Post the onboarding notification and poll until the user picks an action.
+ * Returns `null` if the notification could not be posted (e.g. non-macOS),
+ * the user dismissed it more than MAX_DISMISS_RETRIES times (falls back to
+ * the overlay), or an unrecognised choice is received.
+ *
+ * @param dismissRetryCount - internal recursion depth guard; callers should
+ *   omit this (defaults to 0). When it reaches MAX_DISMISS_RETRIES the
+ *   function returns null so the caller can fall back to the onboarding
+ *   overlay rather than looping indefinitely.
+ */
+export async function waitForOnboardingNotificationChoice(
+  dismissRetryCount = 0,
+): Promise<ResolvedOnboardingChoice | null> {
+  const posted = postOnboardingNotification(
+    "Welcome to Eliza",
+    "Choose how to run your agent.",
+  );
+  if (!posted) {
+    logger.warn(
+      "[native-onboarding] Failed to post notification — falling back to overlay",
+    );
+    return null;
+  }
+  logger.info("[native-onboarding] Notification posted, waiting for choice…");
+
+  // Maximum time to wait for a user choice before giving up (5 minutes).
+  // This ensures the setInterval is always cleared even if the promise is
+  // abandoned (e.g. the overlay wins the race and the notification is ignored).
+  const POLL_TIMEOUT_MS = 5 * 60 * 1_000;
+
+  return new Promise<ResolvedOnboardingChoice | null>((resolve) => {
+    let settled = false;
+    const settle = (
+      value:
+        | ResolvedOnboardingChoice
+        | null
+        | PromiseLike<ResolvedOnboardingChoice | null>,
+    ): void => {
+      if (settled) return;
+      settled = true;
+      clearInterval(timer);
+      clearTimeout(abandonTimeout);
+      // resolve() is Promise/A+ compliant — passing a PromiseLike chains it.
+      resolve(value);
+    };
+
+    const timer = setInterval(() => {
+      const choice: OnboardingChoice = getOnboardingChoice();
+      if (choice === 0) return; // still waiting
+
+      // Dismiss the notification for all choice paths so macOS removes it
+      // from the notification centre before we settle/re-post.
+      dismissOnboardingNotification();
+
+      switch (choice) {
+        case 1: // Local (On-Device)
+          logger.info("[native-onboarding] User chose: local all-on-device");
+          settle({ runtime: "local", localInference: "all-local" });
+          break;
+        case 2: // Local (Cloud AI)
+          logger.info("[native-onboarding] User chose: local cloud-inference");
+          settle({ runtime: "local", localInference: "cloud-inference" });
+          break;
+        case 3: // Eliza Cloud
+          logger.info("[native-onboarding] User chose: Eliza Cloud");
+          settle({ runtime: "cloud", localInference: "all-local" });
+          break;
+        case 4: // Dismissed
+          if (dismissRetryCount >= MAX_DISMISS_RETRIES) {
+            logger.warn(
+              `[native-onboarding] Notification dismissed ${MAX_DISMISS_RETRIES + 1} times — falling back to overlay`,
+            );
+            settle(null);
+          } else {
+            logger.info(
+              `[native-onboarding] Notification dismissed (retry ${dismissRetryCount + 1}/${MAX_DISMISS_RETRIES}) — re-posting`,
+            );
+            settle(waitForOnboardingNotificationChoice(dismissRetryCount + 1));
+          }
+          break;
+        default:
+          settle(null);
+      }
+    }, 500);
+
+    // Safety net: if the promise is abandoned (overlay wins the race or the
+    // caller is GC-ed) this timeout clears the interval so we don't leak.
+    const abandonTimeout = setTimeout(() => {
+      if (!settled) {
+        logger.warn(
+          "[native-onboarding] Timed out waiting for notification choice — clearing poll timer",
+        );
+        settle(null);
+      }
+    }, POLL_TIMEOUT_MS);
+  });
+}
+
+/**
+ * Build the first-run submit payload and POST it to the local API server.
+ *
+ * This mirrors what the renderer does in `finishLocal` / `finishCloud`,
+ * but runs entirely from the main process so no renderer window is needed.
+ */
+export async function submitOnboardingFirstRun(
+  apiBase: string,
+  choice: ResolvedOnboardingChoice,
+): Promise<boolean> {
+  const style = getDefaultStylePreset();
+  const agentName = style.name;
+
+  const runtimeTarget =
+    choice.runtime === "cloud"
+      ? "elizacloud"
+      : choice.localInference === "cloud-inference"
+        ? "elizacloud-hybrid"
+        : "local";
+
+  const provider =
+    choice.runtime === "cloud" || choice.localInference === "cloud-inference"
+      ? "elizacloud"
+      : "";
+
+  const useCloudModels =
+    choice.runtime === "cloud" || choice.localInference === "cloud-inference";
+  const cloudModel = useCloudModels ? DEFAULT_ELIZA_CLOUD_TEXT_MODEL : "";
+
+  const runtimeConfig = buildFirstRunRuntimeConfig({
+    firstRunRuntimeTarget: runtimeTarget,
+    firstRunCloudApiKey: "",
+    firstRunProvider: provider,
+    firstRunApiKey: "",
+    omitRuntimeProvider: provider !== "elizacloud",
+    firstRunVoiceProvider: "",
+    firstRunVoiceApiKey: "",
+    firstRunPrimaryModel: "",
+    firstRunOpenRouterModel: "",
+    firstRunRemoteConnected: false,
+    firstRunRemoteApiBase: "",
+    firstRunRemoteToken: "",
+    firstRunNanoModel: cloudModel,
+    firstRunSmallModel: cloudModel,
+    firstRunMediumModel: cloudModel,
+    firstRunLargeModel: cloudModel,
+    firstRunMegaModel: cloudModel,
+    firstRunFeatureCrypto: true,
+    firstRunFeatureBrowser: true,
+  });
+
+  const systemPrompt =
+    style.system?.replace(/\{\{name\}\}/g, agentName) ??
+    `You are ${agentName}, an autonomous AI agent powered by elizaOS.`;
+
+  const payload = {
+    name: agentName,
+    sandboxMode: choice.runtime === "cloud" ? "standard" : "off",
+    bio: style.bio ?? ["An autonomous AI agent."],
+    systemPrompt,
+    style: style.style,
+    adjectives: style.adjectives,
+    topics: style.topics,
+    postExamples: style.postExamples,
+    messageExamples: style.messageExamples,
+    avatarIndex: style.avatarIndex ?? 1,
+    language: "en",
+    presetId: style.id,
+    deploymentTarget: runtimeConfig.deploymentTarget,
+    ...(runtimeConfig.linkedAccounts
+      ? { linkedAccounts: runtimeConfig.linkedAccounts }
+      : {}),
+    ...(runtimeConfig.serviceRouting
+      ? { serviceRouting: runtimeConfig.serviceRouting }
+      : {}),
+    ...(runtimeConfig.credentialInputs
+      ? { credentialInputs: runtimeConfig.credentialInputs }
+      : {}),
+    features: {
+      crypto: { enabled: true },
+      browser: { enabled: true },
+      voice: { enabled: true, firstRun: true },
+    },
+  };
+
+  logger.info(
+    `[native-onboarding] Submitting first-run to ${apiBase}/api/first-run (runtime=${choice.runtime}, target=${runtimeTarget})`,
+  );
+
+  try {
+    const response = await fetch(`${apiBase}/api/first-run`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      logger.error(
+        `[native-onboarding] First-run API failed (${response.status}): ${text}`,
+      );
+      return false;
+    }
+
+    logger.info("[native-onboarding] First-run API succeeded");
+    return true;
+  } catch (err) {
+    logger.error(
+      `[native-onboarding] First-run API call failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return false;
+  }
+}
+
+/**
+ * Wait for the local API server to be ready by polling `/api/first-run/status`.
+ */
+export async function waitForApiReady(
+  apiBase: string,
+  timeoutMs = 60_000,
+): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${apiBase}/api/first-run/status`);
+      if (res.ok) return true;
+    } catch {
+      // Server not ready yet
+    }
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  return false;
+}

package/platforms/electrobun/src/onboarding-overlay-window.ts

@@ -0,0 +1,141 @@
+/**
+ * First-run onboarding overlay window for Electrobun.
+ *
+ * Spawns a single small, borderless, transparent, always-on-top BrowserWindow
+ * docked to the top-right of the work area that loads the renderer with
+ * `?shellMode=onboarding-overlay` — which renders ONLY the floating onboarding
+ * card over a transparent background.
+ *
+ * The window is sized to the card (not full-screen) so the rest of the desktop
+ * stays clickable: a full-screen transparent + passthrough window did not click
+ * through reliably on macOS (Electrobun's region-based passthrough relies on
+ * WKWebView per-pixel alpha, which is not dependable for dynamic React
+ * content), so the empty area captured every click. With a card-sized window
+ * the OS routes clicks outside it straight to whatever is behind.
+ *
+ * This replaces the opaque dashboard window at first launch (opt-in via
+ * ELIZA_DESKTOP_ONBOARDING_OVERLAY=1; see shouldStartOnboardingOverlay). Once
+ * onboarding completes the overlay is closed and the normal dashboard window
+ * opens.
+ *
+ * Modeled on pill-window.ts (the existing small borderless/transparent overlay).
+ */
+
+import { type BrowserWindow, Screen } from "electrobun/bun";
+import {
+  createElectrobunBrowserWindow,
+  type ElectrobunBrowserWindowOptions,
+} from "./electrobun-window-options";
+import { logger } from "./logger";
+import { makeKeyAndOrderFront } from "./native/mac-window-effects";
+
+/** rpc handle baked into the window at construction (typed via the wrapper). */
+type OverlayRpc = ElectrobunBrowserWindowOptions["rpc"];
+
+export function buildOnboardingOverlayRendererUrl(rendererUrl: string): string {
+  const url = new URL(rendererUrl);
+  url.search = "?shellMode=onboarding-overlay";
+  url.hash = "";
+  return url.toString();
+}
+
+let overlayWindow: BrowserWindow | null = null;
+
+export function createOnboardingOverlayWindow(args: {
+  rendererUrl: string;
+  preload: string;
+  rpc?: OverlayRpc;
+}): BrowserWindow {
+  if (overlayWindow) {
+    return overlayWindow;
+  }
+
+  // Use the full work area so the renderer can place UI elements anywhere on
+  // screen — the onboarding card is pinned top-right via CSS, and the voice
+  // pill is centered at the bottom. The window is transparent + passthrough,
+  // so clicks on empty regions fall through to the desktop. The
+  // makeKeyAndOrderFront call after dom-ready ensures the interactive elements
+  // (buttons, pill) receive clicks.
+  const workArea = Screen.getPrimaryDisplay().workArea;
+  const frame = {
+    x: workArea.x,
+    y: workArea.y,
+    width: workArea.width,
+    height: workArea.height,
+  };
+  const url = buildOnboardingOverlayRendererUrl(args.rendererUrl);
+
+  const win = createElectrobunBrowserWindow({
+    title: "Eliza Setup",
+    url,
+    preload: args.preload,
+    frame,
+    titleBarStyle: "hidden",
+    transparent: true,
+    // Match the pill window's proven-visible config. A small, borderless,
+    // transparent window only showed reliably with activate:false — a
+    // borderless NSWindow cannot become key, and activate:true left the small
+    // window unshown (the full-screen variant happened to paint regardless).
+    // No passthrough: the window is small, so clicks outside it already reach
+    // the desktop via the OS; full-screen-style per-pixel passthrough never
+    // composited dependably and is unnecessary here.
+    activate: false,
+    ...(args.rpc ? { rpc: args.rpc } : {}),
+  });
+
+  try {
+    win.setAlwaysOnTop(true);
+  } catch (err) {
+    logger.warn(
+      `[onboarding-overlay] setAlwaysOnTop failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  // The window was created with `activate: false` so it actually renders (a
+  // borderless transparent NSWindow does not show reliably with activate:true).
+  // But a non-activated window swallows the first click as macOS window
+  // activation, making the "Use Local" / "Eliza Cloud" buttons unresponsive.
+  //
+  // Fix: once the DOM is ready (WKWebView has painted), call the native
+  // `makeKeyAndOrderFront` FFI to make the window key. This is the same
+  // pattern the main window uses (see desktop.ts showMainWindow).
+  if (process.platform === "darwin") {
+    win.webview.on("dom-ready", () => {
+      const ptr = (win as { ptr?: unknown }).ptr;
+      if (ptr) {
+        makeKeyAndOrderFront(ptr as Parameters<typeof makeKeyAndOrderFront>[0]);
+        logger.info(
+          "[onboarding-overlay] Activated window via makeKeyAndOrderFront",
+        );
+      }
+    });
+  }
+
+  win.on("close", () => {
+    overlayWindow = null;
+  });
+
+  overlayWindow = win;
+  logger.info(
+    `[onboarding-overlay] Spawned transparent click-through overlay ${frame.width}x${frame.height} at (${frame.x},${frame.y})`,
+  );
+  return win;
+}
+
+export function getOnboardingOverlayWindow(): BrowserWindow | null {
+  return overlayWindow;
+}
+
+export function closeOnboardingOverlayWindow(): void {
+  if (!overlayWindow) {
+    return;
+  }
+  try {
+    overlayWindow.close();
+  } catch (err) {
+    logger.warn(
+      `[onboarding-overlay] close failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  overlayWindow = null;
+}

package/platforms/electrobun/src/persisted-deployment.ts

@@ -0,0 +1,91 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveStateDir, resolveUserPath } from "@elizaos/core";
+import { normalizeDeploymentTargetConfig } from "@elizaos/shared";
+import type { PersistedDeployment } from "./api-base";
+import { logger } from "./logger";
+
+const CONFIG_FILENAME = "eliza.json";
+
+/**
+ * Resolve the canonical `eliza.json` path the agent persists its config to.
+ * Mirrors `@elizaos/agent`'s `resolveConfigPath` (state-dir + filename, with
+ * the `ELIZA_CONFIG_PATH` override) without importing the agent boot module,
+ * so the desktop main process can read the persisted deployment target without
+ * pulling the agent into the static boot graph.
+ */
+function resolveElizaConfigPath(
+  env: Record<string, string | undefined>,
+): string {
+  const override = env.ELIZA_CONFIG_PATH?.trim();
+  if (override) {
+    return resolveUserPath(override);
+  }
+  return path.join(resolveStateDir(env as NodeJS.ProcessEnv), CONFIG_FILENAME);
+}
+
+/**
+ * Read the persisted `deploymentTarget` from `eliza.json` as a
+ * {@link PersistedDeployment} (`runtime` + the cloud-hosted/external agent's
+ * `remoteApiBase`). Best-effort and fail-safe: any missing file, parse error,
+ * or absent deployment target resolves to `null`, which the caller treats as
+ * "no cloud-hosted target" and keeps the existing local-agent boot path. The
+ * persisted config is written by `saveElizaConfig` as strict JSON, so a strict
+ * `JSON.parse` is sufficient.
+ */
+export function readPersistedDeployment(
+  env: Record<string, string | undefined> = process.env as Record<
+    string,
+    string | undefined
+  >,
+): PersistedDeployment | null {
+  const configPath = resolveElizaConfigPath(env);
+  let raw: string;
+  try {
+    raw = fs.readFileSync(configPath, "utf-8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return null;
+    }
+    logger.warn(
+      `[Deployment] Could not read ${configPath}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return null;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    logger.warn(
+      `[Deployment] Could not parse ${configPath}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return null;
+  }
+
+  const deploymentTarget = normalizeDeploymentTargetConfig(
+    (parsed as { deploymentTarget?: unknown } | null)?.deploymentTarget,
+  );
+  if (!deploymentTarget) {
+    return null;
+  }
+  return {
+    runtime: deploymentTarget.runtime,
+    remoteApiBase: deploymentTarget.remoteApiBase ?? null,
+  };
+}
+
+let cachedDeployment: PersistedDeployment | null | undefined;
+
+/**
+ * Cached read of the persisted deployment for the lifetime of the desktop
+ * process. The deployment target only changes via a first-run flow that
+ * restarts the shell, so a single read at boot is the source of truth for every
+ * runtime-mode decision in `main()`.
+ */
+export function getPersistedDeployment(): PersistedDeployment | null {
+  if (cachedDeployment === undefined) {
+    cachedDeployment = readPersistedDeployment();
+  }
+  return cachedDeployment;
+}

package/platforms/electrobun/src/pill-window.test.ts

@@ -0,0 +1,91 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  createWindow: vi.fn(),
+  getPrimaryDisplay: vi.fn(),
+  info: vi.fn(),
+  warn: vi.fn(),
+}));
+
+vi.mock("electrobun/bun", () => ({
+  BrowserWindow: class BrowserWindow {},
+  Screen: {
+    getPrimaryDisplay: mocks.getPrimaryDisplay,
+  },
+}));
+
+vi.mock("./electrobun-window-options", () => ({
+  createElectrobunBrowserWindow: mocks.createWindow,
+}));
+
+vi.mock("./logger", () => ({
+  logger: {
+    debug: vi.fn(),
+    error: vi.fn(),
+    info: mocks.info,
+    success: vi.fn(),
+    warn: mocks.warn,
+  },
+}));
+
+describe("pill window", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    mocks.createWindow.mockReset();
+    mocks.getPrimaryDisplay.mockReset();
+    mocks.info.mockReset();
+    mocks.warn.mockReset();
+  });
+
+  it("loads the OS pill into the live chat overlay shell route", async () => {
+    const { buildPillRendererUrl } = await import("./pill-window");
+
+    expect(buildPillRendererUrl("http://127.0.0.1:5174/home?old=1#hash")).toBe(
+      "http://127.0.0.1:5174/home?shellMode=chat-overlay",
+    );
+  });
+
+  it("creates a bottom-centered transparent always-on-top window", async () => {
+    const closeHandlers: Array<() => void> = [];
+    const setAlwaysOnTop = vi.fn();
+    const windowMock = {
+      on: vi.fn((event: string, handler: () => void) => {
+        if (event === "close") closeHandlers.push(handler);
+      }),
+      setAlwaysOnTop,
+    };
+    mocks.createWindow.mockReturnValue(windowMock);
+    mocks.getPrimaryDisplay.mockReturnValue({
+      workArea: { x: 100, y: 50, width: 1600, height: 900 },
+    });
+
+    const { createPillWindow, getPillWindow } = await import("./pill-window");
+    const win = createPillWindow({
+      rendererUrl: "http://127.0.0.1:5174/",
+      preload: "preload.js",
+    });
+
+    expect(win).toBe(windowMock);
+    expect(mocks.createWindow).toHaveBeenCalledWith(
+      expect.objectContaining({
+        title: "Eliza Pill",
+        url: "http://127.0.0.1:5174/?shellMode=chat-overlay",
+        preload: "preload.js",
+        titleBarStyle: "hidden",
+        transparent: true,
+        activate: false,
+        frame: {
+          x: 720,
+          y: 654,
+          width: 360,
+          height: 280,
+        },
+      }),
+    );
+    expect(setAlwaysOnTop).toHaveBeenCalledWith(true);
+    expect(getPillWindow()).toBe(windowMock);
+
+    for (const handler of closeHandlers) handler();
+    expect(getPillWindow()).toBeNull();
+  });
+});

package/platforms/electrobun/src/pill-window.ts

@@ -0,0 +1,99 @@
+/**
+ * Pill overlay window for Electrobun.
+ *
+ * Spawns a single borderless, transparent, always-on-top BrowserWindow
+ * docked to the bottom-center of the user's primary display. The window
+ * loads the same renderer bundle as the main shell with
+ * `?shellMode=chat-overlay`, which routes to the live assistant overlay shell.
+ *
+ * Lifecycle:
+ *  - Created once at app boot, alongside the main window.
+ *  - Closing the main window does NOT close the pill, and vice versa.
+ *  - Quitting the app closes both (handled by Electrobun's standard
+ *    `exitOnLastWindowClosed` behavior firing when both windows are gone,
+ *    or by the application's quit menu).
+ *
+ * This is the persistent chat-overlay pill — created at app boot when
+ * shouldCreateDesktopPill() returns true (shellMode=chat-overlay). It is the
+ * live production voice/chat surface the user sees every day, rendering the
+ * ContinuousChatOverlay (NOT the old standalone VoicePill, which was removed).
+ */
+
+import { type BrowserWindow, Screen } from "electrobun/bun";
+import { createElectrobunBrowserWindow } from "./electrobun-window-options";
+import { logger } from "./logger";
+
+const PILL_WIDTH = 360;
+const PILL_HEIGHT = 280;
+const PILL_BOTTOM_MARGIN = 16;
+
+interface PillWindowFrame {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+function resolvePillFrame(): PillWindowFrame {
+  const display = Screen.getPrimaryDisplay();
+  const workArea = display.workArea;
+  return {
+    x: workArea.x + Math.round((workArea.width - PILL_WIDTH) / 2),
+    y: workArea.y + workArea.height - PILL_HEIGHT - PILL_BOTTOM_MARGIN,
+    width: PILL_WIDTH,
+    height: PILL_HEIGHT,
+  };
+}
+
+export function buildPillRendererUrl(rendererUrl: string): string {
+  const url = new URL(rendererUrl);
+  url.search = "?shellMode=chat-overlay";
+  url.hash = "";
+  return url.toString();
+}
+
+let pillWindow: BrowserWindow | null = null;
+
+export function createPillWindow(args: {
+  rendererUrl: string;
+  preload: string;
+}): BrowserWindow {
+  if (pillWindow) {
+    return pillWindow;
+  }
+
+  const frame = resolvePillFrame();
+  const url = buildPillRendererUrl(args.rendererUrl);
+
+  const win = createElectrobunBrowserWindow({
+    title: "Eliza Pill",
+    url,
+    preload: args.preload,
+    frame,
+    titleBarStyle: "hidden",
+    transparent: true,
+    activate: false,
+  });
+
+  try {
+    win.setAlwaysOnTop(true);
+  } catch (err) {
+    logger.warn(
+      `[pill-window] setAlwaysOnTop failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  win.on("close", () => {
+    pillWindow = null;
+  });
+
+  pillWindow = win;
+  logger.info(
+    `[pill-window] Spawned pill overlay at (${frame.x},${frame.y}) ${frame.width}x${frame.height}`,
+  );
+  return win;
+}
+
+export function getPillWindow(): BrowserWindow | null {
+  return pillWindow;
+}