omni-notify-mcp 1.3.13 → 1.3.20

package/README.md

@@ -1,264 +1,304 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/menih/notify-mcp/main/assets/logo.svg" width="128" height="128" alt="omni-notify-mcp">
+  <img src="https://raw.githubusercontent.com/menih/BullseyeNotif/main/assets/logo.svg" width="128" height="128" alt="BullseyeNotify">
 </p>
 
-<h1 align="center">omni-notify-mcp</h1>
+<h1 align="center">BullseyeNotify · <code>omni-notify-mcp</code></h1>
 
 <p align="center">
-  <em>Reach me on any channel. Ask me anything. Get out of my way when I'm busy.</em><br>
-  HTTP-first notification/control server with optional MCP compatibility for AI agents
-  (Claude, Copilot, Cursor, etc.): desktop, Telegram, Slack, SMS, email,
-  two-way replies, idle gating, and Do Not Disturb.
+  A local notification bus for AI agents. One HTTP server owns the channels, the
+  routing policy and the inbound message queue; a thin stdio MCP bridge exposes it
+  to Claude Code, Cursor, Copilot and any other MCP host; a VS Code extension frames
+  the config UI in the editor.
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/omni-notify-mcp"><img src="https://img.shields.io/npm/v/omni-notify-mcp.svg" alt="npm"></a>
-  <a href="https://marketplace.visualstudio.com/items?itemName=Karish911.omni-notify-mcp"><img src="https://img.shields.io/visual-studio-marketplace/v/Karish911.omni-notify-mcp?label=marketplace" alt="VS Code Marketplace"></a>
+  <a href="https://marketplace.visualstudio.com/items?itemName=menihillel.bullseye-notify"><img src="https://img.shields.io/visual-studio-marketplace/v/menihillel.bullseye-notify?label=marketplace" alt="VS Code Marketplace"></a>
   <img src="https://img.shields.io/badge/license-MIT-4ea3ff.svg" alt="MIT license">
-  <img src="https://img.shields.io/badge/MCP-compatible-4ea3ff.svg" alt="MCP compatible">
+  <img src="https://img.shields.io/badge/node-%3E%3D18-4ea3ff.svg" alt="Node 18+">
 </p>
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/menih/notify-mcp/main/assets/screenshots/main-ui.png" width="900" alt="omni-notify-mcp config UI — channels and policies side by side, with live activity log">
+  <img src="https://raw.githubusercontent.com/menih/BullseyeNotif/main/assets/screenshots/main-ui.png" width="900" alt="Config UI — delivery channels and system policies side by side, with the activity log below">
 </p>
 
 ---
 
-## Why
+## The two processes
 
-You step away from your machine and the AI is still working. **It needs to**:
+| Process | Entry | What it owns |
+|---|---|---|
+| **UI/HTTP server** | `dist/ui/server.js` (bin `omni-notify-ui`) | Every channel implementation, the routing policy (DND / idle / mute), the inbound inbox, the Telegram long-poll listener, the Slack channel poller, the built-in ntfy server, the web config UI, and — when `ENABLE_MCP=1` — the Streamable-HTTP `/mcp` endpoint. Listens on `0.0.0.0:3737` by default. |
+| **stdio MCP bridge** | `dist/index.js` (bin `omni-notify-mcp`) | A stateless proxy. Auto-spawns the server if `:3737` isn't answering, opens one persistent `/mcp` session, forwards every tool call to it, subscribes to `/api/inbox/stream` and re-emits each message as a `notifications/claude/channel` event. Holds no config and no queue. |
 
-- tell you something important happened (`notify`)
-- ask you a question and wait for your answer (`ask`)
-- check whether you've sent it an unsolicited message (`poll`, or live SSE)
-- **not buzz your phone every 90 seconds** while you're sitting at the keyboard
+The VS Code extension (`vscode-extension/`) is a third, optional face: it starts the
+server if needed and renders `http://localhost:3737/` inside a webview.
 
-`omni-notify-mcp` is the one MCP server that does all of that, on whatever channels you've configured, with the right level of "shut up" built in.
+> **Build note.** `package.json` is deliberately untracked in this repo (see
+> `.gitignore`), so the dependency list, the `bin` map, the version and the extension
+> manifest are not in git. The published package declares `build` as
+> `tsc && tsc -p ui/tsconfig.json` and `test` as `npm run build && node --test tests/*.test.mjs`.
 
 ## Quick start
 
 ```bash
-npx omni-notify-ui
+npm install
+npm run build
+ENABLE_MCP=1 node dist/ui/server.js     # or: ./notify-ui.sh (no MCP)
 ```
 
-This starts the HTTP/UI server on `http://localhost:3737`.
+Open <http://localhost:3737>, enable the channels you want, hit the per-channel
+**Test** button. Config is written to `~/.notify-mcp/config.json` and re-read on
+every notification — no restart after a settings change.
 
-MCP is optional. To enable the `/mcp` endpoint, start with:
+Register the bridge with an MCP host:
 
-```bash
-ENABLE_MCP=1 npx omni-notify-ui
-```
-
-Or use the stdio bridge (which auto-spawns the UI with MCP enabled):
-
-```bash
-npx omni-notify-mcp
-```
-
-Add to your MCP config (`~/.claude.json`, `.vscode/mcp.json`, `claude_desktop_config.json`, etc.):
-
-```json
-{
-  "mcpServers": {
-    "notify": {
-      "command": "npx",
-      "args": ["omni-notify-mcp"]
-    }
-  }
-}
-```
-
-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
-
-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. |
-| **`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`:
-
-| Priority | Channels |
-|---|---|
-| `low`    | email only |
-| `normal` | desktop + Telegram + email |
-| `high`   | desktop + Telegram + SMS + email — **bypasses DND and idle gating** |
-
-## Features
-
-### Channels
-- **Desktop** — native `node-notifier` (macOS/Windows/Linux). Per-channel **system-sound toggle** and optional **text-to-speech** with a voice picker covering 30+ neural voices (US/UK/AU/CA/IN/IE/NZ/…) via `msedge-tts`, no API key.
-- **Telegram** — bidirectional. The bot **replies in-thread** to user messages and acknowledges every inbound message so the user knows it landed.
-- **SMS** — Twilio.
-- **Email** — Gmail App Password (one click) or any SMTP. `ask` over email sends a reply link the user clicks to answer.
-
-### Two-way (`ask`)
-The agent calls `ask`, the question goes out on Telegram and email, and the call **blocks until the user replies** (or times out). Reply on Telegram → agent gets the text. Click the email reply link → agent gets the text. No glue code, no polling loop.
-
-### Real-time inbox push (SSE)
-Subscribe to `GET /api/inbox/stream` (text/event-stream) to receive unsolicited user messages **the moment they arrive** — no polling. Ideal for an always-on agent that wants to react instantly. Per-session tag filtering supported (`?tag=alphawave`). Falls back gracefully to `poll` for clients without SSE.
-
-### Multi-session tagging
-Run multiple agents against the same notify server (e.g. one Claude session in `repo-a`, another in `repo-b`). Each connects with `?tag=<name>` and the user can route a Telegram message to a specific agent by prefixing `@<name>`. Untagged messages broadcast to every session.
-
-The stdio bridge derives its tag as `<hostname>-<workspace-folder>` unless you override it with the **`NOTIFY_MCP_TAG`** env var — set it to give a bridge a durable, human-meaningful name (e.g. `NOTIFY_MCP_TAG=frontend`). This is the only stable per-bridge name: Claude Code exposes no per-session id to MCP subprocesses, so two extension panels on the *same* workspace share a tag by default.
-
-### Multiple panels in one window
-Open N Claude extension panels in one VS Code window and each spawns its own bridge → its own MCP session. They share a tag (same host + workspace), but `/api/clients` lists each as a separate logical client (one per panel), disambiguated by an auto-suffixed id (`foo`, `foo-2`, …) plus `panel <n>/<total>` and a short session id. `list clients` annotates the panel count. To give a panel its own durable identity instead of an ordinal, launch it with a distinct `NOTIFY_MCP_TAG`.
-
-### Do Not Disturb
-- **Manual toggle** — flip it on, all `priority < high` notifs drop on the floor.
-- **Scheduled quiet hours** — e.g. 22:00 → 08:00, configurable per-day.
-- `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.
-
-### 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 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\""
-          }
-        ]
-      }
-    ]
+    "notify": { "type": "stdio", "command": "npx", "args": ["-y", "omni-notify-mcp"] }
   }
 }
 ```
 
-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.
-
-Cross-platform idle detection: Windows (PowerShell + `GetLastInputInfo`), macOS (`ioreg`), Linux (`xprintidle`).
-
-### Web config UI
-One page, dark theme, live activity log streaming over SSE, one-click test buttons per channel, secrets masked at rest. Plus a copy-paste help page that walks any AI client through registration in 30 seconds:
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/menih/notify-mcp/main/assets/screenshots/help-page.png" width="800" alt="Help page — copy-paste snippets for Claude Code, Cursor, VS Code, Claude Desktop, Windsurf, Zed">
-</p>
-
-### Activity log
-Every notify, ask, reply, and inbox event is logged with timestamp, direction (`→` `←` `·`), channel, and (color-coded) client/session id. Visible live in the UI; last 500 entries replayed on connect.
-
-### Behavioral rules baked in
-The MCP server ships with `instructions` that tell every connecting client:
-1. Pre-flight with `get_idle_seconds` and skip if user is active.
-2. Echo the message in chat too — don't trust the user is checking their phone.
-3. Use channel-agnostic wording ("notif", not "Telegram").
-4. Reply to inbox messages **through `notify`**, not just in chat.
-5. `priority='high'` is for blockers, not noise.
-
-This means well-behaved agents get the right behavior automatically — no per-prompt nagging required.
+VS Code / Copilot use `.vscode/mcp.json` with a `servers` key instead of
+`mcpServers`; the bundled help page at `http://localhost:3737/help.html` has the exact
+snippet for Claude Code, Cursor, VS Code, Claude Desktop, Windsurf, Zed and generic
+clients.
+
+## MCP tools
+
+Eight tools over HTTP, nine over stdio. The agent never names a channel — routing is
+entirely server-side.
+
+| Tool | Arguments | Behaviour |
+|---|---|---|
+| `notify` | `message`, `priority` = `low`\|`normal`\|`high` | Fan out per the routing table below. Response states `outcome=` with the `attempted` and `delivered` channels plus any per-channel error, and carries any queued inbox messages for this session. |
+| `ask` | `question`, `timeout_seconds` (30–3600, default 300) | Sends the question to Telegram (every configured chat id) and email (with a one-shot `/reply/:token` web page), then **blocks** until a reply lands or the timeout throws. |
+| `poll` | — | Drains queued inbox messages for this session's tag; returns `inbox:empty` when there are none. |
+| `wait_for_inbox` | `timeout_seconds` (5–55, default 50) | Parks a waiter and returns the moment a matching message arrives, as a tool *result*. Returns already-queued messages immediately without parking. |
+| `get_idle_seconds` | — | Seconds since the last OS keyboard/mouse input, or `-1` where unsupported. Drains the inbox as a side effect. |
+| `get_idle_config` | — | `{ enabled, thresholdSeconds, alwaysDesktopWhenActive }`. Drains the inbox. |
+| `get_dnd_status` | — | `{ active, reason }` where reason is `disabled` (master mute or this client disabled), `manual`, `schedule` or `off`. Drains the inbox. |
+| `update_instructions` | `instructions` (≤4000), `target` = `global`\|`project` | Rewrites a marker-delimited block in `~/.claude/CLAUDE.md` (global) or `./.claude/CLAUDE.md` (project). |
+| `reply` *(stdio bridge only)* | `message` (≤2000), `priority` | The Claude Code Channels return path. Prefixes the bridge's session tag and routes through `notify`. |
+
+**Message size and chunking.** The HTTP server caps `notify.message` at 500
+characters and rejects anything longer. The stdio bridge accepts up to 5000, splits it
+in `src/chunk.ts` into `(1/N) …` chunks of ≤500 (word-aware where a break lands past
+60 % of the budget), and delivers them in order — so chunking exists **only on the
+bridge path**. A bridge caller gets back either `Delivered as N chunks (M chars).` or a
+count of how many chunks reached no channel and what the server said.
+
+## Delivery routing
+
+`sendWithRouting` in `ui/messaging/notificationEngine.ts` is the single chokepoint.
+Three suppressions run before it, in order: master mute (`muteAll`) drops everything
+including `high`; a client listed in `disabledClients` is dropped by client id; then
+DND drops everything below `high`.
+
+The **desktop-only** mode kicks in when the web UI reported itself visible in the last
+30 s, or when idle gating is on, no Telegram conversation has been active in the last
+5 minutes, and OS idle time is under the threshold.
+
+> With `idle.alwaysDesktopWhenActive: false` the desktop is held back too while the user
+> is active, so only Slack is attempted. When Slack is off nothing is sent, and the reply
+> says `outcome=blocked`, as it does under DND, never `outcome=failed`.
+
+| Channel | `low` | `normal` | `high` | Under desktop-only |
+|---|---|---|---|---|
+| desktop | — | ✓ | ✓ | ✓ |
+| telegram | — | ✓ | ✓ | — |
+| email | ✓ | ✓ | ✓ | — |
+| ntfy | ✓ | ✓ | ✓ | — |
+| discord | ✓ | ✓ | ✓ | — |
+| teams | ✓ | ✓ | ✓ | — |
+| slack | ✓ | ✓ | ✓ | **✓ — exempt from idle gating** |
+| sms | — | — | ✓ | — |
+
+`priority: 'high'` bypasses DND and idle gating both. Per-channel failures are
+collected, never thrown: the tool response lists what was delivered and what errored.
+
+## Channels
+
+Every channel is off until enabled, and a channel whose credentials are incomplete is
+skipped by the `enable*` predicates in `ui/server.ts` even when `enabled: true`.
+
+| Channel | Config key and fields | Transport |
+|---|---|---|
+| **Desktop** | `desktop` — `enabled`, `sound`, `tts`, `ttsVoice` | `node-notifier` toast titled *Claude Notify*. On Windows the toast sound is unreliable, so a PowerShell `SystemSounds::Asterisk` is fired alongside it. With `tts: true` the body is synthesised through `msedge-tts` (default voice `en-US-AndrewMultilingualNeural`) and played via MediaPlayer / `afplay` / `aplay`. |
+| **Telegram** | `telegram` — `enabled`, `token`, `chatIds[]` | `sendMessage` per chat id. When the last inbound message came from that same chat, the notification is sent as a threaded reply. Also the inbound listener (see below). |
+| **Email** | `email` — `enabled`, `to`, plus either Gmail OAuth (`clientId`, `clientSecret`, `refreshToken`, `accessToken`, `connectedEmail`) or SMTP (`host`, `port` 587, `secure` false, `user`, `pass`) | `nodemailer`; subject *Claude Notify*. OAuth wins when a refresh token is present. `ask` sends HTML with a **Reply to Claude** button pointing at `http://<lan-ip>:3737/reply/<token>`. |
+| **SMS** | `sms` — `enabled`, `accessKeyId`, `secretAccessKey`, `region`, `originationNumber`, `to[]` | AWS End User Messaging (`@aws-sdk/client-pinpoint-sms-voice-v2`, `SendTextMessage`), one call per destination, numbers normalised to E.164. `high` priority only. |
+| **ntfy** | `ntfy` — `enabled`, `topic`, `serverUrl` (display only), `token` | **This server *is* the ntfy server.** It implements the publish/subscribe wire protocol at `/:topic/sse`, `/:topic/json` and `PUT`/`POST /:topic`, and a notification fans out to whoever is subscribed to that topic *on this server*. Point the ntfy mobile app at this host. Sending with zero subscribers is an error, not a silent drop. |
+| **Discord** | `discord` — `enabled`, `webhookUrl`, `username`, `clientId`, `clientSecret`, `channelName` | Webhook embed, colour-coded by priority. `GET /auth/discord/start` runs a one-click OAuth flow (`webhook.incoming` scope) that returns a ready-made channel webhook. |
+| **Slack** | `slack` — `enabled`, `webhookUrl`, `botToken`, `channels[]`, `clientId`, `clientSecret`, `team` | With a bot token **and** channels, one `chat.postMessage` per channel; otherwise the single incoming webhook. `GET /auth/slack/start` runs OAuth for `channels:read,groups:read,channels:history,groups:history,chat:write,chat:write.public`, so the minted token also serves the Slack bus poller. When `slack.botToken` is blank the token from `notify-secrets.json` / `SLACK_BOT_TOKEN` is reused. |
+| **Teams** | `teams` — `enabled`, `webhookUrl` | Adaptive Card v1.2 posted to a Teams *Workflows* webhook. |
 
 ## Configuration
 
-Default location: `~/.notify-mcp/config.json`. The web UI manages this file for you, but the schema is straightforward:
+`~/.notify-mcp/config.json`, overridable with `NOTIFY_MCP_CONFIG_DIR`. The UI writes
+it; secrets are replaced with `••••••••` on read and a masked value posted back is
+restored from the on-disk copy rather than overwriting it. Legacy single-destination
+fields are migrated on load: `telegram.chatId` → `chatIds[]`, `sms.to` string →
+array, and the dead Twilio fields (`accountSid`, `authToken`, `from`) are deleted.
 
 ```json
 {
-  "desktop": { "enabled": true, "sound": true },
-  "telegram": { "enabled": true, "token": "BOT_TOKEN", "chatId": "CHAT_ID" },
+  "muteAll": false,
+  "disabledClients": [],
+  "clientAliases": {},
+  "desktop": { "enabled": true, "sound": true, "tts": false },
+  "telegram": { "enabled": true, "token": "BOT_TOKEN", "chatIds": ["123456789"] },
   "sms": {
     "enabled": false,
-    "accountSid": "ACxxxx",
-    "authToken": "...",
-    "from": "+15550000000",
-    "to": "+15550000001"
+    "accessKeyId": "AKIA…", "secretAccessKey": "…",
+    "region": "us-east-1", "originationNumber": "+15550000000",
+    "to": ["+15550000001"]
   },
   "email": {
-    "enabled": true,
+    "enabled": true, "to": "you@gmail.com",
     "host": "smtp.gmail.com", "port": 587, "secure": false,
-    "user": "you@gmail.com", "pass": "GMAIL_APP_PASSWORD",
-    "to": "you@gmail.com"
+    "user": "you@gmail.com", "pass": "GMAIL_APP_PASSWORD"
   },
+  "ntfy":    { "enabled": false, "topic": "", "serverUrl": "" },
+  "discord": { "enabled": false, "webhookUrl": "", "username": "Claude Notify" },
+  "slack":   { "enabled": false, "webhookUrl": "", "botToken": "", "channels": [] },
+  "teams":   { "enabled": false, "webhookUrl": "" },
   "dnd": {
     "enabled": false,
-    "schedule": {
-      "enabled": false,
-      "quietStart": "22:00", "quietEnd": "08:00",
-      "days": [0, 1, 2, 3, 4, 5, 6]
-    }
+    "schedule": { "enabled": false, "quietStart": "22:00", "quietEnd": "08:00", "days": [0,1,2,3,4,5,6] }
   },
-  "idle": { "enabled": true, "thresholdSeconds": 120 }
+  "idle": { "enabled": true, "thresholdSeconds": 120, "alwaysDesktopWhenActive": true }
 }
 ```
 
-Disabled channels are silently skipped. Secrets are masked when read back via the API.
-
-### Channel setup
-
-- **Desktop** — works out of the box. Toggle `sound` to mute the system chime.
-- **Telegram** — create a bot via [@BotFather](https://t.me/botfather), then click **Detect** in the UI to auto-fill the chat ID.
-- **SMS** — Twilio account SID + auth token + a Twilio number.
-- **Email** — Gmail [App Password](https://myaccount.google.com/apppasswords) (the UI walks you through it) or any SMTP host/user/pass.
-
-## Endpoints (for power users)
-
-The UI server (default `:3737`) also exposes:
+`notify-secrets.json` at the repo root is a second, optional source: values under keys
+ending in `_b64` are base64-decoded at load, and on startup any credential it holds is
+copied into **empty** fields of `config.json` (never over a value you already set).
+See `config.example.json` for a hand-written starting point.
+
+## Inbound — the inbox
+
+Messages arriving *from* the user (Telegram reply, Slack channel post,
+`POST /api/agent/inbox/inject`, Slack Events API) land in one queue and are delivered
+through whichever path is available:
+
+1. **Parked long-poll waiters** get first refusal — `wait_for_inbox` or
+   `GET /api/agent/inbox/wait`, delivered as a tool/HTTP result. Message is handed to
+   the waiters and not queued.
+2. **SSE broadcast** to every `/api/inbox/stream` subscriber whose tag matches. The
+   stdio bridge is such a subscriber and re-emits each message as a
+   `notifications/claude/channel` event, which Claude Code (CLI, launched with
+   `--channels`) surfaces as a synthetic turn.
+3. **File drop** at `~/.notify-mcp/inbox/<iso-ts>[.<tag>].md`, reaped after 24 h. The
+   Slack-origin drop embeds the exact `curl` needed to answer in-channel.
+   `.claude/notify-inbox-drain.sh` is the consumer shipped here: it is wired into
+   `SessionStart`, `UserPromptSubmit` and `Stop`, matches this session's tag, deletes
+   each file as it reads it, and returns the text as `additionalContext` (or as a
+   `decision: "block"` reason on `Stop`, which is what lets a message reach an agent
+   mid-loop). It deliberately no-ops on `PreToolUse`/`PostToolUse`, where Claude Code
+   discards hook output — draining there would delete a message without delivering it.
+
+**Tags.** A session declares one via `/mcp?tag=<name>` or `/api/inbox/stream?tag=<name>`.
+A user message prefixed `@<tag> ` is routed to that tag only; everything else
+broadcasts. The bridge derives its own tag as
+`<hostname>-<project>` where `<project>` is `NOTIFY_MCP_TAG`, else the nearest
+meaningful folder walking up from `CLAUDE_PROJECT_DIR` (generic names like `claude`,
+`code`, `src`, `dist`, `system32` are skipped). When neither variable is set — the VS
+Code extension case — a 6-character hash of `CLAUDE_CODE_SESSION_ID` is appended so two
+windows sharing a working directory stay distinct. Subagents inherit their parent's
+session id, so `/api/clients` folds them into the parent's panel.
+
+Telegram acknowledges every inbound message in-thread, naming what it did:
+routed to `@tag`, broadcast to *n* listeners, or queued because nobody is connected.
+
+## Slack bus
+
+A single shared Slack channel works as a cross-machine bus: the server polls
+`conversations.history` every 2 s, ingests genuine human messages only, answers
+`clients` / `help` in-channel itself, and routes `@<name> …` / `#<n> …` to the matching
+connected client. Full architecture, addressing rules and operating notes:
+[`docs/SLACK-BUS.md`](docs/SLACK-BUS.md).
+
+## Web UI
+
+One page at `:3737`, dark, no build step. A master-mute bar on top; a **Delivery
+channels** column (desktop, email, telegram, sms, ntfy, discord, slack, teams — each a
+collapsible card with a status badge, an enable toggle, a **Test** button and inline
+setup instructions); a **System policies** column (Do Not Disturb manual + scheduled
+quiet hours with per-day checkboxes; idle gating threshold and the
+always-play-desktop-sound toggle). Below them a collapsible panel with two tabs: the
+live activity log (SSE, last 500 lines replayed on connect, direction-marked `→ ← ·`)
+and **Clients**, which lists every connected session with its panel number and lets you
+rename, disable or force-reconnect one. `help.html` is the copy-paste setup page.
+
+## HTTP endpoints
 
 | Path | Purpose |
 |---|---|
-| `POST /mcp[?tag=<name>]` | StreamableHTTP MCP transport. Optional session tag. |
-| `GET  /api/inbox/stream[?tag=<name>]` | SSE push of unsolicited user messages. |
-| `GET  /api/logs` | SSE stream of the activity log. |
-| `GET/POST /api/config` | Read/write the config (secrets masked on read). |
-| `POST /api/test/<channel>` | One-shot test send for desktop/telegram/sms/email. |
-| `GET  /reply/:token` | Web reply page for `ask` over email. |
+| `ALL /mcp[?tag=&hsid=]` | Streamable-HTTP MCP transport. `404 mcp_disabled` unless `ENABLE_MCP=1`. An unknown session id on a fresh `initialize` is adopted (survives a server restart); on any other request it returns 404 so the client reinitialises. |
+| `GET /api/inbox/stream[?tag=]` | SSE push of inbound user messages, 20 s keepalive comments. |
+| `GET /api/logs` | SSE activity log. |
+| `GET/POST /api/config` | Read (masked) / merge-write the config. |
+| `GET/POST /api/mute` | Master kill switch. |
+| `POST /api/window/register` | Extension → server: `{sessionId, workspaceName, workspacePath}`, so a window's real workspace name can be shown for its bridge session. |
+| `GET/POST /api/window/:sessionId/mute` | Mute every client belonging to one editor window. |
+| `GET /api/sessions`, `DELETE /api/sessions/:clientId` | Raw MCP session list / drop one. |
+| `GET /api/clients` | Connected clients with panel numbering, kinds (`mcp`/`sse`/`waiter`), workspace name and disabled flag. |
+| `POST /api/clients/:tag/rename`, `/api/clients/:id/disable` | Persisted display alias / per-client kill switch. |
+| `POST /api/clients/:tag/reconnect`, `/api/clients/:tag/panel/:sessionId/reconnect` | Drop every connection for a tag, or just one panel. |
+| `POST /api/test/{sound,tts,desktop,telegram,sms,email,ntfy,discord,slack,teams}` | One-shot test send per channel. |
+| `GET /api/voices` | English neural voices from msedge-tts, cached 24 h. |
+| `GET /api/telegram/chats`, `/api/slack/channels`, `/api/sms/numbers` | Pickers backing the UI. |
+| `GET /api/slack/status`, `/api/discord/status`, `/api/gcloud/status` | Connection state for the UI badges. |
+| `GET /auth/{google,slack,discord}/start`, `/callback`; `DELETE /auth/{google,slack,discord}` | OAuth connect / disconnect. |
+| `GET /api/google/open-apppasswords`, `POST /api/google/apppassword`, `GET /api/gcloud/login` | Gmail App Password helper flow and the gcloud sign-in it can fall back on. |
+| `POST /api/agent/notify`, `GET /api/agent/inbox/poll`, `GET /api/agent/inbox/wait`, `POST /api/agent/inbox/inject`, `POST /api/agent/slack/reply` | Plain-HTTP agent API — same behaviour as the MCP tools, no transport required. Gated by `x-notify-key` when `NOTIFY_AGENT_KEY` is set. |
+| `POST /api/session/state` | A session reports itself busy/idle so the bus can answer "Claude is busy, ~Ns". |
+| `POST /api/slack/events` | Slack Events API receiver; HMAC-verified when `SLACK_SIGNING_SECRET` is set. |
+| `POST /api/ui/visibility` | The web UI heartbeats its own visibility; while visible, non-`high` notifications stay desktop-only. |
+| `GET /reply/:token`, `POST /reply/:token` | One-shot web reply page for `ask` over email. |
+| `GET /v1/health`, `/v1/info` | Liveness (used by the VS Code extension) and version stub. |
+| `/:topic/sse`, `/:topic/json`, `PUT`/`POST /:topic`, `/:topic/subscribers` | Built-in ntfy protocol server (also mounted under `/ntfy/…`). |
+
+`POST /__test__/inject-inbox` and `GET /__test__/slack-clients` exist only when
+`NOTIFY_MCP_TEST_ENDPOINTS=1`.
+
+## Environment
+
+| Variable | Read by | Effect |
+|---|---|---|
+| `PORT` / `NOTIFY_MCP_PORT` | server / bridge | Listen port, default 3737. |
+| `ENABLE_MCP` | server | `1` enables `/mcp`. The bridge always sets it when it spawns the server; a manual relaunch that forgets it makes every MCP tool 404. |
+| `NOTIFY_MCP_CONFIG_DIR` | server | Config + inbox-drop root, default `~/.notify-mcp`. |
+| `NOTIFY_MCP_TAG` | bridge, `notify-watch.sh`, drain hook | Explicit session tag. |
+| `NOTIFY_AGENT_KEY` | server | When set, `/api/agent/*` requires header `x-notify-key`. |
+| `SLACK_BOT_TOKEN`, `SLACK_CHANNEL_ID`, `SLACK_POLL_INTERVAL`, `SLACK_SIGNING_SECRET` | server | Slack bus credentials, poll interval (seconds, default 2) and Events-API signature verification. |
+| `NOTIFY_MCP_NO_OPEN`, `BROWSER=none` | server | Suppress the first-run browser pop. |
+| `NOTIFY_MCP_TEST_ENDPOINTS` | server | `1` enables the test-only routes, isolates the inbox drop dir, and skips the live Telegram/Slack listeners. |
+| `CLAUDE_PROJECT_DIR`, `CLAUDE_CODE_SESSION_ID` | bridge, extension | Supplied by the host; drive tag derivation and subagent folding. |
+
+## Scripts
+
+| Script | What it does |
+|---|---|
+| `notify-ui.sh` | Build if `dist/ui/server.js` is missing, then run the server in the foreground (**without** `ENABLE_MCP`). |
+| `restart.sh` | `npm run build:ui`, kill the running `dist/ui/server.js`, relaunch detached to `/tmp/notify-mcp.log`. |
+| `bus-up.sh` | Singleton watchdog: keeps `:3737` listening, redeploys when `dist/ui/server.js` changes on disk, and keeps one `notify-watch.sh` alive. Logs to `.run/`. |
+| `notify-watch.sh` | Detached responder. Long-polls `/api/agent/inbox/wait` for `<host>-<folder>-bot`, and passes every message **verbatim** to a headless `claude -p` that answers via `POST /api/agent/slack/reply`. |
+| `scripts/agent-notify.sh`, `agent-poll-inbox.sh`, `agent-wait-inbox.sh`, `agent-listen-loop.sh` | curl wrappers over the plain-HTTP agent API (`NOTIFY_BASE_URL`, `NOTIFY_AGENT_KEY`, `NOTIFY_TAG`, `NOTIFY_ON_MESSAGE_CMD`). |
+| `scripts/bus-startup-task.sh` | Registers `bus-up.sh` with Windows Task Scheduler. |
+| `scripts/run-tunnel-loop.sh` | Keeps a localtunnel pointed at the port. |
+| `release.sh`, `setup-secrets.sh` | npm + Marketplace publish, and the guided credential setup it calls on first run. |
+
+## Tests
+
+`tests/smoke.test.mjs` — end-to-end only. It spawns a real server on a random free
+port with an isolated config dir, drives it over real HTTP, and runs the stdio bridge
+as a real subprocess; a local capture server stands in for the Slack webhook. Run with
+`npm test` (which builds first) or `node --test tests/smoke.test.mjs` against an
+existing `dist/`.
 
 ## License