relay-companion 0.1.0

package/overlay/main.cjs

@@ -0,0 +1,762 @@
+// Relay companion pill — a small floating, always-on-top Relay window that lists
+// incoming Relay attention items + tasks, and lazy-opens them in Claude Code / Codex.
+//
+// Motion principle: the OS window is a FIXED-SIZE, transparent, click-through canvas.
+// It is NEVER resized while animating. All expand/collapse motion is GPU-composited CSS
+// on the card inside it, so it stays perfectly smooth. The empty area around the card is
+// click-through, so the overlay never blocks the app behind it.
+//
+// Data:
+//   - Relay attention rows come from ${RELAY_HOME:-~/.relay-companion}/state.json under
+//     `state.packets` (staged by the companion daemon). Read it directly + fs.watch it.
+//   - Tasks come live from RelayClient.listTasks(), refreshed on a timer and on demand.
+//   - Contacts come live from RelayClient.listContacts() / upsertContact().
+//   - Mutations (accept/reject/approve/decline/answer) call RelayClient with device-token
+//     auth. ack/mark-read writes state.json directly (atomic temp+rename).
+
+const { app, BrowserWindow, ipcMain, shell, screen } = require("electron");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { execFile, spawn, pathToFileURL } = (() => {
+  const cp = require("node:child_process");
+  const url = require("node:url");
+  return { execFile: cp.execFile, spawn: cp.spawn, pathToFileURL: url.pathToFileURL };
+})();
+
+const RELAY_HOME = process.env.RELAY_HOME || process.env.RELAY_COMPANION_HOME || path.join(os.homedir(), ".relay-companion");
+const STATE_PATH = path.join(RELAY_HOME, "state.json");
+// The companion CLI entrypoint (same path the overlay resolves its ESM modules
+// from). Spawned with ELECTRON_RUN_AS_NODE so Electron runs it as plain Node.
+const RELAY_CLI = path.resolve(__dirname, "..", "bin", "relay.js");
+
+// Fixed transparent canvas, large enough to contain the inbox sheet + spring/shadow room.
+const WIN = { width: 520, height: 840 };
+const MARGIN = 8;
+const DEFAULT_WEB_BASE = "https://sendrelays.com";
+
+let win = null;
+let hostRunning = false; // Claude or Codex desktop app is running
+let lastHost = null; // most-recently foregrounded host: "claude" | "codex"
+let lastHostSeenAt = 0;
+let lastSig = "";
+
+// The ESM companion modules (config/client) are loaded lazily via dynamic import,
+// because this overlay runs as CommonJS under Electron while the package is ESM.
+let relayModules = null;
+let relayModulesPromise = null;
+function loadRelayModules() {
+  if (relayModules) return Promise.resolve(relayModules);
+  if (relayModulesPromise) return relayModulesPromise;
+  const clientUrl = pathToFileURL(path.join(__dirname, "..", "src", "client.js")).href;
+  const configUrl = pathToFileURL(path.join(__dirname, "..", "src", "config.js")).href;
+  relayModulesPromise = Promise.all([import(clientUrl), import(configUrl)])
+    .then(([client, config]) => {
+      relayModules = { RelayClient: client.RelayClient, config };
+      return relayModules;
+    })
+    .catch((error) => {
+      console.error("[overlay] failed to load relay modules:", error && error.message);
+      relayModulesPromise = null;
+      throw error;
+    });
+  return relayModulesPromise;
+}
+
+async function relayClient() {
+  const { RelayClient } = await loadRelayModules();
+  return new RelayClient();
+}
+
+app.setName("Relay");
+
+// ---- config / account ----------------------------------------------------
+
+function readConfigFile() {
+  const configPath =
+    process.env.RELAY_CONFIG ||
+    path.join(process.env.RELAY_CONFIG_DIR || path.join(os.homedir(), ".relay"), "config.json");
+  try {
+    return JSON.parse(fs.readFileSync(configPath, "utf8")) || {};
+  } catch {
+    return {};
+  }
+}
+
+function deviceToken() {
+  if (process.env.RELAY_DEVICE_TOKEN) return process.env.RELAY_DEVICE_TOKEN;
+  return readConfigFile().deviceToken || "";
+}
+
+function webBase() {
+  const cfg = readConfigFile();
+  const base = process.env.RELAY_WEB_URL || cfg.webUrl || DEFAULT_WEB_BASE;
+  return String(base).replace(/\/+$/, "");
+}
+
+function account() {
+  const cfg = readConfigFile();
+  const user = cfg.user || {};
+  return {
+    paired: Boolean(deviceToken()),
+    email: user.email || "",
+    name: user.name || "",
+  };
+}
+
+// Turn an actionUrl (absolute https, or a relative path) into an absolute URL.
+function absoluteUrl(pathOrUrl) {
+  const value = String(pathOrUrl || "").trim();
+  if (!value) return webBase();
+  if (/^https?:\/\//i.test(value)) return value;
+  const suffix = value.startsWith("/") ? value : `/${value}`;
+  return `${webBase()}${suffix}`;
+}
+
+function taskWebUrl(taskId) {
+  return `${webBase()}/app/tasks/${encodeURIComponent(taskId)}`;
+}
+
+// ---- state.json reading (Relay attention rows) ---------------------------
+
+function readStore() {
+  try {
+    return JSON.parse(fs.readFileSync(STATE_PATH, "utf8")) || {};
+  } catch {
+    return {};
+  }
+}
+
+function writeStateAtomic(store) {
+  try {
+    fs.mkdirSync(path.dirname(STATE_PATH), { recursive: true });
+    const tmp = `${STATE_PATH}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(store, null, 2)}\n`);
+    fs.renameSync(tmp, STATE_PATH);
+  } catch (error) {
+    console.error("[overlay] state write failed:", error && error.message);
+  }
+}
+
+// The inbound Relay attention rows, newest + unread first.
+function readRelays() {
+  const store = readStore();
+  const packets = (store && store.packets) || {};
+  return Object.entries(packets)
+    .map(([id, p]) => ({ id, ...(p || {}) }))
+    .filter((p) => p.direction === "inbound")
+    .map((p) => ({
+      id: p.id,
+      direction: "inbound",
+      state: p.state === "read" ? "read" : "unread",
+      unread: p.state !== "read",
+      relayNotificationKind: p.relayNotificationKind || "task_completed",
+      urgency: p.urgency || "normal",
+      senderName: p.senderName || "Relay",
+      title: p.title || p.displayTitle || "Relay",
+      displayTitle: p.displayTitle || p.title || "Relay",
+      bodyMarkdown: p.bodyMarkdown || "",
+      briefingMarkdown: p.briefingMarkdown || "",
+      createdAt: p.createdAt || "",
+      updatedAt: p.updatedAt || "",
+      actionUrl: p.actionUrl || "",
+      action: p.action || {},
+      quickReply: Boolean(p.quickReply),
+      taskId: p.taskId || null,
+      participantId: p.participantId || null,
+      messageId: p.messageId || null,
+      approvalId:
+        (p.action && (p.action.approvalId || (Array.isArray(p.action.actions) ? null : null))) || p.approvalId || null,
+      provider: p.provider || null,
+      contentPath: p.contentPath || null,
+      expectedVersion: p.expectedVersion || null,
+    }))
+    .sort((a, b) => {
+      if (a.unread !== b.unread) return a.unread ? -1 : 1; // unread always on top
+      return String(b.createdAt).localeCompare(String(a.createdAt)); // then newest
+    });
+}
+
+// ---- tasks (live) --------------------------------------------------------
+
+let tasksCache = [];
+let tasksLoadedOnce = null; // a promise that resolves after the first task load
+async function refreshTasks() {
+  try {
+    const client = await relayClient();
+    const res = await client.listTasks();
+    tasksCache = Array.isArray(res && res.tasks) ? res.tasks : [];
+  } catch (error) {
+    // Keep the last good cache; surface the error in the log but don't crash.
+    console.error("[overlay] listTasks failed:", error && error.message);
+  }
+  return tasksCache;
+}
+// Ensure the live task list is loaded at least once before the first payload is
+// served, so the renderer's initial paint already includes Tasks.
+function ensureTasksLoaded() {
+  if (!tasksLoadedOnce) tasksLoadedOnce = refreshTasks().catch(() => tasksCache);
+  return tasksLoadedOnce;
+}
+
+// ---- contacts (live) -----------------------------------------------------
+
+async function readContacts() {
+  try {
+    const client = await relayClient();
+    const res = await client.listContacts();
+    const contacts = Array.isArray(res && res.contacts) ? res.contacts : [];
+    return contacts
+      .map((c) => {
+        const emails = Array.isArray(c.emails) ? c.emails.filter(Boolean) : c.email ? [c.email] : [];
+        return {
+          id: c.id || "",
+          name: c.name || emails[0] || "",
+          email: emails[0] || c.email || "",
+          emails,
+          updatedAt: c.updatedAt || null,
+        };
+      })
+      .sort((a, b) => String(a.name).localeCompare(String(b.name)));
+  } catch (error) {
+    console.error("[overlay] listContacts failed:", error && error.message);
+    return [];
+  }
+}
+
+async function saveContact(input) {
+  const name = String((input && input.name) || "").trim();
+  const emails = Array.isArray(input && input.emails)
+    ? input.emails.map((e) => String(e || "").trim()).filter(Boolean)
+    : input && input.email
+      ? [String(input.email).trim()].filter(Boolean)
+      : [];
+  if (!name) throw new Error("A name is required");
+  for (const e of emails) if (!e.includes("@")) throw new Error("That email looks off.");
+  const client = await relayClient();
+  await client.upsertContact({ name, emails, email: emails[0] || "" });
+  return readContacts();
+}
+
+// ---- payload assembly + push to renderer ---------------------------------
+
+async function buildPayload() {
+  await ensureTasksLoaded();
+  const [relays, contacts] = [readRelays(), await readContacts()];
+  return {
+    account: account(),
+    relays,
+    tasks: tasksCache,
+    contacts,
+  };
+}
+
+let knownIds = null; // null until first load, so we never "notify" for rows already present
+async function pushInbox(force) {
+  if (!win || win.isDestroyed()) return;
+  const payload = await buildPayload();
+  const rows = payload.relays;
+  if (knownIds === null) {
+    knownIds = new Set(rows.map((r) => r.id));
+  } else {
+    const fresh = rows.filter((r) => r.unread && !knownIds.has(r.id));
+    knownIds = new Set(rows.map((r) => r.id));
+    if (fresh.length && win && !win.isDestroyed()) win.webContents.send("newRelay", fresh[0]); // newest arrival drives the peek
+  }
+  const sig = JSON.stringify({
+    relays: rows.map((r) => [r.id, r.relayNotificationKind, r.unread, r.title, r.senderName, r.urgency]),
+    tasks: payload.tasks.map((t) => [
+      t.id,
+      t.state,
+      t.updatedAt,
+      t.requiresViewerAction,
+      t.pendingApprovalCount,
+      Array.isArray(t.participants) ? t.participants.length : 0,
+    ]),
+    contacts: payload.contacts.map((c) => [c.id, c.name, c.email]),
+    account: [payload.account.paired, payload.account.email],
+  });
+  if (!force && sig === lastSig) {
+    if (!win || win.isDestroyed()) return;
+  }
+  lastSig = sig;
+  if (win && !win.isDestroyed()) win.webContents.send("inbox", payload);
+}
+
+// Refresh state-derived rows only (fast path used by fs.watch + the safety poll).
+function pushInboxQuiet() {
+  pushInbox(false).catch((error) => console.error("[overlay] pushInbox failed:", error && error.message));
+}
+
+// ---- mark-read (write state.json directly) -------------------------------
+
+function ackPacket(packetId) {
+  if (!packetId) return;
+  const store = readStore();
+  if (!store.packets || !store.packets[packetId]) return;
+  store.packets[packetId] = {
+    ...store.packets[packetId],
+    state: "read",
+    updatedAt: new Date().toISOString(),
+  };
+  writeStateAtomic(store);
+  pushInbox(true).catch(() => {});
+}
+
+// ---- mutations -----------------------------------------------------------
+
+function idempotencyKey(prefix) {
+  return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+
+function rowById(packetId) {
+  return readRelays().find((r) => r.id === packetId) || null;
+}
+
+// Find an approvalId for a share_approval row. The staged row may not carry it,
+// in which case the renderer routes to the web detail page (Review) instead.
+function approvalIdForRow(row) {
+  if (!row) return null;
+  if (row.approvalId) return row.approvalId;
+  const action = row.action || {};
+  if (action.approvalId) return action.approvalId;
+  return null;
+}
+
+async function runMutation(label, fn) {
+  try {
+    await fn();
+    await refreshTasks();
+    await pushInbox(true);
+    return { ok: true };
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error);
+    const conflict = error && (error.status === 409 || /stale|conflict|version/i.test(message));
+    console.error(`[overlay] ${label} failed:`, message);
+    await refreshTasks().catch(() => {});
+    await pushInbox(true).catch(() => {});
+    return { ok: false, error: message, conflict: Boolean(conflict) };
+  }
+}
+
+async function acceptTask(taskId, participantId) {
+  if (!taskId || !participantId) return { ok: false, error: "Missing task or participant id." };
+  const expectedVersion = taskVersion(taskId);
+  return runMutation("accept", async () => {
+    const client = await relayClient();
+    await client.acceptTask(taskId, participantId, {
+      idempotencyKey: idempotencyKey("accept"),
+      ...(expectedVersion != null ? { expectedVersion } : {}),
+    });
+  });
+}
+
+async function rejectTask(taskId, participantId) {
+  if (!taskId || !participantId) return { ok: false, error: "Missing task or participant id." };
+  const expectedVersion = taskVersion(taskId);
+  return runMutation("reject", async () => {
+    const client = await relayClient();
+    await client.rejectTask(taskId, participantId, {
+      idempotencyKey: idempotencyKey("reject"),
+      ...(expectedVersion != null ? { expectedVersion } : {}),
+    });
+  });
+}
+
+async function approveShare(taskId, approvalId) {
+  if (!taskId || !approvalId) return { ok: false, error: "Missing task or approval id." };
+  return runMutation("approve", async () => {
+    const client = await relayClient();
+    await client.approveShare(taskId, approvalId, { idempotencyKey: idempotencyKey("approve") });
+  });
+}
+
+async function declineShare(taskId, approvalId) {
+  if (!taskId || !approvalId) return { ok: false, error: "Missing task or approval id." };
+  return runMutation("decline", async () => {
+    const client = await relayClient();
+    await client.declineShare(taskId, approvalId, { idempotencyKey: idempotencyKey("decline") });
+  });
+}
+
+async function answerQuestion(taskId, messageId, text) {
+  const answerMarkdown = String(text || "").trim();
+  if (!taskId || !messageId) return { ok: false, error: "Missing task or message id." };
+  if (!answerMarkdown) return { ok: false, error: "Write an answer first." };
+  return runMutation("answer", async () => {
+    const client = await relayClient();
+    await client.answerHumanQuestion(taskId, messageId, {
+      answerMarkdown,
+      idempotencyKey: idempotencyKey("answer"),
+    });
+  });
+}
+
+function taskVersion(taskId) {
+  const task = tasksCache.find((t) => t.id === taskId);
+  return task && task.version != null ? task.version : null;
+}
+
+// ---- click-to-open a Relay row -------------------------------------------
+
+// Best-effort frontmost-app bundle id (no permission prompt; uses lsappinfo).
+function frontmostBundleId(cb) {
+  execFile("/usr/bin/lsappinfo", ["front"], (e1, asn) => {
+    const a = String(asn || "").trim();
+    if (e1 || !a) return cb(null);
+    execFile("/usr/bin/lsappinfo", ["info", "-only", "bundleid", a], (e2, out) => {
+      const m = String(out || "").match(/"CFBundleIdentifier"\s*=\s*"([^"]+)"/);
+      cb(e2 ? null : m ? m[1] : null);
+    });
+  });
+}
+
+function hostFromBundle(bundle) {
+  if (bundle === "com.anthropic.claudefordesktop") return "claude";
+  if (bundle === "com.openai.codex") return "codex";
+  return null;
+}
+
+function rememberForegroundHost(host) {
+  if (!host) return;
+  lastHost = host;
+  lastHostSeenAt = Date.now();
+}
+
+function appInstalled(appName) {
+  const name = String(appName || "").replace(/[^A-Za-z0-9 ._-]/g, "");
+  if (!name) return false;
+  const candidates = [
+    path.join("/Applications", `${name}.app`),
+    path.join(os.homedir(), "Applications", `${name}.app`),
+  ];
+  return candidates.some((candidate) => fs.existsSync(candidate));
+}
+
+function defaultClickHost() {
+  // Spec: neither foregrounded -> prefer Codex if installed, otherwise Claude Code.
+  if (appInstalled("Codex")) return "codex";
+  if (appInstalled("Claude")) return "claude";
+  return "codex";
+}
+
+function isRelayBundle(bundle) {
+  const clean = String(bundle || "").toLowerCase();
+  return clean.includes("relay") || clean.includes("electron");
+}
+
+// Click-to-open a Relay row. A relay materializes a REAL native agent session
+// inside the already-running foregrounded host (Claude Desktop or Codex) via the
+// companion CLI's `open` command, so it appears in that app's recents rail. The
+// CLI prints { url, skipExternalOpen, openedInHost }; when the host wasn't driven
+// directly (skipExternalOpen false) the overlay fires shell.openExternal(url) as
+// the fallback. The web view is only used if the CLI itself fails. Connector
+// reauth is a web OAuth flow, so it intentionally opens the connectors page.
+function openPacket(packetId) {
+  if (!packetId) return;
+  const row = rowById(packetId);
+  if (win && !win.isDestroyed()) win.webContents.send("opening", packetId);
+  const finish = () => {
+    ackPacket(packetId);
+    if (win && !win.isDestroyed()) win.webContents.send("openDone", packetId); // stop the row spinner
+  };
+  if (row && row.relayNotificationKind === "connector_reauth") {
+    shell
+      .openExternal(`${webBase()}/app/connectors`)
+      .catch((error) => console.error("[overlay] open failed:", error && error.message));
+    return finish();
+  }
+  frontmostBundleId((bundle) => {
+    const frontHost = hostFromBundle(bundle);
+    if (frontHost) rememberForegroundHost(frontHost);
+    const capturedHostIsFresh = lastHost && Date.now() - lastHostSeenAt < 2500;
+    const host = frontHost || ((!bundle || isRelayBundle(bundle)) && capturedHostIsFresh ? lastHost : defaultClickHost());
+    const env = {
+      ...process.env,
+      ELECTRON_RUN_AS_NODE: "1",
+      RELAY_HOME,
+      CODEX_CLI_PATH: process.env.CODEX_CLI_PATH || "/Applications/Codex.app/Contents/Resources/codex",
+    };
+    if (host === "claude") {
+      // Let the overlay own the actual deep-link launch. Otherwise the helper can open Claude first,
+      // then keep the row spinner alive while it does post-import title repair.
+      env.RELAY_IMPORT_CLAUDE_DESKTOP = "0";
+    }
+    const child = spawn(process.execPath, [RELAY_CLI, "open", packetId, "--host", host], {
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (data) => (out += data));
+    child.stderr.on("data", (data) => (err += data));
+    child.on("exit", (code) => {
+      let url = null;
+      let skipExternalOpen = false;
+      try {
+        const parsed = JSON.parse(out.trim());
+        url = parsed.url || null;
+        skipExternalOpen = Boolean(parsed.skipExternalOpen);
+      } catch {}
+      if (url || skipExternalOpen) {
+        if (url && !skipExternalOpen) {
+          shell.openExternal(url).catch((error) => console.error("[overlay] openExternal failed:", error && error.message));
+        }
+      } else {
+        console.error(
+          "[overlay] open failed for",
+          packetId,
+          "host",
+          host,
+          "code",
+          code,
+          "stderr:",
+          err.trim().split("\n").slice(-2).join(" | "),
+        );
+        // Last-resort web fallback so the click is never a dead end.
+        const target = row && row.taskId
+          ? taskWebUrl(row.taskId)
+          : row && row.actionUrl
+            ? absoluteUrl(row.actionUrl)
+            : webBase();
+        shell.openExternal(target).catch((e) => console.error("[overlay] web fallback failed:", e && e.message));
+      }
+      finish();
+    });
+    child.on("error", (error) => {
+      console.error("[overlay] open spawn error:", error && error.message);
+      finish();
+    });
+  });
+}
+
+// Click-to-open a task row. Mirrors openPacket: materialize the task into a REAL
+// native agent session inside the foregrounded host (Claude Desktop or Codex) via
+// `relay open --task <taskId> --host <host>`, so it appears in that app's recents
+// rail seeded with the task's objective + state + an instruction to call
+// relay_task_status for live detail. The web view is only used if the CLI fails.
+function openTaskDetail(taskId) {
+  if (!taskId) return;
+  frontmostBundleId((bundle) => {
+    const frontHost = hostFromBundle(bundle);
+    if (frontHost) rememberForegroundHost(frontHost);
+    const capturedHostIsFresh = lastHost && Date.now() - lastHostSeenAt < 2500;
+    const host = frontHost || ((!bundle || isRelayBundle(bundle)) && capturedHostIsFresh ? lastHost : defaultClickHost());
+    const env = {
+      ...process.env,
+      ELECTRON_RUN_AS_NODE: "1",
+      RELAY_HOME,
+      CODEX_CLI_PATH: process.env.CODEX_CLI_PATH || "/Applications/Codex.app/Contents/Resources/codex",
+    };
+    if (host === "claude") {
+      // Let the overlay own the actual deep-link launch (see openPacket).
+      env.RELAY_IMPORT_CLAUDE_DESKTOP = "0";
+    }
+    const child = spawn(process.execPath, [RELAY_CLI, "open", "--task", taskId, "--host", host], {
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (data) => (out += data));
+    child.stderr.on("data", (data) => (err += data));
+    child.on("exit", (code) => {
+      let url = null;
+      let skipExternalOpen = false;
+      try {
+        const parsed = JSON.parse(out.trim());
+        url = parsed.url || null;
+        skipExternalOpen = Boolean(parsed.skipExternalOpen);
+      } catch {}
+      if (url || skipExternalOpen) {
+        if (url && !skipExternalOpen) {
+          shell.openExternal(url).catch((error) => console.error("[overlay] openExternal failed:", error && error.message));
+        }
+      } else {
+        console.error(
+          "[overlay] task open failed for",
+          taskId,
+          "host",
+          host,
+          "code",
+          code,
+          "stderr:",
+          err.trim().split("\n").slice(-2).join(" | "),
+        );
+        // Last-resort web fallback so the click is never a dead end.
+        shell
+          .openExternal(taskWebUrl(taskId))
+          .catch((e) => console.error("[overlay] task web fallback failed:", e && e.message));
+      }
+    });
+    child.on("error", (error) => {
+      console.error("[overlay] task open spawn error:", error && error.message);
+      shell
+        .openExternal(taskWebUrl(taskId))
+        .catch((e) => console.error("[overlay] task web fallback failed:", e && e.message));
+    });
+  });
+}
+
+function openUrlTarget(url) {
+  const target = absoluteUrl(url);
+  shell.openExternal(target).catch((error) => console.error("[overlay] open failed:", error && error.message));
+}
+
+// ---- window placement / visibility ---------------------------------------
+
+function anchorTopRight() {
+  const display = screen.getDisplayNearestPoint(screen.getCursorScreenPoint()) || screen.getPrimaryDisplay();
+  const wa = display.workArea;
+  return { x: wa.x + wa.width - WIN.width - MARGIN, y: wa.y + MARGIN, width: WIN.width, height: WIN.height };
+}
+
+function maybeShow() {
+  if (!win || win.isDestroyed()) return;
+  if (hostRunning) {
+    if (!win.isVisible()) win.showInactive();
+  } else if (win.isVisible()) {
+    win.hide();
+  }
+}
+
+function pollHosts() {
+  // Show whenever EITHER host app is running; track the foregrounded one for click routing.
+  execFile("/bin/ps", ["-Ao", "comm"], (err, stdout) => {
+    const s = String(stdout || "");
+    const claude = !err && /\/Claude\.app\/Contents\/MacOS\/Claude(\n|$)/.test(s);
+    const codex = !err && /\/Codex\.app\/Contents\/MacOS\/Codex(\n|$)/.test(s);
+    hostRunning = claude || codex;
+    maybeShow();
+  });
+  frontmostBundleId((bundle) => {
+    rememberForegroundHost(hostFromBundle(bundle));
+  });
+}
+
+function createWindow() {
+  win = new BrowserWindow({
+    ...anchorTopRight(),
+    frame: false,
+    transparent: true,
+    backgroundColor: "#00000000",
+    resizable: false,
+    movable: false,
+    show: false,
+    hasShadow: false,
+    skipTaskbar: true,
+    fullscreenable: false,
+    maximizable: false,
+    minimizable: false,
+    focusable: false, // never steal keyboard focus from Claude/Codex
+    title: "Relay",
+    webPreferences: {
+      preload: path.join(__dirname, "preload.cjs"),
+      contextIsolation: true,
+      nodeIntegration: false,
+    },
+  });
+
+  win.setAlwaysOnTop(true, "floating");
+  win.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true });
+  // Empty canvas is click-through; the renderer flips this on when the pointer is over the card.
+  win.setIgnoreMouseEvents(true, { forward: true });
+  win.loadFile(path.join(__dirname, "inbox.html"));
+  // surface renderer + preload errors to the overlay log so failures are visible
+  win.webContents.on("console-message", (...a) => {
+    const d =
+      a[1] && typeof a[1] === "object"
+        ? `${a[1].level} ${a[1].message} @ ${a[1].sourceId}:${a[1].lineNumber}`
+        : `${a[1]} ${a[2]} @ ${a[4]}:${a[3]}`;
+    console.error("[renderer]", d);
+  });
+  win.webContents.on("preload-error", (_e, p, err) => console.error("[preload-error]", p, err && err.message));
+  win.webContents.on("render-process-gone", (_e, det) => console.error("[render-gone]", JSON.stringify(det)));
+  win.once("ready-to-show", () => {
+    // buildPayload() awaits the first task load, so a single push paints all tabs.
+    pushInbox(true).catch((error) => console.error("[overlay] initial push failed:", error && error.message));
+    pollHosts();
+  });
+
+  try {
+    fs.watchFile(STATE_PATH, { interval: 800 }, () => pushInboxQuiet());
+  } catch {}
+  try {
+    fs.watch(RELAY_HOME, { persistent: true }, (_evt, file) => {
+      if (!file || String(file).startsWith("state.json")) pushInboxQuiet();
+    });
+  } catch {}
+  setInterval(() => pushInboxQuiet(), 2500); // safety net for state.json
+  setInterval(() => {
+    refreshTasks()
+      .then(() => pushInbox(false))
+      .catch(() => {});
+  }, 5000); // live task refresh
+  setInterval(pollHosts, 1500);
+}
+
+// ---- ipc -----------------------------------------------------------------
+
+ipcMain.handle("relay:get", () => buildPayload());
+ipcMain.on("relay:open", (_e, id) => openPacket(id));
+ipcMain.on("relay:openTask", (_e, taskId) => openTaskDetail(taskId));
+ipcMain.on("relay:openUrl", (_e, url) => openUrlTarget(url));
+ipcMain.on("relay:ack", (_e, id) => ackPacket(id));
+ipcMain.handle("relay:refreshTasks", async () => {
+  await refreshTasks();
+  await pushInbox(true);
+  return tasksCache;
+});
+ipcMain.handle("relay:accept", (_e, taskId, participantId) => acceptTask(taskId, participantId));
+ipcMain.handle("relay:reject", (_e, taskId, participantId) => rejectTask(taskId, participantId));
+ipcMain.handle("relay:approve", (_e, taskId, approvalId) => approveShare(taskId, approvalId));
+ipcMain.handle("relay:decline", (_e, taskId, approvalId) => declineShare(taskId, approvalId));
+ipcMain.handle("relay:answer", (_e, taskId, messageId, text) => answerQuestion(taskId, messageId, text));
+ipcMain.handle("relay:contacts", () => readContacts());
+ipcMain.handle("relay:contactSave", (_e, input) => saveContact(input));
+
+// The overlay is normally focusable:false so it never steals keyboard focus from
+// Claude/Codex. Text fields (the contact form, quick reply) need focus, so the renderer
+// asks us to grant it while a field is open and revoke it the moment the form closes.
+ipcMain.on("relay:setFocusable", (_e, focusable) => {
+  if (!win || win.isDestroyed()) return;
+  win.setFocusable(Boolean(focusable));
+  if (focusable) win.focus();
+});
+ipcMain.on("relay:interactive", (_e, interactive) => {
+  // Capture the foreground host the instant the pointer reaches the overlay — BEFORE the click can
+  // momentarily activate this accessory window. Without this, clicking a relay while a host is merely
+  // windowed (not fullscreen) makes the at-click frontmost detection return the overlay/Electron.
+  if (interactive) {
+    frontmostBundleId((bundle) => {
+      rememberForegroundHost(hostFromBundle(bundle));
+    });
+  }
+  if (win && !win.isDestroyed()) win.setIgnoreMouseEvents(!interactive, { forward: true });
+});
+ipcMain.on("relay:setPos", (_e, x, y) => {
+  if (win && !win.isDestroyed() && Number.isFinite(x) && Number.isFinite(y)) win.setPosition(Math.round(x), Math.round(y));
+});
+ipcMain.handle("relay:soundBytes", (_e, name) => {
+  const clean = String(name).replace(/[^A-Za-z]/g, "");
+  const candidates = [
+    path.join(__dirname, "sounds", `${clean.toLowerCase()}.wav`), // bundled WAV (Chromium decodes reliably)
+    `/System/Library/Sounds/${clean}.aiff`, // fallback to the system sound
+  ];
+  for (const file of candidates) {
+    try {
+      const b = fs.readFileSync(file);
+      return b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength);
+    } catch {}
+  }
+  return null; // gracefully null when no sound is available
+});
+
+app.whenReady().then(() => {
+  if (process.platform === "darwin" && app.dock) app.dock.hide(); // accessory: no dock icon, no NC banners
+  createWindow();
+});
+
+app.on("window-all-closed", () => {
+  /* keep running as a background agent; relaunched by launchd KeepAlive if it dies */
+});