omni-notify-mcp 1.1.7 → 1.1.8

package/README.md

@@ -106,6 +106,15 @@ Run multiple agents against the same notify server (e.g. one Claude session in `
 - `priority='high'` always punches through.
 - Agents can pre-flight with `get_dnd_status` to skip the round-trip when DND is on.
 
+### Heartbeat-drain (stay responsive during long work)
+Every agent that calls `get_idle_seconds` or `get_dnd_status` while busy gets any pending user inbox messages piggy-backed on the response. The server-side MCP `instructions` tell agents to call `get_idle_seconds` every 15-30 seconds during long operations so a user ping from Telegram lands within 30 seconds even if the agent hasn't called `notify` in hours. When an inbox message lands, the agent is required to fire a terse `busy-ack` back via `notify` so the user knows they were heard — even if the full response comes later.
+
+### Multi-session broadcast
+When multiple agents connect to the same server (e.g. one Claude per repo), every untagged user message is broadcast to all of them. Each agent replies with its session id, the user picks who they want to address, then targets follow-ups with `@<tag>`. The Telegram ack names the sessions the message was routed to.
+
+### Reconnect resilience
+The server returns HTTP 404 on requests with a stale `mcp-session-id` (per the MCP Streamable HTTP spec), so a client that wakes up after a server restart automatically re-initializes on its next tool call instead of staying stuck with a dead session. Idle sessions are reaped after 10 minutes of inactivity so the session list and clients pill bar stay honest.
+
 ### Idle gating (anti-buzz)
 The server publishes a policy `{ enabled, thresholdSeconds }`. Agents are **instructed** (via the MCP `instructions` field, surfaced to every connecting client) to call `get_idle_seconds` first, and **skip** sending a notification if you're actively at the keyboard. They can already see what they'd send. Only fire when you've stepped away. `priority='high'` always fires.
 

package/dist/ui/server.js

@@ -551,6 +551,17 @@ function log(direction, channel, text, client) {
         catch { }
     }
 }
+app.get("/api/sessions", (_req, res) => {
+    const list = listActiveSessions().map(s => ({
+        clientId: s.clientId,
+        tag: s.tag,
+        clientName: s.clientName,
+        clientVersion: s.clientVersion,
+        host: s.host,
+        connectedAt: s.connectedAt,
+    }));
+    res.json({ sessions: list });
+});
 app.get("/api/logs", (req, res) => {
     res.setHeader("Content-Type", "text/event-stream");
     res.setHeader("Cache-Control", "no-cache");
@@ -578,8 +589,11 @@ async function sendNotification(message, priority, client) {
     // they may have multiple agents running and this is a cheap local signal
     // that doesn't blast their phone. Disable via idle.alwaysDesktopWhenActive=false.
     // priority=high always bypasses idle entirely.
+    // Conversation bypass: if the user just messaged us from Telegram (within
+    // the TTL), they clearly want a reply over that channel, so skip idle gating.
+    const inTelegramConvo = Date.now() - lastTelegramInboundAt < TELEGRAM_CONVO_TTL_MS;
     let desktopOnlyMode = false;
-    if (priority !== "high" && cfg.idle?.enabled !== false) {
+    if (priority !== "high" && !inTelegramConvo && cfg.idle?.enabled !== false) {
         const idleSecs = getOsIdleSeconds();
         const threshold = cfg.idle?.thresholdSeconds ?? 120;
         const userIsActive = idleSecs >= 0 && idleSecs < threshold;
@@ -594,6 +608,9 @@ async function sendNotification(message, priority, client) {
             }
         }
     }
+    else if (priority !== "high" && inTelegramConvo) {
+        log("·", "idle", `bypassed (telegram convo active)`, client);
+    }
     const send = async (name, fn) => {
         try {
             await fn();
@@ -732,6 +749,13 @@ const pendingAsks = new Map();
 const inboxQueue = [];
 let tgPollOffset = -1;
 let lastUserMessageId;
+// When the user pings us from Telegram, bypass idle-gating on outbound
+// notifs for a while — clearly they want a Telegram reply back, so we
+// shouldn't gate remote channels just because they're at the keyboard
+// typing. TTL is short so normal idle-gating resumes once the conversation
+// goes quiet.
+let lastTelegramInboundAt = 0;
+const TELEGRAM_CONVO_TTL_MS = 5 * 60 * 1000;
 // Session tagging: a session may declare a tag (e.g. "alphawave") when it
 // connects to /mcp?tag=alphawave. Telegram messages starting with "@<tag>"
 // are routed only to sessions with that exact tag (tag prefix stripped).
@@ -844,6 +868,7 @@ async function startTelegramListener() {
                 if (msg?.chat?.id?.toString() === chatId && msg.text) {
                     log("←", "telegram", msg.text);
                     lastUserMessageId = msg.message_id;
+                    lastTelegramInboundAt = Date.now();
                     const { tag, text } = parseTag(msg.text);
                     // Match an outstanding ask first. If the message is tagged, only
                     // route to a pending ask from that same session — otherwise fall
@@ -863,13 +888,24 @@ async function startTelegramListener() {
                         inboxQueue.push(entry);
                         broadcastInbox(entry);
                         log("·", "inbox", text, tag);
-                        // Acknowledge receipt so user knows the message was queued.
-                        // Wording is deliberately about *delivery*, not processing: the
-                        // agent might be tailing the SSE stream (sees it immediately) or
-                        // might only check on its next poll/notify call.
-                        const ackText = tag
-                            ? `📬 Delivered to @${tag}.`
-                            : `📬 Delivered. The agent will process it on its next check-in.`;
+                        // Build an ack that names the active sessions the user's message
+                        // is being routed to. If the user tagged it and no session with
+                        // that tag is connected, tell them plainly so they don't sit
+                        // waiting for a reply that can't come.
+                        const targets = sessionsMatchingTag(tag);
+                        let ackText;
+                        if (tag && targets.length === 0) {
+                            ackText = `📭 No session @${tag} connected. Message queued — next @${tag} to connect will pick it up.`;
+                        }
+                        else if (targets.length === 0) {
+                            ackText = `📭 No agents connected. Message queued — next agent to connect will pick it up.`;
+                        }
+                        else {
+                            const names = targets.map(sessionDisplay).join(", ");
+                            ackText = tag
+                                ? `📬 Routed to ${names}. Waiting for them to reply.`
+                                : `📬 Broadcast to ${targets.length} session(s): ${names}. Each should reply with its identity — respond to the one you want.`;
+                        }
                         fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
                             method: "POST", headers: { "Content-Type": "application/json" },
                             body: JSON.stringify({
@@ -933,6 +969,18 @@ function drainInboxFor(tag) {
     }
     return taken;
 }
+// Appends an inbox block to any tool's text payload when messages are pending
+// for the given session. Lets cheap read tools (get_idle_seconds, get_dnd_status)
+// double as inbox drains, so a busy agent calling them as a keepalive still
+// sees user messages even when it hasn't called notify/poll in a while.
+function appendInbox(baseText, sessionTag, clientId) {
+    const messages = drainInboxFor(sessionTag);
+    if (messages.length === 0)
+        return baseText;
+    log("·", "poll", `${messages.length} message(s) drained via heartbeat`, clientId);
+    const inbox = messages.map(m => `[${m.ts}] ${m.text}`).join("\n");
+    return `${baseText}\n\n⚠️ USER SENT YOU A MESSAGE — STOP AND RESPOND BEFORE CONTINUING:\n${inbox}`;
+}
 const MCP_INSTRUCTIONS = `
 This server delivers notifications to the user through whatever channels the
 user has configured on the server side. The client never needs to know which
@@ -963,13 +1011,40 @@ BEHAVIORAL RULES for every client that connects:
    user has already configured. Say 'notif' or 'notification' instead.
 
 5. When the user sends you an unsolicited message (visible as INBOX items in
-   the 'notify' response, via 'poll', or via the /api/inbox/stream SSE), reply
-   to them THROUGH 'notify' so the reply actually reaches them — not just in
-   your chat output.
+   the 'notify' response, via 'poll', via 'get_idle_seconds' piggy-back, or
+   via the /api/inbox/stream SSE), reply to them THROUGH 'notify' so the reply
+   actually reaches them — not just in your chat output. Multiple agents may
+   be connected simultaneously — the server broadcasts every untagged inbox
+   message to all of them, so the user can see who is listening. Your reply
+   MUST identify which session you are (start with your own tag or client id,
+   e.g. "[@alphawave]" or "[sess-abcd]") and give a brief status so the user
+   can pick whom to respond to. If the user tagged their message (@<tag>),
+   only the session with that tag should reply. If you are untagged and
+   another session with the same project/workdir is already tagged, let the
+   tagged one reply.
 
-6. The 'get_idle_*' and 'get_dnd_status' tools are informational. You can
-   inspect them if you want to explain a delivery decision, but they are NOT
-   required pre-flights — the server gates server-side.
+5a. BUSY-ACK RULE (hard requirement): The moment you notice a user inbox
+    message — whether via notify response, heartbeat piggy-back, or poll —
+    REPLY IMMEDIATELY via 'notify' with a terse status, EVEN IF YOU CAN'T
+    ACT ON THE REQUEST YET. Do not finish the current tool/task first.
+    Drop what you're doing long enough to fire one 'notify' call, THEN
+    resume. Format: "[<your-session-id>] busy on <current-task>; will
+    respond at <milestone>". The user needs to know (a) you heard them,
+    (b) you're not the stuck one, (c) when to expect a real answer. An
+    inbox message that gets a delayed reply is worse than no reply — it
+    wastes the user's time waiting on silence.
+
+6. The 'get_idle_seconds', 'get_idle_config', and 'get_dnd_status' tools are
+   informational reads, but they ALSO drain pending inbox messages. Use them
+   as a cheap heartbeat during long work: call 'get_idle_seconds' EVERY 15-
+   30 SECONDS while a long task runs (loop iteration, backtest, scan, build,
+   etc.). If the user sent you a message while you were busy, it comes back
+   piggy-backed on the response — you don't need to separately call 'poll'.
+   This is a lightweight local read (no network, no DND or channel routing),
+   so the cost is near zero. Without this heartbeat pattern, a busy agent is
+   deaf to the user until its next 'notify' call — which may be minutes or
+   hours away during long work. Treat 'get_idle_seconds' as the "check for
+   user input" primitive, not an idle-gate check.
 
 7. If your tool call fails with "MCP server not connected" / "transport
    closed" / similar — the SERVER IS ALMOST CERTAINLY FINE. Other clients are
@@ -1120,23 +1195,25 @@ function createMcpServer(clientId, sessionTag) {
         };
     });
     server.tool("get_idle_seconds", "Returns the number of seconds since the user's last keyboard/mouse input. " +
-        "Call this before 'notify' or 'ask' to decide whether to skip (user is active) " +
-        "or fire (user stepped away). Returns -1 if idle detection is unsupported on " +
-        "this platform — in that case, proceed without gating (fail-open).", {}, async () => {
+        "Call this periodically during long work as a cheap heartbeat — the server " +
+        "will piggy-back any pending inbox messages in the response, so you stay " +
+        "responsive to the user without having to call poll. Returns -1 if idle " +
+        "detection is unsupported on this platform — in that case, proceed without " +
+        "gating (fail-open).", {}, async () => {
         const secs = getOsIdleSeconds();
-        return { content: [{ type: "text", text: String(secs) }] };
+        return { content: [{ type: "text", text: appendInbox(String(secs), sessionTag, clientId) }] };
     });
     server.tool("get_idle_config", "Returns the server's idle gating policy: { enabled, thresholdSeconds, alwaysDesktopWhenActive }. " +
         "Informational only — the server gates internally on every notify call. " +
-        "You don't need to pre-flight idle checks; just call 'notify'.", {}, async () => {
+        "Also drains pending inbox messages — safe to use as a heartbeat.", {}, async () => {
         const cfg = loadConfig();
         const idle = cfg.idle ?? { enabled: true, thresholdSeconds: 120, alwaysDesktopWhenActive: true };
-        return { content: [{ type: "text", text: JSON.stringify(idle) }] };
+        return { content: [{ type: "text", text: appendInbox(JSON.stringify(idle), sessionTag, clientId) }] };
     });
     server.tool("get_dnd_status", "Returns the current DND state: " +
         "{ active: boolean, reason: 'manual' | 'schedule' | 'off' }. " +
         "When active, the server will suppress delivery for priority < high. " +
-        "Clients can use this to short-circuit before calling 'notify'.", {}, async () => {
+        "Also drains pending inbox messages — safe to use as a heartbeat.", {}, async () => {
         const cfg = loadConfig();
         const active = isDndActive(cfg);
         let reason = "off";
@@ -1144,31 +1221,106 @@ function createMcpServer(clientId, sessionTag) {
             reason = cfg.dnd?.enabled ? "manual" : "schedule";
         }
         return {
-            content: [{ type: "text", text: JSON.stringify({ active, reason }) }],
+            content: [{ type: "text", text: appendInbox(JSON.stringify({ active, reason }), sessionTag, clientId) }],
         };
     });
     return server;
 }
 const httpTransports = {};
+const sessions = {};
+// Reap sessions that haven't made any request in a while. Keeps the sessions
+// list and pills bar accurate even when clients vanish without closing their
+// transport (VS Code window closed, laptop lid shut, network died). On next
+// reconnect the client gets a 404 and reinitializes cleanly.
+const SESSION_IDLE_TIMEOUT_MS = 10 * 60 * 1000; // 10 min
+setInterval(() => {
+    const now = Date.now();
+    for (const [sessionId, meta] of Object.entries(sessions)) {
+        if (now - meta.lastSeen > SESSION_IDLE_TIMEOUT_MS) {
+            log("·", "session", `reaped idle session ${meta.clientId} (last seen ${Math.round((now - meta.lastSeen) / 1000)}s ago)`);
+            try {
+                httpTransports[sessionId]?.close();
+            }
+            catch { /* ignore */ }
+            delete httpTransports[sessionId];
+            delete sessions[sessionId];
+        }
+    }
+}, 60_000);
+function listActiveSessions() {
+    return Object.values(sessions);
+}
+function sessionsMatchingTag(tag) {
+    if (!tag)
+        return listActiveSessions();
+    return listActiveSessions().filter(s => s.tag === tag);
+}
+function sessionDisplay(s) {
+    return s.tag ? `@${s.tag}` : s.clientId;
+}
 app.all("/mcp", async (req, res) => {
     const existingSessionId = req.headers["mcp-session-id"];
     if (existingSessionId && httpTransports[existingSessionId]) {
         await httpTransports[existingSessionId].handleRequest(req, res, req.body);
+        // Lazy-populate clientInfo after initialize lands on an existing session.
+        const meta = sessions[existingSessionId];
+        if (meta)
+            meta.lastSeen = Date.now();
+        const mcpServer = httpTransports[existingSessionId].__mcpServer;
+        if (meta && !meta.clientName && mcpServer?.getClientVersion) {
+            try {
+                const info = mcpServer.getClientVersion();
+                if (info) {
+                    meta.clientName = info.name;
+                    meta.clientVersion = info.version;
+                }
+            }
+            catch { /* ignore */ }
+        }
+        return;
+    }
+    // Spec-compliant: if the client presents a session ID we don't know about
+    // (server was restarted, or the transport was closed), return 404 so the
+    // client knows to re-initialize. The previous silent-new-session behavior
+    // left idle clients stuck with stale session bookkeeping until the VS Code
+    // window was manually reloaded.
+    if (existingSessionId) {
+        res.status(404).json({
+            jsonrpc: "2.0",
+            error: { code: -32000, message: "Session not found — reinitialize" },
+            id: null,
+        });
         return;
     }
     const rawTag = typeof req.query.tag === "string" ? req.query.tag : undefined;
     const sessionTag = rawTag?.toLowerCase().replace(/[^a-z0-9_-]/g, "") || undefined;
     const newSessionId = randomUUID();
-    const clientId = sessionTag ?? `sess-${newSessionId.slice(0, 8)}`;
+    const host = (req.socket.remoteAddress || "").replace(/^::ffff:/, "") || undefined;
+    const port = req.socket.remotePort;
+    // Build a distinguishable client id: tag wins if set; otherwise use host+port
+    // so two untagged sessions from the same machine are still distinguishable.
+    const clientId = sessionTag
+        ?? (host && port ? `${host === "127.0.0.1" || host === "::1" ? "local" : host}:${port}` : `sess-${newSessionId.slice(0, 8)}`);
     const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => newSessionId });
     transport.onclose = () => {
-        if (transport.sessionId)
+        if (transport.sessionId) {
             delete httpTransports[transport.sessionId];
+            delete sessions[transport.sessionId];
+        }
     };
-    await createMcpServer(clientId, sessionTag).connect(transport);
+    const mcpServer = createMcpServer(clientId, sessionTag);
+    await mcpServer.connect(transport);
+    // Stash the underlying MCP server on the transport so subsequent requests
+    // can grab clientInfo once the initialize handshake completes.
+    transport.__mcpServer = mcpServer.server ?? mcpServer;
     await transport.handleRequest(req, res, req.body);
-    if (transport.sessionId)
+    if (transport.sessionId) {
         httpTransports[transport.sessionId] = transport;
+        const now = Date.now();
+        sessions[transport.sessionId] = {
+            clientId, tag: sessionTag, host, connectedAt: now, lastSeen: now,
+        };
+    }
 });
 // ── Start ─────────────────────────────────────────────────────────────────────
 app.listen(PORT, "0.0.0.0", () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omni-notify-mcp",
-  "version": "1.1.7",
+  "version": "1.1.8",
   "description": "An MCP server that lets AI agents (Claude, Cursor, etc.) reach you on any channel — desktop, Telegram, SMS, email — with two-way ask/reply, real-time inbox push, Do Not Disturb, idle gating, multi-session routing, and a one-page web UI for setup. Zero config code; configure once, agents call notify/ask.",
   "main": "dist/index.js",
   "type": "module",

package/ui/public/app.js

@@ -206,6 +206,20 @@ async function saveEmail() {
   clearDirty("email");
 }
 
+// Standalone enable-toggle handlers: persist immediately without requiring a
+// Save-button click. Credentials still need the explicit Save flow, but the
+// on/off switch auto-persists so users aren't left wondering why their
+// toggle "snapped back" after a reload.
+async function toggleTelegramEnabled() {
+  await patch({ telegram: { enabled: $("telegram-enabled").checked } });
+}
+async function toggleEmailEnabled() {
+  await patch({ email: { enabled: $("email-enabled").checked } });
+}
+async function toggleSmsEnabled() {
+  await patch({ sms: { enabled: $("sms-enabled").checked } });
+}
+
 async function saveTelegram() {
   await patch({
     telegram: {
@@ -552,11 +566,28 @@ function parseLogEntry(raw) {
   return { ts: m[1], client: m[2] || null, dir: m[3], channel: m[4], msg: m[5] };
 }
 
+let logFilterClient = "";
+
+function selectLogFilter(clientId) {
+  logFilterClient = clientId;
+  document.querySelectorAll("#session-pills .pill").forEach(p => {
+    p.classList.toggle("pill-active", (p.dataset.client || "") === clientId);
+  });
+  // Re-apply hidden class to all entries based on the new filter.
+  document.querySelectorAll("#log-panel .log-entry").forEach(el => {
+    const c = el.dataset.client || "";
+    el.style.display = (!clientId || c === clientId || (!c && clientId === "")) ? "" : "none";
+  });
+  const panel = $("log-panel");
+  panel.scrollTop = panel.scrollHeight;
+}
+
 function renderLogEntry(raw) {
   const panel = $("log-panel");
   const p = parseLogEntry(raw);
   const el = document.createElement("div");
   el.className = "log-entry";
+  el.dataset.client = (p && p.client) ? p.client : "";
 
   if (p) {
     const ts = new Date(p.ts).toLocaleTimeString([], { hour12: false });
@@ -574,11 +605,56 @@ function renderLogEntry(raw) {
     el.innerHTML = `<span class="log-msg">${raw.replace(/</g,"&lt;")}</span>`;
   }
 
+  if (logFilterClient && el.dataset.client !== logFilterClient) {
+    el.style.display = "none";
+  }
   const atBottom = panel.scrollHeight - panel.scrollTop <= panel.clientHeight + 20;
   panel.appendChild(el);
   if (atBottom) panel.scrollTop = panel.scrollHeight;
 }
 
+async function refreshSessions() {
+  try {
+    const res = await fetch("/api/sessions");
+    if (!res.ok) return;
+    const { sessions } = await res.json();
+    const bar = $("session-pills");
+    // Build a set of desired pills (keyed by clientId). Keep the "All" pill.
+    const existing = new Map();
+    bar.querySelectorAll(".pill").forEach(p => existing.set(p.dataset.client || "", p));
+    const desired = new Set([""]);
+    for (const s of sessions) desired.add(s.clientId);
+    // Remove pills for disconnected sessions.
+    for (const [id, el] of existing) {
+      if (!desired.has(id)) el.remove();
+    }
+    // Add pills for new sessions.
+    for (const s of sessions) {
+      if (!existing.has(s.clientId)) {
+        const btn = document.createElement("button");
+        btn.className = "pill";
+        btn.dataset.client = s.clientId;
+        btn.textContent = s.tag ? `@${s.tag}` : s.clientId;
+        btn.title = [s.clientName, s.host].filter(Boolean).join(" · ");
+        btn.onclick = () => selectLogFilter(s.clientId);
+        bar.appendChild(btn);
+      }
+    }
+    // If the currently-selected client disconnected, fall back to "All".
+    if (logFilterClient && !desired.has(logFilterClient)) {
+      selectLogFilter("");
+    } else {
+      // Re-sync active state (in case pills were re-added).
+      bar.querySelectorAll(".pill").forEach(p => {
+        p.classList.toggle("pill-active", (p.dataset.client || "") === logFilterClient);
+      });
+    }
+  } catch { /* ignore */ }
+}
+
+setInterval(refreshSessions, 3000);
+refreshSessions();
+
 function clearLog() {
   $("log-panel").innerHTML = "";
 }

package/ui/public/index.html

@@ -87,7 +87,7 @@
           <div id="gmail-connected-state" class="hidden">
             <div class="actions">
               <label class="toggle-wrap">
-                <input type="checkbox" id="email-enabled" oninput="markDirty('email')">
+                <input type="checkbox" id="email-enabled" onchange="toggleEmailEnabled()">
                 <span class="toggle"></span>
               </label>
               <span class="toggle-lbl">Enable</span>
@@ -134,7 +134,7 @@
         <div class="card-body">
           <div class="actions">
             <label class="toggle-wrap">
-              <input type="checkbox" id="telegram-enabled" oninput="markDirty('telegram')">
+              <input type="checkbox" id="telegram-enabled" onchange="toggleTelegramEnabled()">
               <span class="toggle"></span>
             </label>
             <span class="toggle-lbl">Enable</span>
@@ -175,7 +175,7 @@
         <div class="card-body">
           <div class="actions">
             <label class="toggle-wrap">
-              <input type="checkbox" id="sms-enabled" oninput="markDirty('sms')">
+              <input type="checkbox" id="sms-enabled" onchange="toggleSmsEnabled()">
               <span class="toggle"></span>
             </label>
             <span class="toggle-lbl">Enable</span>
@@ -303,6 +303,9 @@
           <span class="dot dot-ok" id="log-dot" style="display:inline-block"></span>
           Activity Log
         </span>
+        <div class="session-pills" id="session-pills">
+          <button class="pill pill-active" data-client="" onclick="selectLogFilter('')">All</button>
+        </div>
         <button class="btn btn-sm btn-ghost" onclick="clearLog()">Clear</button>
       </div>
       <div class="log-panel" id="log-panel"></div>

package/ui/public/style.css

@@ -204,6 +204,34 @@ main {
   letter-spacing: .5px;
 }
 
+.session-pills {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex: 1;
+  justify-content: center;
+  flex-wrap: wrap;
+  overflow: hidden;
+}
+.pill {
+  font: inherit;
+  font-size: 11px;
+  padding: 3px 10px;
+  border-radius: 12px;
+  border: 1px solid var(--border);
+  background: transparent;
+  color: var(--text-2);
+  cursor: pointer;
+  transition: background .15s, color .15s, border-color .15s;
+  white-space: nowrap;
+}
+.pill:hover { border-color: var(--accent); color: var(--text); }
+.pill-active {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: #fff;
+}
+
 /* ── Cards ───────────────────────────────────────────────────────────────── */
 
 .card {