omni-notify-mcp 1.1.8 → 1.2.0

package/README.md

@@ -57,23 +57,25 @@ Add to your MCP config (`~/.claude.json`, `.vscode/mcp.json`, `claude_desktop_co
 Then run the config UI to wire up your channels:
 
 ```bash
-npx omni-notify-mcp ui
+npx omni-notify-ui
 ```
 
 Open <http://localhost:3737>, toggle the channels you want, and hit Save. The MCP server picks up changes immediately — no restart.
 
 ## What the agent gets
 
-Six tools, all server-configured (the agent never names a channel):
+Eight tools, all server-configured (the agent never names a channel):
 
 | Tool | What it does |
 |---|---|
 | **`notify`** | Send a message to the user. Priority controls fan-out (see below). |
 | **`ask`** | Send a question and **wait** for the user's reply (Telegram, or web link via email). |
 | **`poll`** | Drain any unsolicited messages the user sent. |
-| **`get_idle_seconds`** | Seconds since last keyboard/mouse input. -1 if unsupported. |
-| **`get_idle_config`** | The server's idle-gating policy `{ enabled, thresholdSeconds }`. |
-| **`get_dnd_status`** | Current DND state `{ active, reason }`. |
+| **`wait_for_inbox`** | **Long-poll**: block up to 55s and return the moment the user types something. The most reliable push path across every MCP client — messages come back as tool *results*, not notifications (which many clients drop). |
+| **`get_idle_seconds`** | Seconds since last keyboard/mouse input. Drains inbox as a side-effect. |
+| **`get_idle_config`** | The server's idle-gating policy `{ enabled, thresholdSeconds }`. Drains inbox. |
+| **`get_dnd_status`** | Current DND state `{ active, reason }`. Drains inbox. |
+| **`reply`** *(stdio only)* | Channels return-path — Claude Code calls this when the agent responds to a pushed channel message. Routes straight through `notify`. |
 
 Priority routing for `notify`:
 
@@ -112,8 +114,58 @@ Every agent that calls `get_idle_seconds` or `get_dnd_status` while busy gets an
 ### 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.
 
+### Dual transport — HTTP and stdio (with Claude Code Channels)
+`notify-mcp` ships two entrypoints against the same server state:
+
+- **`omni-notify-mcp`** (stdio) — the default `npx omni-notify-mcp` command. Speaks stdio JSON-RPC, auto-spawns the HTTP server as a detached child if it isn't already running, and subscribes to the inbox SSE stream so it can push unsolicited messages to the attached agent. **Declares the `claude/channel` capability**, so Claude Code v2.1.80+ surfaces each user message as a synthetic turn via `notifications/claude/channel` — the only push path that crosses the client boundary reliably ([modelcontextprotocol#1192](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/1192), [claude-code/channels](https://code.claude.com/docs/en/channels)). When the host doesn't support Channels, the bridge still works — agents just use `wait_for_inbox` as the long-poll fallback.
+- **`omni-notify-ui`** (HTTP, default `:3737`) — runs the config web UI, the Telegram listener, all channel implementations, and the Streamable-HTTP `/mcp` endpoint for remote / multi-session agents.
+
+For Claude Code with Channels:
+```bash
+claude --channels omni-notify-mcp
+# or, during preview, if your plugin isn't allowlisted:
+claude --dangerously-load-development-channels omni-notify-mcp
+```
+
+For every other MCP client, the stdio command works as a plain MCP server:
+```json
+{
+  "mcpServers": {
+    "notify": { "command": "npx", "args": ["omni-notify-mcp"] }
+  }
+}
+```
+
+### Reliable push — `wait_for_inbox` long-poll
+The hard truth: **most MCP clients silently drop generic server notifications** ([modelcontextprotocol#1192](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/1192), [claude-code#41733](https://github.com/anthropics/claude-code/issues/41733)). The only delivery paths that survive are (a) Claude Code's new Channels (`notifications/claude/channel`, handled by the stdio bridge above) and (b) tool *results*. `wait_for_inbox` is the universal fallback: the agent calls it, the server parks the request until the user types something, then resolves it with the message — which the client is forced to surface because it's a tool-call response. Default timeout is 50s to stay under the 60s JS SDK request ceiling ([typescript-sdk#245](https://github.com/modelcontextprotocol/typescript-sdk/issues/245)); the agent re-calls on empty in a tight loop. The MCP `instructions` block shipped with the server tells agents exactly this loop pattern, so no per-prompt nagging is needed.
+
 ### 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.
+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 aggressively (90-second timeout, since the heartbeat contract requires requests every 15–30s), dead SSE subscribers are pruned every 15s, and every broadcast ack runs a liveness probe before counting targets — so "Broadcast to N session(s)" always reflects who can actually receive. TCP keepalive is enabled on every incoming socket (15s probe) and the server writes an SSE `: keepalive` comment down every live MCP GET stream every 20s, which defeats proxy idle timeouts and surfaces half-open connections within a minute ([typescript-sdk#270](https://github.com/modelcontextprotocol/typescript-sdk/issues/270)). The stdio bridge transparently re-initializes a fresh HTTP session on 404 without the agent ever seeing a failure.
+
+### File-drop bridge for busy agents (the /btw mechanism)
+Claude Code has no public API for injecting a prompt into a running session while a tool call is executing ([anthropics/claude-code#27441](https://github.com/anthropics/claude-code/issues/27441)). The MCP heartbeat-drain already handles agents that are *voluntarily polling*, but if the agent is deep in a 5-minute `Bash` or `WebFetch` call, the piggy-back never fires. For that case, the server drops every unsolicited inbox message as a markdown file at `~/.notify-mcp/inbox/<timestamp>.md`, so a Claude Code `FileChanged` hook can surface it on the very next turn without the agent having to cooperate.
+
+Drop this into `~/.claude/settings.json` (or a project-local `.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "FileChanged": [
+      {
+        "matcher": "**/.notify-mcp/inbox/*.md",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cat \"$CLAUDE_FILE_PATH\" && rm \"$CLAUDE_FILE_PATH\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The hook's stdout is injected as additional context on the next turn, and the `rm` clears the drop so each message fires exactly once. Stale drops older than 24h are reaped by the server automatically.
 
 ### 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/index.js

@@ -1,146 +1,313 @@
 #!/usr/bin/env node
+/**
+ * Stdio bridge for notify-mcp.
+ *
+ * This is the Claude Code / Cursor / Codex stdio entrypoint. It is a *thin*
+ * foreground process — all state (config, inbox, pending asks, Telegram
+ * listener) lives in the long-running HTTP server (`ui/server.js`, default
+ * port 3737). The bridge:
+ *
+ *   1. Ensures the HTTP server is running (auto-spawns it detached if not).
+ *   2. Subscribes to /api/inbox/stream via SSE and re-emits each unsolicited
+ *      user message as a `notifications/claude/channel` notification to the
+ *      attached client. Claude Code (v2.1.80+) surfaces those as synthetic
+ *      user turns, which is the only push path that reliably crosses the
+ *      client boundary — regular MCP notifications are dropped by most
+ *      clients (modelcontextprotocol/modelcontextprotocol#1192).
+ *   3. Exposes the full tool surface (`notify`, `ask`, `poll`, `wait_for_inbox`,
+ *      `get_idle_seconds`, `get_idle_config`, `get_dnd_status`, `reply`) and
+ *      proxies every call to the HTTP /mcp endpoint so multi-session routing,
+ *      DND, idle gating, etc. all work identically to the HTTP transport.
+ *
+ * The net effect: users can `claude --channels notify-mcp@<registry>` (or
+ * run `npx omni-notify-mcp` as a plain stdio MCP server) and get push-to-agent
+ * delivery without ever touching a .mcp.json or a port number.
+ */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { randomUUID } from "crypto";
+import { spawn } from "child_process";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
 import { z } from "zod";
-import { loadConfig } from "./config.js";
-import { sendDesktop } from "./channels/desktop.js";
-import { sendTelegram } from "./channels/telegram.js";
-import { sendWhatsApp } from "./channels/whatsapp.js";
-import { sendSms } from "./channels/sms.js";
-import { sendEmail } from "./channels/email.js";
-const config = loadConfig();
-// ── Telegram listener ─────────────────────────────────────────────────────────
-const pendingAsks = new Map();
-const inboxQueue = [];
-let tgPollOffset = -1;
-async function initTgOffset(token) {
-    const r = await fetch(`https://api.telegram.org/bot${token}/getUpdates?offset=-1&timeout=0`);
-    const json = await r.json();
-    const results = json.result ?? [];
-    return results.length > 0 ? results[results.length - 1].update_id + 1 : 0;
+const PORT = process.env.NOTIFY_MCP_PORT ? parseInt(process.env.NOTIFY_MCP_PORT) : 3737;
+const BASE = `http://localhost:${PORT}`;
+const SESSION_TAG = (process.env.NOTIFY_MCP_TAG ?? "").toLowerCase().replace(/[^a-z0-9_-]/g, "") || undefined;
+const CLIENT_NAME = "claude-channel-bridge";
+// ── 1. Ensure the HTTP server is up ───────────────────────────────────────────
+async function serverIsUp() {
+    try {
+        const r = await fetch(`${BASE}/mcp`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", "Accept": "application/json, text/event-stream" },
+            body: JSON.stringify({ jsonrpc: "2.0", id: 0, method: "initialize", params: {} }),
+            signal: AbortSignal.timeout(1500),
+        });
+        // Any HTTP response (including 400/406 from malformed init) means the
+        // server is alive and speaking HTTP. Real "down" surfaces as a throw.
+        return r.status > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function spawnUiServerIfNeeded() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // dist/ layout: src/index.ts → dist/index.js; ui → dist/ui/server.js
+    const candidates = [
+        join(here, "ui", "server.js"),
+        join(here, "..", "ui", "server.js"),
+        join(here, "..", "dist", "ui", "server.js"),
+    ];
+    const uiPath = candidates.find(p => existsSync(p));
+    if (!uiPath) {
+        stderr(`[bridge] could not locate ui/server.js near ${here} — skipping auto-spawn`);
+        return;
+    }
+    stderr(`[bridge] auto-spawning UI server: ${uiPath}`);
+    const child = spawn(process.execPath, [uiPath], {
+        detached: true,
+        stdio: "ignore",
+        env: { ...process.env, PORT: String(PORT) },
+    });
+    child.unref();
+}
+async function waitForServer(maxMs = 15_000) {
+    const deadline = Date.now() + maxMs;
+    while (Date.now() < deadline) {
+        if (await serverIsUp())
+            return true;
+        await new Promise(r => setTimeout(r, 500));
+    }
+    return false;
 }
-async function startTelegramListener() {
+function stderr(line) {
+    // stdio transport uses stdout for JSON-RPC — all logging MUST go to stderr.
+    try {
+        process.stderr.write(`${line}\n`);
+    }
+    catch { /* ignore */ }
+}
+// ── 2. HTTP /mcp session — the bridge itself is an MCP client of the server ──
+// We run a single persistent MCP-over-HTTP session per bridge process and
+// forward every local stdio tool call through it. Using one shared session
+// (not per-tool-call) keeps the tag-based routing, waiter parking, and inbox
+// draining all consistent with what the HTTP server sees.
+let httpSessionId;
+let httpRpcId = 1;
+async function httpRpc(method, params, isNotification = false) {
+    // JSON-RPC notifications (method name starts with `notifications/` or the
+    // caller says so) carry no `id` and get no response. Spec-compliant servers
+    // return 202 Accepted with empty body.
+    const notif = isNotification || method.startsWith("notifications/");
+    const body = { jsonrpc: "2.0", method, params: params ?? {} };
+    if (!notif)
+        body.id = httpRpcId++;
+    const headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json, text/event-stream",
+    };
+    if (httpSessionId)
+        headers["mcp-session-id"] = httpSessionId;
+    const tagQuery = SESSION_TAG ? `?tag=${encodeURIComponent(SESSION_TAG)}` : "";
+    const r = await fetch(`${BASE}/mcp${tagQuery}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        // Long-poll tools may block up to ~55s server-side. Give the fetch
+        // generous headroom but not infinite, so a wedged server surfaces fast.
+        signal: AbortSignal.timeout(120_000),
+    });
+    // The server returns 404 when our cached session is stale (spec-compliant
+    // behavior after a server restart). Clear and retry once with a fresh init.
+    if (r.status === 404 && httpSessionId) {
+        httpSessionId = undefined;
+        await httpInitialize();
+        return httpRpc(method, params, isNotification);
+    }
+    if (r.status >= 500) {
+        throw new Error(`HTTP ${r.status} from /mcp: ${await r.text().catch(() => "")}`);
+    }
+    const sid = r.headers.get("mcp-session-id");
+    if (sid && !httpSessionId)
+        httpSessionId = sid;
+    if (notif)
+        return undefined;
+    const ctype = r.headers.get("content-type") ?? "";
+    const raw = await r.text();
+    if (ctype.includes("application/json")) {
+        return JSON.parse(raw);
+    }
+    // SSE framing: pull the first data: line as the JSON-RPC response.
+    for (const line of raw.split(/\r?\n/)) {
+        if (line.startsWith("data:")) {
+            const json = line.slice(5).trim();
+            if (json)
+                return JSON.parse(json);
+        }
+    }
+    throw new Error(`unexpected response from /mcp: ${raw.slice(0, 200)}`);
+}
+async function httpInitialize() {
+    const res = await httpRpc("initialize", {
+        protocolVersion: "2024-11-05",
+        capabilities: {},
+        clientInfo: { name: CLIENT_NAME, version: "1.0" },
+    });
+    if (res?.error)
+        throw new Error(`initialize failed: ${JSON.stringify(res.error)}`);
+    // Follow-up: the spec requires a notifications/initialized after initialize.
+    await httpRpc("notifications/initialized").catch(() => { });
+}
+// ── 3. Stdio MCP server — the thing Claude Code / Cursor attaches to ─────────
+const server = new McpServer({ name: "notify-mcp", version: "1.2.0" }, {
+    // Declare the claude/channel capability so Claude Code knows to surface
+    // our notifications/claude/channel events as synthetic user turns. The
+    // `reply` tool below is how Claude hands the agent's response back to us.
+    // Reference: https://code.claude.com/docs/en/channels-reference
+    capabilities: {
+        experimental: { "claude/channel": {} },
+    },
+    instructions: "This is the stdio bridge for notify-mcp. It pushes unsolicited user " +
+        "messages to the agent via `notifications/claude/channel` when the host " +
+        "supports Channels (Claude Code v2.1.80+). Otherwise call `wait_for_inbox` " +
+        "as a long-poll to reliably receive user messages as tool results.",
+});
+// Thin proxy: forward a tool call to the HTTP server and return its content
+// block array verbatim. Error shape matches what the SDK expects from tool
+// handlers.
+async function proxyToolCall(name, args) {
+    const res = await httpRpc("tools/call", { name, arguments: args });
+    if (res?.error) {
+        return { content: [{ type: "text", text: `Error: ${res.error.message ?? JSON.stringify(res.error)}` }], isError: true };
+    }
+    const result = res?.result;
+    if (result?.content && Array.isArray(result.content)) {
+        return { content: result.content, isError: !!result.isError };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(result ?? {}) }] };
+}
+server.tool("notify", "Send a notification to the user. Delivery channels and DND are server-configured.", {
+    message: z.string().max(500),
+    priority: z.enum(["low", "normal", "high"]).default("normal"),
+}, async (args) => proxyToolCall("notify", args));
+server.tool("ask", "Send a question to the user and wait for their reply.", {
+    question: z.string().max(500),
+    timeout_seconds: z.number().min(30).max(3600).default(300),
+}, async (args) => proxyToolCall("ask", args));
+server.tool("poll", "Drain pending unsolicited user messages.", {}, async () => proxyToolCall("poll", {}));
+server.tool("wait_for_inbox", "Block until an unsolicited user message arrives or timeout expires. Reliable " +
+    "delivery across every MCP client (messages come back as tool results).", {
+    timeout_seconds: z.number().min(5).max(55).default(50),
+}, async (args) => proxyToolCall("wait_for_inbox", args));
+server.tool("get_idle_seconds", "Seconds since user's last keyboard/mouse input. Drains inbox as a side-effect.", {}, async () => proxyToolCall("get_idle_seconds", {}));
+server.tool("get_idle_config", "Server's idle gating policy. Drains inbox as a side-effect.", {}, async () => proxyToolCall("get_idle_config", {}));
+server.tool("get_dnd_status", "Current DND state. Drains inbox as a side-effect.", {}, async () => proxyToolCall("get_dnd_status", {}));
+// `reply` is the Channels return-path: Claude Code invokes it when the agent
+// has produced a response to a channel-delivered user message. We just funnel
+// it straight through `notify` so it flows to whatever channel the user is
+// actually reading (Telegram, desktop, email, ...).
+server.tool("reply", "Reply to the user's most recent channel message. Routes through notify so " +
+    "the response reaches whichever channel the user is reading.", {
+    message: z.string().max(2000).describe("The reply text to deliver"),
+    priority: z.enum(["low", "normal", "high"]).default("normal"),
+}, async ({ message, priority }) => {
+    const tagPrefix = SESSION_TAG ? `[@${SESSION_TAG}] ` : "";
+    return proxyToolCall("notify", { message: `${tagPrefix}${message}`, priority });
+});
+async function subscribeInbox() {
+    const tagQuery = SESSION_TAG ? `?tag=${encodeURIComponent(SESSION_TAG)}` : "";
+    // Reconnect forever with backoff. We don't care about replay; the
+    // file-drop bridge and queue handle the "missed while offline" window.
+    let backoff = 1000;
     while (true) {
         try {
-            const cfg = loadConfig();
-            const { token, chatId } = cfg.telegram ?? {};
-            if (!token || !chatId || !cfg.telegram?.enabled) {
-                await new Promise(r => setTimeout(r, 5000));
-                continue;
-            }
-            if (tgPollOffset < 0) {
-                tgPollOffset = await initTgOffset(token);
-            }
-            const r = await fetch(`https://api.telegram.org/bot${token}/getUpdates?offset=${tgPollOffset}&timeout=10`);
-            const json = await r.json();
-            for (const update of json.result ?? []) {
-                tgPollOffset = update.update_id + 1;
-                const msg = update.message;
-                if (msg?.chat?.id?.toString() === chatId && msg.text) {
-                    const first = [...pendingAsks.entries()][0];
-                    if (first) {
-                        const [id, pending] = first;
-                        clearTimeout(pending.timer);
-                        pendingAsks.delete(id);
-                        pending.resolve(msg.text);
-                    }
-                    else {
-                        inboxQueue.push({ text: msg.text, ts: new Date().toISOString() });
+            const r = await fetch(`${BASE}/api/inbox/stream${tagQuery}`, {
+                headers: { "Accept": "text/event-stream" },
+            });
+            if (!r.ok || !r.body)
+                throw new Error(`stream HTTP ${r.status}`);
+            backoff = 1000; // reset on successful connect
+            const reader = r.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = "";
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                let idx;
+                while ((idx = buffer.indexOf("\n\n")) !== -1) {
+                    const frame = buffer.slice(0, idx);
+                    buffer = buffer.slice(idx + 2);
+                    // SSE frame: may include multiple "data:" lines. We emit on each.
+                    for (const line of frame.split(/\r?\n/)) {
+                        if (!line.startsWith("data:"))
+                            continue;
+                        const payload = line.slice(5).trim();
+                        if (!payload)
+                            continue;
+                        try {
+                            const entry = JSON.parse(payload);
+                            await emitChannelEvent(entry);
+                        }
+                        catch (err) {
+                            stderr(`[bridge] bad SSE payload: ${err instanceof Error ? err.message : String(err)}`);
+                        }
                     }
                 }
             }
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            if (!msg.includes("terminated") && !msg.includes("aborted")) {
-                await new Promise(r => setTimeout(r, 2000));
-            }
+            stderr(`[bridge] inbox stream closed: ${err instanceof Error ? err.message : String(err)}`);
         }
+        await new Promise(r => setTimeout(r, backoff));
+        backoff = Math.min(30_000, backoff * 2);
     }
 }
-startTelegramListener();
-// ── MCP server ────────────────────────────────────────────────────────────────
-const server = new McpServer({
-    name: "omni-notify-mcp",
-    version: "1.0.0",
-});
-server.tool("notify", "Send a notification through configured channels (desktop, Telegram, WhatsApp, SMS, email). " +
-    "Priority: low=email only; normal=desktop+telegram+email; high=all channels. " +
-    "Use for: task milestones, questions needing user input, catastrophic findings, long task completion.", {
-    message: z.string().max(500).describe("Notification message, max 500 chars"),
-    priority: z
-        .enum(["low", "normal", "high"])
-        .default("normal")
-        .describe("low=email only; normal=desktop+telegram+email; high=desktop+telegram+whatsapp+sms+email"),
-}, async ({ message, priority }) => {
-    const results = [];
-    const errors = [];
-    const send = async (name, fn) => {
-        try {
-            await fn();
-            results.push(name);
-        }
-        catch (err) {
-            errors.push(`${name}: ${err instanceof Error ? err.message : String(err)}`);
+async function emitChannelEvent(entry) {
+    // Emit the new Claude Code Channels notification *and* the generic
+    // `notifications/message` as a belt-and-suspenders approach: hosts that
+    // ignore `notifications/claude/channel` may still surface the message as
+    // a log line. Both are fire-and-forget; a failure just means the peer
+    // closed the stdio transport (we'll notice on the next tool call).
+    const content = entry.tag ? `[@${entry.tag}] ${entry.text}` : entry.text;
+    try {
+        await server.server.notification({
+            method: "notifications/claude/channel",
+            params: {
+                content,
+                meta: { ts: entry.ts, tag: entry.tag ?? null, source: "notify-mcp" },
+            },
+        });
+    }
+    catch {
+        // client doesn't support the experimental capability — that's fine,
+        // wait_for_inbox is the universal fallback.
+    }
+}
+// ── 5. Wire it up ────────────────────────────────────────────────────────────
+async function main() {
+    if (!(await serverIsUp())) {
+        spawnUiServerIfNeeded();
+        if (!(await waitForServer())) {
+            stderr(`[bridge] HTTP server at ${BASE} did not come up within 15s — giving up on push; tool calls will fail.`);
         }
-    };
-    if (priority === "normal" || priority === "high") {
-        await send("desktop", () => sendDesktop(config.desktop, message));
-        await send("telegram", () => sendTelegram(config.telegram, message));
-    }
-    if (priority === "high") {
-        await send("whatsapp", () => sendWhatsApp(config.whatsapp, message));
-        await send("sms", () => sendSms(config.sms, message));
-    }
-    await send("email", () => sendEmail(config.email, message));
-    const summary = [
-        results.length > 0 ? `Sent via: ${results.join(", ")}` : null,
-        errors.length > 0 ? `Errors: ${errors.join("; ")}` : null,
-    ].filter(Boolean).join(" | ");
-    return { content: [{ type: "text", text: summary || "No channels delivered" }] };
-});
-server.tool("ask", "Send a question to the user via Telegram and wait for their reply. " +
-    "Use when a decision is needed before continuing — e.g. 'Should I delete these files?'", {
-    question: z.string().max(500).describe("The question to ask the user"),
-    timeout_seconds: z.number().min(30).max(3600).default(300)
-        .describe("How long to wait for a reply in seconds (default 5 min)"),
-}, async ({ question, timeout_seconds = 300 }) => {
-    const cfg = loadConfig();
-    if (!cfg.telegram?.enabled || !cfg.telegram.token || !cfg.telegram.chatId) {
-        return { content: [{ type: "text", text: "Error: Telegram not configured. Enable it in ~/.notify-mcp/config.json" }] };
-    }
-    await fetch(`https://api.telegram.org/bot${cfg.telegram.token}/sendMessage`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-            chat_id: cfg.telegram.chatId,
-            text: `❓ ${question}\n\nReply to this message with your answer.`,
-        }),
-    });
-    const token = randomUUID();
-    const reply = await new Promise((resolve, reject) => {
-        const timer = setTimeout(() => {
-            pendingAsks.delete(token);
-            reject(new Error(`No reply received within ${timeout_seconds}s`));
-        }, timeout_seconds * 1000);
-        pendingAsks.set(token, { resolve, timer });
-    });
-    return { content: [{ type: "text", text: reply }] };
-});
-server.tool("poll", "Check for unsolicited messages the user sent on Telegram (not in response to an ask). " +
-    "Returns queued messages and clears the queue. Returns 'inbox:empty' if nothing pending. " +
-    "Call this at the start of each work cycle.", {}, async () => {
-    if (inboxQueue.length === 0) {
-        return { content: [{ type: "text", text: "inbox:empty" }] };
-    }
-    const messages = inboxQueue.splice(0);
-    return {
-        content: [{
-                type: "text",
-                text: messages.map(m => `[${m.ts}] ${m.text}`).join("\n"),
-            }],
-    };
+    }
+    try {
+        await httpInitialize();
+    }
+    catch (err) {
+        stderr(`[bridge] initial HTTP initialize failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Fire-and-forget: the stdio transport should be usable immediately; the
+    // push channel attaches as soon as the SSE handshake completes.
+    subscribeInbox().catch(err => stderr(`[bridge] inbox subscriber crashed: ${err instanceof Error ? err.message : String(err)}`));
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    stderr(`[bridge] stdio MCP bridge ready (tag=${SESSION_TAG ?? "none"}, port=${PORT})`);
+}
+main().catch(err => {
+    stderr(`[bridge] fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
+    process.exit(1);
 });
-const transport = new StdioServerTransport();
-await server.connect(transport);

package/dist/ui/server.js

@@ -1,7 +1,8 @@
+#!/usr/bin/env node
 import { randomUUID } from "crypto";
 import express from "express";
 import { google } from "googleapis";
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from "fs";
 import { homedir, networkInterfaces } from "os";
 import { join } from "path";
 import { fileURLToPath } from "url";
@@ -747,6 +748,21 @@ function getLocalIp() {
 }
 const pendingAsks = new Map();
 const inboxQueue = [];
+const inboxWaiters = new Map();
+// Match waiters the same way `matchesSession` matches SSE subscribers:
+// - untagged entry → every waiter is a match (broadcast)
+// - tagged entry   → only waiters with the same tag match
+function takeWaitersFor(entryTag) {
+    const taken = [];
+    for (const [id, w] of inboxWaiters) {
+        const match = entryTag === undefined ? true : w.tag === entryTag;
+        if (match) {
+            inboxWaiters.delete(id);
+            taken.push(w);
+        }
+    }
+    return taken;
+}
 let tgPollOffset = -1;
 let lastUserMessageId;
 // When the user pings us from Telegram, bypass idle-gating on outbound
@@ -772,19 +788,110 @@ function matchesSession(entry, sessionTag) {
         return true; // untagged → everyone
     return entry.tag === sessionTag; // tagged   → only matching session
 }
+// ── /btw file-drop bridge ─────────────────────────────────────────────────────
+// Claude Code has no API for injecting a prompt into a running session while a
+// tool call is executing (anthropics/claude-code#27441, still open). The only
+// in-band channel is the `FileChanged` hook: when a watched file changes on
+// disk, Claude Code's hook script stdout is injected as additional context on
+// the next turn — without the agent having to poll.
+//
+// We drop every unsolicited user message into ~/.notify-mcp/inbox/<ts>.md, and
+// ship a one-liner hook in the README that globs that directory. This is the
+// closest thing to a "/btw" we can get until the client exposes a real inject
+// endpoint.
+const INBOX_DROP_DIR = join(CONFIG_DIR, "inbox");
+const INBOX_DROP_TTL_MS = 24 * 60 * 60 * 1000; // 24h — hook should have consumed within seconds
+function writeInboxDrop(entry) {
+    try {
+        if (!existsSync(INBOX_DROP_DIR))
+            mkdirSync(INBOX_DROP_DIR, { recursive: true });
+        const safeTs = entry.ts.replace(/[:.]/g, "-");
+        const tagPart = entry.tag ? `.${entry.tag}` : "";
+        const path = join(INBOX_DROP_DIR, `${safeTs}${tagPart}.md`);
+        const header = `# Unsolicited user message\n\n` +
+            `- Time: ${entry.ts}\n` +
+            (entry.tag ? `- Tag: @${entry.tag}\n` : "") +
+            `- Origin: user (out-of-band)\n\n`;
+        writeFileSync(path, header + entry.text + "\n");
+    }
+    catch (err) {
+        log("·", "inbox-drop", `write failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+// Reap old drops so the directory doesn't grow forever. Hooks consume within
+// seconds, so anything older than a day is a message the agent never saw —
+// keep it for forensics but eventually clean up.
+setInterval(() => {
+    try {
+        if (!existsSync(INBOX_DROP_DIR))
+            return;
+        const now = Date.now();
+        const files = readdirSync(INBOX_DROP_DIR);
+        for (const f of files) {
+            const p = join(INBOX_DROP_DIR, f);
+            try {
+                const st = statSync(p);
+                if (now - st.mtimeMs > INBOX_DROP_TTL_MS)
+                    unlinkSync(p);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    catch { /* ignore */ }
+}, 60 * 60 * 1000);
 const inboxStreamClients = new Set();
 function broadcastInbox(entry) {
     const payload = JSON.stringify(entry);
+    let delivered = 0;
     for (const c of inboxStreamClients) {
+        // Proactively drop subscribers whose socket is gone. Node's req.on("close")
+        // isn't reliable on every disconnect path (e.g. VS Code window killed hard,
+        // laptop lid shut), so check writability before every write.
+        if (c.res.destroyed || c.res.writableEnded || !c.res.writable) {
+            inboxStreamClients.delete(c);
+            continue;
+        }
         if (!matchesSession(entry, c.tag))
             continue;
         try {
             c.res.write(`data: ${payload}\n\n`);
+            delivered++;
         }
         catch {
-            // drop on failure; the close handler will remove the client
+            inboxStreamClients.delete(c);
         }
     }
+    return delivered;
+}
+// Test-only: inject a fake inbox entry exactly as the Telegram listener would.
+// Gated behind NOTIFY_MCP_TEST_ENDPOINTS=1 so it's never exposed in a normal
+// production run. Used by the test suite to drive wait_for_inbox wake-up and
+// SSE broadcast paths without needing a real Telegram bot.
+if (process.env.NOTIFY_MCP_TEST_ENDPOINTS === "1") {
+    app.post("/__test__/inject-inbox", express.json(), (req, res) => {
+        const text = String(req.body?.text ?? "");
+        const tag = req.body?.tag ? String(req.body.tag).toLowerCase() : undefined;
+        if (!text) {
+            res.status(400).json({ error: "text required" });
+            return;
+        }
+        const entry = { text, ts: new Date().toISOString(), tag };
+        const waiters = takeWaitersFor(tag);
+        if (waiters.length > 0) {
+            for (const w of waiters) {
+                clearTimeout(w.timer);
+                w.resolve([entry]);
+            }
+        }
+        else {
+            inboxQueue.push(entry);
+        }
+        const sse = broadcastInbox(entry);
+        writeInboxDrop(entry);
+        log("·", "test-inject", `${text} (waiters=${waiters.length}, sse=${sse})`, tag);
+        res.json({ injected: true, waiters: waiters.length, sse });
+    });
+    log("·", "test", "NOTIFY_MCP_TEST_ENDPOINTS=1 — /__test__/inject-inbox enabled");
 }
 app.get("/api/inbox/stream", (req, res) => {
     res.setHeader("Content-Type", "text/event-stream");
@@ -885,9 +992,30 @@ async function startTelegramListener() {
                         const entry = {
                             text, ts: new Date().toISOString(), messageId: msg.message_id, tag,
                         };
-                        inboxQueue.push(entry);
-                        broadcastInbox(entry);
-                        log("·", "inbox", text, tag);
+                        // Waiters (wait_for_inbox long-poll) get first crack — they were
+                        // already parked by an agent explicitly asking "wake me up when
+                        // something arrives." Hand the entry off as a tool *result*, which
+                        // every MCP client actually surfaces. Only queue if no one was
+                        // waiting, so the message isn't delivered twice.
+                        const waiters = takeWaitersFor(tag);
+                        if (waiters.length > 0) {
+                            for (const w of waiters) {
+                                clearTimeout(w.timer);
+                                w.resolve([entry]);
+                            }
+                            log("·", "inbox", `${text} → ${waiters.length} long-poll waiter(s)`, tag);
+                        }
+                        else {
+                            inboxQueue.push(entry);
+                        }
+                        writeInboxDrop(entry);
+                        const liveSseCount = broadcastInbox(entry);
+                        log("·", "inbox", `${text} (sse=${liveSseCount}, waiters=${waiters.length})`, tag);
+                        // Before building the ack, prune sessions whose transport stream
+                        // is dead or whose heartbeat has lapsed. Without this the ack
+                        // cheerfully claims "broadcast to 3 sessions" when 2 of them are
+                        // closed VS Code windows — which is exactly what prompted this fix.
+                        pruneDeadSessions();
                         // 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
@@ -1011,8 +1139,9 @@ 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', via 'get_idle_seconds' piggy-back, or
-   via the /api/inbox/stream SSE), reply to them THROUGH 'notify' so the reply
+   the 'notify' response, via 'poll', via 'wait_for_inbox', 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
@@ -1046,6 +1175,16 @@ BEHAVIORAL RULES for every client that connects:
    hours away during long work. Treat 'get_idle_seconds' as the "check for
    user input" primitive, not an idle-gate check.
 
+   If your work is naturally idle (waiting for the user, between loop iters),
+   prefer 'wait_for_inbox' instead — it blocks up to 50s and returns the
+   moment the user types anything, as a tool result. That's the most reliable
+   delivery path across every MCP client (notifications over SSE are silently
+   dropped by Claude Code, Cursor, and others). Loop pattern:
+     while (true) {
+       const r = await wait_for_inbox({ timeout_seconds: 50 });
+       if (r !== "inbox:empty") handle(r);
+     }
+
 7. If your tool call fails with "MCP server not connected" / "transport
    closed" / similar — the SERVER IS ALMOST CERTAINLY FINE. Other clients are
    connected to the same server right now. Only YOUR client's transport
@@ -1194,6 +1333,37 @@ function createMcpServer(clientId, sessionTag) {
                 }],
         };
     });
+    server.tool("wait_for_inbox", "Block until the user sends an unsolicited message, or until the timeout " +
+        "expires. Returns the message(s) as tool results (the reliable MCP delivery " +
+        "path — notifications over SSE are dropped by many clients). Default timeout " +
+        "is 50s to stay under the JS SDK's 60s request timeout; keep the agent-side " +
+        "loop re-calling on empty so a quiet user doesn't leak an abandoned waiter. " +
+        "If messages are already queued for this session, returns them immediately.", {
+        timeout_seconds: z.number().min(5).max(55).default(50)
+            .describe("How long to block before returning empty (5-55s)"),
+    }, async ({ timeout_seconds = 50 }) => {
+        // Fast-path: if there are already messages queued for this session tag,
+        // drain and return them without parking a waiter.
+        const queued = drainInboxFor(sessionTag);
+        if (queued.length > 0) {
+            const body = queued.map(m => `[${m.ts}] ${m.text}`).join("\n");
+            return { content: [{ type: "text", text: `⚠️ USER SENT YOU A MESSAGE — STOP AND RESPOND BEFORE CONTINUING:\n${body}` }] };
+        }
+        const token = randomUUID();
+        const entries = await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                inboxWaiters.delete(token);
+                resolve([]);
+            }, timeout_seconds * 1000);
+            inboxWaiters.set(token, { resolve, timer, tag: sessionTag });
+        });
+        if (entries.length === 0) {
+            return { content: [{ type: "text", text: "inbox:empty" }] };
+        }
+        log("·", "wait_for_inbox", `${entries.length} message(s) delivered`, clientId);
+        const body = entries.map(m => `[${m.ts}] ${m.text}`).join("\n");
+        return { content: [{ type: "text", text: `⚠️ USER SENT YOU A MESSAGE — STOP AND RESPOND BEFORE CONTINUING:\n${body}` }] };
+    });
     server.tool("get_idle_seconds", "Returns the number of seconds since the user's last keyboard/mouse input. " +
         "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 " +
@@ -1232,7 +1402,12 @@ const 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
+//
+// The MCP instructions force agents to call get_idle_seconds every 15–30s as a
+// keepalive, so any session that hasn't made *any* request in 90s is almost
+// certainly dead. Keep this tight — the whole point is that stale sessions
+// stop showing up in broadcast acks.
+const SESSION_IDLE_TIMEOUT_MS = 90 * 1000;
 setInterval(() => {
     const now = Date.now();
     for (const [sessionId, meta] of Object.entries(sessions)) {
@@ -1246,7 +1421,16 @@ setInterval(() => {
             delete sessions[sessionId];
         }
     }
-}, 60_000);
+    // Prune SSE inbox subscribers whose underlying socket has died. Node
+    // surfaces dead sockets as destroyed/writableEnded — if we don't sweep
+    // these, broadcastInbox quietly writes to ghosts and the ack count lies
+    // to the user ("Broadcast to 3 sessions" when there's really one).
+    for (const c of inboxStreamClients) {
+        if (c.res.destroyed || c.res.writableEnded || !c.res.writable) {
+            inboxStreamClients.delete(c);
+        }
+    }
+}, 15_000);
 function listActiveSessions() {
     return Object.values(sessions);
 }
@@ -1255,6 +1439,38 @@ function sessionsMatchingTag(tag) {
         return listActiveSessions();
     return listActiveSessions().filter(s => s.tag === tag);
 }
+// Synchronous best-effort liveness check before we count sessions in an ack.
+// The transport's SDK doesn't expose a "ping" API, but it does hold a ref to
+// the response stream of the last GET the client opened — if that stream is
+// destroyed/ended, the client is gone. We also use the `lastSeen` shortcut:
+// if a session hasn't made a request in more than (idle+grace) seconds and
+// the MCP instructions require a 15-30s heartbeat, it's dead. Be lenient —
+// false-positives here result in lying to the user; false-negatives just
+// cause a harmless write that the next reap will clean up.
+const LIVE_GRACE_MS = 60_000;
+function pruneDeadSessions() {
+    const now = Date.now();
+    for (const [sessionId, meta] of Object.entries(sessions)) {
+        const stale = now - meta.lastSeen > LIVE_GRACE_MS;
+        const transport = httpTransports[sessionId];
+        // The SDK stashes the active response stream on the transport for server-
+        // sent notifications. If it exists and is dead, prune. Guarded because
+        // the internal field name isn't stable across SDK versions.
+        const streams = [transport?._streams, transport?._responseStreams, transport?._sseResponse]
+            .filter(Boolean)
+            .flatMap(s => (s instanceof Map ? [...s.values()] : Array.isArray(s) ? s : [s]));
+        const deadStream = streams.length > 0 && streams.every(r => r?.destroyed || r?.writableEnded || r?.writable === false);
+        if (stale || deadStream) {
+            log("·", "session", `pruned unresponsive session ${meta.clientId} (stale=${stale}, deadStream=${deadStream})`);
+            try {
+                httpTransports[sessionId]?.close();
+            }
+            catch { /* ignore */ }
+            delete httpTransports[sessionId];
+            delete sessions[sessionId];
+        }
+    }
+}
 function sessionDisplay(s) {
     return s.tag ? `@${s.tag}` : s.clientId;
 }
@@ -1323,10 +1539,83 @@ app.all("/mcp", async (req, res) => {
     }
 });
 // ── Start ─────────────────────────────────────────────────────────────────────
-app.listen(PORT, "0.0.0.0", () => {
+const httpServer = app.listen(PORT, "0.0.0.0", () => {
     const ip = getLocalIp();
     console.log(`\n  Claude Notify config UI  → http://localhost:${PORT}`);
     console.log(`  MCP endpoint (remote)    → http://${ip}:${PORT}/mcp\n`);
     startTelegramListener();
     open(`http://localhost:${PORT}`).catch(() => { });
 });
+// TCP-level keepalive on every incoming socket. Without this, a client that
+// vanishes (laptop lid, killed VS Code, WiFi drop) leaves a half-open TCP
+// connection that Node never notices — the SDK's `onclose` therefore never
+// fires and the session goes zombie. With SO_KEEPALIVE the OS probes every
+// 15s and kills the socket within a couple minutes of silence, which fires
+// our reaper and clears the session bookkeeping.
+httpServer.on("connection", (socket) => {
+    socket.setKeepAlive(true, 15_000);
+});
+// keepAliveTimeout gates how long Node holds an HTTP/1.1 keep-alive idle
+// connection open before closing it. Default is 5s, which was fine for
+// short-lived requests but kills long-poll waiters and MCP GET streams
+// prematurely. Bump above the 55s long-poll ceiling so the socket stays
+// alive across the whole wait. headersTimeout must exceed it.
+httpServer.keepAliveTimeout = 75_000;
+httpServer.headersTimeout = 80_000;
+// App-level keepalive on every active MCP GET SSE stream. The SDK doesn't
+// emit any bytes on an idle stream, so intermediate proxies and some clients
+// time out the stream after ~60s of silence. We write an SSE *comment* line
+// (`: keepalive\n\n`) directly to each live response — comments are ignored
+// by SSE parsers but reset proxy idle timers and surface dead sockets as
+// write errors that we can catch and reap. Pattern is the community-standard
+// fix for typescript-sdk#270.
+setInterval(() => {
+    for (const [sid, transport] of Object.entries(httpTransports)) {
+        const t = transport;
+        // Internal field names vary across SDK versions. Collect every candidate
+        // response stream reference; the ones we find are either Response-like
+        // objects with .write or Maps/arrays of them. Write-failure is the signal
+        // that tells us the socket is dead.
+        const candidates = [];
+        for (const key of ["_streamMapping", "_streams", "_responseStreams", "_sseResponse", "_responses"]) {
+            const v = t[key];
+            if (!v)
+                continue;
+            if (v instanceof Map)
+                candidates.push(...v.values());
+            else if (Array.isArray(v))
+                candidates.push(...v);
+            else
+                candidates.push(v);
+        }
+        let wrote = false;
+        let allDead = candidates.length > 0;
+        for (const r of candidates) {
+            if (!r || r.destroyed || r.writableEnded || r.writable === false)
+                continue;
+            try {
+                r.write(`: keepalive ${Date.now()}\n\n`);
+                wrote = true;
+                allDead = false;
+            }
+            catch {
+                // write failed — socket is dead, move on
+            }
+        }
+        if (candidates.length > 0 && allDead) {
+            try {
+                httpTransports[sid]?.close();
+            }
+            catch { /* ignore */ }
+            delete httpTransports[sid];
+            delete sessions[sid];
+        }
+        // Touch lastSeen on a successful keepalive write so the reaper doesn't
+        // kill a session that's quietly connected but idle. lastSeen normally
+        // tracks inbound requests; extending it to "stream is verified writable"
+        // is fine — if the write succeeds, the client really is still there.
+        if (wrote && sessions[sid]) {
+            sessions[sid].lastSeen = Date.now();
+        }
+    }
+}, 20_000);

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "omni-notify-mcp",
-  "version": "1.1.8",
+  "version": "1.2.0",
   "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",
   "bin": {
-    "omni-notify-mcp": "dist/index.js"
+    "omni-notify-mcp": "dist/index.js",
+    "omni-notify-ui": "dist/ui/server.js"
   },
   "files": [
     "dist/",
@@ -47,6 +48,7 @@
     "build:ui": "tsc -p ui/tsconfig.json",
     "start": "node dist/index.js",
     "ui": "npm run build:ui && node dist/ui/server.js",
+    "test": "npm run build && node --test tests/*.test.mjs",
     "prepublishOnly": "npm run build:mcp"
   },
   "dependencies": {