3 files changed, 172 insertions, 0 deletions

diff --git a/packages/api/src/app.ts b/packages/api/src/app.ts
index 19cc193..0dabb0d 100644
--- a/packages/api/src/app.ts
+++ b/packages/api/src/app.ts
@@ -1,3 +1,4 @@
+import { getTab, NotificationDispatcher } from "@dispatch/core";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { AgentManager } from "./agent-manager.js";
@@ -5,12 +6,39 @@ import { PermissionManager } from "./permission-manager.js";
 import { agentsRoutes } from "./routes/agents.js";
 import { configRoutes } from "./routes/config.js";
 import { modelsRoutes, startWakeScheduler } from "./routes/models.js";
+import { notificationsRoutes } from "./routes/notifications.js";
 import { skillsRoutes } from "./routes/skills.js";
 import { tabsRoutes } from "./routes/tabs.js";
 
 export const permissionManager = new PermissionManager();
 export const agentManager = new AgentManager(permissionManager);
 
+// ntfy.sh push notifications. The dispatcher reads its config from the
+// `settings` table on every send, so config changes apply immediately —
+// no restart, no re-attach needed.
+export const notificationDispatcher = new NotificationDispatcher({
+	getTabTitle: (tabId) => {
+		try {
+			return getTab(tabId)?.title ?? null;
+		} catch {
+			return null;
+		}
+	},
+	getTabParentId: (tabId) => {
+		try {
+			// `undefined` when the lookup fails (tab not found / DB unavailable)
+			// so the dispatcher falls back to "treat as top-level" rather than
+			// silently dropping notifications.
+			const row = getTab(tabId);
+			return row ? row.parentTabId : undefined;
+		} catch {
+			return undefined;
+		}
+	},
+});
+notificationDispatcher.attachToAgentManager(agentManager);
+notificationDispatcher.attachToPermissionManager(permissionManager);
+
 export const app = new Hono();
 
 app.use(
@@ -112,6 +140,7 @@ app.route("/skills", skillsRoutes);
 app.route("/models", modelsRoutes);
 app.route("/tabs", tabsRoutes);
 app.route("/agents", agentsRoutes);
+app.route("/notifications", notificationsRoutes);
 
 // Start the wake scheduler on boot (restores persisted schedule)
 startWakeScheduler();
diff --git a/packages/api/src/permission-manager.ts b/packages/api/src/permission-manager.ts
index d98dc52..3a24d03 100644
--- a/packages/api/src/permission-manager.ts
+++ b/packages/api/src/permission-manager.ts
@@ -5,9 +5,25 @@ import {
 	type Ruleset,
 } from "@dispatch/core";
 
+/**
+ * Listener fired exactly once per newly-created pending prompt. Used by
+ * the notification dispatcher so that a permission request triggers a
+ * push notification on the user's phone (without re-firing every time
+ * the pending list mutates for an unrelated reason).
+ */
+export type PromptAddedListener = (prompt: {
+	id: string;
+	permission: string;
+	description: string;
+	metadata: Record<string, unknown>;
+}) => void;
+
 export class PermissionManager {
 	private service = new PermissionService();
 	private wsClients: Map<string, (data: unknown) => void> = new Map();
+	private promptAddedListeners: Set<PromptAddedListener> = new Set();
+	/** Ids that have already been broadcast as "added" — guards against re-emits. */
+	private announcedPromptIds: Set<string> = new Set();
 
 	registerClient(id: string, send: (data: unknown) => void): void {
 		this.wsClients.set(id, send);
@@ -25,6 +41,33 @@ export class PermissionManager {
 		for (const send of this.wsClients.values()) {
 			send(message);
 		}
+
+		// Detect newly-added prompts (ids present now that weren't before) and
+		// fire `promptAddedListeners` once for each. Resolved/rejected ids are
+		// pruned from `announcedPromptIds` so a future prompt that reuses an
+		// id (theoretical, given the monotonic counter) would still notify.
+		const currentIds = new Set(pending.map((p) => p.id));
+		for (const id of this.announcedPromptIds) {
+			if (!currentIds.has(id)) this.announcedPromptIds.delete(id);
+		}
+		for (const p of pending) {
+			if (this.announcedPromptIds.has(p.id)) continue;
+			this.announcedPromptIds.add(p.id);
+			for (const listener of this.promptAddedListeners) {
+				try {
+					listener({
+						id: p.id,
+						permission: p.request.permission,
+						description: p.request.description,
+						metadata: p.request.metadata,
+					});
+				} catch (err) {
+					console.warn(
+						`[permission] promptAdded listener threw: ${err instanceof Error ? err.message : String(err)}`,
+					);
+				}
+			}
+		}
 	}
 
 	async ask(request: PermissionRequest, rulesets: Ruleset[] = []): Promise<PermissionReply> {
@@ -45,4 +88,16 @@ export class PermissionManager {
 	getService(): PermissionService {
 		return this.service;
 	}
+
+	/**
+	 * Subscribe to "a new prompt is now pending" events. Fires once per
+	 * unique prompt id, even if `broadcastPending` is called repeatedly
+	 * for unrelated mutations. Returns an unsubscribe function.
+	 */
+	onPromptAdded(listener: PromptAddedListener): () => void {
+		this.promptAddedListeners.add(listener);
+		return () => {
+			this.promptAddedListeners.delete(listener);
+		};
+	}
 }
diff --git a/packages/api/src/routes/notifications.ts b/packages/api/src/routes/notifications.ts
new file mode 100644
index 0000000..473e837
--- /dev/null
+++ b/packages/api/src/routes/notifications.ts
@@ -0,0 +1,88 @@
+// `/notifications` — ntfy.sh config + test-send route.
+
+import {
+	defaultNtfyConfig,
+	loadNtfyConfig,
+	type NotificationEventType,
+	NTFY_EVENT_TYPES,
+	type NtfyConfig,
+	normalizeNtfyConfig,
+	redactNtfyConfig,
+	saveNtfyConfig,
+	sendNtfy,
+} from "@dispatch/core";
+import { Hono } from "hono";
+
+export const notificationsRoutes = new Hono();
+
+notificationsRoutes.get("/", (c) => {
+	const config = loadNtfyConfig();
+	return c.json({
+		config: redactNtfyConfig(config),
+		eventTypes: NTFY_EVENT_TYPES,
+		defaults: defaultNtfyConfig(),
+	});
+});
+
+notificationsRoutes.put("/", async (c) => {
+	const body = await c.req.json<Partial<NtfyConfig> & { authToken?: string }>();
+	const existing = loadNtfyConfig();
+
+	// `authToken === ""` ⇒ explicit clear; `authToken === undefined` ⇒ keep
+	// the existing token (the GET response redacts it, so the frontend doesn't
+	// have it to send back). Any other string ⇒ replace.
+	let nextAuthToken = existing.authToken;
+	if (typeof body.authToken === "string") nextAuthToken = body.authToken;
+
+	const merged = normalizeNtfyConfig({
+		enabled: typeof body.enabled === "boolean" ? body.enabled : existing.enabled,
+		topic: typeof body.topic === "string" ? body.topic : existing.topic,
+		authToken: nextAuthToken,
+		events: { ...existing.events, ...(body.events ?? {}) },
+		notifySubagents:
+			typeof body.notifySubagents === "boolean" ? body.notifySubagents : existing.notifySubagents,
+	});
+
+	// Only validation: if notifications are turned on, the topic must be
+	// non-empty. Any other "is this a valid ntfy topic name?" check is
+	// punted to the ntfy server itself — its rules vary and have changed
+	// over time, and a syntactically-valid name still might be rejected
+	// (e.g. reserved words), so a clear server error is more useful than
+	// a client-side guess.
+	if (merged.enabled && !merged.topic.trim()) {
+		return c.json({ error: "Topic is required" }, 400);
+	}
+
+	saveNtfyConfig(merged);
+	return c.json({ config: redactNtfyConfig(merged) });
+});
+
+notificationsRoutes.post("/test", async (c) => {
+	const config = loadNtfyConfig();
+	if (!config.enabled) {
+		return c.json({ ok: false, error: "Notifications are disabled" }, 400);
+	}
+	if (!config.topic.trim()) {
+		return c.json({ ok: false, error: "Topic is required" }, 400);
+	}
+
+	// Use a real event type so the per-event toggle is honored when wiring
+	// is tested end-to-end; pick `turn-completed` since it's the most
+	// common enabled-by-default event.
+	const eventType: NotificationEventType = "turn-completed";
+	if (!config.events[eventType]) {
+		return c.json(
+			{ ok: false, error: `Event type "${eventType}" is disabled — enable it to test.` },
+			400,
+		);
+	}
+
+	const result = await sendNtfy(config, {
+		type: eventType,
+		title: "Dispatch test notification",
+		message: "If you can see this, ntfy.sh notifications are wired up correctly.",
+		tags: ["bell"],
+	});
+	if (!result.ok) return c.json(result, 502);
+	return c.json(result);
+});