relay-companion 0.1.7 → 0.1.9

package/overlay/inbox.html

@@ -57,6 +57,18 @@
   }
   @keyframes appIn { from { opacity:0; transform:scale(.97); } to { opacity:1; transform:none; } }
 
+  /* Dismissal states. `offstage` parks the card invisibly while the OS window is hidden.
+     `bye` is the graceful exit (✕ click, or a ghost notification finishing). A `ghost`
+     card is the designed notification shown while the pill is dismissed: it emerges like
+     a banner (drift down + fade) and NEVER folds back into a pill — it just leaves. */
+  .card.offstage { visibility:hidden; animation:none; }
+  .card.bye { animation:byeOut .3s var(--settle) both; pointer-events:none; }
+  @keyframes byeOut { from { opacity:1; transform:none; } to { opacity:0; transform:scale(.96) translateY(-10px); } }
+  .card.ghost { animation:ghostIn .5s var(--soft) both; }
+  @keyframes ghostIn { from { opacity:0; transform:translateY(-14px) scale(.98); } to { opacity:1; transform:none; } }
+  .card.ghost.bye { animation:ghostOut .38s var(--settle) both; }
+  @keyframes ghostOut { from { opacity:1; transform:none; } to { opacity:0; transform:translateY(-12px) scale(.985); } }
+
   /* brand lockup — present in BOTH states; no surface, no rule */
   .lockup {
     flex:0 0 44px; display:flex; align-items:center; gap:9px;
@@ -78,7 +90,9 @@
     transition:color .18s var(--settle), opacity .18s var(--settle), width .18s var(--settle), margin .18s var(--settle);
   }
   .lockup:hover .minimize-hint { color:var(--muted-2); }
-  .card.collapsed .minimize-hint {
+  .card.collapsed .minimize-hint,
+  .card.peek .minimize-hint {
+    /* folded pill and notification banner: tapping the lockup EXPANDS, so no "Minimize" */
     width:0;
     margin-right:0;
     overflow:hidden;
@@ -89,6 +103,17 @@
     color:var(--accent); line-height:1; transition:color .3s var(--settle);
   }
   .count.zero { color:var(--muted-3); }
+  /* ✕ — fully hide the overlay; the Relay mark in the menu bar brings it back. Present in
+     every card state (expanded, pill, notification) so the pill is always escapable. */
+  .close-x {
+    flex:0 0 auto; appearance:none; border:0; background:transparent; cursor:pointer;
+    width:20px; height:20px; border-radius:6px; padding:0; margin-left:6px; margin-right:-6px;
+    display:inline-flex; align-items:center; justify-content:center;
+    color:var(--muted-3);
+    transition:color .15s var(--settle), background-color .15s var(--settle);
+  }
+  .close-x:hover { color:var(--ink-2); background:rgba(31,26,23,.06); }
+  .close-x:active { color:var(--ink); }
   @keyframes countRoll { from { transform:translateY(-6px); opacity:.3; } to { transform:none; opacity:1; } }
 
   /* tab control — individual rounded-rect buttons (the loved control) */
@@ -412,6 +437,9 @@
       <span class="spacer"></span>
       <span class="minimize-hint">Minimize</span>
       <span class="count zero" id="count">0</span>
+      <button class="close-x" id="closeX" type="button" aria-label="Hide Relay" title="Hide Relay — reopen from the menu bar">
+        <svg width="9" height="9" viewBox="0 0 10 10" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" aria-hidden="true"><path d="M1 1l8 8M9 1L1 9"/></svg>
+      </button>
     </div>
 
     <nav class="tabs" aria-label="Relay views">
@@ -484,6 +512,7 @@
 <script>
   const cardEl = document.getElementById("card");
   const lockupEl = document.getElementById("lockup");
+  const closeXEl = document.getElementById("closeX");
   const countEl = document.getElementById("count");
   const tabEls = [...document.querySelectorAll(".tab")];
   const scrollEl = document.getElementById("scroll");
@@ -512,7 +541,7 @@
 
   const REDUCED = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
   const EXPANDED = { w: 344, h: 524 };
-  const PILL = { w: 168, h: 44 };
+  const PILL = { w: 178, h: 44 }; // wide enough for mark + word + count + ✕
   const PEEK = { w: 344, h: 118 };
 
   // ---------- zero-latency sound (Web Audio, pre-decoded) ----------
@@ -581,6 +610,7 @@
   // ---------- collapse / expand / peek ----------
   let collapsed = false;
   let peeking = false, peekTimer = null;
+  let ghost = false, ghostTimer = null; // notification-only mode while the pill is dismissed
   function clearPeek() {
     if (peekTimer) { clearTimeout(peekTimer); peekTimer = null; }
     peeking = false;
@@ -594,6 +624,87 @@
     springTo(collapsed ? PILL.w : EXPANDED.w, collapsed ? PILL.h : EXPANDED.h);
     playTink();
   }
+  // Park the card invisibly at expanded size while the OS window is hidden, so the
+  // next appearance (tray reopen / ghost banner) starts from a clean slate.
+  function snapSize(w, h) {
+    W.v = W.t = w; H.v = H.t = h;
+    if (raf) { cancelAnimationFrame(raf); raf = null; cardEl.style.willChange = ""; }
+    cardEl.style.width = w + "px";
+    cardEl.style.height = h + "px";
+  }
+  function resetOffstage() {
+    ghost = false;
+    if (ghostTimer) { clearTimeout(ghostTimer); ghostTimer = null; }
+    clearPeek();
+    collapsed = false;
+    cardEl.classList.add("offstage");
+    cardEl.classList.remove("collapsed", "ghost", "bye");
+    snapSize(EXPANDED.w, EXPANDED.h);
+  }
+  // ✕ — the card leaves gracefully, then the main process hides the window and keeps
+  // it hidden (persisted) until the menu-bar Relay mark is clicked.
+  function dismissOverlay() {
+    if (cardEl.classList.contains("bye")) return;
+    if (ghostTimer) { clearTimeout(ghostTimer); ghostTimer = null; }
+    if (peekTimer) { clearTimeout(peekTimer); peekTimer = null; }
+    const wasGhost = ghost;
+    cardEl.classList.add("bye");
+    setInteractive(false);
+    setTimeout(() => {
+      if (wasGhost) window.relay.notifDone(); // already dismissed; just re-hide the window
+      else window.relay.dismiss();
+      resetOffstage();
+    }, wasGhost ? 380 : 300);
+  }
+  // A relay arrived while dismissed: the same designed banner, but as a free-standing
+  // notification. It emerges at banner size (no pill morph — there is no pill), and
+  // when done it fades away instead of folding back into anything.
+  function ghostArrival(row) {
+    if (ghostTimer) { clearTimeout(ghostTimer); ghostTimer = null; }
+    clearPeek();
+    collapsed = false;
+    cardEl.classList.remove("collapsed", "offstage", "bye");
+    snapSize(PEEK.w, PEEK.h);
+    ghost = true; peeking = true;
+    cardEl.classList.add("peek", "ghost");
+    const kind = row && row.relayNotificationKind;
+    activeView = (kind === "task_request" || kind === "share_approval") ? "tasks" : "relays";
+    syncTabs();
+    applyView();
+    renderAll();
+    scrollEl.scrollTop = 0;
+    playTink();
+    // Leave after ~7s — but never rug-pull someone mid-reply or with the pointer on
+    // the banner; check again shortly instead (macOS banners hold while hovered too).
+    ghostTimer = setTimeout(function tick() {
+      ghostTimer = null;
+      if (interactive || quickReplyIsActive()) { ghostTimer = setTimeout(tick, 4000); return; }
+      dismissOverlay(); // rides the ghostOut exit, then main re-hides the window
+    }, 7000);
+  }
+  // Menu-bar Relay mark clicked: the card comes back FULLY OPEN (never the pill).
+  function trayOpen() {
+    const wasOffstage = cardEl.classList.contains("offstage") || cardEl.classList.contains("bye");
+    if (ghostTimer) { clearTimeout(ghostTimer); ghostTimer = null; }
+    ghost = false;
+    clearPeek();
+    collapsed = false;
+    cardEl.classList.remove("collapsed");
+    if (wasOffstage) {
+      // fresh entrance: snap to expanded and replay the appear animation
+      cardEl.classList.remove("ghost", "bye", "offstage");
+      snapSize(EXPANDED.w, EXPANDED.h);
+      cardEl.style.animation = "none";
+      void cardEl.offsetWidth;
+      cardEl.style.animation = "";
+    } else {
+      // visible (maybe mid-banner): keep animation-bearing classes untouched so nothing
+      // restarts — just morph to full size on the spring.
+      springTo(EXPANDED.w, EXPANDED.h);
+    }
+    renderAll();
+    playTink();
+  }
   // A new relay arrived. If folded, peek open like an iOS banner (~7s) then fold back.
   // The peek routes to the tab the item lives in: task_request / share_approval -> Tasks
   // (the clean split), everything else -> Relays.
@@ -620,6 +731,14 @@
     }, 7000);
   }
   function openFull() {
+    if (ghost) {
+      // Engaging with a ghost banner brings the pill back for real. Keep the .ghost
+      // class (removing it while visible would restart the base entrance animation);
+      // it only influences which exit animation would play later.
+      ghost = false;
+      if (ghostTimer) { clearTimeout(ghostTimer); ghostTimer = null; }
+      window.relay.undismiss();
+    }
     clearPeek();
     collapsed = false;
     cardEl.classList.remove("collapsed");
@@ -627,6 +746,14 @@
     playTink();
   }
 
+  // ---------- the ✕ ----------
+  // Swallow the mousedown so the lockup's drag/tap-fold never engages.
+  closeXEl.addEventListener("mousedown", (e) => { e.stopPropagation(); });
+  closeXEl.addEventListener("click", (e) => {
+    e.stopPropagation();
+    dismissOverlay();
+  });
+
   // ---------- drag the lockup to move, tap it to fold ----------
   let dragging = false, offX = 0, offY = 0, downSX = 0, downSY = 0, moved = 0;
   lockupEl.addEventListener("mousedown", (e) => {
@@ -1418,7 +1545,14 @@
   }
 
   window.relay.onInbox(onPayload);
-  if (window.relay.onNewRelay) window.relay.onNewRelay((row) => notifyArrival(row));
+  if (window.relay.onNewRelay) window.relay.onNewRelay((row, opts) => {
+    if (opts && opts.ghost) ghostArrival(row); // pill dismissed -> free-standing banner
+    else notifyArrival(row);
+  });
+  if (window.relay.onOpenFull) window.relay.onOpenFull(() => trayOpen());
+  // The OS window was just re-shown and main re-asserted click-through; reset the
+  // local flag so the next mousemove re-runs the interactivity handshake cleanly.
+  if (window.relay.onShown) window.relay.onShown(() => { interactive = false; });
   if (window.relay.onOpenDone) window.relay.onOpenDone((id) => stopOpening(id));
   window.relay.refresh().then((p) => {
     onPayload(p);

package/overlay/main.cjs

@@ -6,6 +6,11 @@
 // 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.
 //
+// Visibility: the card carries a ✕ that hides the overlay entirely (persisted). The Relay
+// mark in the macOS menu bar (Tray) brings it back fully open. While dismissed, fresh
+// relays still show the designed banner as a "ghost" notification — the window appears
+// just for the banner, which fades away instead of folding back into a pill.
+//
 // 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.
@@ -14,7 +19,7 @@
 //   - 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 { app, BrowserWindow, Tray, ipcMain, nativeImage, shell, screen } = require("electron");
 const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
@@ -36,11 +41,33 @@ const MARGIN = 8;
 const DEFAULT_WEB_BASE = "https://sendrelays.com";
 
 let win = null;
+let tray = 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 = "";
 
+// Dismissed mode: the user clicked the ✕ on the card, so the overlay stays hidden
+// until they click the Relay menu-bar icon. Persisted across relaunches. While
+// dismissed, a fresh relay still shows the designed notification (a "ghost" peek):
+// the window appears just for the banner, then hides again when it finishes.
+const OVERLAY_PREFS_PATH = path.join(RELAY_HOME, "overlay-prefs.json");
+let dismissed = false;
+let ghostActive = false; // a ghost notification is on screen while dismissed
+let trayForcedVisible = false; // tray click while no host is running still shows the card
+try {
+  dismissed = JSON.parse(fs.readFileSync(OVERLAY_PREFS_PATH, "utf8")).dismissed === true;
+} catch {}
+function setDismissed(value) {
+  dismissed = Boolean(value);
+  try {
+    fs.mkdirSync(RELAY_HOME, { recursive: true });
+    fs.writeFileSync(OVERLAY_PREFS_PATH, `${JSON.stringify({ dismissed }, null, 2)}\n`);
+  } catch (error) {
+    console.error("[overlay] prefs write failed:", error && error.message);
+  }
+}
+
 // 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;
@@ -290,7 +317,20 @@ async function pushInbox(force) {
   } 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
+    if (fresh.length && win && !win.isDestroyed()) {
+      // newest arrival drives the peek. While dismissed, the same designed banner still
+      // shows — as a "ghost": the window appears for the notification only, and the
+      // renderer fades it out (never folding back into a pill) when it's done.
+      if (dismissed) {
+        if (hostRunning) {
+          ghostActive = true;
+          showOverlayWindow();
+          win.webContents.send("newRelay", fresh[0], { ghost: true });
+        }
+      } else {
+        win.webContents.send("newRelay", fresh[0], { ghost: false });
+      }
+    }
   }
   const sig = JSON.stringify({
     relays: rows.map((r) => [r.id, r.relayNotificationKind, r.unread, r.title, r.senderName, r.urgency]),
@@ -646,10 +686,25 @@ function anchorTopRight() {
   return { x: wa.x + wa.width - WIN.width - MARGIN, y: wa.y + MARGIN, width: WIN.width, height: WIN.height };
 }
 
+// Show the overlay window. Electron's forwarded-mousemove stream (the thing that
+// lets the renderer detect hover on a click-through window) can stall across a
+// hide()/show() cycle, leaving the window permanently click-through. Re-assert
+// setIgnoreMouseEvents on every hidden->shown transition and tell the renderer to
+// reset its interactivity handshake.
+function showOverlayWindow() {
+  if (!win || win.isDestroyed() || win.isVisible()) return;
+  win.showInactive();
+  win.setIgnoreMouseEvents(true, { forward: true });
+  win.webContents.send("shown");
+}
+
 function maybeShow() {
   if (!win || win.isDestroyed()) return;
-  if (hostRunning) {
-    if (!win.isVisible()) win.showInactive();
+  // Dismissed keeps the window hidden except while a ghost notification is up.
+  // trayForcedVisible honors an explicit menu-bar click even when no host runs.
+  const wanted = (hostRunning || trayForcedVisible) && (!dismissed || ghostActive);
+  if (wanted) {
+    showOverlayWindow();
   } else if (win.isVisible()) {
     win.hide();
   }
@@ -662,6 +717,7 @@ function pollHosts() {
     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;
+    if (hostRunning) trayForcedVisible = false; // normal host-based visibility takes back over
     maybeShow();
   });
   frontmostBundleId((bundle) => {
@@ -730,6 +786,29 @@ function createWindow() {
   setInterval(pollHosts, 1500);
 }
 
+// ---- menu bar (tray) -------------------------------------------------------
+
+// The Relay mark lives in the macOS menu bar. Clicking it brings the card back
+// FULLY OPEN (never the folded pill) — the counterpart to the card's ✕, which
+// hides the overlay entirely. The *Template naming makes macOS tint the mark
+// for light/dark menu bars automatically.
+function createTray() {
+  const icon = nativeImage.createFromPath(path.join(__dirname, "relayTrayTemplate.png"));
+  if (icon.isEmpty()) {
+    console.error("[overlay] tray icon missing; menu bar reopen unavailable");
+    return;
+  }
+  tray = new Tray(icon);
+  tray.setToolTip("Relay");
+  tray.on("click", () => {
+    setDismissed(false);
+    ghostActive = false;
+    if (!hostRunning) trayForcedVisible = true; // an explicit click always gets the card
+    maybeShow();
+    if (win && !win.isDestroyed()) win.webContents.send("openFull");
+  });
+}
+
 // ---- ipc -----------------------------------------------------------------
 
 ipcMain.handle("relay:get", () => buildPayload());
@@ -772,6 +851,27 @@ ipcMain.on("relay:interactive", (_e, interactive) => {
 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));
 });
+// ✕ on the card: hide the overlay entirely until the menu-bar Relay mark is clicked.
+// The renderer plays its exit animation first, then sends this.
+ipcMain.on("relay:dismiss", () => {
+  setDismissed(true);
+  ghostActive = false;
+  trayForcedVisible = false;
+  if (win && !win.isDestroyed() && win.isVisible()) win.hide();
+});
+// The user engaged with a ghost notification (tapped the lockup to expand it):
+// the card is fully open again, so leave dismissed mode.
+ipcMain.on("relay:undismiss", () => {
+  setDismissed(false);
+  ghostActive = false;
+  maybeShow();
+});
+// A ghost notification finished its exit animation; re-hide the window if the
+// overlay is still dismissed.
+ipcMain.on("relay:notifDone", () => {
+  ghostActive = false;
+  if (dismissed && win && !win.isDestroyed() && win.isVisible()) win.hide();
+});
 ipcMain.handle("relay:soundBytes", (_e, name) => {
   const clean = String(name).replace(/[^A-Za-z]/g, "");
   const candidates = [
@@ -799,6 +899,7 @@ if (!gotSingleInstanceLock) {
   app.whenReady().then(() => {
     if (process.platform === "darwin" && app.dock) app.dock.hide(); // accessory: no dock icon, no NC banners
     createWindow();
+    createTray();
   });
 
   app.on("window-all-closed", () => {

package/overlay/preload.cjs

@@ -3,8 +3,10 @@ const { contextBridge, ipcRenderer } = require("electron");
 contextBridge.exposeInMainWorld("relay", {
   // streams from main -> renderer
   onInbox: (cb) => ipcRenderer.on("inbox", (_e, payload) => cb(payload)),
-  onNewRelay: (cb) => ipcRenderer.on("newRelay", (_e, relay) => cb(relay)),
+  onNewRelay: (cb) => ipcRenderer.on("newRelay", (_e, relay, opts) => cb(relay, opts || {})),
   onOpenDone: (cb) => ipcRenderer.on("openDone", (_e, id) => cb(id)),
+  onOpenFull: (cb) => ipcRenderer.on("openFull", () => cb()), // menu-bar icon clicked
+  onShown: (cb) => ipcRenderer.on("shown", () => cb()), // window re-shown; reset hover handshake
 
   // pull the full payload on demand
   refresh: () => ipcRenderer.invoke("relay:get"),
@@ -34,4 +36,9 @@ contextBridge.exposeInMainWorld("relay", {
   interactive: (v) => ipcRenderer.send("relay:interactive", v),
   setPos: (x, y) => ipcRenderer.send("relay:setPos", x, y),
   soundBytes: (name) => ipcRenderer.invoke("relay:soundBytes", name),
+
+  // dismissal (the card's ✕ / the menu-bar mark / ghost notifications)
+  dismiss: () => ipcRenderer.send("relay:dismiss"),
+  undismiss: () => ipcRenderer.send("relay:undismiss"),
+  notifDone: () => ipcRenderer.send("relay:notifDone"),
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-companion",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Relay companion: connects local coding agents to Relay tasks, approvals, and connector tools.",
   "type": "module",
   "bin": {

package/src/mcp.js

@@ -543,7 +543,21 @@ export async function runMcpServer() {
     try {
       return await handleCall(client, req.params.name, req.params.arguments || {});
     } catch (err) {
-      return { content: [{ type: "text", text: `Relay error: ${err.message}` }], isError: true };
+      // Surface the API's validation detail so the calling agent can self-correct
+      // instead of guessing what "invalid_request" meant.
+      let detail = "";
+      const issues = err && err.body && Array.isArray(err.body.issues) ? err.body.issues : null;
+      if (issues && issues.length) {
+        detail =
+          "\n" +
+          issues
+            .slice(0, 8)
+            .map((i) => `- ${Array.isArray(i.path) && i.path.length ? i.path.join(".") : "(request)"}: ${i.message}`)
+            .join("\n");
+      } else if (err && err.body && typeof err.body.instruction === "string") {
+        detail = `\n${err.body.instruction}`;
+      }
+      return { content: [{ type: "text", text: `Relay error: ${err.message}${detail}` }], isError: true };
     }
   });
 

package/src/notifications.js

@@ -287,6 +287,11 @@ function senderForNotification(notification) {
   // anyway via RELAY_HIDDEN_KINDS, but the staged senderName must still be coherent.)
   if (notification.kind === "task_request") return "Your agent";
   if (notification.kind === "share_approval") return "Your agent";
+  // Task lifecycle notices (completed/cancelled/failed) are the agent run reporting
+  // back, not a person — label them as the automation, never "Someone".
+  if (notification.kind === "task_completed") return "Your agent";
+  if (notification.kind === "task_cancelled") return "Your agent";
+  if (notification.kind === "task_failed") return "Your agent";
   if (notification.kind === "connector_reauth") return "Relay connectors";
   return "Someone";
 }